Spaces:
Sleeping
Sleeping
| # Visualizer ↔ Game-engine contract | |
| This document describes what the React visualizer in `visualizer/` expects from | |
| the rest of the project. The viewer can render episodes from two sources: | |
| 1. **Live streaming** (default): the FastAPI server in | |
| `server/visualizer_server.py` runs LLM- or rule-based agents through the | |
| parliamentary loop and streams per-round records over Server-Sent Events. | |
| 2. **Static JSON files**: drag-and-drop a `.json` file (or click | |
| "Load episode JSON") with the shape described below. | |
| The two paths share the same per-round schema, so anything the live runner | |
| produces can be dropped onto disk and replayed later. | |
| --- | |
| ## 1. The episode JSON contract | |
| Top-level shape: | |
| ```jsonc | |
| { | |
| "episode_id": "string", | |
| "seed": 42, | |
| "policy": "string e.g. 'gpt-4o-mini' or 'PPO/checkpoint-12000'", | |
| "config": { | |
| "sectors": [ | |
| { "name": "Social", "full_name": "Social/Municipal", "baseline": 60 }, | |
| ... | |
| ], | |
| "pop_0": 1000000, | |
| "initial_treasury": 1000, | |
| "baseline_tax": 100, | |
| "productivity_bounds": [0.5, 2.0], | |
| "max_rounds": 50 | |
| }, | |
| "rounds": [ /* see §1.1 below */ ], | |
| "summary": { | |
| "rounds_survived": 50, | |
| "total_reward": 12345.6, | |
| "final_treasury": 2200, | |
| "final_prosperity": 0.0021, | |
| "final_productivity": 1.42, | |
| "final_population": 1080000, | |
| "termination_reason": "MAX_ROUNDS" | |
| } | |
| } | |
| ``` | |
| ### 1.1 Per-round shape | |
| Each entry in `rounds[]` is one full step (Phases 1–9 of the spec): | |
| ```jsonc | |
| { | |
| "round_num": 1, | |
| "year": 1, | |
| "quarter": 1, | |
| // Phase 1 — events | |
| "events": [ | |
| { | |
| "round": 1, | |
| "id": "war", | |
| "name": "War", | |
| "severity": 4, | |
| "affected_sectors": { "Defense": 2.5, "Agriculture": 1.3 }, | |
| "category": "moderate", | |
| "narrative": "Enemy forces…", | |
| "treasury_injection": 0, | |
| "is_positive": false | |
| } | |
| ], | |
| "crisis_occurred": false, | |
| "treasury_injection": 0, | |
| // Phase 2 — debate | |
| "debate": [ | |
| { "agent_id": "Health", "department": "Health", "message": "…" } | |
| ], | |
| // Phases 3–4 — proposals + voting | |
| "proposal_order": ["Defense", "Health", "Education", "Commerce", "Social", "Agriculture"], | |
| "proposals": [ | |
| { | |
| "proposal_id": "r1_Defense", | |
| "agent_id": "Defense", | |
| "department": "Defense", | |
| "amount": 320, | |
| "justification": "…", | |
| "status": "approved", | |
| "rejection_reason": null, | |
| "votes": { "Health": "YES", "Defense": "ABSTAIN", ... } | |
| } | |
| ], | |
| "votes": [ | |
| { | |
| "proposal_id": "r1_Defense", | |
| "agent_id": "Health", | |
| "department": "Health", | |
| "vote": "YES" | |
| } | |
| ], | |
| "vote_results": [ | |
| { | |
| "proposal_id": "r1_Defense", | |
| "department": "Defense", | |
| "amount": 320, | |
| "yes": 4, "no": 1, "abstain": 1, | |
| "status": "APPROVED" | |
| } | |
| ], | |
| // Phases 5–8 — execution + revenue + surplus | |
| "allocations": { "Defense": 320, "Health": 95, ... }, | |
| "consumptions": { "Defense": 250, "Health": 90, ... }, | |
| "revenues": { "Defense": 480, "Health": 130, ... }, | |
| "revenue_factors": { "Defense": 1.50, "Health": 1.36, ... }, | |
| "thresholds": { | |
| "Defense": { "critical": 100, "demand": 250, "surplus": 375, "wastage": 625 }, | |
| ... | |
| }, | |
| "event_multipliers": { "Defense": 2.5, "Agriculture": 1.3, ... }, | |
| "treasury_before": 1000.0, | |
| "treasury_after": 1180.4, | |
| "total_allocation": 740, | |
| "total_revenue": 1020.4, | |
| "surplus_returned": 60.0, | |
| "population": 1004000, | |
| "productivity": 1.04, | |
| "avg_revenue_factor":1.21, | |
| "prosperity": 0.00102, | |
| // Phase 9 — reward + termination | |
| "reward": { | |
| "base_reward": 0.00102, | |
| "productivity_bonus": 2.0, | |
| "survival_bonus": 10.0, | |
| "over_alloc_penalty": 0, | |
| "under_alloc_penalty": -10, | |
| "critical_penalty": 0, | |
| "total": 2.001 | |
| }, | |
| "cumulative_reward": 2.001, | |
| "done": false, | |
| "termination_reason": null, | |
| "critical_failure_in_budget": false | |
| } | |
| ``` | |
| ### 1.2 Validation rules the loader enforces | |
| `App.jsx::onLoadFile` requires: | |
| - `parsed.rounds` is an array (may be empty for a freshly-started live run). | |
| - `parsed.config.sectors` exists. | |
| Everything else is run through `src/utils/normalizeEpisode.js`, which derives | |
| the optional fields below from the spec formulas in | |
| `specification/04_ECONOMY_MODEL.md`. The engine's lean output is enough. | |
| ### 1.3 Required vs derived fields (per round) | |
| | Field | Required | If missing, derived as | | |
| |---|---|---| | |
| | `round_num` | ✓ (or implied by index) | `index + 1` | | |
| | `treasury` *or* `treasury_after` | ✓ | uses whichever is present | | |
| | `treasury_before` | – | previous round's `treasury_after` (`config.initial_treasury` for round 1) | | |
| | `allocations[s]`, `revenues[s]`, `revenue_factors[s]`, `consumptions[s]` | ✓ | – | | |
| | `demands[s]` *or* `thresholds[s]` | ✓ (one of) | thresholds derived as `{0.4, 1.0, 1.5, 2.5} × demand` (spec 04) | | |
| | `event_multipliers[s]` | – | aggregated multiplicatively from `events[].affected_sectors` | | |
| | `total_allocation`, `total_revenue`, `surplus_returned` | – | summed from per-sector dicts | | |
| | `prosperity` | – | `total_revenue / population` (spec 09 base reward) | | |
| | `avg_revenue_factor` | – | mean of `revenue_factors[s]` | | |
| | `cumulative_reward` | – | running sum of `reward.total` | | |
| | `events[].is_positive` | – | true iff `treasury_injection > 0` or `category == "positive"` or every multiplier `< 1` | | |
| | `events[].treasury_injection` | – | `0` | | |
| | `debate`, `proposal_order`, `proposals`, `votes`, `vote_results` | – | empty (panel renders gracefully) | | |
| | `done`, `termination_reason`, `reward.*` | – | falsy / zero | | |
| **Critical-failure semantics** (per `core/game.py::_terminate()` + spec 04): | |
| the engine returns the round with `revenues = 0`, `revenue_factors = 0`, | |
| `consumptions = 0`, `surplus_returned = 0` for every sector and **does not | |
| debit the treasury** (the check fires in Phase 5a, before Phase 5b debit). | |
| The visualizer detects this with `done && termination_reason.startsWith("CRITICAL_FAILURE")`, | |
| flags the offending sector(s) (those with `allocation < critical`), greys out | |
| the rest, and labels the treasury cell as "frozen — failure before debit". | |
| --- | |
| ## 2. Live streaming | |
| The visualizer talks to `server/visualizer_server.py` over a tiny REST + SSE | |
| surface. The Vite dev server already proxies `/api/*` to | |
| `http://127.0.0.1:8001` (override with `VIZ_BACKEND_URL`). | |
| ### 2.1 Endpoints | |
| | Method | Path | Purpose | | |
| |---|---|---| | |
| | `GET` | `/api/health` | Liveness check. | | |
| | `GET` | `/api/config` | Visualizer-shaped `config` block (sectors, baselines, …). | | |
| | `GET` | `/api/modes` | Available inference modes (`llm` + rule-based baselines). | | |
| | `GET` | `/api/runs` | List recent runs. | | |
| | `POST` | `/api/runs` | Start a new run. Body: `{mode, model_id?, seed, max_rounds, temperature}`. Returns `{run_id, ...}`. | | |
| | `GET` | `/api/runs/{id}/snapshot` | Full episode-so-far in the §1 shape. | | |
| | `GET` | `/api/runs/{id}/stream` | SSE stream — see §2.2. | | |
| ### 2.2 SSE event types | |
| Each event arrives as `event: <type>\ndata: <json>\n\n`. The browser client in | |
| `src/utils/api.js` dispatches them into typed callbacks. | |
| | `event` | Payload | Notes | | |
| |---|---|---| | |
| | `start` | `{run_id, policy, mode, seed, config, max_rounds}` | Sent once on connection. | | |
| | `round` | A single per-round record (§1.1). | One per completed round. | | |
| | `summary` | The §1 `summary` block. | Sent once when the episode finishes. | | |
| | `error` | `{message: string}` | Adapter or engine failure. | | |
| | `done` | `{reason: "complete" \| "error" \| "already_closed"}` | Always the last event. | | |
| Late subscribers receive the full event history first (so refreshing the page | |
| mid-run replays from the beginning), then live updates. | |
| ### 2.3 Inference modes | |
| Modes returned from `/api/modes`: | |
| - `llm` — drives every minister with a Hugging Face Inference API model. | |
| Requires `HF_TOKEN` in the server `.env`; reads `HF_MODEL_ID` as the default | |
| model id (the form lets you override it per-run). | |
| - `equal_split`, `optimal_zone`, `conservative`, `greedy` — rule-based | |
| baselines from `agents/rule_based/`. Useful for offline demos. | |
| ### 2.4 Running locally | |
| Two terminals: | |
| ```bash | |
| # Terminal 1 — backend (FastAPI + SSE on :8001) | |
| python -m scripts.run_visualizer_server | |
| # Terminal 2 — frontend (Vite dev server on :5173) | |
| cd visualizer | |
| npm install # one time | |
| npm run dev | |
| ``` | |
| Open <http://localhost:5173>, pick a policy in the **Live inference** card, and | |
| press **Start run**. Rounds will stream into the dashboard as they're produced. | |
| --- | |
| ## 3. Static JSON files | |
| The static loader is unchanged. To export a recorded run, hit | |
| `GET /api/runs/{id}/snapshot` and save the response — the file matches the | |
| shape in §1 and can be dragged back into the visualizer at any time. | |
| --- | |
| ## 4. Development notes | |
| - `vite.config.js` has `server.watch.usePolling: true` because the project | |
| lives on a WSL-mounted Windows drive where `fs.watch()` throws `EISDIR`. | |
| Remove it on a normal filesystem to lower idle CPU. | |
| - For the very first run on Windows + WSL, install dependencies *inside* WSL | |
| (`wsl npm install`) to avoid `EPERM`/`EISDIR` cleanup errors, then run the | |
| build/dev server from either side. | |
| - The proxy block in `vite.config.js` strips response buffering for the | |
| `/stream` endpoint so SSE chunks arrive immediately even through the dev | |
| proxy. | |