# Squad Commander

a hybrid RTS where a low-frequency LLM commander re-prioritises a classical squad.

```{raw} html
<a class="example-run-button" href="../demos/demos_squad_commander.html">▶ Run in browser</a>

```

**Tags:** `ai` `llm` `rts` `agent`

Two layers, cleanly split:

- The **classical squad AI** is authoritative and runs **every frame**. Each blue
  unit is a dep-free ``Brain`` (``SquadUnitBrain``) that reads the shared squad
  plan off its blackboard and returns a concrete Action this frame: advance and
  attack the nearest red enemy (``attack``), hold position (``hold``), or fall back
  to the rally point (``retreat``). It imports no LLM code and runs identically
  whether or not a commander is present.

- The **LLM commander** is a stage, not the controller. A few seconds apart and
  entirely off the frame thread, ``SquadCommanderBrain`` asks the model for a typed
  battle plan (a strict ``stance`` / ``focus`` / ``target`` schema) and writes that
  one plan onto the *shared squad blackboard*, which every unit reads. A late /
  dropped / failed / malformed call keeps the last good plan; the squad never stalls
  and never depends on the model being present.

Drop the commander entirely and the squad still plays on the default plan: the LLM
is provably optional.

Run offline (default: a scripted fake commander reads the battlefield and swaps the
stance, after a trivial awaitable that proves the off-thread path):

    uv run python examples/demos/squad_commander.py

Run against a real model (records to a local cache so a re-run is deterministic):

    SIMVX_LLM_BASE_URL=http://host:8000/v1 SIMVX_LLM_MODEL=your-model         uv run python examples/demos/squad_commander.py --live

Controls: Space spawns a wave of red enemies (watch the commander switch to attack),
R forces a manual retreat order, Esc quits.

## Source

```{literalinclude} ../../examples/demos/squad_commander.py
:language: python
:linenos:
```