synapse-framework 0.2.4__py3-none-any.whl

synapse/storage/graph_store.py

@@ -0,0 +1,162 @@
+"""Persistent directed knowledge graph storage backed by NetworkX and JSON."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import networkx as nx
+
+from synapse.config import DEFAULT_GRAPH_FILE, DESIGN_TOKENS
+from synapse.graph.networkx_store import NetworkXGraph
+
+PALETTE: dict[str, str] = DESIGN_TOKENS["palettes"]["zinc"]
+
+
+class PersistentGraphStore(NetworkXGraph):
+    """Manages a persistent directed graph of entities and relations."""
+
+    def __init__(self, filepath: str | Path | None = None) -> None:
+        """Initializes the graph store from a persistent JSON file."""
+        super().__init__(filepath=filepath or DEFAULT_GRAPH_FILE)
+
+    def add_node_entity(
+        self,
+        name: str,
+        entity_type: str = "Default",
+        color: str | None = None,
+        attributes: dict[str, Any] | None = None,
+    ) -> None:
+        """Adds or updates an entity node in the graph."""
+        clean_name = name.strip()
+        if not clean_name:
+            return
+
+        assigned_color = color or self.palette.get(
+            entity_type, self.palette["Default"]
+        )
+        node_data: dict[str, Any] = {
+            "name": clean_name,
+            "type": entity_type,
+            "color": assigned_color,
+        }
+        if attributes:
+            node_data.update(attributes)
+
+        if self.graph.has_node(clean_name):
+            self.graph.nodes[clean_name].update(node_data)
+        else:
+            self.graph.add_node(clean_name, **node_data)
+
+        self.save()
+
+    def add_relation(
+        self,
+        source: str,
+        relation: str,
+        target: str,
+        source_type: str = "Default",
+        target_type: str = "Default",
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Creates a directed relation edge between source and target entities."""
+        clean_source = source.strip()
+        clean_target = target.strip()
+        clean_rel = relation.strip().upper()
+
+        if not clean_source or not clean_target:
+            return
+
+        if not self.graph.has_node(clean_source):
+            self.add_node_entity(clean_source, entity_type=source_type)
+        if not self.graph.has_node(clean_target):
+            self.add_node_entity(clean_target, entity_type=target_type)
+
+        edge_data: dict[str, Any] = {"relation": clean_rel}
+        if metadata:
+            edge_data.update(metadata)
+
+        self.graph.add_edge(clean_source, clean_target, **edge_data)
+        self.save()
+
+    def find_relation_for(self, entity_name: str) -> list[str]:
+        """Retrieves incoming and outgoing relational facts for an entity."""
+        clean_entity = entity_name.strip()
+        facts: list[str] = []
+
+        if not self.graph.has_node(clean_entity):
+            return facts
+
+        for neighbor in self.graph.successors(clean_entity):
+            edge_data = self.graph.get_edge_data(clean_entity, neighbor) or {}
+            rel = edge_data.get("relation", "CONNECTED_TO")
+            facts.append(f"{clean_entity} -> {rel} -> {neighbor}")
+
+        for neighbor in self.graph.predecessors(clean_entity):
+            edge_data = self.graph.get_edge_data(neighbor, clean_entity) or {}
+            rel = edge_data.get("relation", "CONNECTED_TO")
+            facts.append(f"{neighbor} -> {rel} -> {clean_entity}")
+
+        return facts
+
+    def get_3d_payload(self) -> dict[str, Any]:
+        """Serializes the graph into 3D Force-Graph nodes and links."""
+        nodes: list[dict[str, Any]] = []
+        for node_id, data in self.graph.nodes(data=True):
+            node_type = data.get("type", "Default")
+            color = data.get(
+                "color", self.palette.get(node_type, self.palette["Default"])
+            )
+            degree = self.graph.degree(node_id)
+            node_size = max(3, min(14, degree * 2))
+
+            nodes.append({
+                "id": str(node_id),
+                "name": str(node_id),
+                "type": node_type,
+                "color": color,
+                "val": node_size,
+                "attributes": {
+                    k: v
+                    for k, v in data.items()
+                    if k not in ["type", "color", "name"]
+                },
+            })
+
+        links: list[dict[str, Any]] = []
+        for u, v, data in self.graph.edges(data=True):
+            links.append({
+                "source": str(u),
+                "target": str(v),
+                "relation": data.get("relation", "CONNECTED_TO"),
+            })
+
+        return {"nodes": nodes, "links": links}
+
+    def load(self) -> None:
+        """Loads graph data from JSON file on disk."""
+        if os.path.exists(self.filepath):
+            try:
+                with open(self.filepath, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                    if "edges" in data and "links" not in data:
+                        data["links"] = data.pop("edges")
+                    self.graph = nx.node_link_graph(data, directed=True)
+            except Exception:
+                self.graph = nx.DiGraph()
+
+    def save(self) -> None:
+        """Saves current graph to disk."""
+        self.filepath.parent.mkdir(parents=True, exist_ok=True)
+        data = nx.node_link_data(self.graph)
+        with open(self.filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+    def get_stats(self) -> dict[str, int]:
+        """Returns node and edge counts."""
+        return {
+            "total_nodes": self.graph.number_of_nodes(),
+            "total_edges": self.graph.number_of_edges(),
+        }

synapse/storage/vector_store.py

@@ -0,0 +1,103 @@
+"""Pluggable persistent and in-memory vector storage for Synapse."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from langchain_core.documents import Document
+
+from synapse.config import (
+    DEFAULT_CHROMA_COLLECTION,
+    DEFAULT_CHROMA_DIR,
+)
+from synapse.database.base import BaseVectorDB
+from synapse.database.chroma import ChromaDB
+
+
+class VectorStorage:
+    """Universal vector storage container wrapping pluggable database backends.
+
+    Example:
+        ```python
+        from synapse.database import chromadb, in_memory
+        from synapse.storage import vectorStorage
+
+        # With persistent ChromaDB:
+        storage = vectorStorage(database=chromadb("data/chroma_db"))
+
+        # With pure in-memory database:
+        storage = vectorStorage(database=in_memory())
+
+        # With remote online ChromaDB:
+        storage = vectorStorage(database=chromadb(host="localhost", port=8000))
+        ```
+    """
+
+    def __init__(
+        self,
+        database: BaseVectorDB | None = None,
+        persist_dir: str | Path | None = None,
+        collection_name: str = DEFAULT_CHROMA_COLLECTION,
+        embedding: str | Any | None = None,
+        embedding_model: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initializes the VectorStorage container.
+
+        Args:
+            database: Optional BaseVectorDB instance (e.g. chromadb(), in_memory(), qdrant()).
+            persist_dir: Optional filesystem path for local ChromaDB if database not provided.
+            collection_name: 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.
+            **kwargs: Extra database parameters.
+        """
+        if database is not None:
+            self.database = database
+        else:
+            # Default to ChromaDB backend
+            target_path = persist_dir or DEFAULT_CHROMA_DIR
+            self.database = ChromaDB(
+                path=target_path,
+                collection_name=collection_name,
+                embedding=embedding,
+                embedding_model=embedding_model,
+                **kwargs,
+            )
+
+    def add_documents(self, documents: list[Document]) -> list[str]:
+        """Upserts documents into the underlying database."""
+        return self.database.add_documents(documents)
+
+    def similarity_search(
+        self,
+        query: str,
+        k: int = 4,
+        filter_dict: dict[str, Any] | None = None,
+    ) -> list[Document]:
+        """Performs nearest-neighbor semantic search."""
+        return self.database.similarity_search(query=query, k=k, filter_dict=filter_dict)
+
+    def count(self) -> int:
+        """Returns the total number of document chunks currently indexed."""
+        return self.database.count()
+
+    def clear(self) -> None:
+        """Clears all indexed records."""
+        self.database.clear()
+
+
+# Developer-friendly alias matching user specification
+vectorStorage = VectorStorage
+
+# Backwards-compatible aliases
+LocalVectorStore = VectorStorage
+LocalVectorStorage = VectorStorage
+
+__all__ = [
+    "LocalVectorStorage",
+    "LocalVectorStore",
+    "VectorStorage",
+    "vectorStorage",
+]

synapse_framework-0.2.4.dist-info/METADATA

@@ -0,0 +1,415 @@
+Metadata-Version: 2.4
+Name: synapse-framework
+Version: 0.2.4
+Summary: Modular Multi-MCP & Hybrid RAG AI Application Framework
+Author: Synapse Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AKASH-KUMAR-BARPANDA/synapse-framework
+Project-URL: Repository, https://github.com/AKASH-KUMAR-BARPANDA/synapse-framework
+Project-URL: Issues, https://github.com/AKASH-KUMAR-BARPANDA/synapse-framework/issues
+Keywords: mcp,rag,agents,knowledge-graph,fastapi,claude,cursor,ollama,chromadb,qdrant,networkx,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chromadb>=1.5.9
+Requires-Dist: fastapi[standard]>=0.142.2
+Requires-Dist: fastembed>=0.8.1
+Requires-Dist: google-api-python-client>=2.201.0
+Requires-Dist: google-auth-httplib2>=0.4.4
+Requires-Dist: google-auth-oauthlib>=1.5.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: langchain>=1.4.3
+Requires-Dist: langchain-chroma>=1.1.0
+Requires-Dist: langchain-community>=0.4.2
+Requires-Dist: langchain-core>=1.6.7
+Requires-Dist: langchain-ollama>=1.1.0
+Requires-Dist: matplotlib>=3.11.2
+Requires-Dist: mcp>=2.3.0
+Requires-Dist: networkx>=3.7
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.12.0; extra == "qdrant"
+Provides-Extra: all
+Requires-Dist: qdrant-client>=1.12.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: bandit>=1.9.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pip-audit>=2.8.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: twine>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.png" width="160" height="160" alt="Synapse Logo" style="border-radius: 36px; box-shadow: 0 12px 36px rgba(0,0,0,0.4);"/>
+</p>
+
+<h1 align="center">Synapse</h1>
+
+<p align="center">
+  <b>Modular Multi-MCP & Hybrid RAG AI Application Framework</b>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/synapse-framework/"><img src="https://img.shields.io/pypi/v/synapse-framework.svg?color=6366F1&label=PyPI" alt="PyPI version"/></a>
+  <a href="https://pypi.org/project/synapse-framework/"><img src="https://img.shields.io/pypi/pyversions/synapse-framework.svg?color=06B6D4" alt="Python Versions"/></a>
+  <a href="https://github.com/AKASH-KUMAR-BARPANDA/synapse-framework/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"/></a>
+  <a href="https://github.com/AKASH-KUMAR-BARPANDA/synapse-framework/actions"><img src="https://img.shields.io/badge/tests-23%20passing-success.svg?color=10B981" alt="Tests"/></a>
+  <a href="https://github.com/PyCQA/bandit"><img src="https://img.shields.io/badge/security-bandit%20passed-success.svg?color=10B981" alt="Bandit Security"/></a>
+</p>
+
+<p align="center">
+  <a href="#-quickstart">Quickstart</a> •
+  <a href="#-key-features">Features</a> •
+  <a href="#-interactive-inspector--3d-graph">Inspector & Graph</a> •
+  <a href="#-core-architecture">Architecture</a> •
+  <a href="#-api-endpoint-reference">API Endpoints</a> •
+  <a href="#-claude-desktop--cursor-export">MCP Export</a> •
+  <a href="#-license">License</a>
+</p>
+
+---
+
+**Synapse** is an open-source, local-first Python framework for developing autonomous AI assistants, multi-tool agents, and intelligent backend services. It unifies **Model Context Protocol (MCP)** tool execution, **Hybrid RAG** (vector embeddings combined with directed knowledge graphs), pluggable inference providers (**Ollama**, **Google Gemini**, **OpenAI**), and a real-time developer inspector with an interactive 3D WebGL knowledge visualizer.
+
+---
+
+## ⚡ Key Features
+
+- 🔌 **Dynamic Multi-MCP Tool Orchestration** — Aggregate custom Python functions, external FastMCP servers, and cloud services into schema-validated, discoverable tool sets with automatic LLM tool routing.
+- 🕸️ **Hybrid RAG (Vector + Knowledge Graph)** — Dual-channel retrieval engine pairing semantic vector search (ChromaDB, Qdrant, FastEmbed) with relation-aware multi-hop graph queries (NetworkX, Neo4j).
+- 🧠 **Model Agnostic Inference** — Native support for offline local LLMs via **Ollama** (Qwen 2.5, Llama 3, Mistral) and frontier cloud models (**Google Gemini**, **OpenAI**, Groq, vLLM) with zero lock-in.
+- 📊 **Real-Time Interactive Inspector** — Built-in dashboard at `/inspector` to test prompts, monitor live tool execution traces, inspect retrieved vector chunks, and explore relation facts.
+- 🌐 **3D WebGL Knowledge Graph** — Standalone interactive visualizer at `/graph/export` featuring physics simulations, entity clustering, and real-time relation navigation.
+- 📦 **One-Click MCP Server Export** — Expose your application's tools to Claude Desktop, Cursor, or LibreChat with `synapse export-mcp`.
+- 🛡️ **Zero Vulnerabilities & High Test Coverage** — Clean 100% Bandit security audit, full type annotations, and modern Python 3.10+ async architecture.
+
+---
+
+## 📸 Interactive Inspector & 3D Graph
+
+### 1. Developer Inspector Dashboard (`/inspector`)
+Test chat prompts, observe schema-validated tool invocations in real time, and audit retrieved vector chunks and knowledge graph triples side-by-side:
+
+<p align="center">
+  <img src="assets/inspector_preview.png" width="100%" alt="Synapse Inspector Dashboard" style="border-radius: 12px; border: 1px solid #27272a; box-shadow: 0 8px 24px rgba(0,0,0,0.5);"/>
+</p>
+
+### 2. 3D WebGL Knowledge Graph Explorer (`/graph/export`)
+Navigate and visualize complex entity relationships and multi-hop triples in an interactive 3D physics-based canvas:
+
+<p align="center">
+  <img src="assets/graph_preview.png" width="100%" alt="Synapse 3D Knowledge Graph" style="border-radius: 12px; border: 1px solid #27272a; box-shadow: 0 8px 24px rgba(0,0,0,0.5);"/>
+</p>
+
+### 3. Connector & Sync Manager (`/connectors`)
+Audit connected tools, check authentication status, and trigger on-demand synchronization:
+
+<p align="center">
+  <img src="assets/connectors_preview.png" width="100%" alt="Synapse Connectors View" style="border-radius: 12px; border: 1px solid #27272a; box-shadow: 0 8px 24px rgba(0,0,0,0.5);"/>
+</p>
+
+### 4. Interactive OpenAPI & Swagger Endpoints (`/docs`)
+Explore and test all REST routes, SSE streams, sync triggers, and MCP export endpoints in real time:
+
+<p align="center">
+  <img src="assets/openapi_preview.png" width="100%" alt="Synapse OpenAPI Docs" style="border-radius: 12px; border: 1px solid #27272a; box-shadow: 0 8px 24px rgba(0,0,0,0.5);"/>
+</p>
+
+---
+
+## 🏗️ Core Architecture
+
+```mermaid
+flowchart TD
+    subgraph Clients ["Clients & Interfaces"]
+        UI["Web Inspector (/inspector)"]
+        CLI["Cursor / Claude Desktop (MCP)"]
+        API["REST & SSE Endpoints (/chat)"]
+    end
+
+    subgraph Core ["Synapse BaseApp Engine"]
+        Router["FastAPI Application"]
+        Dispatcher["Tool & Skill Dispatcher"]
+        Context["Execution Tracer"]
+    end
+
+    subgraph LLM ["Model Providers"]
+        OLL["Ollama (Qwen, Llama 3)"]
+        GEM["Google Gemini 1.5 / 2.0"]
+        OAI["OpenAI (GPT-4o, mini)"]
+    end
+
+    subgraph Storage ["Hybrid RAG & Memory"]
+        Vec["Vector Store (ChromaDB / Qdrant)"]
+        Graph["Knowledge Graph (NetworkX / Neo4j)"]
+        Emb["Local Embeddings (FastEmbed / BGE)"]
+    end
+
+    subgraph Tools ["Multi-MCP Connectors"]
+        F1["Custom Tools (makeconnectors)"]
+        F2["OAuth Connectors (Gmail, Notion, Photos)"]
+        F3["External FastMCP Servers"]
+    end
+
+    UI --> Router
+    CLI --> Router
+    API --> Router
+
+    Router --> Dispatcher
+    Dispatcher <--> LLM
+    Dispatcher <--> Storage
+    Dispatcher <--> Tools
+    Dispatcher --> Context
+```
+
+---
+
+## 📦 Installation
+
+Install `synapse-framework` using pip:
+
+```bash
+pip install synapse-framework
+```
+
+Or using `uv`:
+
+```bash
+uv add synapse-framework
+```
+
+### Optional Extras
+
+```bash
+# Add Qdrant vector database support
+pip install "synapse-framework[qdrant]"
+
+# Install all optional drivers and dependencies
+pip install "synapse-framework[all]"
+```
+
+---
+
+## 🚀 60-Second Quickstart
+
+Create an intelligent assistant with custom Python tools, local Ollama inference, and a live web inspector in under 25 lines of code:
+
+```python
+from typing import Dict, Any
+from synapse import BaseApp
+from synapse.models import Ollama
+from synapse.connectors import makeconnectors
+
+# 1. Define custom tools with clear docstrings
+def search_product_catalog(query: str, category: str = "all") -> Dict[str, Any]:
+    """Searches the product database and inventory across warehouses."""
+    return {"results": [{"id": "SKU-992", "name": "Neuro-Link Adapter", "price": 149.0, "stock": 42}]}
+
+def calculate_shipping(weight_kg: float, international: bool = False) -> Dict[str, Any]:
+    """Calculates shipping cost based on package weight and destination."""
+    rate = 14.5 if international else 5.5
+    return {"cost_usd": round(weight_kg * rate, 2), "carrier": "Express Air"}
+
+# 2. Package tools into an MCP connector
+inventory_connector = makeconnectors(
+    name="inventory_service",
+    tools=[search_product_catalog, calculate_shipping],
+)
+
+# 3. Initialize Synapse application
+app = BaseApp(
+    title="Logistics Assistant",
+    model=Ollama(model="qwen2.5:0.5b", base_url="http://localhost:11434"),
+    connectors=[inventory_connector],
+    visualize_graph=True,
+)
+
+if __name__ == "__main__":
+    app.run(host="127.0.0.1", port=8000)
+```
+
+Open your browser to start interacting:
+- 📊 **Web Inspector**: [`http://127.0.0.1:8000/inspector`](http://127.0.0.1:8000/inspector)
+- 🕸️ **3D Knowledge Graph**: [`http://127.0.0.1:8000/graph/export`](http://127.0.0.1:8000/graph/export)
+- 📖 **Interactive OpenAPI Docs**: [`http://127.0.0.1:8000/docs`](http://127.0.0.1:8000/docs)
+
+---
+
+## 🧠 Pluggable Model Providers
+
+Synapse offers unified model abstractions with automatic prompt formatting and tool calling normalization:
+
+### 1. Local Ollama (Offline / Private)
+```python
+from synapse.models import Ollama
+
+model = Ollama(
+    model="qwen2.5:0.5b",
+    base_url="http://localhost:11434",
+    temperature=0.2,
+)
+```
+
+### 2. Google Gemini
+```python
+import os
+from synapse.models import Gemini
+
+model = Gemini(
+    api_key=os.getenv("GEMINI_API_KEY"),
+    model="gemini-1.5-flash",
+)
+```
+
+### 3. OpenAI / Groq / OpenRouter / vLLM
+```python
+import os
+from synapse.models import OpenAI
+
+model = OpenAI(
+    api_key=os.getenv("OPENAI_API_KEY"),
+    model="gpt-4o-mini",
+)
+```
+
+---
+
+## 🔌 Connectors & Custom Tools
+
+### Custom Tools via `makeconnectors`
+Transform any Python functions into a tool connector ready for MCP client consumption:
+
+```python
+from synapse.connectors import makeconnectors
+
+def query_financial_metrics(quarter: str = "Q3") -> dict:
+    """Returns quarterly revenue, operating expenses, and net profit margin."""
+    return {"revenue": 420000, "expenses": 180000, "margin": "57.1%"}
+
+finance_connector = makeconnectors(
+    name="finance_analytics",
+    tools=[query_financial_metrics],
+)
+```
+
+### Prebuilt OAuth Productivity Connectors
+Synapse includes managed OAuth 2.0 lifecycle helpers:
+
+```python
+from synapse.oauth import GoogleOAuthService
+from synapse.connectors import GmailConnectors, GooglePhotosConnectors, NotionConnectors
+
+oauth = GoogleOAuthService(
+    credentials_path="credentials.json",
+    token_path="token.json",
+)
+
+gmail = GmailConnectors(oauth_service=oauth)
+photos = GooglePhotosConnectors(oauth_service=oauth)
+notion = NotionConnectors(api_key="secret_notion_key")
+```
+
+---
+
+## 🕸️ Hybrid RAG & Knowledge Graph
+
+Synapse pairs dense semantic similarity with relational graph reasoning:
+
+```python
+from synapse.storage import PersistentGraphStore, VectorStore
+from synapse.rag import HybridRAG
+
+# 1. Initialize persistent storage layers
+graph_store = PersistentGraphStore(filepath="./data/graph.json")
+vector_store = VectorStore(persist_dir="./data/chroma_db")
+
+# 2. Add relational facts to knowledge graph
+graph_store.add_relation("Alice", "LEADS", "Platform Engineering", source_type="Person", target_type="Organization")
+graph_store.add_relation("Platform Engineering", "MAINTAINS", "Synapse Framework", source_type="Organization", target_type="Project")
+
+# 3. Query combined knowledge base
+rag = HybridRAG(vector_store=vector_store, graph_store=graph_store)
+result = rag.retrieve_context("What does Alice lead?")
+
+print("Entities found:", result["entities_detected"])
+print("Graph facts:", result["graph_facts"])
+```
+
+---
+
+## 🌐 API Endpoint Reference
+
+Synapse automatically mounts standard REST, Server-Sent Events (SSE), and documentation endpoints on your application:
+
+| Method | Endpoint | Tag | Description |
+| :--- | :--- | :--- | :--- |
+| `GET` | **`/`** or **`/inspector`** | `Inspector` | Interactive Web Inspector dashboard for chat, trace inspection, and tools. |
+| `POST` | **`/chat`** | `Chat` | Server-Sent Events (SSE) streaming endpoint for agent prompts, tool calls, and grounded replies. |
+| `GET` | **`/graph/export`** | `Graph` | Full-screen interactive 3D WebGL knowledge graph visualizer. |
+| `GET` | **`/graph/data`** | `Graph` | JSON payload containing all graph nodes, directed links, color tokens, and stats. |
+| `GET` | **`/connectors`** | `Sync` | Lists all registered connectors, descriptions, and active tools. |
+| `POST` | **`/sync/{connector_name}`** | `Sync` | Triggers background synchronization and indexing for a specific connector. |
+| `GET` | **`/sync/status`** | `Sync` | Returns current synchronization progress, item counts, and timestamps. |
+| `GET` | **`/mcp/export`** | `MCP` | Exports active tools into Claude Desktop config format and FastMCP manifests. |
+| `GET` | **`/skills`** | `Skills` | Returns registered agent skills and specialized system instructions. |
+| `GET` | **`/resources`** | `Resources` | Lists static reference documents and indexed data resources. |
+| `GET` | **`/info`** | `Inspector` | Overview of running model provider, connector count, and framework version. |
+| `GET` | **`/health`** | `System` | Health check endpoint returning status and uptime. |
+| `GET` | **`/docs`** | `Docs` | Interactive Swagger / OpenAPI documentation with try-it-out capabilities. |
+
+---
+
+## 🛠️ Claude Desktop & Cursor Export
+
+Export your application tools directly to Claude Desktop or Cursor:
+
+```bash
+# Export config file
+synapse export-mcp --output claude_desktop_config.json
+```
+
+Add the configuration block into your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "synapse": {
+      "command": "python",
+      "args": ["-m", "synapse.export.mcp_server", "--port", "8000"]
+    }
+  }
+}
+```
+
+---
+
+## 🧪 Testing & Code Quality
+
+Synapse is built with strict code quality and security verification:
+
+```bash
+# Run pytest test suite (23 unit tests)
+pytest tests/
+
+# Run security static analysis (0 vulnerabilities)
+bandit -r synapse
+
+# Check code formatting and modern standards
+ruff check synapse/
+```
+
+---
+
+## 📄 License
+
+Synapse is licensed under the [MIT License](LICENSE).