From ca96b488e6f6ba9889c6f22491644202711280d4 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Fri, 8 May 2026 13:12:02 -0400
Subject: [PATCH] Add README and fix .env.example project name

---
 .env.example |  2 +-
 README.md    | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/.env.example b/.env.example
index eca36a8..0c1ffa6 100644
--- 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=
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bc1cbe5
--- /dev/null
+++ 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`).