Synapse is a generic, modular framework for building Autonomous AI Agents specialized in Operations and Site Reliability Engineering (SRE).
Built on top of Microsoft Semantic Kernel, Synapse is vendor-agnostic and supports multiple LLM providers (Gemini, OpenAI, Anthropic). It provides the "Core Engine" to decouple intelligent reasoning from native code execution, allowing developers to spin up agents that can plan, execute tools, and retrieve knowledge for any domain.
Synapse implements the ReAct (Reasoning + Acting) pattern. It separates the "Brain" (LLM) from the "Hands" (Native Code).
In Synapse, Functions are the specific tools available to the system, while the Agent (the Planner) is the entity that decides which tools to use and in what order.
+-----------------------------------------------------------------------+
| THE KERNEL (Orchestrator) |
| |
| +-------------------------------------+ +---------------------+ |
| | PLUGIN REGISTRY | | AI SERVICES | |
| | (Where Functions are Stored) | | (The "Brain") | |
| | | | | |
| | [Plugin: SystemMonitor] | | [Gemini Flash] | |
| | ├── Function: get_cpu_usage |<--|--> (LLM) | |
| | └── Function: check_disk_space | | | |
| | | +---------------------+ |
| | [Plugin: TechSupport] | |
| | └── Function: search_manuals | +---------------------+ |
| | (Semantic/Vector Search) | | MATHEMATICAL RANKING| |
| +-------------------------------------+ | | |
| | • BM25 Scorer | |
| +-------------------------------------+ | • PageRank Calc | |
| | FUNCTION REGISTRY | | • Thompson Sampling | |
| | (Self-Learning Dynamic Functions) | | • Feature Extractor | |
| | | | • Linear Ranker | |
| | [209 Functions, 62 Unique] | | • LambdaMART (ML) | |
| | ├── analyze_jira_tickets (α=5,β=1) |<--+---------------------+ |
| | ├── get_system_metrics (α=12,β=2) | |
| | └── search_documentation (α=8,β=1) | [Thompson Sampling] |
| | | Confidence ≥ 0.7 → Reuse |
| | Quality Score: 0.7×success+0.3×spd | Confidence < 0.7 → Generate
| +-------------------------------------+ |
| |
+-----------------------------------------------------------------------+
^
| 1. "Fix the slow server." (User Goal)
|
+------------------+----------------------------------------------------+
| v |
| THE AGENT (The Planner) |
| |
| "I am the Synapse Agent. I see the user's goal." |
| "I will inspect the Kernel to see what Functions are available." |
| |
| [PLANNING PROCESS - Enhanced with Math Ranking] |
| 1. Thompson Sampling checks for reusable functions (α,β) |
| 2. If confidence ≥ 0.7: REUSE existing function (⚡0.5s, 💰$0) |
| 3. If confidence < 0.7: GENERATE new function (🧠3.5s, 💸$0.05) |
| 4. Rank candidates using Hybrid Score (BM25+Cosine+PageRank+...) |
| |
| [GENERATED PLAN - Optimized] |
| Step 1: Call `SystemMonitor.get_cpu_usage` [REUSED, conf=0.92] |
| Step 2: If CPU > 90%, Call `TechSupport.search_manuals` [NEW] |
| |
+------------------+----------------------------------------------------+
|
| 2. Agent executes the plan on the Kernel
v
[KERNEL EXECUTION]
-> Runs Python Code (Native Function)
-> Runs Vector Search (Semantic Function)
-> Records Metrics (success, latency) → Updates α,β
-> Synthesizes Natural Language Response
- Native Functions (Code): Deterministic Python methods. High reliability, zero cost, no hallucinations. Used for fetching metrics, hitting APIs, or performing math.
- Semantic Functions (Prompts): LLM-powered natural language logic. Used for summarization, sentiment analysis, and complex reasoning.
- Synapse Core (
src/synapse/core): The generic engine. It handles LLM connections, Memory management, and the Planning loop. - Cartridges (Plugins): Your domain-specific implementation. You can swap cartridges to move from Cloud SRE to Database Management or IoT automation without changing the core.
Synapse implements a mathematically rigorous function selection system inspired by Google's core algorithms, achieving 60-80% latency reduction and 70-90% cost reduction through intelligent function reuse.
Before: Every request generated a NEW function (expensive, slow):
Request 1: "show jira tickets" → Generate Function → 3.5s, $0.05
Request 2: "show jira tickets" → Generate Function → 3.5s, $0.05 (wasteful!)
Request 3: "show jira tickets" → Generate Function → 3.5s, $0.05 (wasteful!)
After: Thompson Sampling reuses proven functions (cheap, fast):
Request 1: "show jira tickets" → Generate Function → 3.5s, $0.05
Request 2: "show jira tickets" → Reuse Function → 0.5s, $0.00 ⚡💰
Request 3: "show jira tickets" → Reuse Function → 0.5s, $0.00 ⚡💰
┌─────────────────────────────────────────────────────────────────────────┐
│ PHASE 1: Hybrid Ranking │
│ ┌────────────┐ ┌────────────┐ ┌───────────┐ ┌─────────┐ ┌────────┐│
│ │ BM25 │ │ Cosine │ │ PageRank │ │ Quality │ │Recency ││
│ │ (Text) │ │(Semantic) │ │(Importance│ │ Score │ │ ││
│ │ 0.30× │ │ 0.25× │ │ 0.20× │ │ 0.20× │ │ 0.05× ││
│ └─────┬──────┘ └─────┬──────┘ └─────┬─────┘ └────┬────┘ └────┬───┘│
│ └───────────────┴─────────────────┴─────────────┴────────────┘ │
│ │ │
│ ▼ │
│ Hybrid Score = Σ w_i · feature_i │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ PHASE 2: Thompson Sampling (MAB) │
│ │
│ For each function f: │
│ α = success_count + 1 │
│ β = failure_count + 1 │
│ Sample θ ~ Beta(α, β) [Bayesian Multi-Armed Bandit] │
│ │
│ ┌─────────────────────┐ ┌──────────────────────┐ │
│ │ Best θ ≥ 0.7? │──YES──→ │ EXPLOIT: Reuse │ │
│ │ (Confident?) │ │ Existing Function │ │
│ └──────────┬──────────┘ │ ⚡ Fast (0.5s) │ │
│ │ │ 💰 Cheap ($0.00) │ │
│ NO └──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ EXPLORE: Generate │ │
│ │ New Function │ │
│ │ 🧠 Learn (3.5s) │ │
│ │ 💸 Cost ($0.05) │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ PHASE 3: Feature Extraction (15 Features) │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │
│ │ Semantic (4) │ │ Quality (4) │ │ Performance (3) │ │
│ ├─────────────────┤ ├─────────────────┤ ├──────────────────┤ │
│ │• Cosine Sim │ │• Success Rate │ │• Avg Latency │ │
│ │• BM25 Score │ │• Speed Score │ │• Execution Count │ │
│ │• Token Overlap │ │• Quality Score │ │• Stability │ │
│ │• L2 Distance │ │• Failure Penalty│ │ │ │
│ └─────────────────┘ └─────────────────┘ └──────────────────┘ │
│ │
│ ┌─────────────────┐ ┌──────────────────────────────────────┐ │
│ │ Recency (2) │ │ Interaction (2) │ │
│ ├─────────────────┤ ├──────────────────────────────────────┤ │
│ │• Days Since Exec│ │• PageRank Score │ │
│ │• Days Since Made│ │• Quality × Popularity │ │
│ └─────────────────┘ └──────────────────────────────────────┘ │
│ │
│ Linear Score = Σ w_i · feature_i │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ PHASE 4: LambdaMART (ML-Based Ranking) [Future] │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ LightGBM Gradient Boosted Trees │ │
│ │ Optimizing NDCG@k │ │
│ │ │ │
│ │ [Tree 1] → [Tree 2] → ... → [Tree 100] │ │
│ │ │ │
│ │ Learns non-linear feature interactions │ │
│ │ from 500+ queries with execution feedback │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ Training Pipeline: │
│ 1. Collect execution feedback (success/failure/latency) │
│ 2. Generate (query, function, relevance_label) training data │
│ 3. Train LightGBM model with NDCG@5 optimization │
│ 4. A/B test: 95% Linear Ranker, 5% LambdaMART │
│ 5. Deploy if >5% improvement │
└─────────────────────────────────────────────────────────────────────────┘
METRIC │ BEFORE │ AFTER │ IMPROVEMENT
───────────────────────┼───────────┼────────────┼─────────────
Avg Latency │ 3500ms │ 700-1400ms │ 60-80% ↓
LLM API Calls │ 100% │ 10-30% │ 70-90% ↓
Function Reuse Rate │ 0% │ 60-80% │ NEW METRIC
Success Rate │ 75% │ 79-83% │ 5-10% ↑
Relevance (NDCG@5) │ ~0.60 │ 0.75-0.80 │ 15-25% ↑
BM25 (Best Matching 25): Keyword-based text relevance
BM25(d,q) = Σ IDF(t) · [f(t,d)·(k₁+1)] / [f(t,d) + k₁·(1-b+b·|d|/avgdl)]
t∈q
PageRank: Function importance via execution graph
PR(f) = (1-d)/N + d · Σ PR(caller)/L(caller)
caller→f
Thompson Sampling: Beta distribution multi-armed bandit
For each function f:
α = success_count + 1
β = failure_count + 1
Sample θ ~ Beta(α, β)
Select function with highest θ
LambdaMART: Gradient boosted trees optimizing NDCG@k
NDCG@k = DCG@k / IDCG@k
where DCG@k = Σ (2^rel_i - 1) / log₂(i + 1)
i=1..k
┌──────────────────────────────────────────────────────────────────┐
│ User Query │
└────────────────────────────┬─────────────────────────────────────┘
│
▼
┌────────────────────────────────┐
│ Generate Query Embedding │
│ (Gemini/OpenAI/Anthropic) │
└────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Thompson Sampling Selector │
│ 1. Retrieve candidate functions │
│ 2. Sample from Beta distributions │
│ 3. Check confidence threshold (0.7) │
└──────────┬──────────────────────┬────────┘
│ │
Confident ≥0.7 Not Confident <0.7
│ │
▼ ▼
┌─────────────────────┐ ┌────────────────────────┐
│ REUSE PATH │ │ GENERATION PATH │
│ │ │ │
│ • Load function │ │ • Call LLM to generate │
│ from registry │ │ new function code │
│ • Skip LLM call │ │ • Validate code │
│ • Execute directly │ │ • Store in registry │
│ │ │ │
│ ⚡ 0.5s latency │ │ 🧠 3.5s latency │
│ 💰 $0.00 cost │ │ 💸 $0.05 cost │
└──────────┬──────────┘ └──────────┬─────────────┘
│ │
└────────────┬───────────┘
│
▼
┌────────────────────────┐
│ Execute Function │
│ (Sandboxed) │
└────────────┬───────────┘
│
▼
┌────────────────────────┐
│ Record Execution │
│ Metrics │
│ • Success/Failure │
│ • Latency │
│ • Update Beta params │
└────────────┬───────────┘
│
▼
┌────────────────────────┐
│ Update Rankings │
│ • BM25 index (weekly) │
│ • PageRank (daily) │
│ • Thompson α,β (live) │
└────────────────────────┘
See MATHEMATICAL_RANKING_GUIDE.md for complete documentation.
Synapse is vendor-agnostic and supports multiple LLM providers out of the box. Switch providers via environment variables without changing code.
| Provider | Chat Models | Embedding Models | Status |
|---|---|---|---|
| Google Gemini | gemini-1.5-flash, gemini-1.5-pro | models/embedding-001 | ✅ Default |
| OpenAI | gpt-4o, gpt-4o-mini | text-embedding-3-small/large | ✅ Supported |
| Anthropic | claude-3-5-sonnet, claude-3-opus | N/A (use OpenAI) | ✅ Supported |
Set your provider in .env:
# Use Gemini (Free Tier Available)
LLM_PROVIDER="gemini"
CHAT_MODEL_ID="gemini-1.5-flash-latest"
GEMINI_API_KEY="your-api-key"
# Use OpenAI (Paid)
LLM_PROVIDER="openai"
CHAT_MODEL_ID="gpt-4o-mini"
OPENAI_API_KEY="your-api-key"
# Use Anthropic (Recommended for Production)
LLM_PROVIDER="anthropic"
CHAT_MODEL_ID="claude-3-5-sonnet-20241022"
ANTHROPIC_API_KEY="your-api-key"Synapse v2.0 uses SQLite for persistent vector storage, eliminating the expensive embedding rehydration process:
- Before (v1.0): 100 docs = ~50 seconds startup (regenerate embeddings)
- After (v2.0): 100 docs = <5 seconds startup (read from SQLite)
Embeddings are stored in data/synapse.db and persist across restarts.
Enable Redis for additional performance benefits:
REDIS_ENABLED="true"
REDIS_URL="redis://localhost:6379/0"Benefits:
- Faster repeat queries (~10x speedup)
- Reduced API costs (embedding cache)
- Session management for multi-turn conversations
See MIGRATION.md for detailed migration guide from v1.0 to v2.0.
Synapse includes a unique, interactive web interface designed to look like a Retro Apple CRT Terminal.
- Phosphor Green Aesthetic: A high-contrast, glowing green-on-black interface with CRT scanlines and flicker effects.
- Modern Code Blocks: Features a "Holographic" contrast where code blocks are rendered with modern VS Code-style syntax highlighting (
Prism.js), floating within the retro environment. - Active AI (Fallout Style): If the terminal is left idle, the agent becomes interactive. It will chime in with "Pip-Boy" style status reports, sarcastic GLaDOS-like comments, or "Wasteland Survival" tips based on real-time system metrics.
- Autonomous Planning: Uses
SequentialPlannerto chain functions dynamically. - Mathematical Function Selection: Google-inspired algorithms (BM25, PageRank, Thompson Sampling, LambdaMART)
- Vector-Routed Memory: Built-in RAG pipeline to ingest documentation and search it via embeddings.
- Data Uplink:
- Drag & Drop: Upload ZIPs or Text files directly to the agent's brain.
- Git Clone: Ingest public GitHub repositories with a single command.
- Persistence: Automatically saves ingested data to disk and re-hydrates memory on startup.
- Self-Learning: Thompson Sampling for 60-80% latency reduction and 70-90% cost reduction.
This guide will walk you through setting up and running the Synapse project in a standardized development environment.
- pyenv: To manage Python versions. The setup script relies on
pyenvto install and select the correct Python version. See thepyenvinstallation guide. - Python 3.11.9: The script will automatically install this version for you using
pyenv. - Git: For cloning the repository.
This project includes an automated setup script that handles everything for you.
-
Clone the Repository:
git clone https://github.com/mattschwen/Synapse.git cd Synapse -
Run the Setup Script: This will check your Python version, create a virtual environment, install dependencies, and create the
.envconfiguration file../setup.sh
-
Configure Your API Key: After the setup script is complete, open the newly created
.envfile and add your API key. You can get a Gemini API key from Google AI Studio.# Inside your .env file GEMINI_API_KEY="YOUR_API_KEY_HERE"
The main application is a FastAPI web server with a retro terminal interface.
# Ensure your virtual environment is active before running
python src/synapse/server.pyYou can now access the web interface at http://127.0.0.1:8000.
The DevAssistant is the AI-powered command-line tool we use to develop and manage the Synapse project itself. It uses an AI planner to break down development tasks and delegate them to specialist agents.
# Ensure your virtual environment is active
python .gemini/agents/DevAssistant.py "Your detailed development request here"
# Example:
python .gemini/agents/DevAssistant.py "Add a new endpoint to the backend that returns the current system time"Distributed under the MIT License. See LICENSE for more information.