Personal AI, On Personal Devices
Python
feat: add Granola meeting notes connector with transcript support
krypticmouse1257303cd4a3
diff --git a/src/openjarvis/connectors/__init__.py b/src/openjarvis/connectors/__init__.pyindex 32e5458d..1bc5dd24 100644--- a/src/openjarvis/connectors/__init__.py+++ b/src/openjarvis/connectors/__init__.py@@ -22,3 +22,8 @@ try:import openjarvis.connectors.notion # noqa: F401except ImportError:pass++try:+ import openjarvis.connectors.granola # noqa: F401+except ImportError:+ passdiff --git a/src/openjarvis/connectors/granola.py b/src/openjarvis/connectors/granola.pynew file mode 100644index 00000000..1cccc707--- /dev/null+++ b/src/openjarvis/connectors/granola.py@@ -0,0 +1,403 @@+"""Granola connector — syncs meeting notes via the Granola public API.++Uses an API key (Bearer token) stored locally. All network calls are+isolated in module-level functions (``_granola_api_*``) to make them+trivially mockable in tests.++Users create an API key in the Granola desktop app under+Settings → API (requires Business or Enterprise plan).+"""++from __future__ import annotations++from datetime import datetime, timezone+from typing import Any, Dict, Iterator, List, Optional++import httpx++from openjarvis.connectors._stubs import BaseConnector, Document, SyncStatus+from openjarvis.connectors.oauth import delete_tokens, load_tokens, save_tokens+from openjarvis.core.config import DEFAULT_CONFIG_DIR+from openjarvis.core.registry import ConnectorRegistry+from openjarvis.tools._stubs import ToolSpec++# ---------------------------------------------------------------------------+# Constants+# ---------------------------------------------------------------------------++_GRANOLA_API_BASE = "https://public-api.granola.ai"+_DEFAULT_CREDENTIALS_PATH = str(+ DEFAULT_CONFIG_DIR / "connectors" / "granola.json"+)++# ---------------------------------------------------------------------------+# Module-level API functions (easy to patch in tests)+# ---------------------------------------------------------------------------+++def _granola_api_list_notes(+ api_key: str,+ *,+ cursor: Optional[str] = None,+ created_after: Optional[str] = None,+) -> Dict[str, Any]:+ """Call the Granola ``GET /v1/notes`` endpoint.++ Parameters+ ----------+ api_key:+ Granola API key (Bearer token).+ cursor:+ Pagination cursor from a previous response.+ created_after:+ ISO 8601 datetime string; only notes created after this time are+ returned.++ Returns+ -------+ dict+ Raw API response containing ``data`` list, ``hasMore`` flag, and+ optional ``cursor``.+ """+ params: Dict[str, Any] = {"page_size": 30}+ if cursor:+ params["cursor"] = cursor+ if created_after:+ params["created_after"] = created_after++ resp = httpx.get(+ f"{_GRANOLA_API_BASE}/v1/notes",+ headers={"Authorization": f"Bearer {api_key}"},+ params=params,+ timeout=30.0,+ )+ resp.raise_for_status()+ return resp.json()+++def _granola_api_get_note(api_key: str, note_id: str) -> Dict[str, Any]:+ """Fetch a single Granola note by ID (includes transcript).++ Parameters+ ----------+ api_key:+ Granola API key (Bearer token).+ note_id:+ Note ID matching pattern ``not_[a-zA-Z0-9]{14}``.++ Returns+ -------+ dict+ Raw API response for the note resource including summary and+ transcript.+ """+ resp = httpx.get(+ f"{_GRANOLA_API_BASE}/v1/notes/{note_id}",+ headers={"Authorization": f"Bearer {api_key}"},+ params={"include": "transcript"},+ timeout=30.0,+ )+ resp.raise_for_status()+ return resp.json()+++# ---------------------------------------------------------------------------+# Content formatting helper+# ---------------------------------------------------------------------------+++def _format_note_content(note: Dict[str, Any]) -> str:+ """Build a markdown string combining the note summary and transcript.++ Parameters+ ----------+ note:+ Full note object as returned by :func:`_granola_api_get_note`.++ Returns+ -------+ str+ Formatted markdown with ``## Summary`` and ``## Transcript`` sections.+ """+ parts: List[str] = []++ # Summary section+ summary_markdown: str = (+ note.get("summary", {}) or {}+ ).get("markdown", "")+ parts.append("## Summary")+ parts.append(summary_markdown)++ # Transcript section+ transcript: List[Dict[str, Any]] = note.get("transcript") or []+ parts.append("")+ parts.append("## Transcript")+ if transcript:+ for turn in transcript:+ speaker: str = turn.get("speaker", "unknown")+ text: str = turn.get("text", "")+ parts.append(f"**{speaker}:** {text}")+ # (empty transcript → section header with no turns is fine)++ return "\n".join(parts)+++# ---------------------------------------------------------------------------+# ISO datetime parser+# ---------------------------------------------------------------------------+++def _parse_iso_datetime(dt_str: str) -> datetime:+ """Parse an ISO 8601 datetime string into a :class:`~datetime.datetime`.++ Falls back to UTC now if the string is missing or unparseable.+ """+ if not dt_str:+ return datetime.now(tz=timezone.utc)+ try:+ return datetime.fromisoformat(dt_str.replace("Z", "+00:00"))+ except (ValueError, AttributeError):+ return datetime.now(tz=timezone.utc)+++# ---------------------------------------------------------------------------+# GranolaConnector+# ---------------------------------------------------------------------------++[email protected]("granola")+class GranolaConnector(BaseConnector):+ """Connector that syncs meeting notes from Granola via the public REST API.++ Authentication uses an API key created in the Granola desktop app+ (Settings → API, requires Business or Enterprise plan). The key is+ stored locally in a JSON credentials file.++ Parameters+ ----------+ api_key:+ Granola API key. If provided, it takes priority over any stored+ credentials file.+ credentials_path:+ Path to the JSON file where the API key is stored. Defaults to+ ``~/.openjarvis/connectors/granola.json``.+ """++ connector_id = "granola"+ display_name = "Granola"+ auth_type = "oauth" # API key, same credential-storage pattern as OAuth++ def __init__(+ self,+ api_key: str = "",+ credentials_path: str = "",+ ) -> None:+ self._api_key: str = api_key+ self._credentials_path: str = credentials_path or _DEFAULT_CREDENTIALS_PATH+ self._items_synced: int = 0+ self._items_total: int = 0+ self._last_sync: Optional[datetime] = None+ self._last_cursor: Optional[str] = None++ # ------------------------------------------------------------------+ # Internal key resolution+ # ------------------------------------------------------------------++ def _resolve_api_key(self) -> str:+ """Return the active API key — direct > credentials file."""+ if self._api_key:+ return self._api_key+ tokens = load_tokens(self._credentials_path)+ if tokens:+ return tokens.get("token", "")+ return ""++ # ------------------------------------------------------------------+ # BaseConnector interface+ # ------------------------------------------------------------------++ def is_connected(self) -> bool:+ """Return ``True`` if a valid API key is available."""+ return bool(self._resolve_api_key())++ def disconnect(self) -> None:+ """Clear the in-memory API key and delete the stored credentials file."""+ self._api_key = ""+ delete_tokens(self._credentials_path)++ def auth_url(self) -> str:+ """Return the URL where users can create a Granola API key.++ Users must open the Granola desktop app and navigate to+ Settings → API to generate their key.+ """+ return (+ "https://www.granola.ai — open the Granola desktop app and go to "+ "Settings → API to create your API key "+ "(Business or Enterprise plan required)."+ )++ def handle_callback(self, code: str) -> None:+ """Persist the API key to the credentials file.++ The *code* parameter holds the raw API key string provided by the user.+ """+ save_tokens(self._credentials_path, {"token": code})++ def sync(+ self,+ *,+ since: Optional[datetime] = None,+ cursor: Optional[str] = None,+ ) -> Iterator[Document]:+ """Yield :class:`Document` objects for Granola meeting notes.++ Paginates through ``GET /v1/notes`` and fetches each note's full+ content (summary + transcript) via ``GET /v1/notes/{id}``.++ Parameters+ ----------+ since:+ If provided, only notes created after this datetime are returned+ (passed as ``created_after`` to the API).+ cursor:+ Pagination cursor from a previous sync to resume paginating.+ """+ api_key = self._resolve_api_key()+ if not api_key:+ return++ # Convert since to ISO string if provided+ created_after: Optional[str] = None+ if since is not None:+ # Ensure UTC-aware for serialisation+ if since.tzinfo is None:+ since = since.replace(tzinfo=timezone.utc)+ created_after = since.isoformat()++ page_cursor: Optional[str] = cursor+ synced = 0++ while True:+ list_resp = _granola_api_list_notes(+ api_key,+ cursor=page_cursor,+ created_after=created_after,+ )+ notes: List[Dict[str, Any]] = list_resp.get("data", [])++ for note_summary in notes:+ note_id: str = note_summary.get("id", "")+ if not note_id:+ continue++ # Fetch full note with transcript+ note = _granola_api_get_note(api_key, note_id)++ title: str = note.get("title", "")+ owner: Dict[str, Any] = note.get("owner") or {}+ author: str = owner.get("email", "")++ attendees: List[Dict[str, Any]] = note.get("attendees") or []+ participants: List[str] = [+ a.get("email", "") for a in attendees if a.get("email")+ ]++ created_at_str: str = note.get("created_at", "")+ timestamp = _parse_iso_datetime(created_at_str)++ content = _format_note_content(note)++ # Build URL from calendar event if available, else None+ cal_event: Optional[Dict[str, Any]] = note.get("calendar_event")+ url: Optional[str] = None+ if cal_event:+ url = note.get("url")++ doc = Document(+ doc_id=f"granola:{note_id}",+ source="granola",+ doc_type="document",+ content=content,+ title=title,+ author=author,+ participants=participants,+ timestamp=timestamp,+ url=url,+ metadata={+ "note_id": note_id,+ "owner_name": owner.get("name", ""),+ "updated_at": note.get("updated_at", ""),+ },+ )+ synced += 1+ yield doc++ has_more: bool = list_resp.get("hasMore", False)+ if not has_more:+ self._last_cursor = None+ break+ page_cursor = list_resp.get("cursor")+ self._last_cursor = page_cursor++ self._items_synced = synced+ self._last_sync = datetime.now(tz=timezone.utc)++ def sync_status(self) -> SyncStatus:+ """Return sync progress from the most recent :meth:`sync` call."""+ return SyncStatus(+ state="idle",+ items_synced=self._items_synced,+ last_sync=self._last_sync,+ cursor=self._last_cursor,+ )++ # ------------------------------------------------------------------+ # MCP tools+ # ------------------------------------------------------------------++ def mcp_tools(self) -> List[ToolSpec]:+ """Expose two MCP tool specs for real-time Granola queries."""+ return [+ ToolSpec(+ name="granola_search_notes",+ description=(+ "Search Granola meeting notes by keyword or topic. "+ "Returns matching note titles, attendees, and summaries."+ ),+ parameters={+ "type": "object",+ "properties": {+ "query": {+ "type": "string",+ "description": "Search query string",+ },+ "max_results": {+ "type": "integer",+ "description": "Maximum number of notes to return",+ "default": 20,+ },+ },+ "required": ["query"],+ },+ category="knowledge",+ ),+ ToolSpec(+ name="granola_get_note",+ description=(+ "Retrieve the full content of a Granola meeting note by its ID, "+ "including the summary and transcript."+ ),+ parameters={+ "type": "object",+ "properties": {+ "note_id": {+ "type": "string",+ "description": "Granola note ID (e.g. not_abc12345678901)",+ },+ },+ "required": ["note_id"],+ },+ category="knowledge",+ ),+ ]diff --git a/tests/connectors/test_granola.py b/tests/connectors/test_granola.pynew file mode 100644index 00000000..c3d53659--- /dev/null+++ b/tests/connectors/test_granola.py@@ -0,0 +1,251 @@+"""Tests for GranolaConnector — Granola meeting notes sync connector.++All Granola API calls are mocked; no network access is required.+"""++from __future__ import annotations++import json+from pathlib import Path+from typing import List+from unittest.mock import patch++import pytest++from openjarvis.connectors._stubs import Document+from openjarvis.core.registry import ConnectorRegistry++# ---------------------------------------------------------------------------+# Fake API payloads+# ---------------------------------------------------------------------------++_LIST_RESPONSE = {+ "data": [+ {+ "id": "not_abc12345678901",+ "title": "Sprint Planning",+ "owner": {"name": "Alice", "email": "[email protected]"},+ "created_at": "2024-03-15T10:00:00Z",+ "updated_at": "2024-03-15T11:00:00Z",+ },+ {+ "id": "not_def12345678901",+ "title": "Design Review",+ "owner": {"name": "Bob", "email": "[email protected]"},+ "created_at": "2024-03-16T14:00:00Z",+ "updated_at": "2024-03-16T15:00:00Z",+ },+ ],+ "hasMore": False,+ "cursor": None,+}++_NOTE_1 = {+ "id": "not_abc12345678901",+ "title": "Sprint Planning",+ "owner": {"name": "Alice", "email": "[email protected]"},+ "created_at": "2024-03-15T10:00:00Z",+ "updated_at": "2024-03-15T11:00:00Z",+ "attendees": [+ {"name": "Alice", "email": "[email protected]"},+ {"name": "Carol", "email": "[email protected]"},+ ],+ "summary": {"markdown": "Discussed sprint goals and capacity."},+ "transcript": [+ {+ "speaker": "microphone",+ "text": "Let's start with the sprint goals.",+ "start": 0,+ "end": 5,+ },+ {+ "speaker": "speaker",+ "text": "I think we should focus on auth.",+ "start": 5,+ "end": 10,+ },+ ],+ "calendar_event": {+ "event_title": "Sprint Planning",+ "scheduled_start": "2024-03-15T10:00:00Z",+ },+}++_NOTE_2 = {+ "id": "not_def12345678901",+ "title": "Design Review",+ "owner": {"name": "Bob", "email": "[email protected]"},+ "created_at": "2024-03-16T14:00:00Z",+ "updated_at": "2024-03-16T15:00:00Z",+ "attendees": [{"name": "Bob", "email": "[email protected]"}],+ "summary": {"markdown": "Reviewed new dashboard mockups."},+ "transcript": [],+ "calendar_event": None,+}++# ---------------------------------------------------------------------------+# Fixtures+# ---------------------------------------------------------------------------+++def connector(tmp_path: Path):+ """GranolaConnector pointing at a tmp credentials path (no file yet)."""+ from openjarvis.connectors.granola import GranolaConnector # noqa: PLC0415++ creds_path = str(tmp_path / "granola.json")+ return GranolaConnector(credentials_path=creds_path)+++# ---------------------------------------------------------------------------+# Test 1 — not connected without a key or credentials file+# ---------------------------------------------------------------------------+++def test_not_connected_without_key(connector) -> None:+ """is_connected() returns False when no API key and no credentials file."""+ assert connector.is_connected() is False+++# ---------------------------------------------------------------------------+# Test 2 — connected when api_key is provided directly+# ---------------------------------------------------------------------------+++def test_connected_with_key() -> None:+ """is_connected() returns True when an api_key is passed directly."""+ from openjarvis.connectors.granola import GranolaConnector # noqa: PLC0415++ conn = GranolaConnector(api_key="grl_fake_key")+ assert conn.is_connected() is True+++# ---------------------------------------------------------------------------+# Test 3 — auth_url references granola.ai+# ---------------------------------------------------------------------------+++def test_auth_url(connector) -> None:+ """auth_url() returns a URL pointing users to the Granola settings page."""+ url = connector.auth_url()+ assert "granola.ai" in url+++# ---------------------------------------------------------------------------+# Test 4 — sync yields documents with correct fields (mocked API)+# ---------------------------------------------------------------------------+++@patch("openjarvis.connectors.granola._granola_api_list_notes")+@patch("openjarvis.connectors.granola._granola_api_get_note")+def test_sync_yields_documents(+ mock_get,+ mock_list,+ connector,+ tmp_path: Path,+) -> None:+ """sync() yields one Document per note with correct metadata."""+ # Write fake credentials so is_connected() returns True+ creds_path = Path(connector._credentials_path)+ creds_path.parent.mkdir(parents=True, exist_ok=True)+ creds_path.write_text(+ json.dumps({"token": "grl_fake_key"}), encoding="utf-8"+ )++ mock_list.return_value = _LIST_RESPONSE+ mock_get.side_effect = [_NOTE_1, _NOTE_2]++ docs: List[Document] = list(connector.sync())++ assert len(docs) == 2++ # --- Note 1 ---+ doc1 = next(d for d in docs if d.doc_id == "granola:not_abc12345678901")+ assert doc1.source == "granola"+ assert doc1.doc_type == "document"+ assert doc1.title == "Sprint Planning"+ assert doc1.author == "[email protected]"+ assert "[email protected]" in doc1.participants+ assert "[email protected]" in doc1.participants+ assert "Discussed sprint goals and capacity." in doc1.content+ assert "Let's start with the sprint goals." in doc1.content+ assert "I think we should focus on auth." in doc1.content++ # --- Note 2 ---+ doc2 = next(d for d in docs if d.doc_id == "granola:not_def12345678901")+ assert doc2.title == "Design Review"+ assert doc2.author == "[email protected]"+ assert "Reviewed new dashboard mockups." in doc2.content++ # Verify the API was called correctly+ mock_list.assert_called_once()+ assert mock_get.call_count == 2+++# ---------------------------------------------------------------------------+# Test 5 — _format_note_content produces correct summary + transcript+# ---------------------------------------------------------------------------+++def test_format_note_content() -> None:+ """_format_note_content combines summary and transcript into correct markdown."""+ from openjarvis.connectors.granola import _format_note_content # noqa: PLC0415++ result = _format_note_content(_NOTE_1)++ assert "## Summary" in result+ assert "Discussed sprint goals and capacity." in result+ assert "## Transcript" in result+ assert "**microphone:**" in result+ assert "Let's start with the sprint goals." in result+ assert "**speaker:**" in result+ assert "I think we should focus on auth." in result+++# ---------------------------------------------------------------------------+# Test 6 — disconnect removes the credentials file+# ---------------------------------------------------------------------------+++def test_disconnect(connector, tmp_path: Path) -> None:+ """disconnect() deletes the credentials file."""+ creds_path = Path(connector._credentials_path)+ creds_path.parent.mkdir(parents=True, exist_ok=True)+ creds_path.write_text(+ json.dumps({"token": "grl_fake_key"}), encoding="utf-8"+ )+ assert connector.is_connected() is True++ connector.disconnect()++ assert not creds_path.exists()+ assert connector.is_connected() is False+++# ---------------------------------------------------------------------------+# Test 7 — mcp_tools returns the two expected tool specs+# ---------------------------------------------------------------------------+++def test_mcp_tools(connector) -> None:+ """mcp_tools() returns exactly 2 tools with the required names."""+ tools = connector.mcp_tools()+ names = {t.name for t in tools}+ assert len(tools) == 2+ assert "granola_search_notes" in names+ assert "granola_get_note" in names+++# ---------------------------------------------------------------------------+# Test 8 — ConnectorRegistry contains "granola" after import+# ---------------------------------------------------------------------------+++def test_registry() -> None:+ """GranolaConnector can be registered and retrieved via ConnectorRegistry."""+ from openjarvis.connectors.granola import GranolaConnector # noqa: PLC0415++ ConnectorRegistry.register_value("granola", GranolaConnector)+ assert ConnectorRegistry.contains("granola")+ cls = ConnectorRegistry.get("granola")+ assert cls.connector_id == "granola"