chuk-puzzles-gym 0.10__py3-none-any.whl → 0.10.2__py3-none-any.whl

chuk_puzzles_gym/server.py

@@ -63,6 +63,9 @@ class ArcadeHandler(TelnetHandler):
         if not self.current_game:
             return
 
+        # Get final reasoning metrics
+        reasoning = self.current_game.get_reasoning_metrics().to_dict()
+
         if self.output_mode == OutputMode.JSON:
             await self.send_json_response(
                 type="complete",
@@ -72,17 +75,27 @@ class ArcadeHandler(TelnetHandler):
                 invalid_moves=self.current_game.invalid_moves,
                 hints_used=self.current_game.hints_used,
                 optimal_steps=self.current_game.optimal_steps,
+                reasoning_metrics=reasoning,
             )
         elif self.output_mode == OutputMode.STRICT:
             await self.send_line(
                 f"COMPLETE:{self.current_game.moves_made}:{self.current_game.invalid_moves}:"
-                f"{self.current_game.hints_used}"
+                f"{self.current_game.hints_used}:"
+                f"BT={reasoning['backtrack_count']}:"
+                f"OH={reasoning['reasoning_overhead']:.2f}:"
+                f"ST={reasoning['progress_steadiness']:.2f}"
             )
         else:
             await self.send_line("\n" + "=" * 50)
             await self.send_line("CONGRATULATIONS! YOU SOLVED IT!")
             await self.send_line("=" * 50)
             await self.send_line(self.current_game.get_stats())
+            await self.send_line("")
+            await self.send_line("Reasoning Depth:")
+            await self.send_line(f"  Backtrack rate:      {reasoning['backtrack_rate']:.0%}")
+            await self.send_line(f"  Progress steadiness: {reasoning['progress_steadiness']:.0%}")
+            await self.send_line(f"  Reasoning overhead:  {reasoning['reasoning_overhead']:.1f}x optimal")
+            await self.send_line(f"  Error streak max:    {reasoning['error_streak_max']}")
             await self.send_line("\nType 'menu' to play another game.")
             await self.send_line("=" * 50 + "\n")
 
@@ -109,6 +122,9 @@ class ArcadeHandler(TelnetHandler):
             "constraint_density": profile.constraint_density,
         }
 
+        # Reasoning depth metrics
+        reasoning = self.current_game.get_reasoning_metrics().to_dict()
+
         return {
             "game": self.current_game.name,
             "difficulty": self.current_game.difficulty.value,
@@ -120,6 +136,7 @@ class ArcadeHandler(TelnetHandler):
             "optimal_steps": self.current_game.optimal_steps,
             "is_complete": self.current_game.is_complete(),
             "difficulty_profile": profile_dict,
+            "reasoning_metrics": reasoning,
             "grid": grid,
         }
 
@@ -435,9 +452,10 @@ class ArcadeHandler(TelnetHandler):
             return
 
         if cmd_enum == GameCommand.STATS:
-            # Show detailed stats including difficulty profile
+            # Show detailed stats including difficulty profile and reasoning metrics
             profile = self.current_game.difficulty_profile
             optimal = self.current_game.optimal_steps
+            reasoning = self.current_game.get_reasoning_metrics().to_dict()
 
             if self.output_mode == OutputMode.JSON:
                 await self.send_json_response(
@@ -455,11 +473,15 @@ class ArcadeHandler(TelnetHandler):
                         "state_observability": profile.state_observability,
                         "constraint_density": profile.constraint_density,
                     },
+                    reasoning_metrics=reasoning,
                 )
             elif self.output_mode == OutputMode.STRICT:
                 await self.send_line(
                     f"STATS:{self.current_game.moves_made}:{self.current_game.invalid_moves}:"
-                    f"{self.current_game.hints_used}:{optimal or 0}"
+                    f"{self.current_game.hints_used}:{optimal or 0}:"
+                    f"BT={reasoning['backtrack_count']}:"
+                    f"OH={reasoning['reasoning_overhead']:.2f}:"
+                    f"ST={reasoning['progress_steadiness']:.2f}"
                 )
             else:
                 await self.send_line("")
@@ -482,6 +504,15 @@ class ArcadeHandler(TelnetHandler):
                     await self.send_line(f"  Optimal steps: {optimal}")
                     await self.send_line(f"  Current efficiency: {efficiency:.1%}")
                 await self.send_line("")
+                await self.send_line("Reasoning Depth:")
+                await self.send_line(f"  Backtrack count:     {reasoning['backtrack_count']}")
+                await self.send_line(f"  Backtrack rate:      {reasoning['backtrack_rate']:.0%}")
+                await self.send_line(f"  Progress velocity:   {reasoning['progress_velocity']:.2f} cells/step")
+                await self.send_line(f"  Progress steadiness: {reasoning['progress_steadiness']:.0%}")
+                await self.send_line(f"  Reasoning overhead:  {reasoning['reasoning_overhead']:.1f}x optimal")
+                await self.send_line(f"  Error streak max:    {reasoning['error_streak_max']}")
+                await self.send_line(f"  Total actions:       {reasoning['total_actions']}")
+                await self.send_line("")
                 await self.send_line("Difficulty Profile:")
                 await self.send_line(f"  Logic depth: {profile.logic_depth}")
                 await self.send_line(f"  Branching factor: {profile.branching_factor:.1f}")
@@ -599,10 +630,6 @@ class ArcadeHandler(TelnetHandler):
         if self.game_handler and cmd_enum in self.game_handler.supported_commands:
             result = await self.game_handler.handle_command(cmd_enum, parts[1:])
 
-            # Track invalid moves
-            if not result.result.success:
-                self.current_game.invalid_moves += 1
-
             # Send result based on output mode
             code = "OK" if result.result.success else "INVALID"
             await self.send_result(result.result.success, result.result.message, code)
@@ -626,9 +653,7 @@ class ArcadeHandler(TelnetHandler):
                 num = int(parts[3])
 
                 result = await self.current_game.validate_move(row, col, num)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((row, col), result.success)
 
                 await self.send_result(result.success, result.message, "PLACED" if result.success else "INVALID_MOVE")
 
@@ -639,7 +664,6 @@ class ArcadeHandler(TelnetHandler):
                         await self.send_game_complete()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -653,9 +677,7 @@ class ArcadeHandler(TelnetHandler):
                 col = int(parts[2])
 
                 result = await self.current_game.validate_move(row, col, 0)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((row, col), result.success)
 
                 await self.send_result(result.success, result.message, "CLEARED" if result.success else "INVALID_CLEAR")
 
@@ -663,7 +685,6 @@ class ArcadeHandler(TelnetHandler):
                     await self.display_puzzle()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -693,9 +714,7 @@ class ArcadeHandler(TelnetHandler):
                 col = int(parts[2])
 
                 result = await self.current_game.validate_move(row, col)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((row, col), result.success)
 
                 await self.send_result(result.success, result.message, "PRESSED" if result.success else "INVALID_PRESS")
 
@@ -706,7 +725,6 @@ class ArcadeHandler(TelnetHandler):
                         await self.send_game_complete()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -718,9 +736,7 @@ class ArcadeHandler(TelnetHandler):
 
             cat1, val1, cat2, val2 = parts[1], parts[2], parts[3], parts[4]
             result = await self.current_game.validate_move(cat1, val1, cat2, val2, True)
-
-            if not result.success:
-                self.current_game.invalid_moves += 1
+            self.current_game.record_move((cat1, val1, cat2, val2), result.success)
 
             await self.send_result(result.success, result.message, "CONNECTED" if result.success else "INVALID_CONNECT")
             if result.success:
@@ -736,9 +752,7 @@ class ArcadeHandler(TelnetHandler):
 
             cat1, val1, cat2, val2 = parts[1], parts[2], parts[3], parts[4]
             result = await self.current_game.validate_move(cat1, val1, cat2, val2, False)
-
-            if not result.success:
-                self.current_game.invalid_moves += 1
+            self.current_game.record_move((cat1, val1, cat2, val2), result.success)
 
             await self.send_result(result.success, result.message, "EXCLUDED" if result.success else "INVALID_EXCLUDE")
             if result.success:
@@ -758,9 +772,7 @@ class ArcadeHandler(TelnetHandler):
                 col = int(parts[2])
 
                 result = await self.current_game.validate_move("reveal", row, col)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((row, col), result.success)
 
                 await self.send_result(
                     result.success, result.message, "REVEALED" if result.success else "INVALID_REVEAL"
@@ -783,7 +795,6 @@ class ArcadeHandler(TelnetHandler):
                                 await self.send_line("=" * 50 + "\n")
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -797,9 +808,7 @@ class ArcadeHandler(TelnetHandler):
                 col = int(parts[2])
 
                 result = await self.current_game.validate_move("flag", row, col)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((row, col), result.success)
 
                 await self.send_result(result.success, result.message, "FLAGGED" if result.success else "INVALID_FLAG")
 
@@ -807,7 +816,6 @@ class ArcadeHandler(TelnetHandler):
                     await self.display_puzzle()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -824,9 +832,7 @@ class ArcadeHandler(TelnetHandler):
                 state = int(parts[4])
 
                 result = await self.current_game.validate_move(edge_type, row, col, state)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((edge_type, row, col), result.success)
 
                 await self.send_result(result.success, result.message, "SET" if result.success else "INVALID_SET")
 
@@ -837,7 +843,6 @@ class ArcadeHandler(TelnetHandler):
                         await self.send_game_complete()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only for row, col, state.", "PARSE_ERROR")
             return
 
@@ -851,9 +856,7 @@ class ArcadeHandler(TelnetHandler):
                 guess = [int(p) for p in parts[1:]]
 
                 result = await self.current_game.validate_move(*guess)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move(tuple(guess), result.success)
 
                 await self.send_result(result.success, result.message, "GUESSED" if result.success else "INVALID_GUESS")
 
@@ -874,7 +877,6 @@ class ArcadeHandler(TelnetHandler):
                         await self.send_line("=" * 50 + "\n")
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -888,9 +890,7 @@ class ArcadeHandler(TelnetHandler):
                 item_index = int(parts[1])
 
                 result = await self.current_game.validate_move("select", item_index)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((item_index,), result.success)
 
                 await self.send_result(
                     result.success, result.message, "SELECTED" if result.success else "INVALID_SELECT"
@@ -900,7 +900,6 @@ class ArcadeHandler(TelnetHandler):
                     await self.display_puzzle()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -913,9 +912,7 @@ class ArcadeHandler(TelnetHandler):
                 item_index = int(parts[1])
 
                 result = await self.current_game.validate_move("deselect", item_index)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((item_index,), result.success)
 
                 await self.send_result(
                     result.success, result.message, "DESELECTED" if result.success else "INVALID_DESELECT"
@@ -925,7 +922,6 @@ class ArcadeHandler(TelnetHandler):
                     await self.display_puzzle()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -941,9 +937,7 @@ class ArcadeHandler(TelnetHandler):
                 color = parts[3].lower()
 
                 result = await self.current_game.validate_move(row, col, color)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((row, col), result.success)
 
                 await self.send_result(result.success, result.message, "MARKED" if result.success else "INVALID_MARK")
 
@@ -954,7 +948,6 @@ class ArcadeHandler(TelnetHandler):
                         await self.send_game_complete()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Row and col must be numbers.", "PARSE_ERROR")
             return
 
@@ -969,9 +962,7 @@ class ArcadeHandler(TelnetHandler):
                 col = int(parts[2])
 
                 result = await self.current_game.validate_move(row, col, "shade")
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((row, col), result.success)
 
                 await self.send_result(result.success, result.message, "SHADED" if result.success else "INVALID_SHADE")
 
@@ -982,7 +973,6 @@ class ArcadeHandler(TelnetHandler):
                         await self.send_game_complete()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -1000,9 +990,7 @@ class ArcadeHandler(TelnetHandler):
                 count = int(parts[5])
 
                 result = await self.current_game.validate_move(r1, c1, r2, c2, count)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((r1, c1, r2, c2), result.success)
 
                 await self.send_result(
                     result.success, result.message, "BRIDGED" if result.success else "INVALID_BRIDGE"
@@ -1015,7 +1003,6 @@ class ArcadeHandler(TelnetHandler):
                         await self.send_game_complete()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -1028,9 +1015,7 @@ class ArcadeHandler(TelnetHandler):
             direction = parts[1].lower()
 
             result = await self.current_game.validate_move(direction)
-
-            if not result.success:
-                self.current_game.invalid_moves += 1
+            self.current_game.record_move((direction,), result.success)
 
             await self.send_result(result.success, result.message, "MOVED" if result.success else "INVALID_MOVE")
 
@@ -1054,9 +1039,7 @@ class ArcadeHandler(TelnetHandler):
                 start_time = int(parts[3])
 
                 result = await self.current_game.validate_move(task_id, worker_id, start_time)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((task_id,), result.success)
 
                 await self.send_result(
                     result.success, result.message, "ASSIGNED" if result.success else "INVALID_ASSIGN"
@@ -1068,7 +1051,6 @@ class ArcadeHandler(TelnetHandler):
                         await self.send_game_complete()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 
@@ -1081,9 +1063,7 @@ class ArcadeHandler(TelnetHandler):
                 task_id = int(parts[1])
 
                 result = await self.current_game.validate_move(task_id, 0, -1)
-
-                if not result.success:
-                    self.current_game.invalid_moves += 1
+                self.current_game.record_move((task_id,), result.success)
 
                 await self.send_result(
                     result.success, result.message, "UNASSIGNED" if result.success else "INVALID_UNASSIGN"
@@ -1093,7 +1073,6 @@ class ArcadeHandler(TelnetHandler):
                     await self.display_puzzle()
 
             except ValueError:
-                self.current_game.invalid_moves += 1
                 await self.send_result(False, "Invalid input. Use numbers only.", "PARSE_ERROR")
             return
 

{chuk_puzzles_gym-0.10.dist-info → chuk_puzzles_gym-0.10.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-puzzles-gym
-Version: 0.10
+Version: 0.10.2
 Summary: Multi-game puzzle gym for LLM training and benchmarking - 30 constraint puzzles with synthetic data generation
 Author: Chris Hay
 License: MIT
@@ -93,10 +93,17 @@ Once connected, type `help` to see available games, or `sudoku easy` to start pl
   - Enable with `mode agent` command
   - Machine-parseable grid format with clear start/end markers
   - Compact output optimized for LLM tool integration
+- **Reasoning Depth Metrics** - Measure *how* agents reason, not just if they succeed
+  - Backtrack detection (did the agent revise previous placements?)
+  - Progress steadiness (monotonic advance toward solution?)
+  - Error streak analysis (isolated mistakes vs. clustered confusion?)
+  - Reasoning overhead (wasted work relative to optimal path)
+  - Solver distance traces (remaining work after each valid move)
+  - Available in all paths: Gym env, eval harness, and server (telnet/WebSocket)
 - **Evaluation Harness** (`chuk-puzzles-eval`) - Built-in benchmarking CLI
   - Batch evaluation with configurable episodes
   - Multiple output formats (JSON, CSV, Markdown)
-  - Metrics: moves, invalid moves, hints, solve time
+  - Metrics: moves, invalid moves, hints, solve time, reasoning depth
   - Reproducible with deterministic seeds
 - **Dataset Export** (`chuk-puzzles-export`) - Synthetic data generation for LLM training
   - JSONL output with complete problem definitions and solutions
@@ -500,6 +507,7 @@ games = PuzzleEnv.available_games()
 
 - **All 30 games** accessible through unified API
 - **Configurable rewards** for correct moves, invalid attempts, completion bonuses
+- **Reasoning depth metrics** tracking backtracks, progress steadiness, error patterns
 - **Hint system** with optional budget limits
 - **Solver-free mode** for pure reasoning benchmarks
 - **Efficiency scoring** based on optimal step counts
@@ -515,8 +523,25 @@ obs = {
     "moves": 5,
     "invalid_moves": 1,
     "hints_used": 2,
+    "hints_remaining": 98,
     "is_complete": False,
-    "grid": [[4, 0, 8, ...], ...]  # Game-specific state
+    "grid": [[4, 0, 8, ...], ...],  # Game-specific state
+    "render": "  | 1 2 3 | ...",     # ASCII grid
+}
+
+# Info dict includes reasoning metrics and difficulty profile
+info = {
+    "optimal_steps": 45,
+    "difficulty_profile": {"logic_depth": 2, "branching_factor": 2.0, ...},
+    "reasoning_metrics": {
+        "backtrack_count": 0,
+        "backtrack_rate": 0.0,
+        "progress_velocity": 1.0,
+        "progress_steadiness": 1.0,
+        "reasoning_overhead": 1.0,
+        "error_streak_max": 0,
+        "solver_distance_trace": [44, 43, 42, ...],
+    },
 }
 ```
 
@@ -546,6 +571,89 @@ config = SolverConfig(hint_budget=5, hint_penalty=0.1)
 env = PuzzleEnv("sudoku", solver_config=config)
 ```
 
+## Reasoning Depth Metrics
+
+Beyond binary success/failure, the system measures **how** an agent reasons through puzzles. These metrics are available in all interaction paths: the Gym environment, the evaluation harness, and the telnet/WebSocket server.
+
+### Metrics
+
+| Metric | Description | Perfect Score |
+|--------|-------------|---------------|
+| `backtrack_count` | Times the agent revised a previous placement | 0 |
+| `backtrack_rate` | Fraction of valid moves that were backtracks | 0% |
+| `progress_velocity` | Average cells solved per step | 1.0 |
+| `progress_steadiness` | How monotonically remaining work decreases (1.0 = never stalls) | 100% |
+| `reasoning_overhead` | Total actions / optimal path length (1.0 = no waste) | 1.0x |
+| `error_streak_max` | Longest run of consecutive invalid moves | 0 |
+| `avg_error_streak` | Average length of error bursts | 0.0 |
+| `solver_distance_trace` | Remaining positions after each valid move | Monotonically decreasing |
+
+### Usage in Gym Environment
+
+```python
+from chuk_puzzles_gym.gym_env import PuzzleEnv
+
+env = PuzzleEnv("sudoku", difficulty="easy", seed=42)
+obs, info = await env.reset()
+
+# Reasoning metrics available in info after reset
+print(info["reasoning_metrics"])
+
+# ... agent plays ...
+obs, reward, terminated, truncated, info = await env.step("place 1 1 5")
+
+# On episode end, info includes full reasoning metrics
+if terminated:
+    metrics = info["reasoning_metrics"]
+    print(f"Backtrack rate: {metrics['backtrack_rate']:.0%}")
+    print(f"Overhead: {metrics['reasoning_overhead']:.1f}x")
+    print(f"Steadiness: {metrics['progress_steadiness']:.0%}")
+```
+
+### Usage in Server (Telnet/WebSocket)
+
+Reasoning metrics are included automatically in server output:
+
+- **JSON mode**: `reasoning_metrics` dict in every state response and completion message
+- **STRICT mode**: `BT=`, `OH=`, `ST=` fields appended to STATS and COMPLETE messages
+- **Normal mode**: "Reasoning Depth" section shown on completion and in `stats` command
+
+```
+> mode json
+> place 1 1 5
+{"type":"result","success":true,...,"state":{...,"reasoning_metrics":{"backtrack_count":0,...}}}
+
+> stats
+{"type":"stats",...,"reasoning_metrics":{"backtrack_count":0,"backtrack_rate":0.0,...}}
+```
+
+### Usage in Evaluation Harness
+
+```bash
+# Reasoning metrics included in all output formats
+chuk-puzzles-eval sudoku -d easy -n 10 -o json
+```
+
+```python
+from chuk_puzzles_gym.eval import evaluate_game
+
+report = await evaluate_game("sudoku", difficulty="easy", episodes=10)
+report.print_summary()  # Includes "Reasoning Depth" section
+
+# Aggregate metrics
+print(f"Avg backtrack rate: {report.avg_backtrack_rate:.0%}")
+print(f"Avg overhead: {report.avg_reasoning_overhead:.1f}x")
+print(f"Avg steadiness: {report.avg_progress_steadiness:.0%}")
+```
+
+### What the Metrics Reveal
+
+A **perfect solver** shows: 0 backtracks, 1.0x overhead, 100% steadiness, 1.0 velocity.
+
+A **struggling agent** shows: high backtrack rate (revising decisions), error streaks (clustered confusion), low steadiness (stalling progress), and high overhead (wasted work).
+
+These patterns are visible even when two agents both eventually solve a puzzle — the metrics expose the **quality of the reasoning path**, not just the outcome.
+
 ## Evaluation Harness
 
 The project includes a built-in **evaluation harness** for benchmarking puzzle-solving agents:
@@ -604,6 +712,12 @@ Avg Time:   12ms
 | `hints_used` | Number of hints requested |
 | `wall_time_ms` | Time to solve in milliseconds |
 | `seed` | Puzzle seed for reproducibility |
+| `backtrack_count` | Times agent revised a previous placement |
+| `backtrack_rate` | Fraction of valid moves that were backtracks |
+| `progress_steadiness` | How monotonically progress advances (1.0 = perfect) |
+| `reasoning_overhead` | Total actions / optimal path (1.0 = no waste) |
+| `error_streak_max` | Longest run of consecutive invalid moves |
+| `progress_velocity` | Average cells solved per step |
 
 ## Dataset Export
 
@@ -1194,12 +1308,13 @@ chuk-puzzles-gym/
 │       │   ├── base.py           # GridPosition, MoveResult
 │       │   ├── config.py         # Base GameConfig
 │       │   ├── enums.py          # DifficultyLevel, GameCommand, etc.
+│       │   ├── evaluation.py     # ReasoningMetrics, EpisodeResult, EvaluationSummary
 │       │   └── games.py          # Game-specific models (Cage, Task, etc.)
 │       └── games/                # Self-contained game modules
 │           ├── __init__.py       # AVAILABLE_GAMES registry
 │           ├── _base/            # Base classes
 │           │   ├── __init__.py
-│           │   ├── game.py       # PuzzleGame ABC
+│           │   ├── game.py       # PuzzleGame ABC + ReasoningTracker
 │           │   └── commands.py   # GameCommandHandler ABC
 │           ├── sudoku/           # Example game module
 │           │   ├── __init__.py   # Exports SudokuGame
@@ -1226,6 +1341,7 @@ chuk-puzzles-gym/
 │   ├── example_graph_coloring.py # Graph Coloring game logic demo
 │   ├── example_cryptarithmetic.py# Cryptarithmetic game logic demo
 │   ├── example_rush_hour.py      # Rush Hour game logic demo
+│   ├── example_reasoning_metrics.py # Reasoning depth metrics demo
 │   └── README.md                 # Example usage guide
 ├── .github/workflows/            # CI/CD workflows
 ├── pyproject.toml                # Modern Python project config
@@ -1465,9 +1581,10 @@ See [ROADMAP.md](ROADMAP.md) for the full development roadmap.
 ### Highlights
 
 **Benchmarking & Metrics**
-- Puzzle complexity metrics (constraint count, variable count, branching factor)
-- Episode model for tracking game sessions
-- Trace logging for offline analysis
+- ~~Puzzle complexity metrics~~ (implemented: constraint count, variable count, branching factor)
+- ~~Episode model for tracking game sessions~~ (implemented: EpisodeResult with ReasoningMetrics)
+- ~~Reasoning depth metrics~~ (implemented: backtrack detection, progress steadiness, error patterns)
+- ~~Trace logging for offline analysis~~ (implemented: solver distance traces in all output paths)
 
 **Agent Evaluation Tools**
 - Batch evaluation harness CLI