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

chuk_puzzles_gym/eval.py

@@ -25,7 +25,7 @@ import sys
 import time
 from dataclasses import dataclass, field
 from datetime import datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     pass
@@ -100,8 +100,36 @@ class EvaluationReport:
             return 0.0
         return sum(e.hints_used for e in self.episodes) / self.total_episodes
 
+    @property
+    def avg_backtrack_rate(self) -> float:
+        """Average backtrack rate across episodes with reasoning metrics."""
+        with_metrics = [e for e in self.episodes if e.reasoning_metrics is not None]
+        if not with_metrics:
+            return 0.0
+        return sum(e.reasoning_metrics.backtrack_rate for e in with_metrics) / len(with_metrics)  # type: ignore[union-attr]
+
+    @property
+    def avg_reasoning_overhead(self) -> float:
+        """Average reasoning overhead across episodes with reasoning metrics."""
+        with_metrics = [
+            e for e in self.episodes if e.reasoning_metrics is not None and e.reasoning_metrics.reasoning_overhead > 0
+        ]
+        if not with_metrics:
+            return 0.0
+        return sum(e.reasoning_metrics.reasoning_overhead for e in with_metrics) / len(with_metrics)  # type: ignore[union-attr]
+
+    @property
+    def avg_progress_steadiness(self) -> float:
+        """Average progress steadiness across episodes with reasoning metrics."""
+        with_metrics = [e for e in self.episodes if e.reasoning_metrics is not None]
+        if not with_metrics:
+            return 0.0
+        return sum(e.reasoning_metrics.progress_steadiness for e in with_metrics) / len(with_metrics)  # type: ignore[union-attr]
+
     def to_markdown(self) -> str:
         """Generate markdown report."""
+        has_reasoning = any(e.reasoning_metrics is not None for e in self.episodes)
+
         lines = [
             f"# {self.game.title()} {self.difficulty.title()} Evaluation",
             "",
@@ -112,24 +140,78 @@ class EvaluationReport:
             f"**Avg Hints:** {self.avg_hints:.1f}",
             f"**Avg Efficiency:** {self.avg_efficiency:.1%}",
             f"**Avg Time:** {self.avg_time_ms:.0f}ms",
-            "",
-            f"**Solver Config:** {'solver-free' if not self.solver_config.solver_allowed else f'budget={self.solver_config.hint_budget}, penalty={self.solver_config.hint_penalty}'}",
-            "",
-            "## Episode Details",
-            "",
-            "| Seed | Status | Steps | Invalid | Hints | Efficiency | Time (ms) |",
-            "|------|--------|-------|---------|-------|------------|-----------|",
         ]
-        for e in self.episodes:
-            status = "solved" if e.success else e.status.value
-            eff = f"{e.efficiency_score:.0%}" if e.success else "-"
+
+        if has_reasoning:
+            lines.extend(
+                [
+                    "",
+                    "### Reasoning Depth",
+                    f"**Avg Backtrack Rate:** {self.avg_backtrack_rate:.1%}",
+                    f"**Avg Reasoning Overhead:** {self.avg_reasoning_overhead:.2f}x",
+                    f"**Avg Progress Steadiness:** {self.avg_progress_steadiness:.1%}",
+                ]
+            )
+
+        lines.extend(
+            [
+                "",
+                f"**Solver Config:** {'solver-free' if not self.solver_config.solver_allowed else f'budget={self.solver_config.hint_budget}, penalty={self.solver_config.hint_penalty}'}",
+                "",
+                "## Episode Details",
+                "",
+            ]
+        )
+
+        if has_reasoning:
+            lines.append(
+                "| Seed | Status | Steps | Invalid | Hints | Efficiency | Backtracks | Steadiness | Time (ms) |"
+            )
             lines.append(
-                f"| {e.seed} | {status} | {e.steps_taken} | {e.invalid_actions} | {e.hints_used} | {eff} | {e.wall_time_ms} |"
+                "|------|--------|-------|---------|-------|------------|------------|------------|-----------|"
             )
+            for e in self.episodes:
+                status = "solved" if e.success else e.status.value
+                eff = f"{e.efficiency_score:.0%}" if e.success else "-"
+                bt = str(e.reasoning_metrics.backtrack_count) if e.reasoning_metrics else "-"
+                st = f"{e.reasoning_metrics.progress_steadiness:.0%}" if e.reasoning_metrics else "-"
+                lines.append(
+                    f"| {e.seed} | {status} | {e.steps_taken} | {e.invalid_actions} | {e.hints_used} | {eff} | {bt} | {st} | {e.wall_time_ms} |"
+                )
+        else:
+            lines.append("| Seed | Status | Steps | Invalid | Hints | Efficiency | Time (ms) |")
+            lines.append("|------|--------|-------|---------|-------|------------|-----------|")
+            for e in self.episodes:
+                status = "solved" if e.success else e.status.value
+                eff = f"{e.efficiency_score:.0%}" if e.success else "-"
+                lines.append(
+                    f"| {e.seed} | {status} | {e.steps_taken} | {e.invalid_actions} | {e.hints_used} | {eff} | {e.wall_time_ms} |"
+                )
+
         return "\n".join(lines)
 
     def to_json(self) -> str:
         """Generate JSON report."""
+        summary: dict[str, Any] = {
+            "total_episodes": self.total_episodes,
+            "solved_count": self.solved_count,
+            "solve_rate": self.solve_rate,
+            "avg_steps": self.avg_moves,
+            "avg_invalid": self.avg_invalid_moves,
+            "avg_hints": self.avg_hints,
+            "avg_efficiency": self.avg_efficiency,
+            "avg_time_ms": self.avg_time_ms,
+        }
+
+        # Add aggregate reasoning metrics if available
+        has_reasoning = any(e.reasoning_metrics is not None for e in self.episodes)
+        if has_reasoning:
+            summary["reasoning"] = {
+                "avg_backtrack_rate": round(self.avg_backtrack_rate, 3),
+                "avg_reasoning_overhead": round(self.avg_reasoning_overhead, 3),
+                "avg_progress_steadiness": round(self.avg_progress_steadiness, 3),
+            }
+
         return json.dumps(
             {
                 "game": self.game,
@@ -139,16 +221,7 @@ class EvaluationReport:
                     "hint_budget": self.solver_config.hint_budget,
                     "hint_penalty": self.solver_config.hint_penalty,
                 },
-                "summary": {
-                    "total_episodes": self.total_episodes,
-                    "solved_count": self.solved_count,
-                    "solve_rate": self.solve_rate,
-                    "avg_steps": self.avg_moves,
-                    "avg_invalid": self.avg_invalid_moves,
-                    "avg_hints": self.avg_hints,
-                    "avg_efficiency": self.avg_efficiency,
-                    "avg_time_ms": self.avg_time_ms,
-                },
+                "summary": summary,
                 "episodes": [e.to_summary_dict() for e in self.episodes],
             },
             indent=2,
@@ -158,35 +231,61 @@ class EvaluationReport:
         """Generate CSV report."""
         import io
 
+        has_reasoning = any(e.reasoning_metrics is not None for e in self.episodes)
+
         output = io.StringIO()
         writer = csv.writer(output)
-        writer.writerow(
-            [
-                "game",
-                "difficulty",
-                "seed",
-                "status",
-                "steps_taken",
-                "invalid_actions",
-                "hints_used",
-                "efficiency",
-                "wall_time_ms",
-            ]
-        )
-        for e in self.episodes:
-            writer.writerow(
+
+        header = [
+            "game",
+            "difficulty",
+            "seed",
+            "status",
+            "steps_taken",
+            "invalid_actions",
+            "hints_used",
+            "efficiency",
+            "wall_time_ms",
+        ]
+        if has_reasoning:
+            header.extend(
                 [
-                    e.game,
-                    e.difficulty.value,
-                    e.seed,
-                    e.status.value,
-                    e.steps_taken,
-                    e.invalid_actions,
-                    e.hints_used,
-                    f"{e.efficiency_score:.3f}",
-                    e.wall_time_ms,
+                    "backtrack_count",
+                    "backtrack_rate",
+                    "reasoning_overhead",
+                    "progress_steadiness",
+                    "error_streak_max",
                 ]
             )
+        writer.writerow(header)
+
+        for e in self.episodes:
+            row = [
+                e.game,
+                e.difficulty.value,
+                e.seed,
+                e.status.value,
+                e.steps_taken,
+                e.invalid_actions,
+                e.hints_used,
+                f"{e.efficiency_score:.3f}",
+                e.wall_time_ms,
+            ]
+            if has_reasoning:
+                rm = e.reasoning_metrics
+                if rm is not None:
+                    row.extend(
+                        [
+                            rm.backtrack_count,
+                            f"{rm.backtrack_rate:.3f}",
+                            f"{rm.reasoning_overhead:.3f}",
+                            f"{rm.progress_steadiness:.3f}",
+                            rm.error_streak_max,
+                        ]
+                    )
+                else:
+                    row.extend(["", "", "", "", ""])
+            writer.writerow(row)
         return output.getvalue()
 
     def print_summary(self) -> None:
@@ -206,6 +305,15 @@ class EvaluationReport:
         print(f"Avg Efficiency: {self.avg_efficiency:.1%}")
         print(f"Avg Time:   {self.avg_time_ms:.0f}ms")
 
+        # Reasoning depth metrics
+        has_reasoning = any(e.reasoning_metrics is not None for e in self.episodes)
+        if has_reasoning:
+            print("-" * 40)
+            print("Reasoning Depth:")
+            print(f"  Backtrack Rate:      {self.avg_backtrack_rate:.1%}")
+            print(f"  Reasoning Overhead:  {self.avg_reasoning_overhead:.2f}x")
+            print(f"  Progress Steadiness: {self.avg_progress_steadiness:.1%}")
+
 
 async def _apply_hint(game: PuzzleGame, hint_data: tuple) -> MoveResult:
     """Apply a hint to the game based on game type.
@@ -433,15 +541,22 @@ async def run_episode(
             # Apply the hint based on game type
             try:
                 result = await _apply_hint(game, hint_data)
+                # Normalize hint_data to a tuple for position tracking
+                position = hint_data if isinstance(hint_data, tuple) else (hint_data,)
                 if result.success:
                     steps_taken += 1
+                    # Use game's dynamic optimal_steps (reflects current state)
+                    remaining = game.optimal_steps or 0
+                    game.reasoning_tracker.record_valid_move(position, remaining)
                 else:
                     invalid_actions += 1
+                    game.reasoning_tracker.record_invalid_move()
                     # If we get too many consecutive invalid moves, break
                     if invalid_actions > 50:
                         break
             except (TypeError, ValueError, AttributeError, IndexError):
                 invalid_actions += 1
+                game.reasoning_tracker.record_invalid_move()
                 if invalid_actions > 50:
                     break
         elif not use_hints:
@@ -461,6 +576,12 @@ async def run_episode(
     # Get retries from game if tracked
     retries = getattr(game, "retries", 0)
 
+    # Collect reasoning depth metrics (use pre-solve optimal_steps since
+    # the game's optimal_steps may be 0 after solving)
+    reasoning_metrics = game.reasoning_tracker.to_metrics(
+        optimal_path_length=optimal_steps if optimal_steps and optimal_steps >= 1 else None,
+    )
+
     return EpisodeResult(
         game=game.name,
         difficulty=DifficultyLevel(difficulty),
@@ -475,6 +596,7 @@ async def run_episode(
         retries=retries,
         optimal_steps=optimal_steps,
         solver_config=solver_config,
+        reasoning_metrics=reasoning_metrics,
     )
 
 

chuk_puzzles_gym/export/dataset.py

@@ -190,6 +190,12 @@ class DatasetExporter:
             if canonical:
                 gold_answer = str(canonical)
 
+        # Build reasoning tags from complexity profile
+        complexity_profile = game.complexity_profile
+        reasoning_type = complexity_profile.get("reasoning_type", "deductive")
+        search_space = complexity_profile.get("search_space", "medium")
+        tags = [domain, difficulty.value, f"reasoning:{reasoning_type}", f"search:{search_space}"]
+
         # Create Problem using core schema
         return Problem(
             # Identity
@@ -214,7 +220,7 @@ class DatasetExporter:
             ),
             # Metadata
             operation_count=game.optimal_steps,
-            tags=[domain, difficulty.value],
+            tags=tags,
         )
 
     @property

chuk_puzzles_gym/games/_base/game.py

@@ -1,10 +1,99 @@
 """Abstract base class for all puzzle games."""
 
+from __future__ import annotations
+
 import random
 from abc import ABC, abstractmethod
 from typing import Any
 
 from ...models import DifficultyLevel, DifficultyProfile, MoveResult, SolverConfig
+from ...models.evaluation import ReasoningMetrics
+
+
+class ReasoningTracker:
+    """Tracks reasoning depth metrics during puzzle gameplay.
+
+    Accumulates data about backtrack behavior, solver distance progression,
+    and error patterns. Produces a ReasoningMetrics snapshot on demand.
+
+    This is a lightweight, non-Pydantic class meant to be mutated during play.
+    """
+
+    __slots__ = (
+        "_placed_positions",
+        "_solver_distance_trace",
+        "_backtrack_count",
+        "_consecutive_errors",
+        "_error_streaks",
+        "_max_error_streak",
+        "_total_actions",
+    )
+
+    def __init__(self) -> None:
+        self._placed_positions: set[tuple[Any, ...]] = set()
+        self._solver_distance_trace: list[int] = []
+        self._backtrack_count: int = 0
+        self._consecutive_errors: int = 0
+        self._error_streaks: list[int] = []
+        self._max_error_streak: int = 0
+        self._total_actions: int = 0
+
+    def record_valid_move(self, position: tuple[Any, ...], remaining_count: int) -> None:
+        """Record a valid (successful) move.
+
+        Args:
+            position: The position/target of the move (for backtrack detection)
+            remaining_count: How many positions remain to be filled after this move
+        """
+        self._total_actions += 1
+
+        # Detect backtrack: placing at a position already placed before
+        if position in self._placed_positions:
+            self._backtrack_count += 1
+        self._placed_positions.add(position)
+
+        self._solver_distance_trace.append(remaining_count)
+
+        # Finalize any pending error streak
+        if self._consecutive_errors > 0:
+            self._error_streaks.append(self._consecutive_errors)
+            self._consecutive_errors = 0
+
+    def record_invalid_move(self) -> None:
+        """Record an invalid (failed) move."""
+        self._total_actions += 1
+        self._consecutive_errors += 1
+        self._max_error_streak = max(self._max_error_streak, self._consecutive_errors)
+
+    def to_metrics(self, optimal_path_length: int | None = None) -> ReasoningMetrics:
+        """Produce a frozen ReasoningMetrics snapshot.
+
+        Args:
+            optimal_path_length: Minimum steps to solve (from solver), if known.
+        """
+        # Finalize any pending error streak
+        error_streaks = list(self._error_streaks)
+        if self._consecutive_errors > 0:
+            error_streaks.append(self._consecutive_errors)
+
+        return ReasoningMetrics(
+            backtrack_count=self._backtrack_count,
+            solver_distance_trace=list(self._solver_distance_trace),
+            error_streak_max=self._max_error_streak,
+            error_streaks=error_streaks,
+            total_actions=self._total_actions,
+            optimal_path_length=optimal_path_length,
+        )
+
+    def reset(self) -> None:
+        """Reset all tracked state."""
+        self._placed_positions.clear()
+        self._solver_distance_trace.clear()
+        self._backtrack_count = 0
+        self._consecutive_errors = 0
+        self._error_streaks.clear()
+        self._max_error_streak = 0
+        self._total_actions = 0
 
 
 class PuzzleGame(ABC):
@@ -64,6 +153,9 @@ class PuzzleGame(ABC):
         self.game_started = False
         self._last_move_position: tuple[Any, ...] | None = None  # For retry detection
 
+        # Reasoning depth tracker
+        self._reasoning_tracker = ReasoningTracker()
+
     @abstractmethod
     async def generate_puzzle(self) -> None:
         """Generate a new puzzle with a unique solution.
@@ -162,8 +254,11 @@ class PuzzleGame(ABC):
         """
         if success:
             self.moves_made += 1
+            remaining = self._compute_remaining()
+            self._reasoning_tracker.record_valid_move(position, remaining)
         else:
             self.invalid_moves += 1
+            self._reasoning_tracker.record_invalid_move()
 
         # Detect retries (same position attempted again)
         if self._last_move_position == position:
@@ -183,6 +278,34 @@ class PuzzleGame(ABC):
         self.hints_used += 1
         return True
 
+    def _compute_remaining(self) -> int:
+        """Compute how many positions remain to be filled.
+
+        Uses optimal_steps directly since it is typically dynamic
+        (reflects current game state, e.g. counting empty cells).
+        Override in subclasses for more accurate tracking.
+        """
+        return self.optimal_steps or 0
+
+    def get_reasoning_metrics(self) -> ReasoningMetrics:
+        """Get a snapshot of reasoning depth metrics for the current episode.
+
+        Returns:
+            Frozen ReasoningMetrics with all tracked data.
+        """
+        optimal = self.optimal_steps
+        # optimal_path_length requires ge=1; treat 0 or negative as unknown
+        if optimal is not None and optimal < 1:
+            optimal = None
+        return self._reasoning_tracker.to_metrics(
+            optimal_path_length=optimal,
+        )
+
+    @property
+    def reasoning_tracker(self) -> ReasoningTracker:
+        """Access the reasoning tracker directly."""
+        return self._reasoning_tracker
+
     def can_use_hint(self) -> bool:
         """Check if hints are available without consuming one.
 

chuk_puzzles_gym/games/binary/game.py

@@ -358,6 +358,8 @@ class BinaryPuzzleGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         empty_cells = [(r, c) for r in range(self.size) for c in range(self.size) if self.grid[r][c] == -1]
         if not empty_cells:
             return None

chuk_puzzles_gym/games/bridges/game.py

@@ -415,6 +415,8 @@ class BridgesGame(PuzzleGame):
 
     async def get_hint(self) -> tuple[Any, str] | None:
         """Get a hint for the next move."""
+        if not self.can_use_hint():
+            return None
         # Find a bridge in the solution that's not yet placed correctly
         for bridge_key, solution_count in self.solution.items():
             current_count = self.bridges.get(bridge_key, 0)

chuk_puzzles_gym/games/cryptarithmetic/game.py

@@ -362,6 +362,11 @@ class CryptarithmeticGame(PuzzleGame):
 
         return "\n".join(lines)
 
+    def get_stats(self) -> str:
+        """Get current game statistics."""
+        assigned = sum(1 for v in self.player_mapping.values() if v is not None)
+        return f"Moves: {self.moves_made} | Assigned: {assigned}/{len(self.letters)} | Seed: {self.seed}"
+
     def get_rules(self) -> str:
         return (
             "CRYPTARITHMETIC\n"

chuk_puzzles_gym/games/einstein/game.py

@@ -281,6 +281,8 @@ class EinsteinGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None
         """
+        if not self.can_use_hint():
+            return None
         # Find first unassigned attribute in solution
         for i in range(self.num_houses):
             for attr in ATTRIBUTES:

chuk_puzzles_gym/games/fillomino/game.py

@@ -435,6 +435,8 @@ class FillominoGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         # Find an empty cell
         for r in range(self.size):
             for c in range(self.size):

chuk_puzzles_gym/games/futoshiki/game.py

@@ -288,6 +288,8 @@ class FutoshikiGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         empty_cells = [(r, c) for r in range(self.size) for c in range(self.size) if self.grid[r][c] == 0]
         if not empty_cells:
             return None

chuk_puzzles_gym/games/graph_coloring/commands.py

@@ -4,10 +4,14 @@ from typing import TYPE_CHECKING
 
 from ...models import GameCommand, MoveResult
 from .._base import CommandResult, GameCommandHandler
+from .game import COLOR_NAMES
 
 if TYPE_CHECKING:
     from .game import GraphColoringGame
 
+# Build a lookup from lowercase color name to color number
+_COLOR_NAME_TO_NUM = {name.lower(): i + 1 for i, name in enumerate(COLOR_NAMES)}
+
 
 class GraphColoringCommandHandler(GameCommandHandler):
     """Handles commands for Graph Coloring game."""
@@ -36,6 +40,16 @@ class GraphColoringCommandHandler(GameCommandHandler):
         else:
             return self.error_result(f"Unknown command: {cmd}")
 
+    def _parse_color(self, value: str) -> int | None:
+        """Parse a color argument as either an integer or a color name."""
+        # Try integer first
+        try:
+            return int(value)
+        except ValueError:
+            pass
+        # Try color name lookup
+        return _COLOR_NAME_TO_NUM.get(value.lower())
+
     async def _handle_place(self, args: list[str]) -> CommandResult:
         """Handle the PLACE command: place <node> <color>."""
         if len(args) != 2:
@@ -45,10 +59,13 @@ class GraphColoringCommandHandler(GameCommandHandler):
             )
 
         node = self.parse_int(args[0], "node")
-        color = self.parse_int(args[1], "color")
+        color = self._parse_color(args[1])
 
-        if node is None or color is None:
-            return self.error_result("Node and color must be integers.")
+        if node is None:
+            return self.error_result("Node must be an integer.")
+        if color is None:
+            valid = ", ".join(f"{i + 1}={COLOR_NAMES[i]}" for i in range(self.game.num_colors))
+            return self.error_result(f"Invalid color. Use a number or name: {valid}")
 
         result = await self.game.validate_move(node, color)
 

chuk_puzzles_gym/games/graph_coloring/game.py

@@ -289,6 +289,11 @@ class GraphColoringGame(PuzzleGame):
 
         return "\n".join(lines)
 
+    def get_stats(self) -> str:
+        """Get current game statistics."""
+        colored = sum(1 for n in range(1, self.num_nodes + 1) if self.coloring.get(n, 0) > 0)
+        return f"Moves: {self.moves_made} | Colored: {colored}/{self.num_nodes} | Edges: {len(self.edges)} | Seed: {self.seed}"
+
     def get_rules(self) -> str:
         return (
             f"GRAPH COLORING ({self.num_nodes} nodes, {self.num_colors} colors)\n"
@@ -298,9 +303,11 @@ class GraphColoringGame(PuzzleGame):
         )
 
     def get_commands(self) -> str:
+        color_map = ", ".join(f"{i + 1}={COLOR_NAMES[i]}" for i in range(self.num_colors))
         return (
             "Commands:\n"
-            f"  place <node> <color>  - Color a node (1-{self.num_colors})\n"
+            f"  place <node> <color>  - Color a node (number or name)\n"
+            f"  Colors: {color_map}\n"
             "  clear <node>          - Remove color from a node\n"
             "  hint                  - Get a hint\n"
             "  check                 - Check if solved\n"

chuk_puzzles_gym/games/hidato/game.py

@@ -302,6 +302,8 @@ class HidatoGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         # Find an empty cell
         empty_cells = [(r, c) for r in range(self.size) for c in range(self.size) if self.grid[r][c] == 0]
         if not empty_cells:

chuk_puzzles_gym/games/hitori/game.py

@@ -395,6 +395,8 @@ class HitoriGame(PuzzleGame):
 
     async def get_hint(self) -> tuple[Any, str] | None:
         """Get a hint for the next move."""
+        if not self.can_use_hint():
+            return None
         # Find a cell that should be shaded but isn't, or vice versa
         for r in range(self.size):
             for c in range(self.size):

chuk_puzzles_gym/games/kakuro/game.py

@@ -311,6 +311,8 @@ class KakuroGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         empty_cells = [
             (r, c)
             for r in range(self.size)

chuk_puzzles_gym/games/kenken/game.py

@@ -366,6 +366,8 @@ class KenKenGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         empty_cells = [(r, c) for r in range(self.size) for c in range(self.size) if self.grid[r][c] == 0]
         if not empty_cells:
             return None

chuk_puzzles_gym/games/killer_sudoku/game.py

@@ -395,6 +395,8 @@ class KillerSudokuGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         empty_cells = [(r, c) for r in range(9) for c in range(9) if self.grid[r][c] == 0]
         if not empty_cells:
             return None

chuk_puzzles_gym/games/knapsack/game.py

@@ -255,6 +255,8 @@ class KnapsackGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None
         """
+        if not self.can_use_hint():
+            return None
         # Suggest selecting an item that's in the optimal solution but not selected
         for i in range(len(self.items)):
             if self.optimal_selection[i] and not self.selection[i]: