Synapse Council

A GitHub-ready multi-agent orchestration framework for structured reasoning, debate, synthesis, and review across multiple LLM providers.

Overview

Synapse Council is a modular multi-agent system that improves complex reasoning by coordinating specialized AI agents through a staged workflow:

Research → Analysis → Debate → Synthesis → Review

Instead of relying on one model to do everything, the framework routes work to the most appropriate models, shares intermediate state through a layered blackboard, and enforces phase-specific protocols and quality gates.

Core Capabilities

• Dynamic role generation based on prompt complexity
• Multi-provider model routing and fallback chains
• Layered blackboard memory with controlled state sharing
• Structured, phase-based reasoning pipeline
• Quality tracking and validation before final output
• CLI, Python API, and lightweight web interface
• Configuration-driven architecture for rapid iteration

Architecture Snapshot

flowchart LR
    U[User Prompt] --> MR[Meta Router]
    MR --> RP[Research Phase]
    RP --> AP[Analysis Phase]
    AP --> DP[Debate Phase]
    DP --> SP[Synthesis Phase]
    SP --> RV[Review Phase]
    RV --> O[Final Output]

    MR -. config .-> CFG[settings.yaml]
    RP -. shared memory .-> BB[Layered Blackboard]
    AP -. shared memory .-> BB
    DP -. shared memory .-> BB
    SP -. shared memory .-> BB
    RV -. quality gates .-> QT[Quality Tracker]

Loading

Repository Layout

Synapse-Council/
├── app_desktop.py
├── app_web.py
├── config/
├── docs/
├── src/
│   ├── agents/
│   ├── blackboard/
│   ├── graphs/
│   ├── meta_router/
│   ├── pipeline/
│   ├── protocols/
│   ├── utils/
│   └── web/
├── tests/
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

Quick Start

git clone <your-repo-url>
cd Synapse-Council
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
python -m src.main "Explain how multi-agent reasoning improves answer quality."

Web UI

uvicorn src.web.api:app --reload

Then open the local address printed by Uvicorn in your browser.

Python API Example

import asyncio
from src.utils.orchestrator import CouncilOrchestrator

async def main() -> None:
    orchestrator = CouncilOrchestrator()
    result = await orchestrator.run("What are the trade-offs of multi-agent AI systems?")
    print(result.final_output)

asyncio.run(main())

Documentation

The original project contained a mix of English and Persian technical notes. For this public GitHub edition, the repository has been normalized into an English-first structure and the documentation has been converted into concise GitHub-style summaries.

Start here:

• docs/00_OVERVIEW.md
• docs/guides/01_GETTING_STARTED.md
• docs/guides/02_CODE_WALKTHROUGH.md
• docs/diagrams/SYSTEM_OVERVIEW.md

Recommended Positioning

This project fits well as:

• an advanced orchestration prototype
• a portfolio project for AI systems engineering
• a research playground for agent collaboration patterns
• a base for experimentation with routing, memory, and debate protocols

License

MIT