# CR Agent System - Implementation Walkthrough

Complete implementation of the AI Code Review Orchestrator using LangGraph for multi-agent orchestration.

---

## Project Structure

```
cr-agent-system/
├── pyproject.toml                    # Dependencies: langgraph, langchain, chromadb
├── CR_ORCHESTRATOR_PROMPT.md         # System prompt
├── doc/
│   └── DESIGN.md                     # Architecture design
├── scripts/
│   └── test_vllm_pr.py               # E2E verification script
├── tests/                            # Pytest suite
├── .github/                          # CI workflows
├── src/cr_agent/
│   ├── state.py                      # AgentState + Pydantic models
│   ├── graph.py                      # LangGraph workflow
│   ├── main.py                       # Production CLI
│   ├── seed.py                       # Knowledge seeding utility
│   ├── tools/
│   │   ├── dependency_impact.py      # Dependency analyzer
│   │   ├── design_patterns.py        # Pattern retrieval
│   │   ├── hotspot_detector.py       # Git history analyzer
│   │   └── user_preferences.py       # ChromaDB RAG search
│   ├── agents/
│   │   ├── general_reviewer.py       # Lite mode (≤300 lines)
│   │   ├── security_agent.py         # SQLi, XSS, Auth
│   │   ├── performance_agent.py      # N+1 detection
│   │   └── domain_agent.py           # Business logic
│   └── routing/
│       ├── router.py                 # 300 lines / 3 domains threshold
│       └── file_filter.py            # Context pruning
```

---

## Quick Start

```bash
# Install
pip install -e .

# Set credentials
export OPENAI_API_KEY="your-key"
export GITHUB_TOKEN="your-token"  # For PR fetching

# Review a PR
python -m cr_agent.main --github vllm-project/vllm --pr 32263
```

---

export GITLAB_TOKEN="token"
export GITLAB_PROJECT_ID="12345"
python scripts/seed_knowledge.py
```

**What it does:**
1. Fetches last 20 merged PRs
2. Extracts discussion threads that resulted in code changes
3. Uses LLM to distill "Preference Rules"
4. Stores in ChromaDB for RAG retrieval

---

## Validation Results

### vLLM PR #32263 (Real-world Test)

**Input:** CPU Paged Attention NEON BFMMLA BF16 Implementation  
**Stats:** 1,006 diff lines, 8 files

**Seeding Output:**
```
📥 Fetched 20 merged PRs from vllm-project/vllm
📝 Found 23 actionable discussion threads
🧠 Distilled 23 preference rules
💾 Ingested into ChromaDB
```

**Review Output (gpt-5-mini):**
- ✓ Identified BF16 intrinsic type mismatch risk
- ✓ Flagged missing `ARM_BF16_SUPPORT` guards
- ✓ Detected potential stack overflow with large arrays
- ✓ Provided concrete code fixes with examples
- ✓ Generated 6-item pre-merge checklist

---

## Test Coverage

```
44 tests passed in 2.73s

tests/test_state.py    — 14 tests (Pydantic models)
tests/test_routing.py  — 21 tests (file filtering, routing)
tests/test_tools.py    — 9 tests (drift prevention tools)
```

---

## Architecture Decisions

| Decision | Rationale |
|----------|-----------|
| LangGraph | State machine for complex multi-agent workflows |
| ChromaDB | Lightweight vector store for RAG |
| 300 line threshold | Balance between lite mode speed and delegation accuracy |
| File filtering | Reduces context window usage by 60-80% |
| gpt-5-mini | Best cost/quality ratio for code review |

---

## Next Steps

1. **Parallel execution** — Use LangGraph's `Send` API for concurrent sub-agents
2. **Git integration** — Implement actual git history in `HotspotDetectorTool`
3. **Checkpointing** — Enable persistence for long-running reviews
4. **Webhook integration** — Auto-trigger on PR creation
