feat(cp2): slim action parser

proteus/agents/__init__.py

@@ -0,0 +1 @@
+"""proteus.agents — slim LLM agent abstraction (no forfeit/stake/risk)."""

proteus/agents/parsing.py

@@ -0,0 +1,48 @@
+"""Extract a single action token from free-form LLM text.
+
+Strategy (first match wins):
+    1. The last ``ACTION: <token>`` field (case-insensitive), trailing
+       punctuation stripped, if the token is a valid action.
+    2. Fallback: the last valid-action word appearing anywhere in the text.
+    3. ``None`` if no valid action is found.
+
+Mirrors the parent project's ``ACTION:`` convention but drops all
+forfeit/stake handling.
+"""
+
+from __future__ import annotations
+
+import re
+
+_ACTION_FIELD = re.compile(r"ACTION\s*:\s*([^\n\r]+)", re.IGNORECASE)
+_WORD = re.compile(r"[a-zA-Z]+")
+
+
+def extract_action(text: str, valid: list[str]) -> str | None:
+    """Return the chosen action (one of *valid*) parsed from *text*, or None.
+
+    Args:
+        text: Raw LLM output.
+        valid: Allowed action strings (lowercase, e.g. ``["up", ...]``).
+
+    Returns:
+        The matched action string, or ``None`` if none is found.
+    """
+    valid_set = {v.lower() for v in valid}
+
+    # Strategy 1: last ACTION: <token> field.
+    field_matches = _ACTION_FIELD.findall(text)
+    for raw in reversed(field_matches):
+        token = raw.strip().strip(".!,;:'\"`").lower()
+        # take the first word of the field value
+        first = token.split()[0] if token.split() else ""
+        if first in valid_set:
+            return first
+
+    # Strategy 2: last valid-action word anywhere.
+    words = [w.lower() for w in _WORD.findall(text)]
+    for w in reversed(words):
+        if w in valid_set:
+            return w
+
+    return None

tests/agents/test_parsing.py

@@ -0,0 +1,20 @@
+from proteus.agents.parsing import extract_action
+
+VALID = ["up", "down", "left", "right", "stay"]
+
+
+def test_extracts_action_field_last_occurrence_wins():
+    text = "ACTION: left\n...changed my mind...\nACTION: up"
+    assert extract_action(text, VALID) == "up"
+
+
+def test_case_insensitive_and_strips_punctuation():
+    assert extract_action("Action: Up.", VALID) == "up"
+
+
+def test_bare_word_fallback_when_no_action_field():
+    assert extract_action("I will move down to escape.", VALID) == "down"
+
+
+def test_returns_none_when_no_valid_action():
+    assert extract_action("no idea", VALID) is None