feat(cp1): port ascii_view into proteus.grid

proteus/grid/ascii_view.py

@@ -0,0 +1,68 @@
+"""ASCII rendering of a motive_grid frame for text-only model observations.
+
+Benchmark models read text, not pixels, so the world state is shown to the
+model as a compact ASCII grid: one character per cell, one line per row.  The
+arc_grid PNG/terminal renderers stay reserved for humans and debugging.
+
+The native-resolution palette frame comes from
+:meth:`~.game.MotiveGridGame.current_grid` (a ``(height, width)`` array of
+palette indices), and the index -> symbol mapping comes from
+:meth:`~.scenario.Scenario.legend`.  This module is pure and deterministic: no
+randomness, no IO.
+
+See ``docs/superpowers/specs/2026-06-01-motive-grid-design.md`` §3.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def frame_to_ascii(
+    grid: np.ndarray,
+    legend: dict[int, str],
+    unknown: str = "?",
+) -> str:
+    """Render a native-resolution palette grid as an ASCII string.
+
+    Each integer cell is mapped to its legend character; any index absent from
+    *legend* maps to *unknown*.  Rows are joined by newlines and the characters
+    within a row are concatenated with no separators, so an ``8x8`` grid yields
+    8 lines of 8 characters.  The output is deterministic for a given grid and
+    legend.
+
+    Args:
+        grid: A 2D native-resolution array of palette indices with shape
+            ``(height, width)``.
+        legend: Mapping from palette index to a single-character symbol.
+        unknown: Character used for any palette index not present in *legend*.
+
+    Returns:
+        A newline-joined ASCII rendering of the grid (no trailing newline).
+    """
+    return "\n".join(
+        "".join(legend.get(int(cell), unknown) for cell in row) for row in grid
+    )
+
+
+def legend_text(legend: dict[int, str]) -> str:
+    """Render a compact, deterministic list of the distinct symbols in use.
+
+    This is intentionally minimal: it lists the symbols only, not their
+    meanings.  ``Scenario.legend`` maps palette index -> a single character, so
+    no meaning can be recovered from it; the rich symbol-meaning key belongs to
+    the scenario's ``rules_text`` (handled later, in CP5).
+
+    Args:
+        legend: Mapping from palette index to a single-character symbol.
+
+    Returns:
+        A line like ``"Symbols: . @ # P"`` listing the distinct symbols in
+        ascending palette-index order (deterministic).
+    """
+    seen: list[str] = []
+    for index in sorted(legend):
+        symbol = legend[index]
+        if symbol not in seen:
+            seen.append(symbol)
+    return "Symbols: " + " ".join(seen)

tests/grid/test_ascii_view.py

@@ -0,0 +1,15 @@
+import numpy as np
+
+from proteus.grid.ascii_view import frame_to_ascii, legend_text
+
+
+def test_frame_to_ascii_maps_indices_and_unknowns():
+    grid = np.array([[5, 1], [3, 9]], dtype=np.int8)
+    legend = {5: ".", 1: "A", 3: "#"}
+    out = frame_to_ascii(grid, legend)
+    assert out == ".A\n#?"  # 9 is unknown -> "?"
+
+
+def test_legend_text_lists_distinct_symbols_in_index_order():
+    legend = {5: ".", 1: "A", 2: "B", 3: "#"}
+    assert legend_text(legend) == "Symbols: A B # ."