Hybrid multi-model task orchestrator — routes coding/review/scan tasks across LLMs via LangGraph
366d7247da
Phase 1 stabilization. Removes the four-copy prompt/agent-description drift surface and the silent router fallback. - models.py: hoist model IDs to module-level constants; add with_retries() helper (2 retries on Anthropic+OpenAI transient errors via with_retry). - agents.py: single AGENTS dict (model_fn, prompt, description) and a make_agent_node() factory that collapses six near-identical node functions. - graph.py: router prompt is generated from AGENTS; router_node uses with_structured_output(RouteDecision) and returns an explicit "unknown" route instead of the silent "researcher" fallback. New unknown_node wires to END. All LLM invocations go through with_retries. - state.py: add "unknown" to the route Literal. - run.py: --route-only now imports router_node from graph.py, killing the fourth prompt copy. - tests/: pytest golden-set (20 labelled tasks + size guard). Skips cleanly without ANTHROPIC_API_KEY or COMPOSIO_API_KEY. Validated 21/21 passing. |
||
|---|---|---|
| tests | ||
| .env.example | ||
| .gitignore | ||
| agents.py | ||
| graph.py | ||
| models.py | ||
| README.md | ||
| requirements.txt | ||
| run.py | ||
| state.py | ||
| tools.py | ||
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 hybrid delegation):
# Claude Code delegates automatically when another model is better for the task
python3 ~/Documents/repositories/orchestrator/run.py "<task description>"
# Check routing without executing
python3 ~/Documents/repositories/orchestrator/run.py --route-only "<task description>"
When Claude Code delegates vs. handles natively
Claude Code uses a hybrid model — it delegates to the orchestrator when a different model has a genuine advantage, and handles everything else natively:
| Delegate to orchestrator | Handle natively in Claude Code |
|---|---|
| Cross-family code review (GPT-4.1) | File editing, refactoring, bug fixes |
| Large codebase scanning (Gemini) | Git operations, PRs, merges |
| Quick bounded coding (DeepSeek) | AWS/SAM/CDK deployments |
| External service actions (Composio) | Shell commands, system admin |
| Interactive planning and conversation |
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
- Install dependencies:
pip install -r requirements.txt - Copy
.env.exampleto.envand fill in API keys - Authenticate Composio integrations at app.composio.dev
Configuration
All API keys are stored in .env (gitignored):
ANTHROPIC_API_KEY— Claude modelsOPENAI_API_KEY— GPT-4.1 cross-reviewerGOOGLE_API_KEY— Gemini scannerDEEPSEEK_API_KEY— DeepSeek fast-coderCOMPOSIO_API_KEY— Composio connectorsLANGSMITH_API_KEY— LangSmith tracing
Tracing is enabled via LangSmith (project: orchestration).