feat(memory): memory_frames() reconstructs per-turn color grids

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

proteus/runtime/memory.py

@@ -127,3 +127,62 @@ def render_memory_block(checkpoint: MemoryCheckpoint) -> str:
         parts.append(mt.frame_ascii)
         parts.append(f"  you chose: {mt.action}")
     return "\n".join(parts)
+
+
+def _invert_legend(legend: dict[int, str]) -> dict[str, int]:
+    return {sym: idx for idx, sym in legend.items()}
+
+
+def _ascii_to_grid(frame: str, sym2idx: dict[str, int]) -> list[list[int]] | None:
+    """Parse *frame* as a rectangular grid of legend symbols, else None."""
+    lines = frame.split("\n")
+    if len(lines) < 2 or len({len(ln) for ln in lines}) != 1 or not lines[0]:
+        return None
+    grid: list[list[int]] = []
+    for ln in lines:
+        row: list[int] = []
+        for ch in ln:
+            if ch not in sym2idx:
+                return None
+            row.append(sym2idx[ch])
+        grid.append(row)
+    return grid
+
+
+def memory_frames(
+    checkpoint: MemoryCheckpoint, *, legend: dict[int, str], grid_size: tuple[int, int]
+) -> list[dict]:
+    """Reconstruct a renderable color grid per memory turn.
+
+    Returns ``[{turn_idx, action, grid}]`` where ``grid`` is a ``height x width``
+    list of palette indices. Grid-style ``frame_ascii`` is inverted via *legend*;
+    prose frames are rebuilt from walls + recorded focal/predator positions.
+    Pure: no engine, no IO.
+    """
+    sym2idx = _invert_legend(legend)
+    bg = sym2idx.get(".", 5)
+    focal_idx = sym2idx.get("A", 1)
+    predator_idx = sym2idx.get("B", 2)
+    wall_idx = sym2idx.get("#", 3)
+    w, h = grid_size
+    out: list[dict] = []
+
+    def paint(grid, x0, y0, n, idx):
+        for j in range(n):
+            for i in range(n):
+                x, y = x0 + i, y0 + j
+                if 0 <= x < w and 0 <= y < h:
+                    grid[y][x] = idx
+
+    for mt in checkpoint.memory_turns:
+        grid = _ascii_to_grid(mt.frame_ascii, sym2idx)
+        if grid is None:
+            grid = [[bg] * w for _ in range(h)]
+            for (rx0, ry0, rx1, ry1) in checkpoint.wall_rects:
+                for y in range(max(0, ry0), min(h, ry1 + 1)):
+                    for x in range(max(0, rx0), min(w, rx1 + 1)):
+                        grid[y][x] = wall_idx
+            paint(grid, mt.predator_pos[0], mt.predator_pos[1], 5, predator_idx)
+            paint(grid, mt.focal_pos[0], mt.focal_pos[1], 3, focal_idx)
+        out.append({"turn_idx": mt.turn_idx, "action": mt.action, "grid": grid})
+    return out

tests/runtime/test_memory_frames.py

@@ -0,0 +1,36 @@
+"""Pure reconstruction of per-turn color grids from a MemoryCheckpoint."""
+from __future__ import annotations
+
+from proteus.runtime.memory import MemoryCheckpoint, MemoryTurn, memory_frames
+
+_GRID_LEGEND = {5: ".", 1: "A", 2: "B", 3: "#"}
+
+
+def _ck(turns, scenario="x", wall_rects=None):
+    return MemoryCheckpoint(
+        model="m", scenario=scenario, difficulty="easy", seed=1,
+        created_at="t", outcome="survived", transparent_prompt="p",
+        memory_turns=turns, wall_rects=wall_rects or [],
+    )
+
+
+def test_grid_frame_inverts_ascii_via_legend():
+    ck = _ck([MemoryTurn(turn_idx=1, frame_ascii="A.\n.#", action="right",
+                         focal_pos=(0, 0), predator_pos=(1, 1))])
+    frames = memory_frames(ck, legend=_GRID_LEGEND, grid_size=(2, 2))
+    assert frames[0]["action"] == "right"
+    assert frames[0]["grid"] == [[1, 5], [5, 3]]  # A . / . #
+
+
+def test_prose_frame_paints_positions_and_walls():
+    ck = _ck(
+        [MemoryTurn(turn_idx=1, frame_ascii="Open field 8x8. You are A ...",
+                    action="up", focal_pos=(0, 0), predator_pos=(5, 5))],
+        wall_rects=[(2, 2, 3, 3)],
+    )
+    g = memory_frames(ck, legend=_GRID_LEGEND, grid_size=(8, 8))[0]["grid"]
+    assert g[0][0] == 1 and g[2][2] == 1  # focal 3x3 at (0,0)
+    assert g[5][5] == 2 and g[7][7] == 2  # predator 5x5 at (5,5) clipped in-bounds
+    assert g[2][2] != 3                   # focal painted over its cells
+    assert g[3][3] == 3                   # wall cell visible
+    assert g[0][4] == 5                   # background elsewhere