documents/ARCHITECTURE.md

# Architecture

## System Overview

```
┌──────────────────────────────────────────────────────────────┐
│                     HF Space / Docker Container              │
│                                                              │
│  ┌──────────────┐    ┌──────────────────────────────────┐    │
│  │  Gradio UI   │    │         FastAPI Server           │    │
│  │  (port 7860) │    │  POST /reset  GET /state         │    │
│  │              │    │  POST /step   GET /health        │    │
│  └──────┬───────┘    └──────────────┬───────────────────┘    │
│         │                           │                        │
│         └──────────┬────────────────┘                        │
│                    │                                         │
│         ┌──────────▼──────────────┐                          │
│         │   InvoiceExceptionEnv   │                          │
│         │  reset() step() state() │                          │
│         │  grade()                │                          │
│         └──────────┬──────────────┘                          │
│                    │                                         │
│         ┌──────────▼──────────────┐                          │
│         │      Task Registry      │                          │
│         │  task1_price_variance   │                          │
│         │  task2_duplicate_tax    │                          │
│         │  task3_compound_fraud   │                          │
│         └─────────────────────────┘                          │
└─────────────────────────────────────────────────────────────┘
```

## Key Design Decisions

### FastAPI + Gradio in same process
HF Spaces requires a single port (7860). Gradio is mounted on FastAPI using
`gr.mount_gradio_app()` so both the validator API and the interactive UI
share the same process and port.

### Pydantic v2 for all models
Required by the OpenEnv spec. Every field is typed. No `Any` fields without
explicit documentation of why.

### EpisodeData vs EnvironmentState
- **EpisodeData** is mutable internal state tracking what the agent has done
- **EnvironmentState** is the immutable snapshot returned to the agent
- Documents (PO, Invoice, GRN) are rebuilt from task factories each time,
  ensuring they are never accidentally mutated

### Separate task classes
Each task is a self-contained class with its own documents, simulators, and
grader. This makes it trivial to add new tasks — just implement BaseTask and
register in TASK_REGISTRY.

### Deterministic simulation
No randomness in simulators or graders. Same seed + same actions = same scores.
The only randomness is in `action_space_sample()` for baseline agents.