backend/README.md

Trenches Backend

This directory contains the Python backend for the Trenches simulator.

It now exposes two layers:

• the existing session-oriented FastAPI API used by the React dashboard
• a native OpenEnv-compatible environment mounted under /openenv when openenv-core is installed

The backend does not serve frontend assets and is intended to stay frontend-stack agnostic. Any web client (Next.js, Vite, Bun, mobile, or a thin dashboard proxy) should be able to consume the same HTTP contract.

CORS is configurable so frontend migrations do not require backend code changes:

• TRENCHES_CORS_ALLOW_ORIGINS=https://app.example.com,https://ops.example.com
• TRENCHES_CORS_ALLOW_ORIGIN_REGEX=https://.*\\.example\\.com
• TRENCHES_CORS_ALLOW_CREDENTIALS=true|false

If no CORS env vars are set, the backend allows local development origins on localhost / 127.0.0.1 for any port.

Entity-model provider bindings are also configurable per agent. The backend does not fake provider readiness: if a provider/model is not configured, the runtime reports heuristic_fallback explicitly in session state and /capabilities.

Supported env patterns:

• TRENCHES_MODEL_PROVIDER=openai|anthropic|openrouter|ollama|vllm|custom
• TRENCHES_MODEL_NAME=<provider model id>
• TRENCHES_MODEL_BASE_URL=<custom base url>
• TRENCHES_MODEL_API_KEY_ENV=<name of env var holding the secret>
• TRENCHES_MODEL_SUPPORTS_TOOL_CALLS=true|false
• TRENCHES_MODEL_SUPPORTS_STRUCTURED_OUTPUT=true|false

Per-entity overrides use the uppercase agent suffix, for example:

• TRENCHES_MODEL_PROVIDER_US=openai
• TRENCHES_MODEL_NAME_US=gpt-4.1
• TRENCHES_MODEL_API_KEY_ENV_US=OPENAI_API_KEY

Relevant OpenEnv pieces in this package:

• trenches_env.openenv_adapter.TrenchesOpenEnvEnvironment
• trenches_env.openenv_adapter.TrenchesOpenEnvAction
• trenches_env.openenv_adapter.TrenchesOpenEnvObservation
• trenches_env.openenv_adapter.TrenchesOpenEnvState
• trenches_env.openenv_client.TrenchesEnvClient

Historical replay training pieces:

• trenches_env.models.Prediction
• trenches_env.models.HistoricalEvent
• trenches_env.models.HistoricalReplayState
• trenches_env.training_cli

The backend now supports replay-aware forecast training:

• reset(..., replay_id=...) starts from a visible historical context event
• step(...) accepts separate action and prediction
• the next ground-truth event is revealed on the same OpenEnv step
• reward blends the entity action reward with forecast scoring terms

Bundled bootstrap replay (⚠️ all replays are synthetic seed data — replace with curated truth sets for production):

• us_synthetic_seed_2025_2026

CLI training entrypoint:

trenches-train \
  --training-agent us \
  --replay-id us_synthetic_seed_2025_2026 \
  --generation-backend transformers

The CLI supports two rollout backends:

• transformers for portable local smoke runs
• vllm for the documented colocated OpenEnv + TRL path on a GPU box

Planned responsibilities:

• Hold in-memory crisis sessions.
• Expose create, reset, step, and state HTTP endpoints.
• Model the fog-of-war world state and per-agent observations.
• Provide a native OpenEnv boundary with scalar rewards for one active training agent while retaining full per-agent state internally.
• Provide extension points for World Monitor ingestion and RL training hooks.