synapse-framework 0.2.4__py3-none-any.whl

synapse/connectors/photos.py

@@ -0,0 +1,141 @@
+"""Google Photos connector for the Synapse framework."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from synapse.connectors.base import BaseConnector
+from synapse.oauth.google import GoogleOAuthService
+
+PHOTOS_READONLY_SCOPE = (
+    "https://www.googleapis.com/auth/photoslibrary.readonly"
+)
+
+
+class GooglePhotosConnector(BaseConnector):
+    """Google Photos connector for searching and referencing photo media items.
+
+    Attributes:
+        oauth: Reusable GoogleOAuthService managing Google Photos scopes.
+    """
+
+    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 GooglePhotosConnector.
+
+        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="photos",
+            description="Google Photos media library, photos, albums, and image metadata",
+            intent_regex=(
+                r"\b(photo|photos|image|images|picture|pictures|album|albums|"
+                r"snapshot|snapshots|gallery|google\s+photos)\b"
+            ),
+            default_tool="search_photos",
+        )
+
+        active_scopes = list(scopes or [PHOTOS_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:
+        """Checks if a valid OAuth token exists for Google Photos."""
+        return self.oauth.is_authenticated()
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """Returns the Google Photos tool schemas."""
+        return [
+            {
+                "server": self.name,
+                "name": "search_photos",
+                "description": "Search photos and media items in user's Google Photos library.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "default": "",
+                            "description": "Optional search filter or category description.",
+                        },
+                        "max_results": {
+                            "type": "integer",
+                            "default": 10,
+                            "description": "Maximum number of photos to return.",
+                        },
+                    },
+                },
+            }
+        ]
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Executes a Google Photos tool."""
+        args = arguments or {}
+        if tool_name == "search_photos":
+            query = str(args.get("query", ""))
+            max_results = int(args.get("max_results", 10))
+            return self.search_photos(query=query, max_results=max_results)
+        raise ValueError(
+            f"Unknown tool '{tool_name}' for connector '{self.name}'"
+        )
+
+    def search_photos(
+        self,
+        query: str = "",
+        max_results: int = 10,
+    ) -> list[dict[str, Any]]:
+        """Searches media items via Google Photos Library API."""
+        if not self.is_authenticated():
+            return []
+
+        try:
+            service = self.oauth.get_service(
+                api_name="photoslibrary",
+                version="v1",
+                scopes=[PHOTOS_READONLY_SCOPE],
+            )
+            body: dict[str, Any] = {"pageSize": max(1, min(max_results, 50))}
+            response = service.mediaItems().search(body=body).execute()
+            items = response.get("mediaItems", [])
+
+            results: list[dict[str, Any]] = []
+            for item in items:
+                results.append({
+                    "id": item.get("id", ""),
+                    "title": item.get("filename", "Photo"),
+                    "url": item.get("productUrl", ""),
+                    "mime_type": item.get("mimeType", ""),
+                    "date": (
+                        item.get("mediaMetadata", {}).get("creationTime", "")
+                    ),
+                    "description": item.get("description", ""),
+                    "type": "Photo",
+                })
+            return results
+        except Exception:
+            return []
+
+
+# Developer-friendly alias matching user request
+GooglePhotosConnectors = GooglePhotosConnector

synapse/database/__init__.py

@@ -0,0 +1,19 @@
+"""Pluggable vector database backends for Synapse."""
+
+from synapse.database.base import BaseVectorDB
+from synapse.database.chroma import ChromaDB, chromadb
+from synapse.database.memory import InMemoryDB, in_memory
+from synapse.database.pgvector import PGVectorDB, pgvector
+from synapse.database.qdrant import QdrantDB, qdrant
+
+__all__ = [
+    "BaseVectorDB",
+    "ChromaDB",
+    "InMemoryDB",
+    "PGVectorDB",
+    "QdrantDB",
+    "chromadb",
+    "in_memory",
+    "pgvector",
+    "qdrant",
+]

synapse/database/base.py

@@ -0,0 +1,63 @@
+"""Abstract base interface for pluggable vector databases in Synapse."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from langchain_core.documents import Document
+
+
+class BaseVectorDB(ABC):
+    """Abstract interface that all Synapse vector database backends must implement.
+
+    Ensures seamless interchangeability between local ChromaDB, in-memory storage,
+    Qdrant, pgvector, or remote hosted vector databases.
+    """
+
+    @abstractmethod
+    def add_documents(
+        self,
+        documents: list[Document],
+        embeddings: list[list[float]] | None = None,
+    ) -> list[str]:
+        """Upserts a list of LangChain Document objects into the vector database.
+
+        Args:
+            documents: List of Document instances with page_content and metadata.
+            embeddings: Optional precomputed vector embeddings.
+
+        Returns:
+            List of generated or assigned document ID strings.
+        """
+
+    @abstractmethod
+    def similarity_search(
+        self,
+        query: str,
+        k: int = 4,
+        filter_dict: dict[str, Any] | None = None,
+        query_embedding: list[float] | None = None,
+    ) -> list[Document]:
+        """Performs semantic similarity search for a query string.
+
+        Args:
+            query: Natural language query string.
+            k: Maximum number of nearest neighbors to return.
+            filter_dict: Optional metadata filter dictionary.
+            query_embedding: Optional precomputed query embedding vector.
+
+        Returns:
+            List of top-k closest Document instances.
+        """
+
+    @abstractmethod
+    def count(self) -> int:
+        """Returns the total number of document chunks currently indexed."""
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Clears all records in the collection/index."""
+
+
+__all__ = ["BaseVectorDB"]

synapse/database/chroma.py

@@ -0,0 +1,175 @@
+"""ChromaDB vector database provider for Synapse."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import chromadb as native_chromadb
+from langchain_chroma import Chroma
+from langchain_core.documents import Document
+
+from synapse.config import (
+    DEFAULT_CHROMA_COLLECTION,
+    DEFAULT_CHROMA_DIR,
+)
+from synapse.database.base import BaseVectorDB
+from synapse.embeddings import resolve_embedding
+
+
+class ChromaDB(BaseVectorDB):
+    """ChromaDB vector database adapter supporting local disk, in-memory, or remote HTTP."""
+
+    def __init__(
+        self,
+        path: str | Path | None = None,
+        host: str | None = None,
+        port: int | None = None,
+        ssl: bool = False,
+        headers: dict[str, str] | None = None,
+        in_memory: bool = False,
+        collection_name: str = DEFAULT_CHROMA_COLLECTION,
+        embedding: str | Any | None = None,
+        embedding_model: str | None = None,
+        embedding_function: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initializes ChromaDB adapter.
+
+        Args:
+            path: Local storage path. If ':memory:' or in_memory=True, runs purely in RAM.
+            host: Hostname for online/remote ChromaDB server (e.g. 'localhost' or 'api.chroma.io').
+            port: Port for remote ChromaDB server (e.g. 8000).
+            ssl: Whether to use HTTPS for remote ChromaDB server.
+            headers: Optional HTTP headers for remote ChromaDB server (e.g. auth tokens).
+            in_memory: If True, operates in ephemeral RAM with zero disk writes.
+            collection_name: ChromaDB collection name. Defaults to 'synapse_memory'.
+            embedding: Embedding model name ('fastembed', 'minilm', 'openai', etc.) or Embeddings object.
+            embedding_model: Backward-compatible alias for embedding model name.
+            embedding_function: Optional custom embedding function.
+            **kwargs: Extra parameters forwarded to the embedding resolver.
+        """
+        self.collection_name = collection_name
+        self.embedding_function = resolve_embedding(
+            embedding=embedding or embedding_function or embedding_model,
+            **kwargs,
+        )
+
+        if host is not None:
+            # Online / remote ChromaDB server
+            self.client = native_chromadb.HttpClient(
+                host=host,
+                port=port or 8000,
+                ssl=ssl,
+                headers=headers,
+            )
+        elif in_memory or path == ":memory:":
+            # Pure in-memory ephemeral client (0 disk writes)
+            self.client = native_chromadb.EphemeralClient()
+        else:
+            # Local persistent on-disk ChromaDB
+            resolved_path = Path(path or DEFAULT_CHROMA_DIR).resolve()
+            resolved_path.mkdir(parents=True, exist_ok=True)
+            self.client = native_chromadb.PersistentClient(path=str(resolved_path))
+
+        self.store = Chroma(
+            client=self.client,
+            collection_name=collection_name,
+            embedding_function=self.embedding_function,
+        )
+
+    def add_documents(
+        self,
+        documents: list[Document],
+        embeddings: list[list[float]] | None = None,
+    ) -> list[str]:
+        """Upserts documents into ChromaDB."""
+        if not documents:
+            return []
+
+        ids: list[str] | None = None
+        has_chunk_ids = all("chunk_id" in doc.metadata for doc in documents)
+        if has_chunk_ids:
+            ids = [str(doc.metadata["chunk_id"]) for doc in documents]
+
+        return self.store.add_documents(documents=documents, ids=ids)
+
+    def similarity_search(
+        self,
+        query: str,
+        k: int = 4,
+        filter_dict: dict[str, Any] | None = None,
+        query_embedding: list[float] | None = None,
+    ) -> list[Document]:
+        """Performs semantic search in ChromaDB."""
+        return self.store.similarity_search(query=query, k=k, filter=filter_dict)
+
+    def count(self) -> int:
+        """Returns total document count in the collection."""
+        try:
+            col = self.client.get_collection(self.collection_name)
+            return col.count()
+        except Exception:
+            return 0
+
+    def clear(self) -> None:
+        """Deletes and recreates the collection."""
+        try:
+            self.client.delete_collection(self.collection_name)
+        except Exception:
+            pass  # nosec B110
+        self.store = Chroma(
+            client=self.client,
+            collection_name=self.collection_name,
+            embedding_function=self.embedding_function,
+        )
+
+
+def chromadb(
+    path: str | Path | None = None,
+    host: str | None = None,
+    port: int | None = None,
+    ssl: bool = False,
+    headers: dict[str, str] | None = None,
+    in_memory: bool = False,
+    collection_name: str = DEFAULT_CHROMA_COLLECTION,
+    embedding: str | Any | None = None,
+    embedding_model: str | None = None,
+    embedding_function: Any | None = None,
+    **kwargs: Any,
+) -> ChromaDB:
+    """Factory helper to configure a ChromaDB vector database instance.
+
+    Example:
+        ```python
+        from synapse.database import chromadb
+        from synapse.storage import vectorStorage
+
+        # Local persistent with MiniLM:
+        db = chromadb("data/chroma_db", embedding="minilm")
+
+        # In-memory ephemeral with FastEmbed BGE:
+        db = chromadb(in_memory=True, embedding="fastembed")
+
+        # Online remote server with OpenAI embeddings:
+        db = chromadb(host="my-chroma.internal", port=8000, embedding="openai")
+
+        storage = vectorStorage(database=db)
+        ```
+    """
+    return ChromaDB(
+        path=path,
+        host=host,
+        port=port,
+        ssl=ssl,
+        headers=headers,
+        in_memory=in_memory,
+        collection_name=collection_name,
+        embedding=embedding,
+        embedding_model=embedding_model,
+        embedding_function=embedding_function,
+        **kwargs,
+    )
+
+
+__all__ = ["ChromaDB", "chromadb"]

synapse/database/memory.py

@@ -0,0 +1,132 @@
+"""Pure in-memory vector database backend with zero disk dependencies."""
+
+from __future__ import annotations
+
+import math
+import uuid
+from typing import Any, Union
+
+from langchain_core.documents import Document
+
+from synapse.database.base import BaseVectorDB
+from synapse.embeddings import resolve_embedding
+
+
+class InMemoryDB(BaseVectorDB):
+    """Pure in-memory vector database using cosine similarity in RAM."""
+
+    def __init__(
+        self,
+        embedding: Union[str, Any] | None = None,
+        embedding_model: str | None = None,
+        embedding_function: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initializes the in-memory vector database."""
+        self.embedding_function = resolve_embedding(
+            embedding=embedding or embedding_function or embedding_model,
+            **kwargs,
+        )
+        self._entries: list[tuple[str, list[float], Document]] = []
+
+    def _cosine_similarity(self, a: list[float], b: list[float]) -> float:
+        """Calculates cosine similarity between two vector embeddings."""
+        dot = sum(x * y for x, y in zip(a, b))
+        norm_a = math.sqrt(sum(x * x for x in a))
+        norm_b = math.sqrt(sum(y * y for y in b))
+        if norm_a == 0.0 or norm_b == 0.0:
+            return 0.0
+        return dot / (norm_a * norm_b)
+
+    def add_documents(
+        self,
+        documents: list[Document],
+        embeddings: list[list[float]] | None = None,
+    ) -> list[str]:
+        """Upserts documents into memory."""
+        if not documents:
+            return []
+
+        texts = [doc.page_content for doc in documents]
+        vecs = embeddings or self.embedding_function.embed_documents(texts)
+        assigned_ids: list[str] = []
+
+        for doc, vec in zip(documents, vecs):
+            doc_id = str(doc.metadata.get("chunk_id") or uuid.uuid4())
+            # Replace if same ID exists
+            self._entries = [e for e in self._entries if e[0] != doc_id]
+            self._entries.append((doc_id, vec, doc))
+            assigned_ids.append(doc_id)
+
+        return assigned_ids
+
+    def similarity_search(
+        self,
+        query: str,
+        k: int = 4,
+        filter_dict: dict[str, Any] | None = None,
+        query_embedding: list[float] | None = None,
+    ) -> list[Document]:
+        """Performs nearest-neighbor search in RAM using cosine similarity."""
+        if not self._entries:
+            return []
+
+        q_vec = query_embedding or self.embedding_function.embed_query(query)
+        scored: list[tuple[float, Document]] = []
+
+        for _, vec, doc in self._entries:
+            # Check optional metadata filter
+            if filter_dict:
+                match = all(
+                    doc.metadata.get(kf) == vf for kf, vf in filter_dict.items()
+                )
+                if not match:
+                    continue
+
+            score = self._cosine_similarity(q_vec, vec)
+            scored.append((score, doc))
+
+        # Sort descending by cosine similarity score
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [doc for _, doc in scored[:k]]
+
+    def count(self) -> int:
+        """Returns the number of documents stored in RAM."""
+        return len(self._entries)
+
+    def clear(self) -> None:
+        """Clears all in-memory entries."""
+        self._entries.clear()
+
+
+def in_memory(
+    embedding: Union[str, Any] | None = None,
+    embedding_model: str | None = None,
+    embedding_function: Any | None = None,
+    **kwargs: Any,
+) -> InMemoryDB:
+    """Factory helper creating an ephemeral in-memory vector database.
+
+    Example:
+        ```python
+        from synapse.database import in_memory
+        from synapse.storage import vectorStorage
+
+        # In-memory with MiniLM:
+        db = in_memory(embedding="minilm")
+
+        # In-memory with FastEmbed BGE:
+        db = in_memory(embedding="fastembed")
+
+        storage = vectorStorage(database=db)
+        ```
+    """
+    return InMemoryDB(
+        embedding=embedding,
+        embedding_model=embedding_model,
+        embedding_function=embedding_function,
+        **kwargs,
+    )
+
+
+__all__ = ["InMemoryDB", "in_memory"]

synapse/database/pgvector.py

@@ -0,0 +1,99 @@
+"""PostgreSQL PGVector 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 PGVectorDB(BaseVectorDB):
+    """PostgreSQL pgvector database adapter for enterprise deployments."""
+
+    def __init__(
+        self,
+        connection_string: str,
+        collection_name: str = "synapse_embeddings",
+        embedding: Union[str, Any] | None = None,
+        embedding_model: str | None = None,
+        embedding_function: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.connection_string = connection_string
+        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 PGVector
+
+            self.store = PGVector(
+                connection_string=connection_string,
+                collection_name=collection_name,
+                embedding_function=self.embedding_function,
+            )
+        except ImportError:
+            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:
+            return 0
+        return self._fallback.count()
+
+    def clear(self) -> None:
+        if self.store:
+            pass
+        else:
+            self._fallback.clear()
+
+
+def pgvector(
+    connection_string: str,
+    collection_name: str = "synapse_embeddings",
+    embedding: Union[str, Any] | None = None,
+    embedding_model: str | None = None,
+    embedding_function: Any | None = None,
+    **kwargs: Any,
+) -> PGVectorDB:
+    """Factory helper to configure a PostgreSQL PGVector database instance."""
+    return PGVectorDB(
+        connection_string=connection_string,
+        collection_name=collection_name,
+        embedding=embedding,
+        embedding_model=embedding_model,
+        embedding_function=embedding_function,
+        **kwargs,
+    )
+
+
+__all__ = ["PGVectorDB", "pgvector"]