# ML/AI — LangChain + LangGraph + LangSmith

## Stack
- Python 3.11+, Poetry
- LangChain (chains, tools, retrievers)
- LangGraph (stateful multi-step agent workflows)
- LangSmith (tracing, evaluation, monitoring)
- FastAPI for serving
- Frontend: Streamlit (POC) / React+Vite (production)

## Project Structure
```
src/
├── api/                  # FastAPI endpoints
├── agents/
│   ├── graphs/           # LangGraph state machines (one file per graph)
│   ├── tools/            # Custom tools (@tool decorated functions)
│   ├── prompts/          # ChatPromptTemplate definitions
│   └── callbacks/        # Custom callback handlers
├── chains/               # Simple LangChain chains (non-agentic)
├── config/               # Pydantic settings, model registry
└── utils/
eval/
├── datasets/             # LangSmith evaluation datasets
├── evaluators/           # Custom evaluator functions
└── config.yaml           # Eval run configurations
tests/
specs/                    # SDD artifacts and lessons learned
poc/
```

## Architecture Rules
> **Non-negotiable.** Violations must be flagged during review, not silently accepted.

- Use LangGraph for ANY multi-step workflow (not legacy AgentExecutor)
- Every LangGraph graph: explicit TypedDict state schema, no Any types
- All chains/graphs must be LangSmith-traceable (LANGCHAIN_TRACING_V2=true)
- Tools must have clear, complete docstrings (LLM reads them for selection)
- Prompts use ChatPromptTemplate; store in src/agents/prompts/

## Agent Patterns
- Tool-using single agent → ReAct pattern via LangGraph
- Multi-step complex tasks → Plan-and-Execute graph
- Multi-agent collaboration → Supervisor graph pattern
- Always implement human-in-the-loop breakpoints for destructive actions
- Max recursion depth: configurable, default 25
- All graph nodes must handle exceptions (return error state, don't crash)

## LangSmith
- All runs tagged with: project name, environment (dev/staging/prod)
- Evaluation datasets stored in eval/datasets/ as JSON
- Custom evaluators in eval/evaluators/ (correctness, tool_selection, latency)
- Run evaluations on every PR that touches agent logic

## Testing
- Unit: mock LLM via FakeLLM, test tool logic independently
- Integration: test full graph with recorded LLM responses
- Eval: LangSmith eval suite (correctness, tool accuracy, hallucination)
- Regression: baseline dataset comparison on each PR

## Commands
```bash
poetry install
poetry run pytest
LANGCHAIN_TRACING_V2=true poetry run uvicorn src.api.main:app --reload
poetry run python -m src.agents.graphs.main          # run agent directly
poetry run streamlit run poc/app.py
```

## Agent Team

### Roles

| Role | Trigger | Owns |
|------|---------|------|
| **Team Lead** (default) | Planning, architecture, agent design review | Overall coordination |
| **Agent Developer** | LangGraph graphs, tools, prompts, callbacks | `src/agents/`, `src/chains/` |
| **Integration Engineer** | API layer, LangSmith config, deployment, infra | `src/api/`, `src/config/`, Docker |
| **QA & Eval Engineer** | Testing, LangSmith evaluations, benchmarks | `tests/`, `eval/` |

### Team Lead — Default Behavior
You ARE the Team Lead. You own agent architecture decisions:
1. Which pattern to use (ReAct, plan-and-execute, supervisor) for each use case.
2. How to decompose complex agent workflows into graph nodes.
3. Review all agent code for correctness, error handling, and prompt quality.
4. Single-domain tasks under ~50 lines → handle directly. Else → delegate.

### Delegation Prompts
```
You are the [ROLE] on a LangChain/LangGraph project.

Project conventions:
- [paste relevant section from this CLAUDE.md]

Your task: [specific task description]

Constraints:
- All graphs use TypedDict state schemas (no Any types)
- All tools have complete docstrings
- LangSmith tracing must be preserved
- Return: code changes + summary of design decisions
```

### Agent Developer
Expertise: LangGraph state machines, LangChain tool/chain design, prompt engineering, ReAct/plan-and-execute patterns, callback handlers.
Constraints: every graph must have explicit state schema. Tools must have docstrings (LLM uses them). Prompts in `src/agents/prompts/`. Error handling in every node. Max recursion configurable.

### Integration Engineer
Expertise: FastAPI, LangSmith configuration, Docker, CI/CD, environment management, API design, auth middleware.
Constraints: all config via Pydantic settings. LANGCHAIN_TRACING_V2 always enabled. Health check at `/health`. API versioning in URL path.

### QA & Eval Engineer
Expertise: pytest, LangSmith evaluation framework, mock LLM patterns, test architecture, regression testing.
Constraints: mock all LLM calls in unit tests (FakeLLM). Integration tests use recorded responses. Eval datasets in `eval/datasets/`. Run existing tests before writing new code. Track eval metrics over time.
