# 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 delegation):
```bash
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](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`).