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

chuk_puzzles_gym/games/knapsack/game.py

@@ -0,0 +1,340 @@
+"""Knapsack optimization puzzle game implementation."""
+
+from typing import Any
+
+from ...models import DifficultyLevel, DifficultyProfile, MoveResult
+from .._base import PuzzleGame
+from .config import KnapsackConfig
+from .enums import KnapsackAction
+from .models import Item
+
+
+class KnapsackGame(PuzzleGame):
+    """Knapsack optimization puzzle game.
+
+    Classic optimization problem: select items to maximize value
+    while staying within weight capacity.
+    Demonstrates objective optimization (not just constraint satisfaction).
+    """
+
+    def __init__(self, difficulty: str = "easy", seed: int | None = None, **kwargs):
+        """Initialize a new Knapsack game.
+
+        Args:
+            difficulty: Game difficulty level (easy/medium/hard)
+        """
+        super().__init__(difficulty, seed, **kwargs)
+
+        # Use pydantic config based on difficulty
+        self.config = KnapsackConfig.from_difficulty(self.difficulty)
+        self.max_weight = self.config.max_weight
+
+        # Item properties - now using Item pydantic model
+        self.items: list[Item] = []
+        self.capacity: int = 0
+
+        # Player's selection (True = selected, False = not selected)
+        self.selection: list[bool] = []
+
+        # Solution tracking
+        self.optimal_value = 0
+        self.optimal_selection: list[bool] = []
+
+    @property
+    def name(self) -> str:
+        """The display name of this puzzle type."""
+        return "Knapsack"
+
+    @property
+    def description(self) -> str:
+        """A one-line description of this puzzle type."""
+        return "Optimize item selection to maximize value within weight limit"
+
+    @property
+    def constraint_types(self) -> list[str]:
+        """Constraint types demonstrated by this puzzle."""
+        return ["optimization", "capacity_constraint", "binary_choice", "objective_maximization"]
+
+    @property
+    def business_analogies(self) -> list[str]:
+        """Business problems this puzzle models."""
+        return ["portfolio_selection", "feature_prioritization", "budget_allocation", "resource_optimization"]
+
+    @property
+    def complexity_profile(self) -> dict[str, str]:
+        """Complexity profile of this puzzle."""
+        return {"reasoning_type": "optimization", "search_space": "exponential", "constraint_density": "sparse"}
+
+    @property
+    def optimal_steps(self) -> int | None:
+        """Minimum steps = items to select."""
+        if not hasattr(self, "optimal_selection") or not self.optimal_selection:
+            return None
+        return sum(self.optimal_selection)
+
+    @property
+    def difficulty_profile(self) -> "DifficultyProfile":
+        """Difficulty characteristics for Knapsack."""
+
+        logic_depth = {
+            DifficultyLevel.EASY.value: 2,
+            DifficultyLevel.MEDIUM.value: 3,
+            DifficultyLevel.HARD.value: 4,
+        }.get(self.difficulty.value, 3)
+        return DifficultyProfile(
+            logic_depth=logic_depth,
+            branching_factor=2.0,  # Select or not
+            state_observability=1.0,
+            constraint_density=0.3,
+        )
+
+    async def generate_puzzle(self) -> None:
+        """Generate a new Knapsack puzzle."""
+        # Generate random items with weights and values
+        item_names = [
+            "Gold Bar",
+            "Diamond",
+            "Ruby",
+            "Emerald",
+            "Sapphire",
+            "Platinum",
+            "Silver",
+            "Jade",
+            "Opal",
+            "Pearl",
+            "Topaz",
+            "Amethyst",
+            "Garnet",
+            "Quartz",
+            "Obsidian",
+        ]
+
+        self.items = []
+        total_weight = 0
+
+        num_items = self.config.num_items
+
+        for i in range(num_items):
+            name = item_names[i] if i < len(item_names) else f"Item {i + 1}"
+            weight = self._rng.randint(1, 10)
+            # Value roughly correlates with weight but with variance
+            value = self._rng.randint(weight * 5, weight * 15)
+
+            self.items.append(Item(name=name, weight=weight, value=value))
+            total_weight += weight
+
+        # Set capacity as a fraction of total weight
+        capacity_factor_map = {
+            DifficultyLevel.EASY: 0.6,
+            DifficultyLevel.MEDIUM: 0.5,
+            DifficultyLevel.HARD: 0.4,
+        }
+        capacity_factor = capacity_factor_map[self.difficulty]
+        self.capacity = int(total_weight * capacity_factor)
+        if self.capacity < 5:
+            self.capacity = 5  # Minimum capacity
+
+        # Initialize empty selection
+        self.selection = [False] * num_items
+
+        # Calculate optimal solution using dynamic programming
+        self._solve_optimal()
+
+        self.moves_made = 0
+        self.game_started = True
+
+    def _solve_optimal(self) -> None:
+        """Solve the knapsack problem optimally using dynamic programming."""
+        n = len(self.items)
+        capacity = self.capacity
+
+        # DP table: dp[i][w] = max value using first i items with capacity w
+        dp = [[0 for _ in range(capacity + 1)] for _ in range(n + 1)]
+
+        # Fill the DP table
+        for i in range(1, n + 1):
+            item = self.items[i - 1]
+            weight = item.weight
+            value = item.value
+
+            for w in range(capacity + 1):
+                # Don't take item i
+                dp[i][w] = dp[i - 1][w]
+
+                # Take item i if it fits
+                if weight <= w:
+                    dp[i][w] = max(dp[i][w], dp[i - 1][w - weight] + value)
+
+        # Backtrack to find which items to select
+        self.optimal_value = dp[n][capacity]
+        self.optimal_selection = [False] * n
+
+        w = capacity
+        for i in range(n, 0, -1):
+            if dp[i][w] != dp[i - 1][w]:
+                self.optimal_selection[i - 1] = True
+                w -= self.items[i - 1].weight
+
+    async def validate_move(self, action: str, item_index: int) -> MoveResult:
+        """Toggle item selection.
+
+        Args:
+            action: 'select' or 'deselect'
+            item_index: Item number (1-indexed, user-facing)
+
+        Returns:
+            MoveResult with success status and message
+        """
+        # Convert to 0-indexed
+        item_index -= 1
+
+        # Validate item index
+        if not (0 <= item_index < len(self.items)):
+            return MoveResult(success=False, message=f"Invalid item number. Use 1-{len(self.items)}.")
+
+        # Parse action using KnapsackAction enum
+        try:
+            action_enum = KnapsackAction(action.lower())
+        except ValueError:
+            return MoveResult(success=False, message="Invalid action. Use 'select' or 'deselect'.")
+
+        if action_enum == KnapsackAction.SELECT:
+            if self.selection[item_index]:
+                return MoveResult(success=False, message="Item is already selected.")
+
+            # Check if adding this item exceeds capacity
+            current_weight = self._get_current_weight()
+            item_weight = self.items[item_index].weight
+
+            if current_weight + item_weight > self.capacity:
+                return MoveResult(
+                    success=False,
+                    message=f"Cannot select - would exceed capacity! (Current: {current_weight}, Item: {item_weight}, Capacity: {self.capacity})",
+                )
+
+            self.selection[item_index] = True
+            self.moves_made += 1
+            item_name = self.items[item_index].name
+            return MoveResult(
+                success=True,
+                message=f"Selected {item_name} (weight: {item_weight}, value: ${self.items[item_index].value})",
+                state_changed=True,
+            )
+
+        elif action_enum == KnapsackAction.DESELECT:
+            if not self.selection[item_index]:
+                return MoveResult(success=False, message="Item is not currently selected.")
+
+            self.selection[item_index] = False
+            self.moves_made += 1
+            item_name = self.items[item_index].name
+            return MoveResult(success=True, message=f"Deselected {item_name}", state_changed=True)
+
+        # Should never reach here due to enum validation above
+        return MoveResult(success=False, message="Invalid action. Use 'select' or 'deselect'.")
+
+    def _get_current_weight(self) -> int:
+        """Calculate total weight of currently selected items."""
+        return sum(self.items[i].weight for i in range(len(self.items)) if self.selection[i])
+
+    def _get_current_value(self) -> int:
+        """Calculate total value of currently selected items."""
+        return sum(self.items[i].value for i in range(len(self.items)) if self.selection[i])
+
+    def is_complete(self) -> bool:
+        """Check if the solution is optimal.
+
+        For optimization problems, we consider it complete if the player
+        has achieved the optimal value.
+        """
+        return self._get_current_value() == self.optimal_value
+
+    async def get_hint(self) -> tuple[Any, str] | None:
+        """Get a hint for the next move.
+
+        Returns:
+            Tuple of (hint_data, hint_message) or 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]:
+                hint_data = ("select", i + 1)
+                hint_message = f"Try selecting item {i + 1} ({self.items[i].name})"
+                return hint_data, hint_message
+
+        # Suggest deselecting an item that's not in the optimal solution but is selected
+        for i in range(len(self.items)):
+            if not self.optimal_selection[i] and self.selection[i]:
+                hint_data = ("deselect", i + 1)
+                hint_message = f"Try deselecting item {i + 1} ({self.items[i].name})"
+                return hint_data, hint_message
+
+        return None
+
+    def render_grid(self) -> str:
+        """Render the current game state as ASCII art.
+
+        Returns:
+            String representation of the puzzle
+        """
+        lines = []
+
+        lines.append(f"Knapsack Capacity: {self.capacity} kg")
+        lines.append(f"Current Weight: {self._get_current_weight()} kg")
+        lines.append(f"Current Value: ${self._get_current_value()}")
+        lines.append(f"Optimal Value: ${self.optimal_value}")
+        lines.append("")
+
+        # Items table
+        lines.append("  # | Item          | Weight | Value  | Selected")
+        lines.append("  --+---------------+--------+--------+---------")
+
+        for i, item in enumerate(self.items):
+            selected = "✓" if self.selection[i] else " "
+            lines.append(f"  {i + 1:2d} | {item.name:<13s} | {item.weight:4d}kg | ${item.value:5d} |    {selected}")
+
+        lines.append("")
+        lines.append(f"Space Remaining: {self.capacity - self._get_current_weight()} kg")
+
+        return "\n".join(lines)
+
+    def get_rules(self) -> str:
+        """Get the rules description for Knapsack.
+
+        Returns:
+            Multi-line string describing the puzzle rules
+        """
+        return f"""KNAPSACK RULES:
+- Select items to maximize total value
+- Cannot exceed capacity of {self.capacity}kg
+- Each item can be selected at most once
+- Goal: Achieve optimal value of ${self.optimal_value}
+- This is an OPTIMIZATION problem - find the best solution!"""
+
+    def get_commands(self) -> str:
+        """Get the available commands for Knapsack.
+
+        Returns:
+            Multi-line string describing available commands
+        """
+        return """KNAPSACK COMMANDS:
+  select <number>    - Select an item (e.g., 'select 3')
+  deselect <number>  - Deselect an item (e.g., 'deselect 2')
+  show               - Display current selection
+  hint               - Get a hint for optimization
+  check              - Check if you've found the optimal solution
+  solve              - Show the optimal solution (ends game)
+  menu               - Return to game selection
+  quit               - Exit the server"""
+
+    def get_stats(self) -> str:
+        """Get current game statistics.
+
+        Returns:
+            String with game stats
+        """
+        current_value = self._get_current_value()
+        current_weight = self._get_current_weight()
+        optimality = (current_value / self.optimal_value * 100) if self.optimal_value > 0 else 0
+
+        return f"Moves: {self.moves_made} | Value: ${current_value}/${self.optimal_value} ({optimality:.0f}%) | Weight: {current_weight}/{self.capacity}kg | Seed: {self.seed}"

chuk_puzzles_gym/games/knapsack/models.py

@@ -0,0 +1,13 @@
+"""Knapsack game models."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Item(BaseModel):
+    """An item in the Knapsack game."""
+
+    model_config = ConfigDict(frozen=True)  # Items don't change once created
+
+    name: str = Field(min_length=1, description="Item name")
+    weight: int = Field(gt=0, description="Item weight")
+    value: int = Field(gt=0, description="Item value")

chuk_puzzles_gym/games/lights_out/__init__.py

@@ -0,0 +1,6 @@
+"""LightsOut puzzle game module."""
+
+from .config import LightsOutConfig
+from .game import LightsOutGame
+
+__all__ = ["LightsOutGame", "LightsOutConfig"]

chuk_puzzles_gym/games/lights_out/config.py

@@ -0,0 +1,24 @@
+"""Configuration for Lights Out game."""
+
+from pydantic import BaseModel, Field
+
+from ...models.enums import DifficultyLevel
+
+
+class LightsOutConfig(BaseModel):
+    """Configuration for Lights Out game."""
+
+    difficulty: DifficultyLevel = Field(default=DifficultyLevel.EASY, description="Game difficulty level")
+    size: int = Field(ge=3, le=10, description="Grid size (NxN)")
+    num_presses: int = Field(ge=1, description="Number of initial presses to create puzzle")
+
+    @classmethod
+    def from_difficulty(cls, difficulty: DifficultyLevel) -> "LightsOutConfig":
+        """Create config from difficulty level."""
+        config_map = {
+            DifficultyLevel.EASY: {"size": 5, "num_presses": 3},
+            DifficultyLevel.MEDIUM: {"size": 6, "num_presses": 5},
+            DifficultyLevel.HARD: {"size": 7, "num_presses": 7},
+        }
+        params = config_map[difficulty]
+        return cls(difficulty=difficulty, **params)

chuk_puzzles_gym/games/lights_out/game.py

@@ -0,0 +1,249 @@
+"""Lights Out puzzle game implementation."""
+
+from typing import Any
+
+from ...models import DifficultyProfile, MoveResult
+from .._base import PuzzleGame
+from .config import LightsOutConfig
+
+
+class LightsOutGame(PuzzleGame):
+    """Lights Out puzzle game.
+
+    Click lights to toggle them and their neighbors.
+    Goal: Turn all lights off.
+    Perfect demonstration of boolean XOR constraints.
+    """
+
+    def __init__(self, difficulty: str = "easy", seed: int | None = None, **kwargs):
+        """Initialize a new Lights Out game.
+
+        Args:
+            difficulty: Game difficulty level (easy=5x5, medium=6x6, hard=7x7)
+        """
+        super().__init__(difficulty, seed, **kwargs)
+
+        # Use pydantic config based on difficulty
+        self.config = LightsOutConfig.from_difficulty(self.difficulty)
+        self.size = self.config.size
+
+        # Grid: 0 = off, 1 = on
+        self.grid = [[0 for _ in range(self.size)] for _ in range(self.size)]
+        self.solution = [[0 for _ in range(self.size)] for _ in range(self.size)]
+        self.initial_grid = [[0 for _ in range(self.size)] for _ in range(self.size)]
+
+        # Track which cells need to be pressed (solution)
+        self.presses = [[0 for _ in range(self.size)] for _ in range(self.size)]
+
+    @property
+    def name(self) -> str:
+        """The display name of this puzzle type."""
+        return "Lights Out"
+
+    @property
+    def description(self) -> str:
+        """A one-line description of this puzzle type."""
+        return "Toggle lights to turn all off - XOR constraint puzzle"
+
+    @property
+    def constraint_types(self) -> list[str]:
+        """Constraint types demonstrated by this puzzle."""
+        return ["boolean_sat", "xor_constraints", "parity", "linear_algebra"]
+
+    @property
+    def business_analogies(self) -> list[str]:
+        """Business problems this puzzle models."""
+        return ["toggle_systems", "parity_checking", "state_synchronization"]
+
+    @property
+    def complexity_profile(self) -> dict[str, str]:
+        """Complexity profile of this puzzle."""
+        return {"reasoning_type": "deductive", "search_space": "exponential", "constraint_density": "dense"}
+
+    @property
+    def optimal_steps(self) -> int | None:
+        """Minimum steps = presses needed."""
+        if not hasattr(self, "presses") or not self.presses:
+            return None
+        return sum(1 for r in range(self.size) for c in range(self.size) if self.presses[r][c] == 1)
+
+    @property
+    def difficulty_profile(self) -> "DifficultyProfile":
+        """Difficulty characteristics for Lights Out."""
+        from ...models import DifficultyLevel
+
+        logic_depth = {
+            DifficultyLevel.EASY.value: 2,
+            DifficultyLevel.MEDIUM.value: 3,
+            DifficultyLevel.HARD.value: 4,
+        }.get(self.difficulty.value, 3)
+        return DifficultyProfile(
+            logic_depth=logic_depth,
+            branching_factor=2.0,  # Press or not
+            state_observability=1.0,
+            constraint_density=0.7,
+        )
+
+    def _toggle_cell(self, row: int, col: int, grid: list[list[int]]) -> None:
+        """Toggle a cell and its neighbors.
+
+        Args:
+            row: Row index
+            col: Column index
+            grid: Grid to modify
+        """
+        # Toggle the cell itself
+        grid[row][col] = 1 - grid[row][col]
+
+        # Toggle neighbors (up, down, left, right)
+        directions = [(-1, 0), (1, 0), (0, -1), (0, 1)]
+        for dr, dc in directions:
+            new_row, new_col = row + dr, col + dc
+            if 0 <= new_row < self.size and 0 <= new_col < self.size:
+                grid[new_row][new_col] = 1 - grid[new_row][new_col]
+
+    async def generate_puzzle(self) -> None:
+        """Generate a new Lights Out puzzle."""
+        # Start with all lights off
+        self.grid = [[0 for _ in range(self.size)] for _ in range(self.size)]
+        self.solution = [[0 for _ in range(self.size)] for _ in range(self.size)]
+
+        # Generate a random solution pattern (which cells to press)
+        num_presses = self.config.num_presses
+
+        # Randomly select cells to press
+        pressed_cells: set[tuple[int, int]] = set()
+        attempts = 0
+        while len(pressed_cells) < num_presses and attempts < 100:
+            row = self._rng.randint(0, self.size - 1)
+            col = self._rng.randint(0, self.size - 1)
+            pressed_cells.add((row, col))
+            attempts += 1
+
+        # Apply these presses to create the puzzle
+        for row, col in pressed_cells:
+            self.presses[row][col] = 1
+            self._toggle_cell(row, col, self.grid)
+
+        # Store initial state
+        self.initial_grid = [row[:] for row in self.grid]
+        self.moves_made = 0
+        self.game_started = True
+
+    async def validate_move(self, row: int, col: int) -> MoveResult:
+        """Toggle a cell (press it).
+
+        Args:
+            row: Row index (1-indexed, user-facing)
+            col: Column index (1-indexed, user-facing)
+
+        Returns:
+            MoveResult with success status and message
+        """
+        # Convert to 0-indexed
+        row -= 1
+        col -= 1
+
+        # Validate coordinates
+        if not (0 <= row < self.size and 0 <= col < self.size):
+            return MoveResult(success=False, message=f"Invalid coordinates. Use row and column between 1-{self.size}.")
+
+        # Toggle the cell and neighbors
+        self._toggle_cell(row, col, self.grid)
+
+        # Update solution tracking - XOR the press state
+        # (pressing a cell twice cancels out)
+        self.presses[row][col] = 1 - self.presses[row][col]
+
+        self.moves_made += 1
+
+        return MoveResult(success=True, message=f"Toggled light at ({row + 1}, {col + 1})", state_changed=True)
+
+    def is_complete(self) -> bool:
+        """Check if the puzzle is complete (all lights off)."""
+        for row in range(self.size):
+            for col in range(self.size):
+                if self.grid[row][col] == 1:
+                    return False
+        return True
+
+    async def get_hint(self) -> tuple[Any, str] | None:
+        """Get a hint for the next move.
+
+        Returns:
+            Tuple of (hint_data, hint_message) or None if puzzle is complete
+        """
+        # Find a cell in the solution that should be pressed
+        for row in range(self.size):
+            for col in range(self.size):
+                if self.presses[row][col] == 1:
+                    hint_data = (row + 1, col + 1)
+                    hint_message = f"Try pressing the light at row {row + 1}, column {col + 1}"
+                    return hint_data, hint_message
+
+        return None
+
+    def render_grid(self) -> str:
+        """Render the current puzzle state as ASCII art.
+
+        Returns:
+            String representation of the puzzle grid
+        """
+        lines = []
+
+        # Header
+        header = "  |"
+        for i in range(self.size):
+            header += f"{i + 1}|"
+        lines.append(header)
+        lines.append("  +" + "-+" * self.size)
+
+        # Grid rows
+        for row in range(self.size):
+            line = f"{row + 1} |"
+            for col in range(self.size):
+                cell = self.grid[row][col]
+                # ● = on, ○ = off
+                symbol = "●" if cell == 1 else "○"
+                line += f"{symbol}|"
+            lines.append(line)
+            lines.append("  +" + "-+" * self.size)
+
+        return "\n".join(lines)
+
+    def get_rules(self) -> str:
+        """Get the rules description for Lights Out.
+
+        Returns:
+            Multi-line string describing the puzzle rules
+        """
+        return f"""LIGHTS OUT RULES:
+- Click a light to toggle it and its neighbors
+- Neighbors = up, down, left, right (not diagonal)
+- Goal: Turn ALL lights off (○)
+- ● = light ON, ○ = light OFF
+- Grid size: {self.size}×{self.size}"""
+
+    def get_commands(self) -> str:
+        """Get the available commands for Lights Out.
+
+        Returns:
+            Multi-line string describing available commands
+        """
+        return """LIGHTS OUT COMMANDS:
+  press <row> <col>  - Press a light (e.g., 'press 2 3')
+  show               - Display the current grid
+  hint               - Get a hint for the next move
+  check              - Check if all lights are off
+  reset              - Reset to initial state
+  menu               - Return to game selection
+  quit               - Exit the server"""
+
+    def get_stats(self) -> str:
+        """Get current game statistics.
+
+        Returns:
+            String with game stats
+        """
+        lights_on = sum(1 for r in range(self.size) for c in range(self.size) if self.grid[r][c] == 1)
+        return f"Moves made: {self.moves_made} | Lights ON: {lights_on} | Grid size: {self.size}×{self.size} | Seed: {self.seed}"

chuk_puzzles_gym/games/logic_grid/__init__.py

@@ -0,0 +1,6 @@
+"""LogicGrid puzzle game module."""
+
+from .config import LogicGridConfig
+from .game import LogicGridGame
+
+__all__ = ["LogicGridGame", "LogicGridConfig"]

chuk_puzzles_gym/games/logic_grid/config.py

@@ -0,0 +1,24 @@
+"""Configuration for Logic Grid game."""
+
+from pydantic import BaseModel, Field
+
+from ...models.enums import DifficultyLevel
+
+
+class LogicGridConfig(BaseModel):
+    """Configuration for Logic Grid game."""
+
+    difficulty: DifficultyLevel = Field(default=DifficultyLevel.EASY, description="Game difficulty level")
+    num_people: int = Field(ge=3, le=5, description="Number of people")
+    num_attributes: int = Field(ge=3, le=5, description="Number of attributes per category")
+
+    @classmethod
+    def from_difficulty(cls, difficulty: DifficultyLevel) -> "LogicGridConfig":
+        """Create config from difficulty level."""
+        config_map = {
+            DifficultyLevel.EASY: {"num_people": 3, "num_attributes": 3},
+            DifficultyLevel.MEDIUM: {"num_people": 4, "num_attributes": 4},
+            DifficultyLevel.HARD: {"num_people": 5, "num_attributes": 5},
+        }
+        params = config_map[difficulty]
+        return cls(difficulty=difficulty, **params)

chuk_puzzles_gym/games/logic_grid/constants.py

@@ -0,0 +1,12 @@
+"""Logic Grid puzzle constants and static data."""
+
+from typing import Final
+
+# Logic Grid categories
+PEOPLE: Final[list[str]] = ["Alice", "Bob", "Carol", "Dave", "Eve"]
+COLORS: Final[list[str]] = ["Red", "Blue", "Green", "Yellow", "Purple"]
+PETS: Final[list[str]] = ["Cat", "Dog", "Bird", "Fish", "Rabbit"]
+DRINKS: Final[list[str]] = ["Coffee", "Tea", "Juice", "Water", "Milk"]
+
+# Category names (for iteration)
+CATEGORIES: Final[list[str]] = ["person", "color", "pet", "drink"]