docs/architecture.md

Architecture Overview

Placeholder. Fill in once V3 implementation lands.

V2 (current, deployed)

            ┌─────────────────────────────────────┐
            │           inference.py              │
            │  Llama-3.3-70B Vendor agent         │
            └─────────────────┬───────────────────┘
                              │  POST /reset, /step
                              ▼
            ┌─────────────────────────────────────┐
            │   FastAPI app (server/app.py)       │
            │  /health  /reset  /step  /state     │
            └─────────────────┬───────────────────┘
                              ▼
        ┌──────────────────────────────────────────┐
        │     NegotiationArenaEnvironment          │
        └─────────────────┬────────────────────────┘
                          │
              ┌───────────┴────────────┐
              ▼                        ▼
   ┌──────────────────┐     ┌────────────────────┐
   │  ScriptedClient  │     │     LLMClient      │
   │   (training)     │     │     (eval only)    │
   └──────────────────┘     └────────────────────┘
                          │
                          ▼
                   server/arena.py        — turn manager
                   server/graders.py      — composite reward
                   server/utility.py      — per-role scoring
                   server/private_briefs  — hidden priorities
                   server/contract_fixtures — 3 tasks

V3 (planned additions)

• server/tom.py — theory-of-mind module (vendor predicts opponent's next action; correctness shapes reward)
• server/tribunal.py — 3-judge ensemble grader; reward = median, anti-collusion penalty on disagreement
• server/curriculum.py — auto-difficulty scheduler driven by recent win rate
• audit/ — adversarial robustness suite (5 exploit agents probing the trained policy)
• evaluation/ — generalization tests + 5 diagnostic plots
• web/landing/ + web/replay_ui/ — public landing page and JSON-driven episode replayer

To be illustrated with a proper diagram (assets/architecture_diagram.png) once V3 is implemented.