synapse-framework 0.2.4__py3-none-any.whl

synapse/models/openai.py

@@ -0,0 +1,289 @@
+"""OpenAI and OpenAI-compatible API model provider for Synapse."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import AsyncGenerator
+from typing import Any
+
+import httpx
+
+from synapse.config import DEFAULT_OPENAI_MODEL, DEFAULT_TEMPERATURE
+from synapse.models.base import BaseModelProvider
+
+
+class OpenAIModel(BaseModelProvider):
+    """OpenAI API and compatible endpoints (Groq, OpenRouter, DeepSeek, vLLM).
+
+    Attributes:
+        api_key: OpenAI API key (reads from OPENAI_API_KEY if omitted).
+        base_url: API endpoint URL (default: 'https://api.openai.com/v1').
+        model_name: Model identifier (default: 'gpt-4o-mini').
+        organization: Optional organization header.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str = DEFAULT_OPENAI_MODEL,
+        base_url: str = "https://api.openai.com/v1",
+        temperature: float = DEFAULT_TEMPERATURE,
+        organization: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        """Initializes the OpenAI model provider.
+
+        Args:
+            api_key: Secret API key. If None, reads from OPENAI_API_KEY environment variable.
+            model: Model name string. Defaults to 'gpt-4o-mini'.
+            base_url: Base endpoint URL. Defaults to 'https://api.openai.com/v1'.
+            temperature: Sampling temperature. Defaults to 0.1.
+            organization: Optional OpenAI organization ID.
+            timeout: HTTP request timeout in seconds. Defaults to 60.0.
+        """
+        super().__init__(model_name=model, temperature=temperature)
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY", "")
+        self.base_url = base_url.rstrip("/")
+        self.organization = organization
+        self.timeout = timeout
+
+    def _get_headers(self) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        if self.organization:
+            headers["OpenAI-Organization"] = self.organization
+        return headers
+
+    async def chat_stream(
+        self,
+        messages: list[dict[str, str]],
+        temperature: float | None = None,
+    ) -> AsyncGenerator[str, None]:
+        """Streams response tokens from the OpenAI chat completions endpoint."""
+        temp = self.temperature if temperature is None else temperature
+        payload: dict[str, Any] = {
+            "model": self.model_name,
+            "messages": messages,
+            "stream": True,
+            "temperature": temp,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                async with client.stream(
+                    "POST",
+                    f"{self.base_url}/chat/completions",
+                    headers=self._get_headers(),
+                    json=payload,
+                ) as stream:
+                    if stream.status_code in (401, 403):
+                        yield "OpenAI authentication failed: Please verify your OpenAI API key in Settings."
+                        return
+                    if stream.status_code != 200:
+                        yield f"OpenAI API returned HTTP {stream.status_code}."
+                        return
+
+                    async for chunk in stream.aiter_lines():
+                        if not chunk or not chunk.startswith("data: "):
+                            continue
+                        data_str = chunk[6:].strip()
+                        if data_str == "[DONE]":
+                            break
+                        try:
+                            data = json.loads(data_str)
+                            choices = data.get("choices", [])
+                            if choices:
+                                delta = choices[0].get("delta", {})
+                                token = delta.get("content", "")
+                                if token:
+                                    yield token
+                        except json.JSONDecodeError:
+                            continue
+        except (httpx.ConnectError, httpx.ConnectTimeout):
+            yield f"Cannot reach OpenAI API at {self.base_url}. Please check your network connection."
+        except Exception as e:
+            yield f"OpenAI error: {e}"
+
+    async def generate(
+        self,
+        prompt: str,
+        temperature: float | None = None,
+    ) -> str:
+        """Generates a non-streaming response for a prompt string."""
+        temp = self.temperature if temperature is None else temperature
+        payload: dict[str, Any] = {
+            "model": self.model_name,
+            "messages": [{"role": "user", "content": prompt}],
+            "stream": False,
+            "temperature": temp,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                res = await client.post(
+                    f"{self.base_url}/chat/completions",
+                    headers=self._get_headers(),
+                    json=payload,
+                )
+                res.raise_for_status()
+                data = res.json()
+                choices = data.get("choices", [])
+                if choices:
+                    return str(
+                        choices[0].get("message", {}).get("content", "")
+                    ).strip()
+                return ""
+        except (httpx.ConnectError, httpx.ConnectTimeout):
+            return f"[Error: Cannot connect to OpenAI API at {self.base_url}. Check your internet connection.]"
+        except Exception as e:
+            return f"[Error from OpenAI: {e}]"
+
+    async def extract_triples(self, text: str) -> list[dict[str, str]]:
+        """Extracts relational triples using OpenAI structured prompt."""
+        clean_text = text.strip()
+        if not clean_text:
+            return []
+
+        prompt = (
+            "You are an information extraction system. Extract key relational triples from the text.\n"
+            "Valid types: Person, Email, Project, Tool, Topic, Default.\n"
+            "Return ONLY a valid JSON list of objects without explanations or markdown backticks.\n\n"
+            "Example format:\n"
+            '[{"source": "Sarah", "source_type": "Person", "relation": "DISCUSSES", "target": "Synapse", "target_type": "Project"}]\n\n'
+            f"TEXT:\n{clean_text}\n\n"
+            "JSON:"
+        )
+
+        try:
+            raw_text = await self.generate(prompt, temperature=0.0)
+            cleaned = re.sub(
+                r"^```(?:json)?\s*|\s*```$",
+                "",
+                raw_text,
+                flags=re.MULTILINE,
+            ).strip()
+            match = re.search(r"\[.*\]", cleaned, re.DOTALL)
+            if match:
+                cleaned = match.group(0)
+            parsed = json.loads(cleaned)
+
+            if isinstance(parsed, list):
+                valid_triples: list[dict[str, str]] = []
+                for item in parsed:
+                    if (
+                        isinstance(item, dict)
+                        and "source" in item
+                        and "relation" in item
+                        and "target" in item
+                    ):
+                        valid_triples.append({
+                            "source": str(item["source"]).strip(),
+                            "relation": (
+                                str(item["relation"])
+                                .strip()
+                                .upper()
+                                .replace(" ", "_")
+                            ),
+                            "target": str(item["target"]).strip(),
+                            "source_type": (
+                                str(item.get("source_type", "Default"))
+                                .strip()
+                                .title()
+                            ),
+                            "target_type": (
+                                str(item.get("target_type", "Default"))
+                                .strip()
+                                .title()
+                            ),
+                        })
+                return valid_triples
+        except Exception:
+            return []
+
+        return []
+
+    async def decide_tool_calls(
+        self,
+        user_message: str,
+        candidate_tools: list[dict[str, Any]],
+        fallback_calls: list[dict[str, Any]] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Decides tool calls using OpenAI JSON reasoning."""
+        text = (user_message or "").strip()
+        if not text or not candidate_tools:
+            return []
+
+        catalog_lines = []
+        valid_keys: dict[tuple[str, str], dict[str, Any]] = {}
+        for idx, t in enumerate(candidate_tools, start=1):
+            srv = str(t.get("server", "")).strip()
+            name = str(t.get("name", "")).strip()
+            desc = str(t.get("description", "")).strip()
+            schema = json.dumps(t.get("inputSchema", {}).get("properties", {}))
+            catalog_lines.append(
+                f'{idx}. server="{srv}", tool="{name}" — {desc}\n   arguments schema: {schema}'
+            )
+            valid_keys[(srv, name)] = t
+            valid_keys[("", name)] = t
+
+        catalog_text = "\n".join(catalog_lines)
+        tool_prompt = (
+            "You are a multi-tool router for a personal AI assistant.\n"
+            "Available Tools:\n"
+            f"{catalog_text}\n\n"
+            "Decide which tool(s) must be called to answer the user's message.\n"
+            "- Only call a tool if the user's message actually requires fetching data from that service.\n"
+            "- For Gmail unread queries, include 'is:unread' in the Gmail query (e.g. 'label:INBOX is:unread').\n"
+            "Return ONLY valid JSON without markdown backticks in this exact format:\n"
+            '{"tool_calls": [{"server": "gmail", "tool": "search_emails", "arguments": {"query": "label:INBOX is:unread", "max_results": 5}}]}\n'
+            "or if no tool is needed:\n"
+            '{"tool_calls": []}\n\n'
+            f"USER MESSAGE: {text}\n"
+            "JSON:"
+        )
+
+        try:
+            raw_text = await self.generate(tool_prompt, temperature=0.0)
+            cleaned = re.sub(
+                r"^```(?:json)?\s*|\s*```$",
+                "",
+                raw_text,
+                flags=re.MULTILINE,
+            ).strip()
+            match = re.search(r"\{.*\}", cleaned, re.DOTALL)
+            if match:
+                cleaned = match.group(0)
+            parsed = json.loads(cleaned)
+
+            if isinstance(parsed, dict):
+                raw_calls = parsed.get("tool_calls")
+                if isinstance(raw_calls, list):
+                    validated: list[dict[str, Any]] = []
+                    for item in raw_calls:
+                        if not isinstance(item, dict):
+                            continue
+                        srv = str(item.get("server") or "").strip()
+                        tl = str(item.get("tool") or item.get("name") or "").strip()
+                        spec = valid_keys.get((srv, tl)) or valid_keys.get(("", tl))
+                        if not spec:
+                            continue
+                        resolved_srv = str(spec.get("server") or srv)
+                        resolved_tl = str(spec.get("name") or tl)
+                        args = item.get("arguments")
+                        if not isinstance(args, dict):
+                            args = {}
+                        validated.append({
+                            "server": resolved_srv,
+                            "tool": resolved_tl,
+                            "arguments": args,
+                        })
+                    if validated:
+                        return validated
+        except (json.JSONDecodeError, KeyError, TypeError, ValueError, httpx.HTTPError):
+            pass  # nosec B110
+
+        return list(fallback_calls or [])

synapse/oauth/__init__.py

@@ -0,0 +1,7 @@
+"""OAuth and token authentication services for Synapse connectors."""
+
+from synapse.oauth.google import GoogleOAuthService
+from synapse.oauth.notion import NotionAuthService
+
+# Re-export GoogleOAuthService matching the user's requested naming
+__all__ = ["GoogleOAuthService", "NotionAuthService"]

synapse/oauth/google.py

@@ -0,0 +1,194 @@
+"""Reusable Google OAuth 2.0 lifecycle and API service manager."""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import Any
+
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import Resource, build
+
+
+class GoogleOAuthService:
+    """Manages Google OAuth 2.0 credentials, token refresh, and client discovery.
+
+    Reusable across all Google-backed connectors (Gmail, Google Photos,
+    Google Calendar, Google Drive).
+
+    Attributes:
+        credentials_path: Path to the Google Cloud OAuth 2.0 Client Secrets JSON.
+        token_path: Path where authorized user tokens are stored.
+        scopes: List of OAuth scope URIs required by the consumer connector(s).
+    """
+
+    def __init__(
+        self,
+        credentials_path: str | Path = "credentials.json",
+        token_path: str | Path = "token.json",  # nosec B107
+        scopes: list[str] | None = None,
+    ) -> None:
+        """Initializes the GoogleOAuthService.
+
+        Args:
+            credentials_path: Path to credentials.json. Defaults to 'credentials.json'.
+            token_path: Path to token.json. Defaults to 'token.json'.
+            scopes: Optional initial list of OAuth scope URIs.
+        """
+        self.credentials_path = Path(credentials_path).resolve()
+        self.token_path = Path(token_path).resolve()
+        self.scopes: list[str] = list(scopes or [])
+        self._credentials: Credentials | None = None
+
+    def add_scopes(self, scopes: list[str]) -> None:
+        """Adds additional OAuth scopes to this service."""
+        for s in scopes:
+            if s not in self.scopes:
+                self.scopes.append(s)
+
+    def has_credentials(self) -> bool:
+        """Checks if the client secrets credentials.json exists on disk."""
+        return self.credentials_path.exists()
+
+    def is_authenticated(self) -> bool:
+        """Checks if a valid, non-expired token exists on disk or in memory."""
+        if not self.token_path.exists():
+            return False
+        try:
+            creds = Credentials.from_authorized_user_file(
+                str(self.token_path), self.scopes or None
+            )
+            return bool(creds and (creds.valid or creds.refresh_token))
+        except Exception:
+            return False
+
+    def authenticate(
+        self, scopes: list[str] | None = None
+    ) -> Credentials:
+        """Loads, refreshes, or initiates a browser flow to acquire valid Credentials.
+
+        Args:
+            scopes: Optional override or extension of required OAuth scopes.
+
+        Returns:
+            A valid, active `google.oauth2.credentials.Credentials` instance.
+
+        Raises:
+            FileNotFoundError: If credentials_path is missing when authorization is needed.
+        """
+        active_scopes = list(scopes or self.scopes)
+
+        if self.token_path.exists():
+            try:
+                self._credentials = Credentials.from_authorized_user_file(
+                    str(self.token_path), active_scopes
+                )
+            except Exception:
+                self._credentials = None
+
+        if not self._credentials or not self._credentials.valid:
+            if (
+                self._credentials
+                and self._credentials.expired
+                and self._credentials.refresh_token
+            ):
+                self._credentials.refresh(Request())
+            else:
+                if not self.credentials_path.exists():
+                    raise FileNotFoundError(
+                        f"Missing OAuth Client Secrets file at: '{self.credentials_path}'. "
+                        "Please provide a valid credentials.json from Google Cloud Console."
+                    )
+                flow = InstalledAppFlow.from_client_secrets_file(
+                    str(self.credentials_path), active_scopes
+                )
+                self._credentials = flow.run_local_server(port=0)
+
+            self.token_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.token_path, "w", encoding="utf-8") as f:
+                f.write(self._credentials.to_json())
+
+        return self._credentials
+
+    def get_service(
+        self,
+        api_name: str,
+        version: str,
+        scopes: list[str] | None = None,
+    ) -> Resource:
+        """Builds an authenticated Google API Discovery Resource.
+
+        Args:
+            api_name: Google API name (e.g. 'gmail', 'photoslibrary').
+            version: API version (e.g. 'v1').
+            scopes: Required OAuth scopes.
+
+        Returns:
+            An authenticated Resource instance.
+        """
+        creds = self.authenticate(scopes)
+        return build(api_name, version, credentials=creds)
+
+    def save_credentials(self, content: str | bytes | dict[str, Any]) -> Path:
+        """Validates and persists uploaded OAuth Client Secrets content to disk.
+
+        Args:
+            content: Raw JSON bytes, string, or parsed dictionary.
+
+        Returns:
+            Resolved Path where credentials were saved.
+        """
+        if isinstance(content, bytes):
+            parsed = json.loads(content.decode("utf-8"))
+        elif isinstance(content, str):
+            parsed = json.loads(content)
+        else:
+            parsed = content
+
+        if "installed" not in parsed and "web" not in parsed:
+            raise ValueError(
+                "Invalid Google OAuth Client Secrets JSON. Expected 'installed' or 'web' root key."
+            )
+
+        self.credentials_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.credentials_path, "w", encoding="utf-8") as f:
+            json.dump(parsed, f, indent=2)
+
+        return self.credentials_path
+
+    def disconnect(self) -> bool:
+        """Deletes the stored token.json from disk.
+
+        Returns:
+            True if the token was removed, False if it did not exist.
+        """
+        self._credentials = None
+        if self.token_path.exists():
+            self.token_path.unlink()
+            return True
+        return False
+
+    @staticmethod
+    def decode_mime_body(payload: dict[str, Any]) -> str:
+        """Decodes plain-text body from a Gmail MIME payload dictionary."""
+        if "parts" in payload:
+            for part in payload["parts"]:
+                if (
+                    part.get("mimeType") == "text/plain"
+                    and "data" in part.get("body", {})
+                ):
+                    raw_data = part["body"]["data"]
+                    return base64.urlsafe_b64decode(raw_data).decode(
+                        "utf-8", errors="ignore"
+                    )
+
+        if "body" in payload and "data" in payload["body"]:
+            raw_data = payload["body"]["data"]
+            return base64.urlsafe_b64decode(raw_data).decode(
+                "utf-8", errors="ignore"
+            )
+
+        return ""

synapse/oauth/notion.py

@@ -0,0 +1,35 @@
+"""Notion API authentication and header manager."""
+
+from __future__ import annotations
+
+import os
+
+
+class NotionAuthService:
+    """Manages Notion REST API tokens and request headers.
+
+    Attributes:
+        api_key: Notion internal integration secret token.
+        base_url: Base URL of the Notion v1 REST API.
+    """
+
+    def __init__(self, api_key: str | None = None) -> None:
+        """Initializes the Notion authentication service.
+
+        Args:
+            api_key: Optional Notion API token (reads from NOTION_API_KEY env if omitted).
+        """
+        self.api_key = api_key or os.getenv("NOTION_API_KEY", "")
+        self.base_url = "https://api.notion.com/v1"
+
+    def is_authenticated(self) -> bool:
+        """Checks if a non-empty API token is configured."""
+        return bool(self.api_key and self.api_key.strip())
+
+    def get_headers(self) -> dict[str, str]:
+        """Constructs request headers for Notion API invocations."""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Notion-Version": "2022-06-28",
+            "Content-Type": "application/json",
+        }

synapse/rag/__init__.py

@@ -0,0 +1,8 @@
+"""Retrieval-Augmented Generation (RAG) and chunking primitives."""
+
+from synapse.rag.chunker import DocumentChunker
+from synapse.rag.hybrid_rag import HybridRAGEngine
+
+HybridRAG = HybridRAGEngine
+
+__all__ = ["DocumentChunker", "HybridRAG", "HybridRAGEngine"]