| # 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: | |
| ```bash | |
| 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. | |