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

chuk_puzzles_gym/games/einstein/game.py

@@ -0,0 +1,366 @@
+"""Einstein's Puzzle (Zebra Puzzle) game implementation."""
+
+from typing import Any
+
+from ...models import DifficultyLevel, DifficultyProfile, MoveResult
+from .._base import PuzzleGame
+from .constants import ATTRIBUTES, COLORS, DRINKS, NATIONALITIES, PETS, SMOKES
+from .models import HouseAssignment
+
+
+class EinsteinGame(PuzzleGame):
+    """Einstein's Puzzle (also known as Zebra Puzzle).
+
+    A classic logic puzzle with 5 houses and 5 attributes each.
+    Uses complex deduction with multiple constraint types.
+    Perfect for testing AI reasoning capabilities.
+    """
+
+    def __init__(self, difficulty: str = "easy", seed: int | None = None, **kwargs):
+        """Initialize a new Einstein's Puzzle game.
+
+        Args:
+            difficulty: Game difficulty level (easy/medium/hard)
+        """
+        super().__init__(difficulty, seed, **kwargs)
+
+        # 5 houses with 5 attributes each
+        self.num_houses = 5
+
+        # Attributes - using constants for type safety
+        self.colors = COLORS
+        self.nationalities = NATIONALITIES
+        self.drinks = DRINKS
+        self.smokes = SMOKES
+        self.pets = PETS
+
+        # Player's assignments: Change from list[dict] to list[HouseAssignment]
+        self.assignments: list[HouseAssignment] = [HouseAssignment() for _ in range(self.num_houses)]
+
+        # Solution
+        self.solution: list[HouseAssignment] = []
+
+        # Clues
+        self.clues: list[str] = []
+
+    @property
+    def name(self) -> str:
+        """The display name of this puzzle type."""
+        return "Einstein's Puzzle"
+
+    @property
+    def description(self) -> str:
+        """A one-line description of this puzzle type."""
+        return "Classic logic deduction - who owns the fish?"
+
+    @property
+    def constraint_types(self) -> list[str]:
+        """Constraint types demonstrated by this puzzle."""
+        return ["multi_attribute", "relational", "positional", "logical_implication", "transitive_closure"]
+
+    @property
+    def business_analogies(self) -> list[str]:
+        """Business problems this puzzle models."""
+        return ["multi_factor_matching", "relationship_mapping", "eligibility_rules", "complex_deduction"]
+
+    @property
+    def complexity_profile(self) -> dict[str, str]:
+        """Complexity profile of this puzzle."""
+        return {"reasoning_type": "deductive", "search_space": "large", "constraint_density": "dense"}
+
+    @property
+    def optimal_steps(self) -> int | None:
+        """Minimum steps = attribute assignments (houses x attributes)."""
+        # 5 attributes: color, nationality, drink, smoke, pet
+        return self.num_houses * 5
+
+    @property
+    def difficulty_profile(self) -> "DifficultyProfile":
+        """Difficulty characteristics for Einstein's Puzzle."""
+
+        logic_depth = {
+            DifficultyLevel.EASY.value: 5,
+            DifficultyLevel.MEDIUM.value: 7,
+            DifficultyLevel.HARD.value: 9,
+        }.get(self.difficulty.value, 6)
+        return DifficultyProfile(
+            logic_depth=logic_depth,
+            branching_factor=5.0,  # 5 houses to match
+            state_observability=1.0,
+            constraint_density=0.7,
+        )
+
+    async def generate_puzzle(self) -> None:
+        """Generate a new Einstein's Puzzle."""
+        # Generate a random valid solution by shuffling attribute lists
+        shuffled_colors = self.colors.copy()
+        shuffled_nationalities = self.nationalities.copy()
+        shuffled_drinks = self.drinks.copy()
+        shuffled_smokes = self.smokes.copy()
+        shuffled_pets = self.pets.copy()
+
+        self._rng.shuffle(shuffled_colors)
+        self._rng.shuffle(shuffled_nationalities)
+        self._rng.shuffle(shuffled_drinks)
+        self._rng.shuffle(shuffled_smokes)
+        self._rng.shuffle(shuffled_pets)
+
+        # Create solution
+        self.solution = []
+        for i in range(self.num_houses):
+            self.solution.append(
+                HouseAssignment(
+                    color=shuffled_colors[i],
+                    nationality=shuffled_nationalities[i],
+                    drink=shuffled_drinks[i],
+                    smoke=shuffled_smokes[i],
+                    pet=shuffled_pets[i],
+                )
+            )
+
+        # Generate clues based on solution
+        self.clues = self._generate_clues()
+
+        # Initialize player grid
+        self.assignments = [HouseAssignment() for _ in range(self.num_houses)]
+
+        self.moves_made = 0
+        self.game_started = True
+
+    def _generate_clues(self) -> list[str]:
+        """Generate clues based on the solution."""
+        clues = []
+
+        # Find positions of each attribute
+        def find_house(attr_type: str, value: str) -> int:
+            for i, house in enumerate(self.solution):
+                if house.get_attribute(attr_type) == value:
+                    return i
+            return -1
+
+        # Always include these starter clues
+        norwegian_house = find_house("nationality", "Norwegian")
+        milk_house = find_house("drink", "Milk")
+
+        clues.append(f"1. The Norwegian lives in house {norwegian_house + 1}")
+        clues.append(f"2. Milk is drunk in house {milk_house + 1}")
+
+        # Add attribute-to-attribute clues
+        clue_num = 3
+
+        # Same house clues
+        for i in range(self.num_houses):
+            house = self.solution[i]
+
+            # Color-Nationality
+            if self._rng.random() < 0.4:
+                clues.append(f"{clue_num}. The {house.nationality} lives in the {house.color} house")
+                clue_num += 1
+
+            # Nationality-Drink
+            if self._rng.random() < 0.4:
+                clues.append(f"{clue_num}. The {house.nationality} drinks {house.drink}")
+                clue_num += 1
+
+            # Smoke-Pet (skip if smoke name has spaces to avoid test parsing issues)
+            if self._rng.random() < 0.4 and " " not in house.smoke:
+                pet = house.pet
+                clues.append(f"{clue_num}. The person who smokes {house.smoke} owns a {pet}")
+                clue_num += 1
+
+        # Neighbor clues
+        for i in range(self.num_houses - 1):
+            house1 = self.solution[i]
+            house2 = self.solution[i + 1]
+
+            if self._rng.random() < 0.3:
+                clues.append(f"{clue_num}. The {house1.color} house is next to the {house2.color} house")
+                clue_num += 1
+
+        # Limit number of clues
+        max_clues_map = {
+            DifficultyLevel.EASY: 12,
+            DifficultyLevel.MEDIUM: 10,
+            DifficultyLevel.HARD: 8,
+        }
+        max_clues = max_clues_map[self.difficulty]
+        return clues[:max_clues]
+
+    async def validate_move(self, house: int, attribute: str, value: str) -> MoveResult:
+        """Assign an attribute to a house.
+
+        Args:
+            house: House number (1-indexed, user-facing)
+            attribute: Attribute type (color, nationality, drink, smoke, pet)
+            value: Attribute value
+
+        Returns:
+            MoveResult indicating success/failure and message
+        """
+        # Convert to 0-indexed
+        house -= 1
+
+        # Validate house number
+        if not (0 <= house < self.num_houses):
+            return MoveResult(success=False, message=f"Invalid house number. Use 1-{self.num_houses}.")
+
+        # Normalize attribute and value
+        attribute = attribute.lower()
+        value = value.title()  # Use title() to handle multi-word values like "Pall Mall"
+
+        # Handle space-to-hyphen conversion for backward compatibility
+        value_normalized = value.replace(" ", "-")
+
+        # Validate attribute type and get valid values
+        valid_attribute_names = ["color", "nationality", "drink", "smoke", "pet"]
+        if attribute not in valid_attribute_names:
+            return MoveResult(success=False, message=f"Invalid attribute. Use: {', '.join(valid_attribute_names)}")
+
+        # Get the valid values list for this attribute
+        if attribute == "color":
+            valid_values = self.colors
+        elif attribute == "nationality":
+            valid_values = self.nationalities
+        elif attribute == "drink":
+            valid_values = self.drinks
+        elif attribute == "smoke":
+            valid_values = self.smokes
+        elif attribute == "pet":
+            valid_values = self.pets
+        else:
+            # Should never reach here due to earlier check
+            return MoveResult(success=False, message=f"Invalid attribute: {attribute}")
+
+        # Validate value (try both original and normalized)
+        if value in valid_values:
+            pass  # Value is valid as-is
+        elif value_normalized in valid_values:
+            value = value_normalized  # Use normalized version
+        else:
+            return MoveResult(success=False, message=f"Invalid {attribute}. Choose from: {', '.join(valid_values)}")
+
+        # Check if value is already assigned to another house
+        for i, other_house in enumerate(self.assignments):
+            if i != house and other_house.get_attribute(attribute) == value:
+                return MoveResult(success=False, message=f"{value} is already assigned to house {i + 1}")
+
+        # Check if this house already has a value for this attribute
+        if self.assignments[house].get_attribute(attribute) is not None:
+            old_value = self.assignments[house].get_attribute(attribute)
+            self.assignments[house].set_attribute(attribute, value)
+            self.moves_made += 1
+            return MoveResult(
+                success=True,
+                message=f"Changed house {house + 1}'s {attribute} from {old_value} to {value}",
+                state_changed=True,
+            )
+
+        # Assign the value
+        self.assignments[house].set_attribute(attribute, value)
+        self.moves_made += 1
+        return MoveResult(success=True, message=f"Assigned {value} to house {house + 1}", state_changed=True)
+
+    def is_complete(self) -> bool:
+        """Check if the puzzle is completely and correctly solved."""
+        # All houses must have all attributes assigned
+        for house in self.assignments:
+            if not house.is_complete():
+                return False
+
+        # Check if assignments match solution
+        for i in range(self.num_houses):
+            for attr in ATTRIBUTES:
+                if self.assignments[i].get_attribute(attr) != self.solution[i].get_attribute(attr):
+                    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
+        """
+        # Find first unassigned attribute in solution
+        for i in range(self.num_houses):
+            for attr in ATTRIBUTES:
+                if self.assignments[i].get_attribute(attr) != self.solution[i].get_attribute(attr):
+                    value = self.solution[i].get_attribute(attr)
+                    hint_data = (i + 1, attr, value)
+                    hint_message = f"Try assigning {value} to house {i + 1} as its {attr}"
+                    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
+        """
+        lines = []
+
+        lines.append("Einstein's Puzzle - Who owns the fish?")
+        lines.append("")
+
+        # Houses table
+        lines.append("House | Color   | Nationality | Drink  | Smoke       | Pet")
+        lines.append("------+---------+-------------+--------+-------------+--------")
+
+        for i in range(self.num_houses):
+            house = self.assignments[i]
+            color = house.color or "?"
+            nationality = house.nationality or "?"
+            drink = house.drink or "?"
+            smoke = house.smoke or "?"
+            pet = house.pet or "?"
+
+            lines.append(f"  {i + 1}   | {color:<7s} | {nationality:<11s} | {drink:<6s} | {smoke:<11s} | {pet:<6s}")
+
+        lines.append("")
+        lines.append("Clues:")
+        for clue in self.clues:
+            lines.append(f"  {clue}")
+
+        return "\n".join(lines)
+
+    def get_rules(self) -> str:
+        """Get the rules description for Einstein's Puzzle.
+
+        Returns:
+            Multi-line string describing the puzzle rules
+        """
+        return """EINSTEIN'S PUZZLE RULES:
+- There are 5 houses in a row
+- Each house has a unique color, nationality, drink, smoke, and pet
+- Use the clues to deduce which attribute belongs in which house
+- No attribute can appear in more than one house
+- All houses must have all 5 attributes assigned
+- Question: WHO OWNS THE FISH?"""
+
+    def get_commands(self) -> str:
+        """Get the available commands for Einstein's Puzzle.
+
+        Returns:
+            Multi-line string describing available commands
+        """
+        return """EINSTEIN'S PUZZLE COMMANDS:
+  assign <house> <attr> <value>  - Assign attribute (e.g., 'assign 1 color red')
+                                   Attributes: color, nationality, drink, smoke, pet
+  show                           - Display current assignments
+  hint                           - Get a hint
+  check                          - Check if solution is correct
+  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
+        """
+        assigned = sum(1 for house in self.assignments for attr in ATTRIBUTES if house.get_attribute(attr) is not None)
+        total = self.num_houses * 5
+
+        return f"Moves: {self.moves_made} | Assigned: {assigned}/{total} | Clues: {len(self.clues)} | Seed: {self.seed}"

chuk_puzzles_gym/games/einstein/models.py

@@ -0,0 +1,35 @@
+"""Einstein's Puzzle game models."""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class HouseAssignment(BaseModel):
+    """Attribute assignments for a house in Einstein's Puzzle."""
+
+    model_config = ConfigDict(frozen=False)  # Allow mutation during gameplay
+
+    color: str | None = None
+    nationality: str | None = None
+    drink: str | None = None
+    smoke: str | None = None
+    pet: str | None = None
+
+    def is_complete(self) -> bool:
+        """Check if all attributes are assigned."""
+        return all(
+            [
+                self.color is not None,
+                self.nationality is not None,
+                self.drink is not None,
+                self.smoke is not None,
+                self.pet is not None,
+            ]
+        )
+
+    def get_attribute(self, attr_type: str) -> str | None:
+        """Get attribute value by type."""
+        return getattr(self, attr_type.lower(), None)
+
+    def set_attribute(self, attr_type: str, value: str) -> None:
+        """Set attribute value by type."""
+        setattr(self, attr_type.lower(), value)

chuk_puzzles_gym/games/fillomino/__init__.py

@@ -0,0 +1,6 @@
+"""Fillomino puzzle game module."""
+
+from .config import FillominoConfig
+from .game import FillominoGame
+
+__all__ = ["FillominoGame", "FillominoConfig"]

chuk_puzzles_gym/games/fillomino/config.py

@@ -0,0 +1,24 @@
+"""Configuration for Fillomino game."""
+
+from pydantic import BaseModel, Field
+
+from ...models.enums import DifficultyLevel
+
+
+class FillominoConfig(BaseModel):
+    """Configuration for Fillomino game."""
+
+    difficulty: DifficultyLevel = Field(default=DifficultyLevel.EASY, description="Game difficulty level")
+    size: int = Field(ge=6, le=10, description="Grid size (NxN)")
+    num_clues: int = Field(ge=4, description="Number of clue numbers to reveal")
+
+    @classmethod
+    def from_difficulty(cls, difficulty: DifficultyLevel) -> "FillominoConfig":
+        """Create config from difficulty level."""
+        config_map = {
+            DifficultyLevel.EASY: {"size": 6, "num_clues": 8},
+            DifficultyLevel.MEDIUM: {"size": 8, "num_clues": 10},
+            DifficultyLevel.HARD: {"size": 10, "num_clues": 12},
+        }
+        params = config_map[difficulty]
+        return cls(difficulty=difficulty, **params)