WARREN

WARREN (Workbench for Agent Research, Resilience, and Emergent Networks) is a MUD-inspired engine for simulating and evaluating populations of goal-directed AI agents.

The classic MUD split: one reusable driver, many configurable worlds. The kernel manages a typed graph world, deterministic action adjudication, simulated time, and telemetry. Scenarios — a six-zone war economy with raiders, a 100-person city evacuation, a Pokémon-like overworld, a Factorio-like factory, a saboteur among the repair crew — are declarative packages on a scenario micro-DSL, cheap enough to author that an experiment can vary one affordance at a time.

Agents observe text and act through typed tools. Spectators watch a top-down pixel-art view of the same world, live over WebSocket or from a recorded trace — every demo below is a single self-contained HTML file.

forge: ~90 agents mine, haul, smelt, assemble, and ship across six zones while raiders work the roads — ▶ watch it in your browser.

Live demos

▶ forge — six-zone economy, convoys, raiders (~90 agents)	▶ city_evacuation — rumors, random trains, rubble crews (100 agents)	▶ swarm_1000 — 1,000 agents across 20 districts
▶ train_evacuation	▶ overcooked_lite	▶ pokemon_lite
▶ bridge_repair	▶ factorio_lite	▶ saboteur_bridge

forge (militia on the frontier)	pokemon_lite	factorio_lite
train_evacuation (follow mode)	overcooked_lite	saboteur_bridge
city_evacuation (a 3-person crew clears the bridge)	bridge_repair	city_evacuation (100 agents)

agents (LLM / policy / scripted / remote)         spectators (browser)
        │  observations ⇄ decisions                       │  trace records
┌───────┴───────────────────────────────┐   ┌─────────────┴─────────────┐
│ runtime: sim clock · wake policies    │──▶│ viz: PixiJS viewer        │
│ durative plans · messages · processes │   │ (replay file or live WS)  │
├───────────────────────────────────────┤   └───────────────────────────┘
│ perception: sight radius · minimap    │
│ observation text (versioned)          │
├───────────────────────────────────────┤
│ core: typed graph world · params DSL  │
│ adjudication · deltas · event log     │
└───────────────────────────────────────┘
        ▲ scenarios: spaces · entities · packs · goals · theme · skin

Quickstart

uv sync --extra dev
uv run pytest                          # 178 tests
uv run python examples/record_demos.py # record all demo traces + viewers
open runs/forge.html                   # watch the six-zone economy run

Host a live simulation with spectators:

uv sync --extra serve
uv run uvicorn --factory warren.serve:app --port 8000
# open http://127.0.0.1:8000 → start a run → watch at /runs/run-1/viewer

Drive agents with Claude:

export ANTHROPIC_API_KEY=...
uv run python examples/llm_agents.py bridge_repair --pace 4

What a scenario looks like

s = ScenarioDef("bridge_repair", desc="Repair the bridge, resupply the clinic.")
s.space(RoomSpace("valley", rooms=(...), edges=(...)))
s.agent("engineer-1", skills=["repair.mechanical"], at="repair_camp", holds=["radio-1"])
s.fixture("bridge-1", at="bridge_deck",
          components=[Damageable(), Blocks(routes=(("bridge_deck", "north_bank"),))],
          state={"integrity": 0, "max_integrity": 2})
s.use(inventory_pack(), comms_pack(), damage_pack(), resources_pack(["medkit"]))
s.action(move_to_action(hop_ms=Duration(1_700, 2_400)))
s.goal("deliver_medkits", state_at_least("clinic-ward", "medkit", 2),
       "Deliver two medkits to the north clinic.", deadline_ms=240_000)
s.theme({"template:engineer": Glyph("🧑‍🔧", "E", "#f0c46c")})
scenario = s.build()   # validated; errors teach the fix

Documentation

Doc	For
User guide	running demos, the viewer's controls, live hosting, LLM agents, reading traces
Scenario catalog	what each of the eight scenarios is and exercises
Authoring guide	writing a new scenario on the micro-DSL, attaching a skin pack
Developer guide	engine internals, contracts, trace format, extension points
Remote agent protocol	warren-agent/0: driving agents from an external client over HTTP
DESIGN.md	why the architecture is shaped this way
ROADMAP.md	known gaps and what's next

Design pillars

• One binding layer. An action's typed params drive validation, affordance enumeration, and the LLM tool schema. No hand-written affordance code.
• Macro-movement. move_to pathfinds once and walks hop-by-hop as a durative plan with progress events — never one LLM inference per tile.
• Processes, not rounds. World dynamics run on the simulated clock, so a scenario behaves identically under every temporal policy.
• Explicit perception. Sight radius, hidden state, witness-dependent event visibility, ASCII minimaps — scenario knobs, not implementation accidents.
• Deterministic kernel. World transitions are a pure function of (genesis, action stream, seed); contention resolves via write-loci grouping.
• One artifact. The trace (genesis + event deltas + wakes) is the replay file, the live wire format, the scoring input, and the viewer's data.
• Skinnable worlds. A scenario can attach a skin pack — a data-only directory of sprite sheets and a skin.toml — turning the abstract world into animated pixel-art (4-direction walk cycles, tiles, props) without touching simulation or observations. Unskinned scenarios render fine.

Scale

The engine is event-driven: agents wake on messages, action completions, and local changes — never in lockstep. With scripted agents (no LLM calls) it runs 100 agents at ~50× realtime and 1,000 agents at ~1.2× realtime on a laptop (examples/bench_scale.py); in LLM-driven runs, inference dominates and the engine's sub-millisecond wakes keep any serving pool busy. The swarm_1000 demo is the 1,000-agent benchmark world, recorded and skinned.

Repository map

warren/core        world, components, params DSL, effects, adjudication engine
warren/runtime     sim clock, wake policies, durative plans, messages, processes
warren/space       grid/room compilers, pathfinding, move/move_to
warren/perception  visibility, observations, versioned text renderer, themes
warren/mechanics   packs: inventory, resources, comms, damage, vehicles,
                   production, encounters
warren/author      scenario micro-DSL + validation
warren/agents      scripted / random / policy runners
warren/analysis    scenario-agnostic trace summaries (python -m warren.analysis)
warren/protocol    warren-agent/0 wire models (briefings, envelopes, commands)
warren/remote      mailbox + RemoteRunner for external agent clients
warren/client      httpx client for the remote protocol
warren/viz         trace recorder + PixiJS viewer (single-file export & live)
warren/serve       FastAPI host: paced runs, WebSocket spectators, /v1 control plane
scenarios/         bridge_repair, train_evacuation, pokemon_lite, factorio_lite,
                   overcooked_lite, saboteur_bridge, city_evacuation (100 agents),
                   forge (six-zone economy) — plus skins/ (per-scenario art packs)

License

MIT — see LICENSE. Bundled art is CC0 and vendored libraries are MIT; see CREDITS.md.