Upload 18 files

pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "disaster_grid"
+version = "0.1.0"
+dependencies = [
+    "openenv-core",
+    "fastapi",
+    "uvicorn",
+    "pydantic",
+    "rich",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+]
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

src/disaster_grid.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: disaster_grid
+Version: 0.1.0
+Requires-Dist: openenv-core
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: pydantic
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"

src/disaster_grid.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+pyproject.toml
+src/disaster_grid/__init__.py
+src/disaster_grid/environment.py
+src/disaster_grid/models.py
+src/disaster_grid/rewards.py
+src/disaster_grid/utils.py
+src/disaster_grid.egg-info/PKG-INFO
+src/disaster_grid.egg-info/SOURCES.txt
+src/disaster_grid.egg-info/dependency_links.txt
+src/disaster_grid.egg-info/requires.txt
+src/disaster_grid.egg-info/top_level.txt
+tests/test_env.py

src/disaster_grid.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/disaster_grid.egg-info/requires.txt

@@ -0,0 +1,8 @@
+openenv-core
+fastapi
+uvicorn
+pydantic
+rich
+
+[dev]
+pytest

src/disaster_grid.egg-info/top_level.txt

@@ -0,0 +1 @@
+disaster_grid

src/disaster_grid/environment.py

@@ -0,0 +1,522 @@
+"""
+src/disaster_grid/environment.py
+=================================
+Core OpenEnv environment for the disaster_grid hackathon project.
+
+Architecture overview
+---------------------
+``CityGrid`` inherits from ``openenv.AutoEnv`` and implements the standard
+``reset`` / ``step`` interface.  It owns the full physics simulation:
+
+* **Grid state** – 25 sector health values mutated by entropy and REPAIR.
+* **Agent state** – position and energy, mutated by movement, repair, and
+  recharge actions.
+* **Observation factory** – ``_get_observation()`` distils the raw grid into
+  the token-efficient ``GridObservation`` schema the LLM sees.
+* **Receipt factory** – ``step()`` assembles a ``StepResult`` that the
+  external reward verifiers in ``rewards.py`` consume.  The environment
+  itself always returns ``reward=0.0``; actual reward computation is
+  deliberately decoupled so verifier weights can be tuned without touching
+  environment logic.
+
+Step contract
+-------------
+``step(action)`` accepts either a raw JSON string (as emitted by the LLM) or
+a pre-parsed ``dict``.  If parsing or Pydantic validation fails the step is
+treated as a ``WAIT`` with ``is_error=True`` recorded in the receipt, giving
+the R3 format verifier a clean signal without crashing the episode.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+from typing import Any
+import openenv
+
+from pydantic import ValidationError
+
+from .models import ActionType, AgentAction, GridObservation, SectorState, StepResult
+
+# ── Grid constants ────────────────────────────────────────────────────────────
+
+_GRID_SIZE: int = 5                    # edge length of the square grid
+_NUM_SECTORS: int = _GRID_SIZE ** 2   # 25 total sectors
+
+# ── Action energy costs and effects ──────────────────────────────────────────
+
+_MOVE_COST: int = 2                    # energy deducted per move attempt (wall or not)
+_REPAIR_COST: int = 15                 # energy deducted per REPAIR
+_REPAIR_GAIN: int = 25                 # health added to current sector per REPAIR
+_RECHARGE_STATION: int = 12           # center sector where RECHARGE is valid
+_RECHARGE_GAIN: int = 20              # energy added per valid RECHARGE (at sector 12)
+_RECHARGE_WRONG_COST: int = 1         # energy penalty for RECHARGE outside sector 12
+_WAIT_COST: int = 1                    # energy deducted per WAIT
+
+# ── Entropy constants ─────────────────────────────────────────────────────────
+
+_ENTROPY_SECTORS_PER_STEP: int = 2    # sectors degraded each step
+_ENTROPY_DAMAGE: int = 5              # health lost per entropy tick
+
+# ── Initial state constants ───────────────────────────────────────────────────
+
+_INIT_HEALTH_LOW: int = 50            # minimum random starting health
+_INIT_HEALTH_HIGH: int = 100          # maximum random starting health
+_CRISIS_HEALTH: int = 20             # health value forced onto crisis sectors at reset
+_NUM_CRISIS_SECTORS: int = 5          # sectors forced into crisis at reset
+
+# ── Episode limit ─────────────────────────────────────────────────────────────
+
+_MAX_STEPS: int = 50
+
+
+class CityGrid(openenv.AutoEnv):
+    """
+    A 5 × 5 disaster-recovery grid environment compliant with the OpenEnv API.
+
+    The city is partitioned into 25 sectors indexed 0–24 in row-major order::
+
+        (0,0) (1,0) (2,0) (3,0) (4,0)   →  indices  0– 4
+        (0,1) (1,1) (2,1) (3,1) (4,1)   →  indices  5– 9
+        (0,2) (1,2) (2,2) (3,2) (4,2)   →  indices 10–14
+        (0,3) (1,3) (2,3) (3,3) (4,3)   →  indices 15–19
+        (0,4) (1,4) (2,4) (3,4) (4,4)   →  indices 20–24
+
+    Sector 12 is the center cell and serves as the only recharge station.
+
+    Episode dynamics
+    ----------------
+    Each call to ``step()`` executes the following sequence in strict order:
+
+    1. Snapshot agent and grid state *before* any mutation.
+    2. Parse and validate the action string / dict from the LLM.
+    3. Execute the action (energy deduction, position update, health change).
+    4. Apply entropy (2 random sectors lose 5 health).
+    5. Snapshot agent and grid state *after* mutations.
+    6. Increment step counter; check termination.
+    7. Build and return the ``StepResult`` receipt in ``info``.
+
+    The reward returned by ``step()`` is always ``0.0``.  Real rewards are
+    computed externally by the three verifiers in ``rewards.py`` using the
+    ``StepResult`` embedded in the ``info`` dict.  This separation means
+    verifier weights and reward shaping can be changed without modifying or
+    re-testing environment physics.
+
+    Attributes
+    ----------
+    grid_health : list[int]
+        Current health values for all 25 sectors.  Index ``i`` corresponds to
+        the sector at coordinate ``_index_to_coord(i)``.
+    agent_pos : int
+        Flat sector index (0–24) of the agent's current position.
+    agent_energy : int
+        Current energy reserve (0–100).  The episode terminates immediately
+        when this reaches 0.
+    step_count : int
+        Number of completed steps in the current episode.
+    """
+
+    # ── Initialisation ────────────────────────────────────────────────────────
+
+    def __init__(self) -> None:
+        """
+        Instantiate the environment without starting an episode.
+
+        State variables are set to sentinel values (all zeros / empty list)
+        until the caller invokes ``reset()``.  This mirrors the convention used
+        by Gymnasium and OpenEnv so the environment can be constructed cheaply
+        inside a trainer worker without triggering random-number generation.
+        """
+      
+        self.grid_health: list[int] = [0] * _NUM_SECTORS
+        self.agent_pos: int = 0
+        self.agent_energy: int = 0
+        self.step_count: int = 0
+
+    # ── Private helpers ───────────────────────────────────────────────────────
+
+    @staticmethod
+    def _index_to_coord(index: int) -> tuple[int, int]:
+        """
+        Convert a flat row-major sector index to an (x, y) coordinate pair.
+
+        The coordinate system places (0, 0) at the top-left corner:
+
+        * ``x`` is the column (0 = leftmost,  4 = rightmost).
+        * ``y`` is the row    (0 = topmost,    4 = bottommost).
+
+        Parameters
+        ----------
+        index : int
+            Flat sector index in [0, 24].
+
+        Returns
+        -------
+        tuple[int, int]
+            ``(x, y)`` where ``x = index % 5`` and ``y = index // 5``.
+
+        Examples
+        --------
+        >>> CityGrid._index_to_coord(0)
+        (0, 0)
+        >>> CityGrid._index_to_coord(7)
+        (2, 1)
+        >>> CityGrid._index_to_coord(24)
+        (4, 4)
+        """
+        return index % _GRID_SIZE, index // _GRID_SIZE
+
+    @staticmethod
+    def _coord_to_index(x: int, y: int) -> int:
+        """
+        Convert an (x, y) coordinate pair to a flat row-major sector index.
+
+        Parameters
+        ----------
+        x : int
+            Column index in [0, 4].
+        y : int
+            Row index in [0, 4].
+
+        Returns
+        -------
+        int
+            Flat sector index ``y * 5 + x`` in [0, 24].
+
+        Examples
+        --------
+        >>> CityGrid._coord_to_index(0, 0)
+        0
+        >>> CityGrid._coord_to_index(2, 1)
+        7
+        >>> CityGrid._coord_to_index(4, 4)
+        24
+        """
+        return y * _GRID_SIZE + x
+
+    def _get_observation(self) -> GridObservation:
+        """
+        Distil current world state into the token-efficient ``GridObservation``
+        schema consumed by the LLM.
+
+        This method intentionally omits the full ``grid_health`` list from the
+        observation.  Passing 25 integers per step at a 50-step horizon costs
+        approximately 1 250 extra tokens per episode — nearly doubling prompt
+        length in a GRPO batch.  Instead the method computes:
+
+        * **average_city_health** – a single float that summarises the global
+          state and correlates with the R1 verifier's reward signal.
+        * **critical_sectors** – a sorted list of indices whose health is below
+          30, giving the agent the minimum routing information needed to plan
+          an optimal repair trajectory.
+
+        Returns
+        -------
+        GridObservation
+            A validated Pydantic model ready for ``model_dump()`` or
+            ``model_dump_json()``.
+        """
+        average_health: float = round(sum(self.grid_health) / _NUM_SECTORS, 2)
+        critical: list[int] = sorted(
+            i for i, h in enumerate(self.grid_health) if h < 30
+        )
+        return GridObservation(
+            step_number=self.step_count,
+            agent_position=self.agent_pos,
+            agent_energy=self.agent_energy,
+            current_sector_health=self.grid_health[self.agent_pos],
+            critical_sectors=critical,
+            average_city_health=average_health,
+        )
+
+    def _apply_entropy(self) -> None:
+        """
+        Degrade two randomly chosen distinct sectors by ``_ENTROPY_DAMAGE``
+        (5) health points, floored at 0.
+
+        Entropy is applied **after** the agent's action each step.  This
+        ordering means a REPAIR action's +25 gain is always partially offset by
+        entropy before the post-step snapshot is taken, preventing the agent
+        from achieving a perfect +25 net gain on a single step and thus
+        maintaining a meaningful resource-management challenge across the full
+        50-step horizon.
+
+        The two sectors are chosen without replacement so the same sector
+        cannot be hit twice in a single entropy tick (which would amount to
+        -10 health and skew the difficulty distribution).
+        """
+        targets: list[int] = random.sample(
+            range(_NUM_SECTORS), _ENTROPY_SECTORS_PER_STEP
+        )
+        for idx in targets:
+            self.grid_health[idx] = max(0, self.grid_health[idx] - _ENTROPY_DAMAGE)
+
+    # ── OpenEnv API ───────────────────────────────────────────────────────────
+
+    def reset(
+        self,
+        seed: int | None = None,
+        options: dict | None = None,
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        """
+        Begin a new episode and return the initial observation.
+
+        The reset procedure deliberately creates an adversarial starting state:
+        five sectors are forced to health 20 (below the critical threshold of
+        30) so the agent faces immediate triage decisions rather than deferring
+        all repair work to the second half of the episode.  This biases the
+        training distribution toward high-action-density rollouts, which
+        produce richer GRPO gradient signal than episodes where the agent
+        coasts on a healthy grid.
+
+        Parameters
+        ----------
+        seed : int | None
+            If provided, seeds Python's ``random`` module before any stochastic
+            operation.  Pass an integer for reproducible evaluation episodes;
+            leave as ``None`` during training to sample diverse rollouts.
+        options : dict | None
+            Reserved for future configuration (e.g. custom entropy rates or
+            forced agent starting positions).  Ignored in the current version.
+
+        Returns
+        -------
+        observation : dict
+            ``GridObservation.model_dump()`` representing the initial world
+            state.  The agent starts at sector 12 with full energy and faces
+            at least five critical sectors.
+        info : dict
+            Empty dict.  Provided for API compatibility with OpenEnv / Gym.
+        """
+        if seed is not None:
+            random.seed(seed)
+
+        # ── Reset counters ─────────────────────────────────────────────────
+        self.step_count = 0
+        self.agent_energy = 100
+        self.agent_pos = _RECHARGE_STATION
+
+        # ── Randomise grid health ──────────────────────────────────────────
+        self.grid_health = [
+            random.randint(_INIT_HEALTH_LOW, _INIT_HEALTH_HIGH)
+            for _ in range(_NUM_SECTORS)
+        ]
+
+        # ── Force five crisis sectors, excluding sector 12 so the recharge
+        #    station always starts accessible and reachable ─────────────────
+        crisis_candidates: list[int] = random.sample(
+            [idx for idx in range(_NUM_SECTORS) if idx != _RECHARGE_STATION],
+            _NUM_CRISIS_SECTORS,
+        )
+        for idx in crisis_candidates:
+            self.grid_health[idx] = _CRISIS_HEALTH
+
+        return self._get_observation().model_dump(), {}
+
+    def step(
+        self,
+        action: str | dict,
+    ) -> tuple[dict[str, Any], float, bool, bool, dict[str, Any]]:
+        """
+        Advance the environment by one step and return the standard 5-tuple.
+
+        The method follows a strict execution pipeline to ensure that the
+        ``StepResult`` receipt always contains consistent before/after
+        snapshots regardless of whether the action was valid:
+
+        1. **Pre-snapshot** – capture ``energy_before`` and
+           ``city_health_before`` before any mutation.
+        2. **Parse** – attempt to deserialise ``action`` into ``AgentAction``.
+           On failure, mark ``is_error=True`` and skip to step 5.  The step
+           acts as a free turn: no energy is deducted for an invalid action,
+           but entropy still applies and the step counter still increments.
+           The error is surfaced to the R3 verifier via ``StepResult``.
+        3. **Execute** – apply the validated action's physics (energy cost,
+           position update, health change).
+        4. **Entropy** – call ``_apply_entropy()`` to degrade two random
+           sectors.
+        5. **Post-snapshot** – capture ``energy_after`` and
+           ``city_health_after``.
+        6. **Bookkeeping** – increment ``step_count``; evaluate termination.
+        7. **Receipt** – build ``StepResult`` and embed in ``info``.
+
+        Parameters
+        ----------
+        action : str | dict
+            The LLM's response, either as a raw JSON string or a pre-parsed
+            dict (the latter is used by the synthetic data generator and unit
+            tests).
+
+        Returns
+        -------
+        observation : dict
+            ``GridObservation.model_dump()`` for the state *after* this step.
+        reward : float
+            Always ``0.0``.  Real rewards are computed by ``rewards.py`` using
+            ``info["step_result"]``.
+        terminated : bool
+            ``True`` when the episode has ended due to energy depletion
+            (``agent_energy <= 0``) or the 50-step limit (``step_count >= 50``).
+        truncated : bool
+            Always ``False``.  Time-limit termination is modelled via
+            ``terminated`` so the GRPO trainer does not need to handle the
+            truncated case separately.
+        info : dict
+            Contains ``"step_result"`` → ``StepResult.model_dump()``, the
+            verifier receipt used by ``rewards.py`` to compute R1, R2, and R3.
+
+        Notes
+        -----
+        **Wall collision** – a move that would take the agent off the grid is
+        silently blocked (position unchanged) but the energy cost is still
+        applied.  This punishes the agent for poor pathing without requiring
+        boundary-check logic inside the reward verifiers.
+
+        **RECHARGE outside sector 12** – deducts ``_RECHARGE_WRONG_COST`` (1)
+        energy and sets ``is_error=True``.  The deliberately small penalty
+        keeps the training signal proportional; a large penalty would dominate
+        the R2 efficiency term and cause the agent to avoid RECHARGE entirely.
+        """
+        # ── 1. Pre-snapshot ───────────────────────────────────────────────
+        energy_before: int = self.agent_energy
+        city_health_before: float = sum(self.grid_health) / _NUM_SECTORS
+
+        # ── 2. Parse action ───────────────────────────────────────────────
+        parsed_action: AgentAction | None = None
+        is_error: bool = False
+        error_message: str = ""
+        if isinstance(action, str):
+            action_attempted = action
+        else:
+            try:
+                action_attempted = json.dumps(action)
+            except (TypeError, ValueError):
+                action_attempted = repr(action)
+
+        try:
+            raw: dict = json.loads(action) if isinstance(action, str) else action
+            parsed_action = AgentAction(**raw)
+        except (json.JSONDecodeError, ValidationError, TypeError) as exc:
+            is_error = True
+            error_message = (
+                f"Action parse failed ({type(exc).__name__}): {exc!s}"
+            )
+
+        # ── 3. Execute action (no-op on parse error) ──────────────────────
+        if not is_error and parsed_action is not None:
+            action_type: ActionType = parsed_action.action
+            x, y = self._index_to_coord(self.agent_pos)
+
+            if action_type in (
+                ActionType.MOVE_N,
+                ActionType.MOVE_S,
+                ActionType.MOVE_E,
+                ActionType.MOVE_W,
+            ):
+                # Energy cost is always applied, even on wall collision.
+                self.agent_energy = max(0, self.agent_energy - _MOVE_COST)
+
+                new_x, new_y = x, y
+                if action_type is ActionType.MOVE_N:
+                    new_y = y - 1
+                elif action_type is ActionType.MOVE_S:
+                    new_y = y + 1
+                elif action_type is ActionType.MOVE_E:
+                    new_x = x + 1
+                elif action_type is ActionType.MOVE_W:
+                    new_x = x - 1
+
+                if 0 <= new_x < _GRID_SIZE and 0 <= new_y < _GRID_SIZE:
+                    self.agent_pos = self._coord_to_index(new_x, new_y)
+                # else: position unchanged; collision already penalised above.
+
+            elif action_type is ActionType.REPAIR:
+                self.agent_energy = max(0, self.agent_energy - _REPAIR_COST)
+                self.grid_health[self.agent_pos] = min(
+                    100, self.grid_health[self.agent_pos] + _REPAIR_GAIN
+                )
+
+            elif action_type is ActionType.RECHARGE:
+                if self.agent_pos == _RECHARGE_STATION:
+                    self.agent_energy = min(100, self.agent_energy + _RECHARGE_GAIN)
+                else:
+                    self.agent_energy = max(
+                        0, self.agent_energy - _RECHARGE_WRONG_COST
+                    )
+                    is_error = True
+                    error_message = (
+                        f"RECHARGE attempted at sector {self.agent_pos} "
+                        f"(valid only at sector 12). "
+                        f"Penalty: -{_RECHARGE_WRONG_COST} energy."
+                    )
+
+            elif action_type is ActionType.WAIT:
+                self.agent_energy = max(0, self.agent_energy - _WAIT_COST)
+
+        # ── 4. Apply entropy ──────────────────────────────────────────────
+        self._apply_entropy()
+
+        # ── 5. Post-snapshot ──────────────────────────────────────────────
+        energy_after: int = self.agent_energy
+        city_health_after: float = sum(self.grid_health) / _NUM_SECTORS
+
+        # ── 6. Bookkeeping ────────────────────────────────────────────────
+        self.step_count += 1
+        terminated: bool = (
+            self.agent_energy <= 0 or self.step_count >= _MAX_STEPS
+        )
+
+        # ── 7. Assemble receipt ───────────────────────────────────────────
+        step_result = StepResult(
+            action_attempted=action_attempted,
+            action_parsed=parsed_action,
+            energy_before=energy_before,
+            energy_after=energy_after,
+            city_health_before=round(city_health_before, 2),
+            city_health_after=round(city_health_after, 2),
+            is_error=is_error,
+            error_message=error_message,
+        )
+
+        return (
+            self._get_observation().model_dump(),
+            0.0,
+            terminated,
+            False,
+            {"step_result": step_result.model_dump()},
+        )
+
+    # ── Utility ───────────────────────────────────────────────────────────────
+
+    def render(self) -> list[SectorState]:
+        """
+        Return the current grid as a list of ``SectorState`` objects.
+
+        This method is consumed by ``utils.py``'s emoji-grid visualiser during
+        debugging and live demo sessions.  It is not called during training.
+
+        Returns
+        -------
+        list[SectorState]
+            One ``SectorState`` per sector (indices 0–24), in row-major order.
+        """
+        return [
+            SectorState(index=i, health=h)
+            for i, h in enumerate(self.grid_health)
+        ]
+
+    def get_action_space(self) -> list[str]:
+        """
+        Return the sorted list of valid action strings.
+
+        Mirrors the ``ActionType`` enum values so external tooling (e.g. the
+        synthetic data generator in ``train/synthetic_data.json``) can
+        enumerate valid actions without importing ``models.py`` directly.
+
+        Returns
+        -------
+        list[str]
+            Sorted list of action name strings, e.g.
+            ``["MOVE_E", "MOVE_N", "MOVE_S", "MOVE_W", "RECHARGE", "REPAIR", "WAIT"]``.
+        """
+        return sorted(a.value for a in ActionType)

src/disaster_grid/models.py

@@ -0,0 +1,446 @@
+"""
+src/disaster_grid/models.py
+============================
+Pydantic schemas and enumerations for the disaster_grid OpenEnv environment.
+
+Design philosophy
+-----------------
+All data structures that cross a module boundary are defined here so that
+`environment.py`, `rewards.py`, and `grpo_trainer.py` share a single source
+of truth.  Pydantic is chosen over `dataclasses` for three reasons:
+
+1. **FastAPI integration** – every model serialises to / deserialises from
+   JSON with zero extra work, enabling a `/step` endpoint with no adapter
+   layer.
+2. **Runtime validation** – `Field` constraints (ge, le, min_length …) are
+   enforced at construction time, so an out-of-range energy value raises a
+   clear `ValidationError` rather than silently corrupting training data.
+3. **LLM prompt hygiene** – `model.model_dump_json()` produces the exact JSON
+   string we can embed in a system prompt, keeping the schema the LLM is
+   trained on perfectly in sync with the schema the environment enforces.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field, computed_field, model_validator
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Enumerations
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class ActionType(str, Enum):
+    """
+    The complete set of actions available to the disaster-recovery agent.
+
+    Inheriting from ``str`` means Pydantic serialises these as plain strings
+    (e.g. ``"MOVE_N"``), which is what the LLM will emit and what FastAPI
+    will accept in a JSON body without any custom encoder.
+
+    Members
+    -------
+    MOVE_N
+        Move the agent one row upward  (row -= 1).
+        Energy cost: -2.  Invalid if the agent is already on row 0.
+    MOVE_S
+        Move the agent one row downward (row += 1).
+        Energy cost: -2.  Invalid if the agent is already on row 4.
+    MOVE_E
+        Move the agent one column rightward (col += 1).
+        Energy cost: -2.  Invalid if the agent is already on col 4.
+    MOVE_W
+        Move the agent one column leftward  (col -= 1).
+        Energy cost: -2.  Invalid if the agent is already on col 0.
+    REPAIR
+        Repair the sector the agent currently occupies.
+        Energy cost: -15.  Sector health gain: +25 (capped at 100).
+        Has no effect if sector health is already 100.
+    RECHARGE
+        Replenish the agent's energy reserve.
+        Energy gain: +20 (capped at 100).
+        **Only valid at sector index 12** (the recharge station at the center).
+        Attempting RECHARGE elsewhere is treated as a no-op with an error flag.
+    WAIT
+        The agent stays in place and takes no action.
+        No energy cost.  Entropy still applies.
+        Useful when the agent is awaiting a recharge opportunity or has no
+        repair targets within reach.
+    """
+
+    MOVE_N = "MOVE_N"
+    MOVE_S = "MOVE_S"
+    MOVE_E = "MOVE_E"
+    MOVE_W = "MOVE_W"
+    REPAIR = "REPAIR"
+    RECHARGE = "RECHARGE"
+    WAIT = "WAIT"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Primitive domain models
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class SectorState(BaseModel):
+    """
+    The state of a single cell in the 5 × 5 city grid.
+
+    The grid uses row-major indexing: sector ``index = row * 5 + col``.
+    Sector 0  is the top-left corner.
+    Sector 24 is the bottom-right corner.
+
+    ``SectorState`` objects are held in ``environment.py``'s internal grid
+    list and are **not** passed directly to the LLM – they are too verbose
+    for a 50-step prompt budget.  Only derived summaries (average health,
+    critical indices) appear in ``GridObservation``.
+
+    Fields
+    ------
+    index : int
+        Flat grid index in [0, 24].  Immutable after construction.
+    health : int
+        Current health of the sector in [0, 100].
+        0  → sector is completely degraded (city infrastructure lost).
+        100 → sector is at full operational capacity.
+        Mutated by the environment's entropy step and by REPAIR actions.
+    """
+
+    index: int = Field(
+        ...,
+        ge=0,
+        le=24,
+        description="Flat row-major index of this sector within the 5×5 grid.",
+    )
+    health: int = Field(
+        ...,
+        ge=0,
+        le=100,
+        description="Current sector health.  Degraded by entropy; restored by REPAIR.",
+    )
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def is_critical(self) -> bool:
+        """
+        Return ``True`` when this sector requires urgent intervention.
+
+        A sector is *critical* when its health drops below 30.  Critical
+        sectors are surfaced to the LLM in ``GridObservation.critical_sectors``
+        so the agent can prioritise routing decisions without scanning the
+        full grid.
+
+        The threshold (30) is a domain constant chosen so that a single
+        entropy tick of -5 would push a critical sector to health 25, giving
+        the agent at most ~5 additional steps before the sector reaches 0.
+        """
+        return self.health < 30
+
+    @model_validator(mode="after")
+    def _clamp_health(self) -> "SectorState":
+        """Silently clamp health into [0, 100] after any mutation helper."""
+        self.health = max(0, min(100, self.health))
+        return self
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LLM-facing observation schema
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class GridObservation(BaseModel):
+    """
+    The structured observation delivered to the LLM at the start of each step.
+
+    **Token budget rationale** – a naïve approach would serialise all 25
+    ``SectorState`` objects (~200 tokens per step × 50 steps = 10 000 tokens
+    per episode).  Instead this model passes:
+
+    * The agent's current coordinates and energy.
+    * The health of only the sector the agent stands on (immediately
+      actionable information).
+    * The *average* city health (global signal for the R1 verifier proxy).
+    * The flat indices of *critical* sectors (health < 30) so the agent can
+      plan efficient routes without enumerating the whole grid.
+
+    This reduces observation size to ~60 tokens per step while preserving all
+    information required for rational decision-making.
+
+    The environment serialises this as a JSON string and injects it into the
+    LLM prompt as the ``<observation>`` block.
+
+    Fields
+    ------
+    step_number : int
+        Current step in [0, 50].  Lets the agent reason about remaining
+        horizon (e.g. "I have 10 steps left, is a recharge trip worth it?").
+    agent_position : int
+        Flat index of the agent's current sector.  Combined with the 5-wide
+        grid, the agent can derive (row, col) via ``divmod(position, 5)``.
+    agent_energy : int
+        Current energy in [0, 100].  The done condition fires at 0.
+    current_sector_health : int
+        Health of the sector at ``agent_position``.  Included so the agent
+        can decide *immediately* whether to REPAIR here or move elsewhere.
+    critical_sectors : list[int]
+        Sorted list of sector indices whose health is below 30.  May be
+        empty.  The agent should prefer routing to the nearest element of
+        this list.  Presented in ascending index order so prompt content is
+        deterministic across identical states (useful for reproducible evals).
+    average_city_health : float
+        Mean health across all 25 sectors, rounded to two decimal places.
+        Acts as the agent's running score proxy.  A strategic agent should
+        try to keep this above 70.0.
+    """
+
+    step_number: int = Field(
+        ...,
+        ge=0,
+        le=50,
+        description="Current environment step.  Episode ends at step 50.",
+    )
+    agent_position: int = Field(
+        ...,
+        ge=0,
+        le=24,
+        description="Flat index of the agent's current grid position.",
+    )
+    agent_energy: int = Field(
+        ...,
+        ge=0,
+        le=100,
+        description="Remaining energy units.  Episode ends immediately if this reaches 0.",
+    )
+    current_sector_health: int = Field(
+        ...,
+        ge=0,
+        le=100,
+        description="Health of the sector currently occupied by the agent.",
+    )
+    critical_sectors: list[int] = Field(
+        default_factory=list,
+        description=(
+            "Sorted indices of sectors with health < 30.  "
+            "Empty list means no sectors are currently critical."
+        ),
+    )
+    average_city_health: float = Field(
+        ...,
+        ge=0.0,
+        le=100.0,
+        description="Mean health across all 25 sectors, rounded to 2 d.p.",
+    )
+
+    @model_validator(mode="after")
+    def _validate_critical_sectors(self) -> "GridObservation":
+        """Ensure all critical sector indices are within the valid grid range."""
+        for idx in self.critical_sectors:
+            if not (0 <= idx <= 24):
+                raise ValueError(
+                    f"critical_sectors contains out-of-range index {idx!r}. "
+                    "All indices must be in [0, 24]."
+                )
+        return self
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LLM output schema (action payload)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class AgentAction(BaseModel):
+    """
+    The structured JSON payload the LLM must emit in response to each
+    ``GridObservation``.
+
+    **Two-field design** – separating ``reasoning`` from ``action`` is a
+    deliberate inductive bias:
+
+    * ``reasoning`` is placed *first* in the schema so that the LLM is
+      forced to produce a chain-of-thought (CoT) token sequence before
+      committing to an ``action`` token.  Empirically, CoT prefix generation
+      significantly improves action quality on multi-step planning tasks.
+    * ``action`` is validated against ``ActionType`` at parse time, so any
+      hallucinated action string (e.g. ``"MOVE_NE"``) raises a
+      ``ValidationError`` that the environment catches and converts into a
+      ``StepResult`` with ``is_error=True``.  This error signal flows through
+      to the R3 (format) verifier.
+
+    The GRPO trainer embeds the ``model_json_schema()`` of this class in the
+    system prompt so the LLM always sees the exact schema it is being graded
+    against.
+
+    Fields
+    ------
+    reasoning : str
+        A free-text explanation (minimum 10 characters) of *why* the agent
+        chose this action given the current observation.  Enforcing a minimum
+        length discourages degenerate single-token rationales.  The ``rewards``
+        module does **not** score reasoning quality – it is included purely as
+        a CoT generation mechanism during GRPO fine-tuning.
+    action : ActionType
+        The chosen action from the ``ActionType`` enum.  Must be one of the
+        seven valid strings; anything else will fail Pydantic validation.
+    """
+
+    reasoning: str = Field(
+        ...,
+        min_length=10,
+        description=(
+            "Chain-of-thought rationale produced *before* the action token.  "
+            "Forces the model to reason about position, energy, and critical "
+            "sectors prior to committing to a move.  Not scored by verifiers."
+        ),
+    )
+    action: ActionType = Field(
+        ...,
+        description=(
+            "The discrete action to execute this step.  Must be a member of "
+            "ActionType.  Invalid strings cause a ValidationError that is "
+            "captured as is_error=True in StepResult and penalised by R3."
+        ),
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Verifier receipt (internal – never seen by the LLM)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class StepResult(BaseModel):
+    """
+    A complete record of everything that happened during one environment step.
+
+    ``StepResult`` is the *contract* between ``environment.py`` and
+    ``rewards.py``.  It is constructed by ``CityGrid.step()`` and passed
+    directly to the three reward verifiers – neither module needs to
+    re-execute environment logic to calculate its score.
+
+    **Why a separate receipt model?**  Each verifier reads a different subset
+    of fields:
+
+    * R1 (health)       reads ``city_health_before`` / ``city_health_after``.
+    * R2 (efficiency)   reads ``energy_before`` / ``energy_after`` plus the
+                        city health delta.
+    * R3 (format)       reads ``action_attempted`` and ``action_parsed``
+                        (``None`` means parse failed → score 0.0).
+
+    Passing a single rich object avoids fragile argument lists and keeps
+    verifier signatures stable as the environment evolves.
+
+    This model is **never serialised into the LLM prompt**.  It is used
+    exclusively within the Python training loop.
+
+    Fields
+    ------
+    action_attempted : str
+        The raw string the LLM emitted (or the trainer injected for synthetic
+        rollouts).  Preserved verbatim so R3 can detect subtle schema
+        violations even when Pydantic parsing partially succeeds.
+    action_parsed : AgentAction | None
+        The validated ``AgentAction`` object if ``action_attempted`` was valid
+        JSON conforming to the schema; ``None`` otherwise.  ``None`` is a
+        direct penalty signal for R3.
+    energy_before : int
+        Agent energy at the *start* of this step, before the action was
+        applied.  Used by R2 to compute energy expenditure.
+    energy_after : int
+        Agent energy at the *end* of this step, after the action (and any
+        recharge) was applied.  R2 uses ``energy_before - energy_after`` as
+        the cost denominator.
+    city_health_before : float
+        Average city health across all 25 sectors *before* this step's
+        entropy tick and repair.  R1 and R2 use this as the baseline.
+    city_health_after : float
+        Average city health *after* entropy and the agent's action.
+        ``city_health_after - city_health_before`` is the net health delta
+        for this step; positive values indicate the agent added more value
+        than entropy removed.
+    is_error : bool
+        ``True`` when the action could not be executed for any reason:
+        invalid JSON, invalid ``ActionType``, illegal move (e.g. MOVE_N from
+        row 0), or RECHARGE attempted outside sector 12.  An error step is a
+        no-op for the environment but still incurs entropy.
+    error_message : str
+        Human-readable description of the error.  Empty string when
+        ``is_error`` is ``False``.  Surfaced in training logs and unit tests
+        to aid debugging without re-running the full episode.
+    """
+
+    action_attempted: str = Field(
+        ...,
+        description=(
+            "Raw LLM output string, preserved verbatim for R3 format scoring "
+            "and debugging.  Never parsed or executed after this field is set."
+        ),
+    )
+    action_parsed: Optional[AgentAction] = Field(
+        default=None,
+        description=(
+            "Validated AgentAction if action_attempted was schema-compliant; "
+            "None if JSON parsing or Pydantic validation failed.  "
+            "None is the primary R3 penalty signal."
+        ),
+    )
+    energy_before: int = Field(
+        ...,
+        ge=0,
+        le=100,
+        description="Agent energy at step start, used as R2 cost baseline.",
+    )
+    energy_after: int = Field(
+        ...,
+        ge=0,
+        le=100,
+        description="Agent energy at step end, after action execution.",
+    )
+    city_health_before: float = Field(
+        ...,
+        ge=0.0,
+        le=100.0,
+        description="Mean sector health before this step's entropy + repair.",
+    )
+    city_health_after: float = Field(
+        ...,
+        ge=0.0,
+        le=100.0,
+        description="Mean sector health after this step's entropy + repair.",
+    )
+    is_error: bool = Field(
+        default=False,
+        description=(
+            "True when the action was invalid or illegal.  "
+            "The environment applies entropy but skips action execution."
+        ),
+    )
+    error_message: str = Field(
+        default="",
+        description=(
+            "Diagnostic message when is_error is True.  "
+            "Empty string on successful steps."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _error_message_consistency(self) -> "StepResult":
+        """
+        Enforce that ``error_message`` is non-empty iff ``is_error`` is True.
+
+        This prevents silent failures where an error condition is set but the
+        message is accidentally cleared (or vice-versa), which would make
+        training logs misleading.
+        """
+        if self.is_error and not self.error_message:
+            raise ValueError(
+                "is_error is True but error_message is empty.  "
+                "Provide a diagnostic string so training logs are actionable."
+            )
+        if not self.is_error and self.error_message:
+            raise ValueError(
+                "error_message is set but is_error is False.  "
+                "Either set is_error=True or clear error_message."
+            )
+        return self

src/disaster_grid/rewards.py

@@ -0,0 +1,341 @@
+"""
+src/disaster_grid/rewards.py
+=============================
+Three independent reward verifiers for the disaster_grid GRPO training loop.
+
+Design philosophy — why three verifiers?
+-----------------------------------------
+A single monolithic reward function is trivially hackable: the agent learns
+whatever shortcut maximises the scalar without learning the intended behaviour.
+Splitting the reward across three *orthogonal* verifiers forces the agent to
+satisfy all three constraints simultaneously, which is exponentially harder to
+game than any one of them in isolation.
+
+* **R1 (health)** — *did the city actually get better?*  Anchors the signal
+  to observable world outcomes.  An agent cannot inflate R1 by taking busy
+  actions that look purposeful but leave entropy unchecked.
+* **R2 (efficiency)** — *was the improvement worth the energy cost?*  Prevents
+  the "lucky repair" failure mode where the agent stumbles onto a broken sector
+  after 30 wasted moves and still earns a high health delta.
+* **R3 (format)** — *did the agent communicate in the expected schema?*  Acts
+  as a hard prerequisite: an agent that cannot reliably emit valid JSON cannot
+  earn positive rewards from R1 or R2, because its actions never execute.  The
+  harsh ``-2.0`` penalty (larger in magnitude than any single-step R1 or R2
+  gain) ensures that schema compliance is always the dominant priority during
+  early GRPO training.
+
+The three verifiers are kept as module-level functions rather than methods on a
+class so that the GRPO trainer can compose or replace individual verifiers
+without subclassing — a critical property for rapid hackathon iteration.
+
+Reward scale reference (approximate single-step ranges)
+---------------------------------------------------------
++-----------+----------------------------------------------+-------------------+
+| Verifier  | Scenario                                     | Score             |
++===========+==============================================+===================+
+| R1 health | Perfect repair, no entropy hits repaired sec | ≈ +1.0            |
+|           | Entropy hits two unrepaired sectors          | ≈ -0.4            |
+|           | Net-zero (repair cancelled by entropy)       |   0.0             |
++-----------+----------------------------------------------+-------------------+
+| R2 eff.   | Repair after direct 1-move approach          | ≈ +1.47           |
+|           | Repair after 10 wasted moves                 | ≈ +0.21           |
+|           | Recharge / WAIT / error (no energy spent)    |   0.0             |
++-----------+----------------------------------------------+-------------------+
+| R3 format | Valid JSON, valid ActionType                 |  +1.0             |
+|           | Malformed JSON or hallucinated action key    |  -2.0             |
++-----------+----------------------------------------------+-------------------+
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import StepResult
+
+# ── Verifier weights (hackathon tuning dials) ─────────────────────────────────
+#
+# Adjust these at the top of the file rather than hunting through the
+# ``compute_reward`` body.  Standard starting point for GRPO on this task:
+#
+#   w_health     = 1.0  — primary objective signal
+#   w_efficiency = 0.5  — secondary shaping signal (half weight to avoid
+#                         over-penalising legitimate recharge trips)
+#   w_format     = 1.0  — schema compliance; equal weight to health because
+#                         an agent that cannot communicate cannot act
+#
+_W_HEALTH: float = 1.0
+_W_EFFICIENCY: float = 0.5
+_W_FORMAT: float = 1.0
+
+# ── R2 scaling constant ───────────────────────────────────────────────────────
+#
+# ``city_health_after`` and ``city_health_before`` are *averages* over 25
+# sectors (range 0–100).  Multiplying the positive delta by 25 converts the
+# average improvement back into a total health-points figure, making the
+# numerator and denominator of the efficiency ratio dimensionally consistent:
+#   numerator   → total health points gained   (0–25 per REPAIR in isolation)
+#   denominator → energy points spent          (1–100 per step)
+#
+_HEALTH_SCALE: float = 25.0
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Verifier 1 — Objective (Health)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def get_health_reward(step_result: StepResult) -> float:
+    """
+    Measure whether the city is objectively healthier after this step.
+
+    The reward is the raw delta of average city health across all 25 sectors::
+
+        R1 = city_health_after − city_health_before
+
+    Range
+    -----
+    * Positive (≈ 0.0 to +1.0) when a REPAIR outweighs entropy.
+    * Negative (≈ -0.4 per step) when the agent does nothing and entropy
+      degrades two sectors by 5 points each (net average loss ≈ 0.4).
+    * Near-zero when the agent's repair precisely cancels entropy damage.
+
+    Why this alone is insufficient (reward-hacking risk)
+    -----------------------------------------------------
+    R1 does not care *how* the health gain was achieved.  A lucky agent could
+    wander randomly, occasionally stumble onto a critical sector, issue a
+    REPAIR, and earn a positive R1 without ever demonstrating strategic
+    routing.  R2 closes this gap by penalising the energy cost of reaching
+    the repaired sector.
+
+    Parameters
+    ----------
+    step_result : StepResult
+        The verifier receipt produced by ``CityGrid.step()``.
+
+    Returns
+    -------
+    float
+        Signed health delta.  Negative values are valid and expected on steps
+        where the agent recharged, moved without repairing, or issued an
+        invalid action.
+    """
+    return step_result.city_health_after - step_result.city_health_before
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Verifier 2 — Strategy (Efficiency)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def get_efficiency_reward(step_result: StepResult) -> float:
+    """
+    Measure whether the health improvement was worth its energy cost.
+
+    The reward is the ratio of total health points gained to energy points
+    spent::
+
+        health_gained = max(0, city_health_after − city_health_before) × 25
+        energy_spent  = energy_before − energy_after
+        R2            = health_gained / energy_spent   (if energy_spent > 0)
+                      = 0.0                            (otherwise)
+
+    Why multiply the health delta by 25?
+    -------------------------------------
+    ``city_health_before`` and ``city_health_after`` are *averages* over 25
+    sectors (domain [0, 100]).  Multiplying the positive delta by 25 converts
+    the mean improvement back into a total health-points figure so the
+    numerator and denominator are dimensionally comparable:
+
+    * Numerator:   total health points added this step  (max ≈ 25 per REPAIR)
+    * Denominator: energy points consumed this step     (1 for WAIT, 15 for
+                   REPAIR, 2 per MOVE, etc.)
+
+    Edge cases
+    ----------
+    ``energy_spent <= 0`` occurs on three legitimate step types:
+
+    1. **RECHARGE at sector 12** – energy increased; ``energy_after >
+       energy_before``.  No efficiency score is appropriate because the agent
+       gained a resource rather than spending one.
+    2. **Parse error** – no energy was deducted; the step was a no-op.
+       Penalising efficiency here would double-penalise the agent on top of
+       R3's format penalty.
+    3. **Energy already at 0** – the episode is terminating; the ratio would
+       be undefined.
+
+    In all three cases the function returns ``0.0`` (neutral) rather than an
+    error, keeping R3 as the sole penalty signal for errors and R1 as the
+    health signal for recharge steps.
+
+    Why this prevents the "lucky repair" failure mode
+    --------------------------------------------------
+    An agent that spends 20 energy units on ``MOVE`` actions to reach a
+    single critical sector and then REPAIRs it earns roughly
+    ``(+25 health) / (20 + 15 energy) ≈ 0.71`` in R2 — significantly lower
+    than an agent that routes directly (2 moves + REPAIR):
+    ``(+25 health) / (4 + 15 energy) ≈ 1.32``.  GRPO will push the policy
+    toward the direct-routing strategy even if both agents produce the same
+    R1 health delta.
+
+    Parameters
+    ----------
+    step_result : StepResult
+        The verifier receipt produced by ``CityGrid.step()``.
+
+    Returns
+    -------
+    float
+        Non-negative efficiency ratio, or ``0.0`` when no energy was spent.
+    """
+    health_gained: float = (
+        max(0.0, step_result.city_health_after - step_result.city_health_before)
+        * _HEALTH_SCALE
+    )
+    energy_spent: int = step_result.energy_before - step_result.energy_after
+
+    if energy_spent <= 0:
+        return 0.0
+
+    # Prevent the agent from getting a massive score multiplier by repairing
+    # with less than 15 energy remaining right before the episode terminates.
+    if health_gained > 0 and energy_spent < 15:
+        energy_spent = 15
+
+    return health_gained / energy_spent
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Verifier 3 — Guardrail (Format & Syntax)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def get_format_reward(step_result: StepResult) -> float:
+    """
+    Enforce strict adherence to the ``AgentAction`` JSON schema.
+
+    The binary reward is asymmetric by design::
+
+        R3 = +1.0   if action_parsed is not None AND is_error is False
+           = -2.0   otherwise
+
+    Why ``-2.0`` rather than ``0.0`` for a failed parse?
+    ------------------------------------------------------
+    A neutral penalty (``0.0``) would allow the agent to achieve a positive
+    total reward purely from occasional lucky health improvements (R1) while
+    ignoring the schema entirely.  Setting the failure penalty to ``-2.0``
+    (larger in magnitude than the maximum single-step R1 gain of ≈ +1.0)
+    ensures that schema non-compliance *always* produces a negative total
+    reward, even when entropy happens not to degrade any sector on that step.
+    This makes format compliance the lexicographically dominant priority
+    during early GRPO training, before the policy has learned to generate
+    valid JSON reliably.
+
+    What counts as a format failure?
+    ---------------------------------
+    * ``is_error=True``: the environment flagged this step as invalid.  This
+      covers malformed JSON, unrecognised ``ActionType`` strings (e.g.
+      ``"MOVE_NE"``), missing required fields (``action`` or ``reasoning``),
+      and ``reasoning`` strings shorter than 10 characters.
+    * ``action_parsed is None``: parsing raised an exception that set
+      ``action_parsed`` to ``None`` in the ``StepResult``.  This is redundant
+      with ``is_error`` for parse failures but provides a belt-and-suspenders
+      check for any future code path that sets ``action_parsed=None`` without
+      explicitly setting ``is_error=True``.
+
+    Note: RECHARGE-outside-sector-0 sets ``is_error=True`` even though the
+    JSON was syntactically valid.  This is intentional — the agent is
+    penalised for spatial reasoning errors that produce semantically invalid
+    actions, not just syntactic ones.
+
+    Parameters
+    ----------
+    step_result : StepResult
+        The verifier receipt produced by ``CityGrid.step()``.
+
+    Returns
+    -------
+    float
+        ``+1.0`` for schema-compliant steps, ``-2.0`` for any violation.
+    """
+    # Use local bindings so static analyzers always see a concrete symbol flow.
+    is_error = step_result.is_error
+    parsed_action = step_result.action_parsed
+    if is_error or parsed_action is None:
+        return -2.0
+    return 1.0
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Master verifier — Aggregation
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def compute_reward(info: dict[str, Any]) -> float:
+    """
+    Aggregate the three independent verifier scores into a single GRPO reward.
+
+    This is the only function called by ``grpo_trainer.py``.  It extracts the
+    ``StepResult`` receipt from the environment's ``info`` dict, calls the
+    three verifiers, and returns the weighted sum::
+
+        reward = w_health     × R1(step_result)
+               + w_efficiency × R2(step_result)
+               + w_format     × R3(step_result)
+
+    With the default weights ``(1.0, 0.5, 1.0)`` the approximate reward range
+    per step is roughly ``[−3.4, +3.7]``:
+
+    * **Best case** (direct repair, valid schema): R1 ≈ +1.0, R2 ≈ +1.47,
+      R3 = +1.0 → total ≈ **+3.24**.
+    * **Worst case** (bad JSON, heavy entropy): R1 ≈ −0.4, R2 = 0.0,
+      R3 = −2.0 → total ≈ **−2.4**.
+
+    This spread gives GRPO a clear gradient signal to differentiate between
+    rollouts — a signal-to-noise ratio that would collapse if the three
+    verifiers were merged into a single hand-crafted formula.
+
+    Robustness contract
+    -------------------
+    * If ``"step_result"`` is absent from ``info`` (e.g. the environment
+      returned early due to an internal error), the function returns ``0.0``
+      rather than raising — the GRPO trainer can safely continue sampling
+      without crashing the batch.
+    * ``StepResult(**info["step_result"])`` re-validates the receipt through
+      Pydantic at aggregation time.  If the environment somehow produced an
+      out-of-range value (e.g. ``energy_before=150``), this raises a
+      ``ValidationError`` that surfaces immediately rather than corrupting the
+      gradient computation silently.
+
+    Tuning guidance
+    ---------------
+    Modify ``_W_HEALTH``, ``_W_EFFICIENCY``, and ``_W_FORMAT`` at the top of
+    this module rather than editing this function body.  Suggested schedule for
+    a 30-hour hackathon:
+
+    * Hours  0–10: ``w_format=2.0`` — prioritise schema compliance above all.
+    * Hours 10–20: ``w_format=1.0, w_health=1.0`` — balanced regime once the
+      model reliably emits valid JSON.
+    * Hours 20–30: ``w_efficiency=1.0`` — maximise strategic routing now that
+      the policy is schema-stable.
+
+    Parameters
+    ----------
+    info : dict[str, Any]
+        The ``info`` dictionary returned by ``CityGrid.step()``.  Expected to
+        contain a ``"step_result"`` key whose value is a ``StepResult``
+        serialised by ``model_dump()``.
+
+    Returns
+    -------
+    float
+        Weighted sum of R1, R2, and R3.  Returns ``0.0`` if ``"step_result"``
+        is absent from ``info``.
+    """
+    if "step_result" not in info:
+        return 0.0
+
+    step_result = StepResult(**info["step_result"])
+    r1: float = get_health_reward(step_result)
+    r2: float = get_efficiency_reward(step_result)
+    r3: float = get_format_reward(step_result)
+
+    return (_W_HEALTH * r1) + (_W_EFFICIENCY * r2) + (_W_FORMAT * r3)

src/disaster_grid/utils.py

@@ -0,0 +1,404 @@
+"""
+src/disaster_grid/utils.py
+===========================
+Debug-focused terminal UI and emoji-grid visualiser for manual playtesting
+of the ``CityGrid`` environment.
+
+Running this module directly launches an interactive session::
+
+    python -m src.disaster_grid.utils
+
+Controls
+--------
++-------+------------+-----------------------------------------+
+| Key   | Action     | Notes                                   |
++=======+============+=========================================+
+| w     | MOVE_N     | Move agent one row upward               |
+| s     | MOVE_S     | Move agent one row downward             |
+| d     | MOVE_E     | Move agent one column right             |
+| a     | MOVE_W     | Move agent one column left              |
+| r     | REPAIR     | Repair current sector (+25 health, -15) |
+| c     | RECHARGE   | Recharge energy (+20, only at sector 12) |
+| q     | WAIT       | Skip turn (-1 energy)                   |
+| x     | Quit       | End the session immediately             |
++-------+------------+-----------------------------------------+
+
+Debug receipt
+-------------
+After every step the terminal prints the raw ``StepResult`` fields so the
+developer can immediately diagnose Pydantic validation failures, wall
+collisions, or wrong-location RECHARGE attempts without reading log files.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+from .environment import CityGrid
+from .models import ActionType
+
+# ── Display constants ─────────────────────────────────────────────────────────
+
+_EMOJI_AGENT: str = "🤖"
+_EMOJI_BASE: str = "🏢"
+_EMOJI_FIRE: str = "🔥"
+_EMOJI_HEALTHY: str = "🟩"
+_CRITICAL_THRESHOLD: int = 30
+
+_SEPARATOR_THICK: str = "═" * 52
+_SEPARATOR_THIN: str = "─" * 52
+
+# ── Key → ActionType mapping ──────────────────────────────────────────────────
+
+_KEY_MAP: dict[str, str] = {
+    "w": ActionType.MOVE_N.value,
+    "s": ActionType.MOVE_S.value,
+    "d": ActionType.MOVE_E.value,
+    "a": ActionType.MOVE_W.value,
+    "r": ActionType.REPAIR.value,
+    "c": ActionType.RECHARGE.value,
+    "q": ActionType.WAIT.value,
+}
+
+_QUIT_KEY: str = "x"
+
+
+# ── Terminal helpers ──────────────────────────────────────────────────────────
+
+
+def _clear() -> None:
+    """Clear the terminal screen on both Windows and POSIX systems."""
+    os.system("cls" if os.name == "nt" else "clear")
+
+
+def _header(text: str) -> str:
+    """Return a centred header line padded to the separator width."""
+    return text.center(52)
+
+
+# ── Grid renderer ─────────────────────────────────────────────────────────────
+
+
+def render_grid(env: CityGrid) -> str:
+    """
+    Render the 5 × 5 grid as a multi-line emoji string.
+
+    Each cell is exactly one emoji wrapped in square brackets so columns
+    align consistently across UTF-8 terminals.  The agent overrides all
+    other cell states — if the agent is standing on the base or a fire
+    sector the robot emoji takes precedence to avoid ambiguity during play.
+
+    Parameters
+    ----------
+    env : CityGrid
+        A live environment instance.  Reads ``env.agent_pos`` and
+        ``env.grid_health`` directly.
+
+    Returns
+    -------
+    str
+        A five-line string ready for ``print()``.
+    """
+    rows: list[str] = []
+    for row in range(5):
+        cells: list[str] = []
+        for col in range(5):
+            idx = row * 5 + col
+            if env.agent_pos == idx:
+                emoji = _EMOJI_AGENT
+            elif idx == 12:
+                emoji = _EMOJI_BASE
+            elif env.grid_health[idx] < _CRITICAL_THRESHOLD:
+                emoji = _EMOJI_FIRE
+            else:
+                emoji = _EMOJI_HEALTHY
+            cells.append(f"[{emoji}]")
+        rows.append("  " + " ".join(cells))
+    return "\n".join(rows)
+
+
+# ── Health bar ────────────────────────────────────────────────────────────────
+
+
+def _health_bar(value: float, width: int = 20) -> str:
+    """
+    Return a compact ASCII progress bar for a health / energy value.
+
+    Parameters
+    ----------
+    value : float
+        Current value in [0, 100].
+    width : int
+        Total number of bar characters (default 20).
+
+    Returns
+    -------
+    str
+        e.g. ``[████████████���░░░░░░░]  60.0``
+    """
+    filled = int(round((value / 100.0) * width))
+    bar = "█" * filled + "░" * (width - filled)
+    return f"[{bar}] {value:5.1f}"
+
+
+# ── HUD panels ────────────────────────────────────────────────────────────────
+
+
+def _render_hud(env: CityGrid, step_number: int) -> str:
+    """Return the agent-status panel string."""
+    x, y = env.agent_pos % 5, env.agent_pos // 5
+    avg_health = sum(env.grid_health) / 25
+    critical = sorted(i for i, h in enumerate(env.grid_health) if h < _CRITICAL_THRESHOLD)
+    critical_str = str(critical) if critical else "none 🎉"
+
+    lines = [
+        _SEPARATOR_THICK,
+        _header("🏙️  DISASTER RECOVERY GRID  🏙️"),
+        _SEPARATOR_THICK,
+        f"  Step       : {step_number:>3} / 50",
+        f"  Position   : sector {env.agent_pos:>2}  (col={x}, row={y})",
+        f"  Energy     : {_health_bar(env.agent_energy)}",
+        f"  City Health: {_health_bar(avg_health)}",
+        f"  🔥 Critical: {critical_str}",
+        _SEPARATOR_THIN,
+    ]
+    return "\n".join(lines)
+
+
+def _render_controls() -> str:
+    """Return the controls reference panel string."""
+    lines = [
+        _SEPARATOR_THIN,
+        _header("— CONTROLS —"),
+        "  [W] Move North    [S] Move South",
+        "  [A] Move West     [D] Move East",
+        "  [R] Repair        [C] Recharge (sector 12 only)",
+        "  [Q] Wait          [X] Quit",
+        _SEPARATOR_THIN,
+    ]
+    return "\n".join(lines)
+
+
+def _render_receipt(step_result: dict[str, Any]) -> str:
+    """
+    Format the ``StepResult`` debug receipt.
+
+    All fields are printed explicitly so the developer can immediately see
+    whether Pydantic parsed the action, whether an error was flagged, and
+    the exact health delta — without needing to inspect raw dicts.
+
+    Parameters
+    ----------
+    step_result : dict[str, Any]
+        The ``info["step_result"]`` dict from the last ``env.step()`` call.
+
+    Returns
+    -------
+    str
+        Multi-line receipt string.
+    """
+    action_parsed = step_result.get("action_parsed")
+    is_error = step_result.get("is_error", False)
+    error_msg = step_result.get("error_message", "")
+    health_before = step_result.get("city_health_before", 0.0)
+    health_after = step_result.get("city_health_after", 0.0)
+    health_delta = health_after - health_before
+    energy_before = step_result.get("energy_before", 0)
+    energy_after = step_result.get("energy_after", 0)
+    energy_delta = energy_after - energy_before
+    action_attempted = step_result.get("action_attempted", "—")
+
+    # Colour-code the health delta with arrows
+    if health_delta > 0:
+        delta_str = f"▲ +{health_delta:.4f}"
+    elif health_delta < 0:
+        delta_str = f"▼  {health_delta:.4f}"
+    else:
+        delta_str = f"   {health_delta:.4f}"
+
+    # Error status badge
+    error_badge = "❌ YES" if is_error else "✅ NO"
+
+    # Parsed action summary
+    if action_parsed is None:
+        parsed_str = "None  ← ⚠️  Pydantic validation FAILED"
+    else:
+        parsed_action_val = (
+            action_parsed.get("action", "?")
+            if isinstance(action_parsed, dict)
+            else str(action_parsed)
+        )
+        parsed_reasoning = (
+            action_parsed.get("reasoning", "")[:40]
+            if isinstance(action_parsed, dict)
+            else ""
+        )
+        parsed_str = f"{parsed_action_val!r}  (reasoning: {parsed_reasoning!r})"
+
+    lines = [
+        _SEPARATOR_THICK,
+        _header("— STEP RECEIPT (StepResult) —"),
+        _SEPARATOR_THIN,
+        f"  Attempted   : {action_attempted}",
+        f"  Parsed      : {parsed_str}",
+        _SEPARATOR_THIN,
+        f"  Error?      : {error_badge}",
+        f"  Error Msg   : {error_msg if error_msg else '—'}",
+        _SEPARATOR_THIN,
+        f"  Energy      : {energy_before:>4}  →  {energy_after:>4}  "
+        f"(delta: {energy_delta:+d})",
+        f"  City Health : {health_before:>8.4f}  →  {health_after:>8.4f}  "
+        f"(delta: {delta_str})",
+        _SEPARATOR_THICK,
+    ]
+    return "\n".join(lines)
+
+
+# ── Main playtest loop ────────────────────────────────────────────────────────
+
+
+def play_manual(seed: int | None = None) -> None:
+    """
+    Launch an interactive manual playtest session in the terminal.
+
+    The loop renders the full game state, waits for a keypress, constructs
+    a valid ``AgentAction``-compatible payload, calls ``env.step()``, then
+    prints the ``StepResult`` debug receipt before pausing so the developer
+    can read the output before the screen clears.
+
+    Parameters
+    ----------
+    seed : int | None
+        Optional RNG seed passed to ``env.reset()``.  Set to a fixed integer
+        for reproducible debug sessions.
+
+    Payload construction note
+    -------------------------
+    The payload is built as a plain ``dict`` (not a JSON string) because
+    ``CityGrid.step()`` accepts both formats.  Using a dict skips the
+    ``json.dumps`` / ``json.loads`` round-trip and surfaces Pydantic
+    validation errors more directly.  The ``reasoning`` value is a fixed
+    string; the ``action`` value is the exact ``.value`` of the enum member,
+    which is what ``AgentAction`` expects::
+
+        action_payload = {
+            "action": key_map[user_input],   # e.g. "MOVE_N"
+            "reasoning": "Manual playtest",
+        }
+    """
+    env = CityGrid()
+    obs, _ = env.reset(seed=seed)
+
+    # ── Welcome splash ────────────────────────────────────────────────────
+    _clear()
+    print(_SEPARATOR_THICK)
+    print(_header("🚨  DISASTER GRID — MANUAL PLAYTEST  🚨"))
+    print(_header("debug mode · all StepResult fields visible"))
+    print(_SEPARATOR_THICK)
+    print()
+    print("  Legend:")
+    print(f"    [{_EMOJI_AGENT}] Agent position")
+    print(f"    [{_EMOJI_BASE}] Base / Recharge station (sector 12)")
+    print(f"    [{_EMOJI_FIRE}] Critical sector (health < 30)")
+    print(f"    [{_EMOJI_HEALTHY}] Healthy sector (health ≥ 30)")
+    print()
+    print("  Press Enter to begin...")
+    input()
+
+    last_receipt: dict[str, Any] = {}
+    episode_over: bool = False
+
+    while not episode_over:
+        _clear()
+
+        # ── Render HUD ────────────────────────────────────────────────────
+        print(_render_hud(env, env.step_count))
+        print()
+
+        # ── Render grid ───────────────────────────────────────────────────
+        print(render_grid(env))
+        print()
+
+        # ── Print last receipt (empty on first turn) ──────────────────────
+        if last_receipt:
+            print(_render_receipt(last_receipt))
+        else:
+            print(_SEPARATOR_THIN)
+            print(_header("— no action taken yet —"))
+            print(_SEPARATOR_THIN)
+
+        print()
+        print(_render_controls())
+        print()
+
+        # ── Prompt ────────────────────────────────────────────────────────
+        raw = input("  Your move › ").strip().lower()
+
+        if raw == _QUIT_KEY:
+            print()
+            print("  Exiting playtest session. Goodbye! 👋")
+            sys.exit(0)
+
+        if raw not in _KEY_MAP:
+            print()
+            print(f"  ⚠️  Unknown key {raw!r}. Valid keys: "
+                  f"{sorted(_KEY_MAP)} or '{_QUIT_KEY}' to quit.")
+            input("  Press Enter to continue...")
+            continue
+
+        # ── Build the exact payload the AgentAction schema expects ────────
+        action_payload: dict[str, str] = {
+            "action": _KEY_MAP[raw],
+            "reasoning": "Manual playtest",
+        }
+
+        print()
+        print(f"  Sending payload → {action_payload}")
+
+        # ── Step the environment ──────────────────────────────────────────
+        try:
+            obs, reward, done, truncated, info = env.step(action_payload)
+        except Exception as exc:  # noqa: BLE001
+            # Surface any unexpected environment crash without losing the
+            # session — developer can inspect the state and continue.
+            print()
+            print(f"  🚨 UNEXPECTED ENVIRONMENT ERROR: {type(exc).__name__}: {exc}")
+            input("  Press Enter to continue...")
+            continue
+
+        # ── Extract StepResult receipt ────────────────────────────────────
+        last_receipt = info.get("step_result", {})
+
+        episode_over = bool(done or truncated)
+
+    # ── Episode over screen ───────────────────────────────────────────────
+    _clear()
+    avg_health = sum(env.grid_health) / 25
+    print(_SEPARATOR_THICK)
+    print(_header("🏁  EPISODE COMPLETE  🏁"))
+    print(_SEPARATOR_THICK)
+    print(f"  Steps taken     : {env.step_count}")
+    print(f"  Final energy    : {env.agent_energy}")
+    print(f"  Final avg health: {avg_health:.2f} / 100.00")
+    print()
+    if avg_health >= 70:
+        print(_header("✅ CITY SAVED — excellent management!"))
+    elif avg_health >= 40:
+        print(_header("⚠️  CITY DAMAGED — recovery possible."))
+    else:
+        print(_header("💀 CITY LOST — better luck next time."))
+    print(_SEPARATOR_THICK)
+
+    # ── Final receipt ─────────────────────────────────────────────────────
+    if last_receipt:
+        print()
+        print(_render_receipt(last_receipt))
+
+    print()
+    input("  Press Enter to exit...")
+
+
+if __name__ == "__main__":
+    play_manual()