synapse-framework 0.2.4__py3-none-any.whl

synapse/cli.py

@@ -0,0 +1,88 @@
+"""Command-line interface for running the Synapse AI inspector server and MCP stdio engine."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from synapse.app import BaseApp
+from synapse.connectors.gmail import GmailConnector
+from synapse.connectors.notion import NotionConnector
+from synapse.export.mcp_exporter import MCPExporter
+from synapse.models.ollama import OllamaModel
+
+
+def build_default_app(data_dir: str = "data") -> BaseApp:
+    """Constructs the default CLI Synapse application instance."""
+    return BaseApp(
+        title="Synapse AI",
+        data_dir=Path(data_dir),
+        model=OllamaModel(),
+        connectors=[
+            GmailConnector(),
+            NotionConnector(),
+        ],
+        persistent_storage=True,
+        Visualize_graph=True,
+    )
+
+
+def main() -> None:
+    """CLI entrypoint: `synapse`, `synapse mcp`, or `python -m synapse.cli`."""
+    parser = argparse.ArgumentParser(
+        description="Synapse — Multi-MCP & Hybrid RAG Framework",
+    )
+    parser.add_argument(
+        "subcommand",
+        nargs="?",
+        default="serve",
+        choices=["serve", "mcp", "export"],
+        help="Action to run: 'serve' (web inspector/API), 'mcp' (stdio server for Claude/Cursor), or 'export' (generate config)",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host interface to bind (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port number to listen on (default: 8000)",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable uvicorn hot-reloading",
+    )
+    parser.add_argument(
+        "--data-dir",
+        default="data",
+        help="Storage directory for ChromaDB and NetworkX graph (default: data)",
+    )
+    parser.add_argument(
+        "--mcp",
+        action="store_true",
+        help="Shortcut to run in stdio MCP mode",
+    )
+    parser.add_argument(
+        "--output",
+        default="claude_desktop_config.json",
+        help="Destination path for 'export' subcommand",
+    )
+
+    args = parser.parse_args()
+    app = build_default_app(data_dir=args.data_dir)
+
+    if args.mcp or args.subcommand == "mcp":
+        # Run stdio MCP server for Claude Desktop / Cursor
+        app.run_mcp(transport="stdio")
+    elif args.subcommand == "export":
+        cfg_path = MCPExporter.save_claude_desktop_config(app, filepath=args.output)
+        print(f"✓ Claude Desktop config saved to: {cfg_path}")
+    else:
+        app.run(host=args.host, port=args.port, reload=args.reload)
+
+
+if __name__ == "__main__":
+    main()

synapse/config.py

@@ -0,0 +1,103 @@
+"""Configuration constants and design tokens for the Synapse framework."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+# Base filesystem directories (default to working directory or user-specified)
+DEFAULT_WORKSPACE_DIR: Path = Path(
+    os.getenv("SYNAPSE_WORKSPACE_DIR", Path.cwd())
+).resolve()
+DEFAULT_DATA_DIR: Path = DEFAULT_WORKSPACE_DIR / "data"
+DEFAULT_CHROMA_DIR: Path = DEFAULT_DATA_DIR / "chroma_db"
+DEFAULT_GRAPH_FILE: Path = DEFAULT_DATA_DIR / "graph.json"
+
+# Default Model settings
+DEFAULT_OLLAMA_BASE_URL: str = os.getenv(
+    "OLLAMA_BASE_URL", "http://localhost:11434"
+)
+DEFAULT_OLLAMA_MODEL: str = os.getenv("OLLAMA_MODEL", "qwen2.5:0.5b")
+DEFAULT_OPENAI_MODEL: str = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+DEFAULT_GEMINI_MODEL: str = os.getenv("GEMINI_MODEL", "gemini-flash-latest")
+DEFAULT_TEMPERATURE: float = float(os.getenv("SYNAPSE_TEMPERATURE", "0.1"))
+
+# Embeddings & Chunking
+DEFAULT_EMBEDDING_MODEL: str = os.getenv(
+    "SYNAPSE_EMBEDDING_MODEL", "BAAI/bge-small-en-v1.5"
+)
+DEFAULT_CHUNK_SIZE: int = int(os.getenv("SYNAPSE_CHUNK_SIZE", "280"))
+DEFAULT_CHUNK_OVERLAP: int = int(os.getenv("SYNAPSE_CHUNK_OVERLAP", "30"))
+DEFAULT_CHROMA_COLLECTION: str = "synapse_memory"
+DEFAULT_TOP_K: int = int(os.getenv("SYNAPSE_TOP_K", "3"))
+
+# Design Tokens: Solid Matte / Zinc Specification
+DESIGN_TOKENS: dict[str, Any] = {
+    "surface": {
+        "canvas": "#09090b",  # Zinc 950
+        "panel": "#18181b",  # Zinc 900
+        "panel_hover": "#27272a",  # Zinc 800
+        "inset": "#121215",  # Zinc 925
+    },
+    "border": {
+        "subtle": "#27272a",  # Zinc 800
+        "strong": "#3f3f46",  # Zinc 700
+    },
+    "text": {
+        "primary": "#f4f4f5",  # Zinc 100
+        "secondary": "#a1a1aa",  # Zinc 400
+        "muted": "#71717a",  # Zinc 500
+        "font_family": "Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+    },
+    "palettes": {
+        "zinc": {
+            "Person": "#818cf8",
+            "Email": "#38bdf8",
+            "Project": "#34d399",
+            "Tool": "#fbbf24",
+            "Topic": "#f472b6",
+            "Database": "#fb923c",
+            "Resource": "#a78bfa",
+            "Document": "#60a5fa",
+            "Framework": "#2dd4bf",
+            "Default": "#94a3b8",
+        },
+        "stone": {
+            "Person": "#e07a5f",
+            "Email": "#81b29a",
+            "Project": "#f2cc8f",
+            "Tool": "#d4a373",
+            "Topic": "#b5838d",
+            "Database": "#e76f51",
+            "Resource": "#6d6875",
+            "Document": "#a8dadc",
+            "Framework": "#588157",
+            "Default": "#a8a29e",
+        },
+        "basalt": {
+            "Person": "#93c5fd",
+            "Email": "#67e8f9",
+            "Project": "#6ee7b7",
+            "Tool": "#fdba74",
+            "Topic": "#f9a8d4",
+            "Database": "#fca5a5",
+            "Resource": "#c4b5fd",
+            "Document": "#7dd3fc",
+            "Framework": "#14b8a6",
+            "Default": "#cbd5e1",
+        },
+        "neon": {
+            "Person": "#00f5d4",
+            "Email": "#00bbf9",
+            "Project": "#7b2cbf",
+            "Tool": "#fee440",
+            "Topic": "#f72585",
+            "Database": "#ff0054",
+            "Resource": "#9b5de5",
+            "Document": "#3a86ff",
+            "Framework": "#06d6a0",
+            "Default": "#00f0ff",
+        },
+    },
+}

synapse/connectors/__init__.py

@@ -0,0 +1,29 @@
+"""Connector definitions and construction factory for Synapse."""
+
+from synapse.connectors.base import BaseConnector
+from synapse.connectors.factory import make_connector, makeconnectors
+from synapse.connectors.gmail import GmailConnector, GmailConnectors
+from synapse.connectors.mcp_wrapper import MCPConnector
+from synapse.connectors.notion import (
+    NotionConnector,
+    NotionConnectors,
+    NotionsConnector,
+)
+from synapse.connectors.photos import (
+    GooglePhotosConnector,
+    GooglePhotosConnectors,
+)
+
+__all__ = [
+    "BaseConnector",
+    "GmailConnector",
+    "GmailConnectors",
+    "GooglePhotosConnector",
+    "GooglePhotosConnectors",
+    "MCPConnector",
+    "NotionConnector",
+    "NotionConnectors",
+    "NotionsConnector",
+    "make_connector",
+    "makeconnectors",
+]

synapse/connectors/base.py

@@ -0,0 +1,222 @@
+"""Abstract base class for all Synapse connectors."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from abc import ABC, abstractmethod
+from typing import Any
+
+from langchain_core.documents import Document
+
+
+class BaseConnector(ABC):
+    """Abstract interface for all Synapse external connectors.
+
+    Every connector exposes tools, authentication state checks, intent matching,
+    and automatic indexing logic into ChromaDB and NetworkX.
+
+    Attributes:
+        name: Unique logical connector identifier (e.g. 'gmail', 'notion', 'photos').
+        description: Human-readable summary of the connector's domain.
+        intent_regex: Optional regex string used as a first-stage intent gate.
+        default_tool: Default tool invoked during sync or fallback operations.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        intent_regex: str | None = None,
+        default_tool: str = "",
+    ) -> None:
+        """Initializes the base connector.
+
+        Args:
+            name: Connector identifier.
+            description: Description of the connector data and capabilities.
+            intent_regex: Optional regex string matching user prompts that require this connector.
+            default_tool: Default tool name.
+        """
+        self.name = name
+        self.description = description
+        self.intent_regex = intent_regex
+        self._compiled_regex = (
+            re.compile(intent_regex, re.IGNORECASE) if intent_regex else None
+        )
+        self.default_tool = default_tool
+
+    def matches_intent(self, user_message: str) -> bool:
+        """Checks if a user message matches this connector's intent regex."""
+        if not self._compiled_regex:
+            return True
+        return bool(self._compiled_regex.search(user_message or ""))
+
+    @abstractmethod
+    def is_authenticated(self) -> bool:
+        """Checks whether the connector has valid authentication credentials."""
+        ...
+
+    @abstractmethod
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """Returns the list of tool schemas exposed by this connector."""
+        ...
+
+    @abstractmethod
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Executes a named tool with arguments.
+
+        Args:
+            tool_name: Name of the tool to execute.
+            arguments: Tool arguments dictionary.
+
+        Returns:
+            Raw tool execution output (list of records or dictionary).
+        """
+        ...
+
+    def default_args_builder(self, user_message: str) -> dict[str, Any]:
+        """Builds default tool arguments from user prompt when arguments are missing."""
+        return {}
+
+    def chunk_record(
+        self,
+        tool_name: str,
+        record: dict[str, Any],
+    ) -> list[Document]:
+        """Standardized chunking normalizer for records produced by this connector.
+
+        Subclasses may override this method for specialized domain chunking.
+        """
+        rec_id = str(
+            record.get("id")
+            or record.get("url")
+            or hashlib.sha256(str(record).encode("utf-8")).hexdigest()[:12]
+        )
+        title = str(
+            record.get("title")
+            or record.get("subject")
+            or record.get("name")
+            or f"{self.name.upper()} Record"
+        ).strip()
+        author = str(
+            record.get("sender")
+            or record.get("from")
+            or record.get("author")
+            or self.name
+        ).strip()
+        date_str = str(
+            record.get("date")
+            or record.get("created_at")
+            or record.get("last_edited_time")
+            or ""
+        ).strip()
+        body = str(
+            record.get("body")
+            or record.get("content")
+            or record.get("text")
+            or record.get("snippet")
+            or ""
+        ).strip()
+        url = str(record.get("url") or "").strip()
+
+        if not body and not title:
+            return []
+
+        header = f"[{self.name.upper()} | {tool_name}] Title: {title} | Source: {author}"
+        if url:
+            header += f" | URL: {url}"
+        full_text = f"{header}\nDate: {date_str}\n\n{body}".strip()
+
+        base_meta: dict[str, Any] = {
+            "source": self.name,
+            "tool": tool_name,
+            "record_id": rec_id,
+            "subject": title,
+            "sender": author,
+            "date": date_str,
+            "url": url,
+            "type": str(record.get("type") or self.name.capitalize()),
+            "chunk_id": f"{self.name}:{rec_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 a record for prompt context, UI RAG chunks, and knowledge graph triple.
+
+        Returns:
+            A tuple of (formatted_summary_line, live_chunk_dict, graph_triple_string).
+        """
+        title = str(
+            record.get("title")
+            or record.get("subject")
+            or record.get("name")
+            or record.get("action")
+            or f"{self.name.upper()} #{index}"
+        )
+        author = str(
+            record.get("sender")
+            or record.get("author")
+            or record.get("owner")
+            or self.name.capitalize()
+        )
+        date_str = str(record.get("date") or "")
+        body_excerpt = str(
+            record.get("body")
+            or record.get("content")
+            or record.get("snippet")
+            or record.get("message")
+            or record.get("text")
+            or record.get("details")
+            or record.get("result")
+            or (json.dumps(record, ensure_ascii=False) if record else "")
+        )[:600].strip()
+        entity_type = str(record.get("type") or "Topic").capitalize()
+
+        summary_line = (
+            f"{index}. [{self.name.upper()}] {title}\n"
+            f"   Source: {author} | Date: {date_str}\n"
+            f"   Content: {body_excerpt}"
+        )
+
+        live_chunk = {
+            "page_content": (
+                f"[{self.name.upper()} | {tool_name}] {title}\n"
+                f"Date: {date_str}\n\n{body_excerpt}"
+            ),
+            "metadata": {
+                "source": f"{self.name}_live",
+                "subject": title,
+                "sender": author,
+                "date": date_str,
+                "type": entity_type,
+            },
+            "source": f"{self.name}_live",
+            "subject": title,
+            "chunk_id": f"live_{self.name}_{record.get('id', index)}",
+        }
+
+        triple = f"{author} -> CONTAINS -> {title}"
+        return summary_line, live_chunk, triple
+
+    def to_mcp_server(self, name: str | None = None) -> Any:
+        """Converts this connector into an official MCP Server instance."""
+        from synapse.export.mcp_exporter import MCPExporter
+        return MCPExporter.create_mcp_server(self, name=name or self.name)
+
+    def run_mcp(self, transport: str = "stdio") -> None:
+        """Runs this connector as a standalone MCP server over stdio or SSE."""
+        server = self.to_mcp_server()
+        server.run(transport=transport)
+

synapse/connectors/factory.py

@@ -0,0 +1,202 @@
+"""Connector factory functions for dynamically constructing BaseConnector instances."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from synapse.connectors.base import BaseConnector
+from synapse.connectors.mcp_wrapper import MCPConnector
+
+
+class FunctionalConnector(BaseConnector):
+    """Dynamic BaseConnector implementation created by `make_connector`."""
+
+    def __init__(
+        self,
+        name: str,
+        service_manager: Any = None,
+        server: Any = None,
+        description: str = "",
+        intent_regex: str | None = None,
+        tools: dict[str, Callable[..., Any]] | None = None,
+        default_tool: str = "",
+        is_authenticated_fn: Callable[[], bool] | None = None,
+    ) -> None:
+        super().__init__(
+            name=name,
+            description=description or f"{name} custom connector",
+            intent_regex=intent_regex,
+            default_tool=default_tool,
+        )
+        self.service_manager = service_manager
+        self.server = server
+        self.tools_dict: dict[str, Callable[..., Any]] = tools or {}
+        self.tools = self.tools_dict
+        self.is_authenticated_fn = is_authenticated_fn
+
+    def is_authenticated(self) -> bool:
+        if self.is_authenticated_fn:
+            try:
+                return bool(self.is_authenticated_fn())
+            except Exception:
+                return False
+        if self.service_manager and hasattr(
+            self.service_manager, "is_authenticated"
+        ):
+            try:
+                return bool(self.service_manager.is_authenticated())
+            except Exception:
+                return False
+        return True
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        schemas: list[dict[str, Any]] = []
+        for tool_name, func in self.tools_dict.items():
+            doc = inspect.getdoc(func) or f"Execute {tool_name}."
+            props: dict[str, Any] = {}
+            required: list[str] = []
+            try:
+                sig = inspect.signature(func)
+                for param_name, param in sig.parameters.items():
+                    if param_name in ("self", "cls"):
+                        continue
+                    p_type = "string"
+                    if param.annotation is int:
+                        p_type = "integer"
+                    elif param.annotation is float:
+                        p_type = "number"
+                    elif param.annotation is bool:
+                        p_type = "boolean"
+                    elif param.annotation is list:
+                        p_type = "array"
+                    elif param.annotation is dict:
+                        p_type = "object"
+
+                    prop_info: dict[str, Any] = {"type": p_type}
+                    if param.default is inspect.Parameter.empty:
+                        required.append(param_name)
+                    else:
+                        prop_info["default"] = param.default
+                    props[param_name] = prop_info
+            except Exception:
+                pass  # nosec B110
+
+            schema_obj: dict[str, Any] = {
+                "type": "object",
+                "properties": props,
+            }
+            if required:
+                schema_obj["required"] = required
+
+            schemas.append({
+                "server": self.name,
+                "name": tool_name,
+                "description": doc,
+                "inputSchema": schema_obj,
+            })
+        return schemas
+
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        if tool_name not in self.tools_dict:
+            raise KeyError(
+                f"Tool '{tool_name}' not registered on connector '{self.name}'."
+            )
+        func = self.tools_dict[tool_name]
+        args = arguments or {}
+        if inspect.iscoroutinefunction(func):
+            return await func(**args)
+        return func(**args)
+
+
+def make_connector(
+    name: str,
+    service_manager: Any = None,
+    server: Any = None,
+    description: str = "",
+    intent_regex: str | None = None,
+    tools: list[Callable[..., Any]] | dict[str, Callable[..., Any]] | None = None,
+    default_tool: str = "",
+    is_authenticated_fn: Callable[[], bool] | None = None,
+) -> BaseConnector:
+    """Creates a Synapse `BaseConnector` from custom service managers or servers.
+
+    Args:
+        name: Unique connector name.
+        service_manager: Optional auth/service manager (e.g. GoogleOAuthService, NotionAuthService).
+        server: Optional FastMCP server script path, server instance, or Stdio command.
+        description: Description of the connector's capabilities.
+        intent_regex: Optional regex string matching relevant user messages.
+        tools: Optional dictionary or list of callable functions exposed as tools.
+        default_tool: Optional default tool identifier.
+        is_authenticated_fn: Optional custom readiness check callable.
+
+    Returns:
+        A ready-to-use `BaseConnector` instance.
+
+    Example:
+        ```python
+        from synapse.connectors import make_connector
+
+        def search_docs(query: str = ""):
+            return [{"title": "Quickstart", "content": "..."}]
+
+        docs_connector = make_connector(
+            name="docs",
+            description="Documentation search",
+            tools={"search_docs": search_docs},
+            default_tool="search_docs",
+        )
+        ```
+    """
+    # If server is a script path or command, wrap via MCPConnector
+    if isinstance(server, (str, Path)) and (
+        str(server).endswith(".py") or Path(server).exists()
+    ):
+        return MCPConnector(
+            name=name,
+            script_path=server,
+            description=description,
+            intent_regex=intent_regex,
+            default_tool=default_tool,
+            is_ready_fn=is_authenticated_fn,
+        )
+
+    # Normalize tools into a dictionary
+    normalized_tools: dict[str, Callable[..., Any]] = {}
+    if isinstance(tools, dict):
+        normalized_tools = tools
+    elif isinstance(tools, list):
+        for fn in tools:
+            fn_name = getattr(fn, "__name__", str(fn))
+            normalized_tools[fn_name] = fn
+
+    # Automatically extract tools from server if server has tools registry
+    if server and hasattr(server, "_tools"):
+        for t_name, t_fn in getattr(server, "_tools", {}).items():
+            if t_name not in normalized_tools:
+                normalized_tools[t_name] = t_fn
+
+    chosen_default = default_tool or ""
+
+    return FunctionalConnector(
+        name=name,
+        service_manager=service_manager,
+        server=server,
+        description=description,
+        intent_regex=intent_regex,
+        tools=normalized_tools,
+        default_tool=chosen_default,
+        is_authenticated_fn=is_authenticated_fn,
+    )
+
+
+# Developer-friendly alias matching user request
+makeconnectors = make_connector