synapse-framework 0.2.4__tar.gz

synapse_framework-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synapse Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synapse_framework-0.2.4/PKG-INFO

@@ -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).