feat(env): add print_history helper

 - the paths back from fragile weren't producing the right states (maybe my error) but the agents have all their history internally, so this helper replays the agent history from the given state and prints it out.
 - regenerate api docs

Author: justindujardin

libraries/mathy_python/mathy/env.py

@@ -311,14 +311,52 @@ def print_state(
             )
         )
 
+    def is_terminal_state(self, env_state: MathyEnvState) -> bool:
+        """Determine if a given state is terminal or not.
+
+        # Arguments
+        env_state (MathyEnvState): The state to inspect
+
+        # Returns
+        (bool): A boolean indicating if the state is terminal or not.
+        """
+        return is_terminal_transition(self.get_state_transition(env_state))
+
+    def print_history(self, env_state: MathyEnvState) -> None:
+        """Render the history of an episode from a given state.
+
+        # Arguments
+        env_state (MathyEnvState): The state to render the history of.
+        """
+        history: List[MathyEnvStateStep] = env_state.agent.history[:]
+        initial_step: MathyEnvStateStep = history.pop(0)
+        curr_state: MathyEnvState = MathyEnvState(
+            problem=initial_step.raw, max_moves=env_state.max_moves,
+        )
+        self.print_state(curr_state, "initial-state")
+        while not self.is_terminal_state(curr_state):
+            step: MathyEnvStateStep = history.pop(0)
+            curr_state, transition, change = self.get_next_state(
+                curr_state, step.action + (step.focus * len(self.rules))
+            )
+            rule_idx, token_idx = self.get_action_indices(step.action)
+            rule: BaseRule = self.rules[rule_idx]
+            self.print_state(
+                env_state=curr_state,
+                action_name=rule.name[:25].lower(),
+                token_index=int(f"{step.focus}".zfill(3)),
+                change=change,
+                change_reward=transition.reward,
+            )
+
     def render_state(
         self,
         env_state: MathyEnvState,
         action_name: str,
         token_index: int = -1,
         change: ExpressionChangeRule = None,
         change_reward: float = 0.0,
-    ):
+    ) -> str:
         """Render the given state to a string suitable for printing to a log"""
         changed_problem = env_state.agent.problem
         if change is not None and change.result is not None:

libraries/mathy_python/tests/test_envs.py

@@ -47,9 +47,20 @@ def test_env_terminal_conditions():
     for text, is_win in expectations + out_of_scope_valid:
         env_state = MathyEnvState(problem=text)
         reward = env.get_state_transition(env_state)
+        assert text == text and env.is_terminal_state(env_state) == bool(is_win)
         assert text == text and is_terminal_transition(reward) == bool(is_win)
 
 
+def test_print_history():
+    env = PolySimplify()
+    env_state = MathyEnvState(problem="4x+2")
+    for i in range(10):
+        env_state = env_state.get_out_state(
+            problem="2+4x", focus=i, moves_remaining=10 - i, action=i
+        )
+    assert env.print_history(env_state) is None
+
+
 def test_env_finalize_state():
     env = PolySimplify()
 

libraries/website/docs/api/env.md

@@ -7,6 +7,7 @@ MathyEnv(
     rules: List[mathy.core.rule.BaseRule] = None,
     max_moves: int = 20,
     verbose: bool = False,
+    error_invalid: bool = False,
     reward_discount: float = 0.99,
 )
 ```
@@ -144,10 +145,10 @@ __Returns__
 MathyEnv.get_token_at_index(
     self,
     expression: mathy.core.expressions.MathExpression,
-    focus_index: int,
+    index: int,
 ) -> Optional[mathy.core.expressions.MathExpression]
 ```
-Get the token that is `focus_index` from the left of the expression
+Get the token that is `index` from the left of the expression
 ### get_valid_moves
 ```python
 MathyEnv.get_valid_moves(self, env_state:mathy.state.MathyEnvState) -> List[int]
@@ -176,6 +177,20 @@ MathyEnv.get_win_signal(self, env_state:mathy.state.MathyEnvState) -> float
 Calculate the reward value for completing the episode. This is done
 so that the reward signal can be scaled based on the time it took to
 complete the episode.
+### is_terminal_state
+```python
+MathyEnv.is_terminal_state(self, env_state:mathy.state.MathyEnvState) -> bool
+```
+Determine if a given state is terminal or not.
+
+__Arguments__
+
+- __env_state (MathyEnvState)__: The state to inspect
+
+__Returns__
+
+`(bool)`: A boolean indicating if the state is terminal or not.
+
 ### max_moves_fn
 ```python
 MathyEnv.max_moves_fn(
@@ -185,6 +200,16 @@ MathyEnv.max_moves_fn(
 ) -> int
 ```
 Return the environment specific maximum move count for a given prolem.
+### print_history
+```python
+MathyEnv.print_history(self, env_state:mathy.state.MathyEnvState) -> None
+```
+Render the history of an episode from a given state.
+
+__Arguments__
+
+- __env_state (MathyEnvState)__: The state to render the history of.
+
 ### print_state
 ```python
 MathyEnv.print_state(
@@ -227,7 +252,7 @@ MathyEnv.render_state(
     token_index: int = -1,
     change: mathy.core.rule.ExpressionChangeRule = None,
     change_reward: float = 0.0,
-)
+) -> str
 ```
 Render the given state to a string suitable for printing to a log
 ### state_to_observation

libraries/website/docs/api/state.md

@@ -9,8 +9,6 @@ MathyAgentState(
     problem_type,
     reward = 0.0,
     history = None,
-    focus_index = 0,
-    last_action = None,
 )
 ```
 The state related to an agent for a given environment state
@@ -35,13 +33,23 @@ This allocation strategy requires more memory but removes a class
 of potential issues around unintentional sharing of data and mutation
 by two different sources.
 
+### from_np
+```python
+MathyEnvState.from_np(input_bytes:numpy.ndarray) -> 'MathyEnvState'
+```
+Convert a numpy object into a state object
+### from_string
+```python
+MathyEnvState.from_string(input_string:str) -> 'MathyEnvState'
+```
+Convert a string representation of state into a state object
 ### get_out_state
 ```python
 MathyEnvState.get_out_state(
     self,
     problem: str,
+    focus: int,
     action: int,
-    focus_index: int,
     moves_remaining: int,
 ) -> 'MathyEnvState'
 ```
@@ -60,11 +68,31 @@ __Example__
 - `mycorp.envs.solve_impossible_problems` -> `[12375561, -2838517]`
 
 
+### to_np
+```python
+MathyEnvState.to_np(self) -> numpy.ndarray
+```
+Convert a state object into a numpy representation
+### to_observation
+```python
+MathyEnvState.to_observation(
+    self,
+    move_mask: Optional[List[int]] = None,
+    hash_type: Optional[List[int]] = None,
+    parser: Optional[mathy.core.parser.ExpressionParser] = None,
+) -> mathy.state.MathyObservation
+```
+Convert a state into an observation
 ### to_start_observation
 ```python
 MathyEnvState.to_start_observation(self) -> mathy.state.MathyObservation
 ```
 Generate an episode start MathyObservation
+### to_string
+```python
+MathyEnvState.to_string(self) -> str
+```
+Convert a state object into a string representation
 ## MathyEnvStateStep
 ```python
 MathyEnvStateStep(self, /, *args, **kwargs)