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

chuk_puzzles_gym/games/skyscrapers/game.py

@@ -0,0 +1,277 @@
+"""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_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/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
 

chuk_puzzles_gym/trace/generator.py

@@ -711,6 +711,93 @@ class TraceGenerator:
         """Generate trace for Einstein's Puzzle (handles 'einstein's puzzle' -> 'einsteins_puzzle')."""
         return self._generate_einstein(game)
 
+    def _generate_graph_coloring(self, game: PuzzleGame) -> Trace:
+        """Generate trace for Graph Coloring puzzle."""
+        problem_id = f"graph_coloring_{game.difficulty.value}_{game.seed}"
+        steps: list[Step] = []
+
+        solution = getattr(game, "solution", {})
+        initial_coloring = getattr(game, "initial_coloring", {})
+        step_idx = 0
+
+        for node in sorted(solution.keys()):
+            if node not in initial_coloring:
+                color = solution[node]
+                step = Step(
+                    index=step_idx,
+                    operation=StepOperation.PLACE,
+                    before_state=f"node({node})=uncolored",
+                    after_state=f"node({node})=color{color}",
+                    output_value=color,
+                    position=(node,),
+                    rule_applied="graph_coloring_constraint",
+                    explanation=f"Color node {node} with color {color}, avoiding conflicts with adjacent nodes.",
+                )
+                steps.append(step)
+                step_idx += 1
+
+        return Trace(
+            problem_id=problem_id,
+            steps=steps,
+            checkpoints=self._identify_checkpoints(steps),
+        )
+
+    def _generate_cryptarithmetic(self, game: PuzzleGame) -> Trace:
+        """Generate trace for Cryptarithmetic puzzle."""
+        problem_id = f"cryptarithmetic_{game.difficulty.value}_{game.seed}"
+        steps: list[Step] = []
+
+        letter_mapping = getattr(game, "letter_mapping", {})
+        initial_mapping = getattr(game, "initial_mapping", {})
+        step_idx = 0
+
+        for letter in sorted(letter_mapping.keys()):
+            if letter not in initial_mapping:
+                digit = letter_mapping[letter]
+                step = Step(
+                    index=step_idx,
+                    operation=StepOperation.DEDUCE,
+                    before_state=f"letter({letter})=unknown",
+                    after_state=f"letter({letter})={digit}",
+                    output_value=digit,
+                    rule_applied="arithmetic_constraint",
+                    explanation=f"Assign digit {digit} to letter {letter} to satisfy the equation.",
+                )
+                steps.append(step)
+                step_idx += 1
+
+        return Trace(
+            problem_id=problem_id,
+            steps=steps,
+            checkpoints=self._identify_checkpoints(steps),
+        )
+
+    def _generate_rush_hour(self, game: PuzzleGame) -> Trace:
+        """Generate trace for Rush Hour puzzle."""
+        problem_id = f"rush_hour_{game.difficulty.value}_{game.seed}"
+        steps: list[Step] = []
+
+        # Rush Hour traces are move sequences; generate from hint system
+        vehicles = getattr(game, "vehicles", {})
+        if vehicles:
+            step = Step(
+                index=0,
+                operation=StepOperation.DEDUCE,
+                before_state="target_car=blocked",
+                after_state="target_car=exit",
+                output_value="solve",
+                rule_applied="sequential_planning",
+                explanation=f"Slide vehicles to clear a path for car X to reach the exit. "
+                f"Minimum solution: {getattr(game, 'min_solution_moves', '?')} moves.",
+            )
+            steps.append(step)
+
+        return Trace(
+            problem_id=problem_id,
+            steps=steps,
+            checkpoints=self._identify_checkpoints(steps),
+        )
+
 
 def generate_trace(game: PuzzleGame) -> Trace:
     """

{chuk_puzzles_gym-0.9.dist-info → chuk_puzzles_gym-0.10.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: chuk-puzzles-gym
-Version: 0.9
-Summary: Multi-game puzzle gym for LLM training and benchmarking - 24 constraint puzzles with synthetic data generation
+Version: 0.10
+Summary: Multi-game puzzle gym for LLM training and benchmarking - 30 constraint puzzles with synthetic data generation
 Author: Chris Hay
 License: MIT
 Project-URL: Homepage, https://github.com/chrishayuk/chuk-puzzles-gym
@@ -39,7 +39,7 @@ Requires-Dist: ipython>=8.14.0; extra == "dev"
 [![Pydantic v2](https://img.shields.io/badge/pydantic-v2-purple.svg)](https://docs.pydantic.dev/)
 [![Type Checked](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)
 
-A **multi-game puzzle gym** for **LLM training and benchmarking**, hosting 24 different logic puzzle types with synthetic data generation. Built using [chuk-gym-core](https://github.com/chrishayuk/chuk-gym-core) and [chuk-protocol-server](https://github.com/chrishayuk/chuk-protocol-server).
+A **multi-game puzzle gym** for **LLM training and benchmarking**, hosting 30 different logic puzzle types with synthetic data generation. Built using [chuk-gym-core](https://github.com/chrishayuk/chuk-gym-core) and [chuk-protocol-server](https://github.com/chrishayuk/chuk-protocol-server).
 
 **Perfect for:**
 - 🤖 **LLM Agent Testing** - Benchmark reasoning capabilities across constraint types
@@ -82,12 +82,13 @@ Once connected, type `help` to see available games, or `sudoku easy` to start pl
 
 ## Features
 
-- **24 Puzzle Games** with three difficulty levels each (easy, medium, hard)
+- **30 Puzzle Games** with three difficulty levels each (easy, medium, hard)
   - **7 Classic Logic Puzzles** - Sudoku, KenKen, Kakuro, Binary, Futoshiki, Nonogram, Logic Grid
   - **7 Advanced CP-SAT Puzzles** - Killer Sudoku, Lights Out, Mastermind, Slitherlink, Bridges, Hitori, Shikaku
   - **5 Specialized Constraint Puzzles** - Hidato, Tents and Trees, Fillomino, Star Battle, Sokoban
   - **2 Optimization Challenges** - Knapsack, Task Scheduler
   - **3 Advanced Reasoning Puzzles** - Nurikabe, Einstein's Puzzle, Minesweeper
+  - **6 Combinatorial & Search Puzzles** - Skyscrapers, N-Queens, Numberlink, Graph Coloring, Cryptarithmetic, Rush Hour
 - **Agent-Friendly Mode** - Structured output with clear markers for AI agents and tools
   - Enable with `mode agent` command
   - Machine-parseable grid format with clear start/end markers
@@ -113,7 +114,7 @@ Once connected, type `help` to see available games, or `sudoku easy` to start pl
 - **Clean ASCII art grids** - perfectly aligned for easy parsing
 - **Deterministic seeding** - Replay any puzzle with the same seed
 - **Gymnasium-compatible RL Environment** (`PuzzleEnv`) for training agents
-- **Comprehensive test suite** (1067 tests, 94% coverage)
+- **Comprehensive test suite** (1323 tests, 94% coverage)
 - **Modern Python best practices:**
   - **Pydantic v2 native** - All models use ConfigDict for type safety
   - **Async native** - Full async/await support throughout
@@ -173,6 +174,17 @@ Once connected, type `help` to see available games, or `sudoku easy` to start pl
 | **Einstein's Puzzle** | 5 houses × 5 attributes | Multi-attribute deduction + Logic chains | ✅ Complete |
 | **Minesweeper** | 6×6 to 10×10 | Probabilistic reasoning + Safe deduction | ✅ Complete |
 
+### Combinatorial & Search Puzzles
+
+| Game | Grid Size | Constraint Types | Status |
+|------|-----------|------------------|--------|
+| **Skyscrapers** | 4×4 to 6×6 | Latin square + Visibility clues from 4 borders | ✅ Complete |
+| **N-Queens** | 6×6 to 12×12 | Placement + Row/Column/Diagonal attack avoidance | ✅ Complete |
+| **Numberlink** | 5×5 to 9×9 | Path connectivity + Non-crossing + Space filling | ✅ Complete |
+| **Graph Coloring** | 6-15 nodes | Graph coloring + Inequality + Global constraint | ✅ Complete |
+| **Cryptarithmetic** | 3-5 digit words | Arithmetic + AllDifferent + Carry propagation | ✅ Complete |
+| **Rush Hour** | 6×6 | Sequential planning + Spatial blocking + Search | ✅ Complete |
+
 ## Solver Profiles & Business Mapping
 
 Each game includes metadata for **constraint types**, **business analogies**, and **complexity profiles**, making it easy to:
@@ -216,7 +228,13 @@ resource_games = [
 | **Global Loop** | Slitherlink | Circuit design, Path finding |
 | **Boolean SAT** | Lights Out | Feature dependencies, Toggle systems |
 | **Cage Sums** | Killer Sudoku, Kakuro | Team budgets, Grouped constraints |
-| **AllDifferent** | Sudoku, KenKen | Resource uniqueness, Assignment problems |
+| **AllDifferent** | Sudoku, KenKen, Skyscrapers | Resource uniqueness, Assignment problems |
+| **Visibility/Ordering** | Skyscrapers | Priority ranking, Stack-based processing |
+| **Attack Avoidance** | N-Queens, Star Battle | Non-conflicting resource placement |
+| **Path Connectivity** | Numberlink, Nurikabe | Network routing, Cable layout |
+| **Graph Coloring** | Graph Coloring | Frequency assignment, Register allocation, Scheduling |
+| **Arithmetic Deduction** | Cryptarithmetic, KenKen | Code breaking, Constraint propagation |
+| **Sequential Planning** | Rush Hour, Sokoban | Logistics planning, Deadlock resolution |
 
 ## Quick Start
 
@@ -397,6 +415,14 @@ ADVANCED REASONING PUZZLES:
  23) Einstein's Puzzle - Who owns the fish? Multi-attribute deduction
  24) Minesweeper     - Find all mines using logical deduction
 
+COMBINATORIAL & SEARCH PUZZLES:
+ 25) Skyscrapers     - Latin square with visibility clues from borders
+ 26) N-Queens        - Place queens with no row/column/diagonal conflicts
+ 27) Numberlink      - Connect pairs with non-crossing paths filling the grid
+ 28) Graph Coloring  - Color nodes so no adjacent pair shares a color
+ 29) Cryptarithmetic - Assign digits to letters to satisfy an equation
+ 30) Rush Hour       - Slide vehicles to free the target car to the exit
+
 Commands:
   <number>  - Select game by number
   <name>    - Select game by name (e.g., 'sudoku')
@@ -453,7 +479,7 @@ The project includes a **Gymnasium-compatible environment** for training reinfor
 ```python
 from chuk_puzzles_gym.gym_env import PuzzleEnv
 
-# Create environment for any of the 24 games
+# Create environment for any of the 30 games
 env = PuzzleEnv("sudoku", difficulty="easy", seed=42)
 
 # Reset to start a new episode
@@ -472,7 +498,7 @@ games = PuzzleEnv.available_games()
 
 ### Features
 
-- **All 24 games** accessible through unified API
+- **All 30 games** accessible through unified API
 - **Configurable rewards** for correct moves, invalid attempts, completion bonuses
 - **Hint system** with optional budget limits
 - **Solver-free mode** for pure reasoning benchmarks
@@ -586,7 +612,7 @@ Generate synthetic puzzle datasets for training and benchmarking LLMs and constr
 ### CLI Usage
 
 ```bash
-# Generate 100 puzzles per game/difficulty for all 24 games
+# Generate 100 puzzles per game/difficulty for all 30 games
 chuk-puzzles-export -o puzzles.jsonl
 
 # Specific games only
@@ -744,6 +770,9 @@ When `include_trace=True` (default), each problem includes step-by-step solution
 | Hitori | `duplicate_elimination` |
 | Bridges | `connectivity_constraint` |
 | Slitherlink | `loop_constraint` |
+| Graph Coloring | `graph_coloring_constraint` |
+| Cryptarithmetic | `arithmetic_constraint` |
+| Rush Hour | `sequential_planning` |
 | Others | `constraint_propagation` |
 
 ### Example: Generate Training Data
@@ -772,9 +801,9 @@ With default settings (`-n 100` per game/difficulty):
 
 | Configuration | Problems Generated |
 |--------------|-------------------|
-| All games, all difficulties | 24 games × 3 difficulties × 100 = 7,200 |
+| All games, all difficulties | 30 games × 3 difficulties × 100 = 9,000 |
 | Single game, all difficulties | 1 × 3 × 100 = 300 |
-| All games, single difficulty | 24 × 1 × 100 = 2,400 |
+| All games, single difficulty | 30 × 1 × 100 = 3,000 |
 
 ### Integration with chuk-gym-core
 
@@ -983,7 +1012,7 @@ pip install -e ".[dev]"
 
 ### Testing
 
-The project has comprehensive test coverage (94%, 1067 tests):
+The project has comprehensive test coverage (94%, 1323 tests):
 
 ```bash
 # Run all tests
@@ -1034,7 +1063,7 @@ The project follows modern Python best practices with a **9.8/10 compliance scor
 - ✅ **Test Coverage** (9.5/10) - 94% overall, most files ≥90%
 
 #### Quality Metrics
-- **1067 tests** - All passing ✅
+- **1323 tests** - All passing ✅
 - **94% coverage** - Exceeds 90% threshold ✅
 - **Zero linting errors** - Clean codebase ✅
 - **Full type safety** - MyPy passes ✅
@@ -1181,7 +1210,7 @@ chuk-puzzles-gym/
 │           │   ├── __init__.py
 │           │   ├── game.py
 │           │   └── config.py
-│           └── ... (24 games total)
+│           └── ... (30 games total)
 ├── tests/
 │   ├── test_puzzle_game.py       # Base class tests
 │   ├── test_deterministic_seeding.py  # Seeding tests
@@ -1191,6 +1220,12 @@ chuk-puzzles-gym/
 ├── examples/
 │   ├── simple_client.py          # Telnet client example
 │   ├── websocket_client.py       # WebSocket client example
+│   ├── example_skyscrapers.py    # Skyscrapers game logic demo
+│   ├── example_nqueens.py        # N-Queens game logic demo
+│   ├── example_numberlink.py     # Numberlink game logic demo
+│   ├── example_graph_coloring.py # Graph Coloring game logic demo
+│   ├── example_cryptarithmetic.py# Cryptarithmetic game logic demo
+│   ├── example_rush_hour.py      # Rush Hour game logic demo
 │   └── README.md                 # Example usage guide
 ├── .github/workflows/            # CI/CD workflows
 ├── pyproject.toml                # Modern Python project config
@@ -1203,14 +1238,15 @@ chuk-puzzles-gym/
 
 ### Key Statistics
 
-- **Test Coverage**: 94% overall (1067 tests, all passing)
+- **Test Coverage**: 94% overall (1323 tests, all passing)
 - **Code Quality Score**: 9.8/10 (near perfect compliance)
-- **Games Implemented**: 24 complete puzzle types
+- **Games Implemented**: 30 complete puzzle types
   - 7 Classic Logic Puzzles
   - 7 Advanced CP-SAT Puzzles
   - 5 Specialized Constraint Puzzles
   - 2 Optimization Challenges
   - 3 Advanced Reasoning Puzzles
+  - 6 Combinatorial & Search Puzzles
 - **Supported Transports**: 4 (Telnet, TCP, WebSocket, WS-Telnet)
 - **Agent-Friendly Mode**: Structured output for AI tools
 - **Gymnasium API**: RL-compatible environment for all games
@@ -1243,7 +1279,7 @@ Test the generality of constraint solvers (like MCP solvers):
 
 Learn about constraint satisfaction problems:
 
-- **24 different puzzle types** demonstrating various constraint types:
+- **30 different puzzle types** demonstrating various constraint types:
   - AllDifferent constraints (Sudoku, KenKen, Futoshiki)
   - Arithmetic constraints (KenKen, Kakuro, Killer Sudoku)
   - Boolean/SAT constraints (Lights Out, Binary Puzzle)
@@ -1253,9 +1289,14 @@ Learn about constraint satisfaction problems:
   - Temporal reasoning (Task Scheduler)
   - Connectivity constraints (Nurikabe, Slitherlink)
   - Probabilistic reasoning (Minesweeper)
-  - And more!
+  - Graph coloring (Graph Coloring)
+  - Arithmetic deduction (Cryptarithmetic)
+  - Sequential planning (Rush Hour)
+  - Visibility constraints (Skyscrapers)
+  - Attack avoidance (N-Queens)
+  - Path connectivity (Numberlink)
 - **Well-documented code** showing puzzle generation algorithms
-- **Comprehensive tests** (1067 tests, 94% coverage) demonstrating validation
+- **Comprehensive tests** (1323 tests, 94% coverage) demonstrating validation
 - **Deterministic seeding** - Reproduce any puzzle for debugging/testing
 - **Production-ready** - 9.8/10 code quality score
 - **Type-safe** - Full Pydantic v2 and MyPy compliance