feat(cp2): Agent ABC + ActResult

proteus/agents/base.py

@@ -0,0 +1,78 @@
+"""Slim agent interface for the PROTEUS arena.
+
+An agent observes the grid and produces an action (plus the reasoning behind
+it). It may optionally answer a side-channel probe. There is no forfeit,
+stake, or risk machinery — the arena measures motive-reading, not
+self-preservation trade-offs.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class ActResult:
+    """An agent's decision for one turn.
+
+    Attributes:
+        action: The chosen action (one of the available actions).
+        reasoning: The agent's stated/extracted rationale (CoT / thinking).
+            Empty string if none was produced.
+        raw_text: The full unprocessed model output.
+    """
+
+    action: str
+    reasoning: str
+    raw_text: str
+
+
+class Agent(ABC):
+    """Abstract LLM agent that plays a motive_grid scenario."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short identifier for this agent variant (e.g. ``"vanilla"``)."""
+
+    @abstractmethod
+    def act(
+        self,
+        observation: str,
+        available_actions: list[str],
+        system_prompt: str,
+    ) -> ActResult:
+        """Choose an action for the current turn.
+
+        Args:
+            observation: Text rendering of the current world (+ Cut history
+                on the first turn).
+            available_actions: Valid action strings to choose from.
+            system_prompt: Rules + handover framing for the session.
+
+        Returns:
+            An :class:`ActResult`.
+        """
+
+    @abstractmethod
+    def probe(
+        self,
+        observation: str,
+        question: str,
+        system_prompt: str,
+    ) -> str:
+        """Answer a side-channel comprehension probe (does not change state).
+
+        Args:
+            observation: Text rendering of the current world.
+            question: The probe question.
+            system_prompt: Rules + handover framing for the session.
+
+        Returns:
+            Free-text probe answer.
+        """
+
+    @abstractmethod
+    def reset(self) -> None:
+        """Clear any per-session internal state."""

tests/agents/test_agent_base.py

@@ -0,0 +1,15 @@
+import pytest
+
+from proteus.agents.base import Agent, ActResult
+
+
+def test_actresult_fields():
+    r = ActResult(action="up", reasoning="predator behind", raw_text="ACTION: up")
+    assert r.action == "up"
+    assert r.reasoning == "predator behind"
+    assert r.raw_text == "ACTION: up"
+
+
+def test_agent_is_abstract():
+    with pytest.raises(TypeError):
+        Agent()  # abstract: cannot instantiate