docs/ARCHITECTURE.md

Architecture

A concise map of how the system fits together. For exhaustive detail see TECHNICAL_REFERENCE.md; for the improvement plan see ROADMAP.md.

Layers

                +-------------------------------------------------+
   clients ---> |  FastAPI app (env/api.py)                       |
   (curl,       |  gateway middleware: request-id, rate limit,     |
    dashboard,  |  auth, telemetry  +  global JSON error handler   |
    tooling)    +------------------+------------------------------+
                                   |
        +--------------------------+--------------------------+
        |              |               |              |        |
        v              v               v              v        v
   Environment      Grader         Policies/Agents  Persistence  Telemetry
   (env/            (env/          (env/policy,     (env/db,     (telemetry/
   environment.py)  grader.py)     llm_*, agents/)  repositories) metrics,alerts)
        |              |               |              |
        +-----> Tasks/scenarios (env/tasks.py, data_loader.py, data/*.yaml)
                config (env/config.py)  logging (env/logging_config.py)

Request flow (e.g. POST /baseline)

1. Gateway middleware assigns a request id (X-Request-ID), enforces opt-in rate limit + auth, and times the request for /metrics.
2. The handler runs a policy (baseline/stress/llm/hybrid) against the environment, scoring each step with the grader (bounded to the open interval (0,1)).
3. The result is persisted (episode DB + above-threshold learning trajectory) best-effort, and returned. /replay reads memory then falls back to the DB.

Key components

Area	Module(s)	Responsibility
Runtime API	env/api.py, env/dashboard_api.py	REST + WebSocket surface
Simulation	env/environment.py, env/tasks.py, env/data_loader.py	Deterministic inbox state machine + scenarios
Scoring	env/grader.py, env/utils.py	Bounded, monotonic, numerically stable scores
Decisioning	env/policy.py, env/llm_policy.py, env/llm_agent.py, env/agents/	Baseline, hybrid planner/executor, LLM, multi-agent
Persistence	env/db.py, env/repositories.py, env/learning/	SQLite episodes/preferences + learning store
Cross-cutting	env/config.py, env/logging_config.py, env/security.py	Settings, structured logging, auth/rate-limit
Observability	telemetry/	Prometheus metrics, alert rules
Tooling	baseline/, benchmark/, reports/	CLI runners, benchmark matrix, PDF reports
UI	dashboard/	React dashboard (built into the image, served at /dashboard/)

Invariants

• Score/log contract: inference.py log format ([START]/[STEP]/[END]) and the open-interval (0,1) score contract are stable so tooling can parse runs reliably.
• Determinism: a given (task, seed, persona) always produces the same baseline trajectory and score (guarded by tests/test_grading_rigor.py).
• Config is centralized in env/config.py; security and logging are opt-in and configured via environment variables (see .env.example).

Notable design decisions

• Open-interval scoring (strict_unit_interval + atan reward squash): bounds scores into (0,1) while preserving order, so downstream consumers never have to special-case exact 0.0/1.0.
• Opt-in security: the API runs open by default (frictionless local/eval use); auth, CORS limits, and rate limiting activate only when configured.
• HITL approval is opt-in (REQUIRE_APPROVAL): the raw agent acts directly; the product path can require human approval for reply/escalate.