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

chuk_puzzles_gym/games/logic_grid/game.py

@@ -0,0 +1,333 @@
+"""Logic Grid puzzle game implementation."""
+
+from typing import Any
+
+from ...models import DifficultyProfile, MoveResult
+from .._base import PuzzleGame
+from .config import LogicGridConfig
+from .constants import CATEGORIES, COLORS, DRINKS, PEOPLE, PETS
+from .models import LogicGridCategories, PersonAttributes
+
+
+class LogicGridGame(PuzzleGame):
+    """Logic Grid puzzle game (like Einstein's Riddle or Zebra Puzzle).
+
+    Use logical deduction to determine which attributes belong together.
+    Each person/house has exactly one of each attribute type.
+    """
+
+    def __init__(self, difficulty: str = "easy", seed: int | None = None, **kwargs):
+        """Initialize a new Logic Grid game.
+
+        Args:
+            difficulty: Game difficulty level (easy=3x3, medium=4x4, hard=5x5)
+        """
+        super().__init__(difficulty, seed, **kwargs)
+
+        # Use pydantic config based on difficulty
+        self.config = LogicGridConfig.from_difficulty(self.difficulty)
+        self.num_people = self.config.num_people
+
+        # Categories using Pydantic model with constants
+        self.categories = LogicGridCategories(
+            person=PEOPLE[: self.num_people],
+            color=COLORS[: self.num_people],
+            pet=PETS[: self.num_people],
+            drink=DRINKS[: self.num_people],
+        )
+
+        # Solution: dict mapping person -> PersonAttributes
+        self.solution: dict[str, PersonAttributes] = {}
+
+        # Player grid: dict of (category1, value1, category2, value2) -> bool | None
+        # True = definitely connected, False = definitely not connected, None = unknown
+        self.player_grid: dict[tuple[str, str, str, str], bool | None] = {}
+
+        # Clues: list of clue strings
+        self.clues: list[str] = []
+
+    @property
+    def name(self) -> str:
+        """The display name of this puzzle type."""
+        return "Logic Grid"
+
+    @property
+    def description(self) -> str:
+        """A one-line description of this puzzle type."""
+        return "Deductive reasoning puzzle - match attributes using logic"
+
+    @property
+    def constraint_types(self) -> list[str]:
+        """Constraint types demonstrated by this puzzle."""
+        return [
+            "all_different_per_attribute",
+            "cross_attribute_links",
+            "transitive_closure",
+            "bi-directional_inference",
+        ]
+
+    @property
+    def business_analogies(self) -> list[str]:
+        """Business problems this puzzle models."""
+        return ["multi_factor_matching", "relationship_mapping", "entity_resolution", "attribute_correlation"]
+
+    @property
+    def complexity_profile(self) -> dict[str, str]:
+        """Complexity profile of this puzzle."""
+        return {"reasoning_type": "deductive", "search_space": "medium", "constraint_density": "moderate"}
+
+    @property
+    def optimal_steps(self) -> int | None:
+        """Minimum steps = attribute assignments (people x attributes)."""
+        return self.num_people * 3  # 3 attributes per person
+
+    @property
+    def difficulty_profile(self) -> "DifficultyProfile":
+        """Difficulty characteristics for Logic Grid."""
+        from ...models import DifficultyLevel
+
+        logic_depth = {
+            DifficultyLevel.EASY.value: 3,
+            DifficultyLevel.MEDIUM.value: 5,
+            DifficultyLevel.HARD.value: 7,
+        }.get(self.difficulty.value, 4)
+        return DifficultyProfile(
+            logic_depth=logic_depth,
+            branching_factor=float(self.num_people),
+            state_observability=1.0,
+            constraint_density=0.6,
+        )
+
+    def _generate_solution(self) -> None:
+        """Generate a random valid solution."""
+        people = self.categories.person
+
+        # Randomly assign each attribute to each person
+        colors = self.categories.color[:]
+        pets = self.categories.pet[:]
+        drinks = self.categories.drink[:]
+
+        self._rng.shuffle(colors)
+        self._rng.shuffle(pets)
+        self._rng.shuffle(drinks)
+
+        self.solution = {}
+        for i, person in enumerate(people):
+            self.solution[person] = PersonAttributes(
+                color=colors[i],
+                pet=pets[i],
+                drink=drinks[i],
+            )
+
+    def _generate_clues(self) -> None:
+        """Generate clues from the solution."""
+        self.clues = []
+        people = self.categories.person
+
+        # Generate direct association clues
+        num_direct = self.num_people - 1
+        for i in range(num_direct):
+            person = people[i]
+            attrs = self.solution[person]
+
+            # Choose two attributes to reveal
+            cat1, cat2 = self._rng.sample(["color", "pet", "drink"], 2)
+            val1 = getattr(attrs, cat1)
+            val2 = getattr(attrs, cat2)
+            clue = f"{person} has the {val1} {cat1} and drinks {val2}"
+            self.clues.append(clue)
+
+        # Generate relative/constraint clues
+        for _ in range(self.num_people):
+            p1, p2 = self._rng.sample(people, 2)
+            cat = self._rng.choice(["color", "pet", "drink"])
+
+            val = getattr(self.solution[p2], cat)
+            clue = f"{p1} does not have the {val} {cat}"
+            self.clues.append(clue)
+
+    async def generate_puzzle(self) -> None:
+        """Generate a new Logic Grid puzzle."""
+        self._generate_solution()
+        self._generate_clues()
+
+        # Initialize player grid (all unknown)
+        self.player_grid = {}
+
+        self.moves_made = 0
+        self.game_started = True
+
+    async def validate_move(self, cat1: str, val1: str, cat2: str, val2: str, state: bool) -> MoveResult:
+        """Mark a connection in the logic grid.
+
+        Args:
+            cat1: First category
+            val1: First value
+            cat2: Second category
+            val2: Second value
+            state: True = connected, False = not connected
+
+        Returns:
+            MoveResult with success status and message
+        """
+        # Normalize categories
+        cat1 = cat1.lower()
+        cat2 = cat2.lower()
+
+        # Validate categories
+        valid_categories = ["person", "color", "pet", "drink"]
+        if cat1 not in valid_categories or cat2 not in valid_categories:
+            return MoveResult(success=False, message=f"Invalid category. Use: {', '.join(valid_categories)}")
+
+        if cat1 == cat2:
+            return MoveResult(success=False, message="Cannot connect values from the same category")
+
+        # Validate values
+        cat1_values = getattr(self.categories, cat1)
+        cat2_values = getattr(self.categories, cat2)
+
+        if val1 not in cat1_values:
+            return MoveResult(success=False, message=f"Invalid {cat1}. Choose from: {', '.join(cat1_values)}")
+
+        if val2 not in cat2_values:
+            return MoveResult(success=False, message=f"Invalid {cat2}. Choose from: {', '.join(cat2_values)}")
+
+        # Store the connection (normalize order)
+        key = (cat1, val1, cat2, val2) if cat1 < cat2 else (cat2, val2, cat1, val1)
+        self.player_grid[key] = state
+        self.moves_made += 1
+
+        return MoveResult(
+            success=True,
+            message=f"Marked {val1} ({cat1}) and {val2} ({cat2}) as {'connected' if state else 'not connected'}",
+            state_changed=True,
+        )
+
+    def is_complete(self) -> bool:
+        """Check if the puzzle is complete and correct."""
+        # Check if player has correctly identified all connections
+        for person in self.categories.person:
+            attrs = self.solution[person]
+
+            # Check person -> color
+            key1 = ("color", attrs.color, "person", person)
+            key2 = ("person", person, "color", attrs.color)
+            if not self.player_grid.get(key1) and not self.player_grid.get(key2):
+                return False
+
+            # Check person -> pet
+            key1 = ("person", person, "pet", attrs.pet)
+            key2 = ("pet", attrs.pet, "person", person)
+            if not self.player_grid.get(key1) and not self.player_grid.get(key2):
+                return False
+
+            # Check person -> drink
+            key1 = ("drink", attrs.drink, "person", person)
+            key2 = ("person", person, "drink", attrs.drink)
+            if not self.player_grid.get(key1) and not self.player_grid.get(key2):
+                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 connection that hasn't been marked
+        for person in self.categories.person:
+            attrs = self.solution[person]
+
+            # Check all categories except person
+            for cat in [c for c in CATEGORIES if c != "person"]:
+                val = getattr(attrs, cat)
+                key1 = (cat, val, "person", person)
+                key2 = ("person", person, cat, val)
+
+                if not self.player_grid.get(key1) and not self.player_grid.get(key2):
+                    hint_data = (person, cat, val)
+                    hint_message = f"{person} has the {val} {cat}"
+                    return hint_data, hint_message
+
+        return None
+
+    def render_grid(self) -> str:
+        """Render the current puzzle state.
+
+        Returns:
+            String representation of the clues and current deductions
+        """
+        lines = []
+
+        lines.append("\n=== LOGIC GRID PUZZLE ===\n")
+
+        # Show clues
+        lines.append("CLUES:")
+        for i, clue in enumerate(self.clues, 1):
+            lines.append(f"  {i}. {clue}")
+
+        lines.append("\nYOUR DEDUCTIONS:")
+        if not self.player_grid:
+            lines.append("  (none yet)")
+        else:
+            for (cat1, val1, cat2, val2), state in sorted(self.player_grid.items()):
+                if state is True:
+                    lines.append(f"  ✓ {val1} ({cat1}) ←→ {val2} ({cat2})")
+                elif state is False:
+                    lines.append(f"  ✗ {val1} ({cat1}) ←/→ {val2} ({cat2})")
+
+        lines.append("\nCATEGORIES:")
+        for cat in CATEGORIES:
+            values = getattr(self.categories, cat)
+            lines.append(f"  {cat.capitalize()}: {', '.join(values)}")
+
+        return "\n".join(lines)
+
+    def get_rules(self) -> str:
+        """Get the rules description for Logic Grid.
+
+        Returns:
+            Multi-line string describing the puzzle rules
+        """
+        return """LOGIC GRID RULES:
+- Use logical deduction to match attributes
+- Each person has exactly one color, one pet, and one drink
+- No two people share the same attribute value
+- Read the clues carefully and mark connections
+- Mark connections as True (✓) or False (✗)
+- Use elimination and deduction to solve"""
+
+    def get_commands(self) -> str:
+        """Get the available commands for Logic Grid.
+
+        Returns:
+            Multi-line string describing available commands
+        """
+        return """LOGIC GRID COMMANDS:
+  connect <cat1> <val1> <cat2> <val2>
+    - Mark that val1 and val2 are connected (belong to same person)
+    - Example: 'connect person Alice color Red'
+
+  exclude <cat1> <val1> <cat2> <val2>
+    - Mark that val1 and val2 are NOT connected
+    - Example: 'exclude person Bob pet Cat'
+
+  show     - Display clues and deductions
+  hint     - Get a hint
+  check    - Check if puzzle is solved
+  solve    - Show the 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
+        """
+        connections = sum(1 for v in self.player_grid.values() if v is True)
+        exclusions = sum(1 for v in self.player_grid.values() if v is False)
+        return (
+            f"Moves made: {self.moves_made} | Connections: {connections} | Exclusions: {exclusions} | Seed: {self.seed}"
+        )

chuk_puzzles_gym/games/logic_grid/models.py

@@ -0,0 +1,24 @@
+"""Logic Grid puzzle game models."""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class LogicGridCategories(BaseModel):
+    """Categories for Logic Grid puzzle."""
+
+    model_config = ConfigDict(frozen=True)
+
+    person: list[str]
+    color: list[str]
+    pet: list[str]
+    drink: list[str]
+
+
+class PersonAttributes(BaseModel):
+    """Attributes for a person in Logic Grid puzzle."""
+
+    model_config = ConfigDict(frozen=False)
+
+    color: str
+    pet: str
+    drink: str

chuk_puzzles_gym/games/mastermind/__init__.py

@@ -0,0 +1,6 @@
+"""Mastermind puzzle game module."""
+
+from .config import MastermindConfig
+from .game import MastermindGame
+
+__all__ = ["MastermindGame", "MastermindConfig"]

chuk_puzzles_gym/games/mastermind/config.py

@@ -0,0 +1,25 @@
+"""Configuration for Mastermind game."""
+
+from pydantic import BaseModel, Field
+
+from ...models.enums import DifficultyLevel
+
+
+class MastermindConfig(BaseModel):
+    """Configuration for Mastermind game."""
+
+    difficulty: DifficultyLevel = Field(default=DifficultyLevel.EASY, description="Game difficulty level")
+    code_length: int = Field(ge=3, le=6, description="Length of the secret code")
+    num_colors: int = Field(ge=4, le=8, description="Number of available colors")
+    max_guesses: int = Field(ge=8, le=15, description="Maximum number of guesses allowed")
+
+    @classmethod
+    def from_difficulty(cls, difficulty: DifficultyLevel) -> "MastermindConfig":
+        """Create config from difficulty level."""
+        config_map = {
+            DifficultyLevel.EASY: {"code_length": 4, "num_colors": 6, "max_guesses": 12},
+            DifficultyLevel.MEDIUM: {"code_length": 5, "num_colors": 7, "max_guesses": 12},
+            DifficultyLevel.HARD: {"code_length": 6, "num_colors": 8, "max_guesses": 15},
+        }
+        params = config_map[difficulty]
+        return cls(difficulty=difficulty, **params)

chuk_puzzles_gym/games/mastermind/game.py

@@ -0,0 +1,297 @@
+"""Mastermind puzzle game implementation."""
+
+from typing import Any
+
+from ...models import DifficultyProfile, MoveResult
+from .._base import PuzzleGame
+from .config import MastermindConfig
+
+
+class MastermindGame(PuzzleGame):
+    """Mastermind code-breaking puzzle game.
+
+    Guess the secret code using logical deduction from feedback.
+    Each guess gives you black pegs (correct color + position)
+    and white pegs (correct color, wrong position).
+    """
+
+    def __init__(self, difficulty: str = "easy", seed: int | None = None, **kwargs):
+        """Initialize a new Mastermind game.
+
+        Args:
+            difficulty: Game difficulty level (easy/medium/hard)
+        """
+        super().__init__(difficulty, seed, **kwargs)
+
+        # Use pydantic config based on difficulty
+        self.config = MastermindConfig.from_difficulty(self.difficulty)
+        self.code_length = self.config.code_length
+        self.num_colors = self.config.num_colors
+        self.max_guesses = self.config.max_guesses
+
+        # Color representation (1-8 for easy display)
+        self.colors = list(range(1, self.num_colors + 1))
+        self.color_names = {
+            1: "Red",
+            2: "Blue",
+            3: "Green",
+            4: "Yellow",
+            5: "Orange",
+            6: "Purple",
+            7: "Cyan",
+            8: "Magenta",
+        }
+
+        # Game state
+        self.secret_code: list[int] = []
+        self.guesses: list[list[int]] = []
+        self.feedback: list[tuple[int, int]] = []  # (black_pegs, white_pegs)
+
+    @property
+    def name(self) -> str:
+        """The display name of this puzzle type."""
+        return "Mastermind"
+
+    @property
+    def description(self) -> str:
+        """A one-line description of this puzzle type."""
+        return "Code-breaking with logical deduction and feedback"
+
+    @property
+    def constraint_types(self) -> list[str]:
+        """Constraint types demonstrated by this puzzle."""
+        return ["feedback", "elimination", "logical_inference", "pattern_matching", "iterative_refinement"]
+
+    @property
+    def business_analogies(self) -> list[str]:
+        """Business problems this puzzle models."""
+        return ["hypothesis_testing", "feedback_loops", "iterative_optimization", "parameter_tuning"]
+
+    @property
+    def complexity_profile(self) -> dict[str, str]:
+        """Complexity profile of this puzzle."""
+        return {"reasoning_type": "hybrid", "search_space": "exponential", "constraint_density": "sparse"}
+
+    @property
+    def optimal_steps(self) -> int | None:
+        """Optimal guesses for Mastermind with hints = 1 (hint reveals code)."""
+        # With hints, the code is revealed directly, so optimal is 1
+        return 1
+
+    @property
+    def difficulty_profile(self) -> "DifficultyProfile":
+        """Difficulty characteristics for Mastermind."""
+        from ...models import DifficultyLevel
+
+        logic_depth = {
+            DifficultyLevel.EASY.value: 2,
+            DifficultyLevel.MEDIUM.value: 4,
+            DifficultyLevel.HARD.value: 5,
+        }.get(self.difficulty.value, 3)
+        branching = self.num_colors**self.code_length  # Huge search space
+        return DifficultyProfile(
+            logic_depth=logic_depth,
+            branching_factor=min(10.0, branching / 100),  # Normalized
+            state_observability=0.3,  # Hidden code
+            constraint_density=0.2,
+        )
+
+    async def generate_puzzle(self) -> None:
+        """Generate a new Mastermind puzzle."""
+        # Generate random secret code
+        self.secret_code = [self._rng.choice(self.colors) for _ in range(self.code_length)]
+
+        # Reset game state
+        self.guesses = []
+        self.feedback = []
+        self.moves_made = 0
+        self.game_started = True
+
+    def _calculate_feedback(self, guess: list[int]) -> tuple[int, int]:
+        """Calculate feedback for a guess.
+
+        Args:
+            guess: The guessed code
+
+        Returns:
+            Tuple of (black_pegs, white_pegs)
+            - black_pegs: correct color in correct position
+            - white_pegs: correct color in wrong position
+        """
+        black_pegs = 0
+        white_pegs = 0
+
+        # Create copies to track which positions have been matched
+        secret_remaining = list(self.secret_code)
+        guess_remaining = list(guess)
+
+        # First pass: count black pegs (exact matches)
+        for i in range(self.code_length):
+            if guess[i] == self.secret_code[i]:
+                black_pegs += 1
+                secret_remaining[i] = -1  # Mark as used
+                guess_remaining[i] = -1  # Mark as used
+
+        # Second pass: count white pegs (color matches in wrong position)
+        for i in range(self.code_length):
+            if guess_remaining[i] != -1:  # Not already matched
+                if guess_remaining[i] in secret_remaining:
+                    white_pegs += 1
+                    # Remove the first occurrence from secret_remaining
+                    idx = secret_remaining.index(guess_remaining[i])
+                    secret_remaining[idx] = -1
+
+        return black_pegs, white_pegs
+
+    async def validate_move(self, *guess: int) -> MoveResult:
+        """Make a guess.
+
+        Args:
+            *guess: Variable number of color values (should match code_length)
+
+        Returns:
+            MoveResult with success status and message
+        """
+        # Check if game is over
+        if len(self.guesses) >= self.max_guesses:
+            return MoveResult(
+                success=False, message=f"No guesses remaining! The code was: {' '.join(map(str, self.secret_code))}"
+            )
+
+        # Validate guess length
+        if len(guess) != self.code_length:
+            return MoveResult(success=False, message=f"Guess must be exactly {self.code_length} colors.")
+
+        # Validate all colors are in range
+        for color in guess:
+            if color not in self.colors:
+                return MoveResult(success=False, message=f"Invalid color {color}. Use colors 1-{self.num_colors}.")
+
+        # Convert tuple to list
+        guess_list = list(guess)
+
+        # Calculate feedback
+        black_pegs, white_pegs = self._calculate_feedback(guess_list)
+
+        # Store guess and feedback
+        self.guesses.append(guess_list)
+        self.feedback.append((black_pegs, white_pegs))
+        self.moves_made += 1
+
+        # Check if won
+        if black_pegs == self.code_length:
+            return MoveResult(
+                success=True,
+                message=f"Congratulations! You cracked the code in {len(self.guesses)} guesses!",
+                state_changed=True,
+                game_over=True,
+            )
+
+        # Check if out of guesses
+        if len(self.guesses) >= self.max_guesses:
+            code_str = " ".join(map(str, self.secret_code))
+            return MoveResult(
+                success=True, message=f"Game over! The code was: {code_str}", state_changed=True, game_over=True
+            )
+
+        return MoveResult(success=True, message=f"Feedback: {black_pegs} black, {white_pegs} white", state_changed=True)
+
+    def is_complete(self) -> bool:
+        """Check if the puzzle is complete (code cracked)."""
+        if not self.feedback:
+            return False
+        black_pegs, _white_pegs = self.feedback[-1]
+        return black_pegs == self.code_length
+
+    async def get_hint(self) -> tuple[Any, str] | None:
+        """Get a hint for the next move.
+
+        For evaluation purposes, provides the complete secret code as a guess.
+
+        Returns:
+            Tuple of (hint_data, hint_message) or None if no hints available
+        """
+        if self.is_complete():
+            return None
+
+        # Provide the complete secret code as hint for evaluation
+        # The validate_move function expects the full code as arguments
+        hint_data = tuple(self.secret_code)
+        code_str = " ".join(str(c) for c in self.secret_code)
+        hint_message = f"The secret code is: {code_str}"
+        return hint_data, hint_message
+
+    def render_grid(self) -> str:
+        """Render the current game state as ASCII art.
+
+        Returns:
+            String representation of the game state
+        """
+        lines = []
+
+        # Header
+        lines.append(f"Mastermind - Crack the {self.code_length}-color code!")
+        lines.append(f"Colors available: 1-{self.num_colors}")
+        lines.append(f"Guesses remaining: {self.max_guesses - len(self.guesses)}")
+        lines.append("")
+
+        # Color legend
+        lines.append("Color Legend:")
+        legend_parts = []
+        for color in range(1, self.num_colors + 1):
+            legend_parts.append(f"{color}={self.color_names[color][:3]}")
+        lines.append("  " + ", ".join(legend_parts))
+        lines.append("")
+
+        # Guess history
+        if self.guesses:
+            lines.append("Guess History:")
+            lines.append("  #  | Code        | Black | White")
+            lines.append("  " + "-" * 38)
+
+            for i, (guess, (black, white)) in enumerate(zip(self.guesses, self.feedback, strict=True), 1):
+                guess_str = " ".join(str(c) for c in guess)
+                lines.append(f"  {i:2d} | {guess_str:11s} |   {black}   |   {white}")
+        else:
+            lines.append("No guesses yet. Make your first guess!")
+
+        return "\n".join(lines)
+
+    def get_rules(self) -> str:
+        """Get the rules description for Mastermind.
+
+        Returns:
+            Multi-line string describing the puzzle rules
+        """
+        return f"""MASTERMIND RULES:
+- Guess the secret {self.code_length}-color code
+- Each position uses colors 1-{self.num_colors}
+- Colors can repeat in the code
+- After each guess, you get feedback:
+  * Black peg = correct color in correct position
+  * White peg = correct color in wrong position
+- You have {self.max_guesses} guesses to crack the code
+- Use logic to eliminate possibilities!"""
+
+    def get_commands(self) -> str:
+        """Get the available commands for Mastermind.
+
+        Returns:
+            Multi-line string describing available commands
+        """
+        example = " ".join(["1"] * self.code_length)
+        return f"""MASTERMIND COMMANDS:
+  guess <c1> <c2> ... <c{self.code_length}>  - Make a guess (e.g., 'guess {example}')
+  show                   - Display current game state
+  hint                   - Get a hint for the code
+  solve                  - Reveal the 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
+        """
+        return f"Guesses made: {len(self.guesses)}/{self.max_guesses} | Code length: {self.code_length} | Colors: 1-{self.num_colors} | Seed: {self.seed}"

chuk_puzzles_gym/games/minesweeper/__init__.py

@@ -0,0 +1,6 @@
+"""Minesweeper puzzle game module."""
+
+from .config import MinesweeperConfig
+from .game import MinesweeperGame
+
+__all__ = ["MinesweeperGame", "MinesweeperConfig"]