orchestrator/README.md

orchestrator

Multi-model AI agent orchestration via LangGraph + Composio. Routes tasks to the best-fit model and connects to external services (Slack, Notion, GitHub, Google Drive).

Architecture

Claude Code ──► run.py ──► LangGraph StateGraph
                                │
                          ┌─────┤ router (Sonnet)
                          │     │
                          ▼     ▼
               ┌──────────────────────────────┐
               │  implementer    (Sonnet)      │
               │  reviewer       (Sonnet)      │
               │  researcher     (Haiku)       │
               │  cross_reviewer (GPT-4.1)     │
               │  scanner        (Gemini 2.5)  │
               │  fast_coder     (DeepSeek)    │
               │  connector      (Composio)    │
               └──────────────────────────────┘

The router node evaluates each task and routes to one of 7 agent nodes via conditional edges. The connector node uses Composio tools for external service interactions.

Files

File	Purpose
run.py	CLI entry point — python3 run.py "<task>"
graph.py	LangGraph graph definition, router, connector, and summarizer nodes
agents.py	Agent node functions with system prompts
models.py	LLM factory functions for each provider
state.py	Graph state schema (OrchestratorState)
tools.py	Composio tool loading (Slack, Notion, GitHub, Google Drive)

Usage

# Full execution — routes and runs the task
python3 run.py "What is the LangGraph checkpoint API?"

# Route-only — prints which agent would handle the task
python3 run.py --route-only "Review this code for security issues"

From Claude Code (via CLAUDE.md delegation):

python3 ~/Documents/repositories/orchestrator/run.py "<task description>"

Agents

Agent	Model	Use Case
implementer	Claude Sonnet 4.6	Write code with a clear spec
reviewer	Claude Sonnet 4.6	Code review (BLOCK/FIX/NIT/QUESTION)
researcher	Claude Haiku 4.5	Doc lookups, API research
cross_reviewer	GPT-4.1	Independent second-opinion review
scanner	Gemini 2.5 Pro	Large codebase analysis
fast_coder	DeepSeek Coder	Quick, bounded coding tasks
connector	Sonnet + Composio	Slack, Notion, GitHub, Google Drive

Connectors (via Composio)

All connections authenticated under Composio user amoussa:

• Slack: send messages, read channels/threads, find users, add reactions
• Notion: search/read/create/update pages, add content
• GitHub: create issues, list issues, get repo info
• Google Drive: find files, get metadata

Setup

1. Install dependencies: pip install -r requirements.txt
2. Copy .env.example to .env and fill in API keys
3. Authenticate Composio integrations at app.composio.dev

Configuration

All API keys are stored in .env (gitignored):

• ANTHROPIC_API_KEY — Claude models
• OPENAI_API_KEY — GPT-4.1 cross-reviewer
• GOOGLE_API_KEY — Gemini scanner
• DEEPSEEK_API_KEY — DeepSeek fast-coder
• COMPOSIO_API_KEY — Composio connectors
• LANGSMITH_API_KEY — LangSmith tracing

Tracing is enabled via LangSmith (project: orchestration).