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

chuk_puzzles_gym/games/graph_coloring/config.py

@@ -0,0 +1,24 @@
+"""Configuration for Graph Coloring puzzle game."""
+
+from pydantic import BaseModel, Field
+
+from ...models import DifficultyLevel
+
+
+class GraphColoringConfig(BaseModel):
+    """Configuration for a Graph Coloring puzzle."""
+
+    difficulty: DifficultyLevel = Field(default=DifficultyLevel.EASY)
+    num_nodes: int = Field(ge=4, le=20, description="Number of nodes in the graph")
+    num_colors: int = Field(ge=2, le=8, description="Number of available colors")
+    edge_density: float = Field(ge=0.1, le=0.9, description="Probability of edge between nodes")
+
+    @classmethod
+    def from_difficulty(cls, difficulty: DifficultyLevel) -> "GraphColoringConfig":
+        """Create config from difficulty level."""
+        config_map = {
+            DifficultyLevel.EASY: {"num_nodes": 6, "num_colors": 3, "edge_density": 0.3},
+            DifficultyLevel.MEDIUM: {"num_nodes": 10, "num_colors": 4, "edge_density": 0.4},
+            DifficultyLevel.HARD: {"num_nodes": 15, "num_colors": 4, "edge_density": 0.5},
+        }
+        return cls(difficulty=difficulty, **config_map[difficulty])

chuk_puzzles_gym/games/graph_coloring/game.py

@@ -0,0 +1,309 @@
+"""Graph Coloring puzzle game implementation."""
+
+from collections import deque
+from typing import Any
+
+from ...models import DifficultyLevel, DifficultyProfile, MoveResult
+from .._base import PuzzleGame
+from .config import GraphColoringConfig
+
+COLOR_NAMES = ["Red", "Blue", "Green", "Yellow", "Orange", "Purple", "Cyan", "Magenta"]
+
+
+class GraphColoringGame(PuzzleGame):
+    """Graph Coloring puzzle - assign colors to nodes with no adjacent conflicts.
+
+    Rules:
+    - A graph has N nodes connected by edges
+    - Assign one of K colors to each node
+    - No two adjacent (connected) nodes may share the same color
+    """
+
+    def __init__(self, difficulty: str = "easy", seed: int | None = None, **kwargs):
+        super().__init__(difficulty, seed, **kwargs)
+        self.config = GraphColoringConfig.from_difficulty(self.difficulty)
+        self.num_nodes = self.config.num_nodes
+        self.num_colors = self.config.num_colors
+        self.edges: list[tuple[int, int]] = []
+        self.adjacency: dict[int, set[int]] = {}
+        self.coloring: dict[int, int] = {}  # Player's assignment: node -> color (0=uncolored)
+        self.solution: dict[int, int] = {}
+        self.initial_coloring: dict[int, int] = {}  # Pre-colored nodes
+        # Grid representation for server compatibility (adjacency matrix)
+        self.grid: list[list[int]] = []
+
+    @property
+    def name(self) -> str:
+        return "Graph Coloring"
+
+    @property
+    def description(self) -> str:
+        return "Color graph nodes so no adjacent nodes share a color"
+
+    @property
+    def constraint_types(self) -> list[str]:
+        return ["graph_coloring", "inequality", "global_constraint"]
+
+    @property
+    def business_analogies(self) -> list[str]:
+        return ["frequency_assignment", "exam_timetabling", "register_allocation", "zone_planning"]
+
+    @property
+    def complexity_profile(self) -> dict[str, str]:
+        return {
+            "reasoning_type": "deductive",
+            "search_space": "exponential",
+            "constraint_density": "moderate",
+        }
+
+    @property
+    def complexity_metrics(self) -> dict[str, int | float]:
+        uncolored = sum(1 for n in range(1, self.num_nodes + 1) if self.coloring.get(n, 0) == 0)
+        return {
+            "variable_count": self.num_nodes,
+            "constraint_count": len(self.edges),
+            "domain_size": self.num_colors,
+            "branching_factor": self.num_colors,
+            "empty_cells": uncolored,
+        }
+
+    @property
+    def difficulty_profile(self) -> DifficultyProfile:
+        profiles = {
+            DifficultyLevel.EASY: DifficultyProfile(
+                logic_depth=2, branching_factor=3.0, state_observability=1.0, constraint_density=0.5
+            ),
+            DifficultyLevel.MEDIUM: DifficultyProfile(
+                logic_depth=4, branching_factor=4.0, state_observability=1.0, constraint_density=0.5
+            ),
+            DifficultyLevel.HARD: DifficultyProfile(
+                logic_depth=6, branching_factor=4.0, state_observability=1.0, constraint_density=0.6
+            ),
+        }
+        return profiles[self.difficulty]
+
+    @property
+    def optimal_steps(self) -> int | None:
+        initial_colored = len(self.initial_coloring)
+        return self.num_nodes - initial_colored
+
+    def _ensure_connected(self) -> None:
+        """Add edges to make the graph connected if needed."""
+        # Find connected components using BFS
+        visited: set[int] = set()
+        components: list[set[int]] = []
+
+        for node in range(1, self.num_nodes + 1):
+            if node in visited:
+                continue
+            component: set[int] = set()
+            queue = deque([node])
+            while queue:
+                n = queue.popleft()
+                if n in visited:
+                    continue
+                visited.add(n)
+                component.add(n)
+                for neighbor in self.adjacency.get(n, set()):
+                    if neighbor not in visited:
+                        queue.append(neighbor)
+            components.append(component)
+
+        # Connect components by adding edges between them
+        for i in range(1, len(components)):
+            # Pick a node from each component
+            node_a = self._rng.choice(list(components[i - 1]))
+            node_b = self._rng.choice(list(components[i]))
+            # Ensure different colors for the edge
+            if self.solution[node_a] == self.solution[node_b]:
+                # Swap one node's color with an unused color
+                for color in range(1, self.num_colors + 1):
+                    if color != self.solution[node_a]:
+                        conflict = False
+                        for neighbor in self.adjacency.get(node_b, set()):
+                            if self.solution.get(neighbor, 0) == color:
+                                conflict = True
+                                break
+                        if not conflict:
+                            self.solution[node_b] = color
+                            break
+
+            edge = (min(node_a, node_b), max(node_a, node_b))
+            if edge not in set(self.edges):
+                self.edges.append(edge)
+                self.adjacency.setdefault(node_a, set()).add(node_b)
+                self.adjacency.setdefault(node_b, set()).add(node_a)
+            # Merge components
+            components[i] = components[i] | components[i - 1]
+
+    async def generate_puzzle(self) -> None:
+        """Generate a graph coloring puzzle."""
+        n = self.num_nodes
+        k = self.num_colors
+        density = self.config.edge_density
+
+        # Assign each node a random color (guarantees k-colorability)
+        self.solution = {}
+        for node in range(1, n + 1):
+            self.solution[node] = self._rng.randint(1, k)
+
+        # Generate edges: only between differently colored nodes
+        self.edges = []
+        self.adjacency = {node: set() for node in range(1, n + 1)}
+        for i in range(1, n + 1):
+            for j in range(i + 1, n + 1):
+                if self.solution[i] != self.solution[j]:
+                    if self._rng.random() < density:
+                        self.edges.append((i, j))
+                        self.adjacency[i].add(j)
+                        self.adjacency[j].add(i)
+
+        # Ensure graph is connected
+        self._ensure_connected()
+
+        # Pre-color some nodes based on difficulty
+        pre_color_map = {
+            DifficultyLevel.EASY: 2,
+            DifficultyLevel.MEDIUM: 1,
+            DifficultyLevel.HARD: 0,
+        }
+        num_pre = min(pre_color_map[self.difficulty], n)
+        nodes = list(range(1, n + 1))
+        self._rng.shuffle(nodes)
+        self.initial_coloring = {}
+        for node in nodes[:num_pre]:
+            self.initial_coloring[node] = self.solution[node]
+
+        # Initialize player coloring with pre-colored nodes
+        self.coloring = dict.fromkeys(range(1, n + 1), 0)
+        for node, color in self.initial_coloring.items():
+            self.coloring[node] = color
+
+        # Build adjacency matrix as grid for server compatibility
+        self.grid = [[0] * n for _ in range(n)]
+        for i, j in self.edges:
+            self.grid[i - 1][j - 1] = 1
+            self.grid[j - 1][i - 1] = 1
+
+        self.game_started = True
+
+    async def validate_move(self, node: int, color: int) -> MoveResult:
+        """Validate assigning a color to a node.
+
+        Args:
+            node: Node ID (1-indexed)
+            color: Color number (1-K) or 0 to clear
+        """
+        if not (1 <= node <= self.num_nodes):
+            self.record_move((node,), False)
+            return MoveResult(success=False, message=f"Node must be between 1 and {self.num_nodes}.")
+
+        if node in self.initial_coloring:
+            self.record_move((node,), False)
+            return MoveResult(success=False, message="Cannot modify a pre-colored node.")
+
+        if color == 0:
+            self.coloring[node] = 0
+            self.record_move((node,), True)
+            return MoveResult(success=True, message=f"Cleared color from node {node}.", state_changed=True)
+
+        if not (1 <= color <= self.num_colors):
+            self.record_move((node,), False)
+            return MoveResult(
+                success=False,
+                message=f"Color must be between 1 and {self.num_colors} ({', '.join(COLOR_NAMES[: self.num_colors])}).",
+            )
+
+        # Check for conflicts with adjacent nodes
+        for neighbor in self.adjacency.get(node, set()):
+            if self.coloring.get(neighbor, 0) == color:
+                self.record_move((node,), False)
+                color_name = COLOR_NAMES[color - 1] if color <= len(COLOR_NAMES) else str(color)
+                return MoveResult(
+                    success=False,
+                    message=f"Conflict: adjacent node {neighbor} already has color {color_name}.",
+                )
+
+        self.coloring[node] = color
+        self.record_move((node,), True)
+        color_name = COLOR_NAMES[color - 1] if color <= len(COLOR_NAMES) else str(color)
+        return MoveResult(success=True, message=f"Colored node {node} with {color_name}.", state_changed=True)
+
+    def is_complete(self) -> bool:
+        """Check if all nodes are colored with no conflicts."""
+        # All nodes must be colored
+        for node in range(1, self.num_nodes + 1):
+            if self.coloring.get(node, 0) == 0:
+                return False
+
+        # No adjacent nodes share a color
+        for i, j in self.edges:
+            if self.coloring[i] == self.coloring[j]:
+                return False
+
+        return True
+
+    async def get_hint(self) -> tuple[Any, str] | None:
+        """Suggest a node to color."""
+        if not self.can_use_hint():
+            return None
+        for node in range(1, self.num_nodes + 1):
+            if self.coloring.get(node, 0) == 0:
+                color = self.solution[node]
+                color_name = COLOR_NAMES[color - 1] if color <= len(COLOR_NAMES) else str(color)
+                return (
+                    (node, color),
+                    f"Try coloring node {node} with {color_name} (color {color}).",
+                )
+        return None
+
+    def render_grid(self) -> str:
+        """Render the graph structure and current coloring."""
+        lines = []
+        lines.append(f"Graph: {self.num_nodes} nodes, {len(self.edges)} edges, {self.num_colors} colors")
+        lines.append("")
+
+        # Color palette
+        palette = []
+        for i in range(1, self.num_colors + 1):
+            name = COLOR_NAMES[i - 1] if i <= len(COLOR_NAMES) else str(i)
+            palette.append(f"{i}={name}")
+        lines.append("Colors: " + ", ".join(palette))
+        lines.append("")
+
+        # Node coloring status
+        lines.append("Nodes:")
+        for node in range(1, self.num_nodes + 1):
+            color = self.coloring.get(node, 0)
+            neighbors = sorted(self.adjacency.get(node, set()))
+            adj_str = ", ".join(str(n) for n in neighbors)
+            if color > 0:
+                color_name = COLOR_NAMES[color - 1] if color <= len(COLOR_NAMES) else str(color)
+                prefix = "*" if node in self.initial_coloring else " "
+                lines.append(f"  {prefix}{node:2d}: [{color_name:>7s}]  adj: {adj_str}")
+            else:
+                lines.append(f"   {node:2d}: [       ]  adj: {adj_str}")
+
+        colored = sum(1 for n in range(1, self.num_nodes + 1) if self.coloring.get(n, 0) > 0)
+        lines.append(f"\nColored: {colored}/{self.num_nodes}")
+
+        return "\n".join(lines)
+
+    def get_rules(self) -> str:
+        return (
+            f"GRAPH COLORING ({self.num_nodes} nodes, {self.num_colors} colors)\n"
+            "Assign a color to each node in the graph.\n"
+            "No two connected (adjacent) nodes may share the same color.\n"
+            "Pre-colored nodes (marked with *) cannot be changed."
+        )
+
+    def get_commands(self) -> str:
+        return (
+            "Commands:\n"
+            f"  place <node> <color>  - Color a node (1-{self.num_colors})\n"
+            "  clear <node>          - Remove color from a node\n"
+            "  hint                  - Get a hint\n"
+            "  check                 - Check if solved\n"
+            "  show                  - Show current state\n"
+            "  menu                  - Return to menu"
+        )

chuk_puzzles_gym/games/nqueens/__init__.py

@@ -0,0 +1,6 @@
+"""N-Queens puzzle game."""
+
+from .config import NQueensConfig
+from .game import NQueensGame
+
+__all__ = ["NQueensGame", "NQueensConfig"]

chuk_puzzles_gym/games/nqueens/config.py

@@ -0,0 +1,23 @@
+"""Configuration for N-Queens puzzle game."""
+
+from pydantic import BaseModel, Field
+
+from ...models import DifficultyLevel
+
+
+class NQueensConfig(BaseModel):
+    """Configuration for an N-Queens puzzle."""
+
+    difficulty: DifficultyLevel = Field(default=DifficultyLevel.EASY)
+    size: int = Field(ge=4, le=20, description="Board size (N)")
+    pre_placed: int = Field(ge=0, description="Number of pre-placed queens as hints")
+
+    @classmethod
+    def from_difficulty(cls, difficulty: DifficultyLevel) -> "NQueensConfig":
+        """Create config from difficulty level."""
+        config_map = {
+            DifficultyLevel.EASY: {"size": 6, "pre_placed": 3},
+            DifficultyLevel.MEDIUM: {"size": 8, "pre_placed": 2},
+            DifficultyLevel.HARD: {"size": 12, "pre_placed": 1},
+        }
+        return cls(difficulty=difficulty, **config_map[difficulty])

chuk_puzzles_gym/games/nqueens/game.py

@@ -0,0 +1,316 @@
+"""N-Queens puzzle game implementation."""
+
+from typing import Any
+
+from ...models import DifficultyLevel, DifficultyProfile, MoveResult
+from .._base import PuzzleGame
+from .config import NQueensConfig
+
+
+class NQueensGame(PuzzleGame):
+    """N-Queens puzzle - place N queens on an NxN board with no conflicts.
+
+    Rules:
+    - Place exactly N queens on an NxN chessboard
+    - No two queens may share the same row, column, or diagonal
+    - Some queens may be pre-placed as hints
+    """
+
+    def __init__(self, difficulty: str = "easy", seed: int | None = None, **kwargs):
+        super().__init__(difficulty, seed, **kwargs)
+        self.config = NQueensConfig.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._queen_cols: list[int] = []  # Solution: queen_cols[row] = col
+
+    @property
+    def name(self) -> str:
+        return "N-Queens"
+
+    @property
+    def description(self) -> str:
+        return f"Place {self.size} queens on a {self.size}x{self.size} board with no conflicts"
+
+    @property
+    def constraint_types(self) -> list[str]:
+        return ["placement", "attack_avoidance", "all_different", "diagonal_constraint"]
+
+    @property
+    def business_analogies(self) -> list[str]:
+        return ["non_conflicting_placement", "resource_allocation", "antenna_placement"]
+
+    @property
+    def complexity_profile(self) -> dict[str, str]:
+        return {
+            "reasoning_type": "deductive",
+            "search_space": "exponential",
+            "constraint_density": "moderate",
+        }
+
+    @property
+    def complexity_metrics(self) -> dict[str, int | float]:
+        queens_placed = sum(1 for row in self.grid for cell in row if cell == 1)
+        return {
+            "variable_count": self.size,
+            "constraint_count": self.size * 3,  # row + col + diag constraints
+            "domain_size": self.size,
+            "branching_factor": self.size / 2.0,
+            "empty_cells": self.size - queens_placed,
+        }
+
+    @property
+    def difficulty_profile(self) -> DifficultyProfile:
+        profiles = {
+            DifficultyLevel.EASY: DifficultyProfile(
+                logic_depth=2, branching_factor=3.0, state_observability=1.0, constraint_density=0.5
+            ),
+            DifficultyLevel.MEDIUM: DifficultyProfile(
+                logic_depth=4, branching_factor=4.0, state_observability=1.0, constraint_density=0.4
+            ),
+            DifficultyLevel.HARD: DifficultyProfile(
+                logic_depth=6, branching_factor=6.0, state_observability=1.0, constraint_density=0.3
+            ),
+        }
+        return profiles[self.difficulty]
+
+    @property
+    def optimal_steps(self) -> int | None:
+        """Number of queens left to place."""
+        initial_queens = sum(1 for row in self.initial_grid for cell in row if cell == 1)
+        return self.size - initial_queens
+
+    def _solve_nqueens(self) -> list[int] | None:
+        """Find a valid N-Queens solution using randomized backtracking.
+
+        Returns:
+            List of column positions for each row, or None if no solution.
+        """
+        n = self.size
+        result: list[int] = [-1] * n
+        used_cols: set[int] = set()
+        diag1: set[int] = set()  # row - col
+        diag2: set[int] = set()  # row + col
+
+        # Create shuffled column order for each row (for randomization)
+        col_orders = []
+        for _ in range(n):
+            cols = list(range(n))
+            self._rng.shuffle(cols)
+            col_orders.append(cols)
+
+        def backtrack(row: int) -> bool:
+            if row == n:
+                return True
+            for col in col_orders[row]:
+                if col in used_cols:
+                    continue
+                d1 = row - col
+                d2 = row + col
+                if d1 in diag1 or d2 in diag2:
+                    continue
+                result[row] = col
+                used_cols.add(col)
+                diag1.add(d1)
+                diag2.add(d2)
+                if backtrack(row + 1):
+                    return True
+                used_cols.discard(col)
+                diag1.discard(d1)
+                diag2.discard(d2)
+            return False
+
+        if backtrack(0):
+            return result
+        return None
+
+    def _has_conflicts(self) -> bool:
+        """Check if current grid has any queen conflicts."""
+        n = self.size
+        queens = []
+        for r in range(n):
+            for c in range(n):
+                if self.grid[r][c] == 1:
+                    queens.append((r, c))
+
+        for i in range(len(queens)):
+            for j in range(i + 1, len(queens)):
+                r1, c1 = queens[i]
+                r2, c2 = queens[j]
+                if r1 == r2 or c1 == c2 or abs(r1 - r2) == abs(c1 - c2):
+                    return True
+        return False
+
+    async def generate_puzzle(self) -> None:
+        """Generate an N-Queens puzzle."""
+        n = self.size
+        queen_cols = self._solve_nqueens()
+        if queen_cols is None:
+            raise RuntimeError(f"Failed to find N-Queens solution for N={n}")
+
+        self._queen_cols = queen_cols
+
+        # Build solution grid
+        self.solution = [[0] * n for _ in range(n)]
+        for r in range(n):
+            self.solution[r][queen_cols[r]] = 1
+
+        # Pre-place some queens as hints
+        self.grid = [[0] * n for _ in range(n)]
+        rows = list(range(n))
+        self._rng.shuffle(rows)
+        for r in rows[: self.config.pre_placed]:
+            self.grid[r][queen_cols[r]] = 1
+
+        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 or removing a queen.
+
+        Args:
+            row: 1-indexed row
+            col: 1-indexed column
+            num: 1 to place queen, 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] == 1 and num == 0:
+            self.record_move((row, col), False)
+            return MoveResult(success=False, message="Cannot remove a pre-placed queen.")
+
+        if num == 0:
+            if self.grid[r][c] == 0:
+                self.record_move((row, col), False)
+                return MoveResult(success=False, message="No queen at that position.")
+            self.grid[r][c] = 0
+            self.record_move((row, col), True)
+            return MoveResult(success=True, message=f"Removed queen from ({row}, {col}).", state_changed=True)
+
+        if num != 1:
+            self.record_move((row, col), False)
+            return MoveResult(success=False, message="Use 1 to place a queen or 0 to clear.")
+
+        if self.grid[r][c] == 1:
+            self.record_move((row, col), False)
+            return MoveResult(success=False, message="A queen is already at that position.")
+
+        # Check conflicts with existing queens
+        for rr in range(n):
+            for cc in range(n):
+                if self.grid[rr][cc] == 1:
+                    if rr == r:
+                        self.record_move((row, col), False)
+                        return MoveResult(
+                            success=False,
+                            message=f"Conflicts with queen at ({rr + 1}, {cc + 1}) - same row.",
+                        )
+                    if cc == c:
+                        self.record_move((row, col), False)
+                        return MoveResult(
+                            success=False,
+                            message=f"Conflicts with queen at ({rr + 1}, {cc + 1}) - same column.",
+                        )
+                    if abs(rr - r) == abs(cc - c):
+                        self.record_move((row, col), False)
+                        return MoveResult(
+                            success=False,
+                            message=f"Conflicts with queen at ({rr + 1}, {cc + 1}) - same diagonal.",
+                        )
+
+        self.grid[r][c] = 1
+        self.record_move((row, col), True)
+        return MoveResult(success=True, message=f"Placed queen at ({row}, {col}).", state_changed=True)
+
+    def is_complete(self) -> bool:
+        """Check if N queens are placed with no conflicts."""
+        n = self.size
+        queens = []
+        for r in range(n):
+            for c in range(n):
+                if self.grid[r][c] == 1:
+                    queens.append((r, c))
+
+        if len(queens) != n:
+            return False
+
+        # Verify no conflicts
+        cols = set()
+        diag1 = set()
+        diag2 = set()
+        for r, c in queens:
+            if c in cols or (r - c) in diag1 or (r + c) in diag2:
+                return False
+            cols.add(c)
+            diag1.add(r - c)
+            diag2.add(r + c)
+
+        return True
+
+    async def get_hint(self) -> tuple[Any, str] | None:
+        """Suggest the next queen to place from the solution."""
+        if not self.can_use_hint():
+            return None
+        n = self.size
+        for r in range(n):
+            c = self._queen_cols[r]
+            if self.grid[r][c] == 0:
+                return (
+                    (r + 1, c + 1, 1),
+                    f"Try placing a queen at row {r + 1}, column {c + 1}.",
+                )
+        return None
+
+    def render_grid(self) -> str:
+        """Render the chessboard with queens."""
+        n = self.size
+        lines = []
+
+        # Column headers
+        header = "    " + "  ".join(str(c + 1) for c in range(n))
+        lines.append(header)
+        lines.append("   " + "+" + "---" * n + "+")
+
+        for r in range(n):
+            cells = []
+            for c in range(n):
+                if self.grid[r][c] == 1:
+                    if self.initial_grid[r][c] == 1:
+                        cells.append("Q")  # Pre-placed queen
+                    else:
+                        cells.append("Q")  # Player-placed queen
+                else:
+                    cells.append(".")
+            line = f" {r + 1} | " + "  ".join(cells) + " |"
+            lines.append(line)
+
+        lines.append("   " + "+" + "---" * n + "+")
+        queens_placed = sum(1 for row in self.grid for cell in row if cell == 1)
+        lines.append(f"Queens: {queens_placed}/{n}")
+
+        return "\n".join(lines)
+
+    def get_rules(self) -> str:
+        return (
+            f"N-QUEENS ({self.size}x{self.size})\n"
+            f"Place {self.size} queens on the board.\n"
+            "No two queens may share the same row, column, or diagonal.\n"
+            "Pre-placed queens (Q) cannot be removed."
+        )
+
+    def get_commands(self) -> str:
+        return (
+            "Commands:\n"
+            "  place <row> <col> 1  - Place a queen\n"
+            "  clear <row> <col>    - Remove a queen\n"
+            "  hint                 - Get a hint\n"
+            "  check                - Check if solved\n"
+            "  show                 - Show current state\n"
+            "  menu                 - Return to menu"
+        )

chuk_puzzles_gym/games/numberlink/__init__.py

@@ -0,0 +1,6 @@
+"""Numberlink (Flow) puzzle game."""
+
+from .config import NumberlinkConfig
+from .game import NumberlinkGame
+
+__all__ = ["NumberlinkGame", "NumberlinkConfig"]