Add README and fix .env.example project name

2026-05-08 13:12:02 -04:00 · 2026-05-08 13:12:02 -04:00 · ca96b488e6
commit ca96b488e6
parent b125956ee5
2 changed files with 89 additions and 1 deletions
--- a/.env.example
+++ b/.env.example
@ -1,7 +1,7 @@
 # LangSmith / LangGraph Cloud
 LANGSMITH_API_KEY=
 LANGCHAIN_TRACING_V2=true
-LANGCHAIN_PROJECT=seahaven-orchestrator
+LANGCHAIN_PROJECT=orchestration

 # Composio
 COMPOSIO_API_KEY=
--- a/README.md
+++ b/README.md
@ -0,0 +1,88 @@
+# 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`).