synapse-framework 0.2.4__py3-none-any.whl

synapse/connectors/gmail.py

@@ -0,0 +1,292 @@
+"""Gmail connector for the Synapse framework."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from langchain_core.documents import Document
+
+from synapse.connectors.base import BaseConnector
+from synapse.oauth.google import GoogleOAuthService
+
+GMAIL_READONLY_SCOPE = "https://www.googleapis.com/auth/gmail.readonly"
+
+
+class GmailConnector(BaseConnector):
+    """Google Gmail connector for fetching, searching, and indexing emails.
+
+    Attributes:
+        oauth: Reusable GoogleOAuthService managing OAuth tokens and Discovery client.
+    """
+
+    def __init__(
+        self,
+        credentials_path: str | Path = "credentials.json",
+        token_path: str | Path = "token.json",  # nosec B107
+        oauth_service: GoogleOAuthService | None = None,
+        scopes: list[str] | None = None,
+    ) -> None:
+        """Initializes the GmailConnector.
+
+        Args:
+            credentials_path: Path to OAuth client secrets JSON.
+            token_path: Path to cached token JSON.
+            oauth_service: Optional pre-configured GoogleOAuthService instance.
+            scopes: Optional list of OAuth scopes.
+        """
+        super().__init__(
+            name="gmail",
+            description="Gmail inbox, unread/read emails, senders, and message threads",
+            intent_regex=(
+                r"\b(email|emails|e-mail|inbox|unread|mail|mails|message|messages|"
+                r"gmail|sender|sent\s+me|from\s+[a-z0-9_.-]+|check\s+my\s+mail|"
+                r"check\s+my\s+inbox|recent\s+threads)\b"
+            ),
+            default_tool="search_emails",
+        )
+
+        active_scopes = list(scopes or [GMAIL_READONLY_SCOPE])
+        if oauth_service:
+            self.oauth = oauth_service
+            self.oauth.add_scopes(active_scopes)
+        else:
+            self.oauth = GoogleOAuthService(
+                credentials_path=credentials_path,
+                token_path=token_path,
+                scopes=active_scopes,
+            )
+
+    def is_authenticated(self) -> bool:
+        """Returns True if a valid Gmail OAuth token exists."""
+        return self.oauth.is_authenticated()
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """Returns the Gmail tool schemas."""
+        return [
+            {
+                "server": self.name,
+                "name": "search_emails",
+                "description": (
+                    "Search Gmail messages using Gmail query syntax "
+                    "(e.g. 'label:INBOX', 'label:INBOX is:unread', 'from:Sender')."
+                ),
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "default": "label:INBOX",
+                            "description": "Gmail search query string.",
+                        },
+                        "max_results": {
+                            "type": "integer",
+                            "default": 5,
+                            "description": "Maximum number of messages to return.",
+                        },
+                    },
+                },
+            }
+        ]
+
+    def default_args_builder(self, user_message: str) -> dict[str, Any]:
+        """Constructs smart Gmail query arguments from user natural language prompt."""
+        text = (user_message or "").strip()
+        q_lower = text.lower()
+        wants_unread = bool(
+            re.search(
+                r"\b(unread|unseen|not\s+read|new\s+email|new\s+emails|new\s+message|new\s+messages)\b",
+                q_lower,
+            )
+        )
+        query = "label:INBOX is:unread" if wants_unread else "label:INBOX"
+
+        from_match = re.search(
+            r"\bfrom\s+([a-zA-Z0-9_.@-]+)", text, re.IGNORECASE
+        )
+        if from_match:
+            sender_term = from_match.group(1).strip("?.!,")
+            if sender_term.lower() not in {
+                "my",
+                "the",
+                "recent",
+                "inbox",
+                "gmail",
+                "email",
+                "emails",
+            }:
+                query = (
+                    f"from:{sender_term} is:unread"
+                    if wants_unread
+                    else f"from:{sender_term}"
+                )
+
+        return {"query": query, "max_results": 5}
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Executes a Gmail tool via Google API."""
+        args = arguments or {}
+        if tool_name == "search_emails":
+            query = str(args.get("query", "label:INBOX"))
+            max_results = int(args.get("max_results", 5))
+            return self.search_emails(query=query, max_results=max_results)
+        raise ValueError(
+            f"Unknown tool '{tool_name}' for connector '{self.name}'"
+        )
+
+    def search_emails(
+        self,
+        query: str = "label:INBOX",
+        max_results: int = 5,
+    ) -> list[dict[str, Any]]:
+        """Searches Gmail using Google API Discovery client."""
+        if not self.is_authenticated():
+            return []
+
+        service = self.oauth.get_service(
+            api_name="gmail", version="v1", scopes=[GMAIL_READONLY_SCOPE]
+        )
+        response = (
+            service.users()
+            .messages()
+            .list(userId="me", q=query, maxResults=max_results)
+            .execute()
+        )
+
+        messages_meta = response.get("messages", [])
+        if not messages_meta:
+            return []
+
+        results: list[dict[str, Any]] = []
+        for meta in messages_meta:
+            msg = (
+                service.users()
+                .messages()
+                .get(userId="me", id=meta["id"], format="full")
+                .execute()
+            )
+
+            payload = msg.get("payload", {})
+            headers = payload.get("headers", [])
+            label_ids = msg.get("labelIds", []) or []
+            is_unread = "UNREAD" in label_ids
+
+            subject = next(
+                (h["value"] for h in headers if h["name"].lower() == "subject"),
+                "No Subject",
+            )
+            sender = next(
+                (h["value"] for h in headers if h["name"].lower() == "from"),
+                "Unknown Sender",
+            )
+            recipient = next(
+                (h["value"] for h in headers if h["name"].lower() == "to"), "Me"
+            )
+            date_str = next(
+                (h["value"] for h in headers if h["name"].lower() == "date"), ""
+            )
+
+            body_text = GoogleOAuthService.decode_mime_body(payload)
+            snippet = msg.get("snippet", "")
+
+            results.append({
+                "id": msg["id"],
+                "subject": subject,
+                "sender": sender,
+                "to": recipient,
+                "date": date_str,
+                "is_unread": is_unread,
+                "labels": label_ids,
+                "snippet": snippet,
+                "body": (body_text.strip() or snippet.strip()),
+            })
+
+        return results
+
+    def chunk_record(
+        self,
+        tool_name: str,
+        record: dict[str, Any],
+    ) -> list[Document]:
+        """Chunks an email record with rich unread metadata."""
+        email_id = str(record.get("id", ""))
+        subject = str(record.get("subject", "No Subject")).strip()
+        sender = str(
+            record.get("from") or record.get("sender") or "Unknown Sender"
+        ).strip()
+        recipients = str(record.get("to", "Me")).strip()
+        date_str = str(record.get("date", "")).strip()
+        body = str(record.get("body", "")).strip()
+        is_unread = bool(record.get("is_unread", False))
+        read_tag = "UNREAD" if is_unread else "READ"
+
+        if not body and not subject:
+            return []
+
+        header = f"[EMAIL | {read_tag}] Subject: {subject} | From: {sender} | To: {recipients}"
+        full_text = f"{header}\nDate: {date_str}\n\n{body}"
+
+        base_meta = {
+            "source": "gmail",
+            "email_id": email_id,
+            "subject": subject,
+            "sender": sender,
+            "recipients": recipients,
+            "date": date_str,
+            "is_unread": is_unread,
+            "type": "Email",
+            "chunk_id": f"gmail:{email_id}:0",
+        }
+
+        return [Document(page_content=full_text, metadata=base_meta)]
+
+    def format_record(
+        self,
+        tool_name: str,
+        record: dict[str, Any],
+        index: int = 1,
+    ) -> tuple[str, dict[str, Any], str]:
+        """Formats email into context string, UI chunk, and knowledge graph triple."""
+        is_unread = bool(record.get("is_unread", False))
+        unread_badge = "UNREAD" if is_unread else "READ"
+        subject = record.get("subject", "No Subject")
+        sender = record.get("sender", "Unknown Sender")
+        date_str = record.get("date", "")
+        body_excerpt = (
+            record.get("body") or record.get("snippet") or ""
+        )[:600].strip()
+
+        summary_line = (
+            f"{index}. [{unread_badge}] Subject: {subject}\n"
+            f"   From: {sender} | Date: {date_str}\n"
+            f"   Content: {body_excerpt}"
+        )
+
+        live_chunk = {
+            "page_content": (
+                f"[EMAIL | {unread_badge}] Subject: {subject} | From: {sender}\n"
+                f"Date: {date_str}\n\n{body_excerpt}"
+            ),
+            "metadata": {
+                "source": "gmail_live",
+                "subject": f"[{unread_badge}] {subject}",
+                "sender": sender,
+                "date": date_str,
+                "is_unread": is_unread,
+            },
+            "source": "gmail_live",
+            "subject": f"[{unread_badge}] {subject}",
+            "chunk_id": f"live_gmail_{record.get('id', index)}",
+        }
+
+        triple = f"{sender} -> SENT -> {subject}"
+        return summary_line, live_chunk, triple
+
+
+# Developer-friendly alias matching user request
+GmailConnectors = GmailConnector

synapse/connectors/mcp_wrapper.py

@@ -0,0 +1,153 @@
+"""Generic FastMCP / stdio MCP connector wrapper for the Synapse framework."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from synapse.connectors.base import BaseConnector
+
+
+class MCPConnector(BaseConnector):
+    """Wraps an external FastMCP or stdio MCP server into a Synapse BaseConnector.
+
+    Enables adding any MCP server (e.g. GitHub, Slack, Google Calendar, Postgres)
+    with a single class instantiation.
+
+    Attributes:
+        server_params: StdioServerParameters used to run the MCP subprocess.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        script_path: str | Path | None = None,
+        command: str | None = None,
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        description: str = "",
+        intent_regex: str | None = None,
+        default_tool: str = "",
+        is_ready_fn: Callable[[], bool] | None = None,
+        static_tools: list[dict[str, Any]] | None = None,
+    ) -> None:
+        """Initializes the generic MCP connector.
+
+        Args:
+            name: Connector identifier.
+            script_path: Path to a Python MCP server script.
+            command: Executable command override (e.g. 'uvx', 'npx').
+            args: CLI arguments when using an external command.
+            env: Extra environment variables.
+            description: Domain description.
+            intent_regex: Regex for matching relevant user prompts.
+            default_tool: Default tool name.
+            is_ready_fn: Callable returning True when authentication is ready.
+            static_tools: Pre-declared tool schemas.
+        """
+        super().__init__(
+            name=name,
+            description=description or f"{name} MCP connector",
+            intent_regex=intent_regex,
+            default_tool=default_tool,
+        )
+        self.is_ready_fn = is_ready_fn or (lambda: True)
+        self.static_tools = static_tools or []
+        self._tools_cache: list[dict[str, Any]] | None = (
+            static_tools if static_tools else None
+        )
+
+        merged_env = os.environ.copy()
+        if script_path:
+            script_abs = Path(script_path).resolve()
+            python_path = f"{script_abs.parent}:{merged_env.get('PYTHONPATH', '')}"
+            merged_env["PYTHONPATH"] = python_path
+            exec_cmd = command or sys.executable
+            exec_args = args if args is not None else [str(script_abs)]
+        else:
+            exec_cmd = command or sys.executable
+            exec_args = args or []
+
+        if env:
+            merged_env.update(env)
+
+        self.server_params = StdioServerParameters(
+            command=exec_cmd,
+            args=exec_args,
+            env=merged_env,
+        )
+
+    def is_authenticated(self) -> bool:
+        """Checks if the wrapped MCP server is configured and ready."""
+        try:
+            return bool(self.is_ready_fn())
+        except Exception:
+            return False
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """Discovers tools exposed by the MCP server."""
+        if self._tools_cache:
+            return self._tools_cache
+
+        try:
+            async with stdio_client(self.server_params) as (
+                read_stream,
+                write_stream,
+            ), ClientSession(read_stream, write_stream) as session:
+                await session.initialize()
+                tools_result = await session.list_tools()
+                discovered = [
+                    {
+                        "server": self.name,
+                        "name": tool.name,
+                        "description": tool.description,
+                        "inputSchema": getattr(
+                            tool,
+                            "inputSchema",
+                            getattr(tool, "input_schema", {}),
+                        ),
+                    }
+                    for tool in tools_result.tools
+                ]
+                self._tools_cache = discovered
+                return discovered
+        except Exception:
+            return self.static_tools
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Invokes a tool on the MCP server over stdio."""
+        async with stdio_client(self.server_params) as (
+            read_stream,
+            write_stream,
+        ), ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            result = await session.call_tool(
+                name=tool_name,
+                arguments=arguments or {},
+            )
+
+            extracted_data: list[Any] = []
+            for content in result.content:
+                if hasattr(content, "text"):
+                    try:
+                        parsed = json.loads(content.text)
+                        extracted_data.append(parsed)
+                    except (json.JSONDecodeError, TypeError):
+                        extracted_data.append(content.text)
+                else:
+                    extracted_data.append(content)
+
+            if len(extracted_data) == 1:
+                return extracted_data[0]
+            return extracted_data

synapse/connectors/notion.py

@@ -0,0 +1,161 @@
+"""Notion connector for searching and indexing workspace documents."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import httpx
+
+from synapse.connectors.base import BaseConnector
+from synapse.oauth.notion import NotionAuthService
+
+
+class NotionConnector(BaseConnector):
+    """Notion workspace connector for querying pages, databases, and notes.
+
+    Attributes:
+        auth: NotionAuthService managing API authentication headers.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        auth_service: NotionAuthService | None = None,
+    ) -> None:
+        """Initializes the NotionConnector.
+
+        Args:
+            api_key: Optional Notion API integration token.
+            auth_service: Optional pre-configured NotionAuthService instance.
+        """
+        super().__init__(
+            name="notion",
+            description="Notion workspace pages, notes, wiki docs, and databases",
+            intent_regex=(
+                r"\b(notion|wiki|workspace\s+page|workspace\s+pages|notion\s+page|"
+                r"notion\s+pages|notion\s+note|notion\s+notes|notion\s+database)\b"
+            ),
+            default_tool="search_notion_pages",
+        )
+        self.auth = auth_service or NotionAuthService(api_key=api_key)
+
+    def is_authenticated(self) -> bool:
+        """Checks if a Notion API token is available."""
+        return self.auth.is_authenticated()
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """Returns the Notion tool schemas."""
+        return [
+            {
+                "server": self.name,
+                "name": "search_notion_pages",
+                "description": "Search Notion workspace pages and databases matching a query.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "default": "",
+                            "description": "Title or keyword substring to search.",
+                        },
+                        "max_results": {
+                            "type": "integer",
+                            "default": 5,
+                            "description": "Maximum number of Notion items to return.",
+                        },
+                    },
+                },
+            }
+        ]
+
+    def default_args_builder(self, user_message: str) -> dict[str, Any]:
+        """Strips conversational noise from user prompt for Notion search."""
+        text = (user_message or "").strip()
+        cleaned = re.sub(
+            r"\b(check|find|search|show|my|in|on|from|notion|pages|page|notes|note|database|workspace|docs)\b",
+            " ",
+            text,
+            flags=re.IGNORECASE,
+        )
+        cleaned = " ".join(cleaned.split()).strip("?.!,")
+        return {"query": cleaned[:80], "max_results": 5}
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Executes a Notion tool."""
+        args = arguments or {}
+        if tool_name == "search_notion_pages":
+            query = str(args.get("query", ""))
+            max_results = int(args.get("max_results", 5))
+            return await self.search_notion_pages(
+                query=query, max_results=max_results
+            )
+        raise ValueError(
+            f"Unknown tool '{tool_name}' for connector '{self.name}'"
+        )
+
+    async def search_notion_pages(
+        self,
+        query: str = "",
+        max_results: int = 5,
+    ) -> list[dict[str, Any]]:
+        """Executes a live search against the Notion v1 REST API."""
+        if not self.is_authenticated():
+            return []
+
+        payload: dict[str, Any] = {"page_size": max(1, min(max_results, 20))}
+        if query.strip():
+            payload["query"] = query.strip()
+
+        async with httpx.AsyncClient(timeout=20.0) as client:
+            res = await client.post(
+                f"{self.auth.base_url}/search",
+                headers=self.auth.get_headers(),
+                json=payload,
+            )
+            res.raise_for_status()
+            data = res.json()
+
+        results: list[dict[str, Any]] = []
+        for item in data.get("results", []):
+            item_id = item.get("id", "")
+            obj_type = item.get("object", "page")
+            url = item.get("url", "")
+            last_edited = item.get("last_edited_time", "")
+
+            title = "Untitled Notion Page"
+            props = item.get("properties", {})
+            for prop_val in props.values():
+                if (
+                    isinstance(prop_val, dict)
+                    and prop_val.get("type") == "title"
+                ):
+                    title_arr = prop_val.get("title", [])
+                    if title_arr:
+                        title = (
+                            "".join(
+                                t.get("plain_text", "") for t in title_arr
+                            ).strip()
+                            or title
+                        )
+                    break
+
+            results.append({
+                "id": item_id,
+                "title": title,
+                "type": obj_type,
+                "url": url,
+                "date": last_edited,
+                "content": f"Notion {obj_type}: {title} (URL: {url})",
+            })
+
+        return results
+
+
+# Developer-friendly aliases matching different casing
+NotionConnectors = NotionConnector
+NotionsConnector = NotionConnector