Merge pull request #70 from CurtisTechSolutions/feat/python-model-action-views

feat(python): expose readable legal actions to model policies

Author: nosam1998

crates/apps/gfa-py/src/lib.rs

@@ -65,6 +65,10 @@ impl NativeEnv {
         Ok((step.rewards, step.terminated, step.truncated))
     }
 
+    fn spec_json(&self) -> PyResult<String> {
+        serde_json::to_string(&self.inner.spec()).map_err(error)
+    }
+
     fn current_players(&self) -> Vec<usize> {
         self.inner
             .current_players()
@@ -82,11 +86,12 @@ impl NativeEnv {
     }
 
     fn frame<'py>(&self, py: Python<'py>, seat: u8) -> PyResult<Bound<'py, PyDict>> {
-        let (observation, mask) = py
+        let (observation, mask, actions) = py
             .detach(|| {
                 Ok::<_, GameError>((
                     self.inner.observe(Viewer::Player(seat))?,
                     self.inner.action_mask(seat)?,
+                    self.inner.action_catalog(seat)?,
                 ))
             })
             .map_err(error)?;
@@ -106,6 +111,13 @@ impl NativeEnv {
             ),
         )?;
         dict.set_item("text", observation.text)?;
+        dict.set_item(
+            "legal_actions",
+            actions
+                .into_iter()
+                .map(|action| (action.index, action.string))
+                .collect::<Vec<_>>(),
+        )?;
         dict.set_item(
             "board_json",
             serde_json::to_string(&observation.json).map_err(error)?,

crates/core/gfa-core/src/training.rs

@@ -1,4 +1,7 @@
-use crate::{Env, EnvSnapshot, EnvStep, Game, GameError, GameSpec, Observation, PlayerId, Viewer};
+use crate::{
+    Env, EnvSnapshot, EnvStep, Game, GameError, GameSpec, LegalAction, Observation, PlayerId,
+    Viewer,
+};
 
 /// Object-safe native environments for Python bindings and parallel batches.
 /// Implementations retain typed engine state between steps.
@@ -21,6 +24,12 @@ pub trait TrainingEnv: Send + Sync {
     fn observe(&self, viewer: Viewer) -> Result<Observation, GameError>;
     /// Fixed discrete action mask.
     fn action_mask(&self, player: PlayerId) -> Result<Vec<bool>, GameError>;
+    /// Optional readable actions for text policies, scoped to the selected seat.
+    fn action_catalog(&self, _player: PlayerId) -> Result<Vec<LegalAction>, GameError> {
+        Err(GameError::position(
+            "This environment has no readable action catalog",
+        ))
+    }
     /// Native discrete action step.
     fn step_index(&mut self, player: PlayerId, index: u32) -> Result<EnvStep, GameError>;
     /// Canonical notation step.
@@ -66,6 +75,21 @@ where
     fn action_mask(&self, player: PlayerId) -> Result<Vec<bool>, GameError> {
         Env::action_mask(self, player)
     }
+    fn action_catalog(&self, player: PlayerId) -> Result<Vec<LegalAction>, GameError> {
+        let mut actions = self
+            .legal_actions(player)?
+            .iter()
+            .map(|action| {
+                Ok(LegalAction {
+                    string: G::action_to_string(self.state(), action),
+                    json: serde_json::to_value(action)?,
+                    index: G::action_to_index(action),
+                })
+            })
+            .collect::<Result<Vec<_>, GameError>>()?;
+        actions.sort_by(|left, right| left.string.cmp(&right.string));
+        Ok(actions)
+    }
     fn step_index(&mut self, player: PlayerId, index: u32) -> Result<EnvStep, GameError> {
         Env::step_index(self, player, index)
     }

python/README.md

@@ -94,3 +94,7 @@ of numeric output per batch. Throughput still needs measurement against the PRD
 ## Versioned positions
 
 `PositionSet.load("chess-endgames-basic@1")` loads a bundled, hash-verified dataset and validates every entry using the native engine. `PositionSet.from_files(manifest_path, jsonl_path)` loads a custom set with the same checks. Entries are immutable; use `sample(numpy_rng)` to choose a deterministic starting position. Pass its `position` to a native or Gymnasium reset. Expected puzzle answers stay in trusted dataset metadata, outside policy observations. See [position data](../positions/README.md) for the format and provenance.
+
+## Readable actions for model policies
+
+Native frames include `legal_actions` as `(index, canonical_notation)` pairs in stable notation order. Gymnasium info includes the same catalog plus the game ID, rules, and action notation for learner and opponent policies. The catalog contains only actions available to that seat and matches its numeric mask. `NativeEnv.spec_json()` returns the static game contract. Vector batches keep their numeric-only output.

python/gamesforai/_native.pyi

@@ -10,6 +10,7 @@ class NativeEnv:
     def reset(self, seed: int = 0, position: str | None = None) -> None: ...
     def step(self, seat: int, action: int) -> tuple[list[float], bool, bool]: ...
     def step_string(self, seat: int, action: str) -> tuple[list[float], bool, bool]: ...
+    def spec_json(self) -> str: ...
     def current_players(self) -> list[int]: ...
     def flags(self) -> tuple[bool, bool]: ...
     def returns(self) -> list[float]: ...

python/gamesforai/gym_env.py

@@ -41,6 +41,7 @@ def __init__(
         self.native = NativeEnv(game, json.dumps(config or {}))
         if isinstance(seat, bool) or not isinstance(seat, int) or not 0 <= seat < self.native.num_players:
             raise ValueError("seat is outside this game's player range")
+        self._spec = json.loads(self.native.spec_json())
         self.seat = seat
         self.opponent = opponent
         self.render_mode = render_mode
@@ -56,6 +57,10 @@ def _frame(self, seat: int) -> tuple[np.ndarray, dict[str, Any]]:
         terminated, truncated = self.native.flags()
         info = {
             "action_mask": frame["action_mask"],
+            "legal_actions": frame["legal_actions"],
+            "game_id": self._spec["id"],
+            "rules": self._spec["rules_markdown"],
+            "action_notation": self._spec["action_notation"],
             "text": frame["text"],
             "board": json.loads(frame["board_json"]),
             "seat": seat,

python/tests/test_policy_views.py

@@ -0,0 +1,41 @@
+import json
+
+import numpy as np
+import pytest
+
+from gamesforai import NativeEnv, games, make
+
+
+@pytest.mark.parametrize("game", games())
+def test_action_catalog_matches_mask_and_all_encodings(game):
+    env = NativeEnv(game)
+    spec = json.loads(env.spec_json())
+    assert spec["id"] == game and spec["rules_markdown"] and spec["action_notation"]
+    seat = env.current_players()[0]
+    frame = env.frame(seat)
+    catalog = frame["legal_actions"]
+    assert len({index for index, _ in catalog}) == len(catalog)
+    assert sorted(index for index, _ in catalog) == np.flatnonzero(frame["action_mask"]).tolist()
+    assert [text for _, text in catalog] == sorted(text for _, text in catalog)
+    for index, text in catalog[:16]:
+        by_index, by_text = env.clone(), env.clone()
+        assert by_index.step(seat, index) == by_text.step_string(seat, text)
+        assert by_index.get_state() == by_text.get_state()
+    if env.num_players == 2:
+        assert env.frame(1 - seat)["legal_actions"] == []
+
+
+def test_gym_opponent_and_learner_receive_readable_seat_scoped_moves():
+    received = []
+    def opponent(obs, info):
+        received.append(info)
+        return info["legal_actions"][0][0]
+
+    env = make("chess", opponent=opponent)
+    _, info = env.reset(seed=1)
+    assert info["game_id"] == "chess"
+    assert "e2e4" in [text for _, text in info["legal_actions"]]
+    env.step(next(index for index, text in info["legal_actions"] if text == "e2e4"))
+    assert received[0]["seat"] == 1
+    assert "e7e5" in [text for _, text in received[0]["legal_actions"]]
+    assert info["rules"] and info["action_notation"]