synapse-framework 0.2.4__py3-none-any.whl

synapse/database/qdrant.py

@@ -0,0 +1,138 @@
+"""Qdrant vector database provider for Synapse."""
+
+from __future__ import annotations
+
+from typing import Any, Union
+
+from langchain_core.documents import Document
+
+from synapse.database.base import BaseVectorDB
+from synapse.embeddings import resolve_embedding
+
+
+class QdrantDB(BaseVectorDB):
+    """Qdrant vector database adapter supporting local memory, disk, or remote cloud cluster."""
+
+    def __init__(
+        self,
+        location: str | None = ":memory:",
+        url: str | None = None,
+        api_key: str | None = None,
+        path: str | None = None,
+        collection_name: str = "synapse_collection",
+        embedding: Union[str, Any] | None = None,
+        embedding_model: str | None = None,
+        embedding_function: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.collection_name = collection_name
+        self.embedding_function = resolve_embedding(
+            embedding=embedding or embedding_function or embedding_model,
+            **kwargs,
+        )
+
+        try:
+            from langchain_community.vectorstores import Qdrant
+            from qdrant_client import QdrantClient
+
+            if url is not None:
+                self.client = QdrantClient(url=url, api_key=api_key)
+            elif path is not None:
+                self.client = QdrantClient(path=path)
+            else:
+                self.client = QdrantClient(location=location or ":memory:")
+
+            self.store = Qdrant(
+                client=self.client,
+                collection_name=collection_name,
+                embeddings=self.embedding_function,
+            )
+        except ImportError:
+            # Fallback wrapper if qdrant-client is not installed
+            from synapse.database.memory import InMemoryDB
+            self._fallback = InMemoryDB(
+                embedding_model=embedding_model,
+                embedding_function=self.embedding_function,
+            )
+            self.store = None
+
+    def add_documents(
+        self,
+        documents: list[Document],
+        embeddings: list[list[float]] | None = None,
+    ) -> list[str]:
+        if self.store:
+            return self.store.add_documents(documents)
+        return self._fallback.add_documents(documents, embeddings)
+
+    def similarity_search(
+        self,
+        query: str,
+        k: int = 4,
+        filter_dict: dict[str, Any] | None = None,
+        query_embedding: list[float] | None = None,
+    ) -> list[Document]:
+        if self.store:
+            return self.store.similarity_search(query=query, k=k)
+        return self._fallback.similarity_search(query=query, k=k, filter_dict=filter_dict)
+
+    def count(self) -> int:
+        if self.store:
+            try:
+                res = self.client.get_collection(self.collection_name)
+                return getattr(res, "points_count", 0) or 0
+            except Exception:
+                return 0
+        return self._fallback.count()
+
+    def clear(self) -> None:
+        if self.store:
+            try:
+                self.client.delete_collection(self.collection_name)
+            except Exception:
+                pass  # nosec B110
+        else:
+            self._fallback.clear()
+
+
+def qdrant(
+    location: str | None = ":memory:",
+    url: str | None = None,
+    api_key: str | None = None,
+    path: str | None = None,
+    collection_name: str = "synapse_collection",
+    embedding: Union[str, Any] | None = None,
+    embedding_model: str | None = None,
+    embedding_function: Any | None = None,
+    **kwargs: Any,
+) -> QdrantDB:
+    """Factory helper to configure a Qdrant vector database instance.
+
+    Example:
+        ```python
+        from synapse.database import qdrant
+
+        # In-memory with MiniLM:
+        db = qdrant(embedding="minilm")
+
+        # Local disk with FastEmbed BGE:
+        db = qdrant(path="data/qdrant_db", embedding="fastembed")
+
+        # Remote cluster:
+        db = qdrant(url="https://xyz.cloud.qdrant.io", api_key="...", embedding="minilm")
+        ```
+    """
+    return QdrantDB(
+        location=location,
+        url=url,
+        api_key=api_key,
+        path=path,
+        collection_name=collection_name,
+        embedding=embedding,
+        embedding_model=embedding_model,
+        embedding_function=embedding_function,
+        **kwargs,
+    )
+
+
+__all__ = ["QdrantDB", "qdrant"]

synapse/embeddings/__init__.py

@@ -0,0 +1,21 @@
+"""Embedding model providers and resolution utilities for Synapse."""
+
+from synapse.embeddings.base import (
+    EmbeddingModelRegistry,
+    fastembed,
+    huggingface_embeddings,
+    minilm,
+    ollama_embeddings,
+    openai_embeddings,
+    resolve_embedding,
+)
+
+__all__ = [
+    "EmbeddingModelRegistry",
+    "fastembed",
+    "huggingface_embeddings",
+    "minilm",
+    "ollama_embeddings",
+    "openai_embeddings",
+    "resolve_embedding",
+]

synapse/embeddings/base.py

@@ -0,0 +1,262 @@
+"""Pluggable embedding providers and model resolution engine for Synapse."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from synapse.config import DEFAULT_EMBEDDING_MODEL
+
+
+class EmbeddingModelRegistry:
+    """Friendly shorthand aliases for popular embedding models."""
+
+    ALIASES: dict[str, str] = {
+        # MiniLM variants
+        "minilm": "sentence-transformers/all-MiniLM-L6-v2",
+        "all-minilm": "sentence-transformers/all-MiniLM-L6-v2",
+        "all-minilm-l6-v2": "sentence-transformers/all-MiniLM-L6-v2",
+        "minilm-l6": "sentence-transformers/all-MiniLM-L6-v2",
+        "paraphrase-minilm": "sentence-transformers/paraphrase-MiniLM-L6-v2",
+        # BGE variants (Default FastEmbed models)
+        "fastembed": DEFAULT_EMBEDDING_MODEL,
+        "bge": DEFAULT_EMBEDDING_MODEL,
+        "bge-small": "BAAI/bge-small-en-v1.5",
+        "bge-base": "BAAI/bge-base-en-v1.5",
+        "bge-large": "BAAI/bge-large-en-v1.5",
+        # Nomic
+        "nomic": "nomic-ai/nomic-embed-text-v1.5",
+        "nomic-embed": "nomic-ai/nomic-embed-text-v1.5",
+        # Multilingual E5
+        "e5": "intfloat/multilingual-e5-large",
+        "multilingual-e5": "intfloat/multilingual-e5-large",
+        # OpenAI models
+        "openai": "text-embedding-3-small",
+        "text-embedding-3-small": "text-embedding-3-small",
+        "text-embedding-3-large": "text-embedding-3-large",
+        "ada": "text-embedding-ada-002",
+        "text-embedding-ada-002": "text-embedding-ada-002",
+    }
+
+
+def fastembed(
+    model_name: str = "BAAI/bge-small-en-v1.5",
+    max_length: int | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Initializes FastEmbed ONNX local embeddings (ultra-fast, zero-PyTorch).
+
+    Args:
+        model_name: Model name or HuggingFace ID (e.g. 'BAAI/bge-small-en-v1.5',
+            'sentence-transformers/all-MiniLM-L6-v2', 'nomic-ai/nomic-embed-text-v1.5').
+        max_length: Optional maximum sequence length.
+        **kwargs: Extra arguments forwarded to FastEmbedEmbeddings.
+
+    Returns:
+        FastEmbedEmbeddings instance.
+    """
+    resolved_model = EmbeddingModelRegistry.ALIASES.get(model_name.lower(), model_name)
+    try:
+        from langchain_community.embeddings.fastembed import FastEmbedEmbeddings
+
+        extra_args: dict[str, Any] = dict(kwargs)
+        if max_length is not None:
+            extra_args["max_length"] = max_length
+        return FastEmbedEmbeddings(model_name=resolved_model, **extra_args)
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to load FastEmbed model '{resolved_model}': {e}. "
+            "Ensure 'fastembed' is installed."
+        ) from e
+
+
+def minilm(
+    model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+    **kwargs: Any,
+) -> Any:
+    """Convenience factory for MiniLM embeddings via FastEmbed ONNX runtime.
+
+    Args:
+        model_name: MiniLM model variant. Defaults to 'sentence-transformers/all-MiniLM-L6-v2'.
+        **kwargs: Extra parameters passed to FastEmbed.
+
+    Returns:
+        FastEmbedEmbeddings configured with all-MiniLM-L6-v2.
+    """
+    return fastembed(model_name=model_name, **kwargs)
+
+
+def openai_embeddings(
+    model: str = "text-embedding-3-small",
+    api_key: str | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Initializes OpenAI cloud vector embeddings.
+
+    Args:
+        model: OpenAI embedding model name. Defaults to 'text-embedding-3-small'.
+        api_key: Optional OpenAI API key (reads OPENAI_API_KEY env if omitted).
+        **kwargs: Extra parameters passed to OpenAIEmbeddings.
+
+    Returns:
+        OpenAIEmbeddings instance.
+    """
+    try:
+        from langchain_openai import OpenAIEmbeddings
+
+        return OpenAIEmbeddings(model=model, api_key=api_key, **kwargs)
+    except ImportError:
+        try:
+            from langchain_community.embeddings import OpenAIEmbeddings
+
+            return OpenAIEmbeddings(model=model, openai_api_key=api_key, **kwargs)
+        except Exception as e:
+            raise ImportError(
+                "OpenAI embeddings require 'langchain-openai'. "
+                "Install it via 'pip install langchain-openai'."
+            ) from e
+
+
+def ollama_embeddings(
+    model: str = "nomic-embed-text",
+    base_url: str = "http://localhost:11434",
+    **kwargs: Any,
+) -> Any:
+    """Initializes Ollama local embeddings.
+
+    Args:
+        model: Model tag installed in Ollama (e.g. 'nomic-embed-text', 'all-minilm').
+        base_url: Ollama daemon URL. Defaults to 'http://localhost:11434'.
+        **kwargs: Extra parameters.
+
+    Returns:
+        OllamaEmbeddings instance.
+    """
+    try:
+        from langchain_community.embeddings import OllamaEmbeddings
+
+        return OllamaEmbeddings(model=model, base_url=base_url, **kwargs)
+    except Exception as e:
+        raise ImportError(
+            f"Failed to load Ollama embeddings: {e}. "
+            "Ensure 'langchain-community' and Ollama are available."
+        ) from e
+
+
+def huggingface_embeddings(
+    model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+    **kwargs: Any,
+) -> Any:
+    """Initializes PyTorch HuggingFace sentence-transformers embeddings.
+
+    Args:
+        model_name: HuggingFace model repo name.
+        **kwargs: Extra parameters.
+
+    Returns:
+        HuggingFaceEmbeddings instance.
+    """
+    try:
+        from langchain_community.embeddings import HuggingFaceEmbeddings
+
+        return HuggingFaceEmbeddings(model_name=model_name, **kwargs)
+    except Exception:
+        # Fall back to FastEmbed for identical weights with 0 PyTorch
+        return fastembed(model_name=model_name, **kwargs)
+
+
+def resolve_embedding(
+    embedding: str | Any | None = None,
+    embedding_model: str | None = None,
+    embedding_function: Any | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Flexible resolver converting strings, aliases, or objects into an embedding instance.
+
+    Supported patterns:
+        - None: Defaults to 'BAAI/bge-small-en-v1.5' via FastEmbed
+        - 'minilm' or 'all-minilm-l6-v2': MiniLM ONNX embedding
+        - 'fastembed' or 'bge-small': BGE Small ONNX embedding
+        - 'openai' or 'text-embedding-3-small': OpenAI cloud embedding
+        - 'ollama' or 'nomic-embed-text': Local Ollama embedding
+        - Custom Embeddings object: Returned as-is
+
+    Args:
+        embedding: Model alias string, HuggingFace ID, or Embeddings instance.
+        embedding_model: Backward-compatible alias for embedding string.
+        embedding_function: Backward-compatible alias for custom object.
+        **kwargs: Extra keyword arguments forwarded to the provider.
+
+    Returns:
+        An initialized embedding function satisfying the LangChain Embeddings protocol.
+    """
+    # 1. Custom pre-instantiated object passed
+    target = embedding if embedding is not None else (embedding_function or embedding_model)
+
+    if target is None:
+        return fastembed(DEFAULT_EMBEDDING_MODEL, **kwargs)
+
+    # Check if target is already an embedding instance (has embed_documents / embed_query)
+    if hasattr(target, "embed_documents") and hasattr(target, "embed_query"):
+        return target
+
+    # Callable function wrapper
+    if callable(target) and not isinstance(target, str):
+        return target
+
+    # 2. String alias resolution
+    if isinstance(target, str):
+        clean_str = target.strip()
+        lower_str = clean_str.lower()
+
+        # MiniLM shorthand
+        if lower_str in ("minilm", "all-minilm", "all-minilm-l6-v2", "minilm-l6", "sentence-transformers/all-minilm-l6-v2"):
+            return minilm(**kwargs)
+
+        # FastEmbed / BGE shorthands
+        if lower_str in ("fastembed", "bge", "bge-small", "baai/bge-small-en-v1.5"):
+            return fastembed("BAAI/bge-small-en-v1.5", **kwargs)
+
+        if lower_str in ("bge-base", "baai/bge-base-en-v1.5"):
+            return fastembed("BAAI/bge-base-en-v1.5", **kwargs)
+
+        if lower_str in ("bge-large", "baai/bge-large-en-v1.5"):
+            return fastembed("BAAI/bge-large-en-v1.5", **kwargs)
+
+        if lower_str in ("nomic", "nomic-embed", "nomic-ai/nomic-embed-text-v1.5"):
+            return fastembed("nomic-ai/nomic-embed-text-v1.5", **kwargs)
+
+        if lower_str in ("e5", "multilingual-e5", "intfloat/multilingual-e5-large"):
+            return fastembed("intfloat/multilingual-e5-large", **kwargs)
+
+        # OpenAI shorthands
+        if lower_str in ("openai", "text-embedding-3-small", "text-embedding-3-large", "ada", "text-embedding-ada-002"):
+            model_name = "text-embedding-3-small" if lower_str == "openai" else clean_str
+            return openai_embeddings(model=model_name, **kwargs)
+
+        # Ollama shorthands
+        if lower_str.startswith("ollama:"):
+            ollama_m = clean_str.split(":", 1)[1]
+            return ollama_embeddings(model=ollama_m, **kwargs)
+
+        if lower_str == "ollama":
+            return ollama_embeddings(**kwargs)
+
+        # Try FastEmbed with the arbitrary model name (supports HuggingFace repo names)
+        try:
+            return fastembed(clean_str, **kwargs)
+        except Exception:
+            # Fall back to HuggingFace Embeddings
+            return huggingface_embeddings(clean_str, **kwargs)
+
+    raise ValueError(f"Unsupported embedding specification: {target!r}")
+
+
+__all__ = [
+    "EmbeddingModelRegistry",
+    "fastembed",
+    "huggingface_embeddings",
+    "minilm",
+    "ollama_embeddings",
+    "openai_embeddings",
+    "resolve_embedding",
+]

synapse/export/__init__.py

@@ -0,0 +1,14 @@
+"""Synapse exporters for Model Context Protocol (MCP) schemas and 3D knowledge graphs."""
+
+from synapse.export.mcp_exporter import MCPExporter, mcpexporter
+from synapse.storage.graph_exporter import GraphExporter
+
+# Developer-friendly alias
+graphexporter = GraphExporter
+
+__all__ = [
+    "GraphExporter",
+    "MCPExporter",
+    "graphexporter",
+    "mcpexporter",
+]

synapse/export/mcp_exporter.py

@@ -0,0 +1,202 @@
+"""MCP (Model Context Protocol) tool schema, server runner, and configuration exporter."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+try:
+    from mcp.server.mcpserver import MCPServer
+except ImportError:
+    MCPServer = None  # type: ignore
+
+
+class MCPExporter:
+    """Exports Synapse connectors and tools to standard MCP schemas, client configs, and stdio servers."""
+
+    @classmethod
+    def to_tools_list(cls, source: Any) -> list[dict[str, Any]]:
+        """Extracts standard MCP tool definitions from BaseApp or list of connectors."""
+        connectors = cls._resolve_connectors(source)
+        tools_list: list[dict[str, Any]] = []
+
+        for conn in connectors:
+            c_name = getattr(conn, "name", "custom_mcp")
+            c_desc = getattr(conn, "description", "")
+            raw_tools = (
+                getattr(conn, "tools", None)
+                or getattr(conn, "tools_dict", None)
+                or {}
+            )
+
+            if isinstance(raw_tools, dict) and raw_tools:
+                for t_name, t_func in raw_tools.items():
+                    doc = getattr(t_func, "__doc__", "") or f"{t_name} tool provided by {c_name}"
+                    tools_list.append({
+                        "name": f"{c_name}_{t_name}" if c_name not in t_name else t_name,
+                        "description": doc.strip(),
+                        "server": c_name,
+                        "inputSchema": {
+                            "type": "object",
+                            "properties": {
+                                "query": {"type": "string", "description": "Search query or input parameter"}
+                            },
+                        },
+                    })
+            elif hasattr(conn, "default_tool") and conn.default_tool:
+                tools_list.append({
+                    "name": f"{c_name}_{conn.default_tool}",
+                    "description": c_desc or f"Tool for {c_name}",
+                    "server": c_name,
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "query": {"type": "string", "description": "Search query or input parameter"}
+                        },
+                    },
+                })
+
+        return tools_list
+
+    @classmethod
+    def create_mcp_server(
+        cls,
+        source: Any,
+        name: str | None = None,
+    ) -> Any:
+        """Instantiates an official `mcp.server.mcpserver.MCPServer` wired with connector tools."""
+        if MCPServer is None:
+            raise ImportError(
+                "The 'mcp' package is required to create an MCP server. "
+                "Install it with: pip install 'mcp>=2.3.0'"
+            )
+
+        server_name = name or getattr(source, "title", getattr(source, "name", "synapse"))
+        server = MCPServer(name=server_name)
+
+        connectors = cls._resolve_connectors(source)
+        for conn in connectors:
+            c_name = getattr(conn, "name", "tool")
+            raw_tools = (
+                getattr(conn, "tools", None)
+                or getattr(conn, "tools_dict", None)
+                or {}
+            )
+
+            if isinstance(raw_tools, dict) and raw_tools:
+                for t_name, t_func in raw_tools.items():
+                    doc = getattr(t_func, "__doc__", "") or f"Execute {t_name} via {c_name}"
+                    t_alias = f"{c_name}_{t_name}" if c_name not in t_name else t_name
+                    server.add_tool(t_func, name=t_name, description=doc.strip())
+                    if t_alias != t_name:
+                        try:
+                            server.add_tool(t_func, name=t_alias, description=doc.strip())
+                        except Exception:
+                            pass  # nosec B110
+            elif hasattr(conn, "call_tool"):
+                default_t = getattr(conn, "default_tool", "search")
+                doc = getattr(conn, "description", f"Search {c_name}")
+
+                def _make_adapter(c_instance: Any, t_action: str, doc_str: str) -> Callable[..., Any]:
+                    async def dynamic_tool(query: str = "", **kwargs: Any) -> str:
+                        args = {"query": query, **kwargs} if query else kwargs
+                        res = await c_instance.call_tool(t_action, args)
+                        if isinstance(res, (dict, list)):
+                            return json.dumps(res, indent=2)
+                        return str(res)
+
+                    dynamic_tool.__name__ = f"{c_instance.name}_{t_action}"
+                    dynamic_tool.__doc__ = doc_str
+                    return dynamic_tool
+
+                adapter = _make_adapter(conn, default_t, doc)
+                server.add_tool(adapter, name=f"{c_name}_{default_t}", description=doc)
+
+        return server
+
+    @classmethod
+    def run_stdio(
+        cls,
+        source: Any,
+        name: str | None = None,
+    ) -> None:
+        """Runs the MCP server over standard I/O (stdio) for Claude Desktop or Cursor."""
+        server = cls.create_mcp_server(source, name=name)
+        server.run(transport="stdio")
+
+    @classmethod
+    def to_claude_desktop_config(
+        cls,
+        source: Any,
+        server_name: str = "synapse",
+        python_path: str | None = None,
+        args: list[str] | None = None,
+        host: str = "127.0.0.1",
+        port: int = 8000,
+    ) -> dict[str, Any]:
+        """Generates standard claude_desktop_config.json configuration for Claude Desktop."""
+        cmd = python_path or sys.executable or "python3"
+        run_args = args or ["-m", "synapse.cli", "mcp"]
+        return {
+            "mcpServers": {
+                server_name: {
+                    "command": cmd,
+                    "args": run_args,
+                    "env": {
+                        "SYNAPSE_HOST": host,
+                        "SYNAPSE_PORT": str(port),
+                    },
+                }
+            }
+        }
+
+    @classmethod
+    def to_json(cls, source: Any, indent: int = 2) -> str:
+        """Serializes all tool schemas and server definitions into a JSON string."""
+        payload = {
+            "mcpServers": cls.to_claude_desktop_config(source)["mcpServers"],
+            "tools": cls.to_tools_list(source),
+        }
+        return json.dumps(payload, indent=indent)
+
+    @classmethod
+    def save_claude_desktop_config(
+        cls,
+        source: Any,
+        filepath: str | Path = "claude_desktop_config.json",
+        server_name: str = "synapse",
+    ) -> Path:
+        """Writes Claude Desktop configuration file to disk."""
+        target = Path(filepath)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        config = cls.to_claude_desktop_config(source, server_name=server_name)
+        target.write_text(json.dumps(config, indent=2), encoding="utf-8")
+        return target
+
+    @staticmethod
+    def _resolve_connectors(source: Any) -> list[Any]:
+        """Extracts connector objects from BaseApp, lists, or single connector instances."""
+        if hasattr(source, "list_connectors"):
+            return source.list_connectors()
+        if hasattr(source, "_connectors"):
+            return list(source._connectors.values())
+        if isinstance(source, (list, tuple)):
+            return list(source)
+        if isinstance(source, dict):
+            return list(source.values())
+        if (
+            hasattr(source, "call_tool")
+            or hasattr(source, "tools_dict")
+            or hasattr(source, "default_tool")
+        ):
+            return [source]
+        return []
+
+
+# Developer-friendly alias
+mcpexporter = MCPExporter
+
+__all__ = ["MCPExporter", "mcpexporter"]

synapse/graph/__init__.py

@@ -0,0 +1,21 @@
+"""Pluggable knowledge graph backends for Synapse."""
+
+from synapse.graph.base import BaseGraphStore
+from synapse.graph.memory import InMemoryGraph, in_memory_graph
+from synapse.graph.neo4j_store import Neo4jGraph, neo4j
+from synapse.graph.networkx_store import PALETTE, NetworkXGraph, networkx
+
+# Backwards compatible alias
+PersistentGraphStore = NetworkXGraph
+
+__all__ = [
+    "PALETTE",
+    "BaseGraphStore",
+    "InMemoryGraph",
+    "Neo4jGraph",
+    "NetworkXGraph",
+    "PersistentGraphStore",
+    "in_memory_graph",
+    "neo4j",
+    "networkx",
+]