acfeb543d9
README now explains when Claude Code delegates to the orchestrator vs. handles tasks natively, matching the updated CLAUDE.md rules.
104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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):
|
|
```bash
|
|
# 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
|
|
|
|
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](https://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`).
|