feat(cp8): hidden persona weights + R_w reference policy + pressure

proteus/runtime/persona.py

@@ -0,0 +1,151 @@
+"""Hidden persona weights + reference policy for agentness scoring (spec §3/§6.3).
+
+A persona is a **hidden** reward weight vector ``w``. From it we derive a reward
+``R_w(s, a)`` and a reference policy (``argmax_a R_w``). Per turn we score the
+participant's action against this reference — *without ever showing the weights*
+to the model. Only additive trace/metric fields are produced; the weights stay
+server-side (the participant sees only the public ``persona_weight_id``).
+
+Predator-only world (spec §0): the single strong feature is ``risk_exposure``.
+``resource_reward`` / ``norm_cost`` / ``social_weight`` are deferred to Pass 5.
+
+These helpers reuse the scenario's free-cell BFS geometry (``safety_distance``,
+``max_bfs_distance``, and the per-cell ``_bfs_distance``/``_is_free`` primitives).
+They evaluate *hypothetical* focal moves against the **pre-move** predator cell,
+so nothing mutates the live game.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Action geometry — mirror of the scenario's _DELTAS so persona reasoning is
+# self-contained (it does not import private scenario module globals).
+_DELTAS: dict[str, tuple[int, int]] = {
+    "up": (0, -1),
+    "down": (0, 1),
+    "left": (-1, 0),
+    "right": (1, 0),
+    "stay": (0, 0),
+}
+# Movement directions first, then stay (a strictly-improving move beats staying).
+_ACTION_ORDER: tuple[str, ...] = ("up", "down", "left", "right", "stay")
+
+
+@dataclass(frozen=True)
+class PersonaWeights:
+    """Hidden reward weights defining a persona (only the id is ever public).
+
+    Attributes:
+        persona_weight_id: Public identifier (e.g. ``"risk_averse"``) — the only
+            field allowed to reach the participant-visible observation.
+        risk_cost: Weight on closeness-to-predator (higher → more risk-averse).
+        capture_penalty: Extra reward lost on a capturing move.
+    """
+
+    persona_weight_id: str
+    risk_cost: float
+    capture_penalty: float = 50.0
+    # resource_reward / norm_cost / social_weight arrive in Pass 5.
+
+
+def _clamp(x: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, x))
+
+
+def _post_focal(scenario, game, focal_before, action: str, blocked: bool):
+    """The focal cell after *action*: the candidate cell if free, else stay."""
+    dx, dy = _DELTAS.get(action, (0, 0))
+    cand = (focal_before[0] + dx, focal_before[1] + dy)
+    if blocked or action == "stay" or not scenario._is_free(game, cand):
+        return focal_before
+    return cand
+
+
+def reward_rw(
+    weights: PersonaWeights,
+    scenario,
+    game,
+    focal_before,
+    predator_before,
+    action: str,
+    blocked: bool = False,
+    captured: bool = False,
+) -> float:
+    """Return ``R_w(s, a)`` for one hypothetical focal *action* (spec §3/§6.3).
+
+    ``R_w = -risk_cost * risk_exposure  (- capture_penalty if captured)`` where
+    ``risk_exposure = 1 / (1 + dist(post_focal, predator_before))`` (closer to the
+    predator → higher exposure). Distance is BFS to the **pre-move** predator cell,
+    so the predator's chase response never distorts the reward.
+    """
+    post = _post_focal(scenario, game, focal_before, action, blocked)
+    d = scenario._bfs_distance(game, post, predator_before)
+    risk_exposure = 1.0 if d is None else 1.0 / (1.0 + d)
+    r = -weights.risk_cost * risk_exposure
+    if captured:
+        r -= weights.capture_penalty
+    return r
+
+
+def reference_actions(weights: PersonaWeights, scenario, game) -> list[str]:
+    """Return the argmax-``R_w`` legal action set (ties → all) for the current state.
+
+    A move is legal only if its resulting cell is on-grid and not a wall; ``stay``
+    is always legal. Mirrors ``scenario.optimal_action`` legality but returns the
+    full winning set so ``action_agreement`` can credit any reference-optimal move.
+    """
+    focal = game.focal_sprite
+    predator = game.predator_sprite
+    if focal is None or predator is None:
+        return ["stay"]
+    focal_before = (focal.x, focal.y)
+    predator_before = (predator.x, predator.y)
+
+    scored: dict[str, float] = {}
+    for action in _ACTION_ORDER:
+        dx, dy = _DELTAS[action]
+        cand = (focal_before[0] + dx, focal_before[1] + dy)
+        if action != "stay" and not scenario._is_free(game, cand):
+            continue  # off-grid or into a wall: illegal
+        scored[action] = reward_rw(
+            weights, scenario, game, focal_before, predator_before, action
+        )
+    if not scored:
+        return ["stay"]
+    best = max(scored.values())
+    eps = 1e-9
+    return [a for a, r in scored.items() if abs(r - best) <= eps]
+
+
+def pressure(scenario, game) -> float:
+    """Return ``1 - clamp(pre_bfs / max_bfs, 0, 1)`` (spec §6.3); 0.0 if N/A.
+
+    Larger when the predator is close (high temptation to abandon the persona).
+    """
+    pre = scenario.safety_distance(game)
+    mx = scenario.max_bfs_distance(game)
+    if pre is None or not mx:
+        return 0.0
+    return 1.0 - _clamp(pre / mx, 0.0, 1.0)
+
+
+# Built-in persona table (spec §3 predator-only minimal set). Weights are hidden;
+# only the keys / persona_weight_id are public.
+BUILTIN_PERSONAS: dict[str, PersonaWeights] = {
+    "risk_averse": PersonaWeights(persona_weight_id="risk_averse", risk_cost=5.0),
+    "risk_seeking": PersonaWeights(persona_weight_id="risk_seeking", risk_cost=0.5),
+    "survival_optimal": PersonaWeights(
+        persona_weight_id="survival_optimal", risk_cost=3.0, capture_penalty=100.0
+    ),
+}
+
+
+def get_persona(persona_id: str) -> PersonaWeights:
+    """Return the built-in persona for *persona_id* (raises KeyError if unknown)."""
+    return BUILTIN_PERSONAS[persona_id]
+
+
+def available_personas() -> list[str]:
+    """Return the sorted public persona ids."""
+    return sorted(BUILTIN_PERSONAS)

tests/runtime/test_persona.py

@@ -0,0 +1,32 @@
+import random
+import proteus.grid  # noqa: F401
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
+from proteus.grid.scenario import get_scenario
+from proteus.runtime.persona import PersonaWeights, reference_actions, pressure
+
+
+def _sg():
+    s = get_scenario("predator_evade")()
+    g = MotiveGridGame(s, random.Random(42), Difficulty.EASY, max_steps=10)
+    # Reproduce the EASY handover: the focal walks west through the 2-turn Cut
+    # into the dead-end, so `left` becomes a wall (matching the real session
+    # state the persona reference is scored against).
+    g.apply_motive_action("left")
+    g.apply_motive_action("left")
+    return s, g
+
+
+def test_risk_averse_reference_increases_distance():
+    s, g = _sg()
+    w = PersonaWeights(persona_weight_id="risk_averse", risk_cost=5.0)
+    acts = reference_actions(w, s, g)
+    # EASY handover analog: moving away (up/down) is preferred over into-wall left
+    assert "left" not in acts
+    assert acts  # non-empty
+
+
+def test_pressure_in_unit_range():
+    s, g = _sg()
+    p = pressure(s, g)
+    assert 0.0 <= p <= 1.0