# ML/AI — Full-Stack LLM Application

## Stack
- Python 3.10+, setuptools (pyproject.toml), `pip install -e ".[dev]"`
- FastAPI + Uvicorn for the API layer
- LLM providers: LiteLLM abstraction (OpenAI, Anthropic, Ollama, vLLM) ← UPDATE per project
- Vector store: Chroma (dev) / Pinecone or Qdrant (prod) ← UPDATE per project
- Sandboxed execution: Docker container + RestrictedPython ← UPDATE if not needed
- Frontend: Next.js + React + TypeScript + Tailwind CSS + Radix UI
- Code quality: Black (formatter), Ruff (linter), mypy strict (type checker)

## Project Structure
```
src/<package>/
├── core/                # Core algorithm logic, budget tracking, guardrails
├── llm/                 # LLM provider clients (protocol-based abstraction)
│   ├── base.py          # Provider protocol (interface)
│   ├── auto.py          # Auto-detection from env vars
│   └── ...              # One client per provider
├── strategies/          # Pluggable interaction modes (strategy pattern)
│   ├── base.py          # Strategy protocol
│   ├── direct.py        # Single-pass LLM call
│   ├── rag.py           # Retrieval-augmented generation
│   └── ...              # Additional strategies
├── storage/             # Persistence layer
│   ├── database.py      # Base storage (SQLite for dev)
│   ├── conversation_store.py  # Chat history
│   └── vector_store.py  # Vector similarity search
├── envs/                # Execution environments
│   ├── sandbox.py       # Docker sandbox for untrusted code
│   └── timeout.py       # Execution timeout utilities
├── server/              # FastAPI application
│   ├── app.py           # FastAPI instance + middleware
│   ├── models.py        # Pydantic request/response schemas
│   ├── dependencies.py  # Dependency injection
│   └── routes/          # Endpoint handlers (one per domain)
├── domain/              # DDD entities, value objects, events, exceptions
├── infrastructure/      # Config loaders, external service adapters
├── benchmark/           # Evaluation harness (datasets, runner, report)
├── api.py               # Unified high-level API (simple entry point)
└── config.py            # Global configuration (Pydantic settings)
frontend/                # Next.js React app
├── src/
│   ├── app/             # Next.js App Router (pages + layouts)
│   ├── components/      # React components (Radix UI based)
│   └── lib/             # Utilities, API client, hooks
├── package.json
└── tailwind.config.js
docker/                  # Dockerfiles (sandbox container, services)
tests/
├── unit/                # Component-level tests
├── integration/         # Multi-component tests
└── e2e/                 # End-to-end tests
specs/                    # SDD artifacts and lessons learned
```

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

- **Clean Architecture**: domain → application → infrastructure layers; dependencies flow inward
- **Protocol-based abstractions**: LLM providers, strategies, storage all defined as protocols (interfaces)
- **Provider-agnostic**: LLM clients pluggable via standardized protocol; auto-detect from env vars
- **Strategy pattern**: pluggable interaction modes (Direct, RAG, custom) with unified interface
- **Budget tracking**: all LLM operations tracked for tokens, cost, and execution steps
- **Sandboxed execution**: untrusted code runs in Docker containers with resource limits
- **Configuration-driven**: models, strategies, limits all configurable via env vars and config files

## Key Conventions
- All LLM calls: wrapped with tracing (latency, token count, cost)
- Provider selection: auto-detect from environment variables, never hardcode
- Pydantic models for all API request/response schemas
- Type annotations on all public functions; mypy strict mode
- Async handlers for all I/O-bound FastAPI operations
- YAML for prompt templates and configuration; never inline prompt strings
- Health check endpoint at `/health`

## LLM Provider Rules
- Define provider interface as a Python protocol (abstract base)
- Each provider in its own module (`llm/<provider>_client.py`)
- Auto-detection from env vars (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.)
- Never import provider SDKs at module level; use lazy imports (graceful when SDK missing)
- All providers must support: `generate()`, `stream()`, and token estimation
- Mock provider for testing (deterministic responses, no API calls)

## Execution Safety
- Docker sandbox: non-root user, memory/CPU limits, network disabled for untrusted code
- RestrictedPython for lightweight sandboxing when Docker is unavailable
- Execution timeout on all LLM calls and code execution
- Budget limits: max tokens, max cost, max execution steps per request

## Frontend Conventions
- Next.js App Router with server and client components
- SWR for data fetching with caching
- Tailwind CSS for styling; Radix UI for accessible components
- TypeScript strict mode; no `any` types
- Responsive design (mobile-first breakpoints)

## Testing
- Backend: `pytest` with markers (`integration`, `e2e`, `live`, `slow`)
- Mock all LLM calls in unit tests (use mock provider)
- Frontend: Vitest + React Testing Library
- Benchmark suite for strategy comparison (accuracy, cost, latency)
- Coverage target: ≥80% on core modules

## Commands
```bash
pip install -e ".[dev]"                                    # install with dev tools
pip install -e ".[all]"                                    # install everything
pytest --tb=short -q                                       # run tests
uvicorn src.<package>.server.app:app --reload              # API server
cd frontend && npm install && npm run dev                  # frontend dev server
ruff check . && mypy src/                                  # lint + type check
docker build -f docker/Dockerfile.sandbox -t sandbox .     # build sandbox
```

## Agent Team

### Roles

| Role | Trigger | Owns |
|------|---------|------|
| **Team Lead** (default) | Planning, architecture decisions, API contracts, code review | Overall coordination, `src/<pkg>/domain/` |
| **Backend Developer** | FastAPI routes, server logic, core algorithm, storage | `src/<pkg>/server/`, `src/<pkg>/core/`, `src/<pkg>/storage/` |
| **Frontend Developer** | React components, pages, data fetching, UI state | `frontend/` |
| **ML/AI Engineer** | LLM providers, strategies, embeddings, benchmarks, prompts | `src/<pkg>/llm/`, `src/<pkg>/strategies/`, `src/<pkg>/benchmark/` |
| **QA Engineer** | Testing at all layers, coverage, mocking, CI | `tests/`, all test files |

### Team Lead — Default Behavior
You ARE the Team Lead. For every user request:
1. Assess complexity. Single-domain, single-layer changes → handle directly.
2. Multi-layer or >50 lines of specialized code → delegate to specialist sub-agent.
3. Always review sub-agent output against project conventions before presenting.
4. Coordinate when a task spans layers (e.g., new API endpoint needs server + frontend + tests).
5. Own domain entities and cross-cutting concerns (auth, config, error handling).

### Delegation Prompts
When spawning a sub-agent via Agent tool, use this pattern:
```
You are the [ROLE] on a full-stack LLM application.

Architecture: Clean Architecture (domain → application → infrastructure).
Backend: Python 3.10+, FastAPI, protocol-based LLM abstraction, strategy pattern.
Frontend: Next.js + React + TypeScript + Tailwind + Radix UI.

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

Your task: [specific task description]

Constraints:
- Follow all conventions above
- Type-annotated Python with mypy strict compliance
- Do NOT modify files outside your ownership area without noting it
- Return: code changes + brief summary of decisions made
```

### Backend Developer
Expertise: FastAPI, Pydantic, async Python, SQLite/PostgreSQL, dependency injection, Docker.
Constraints: Pydantic models for all API schemas. Async handlers for I/O. Health check at `/health`. Structured logging. Domain entities are plain Python (no framework deps). Business logic in core/services, not in route handlers.

### Frontend Developer
Expertise: Next.js App Router, React (server/client components), TypeScript, Tailwind CSS, Radix UI, SWR, responsive design.
Constraints: Server Components by default; `'use client'` only for interactivity. SWR for data fetching. TypeScript strict mode, no `any`. Accessible components (ARIA). Responsive at all breakpoints.

### ML/AI Engineer
Expertise: LLM API integration, prompt engineering, RAG pipelines, embedding models, evaluation frameworks, token optimization, multi-provider abstraction.
Constraints: all providers implement the base protocol. Auto-detect from env vars. Never hardcode model names; use config. Mock provider for tests. Lazy SDK imports. Budget tracking on all LLM calls. Prompts in YAML files.

### QA Engineer
Expertise: pytest, Vitest, React Testing Library, test architecture, mocking, benchmarking, CI/CD.
Constraints: run existing tests before writing new ones. Mock all external APIs in unit tests. Use pytest markers for test categories. Coverage ≥80% on core modules. Frontend tests with Vitest + RTL. Benchmark tests with labeled datasets.
