chuk-puzzles-gym 0.9__py3-none-any.whl → 0.10.1__py3-none-any.whl

chuk_puzzles_gym/games/skyscrapers/game.py

@@ -0,0 +1,282 @@
+"""Skyscrapers puzzle game implementation."""
+
+from typing import Any
+
+from ...models import DifficultyLevel, DifficultyProfile, MoveResult
+from .._base import PuzzleGame
+from .config import SkyscrapersConfig
+
+
+class SkyscrapersGame(PuzzleGame):
+    """Skyscrapers puzzle - fill a Latin square with visibility clues.
+
+    Rules:
+    - Fill an NxN grid with numbers 1 to N
+    - Each row and column must contain each number exactly once (Latin square)
+    - Numbers represent building heights
+    - Clues around the border indicate how many buildings are visible from that direction
+    - A taller building hides all shorter buildings behind it
+    """
+
+    def __init__(self, difficulty: str = "easy", seed: int | None = None, **kwargs):
+        super().__init__(difficulty, seed, **kwargs)
+        self.config = SkyscrapersConfig.from_difficulty(self.difficulty)
+        self.size = self.config.size
+        self.grid: list[list[int]] = []
+        self.solution: list[list[int]] = []
+        self.initial_grid: list[list[int]] = []
+        self.clues: dict[str, list[int]] = {"top": [], "bottom": [], "left": [], "right": []}
+
+    @property
+    def name(self) -> str:
+        return "Skyscrapers"
+
+    @property
+    def description(self) -> str:
+        return "Fill the grid with building heights using visibility clues"
+
+    @property
+    def constraint_types(self) -> list[str]:
+        return ["all_different", "visibility", "ordering", "boundary_clues"]
+
+    @property
+    def business_analogies(self) -> list[str]:
+        return ["urban_planning", "line_of_sight_analysis", "signal_visibility"]
+
+    @property
+    def complexity_profile(self) -> dict[str, str]:
+        return {
+            "reasoning_type": "deductive",
+            "search_space": "medium",
+            "constraint_density": "dense",
+        }
+
+    @property
+    def complexity_metrics(self) -> dict[str, int | float]:
+        empty = sum(1 for row in self.grid for cell in row if cell == 0)
+        return {
+            "variable_count": self.size * self.size,
+            "constraint_count": 2 * self.size + 4 * self.size,
+            "domain_size": self.size,
+            "branching_factor": self.size / 2.0,
+            "empty_cells": empty,
+        }
+
+    @property
+    def difficulty_profile(self) -> DifficultyProfile:
+        profiles = {
+            DifficultyLevel.EASY: DifficultyProfile(
+                logic_depth=2, branching_factor=2.0, state_observability=1.0, constraint_density=0.7
+            ),
+            DifficultyLevel.MEDIUM: DifficultyProfile(
+                logic_depth=4, branching_factor=3.0, state_observability=1.0, constraint_density=0.6
+            ),
+            DifficultyLevel.HARD: DifficultyProfile(
+                logic_depth=6, branching_factor=4.0, state_observability=1.0, constraint_density=0.5
+            ),
+        }
+        return profiles[self.difficulty]
+
+    def _compute_visibility(self, line: list[int]) -> int:
+        """Count how many buildings are visible from the start of a line."""
+        count = 0
+        max_height = 0
+        for h in line:
+            if h > max_height:
+                count += 1
+                max_height = h
+        return count
+
+    def _generate_latin_square(self) -> list[list[int]]:
+        """Generate a random NxN Latin square."""
+        n = self.size
+        # Start with a shifted-row construction
+        base = list(range(1, n + 1))
+        grid = []
+        for r in range(n):
+            row = [(base[(r + c) % n]) for c in range(n)]
+            grid.append(row)
+
+        # Shuffle rows
+        rows = list(range(n))
+        self._rng.shuffle(rows)
+        grid = [grid[r] for r in rows]
+
+        # Shuffle columns
+        cols = list(range(n))
+        self._rng.shuffle(cols)
+        grid = [[row[c] for c in cols] for row in grid]
+
+        # Shuffle values (relabel)
+        perm = list(range(1, n + 1))
+        self._rng.shuffle(perm)
+        mapping = {i + 1: perm[i] for i in range(n)}
+        grid = [[mapping[cell] for cell in row] for row in grid]
+
+        return grid
+
+    def _compute_all_clues(self, grid: list[list[int]]) -> dict[str, list[int]]:
+        """Compute visibility clues from all 4 directions."""
+        n = self.size
+        clues: dict[str, list[int]] = {"top": [], "bottom": [], "left": [], "right": []}
+
+        for c in range(n):
+            col = [grid[r][c] for r in range(n)]
+            clues["top"].append(self._compute_visibility(col))
+            clues["bottom"].append(self._compute_visibility(col[::-1]))
+
+        for r in range(n):
+            clues["left"].append(self._compute_visibility(grid[r]))
+            clues["right"].append(self._compute_visibility(grid[r][::-1]))
+
+        return clues
+
+    async def generate_puzzle(self) -> None:
+        """Generate a Skyscrapers puzzle."""
+        self.solution = self._generate_latin_square()
+        self.clues = self._compute_all_clues(self.solution)
+
+        # Copy solution to grid, then remove cells based on difficulty
+        self.grid = [row[:] for row in self.solution]
+
+        # Determine cells to remove
+        n = self.size
+        total_cells = n * n
+        remove_map = {
+            DifficultyLevel.EASY: int(total_cells * 0.45),
+            DifficultyLevel.MEDIUM: int(total_cells * 0.60),
+            DifficultyLevel.HARD: int(total_cells * 0.75),
+        }
+        cells_to_remove = remove_map[self.difficulty]
+
+        # Randomly remove cells
+        all_cells = [(r, c) for r in range(n) for c in range(n)]
+        self._rng.shuffle(all_cells)
+        for r, c in all_cells[:cells_to_remove]:
+            self.grid[r][c] = 0
+
+        self.initial_grid = [row[:] for row in self.grid]
+        self.game_started = True
+
+    async def validate_move(self, row: int, col: int, num: int) -> MoveResult:
+        """Validate placing a height value.
+
+        Args:
+            row: 1-indexed row
+            col: 1-indexed column
+            num: Height value (1-N) or 0 to clear
+        """
+        n = self.size
+        r, c = row - 1, col - 1
+
+        if not (0 <= r < n and 0 <= c < n):
+            self.record_move((row, col), False)
+            return MoveResult(success=False, message=f"Position ({row}, {col}) is out of bounds.")
+
+        if self.initial_grid[r][c] != 0:
+            self.record_move((row, col), False)
+            return MoveResult(success=False, message="Cannot modify an initial cell.")
+
+        if num == 0:
+            self.grid[r][c] = 0
+            self.record_move((row, col), True)
+            return MoveResult(success=True, message=f"Cleared cell ({row}, {col}).", state_changed=True)
+
+        if not (1 <= num <= n):
+            self.record_move((row, col), False)
+            return MoveResult(success=False, message=f"Value must be between 1 and {n}.")
+
+        # Check row uniqueness
+        for cc in range(n):
+            if cc != c and self.grid[r][cc] == num:
+                self.record_move((row, col), False)
+                return MoveResult(
+                    success=False,
+                    message=f"Value {num} already exists in row {row}.",
+                )
+
+        # Check column uniqueness
+        for rr in range(n):
+            if rr != r and self.grid[rr][c] == num:
+                self.record_move((row, col), False)
+                return MoveResult(
+                    success=False,
+                    message=f"Value {num} already exists in column {col}.",
+                )
+
+        self.grid[r][c] = num
+        self.record_move((row, col), True)
+        return MoveResult(
+            success=True,
+            message=f"Placed {num} at ({row}, {col}).",
+            state_changed=True,
+        )
+
+    def is_complete(self) -> bool:
+        """Check if the puzzle is solved correctly."""
+        return self.grid == self.solution
+
+    async def get_hint(self) -> tuple[Any, str] | None:
+        """Get a hint - suggest a cell to fill."""
+        if not self.can_use_hint():
+            return None
+        n = self.size
+        for r in range(n):
+            for c in range(n):
+                if self.grid[r][c] == 0:
+                    val = self.solution[r][c]
+                    return (
+                        (r + 1, c + 1, val),
+                        f"Try placing {val} at row {r + 1}, column {c + 1}.",
+                    )
+        return None
+
+    def render_grid(self) -> str:
+        """Render the puzzle with visibility clues."""
+        n = self.size
+        lines = []
+
+        # Top clues
+        top_clues = "    " + "  ".join(str(c) if c > 0 else " " for c in self.clues["top"])
+        lines.append(top_clues)
+        lines.append("   " + "+" + "---" * n + "+")
+
+        # Grid rows with left/right clues
+        for r in range(n):
+            left = str(self.clues["left"][r]) if self.clues["left"][r] > 0 else " "
+            right = str(self.clues["right"][r]) if self.clues["right"][r] > 0 else " "
+            cells = "  ".join(str(v) if v != 0 else "." for v in self.grid[r])
+            lines.append(f" {left} | {cells} | {right}")
+
+        # Bottom border and clues
+        lines.append("   " + "+" + "---" * n + "+")
+        bot_clues = "    " + "  ".join(str(c) if c > 0 else " " for c in self.clues["bottom"])
+        lines.append(bot_clues)
+
+        return "\n".join(lines)
+
+    def get_stats(self) -> str:
+        """Get current game statistics."""
+        empty = sum(1 for r in range(self.size) for c in range(self.size) if self.grid[r][c] == 0)
+        return f"Moves: {self.moves_made} | Empty cells: {empty} | Grid: {self.size}x{self.size} | Seed: {self.seed}"
+
+    def get_rules(self) -> str:
+        return (
+            f"SKYSCRAPERS ({self.size}x{self.size})\n"
+            f"Fill the grid with numbers 1 to {self.size}.\n"
+            "Each row and column must contain each number exactly once.\n"
+            "Numbers represent building heights.\n"
+            "Clues around the border show how many buildings are visible from that direction.\n"
+            "A taller building hides all shorter ones behind it."
+        )
+
+    def get_commands(self) -> str:
+        return (
+            "Commands:\n"
+            f"  place <row> <col> <height>  - Place a height (1-{self.size})\n"
+            "  clear <row> <col>           - Clear a cell\n"
+            "  hint                        - Get a hint\n"
+            "  check                       - Check if solved\n"
+            "  show                        - Show current state\n"
+            "  menu                        - Return to menu"
+        )

chuk_puzzles_gym/games/slitherlink/game.py

@@ -272,6 +272,8 @@ class SlitherlinkGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None
         """
+        if not self.can_use_hint():
+            return None
         # Find an edge that's in the solution but not set by player
         for row in range(self.size + 1):
             for col in range(self.size):

chuk_puzzles_gym/games/sokoban/game.py

@@ -499,6 +499,8 @@ class SokobanGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None
         """
+        if not self.can_use_hint():
+            return None
         if self.is_complete():
             return None
 

chuk_puzzles_gym/games/star_battle/game.py

@@ -301,6 +301,8 @@ class StarBattleGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         # Find a star location from solution that hasn't been placed
         for r in range(self.size):
             for c in range(self.size):

chuk_puzzles_gym/games/sudoku/game.py

@@ -249,6 +249,8 @@ class SudokuGame(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/tents/game.py

@@ -326,6 +326,8 @@ class TentsGame(PuzzleGame):
         Returns:
             Tuple of (hint_data, hint_message) or None if puzzle is complete
         """
+        if not self.can_use_hint():
+            return None
         # Find a tent location from solution that hasn't been placed
         for r in range(self.size):
             for c in range(self.size):

chuk_puzzles_gym/server.py

@@ -202,7 +202,7 @@ class ArcadeHandler(TelnetHandler):
         # Set up command handler if available for this game
         handler_class = GAME_COMMAND_HANDLERS.get(game_id.lower())
         if handler_class:
-            self.game_handler = handler_class(self.current_game)
+            self.game_handler = handler_class(self.current_game)  # type: ignore[abstract]
         else:
             self.game_handler = None
 
@@ -599,10 +599,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 +622,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 +633,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 +646,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 +654,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 +683,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 +694,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 +705,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 +721,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 +741,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 +764,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 +777,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 +785,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 +801,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 +812,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 +825,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 +846,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 +859,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 +869,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 +881,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 +891,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 +906,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 +917,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 +931,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 +942,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 +959,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 +972,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 +984,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 +1008,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 +1020,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 +1032,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 +1042,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