Multi-game puzzle server for telnet - LLMs with MCP solvers welcome!

These details have not been verified by PyPI

Project links

Project description

Puzzle Arcade Server

A multi-game puzzle server and LLM reasoning benchmark arcade hosting 24 different logic puzzle types, built using the chuk-protocol-server framework.

Perfect for:

🤖 LLM Agent Testing - Benchmark reasoning capabilities across constraint types
🎯 CP-SAT Education - Learn constraint programming through progressive puzzles
💼 Business Demos - Map puzzle patterns to real scheduling, optimization, and allocation problems
🔧 MCP Tool Integration - Showcase CHUK + constraint solver workflows

Each puzzle demonstrates specific constraint patterns (AllDifferent, Optimization, Connectivity, Boolean SAT, etc.) and maps to business use cases (scheduling, resource allocation, routing, etc.).

Try It Now

A live demo server is running on Fly.io. Try it instantly:

# Connect via Telnet (IPv6)
telnet 2a09:8280:1::b8:79f4:0 8023

# WebSocket connections
ws://puzzle-arcade-server.fly.dev:8025/ws

Once connected, type help to see available games, or sudoku easy to start playing!

Features

24 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
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
- Compact output optimized for LLM tool integration
Multiple transport protocols:
- Telnet (port 8023) - Classic telnet protocol
- TCP (port 8024) - Raw TCP connections
- WebSocket (port 8025) - Modern WebSocket protocol
- WebSocket-Telnet (port 8026) - WebSocket with telnet negotiation
Interactive menu-driven interface with game selection
Hint system for when you're stuck
Solution checker and auto-solver for all games
Clean ASCII art grids - perfectly aligned for easy parsing
Comprehensive test suite (716 tests, 94% coverage)
Modern Python best practices:
- Pydantic v2 native - All models use ConfigDict for type safety
- Async native - Full async/await support throughout
- Type-safe - No dict["key"] patterns, only typed models
- Enum-based - No magic strings, proper enum constants
Modern Python packaging with pyproject.toml
Docker and Fly.io deployment ready

Available Games

Classic Logic Puzzles

Game	Grid Size	Constraint Types	Status
Sudoku	9×9	AllDifferent (rows, cols, boxes)	✅ Complete
KenKen	4×4 to 6×6	Arithmetic cages + AllDifferent	✅ Complete
Kakuro	5×5 to 8×8	Sum constraints + AllDifferent	✅ Complete
Binary Puzzle	6×6 to 10×10	Adjacency limits + Equal counts	✅ Complete
Futoshiki	4×4 to 6×6	Inequalities + AllDifferent	✅ Complete
Nonogram	5×5 to 10×10	Line sum constraints + Blocks	✅ Complete
Logic Grid	Variable	Category associations + Logic	✅ Complete

Advanced CP-SAT Puzzles

Game	Grid Size	Constraint Types	Status
Killer Sudoku	9×9	Linear constraints + AllDifferent + Cages	✅ Complete
Lights Out	5×5 to 7×7	Boolean XOR constraints (SAT)	✅ Complete
Mastermind	4-6 pegs	Deduction + Feedback constraints	✅ Complete
Slitherlink	5×5 to 10×10	Global loop + Edge constraints	✅ Complete
Bridges	7×7 to 11×11	Connectivity + Degree constraints	✅ Complete
Hitori	5×5 to 9×9	AllDifferent + Adjacency + Connectivity	✅ Complete
Shikaku	6×6 to 10×10	Area partitioning + Rectangle covering	✅ Complete

Specialized Constraint Puzzles

Game	Grid Size	Constraint Types	Status
Hidato	5×5 to 9×9	Sequential adjacency + Hamiltonian path	✅ Complete
Tents and Trees	6×6 to 10×10	Bipartite matching + Adjacency avoidance	✅ Complete
Fillomino	6×6 to 10×10	Region growth + Self-referential constraints	✅ Complete
Star Battle	6×6 to 10×10	Multi-region placement + Adjacency avoidance	✅ Complete
Sokoban	6×6 to 10×10	Spatial planning + Irreversible actions (optimization)	✅ Complete

Optimization Challenges

Game	Problem Size	Constraint Types	Status
Knapsack	5-12 items	Value maximization + Capacity constraint	✅ Complete
Task Scheduler	4-8 tasks	Makespan minimization + Dependencies + Resources	✅ Complete

Advanced Reasoning Puzzles

Game	Grid Size	Constraint Types	Status
Nurikabe	6×6 to 10×10	Connectivity + Island sizes + No 2×2 blocks	✅ Complete
Einstein's Puzzle	5 houses × 5 attributes	Multi-attribute deduction + Logic chains	✅ Complete
Minesweeper	6×6 to 10×10	Probabilistic reasoning + Safe deduction	✅ Complete

Solver Profiles & Business Mapping

Each game includes metadata for constraint types, business analogies, and complexity profiles, making it easy to:

Select puzzles by constraint pattern - Need to demonstrate Boolean SAT? → Lights Out
Map to business use cases - Task Scheduler → Sprint Planning, Knapsack → Portfolio Selection
Benchmark LLM reasoning - Compare model performance across different constraint densities

Example: Query Games by Profile

from puzzle_arcade_server.games import AVAILABLE_GAMES

# Find all optimization problems
optimization_games = [
    name for name, game_class in AVAILABLE_GAMES.items()
    if "optimization" in game_class().constraint_types
]
# → ['knapsack', 'scheduler']

# Find games that model resource allocation
resource_games = [
    name for name, game_class in AVAILABLE_GAMES.items()
    if "resource_allocation" in game_class().business_analogies
]
# → ['scheduler', 'knapsack']

Quick Reference: Constraint Types to Business Problems

Constraint Pattern	Puzzle Examples	Business Use Cases
Optimization	Knapsack, Scheduler	Portfolio selection, Sprint planning, Budget allocation
Precedence	Scheduler	Project dependencies, Workflow sequencing
Sequential Adjacency	Hidato	Path planning, Route sequencing, Tour optimization
Hamiltonian Path	Hidato	Traveling salesman, Circuit design
Bipartite Matching	Tents and Trees	Job assignment, Resource pairing
Region Growth	Fillomino	Territory expansion, Cluster formation
Spatial Planning	Sokoban	Warehouse logistics, Movement planning
Connectivity	Nurikabe, Slitherlink	Network design, Routing, Zone planning
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

See CURRICULUM.md for a structured learning path through constraint patterns See DEMOS.md for complete CHUK + MCP solver integration examples

Quick Start

Prerequisites

Python 3.11 or higher
UV (recommended) or pip

Installation

From Source (Development)

Using UV (Recommended)

# Clone the repository
git clone https://github.com/chrishayuk/puzzle-arcade-server.git
cd puzzle-arcade-server

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install development dependencies
make dev-install

# Run the server
make run

Using pip

# Clone the repository
git clone https://github.com/chrishayuk/puzzle-arcade-server.git
cd puzzle-arcade-server

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run the server
PYTHONPATH=. uv run --with chuk-protocol-server chuk-protocol-server server-launcher -c config.yaml

Using Make (All Commands)

# See all available commands
make help

# Development workflow
make dev-install      # Install dev dependencies
make run              # Run the server
make test             # Run tests
make test-cov         # Run tests with coverage report
make check            # Run linting and type checking
make format           # Format code with ruff
make security         # Run security checks

# Docker workflow
make docker-build     # Build Docker image
make docker-run       # Run in Docker container

# Examples
make example-telnet              # Browse games via telnet
make example-telnet-sudoku       # Sudoku demo
make example-telnet-kenken       # KenKen demo
make example-ws                  # WebSocket tour
make example-ws-interactive      # Interactive WebSocket mode

# Deployment
make fly-deploy       # Deploy to Fly.io
make fly-logs         # View Fly.io logs

Docker Setup

Build and run with Docker:

# Using Make
make docker-run

# Or manually
docker build -t puzzle-arcade-server .
docker run -p 8023:8023 -p 8024:8024 -p 8025:8025 -p 8026:8026 puzzle-arcade-server

Connecting to the Server

Local Development

Via Telnet:

telnet localhost 8023

Via Netcat (TCP):

nc localhost 8024

Via WebSocket:

ws://localhost:8025/ws
ws://localhost:8026/ws

Game Menu

When you connect, you'll see the main menu:

==================================================
       WELCOME TO THE PUZZLE ARCADE!
==================================================

CLASSIC LOGIC PUZZLES:
  1) Sudoku          - Classic logic puzzle - fill 9x9 grid with digits 1-9
  2) KenKen          - Arithmetic cage puzzle - combine math and logic
  3) Kakuro          - Crossword math puzzle - fill runs with unique digits that sum to clues
  4) Binary Puzzle   - Fill grid with 0s and 1s - no three in a row, equal counts
  5) Futoshiki       - Inequality number puzzle - fill grid with constraints
  6) Nonogram        - Picture logic puzzle - reveal image from number clues
  7) Logic Grid      - Deductive reasoning puzzle - match attributes using logic

ADVANCED CP-SAT PUZZLES:
  8) Killer Sudoku   - Sudoku + Kakuro - regions must sum to targets
  9) Lights Out      - Toggle lights to turn all off - XOR constraint puzzle
 10) Mastermind      - Code-breaking with logical deduction and feedback
 11) Slitherlink     - Draw a single loop - numbers show edge counts
 12) Bridges         - Connect islands with bridges - satisfy all numbers
 13) Hitori          - Shade cells to eliminate duplicates - no adjacent shading
 14) Shikaku         - Divide grid into rectangles matching areas

SPECIALIZED CONSTRAINT PUZZLES:
 15) Hidato          - Sequential path puzzle - connect numbers adjacently
 16) Tents           - Place tents next to trees - bipartite matching puzzle
 17) Fillomino       - Fill regions with numbers matching region size
 18) Star Battle     - Place stars avoiding adjacency - multi-region placement
 19) Sokoban         - Push boxes to targets - spatial planning puzzle

OPTIMIZATION CHALLENGES:
 20) Knapsack        - Maximize value within capacity constraints
 21) Task Scheduler  - Minimize makespan with dependencies and resources

ADVANCED REASONING PUZZLES:
 22) Nurikabe        - Island and sea puzzle - connectivity constraints
 23) Einstein's Puzzle - Who owns the fish? Multi-attribute deduction
 24) Minesweeper     - Find all mines using logical deduction

Commands:
  <number>  - Select game by number
  <name>    - Select game by name (e.g., 'sudoku')
  help      - Show this menu again
  quit      - Exit the server
==================================================

Agent-Friendly Mode

The server includes a special agent mode designed for AI tools and LLM integration:

Enabling Agent Mode

> mode agent
Output mode set to: agent

Agent Mode Features

Structured Output - Grid data is wrapped with clear start/end markers:

---GAME-START---
GAME: Sudoku
DIFFICULTY: medium
MOVES: 3
---GRID-START---
  | 1 2 3 | 4 5 6 | 7 8 9 |
  -------------------------
1 | . . 3 | . 2 . | 6 . . |
...
---GRID-END---
---GAME-END---

Benefits for AI Agents:

Easy parsing with regex: ---GRID-START---(.*?)---GRID-END---
Consistent metadata format (GAME, DIFFICULTY, MOVES)
No decorative text or banners to filter out
Minimal token usage compared to normal mode

Switching Modes:

mode normal - Human-friendly output (default)
mode agent - Machine-parseable structured output
mode compact - Reserved for future use

Universal Game Commands

All games support these commands:

Starting and Managing Games

<number> [difficulty] - Select game by number (e.g., 1 medium)
<name> [difficulty] - Select game by name (e.g., sudoku hard)
show - Display the current grid
mode <normal|agent|compact> - Set output mode
help - Show game-specific commands and rules
menu - Return to main menu
quit - Exit the server

Playing Games

place <row> <col> <value> - Place a number/value on the grid
- Example: place 1 5 7 (places 7 at row 1, column 5)
clear <row> <col> - Clear a cell you've filled
hint - Get a hint for the next move
check - Check your progress
solve - Show the solution (ends current game)

Special Commands (Game-Specific)

Logic Grid: connect and exclude commands for associations
See in-game help for game-specific commands

Example Gameplay Sessions

Sudoku

> sudoku medium

==================================================
SUDOKU - MEDIUM MODE
==================================================
Fill the grid so that every row, column, and 3x3 box
contains the digits 1-9 without repetition.

Type 'help' for commands or 'hint' for a clue.
==================================================

  | 1 2 3 | 4 5 6 | 7 8 9 |
  -------------------------
1 | . . 3 | . 2 . | 6 . . |
2 | 9 . . | 3 . 5 | . . 1 |
3 | . . 1 | 8 . 6 | 4 . . |
  -------------------------
4 | . . 8 | 1 . 2 | 9 . . |
5 | 7 . . | . . . | . . 8 |
6 | . . 6 | 7 . 8 | 2 . . |
  -------------------------
7 | . . 2 | 6 . 9 | 5 . . |
8 | 8 . . | 2 . 3 | . . 9 |
9 | . . 5 | . 1 . | 3 . . |
  -------------------------
Moves made: 0
==================================================

> hint
Hint: Try placing 4 at row 1, column 1

> place 1 1 4
Number placed successfully!

> check
Puzzle not yet complete. Keep going!
Moves made: 1

KenKen

> kenken easy

==================================================
KENKEN - EASY MODE
==================================================
KENKEN RULES:
- Fill 4x4 grid with 1-4
- No repeats in rows or columns
- Satisfy cage arithmetic constraints
- Operations: + - * /
==================================================

  | 1  | 2  | 3  | 4  |
  +----+----+----+----+
1 | .8+| .  | .3 | .2 |
  +----+----+----+----+
2 | .  | .6+| .  | .3-|
  +----+----+----+----+
3 | .2 | .6+| .8+| .  |
  +----+----+----+----+
4 | .  | .  | .  | .  |
  +----+----+----+----+

Cages:
  8+: (1,1), (1,2), (2,1)
  3: (1,3)
  2: (1,4)
  ...

> place 1 3 3
Number placed successfully!

Architecture

This server is built on the chuk-protocol-server framework, which provides:

Multiple transport protocol support (Telnet, TCP, WebSocket, WS-Telnet)
Telnet protocol negotiation (IAC, WILL, WONT, DO, DONT)
WebSocket handling with ping/pong keepalive
Connection management and monitoring
Asynchronous I/O with Python asyncio

Game Architecture

All games extend the PuzzleGame abstract base class:

class PuzzleGame(ABC):
    @property
    @abstractmethod
    def name(self) -> str: ...

    @property
    @abstractmethod
    def description(self) -> str: ...

    @abstractmethod
    def generate_puzzle(self) -> None: ...

    @abstractmethod
    def validate_move(self, *args) -> tuple[bool, str]: ...

    @abstractmethod
    def is_complete(self) -> bool: ...

    @abstractmethod
    def render_grid(self) -> str: ...

    def get_hint(self) -> tuple[Any, str] | None: ...
    def get_rules(self) -> str: ...
    def get_commands(self) -> str: ...

Handler Architecture

The ArcadeHandler class manages:

Menu-driven game selection
Command parsing and routing
Grid display with proper formatting
Game state management per connection
Multi-game support

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/chrishayuk/puzzle-arcade-server.git
cd puzzle-arcade-server

# Install development dependencies (with UV)
make dev-install

# Or with pip
pip install -e ".[dev]"

Testing

The project has comprehensive test coverage (95%, 716 tests):

# Run all tests
make test

# Run tests with coverage report
make test-cov

# Run tests in watch mode
make test-watch

# View coverage report in browser
make serve-coverage

Coverage by File

src/puzzle_arcade_server/base/puzzle_game.py       92%
src/puzzle_arcade_server/models/base.py           100%  ✨
src/puzzle_arcade_server/models/config.py         100%
src/puzzle_arcade_server/models/enums.py          100%
src/puzzle_arcade_server/models/games.py          100%
src/puzzle_arcade_server/games/__init__.py        100%
src/puzzle_arcade_server/games/lights_out.py      100%
src/puzzle_arcade_server/games/scheduler.py       100%  ✨
src/puzzle_arcade_server/games/binary.py           98%
src/puzzle_arcade_server/games/einstein.py         98%
src/puzzle_arcade_server/games/knapsack.py         98%
src/puzzle_arcade_server/games/mastermind.py       98%
src/puzzle_arcade_server/games/futoshiki.py        98%
src/puzzle_arcade_server/games/slitherlink.py      98%
src/puzzle_arcade_server/games/kakuro.py           95%
src/puzzle_arcade_server/games/nonogram.py         93%
src/puzzle_arcade_server/games/minesweeper.py      92%
src/puzzle_arcade_server/games/sudoku.py           92%
src/puzzle_arcade_server/games/hitori.py           95%
src/puzzle_arcade_server/games/bridges.py          93%
src/puzzle_arcade_server/games/shikaku.py          93%
src/puzzle_arcade_server/games/nurikabe.py         92%
src/puzzle_arcade_server/games/kenken.py           91%
src/puzzle_arcade_server/games/logic_grid.py       91%
src/puzzle_arcade_server/games/killer_sudoku.py    90%
------------------------------------------------------
TOTAL                                               95%  🎯

All files now meet the 90%+ coverage threshold! ✅

Code Quality

The project follows modern Python best practices with a 9.8/10 compliance score:

Tooling

Ruff: Fast linter and formatter (replaces black + flake8)
MyPy: Static type checking
Pytest: Testing framework with async support
Bandit: Security vulnerability scanning

Code Standards

✅ Pydantic v2 Native (10/10) - All models use ConfigDict, zero deprecation warnings
✅ Async Native (9.5/10) - All I/O operations use async/await properly
✅ Type-Safe (10/10) - No dict["key"] patterns, only typed Pydantic models
✅ No Magic Strings (10/10) - All constants use enums or typed constants
✅ Test Coverage (10/10) - 95% overall, all files ≥90%

Quality Metrics

530 tests - All passing ✅
95% coverage - Exceeds 90% threshold ✅
Zero linting errors - Clean codebase ✅
Full type safety - MyPy passes ✅
3,700+ statements - Well-tested and documented

# Run all checks (lint + typecheck + test + security)
make check

# Run linter
make lint

# Format code
make format

# Type checking
make typecheck

# Security scanning
make security

Running Example Clients

# Telnet client examples
make example-telnet              # Browse all games
make example-telnet-sudoku       # Sudoku demo
make example-telnet-kenken       # KenKen demo
make example-telnet-interactive  # Interactive mode

# WebSocket client examples
make example-ws                  # Tour all games
make example-ws-sudoku           # Sudoku demo
make example-ws-binary           # Binary puzzle demo
make example-ws-solve            # Solve with hints
make example-ws-interactive      # Interactive mode

CI/CD

The project includes GitHub Actions workflows:

test.yml: Runs tests on Ubuntu, Windows, macOS with Python 3.11, 3.12, 3.13
publish.yml: Publishes to PyPI on release
release.yml: Creates GitHub releases
fly-deploy.yml: Auto-deploys to Fly.io on main branch push

Coverage threshold is set to 90% - builds fail if coverage drops below this.

Deployment to Fly.io

Using Make (Recommended)

# Deploy to Fly.io
make fly-deploy

# Check status
make fly-status

# View logs
make fly-logs

Manual Deployment

Install the Fly CLI: https://fly.io/docs/hands-on/install-flyctl/
Login to Fly:

fly auth login

Create and deploy the app:

# First deployment (creates the app)
fly launch --config fly.toml --now

# Subsequent deployments
fly deploy

Important: Allocate a public IPv6 address for TCP services:

# Allocate IPv6 (free)
fly ips allocate-v6

# Verify IP is allocated
fly ips list

Check the status:

fly status

View logs:

fly logs

Connect to your Puzzle Arcade server:

# Get your app's IPv6 address
fly ips list

# Connect via telnet using IPv6 (free tier)
telnet <your-ipv6> 8023

# WebSocket connections work with hostname
# ws://<your-app>.fly.dev:8025/ws

Note: TCP services (Telnet, raw TCP) require a public IP address on Fly.io. We use IPv6 which is free. IPv4 costs $2/month and is not needed for most users.

Project Structure

puzzle-arcade-server/
├── src/
│   └── puzzle_arcade_server/
│       ├── __init__.py           # Package initialization
│       ├── server.py             # Main arcade handler (354 lines)
│       ├── base/
│       │   ├── __init__.py       # Base package
│       │   └── puzzle_game.py    # Abstract base class (35 lines)
│       ├── games/
│       │   ├── __init__.py       # Game registry (AVAILABLE_GAMES)
│       │   ├── sudoku.py         # Sudoku (9×9, 121 lines, 92% coverage)
│       │   ├── kenken.py         # KenKen (4×4-6×6, 216 lines, 91% coverage)
│       │   ├── kakuro.py         # Kakuro (5×5-8×8, 134 lines, 95% coverage)
│       │   ├── binary.py         # Binary (6×6-10×10, 154 lines, 99% coverage)
│       │   ├── futoshiki.py      # Futoshiki (4×4-6×6, 160 lines, 98% coverage)
│       │   ├── nonogram.py       # Nonogram (5×5-10×10, 116 lines, 93% coverage)
│       │   ├── logic_grid.py     # Logic Grid (117 lines, 90% coverage)
│       │   ├── killer_sudoku.py  # Killer Sudoku (9×9, 404 lines, 93% coverage)
│       │   ├── lights_out.py     # Lights Out (5×5-7×7, 204 lines, 94% coverage)
│       │   ├── mastermind.py     # Mastermind (4-6 pegs, 258 lines, 92% coverage)
│       │   ├── slitherlink.py    # Slitherlink (5×5-10×10, 343 lines, 91% coverage)
│       │   ├── bridges.py        # Bridges (7×7-11×11, 337 lines, 93% coverage)
│       │   ├── hitori.py         # Hitori (5×5-9×9, 329 lines, 95% coverage)
│       │   ├── shikaku.py        # Shikaku (6×6-10×10, 306 lines, 93% coverage)
│       │   ├── knapsack.py       # Knapsack (5-12 items, 267 lines)
│       │   ├── scheduler.py      # Task Scheduler (4-8 tasks, 381 lines)
│       │   ├── nurikabe.py       # Nurikabe (6×6-10×10, 383 lines)
│       │   ├── einstein.py       # Einstein's Puzzle (5 houses, 290 lines)
│       │   └── minesweeper.py    # Minesweeper (6×6-10×10, 293 lines)
│       └── utils/
│           └── __init__.py       # Utility functions
├── tests/
│   ├── test_puzzle_game.py       # Base class tests (4 tests)
│   ├── test_sudoku_game.py       # Sudoku tests (11 tests)
│   ├── test_kenken_game.py       # KenKen tests (25 tests)
│   ├── test_kakuro_game.py       # Kakuro tests (12 tests)
│   ├── test_binary_game.py       # Binary tests (27 tests)
│   ├── test_futoshiki_game.py    # Futoshiki tests (25 tests)
│   ├── test_nonogram_game.py     # Nonogram tests (12 tests)
│   ├── test_logic_grid_game.py   # Logic Grid tests (13 tests)
│   ├── test_killer_sudoku.py     # Killer Sudoku tests (27 tests)
│   ├── test_lights_out.py        # Lights Out tests (23 tests)
│   ├── test_mastermind.py        # Mastermind tests (31 tests)
│   ├── test_slitherlink.py       # Slitherlink tests (33 tests)
│   ├── test_bridges.py           # Bridges tests (24 tests)
│   ├── test_hitori.py            # Hitori tests (29 tests)
│   ├── test_shikaku.py           # Shikaku tests (27 tests)
│   ├── test_knapsack.py          # Knapsack tests (30+ tests)
│   ├── test_scheduler.py         # Scheduler tests (35+ tests)
│   ├── test_nurikabe.py          # Nurikabe tests (40+ tests)
│   ├── test_einstein.py          # Einstein's Puzzle tests (35+ tests)
│   └── test_minesweeper.py       # Minesweeper tests (40+ tests)
├── examples/
│   ├── simple_client.py          # Telnet client example
│   ├── websocket_client.py       # WebSocket client example
│   └── README.md                 # Example usage guide
├── .github/
│   └── workflows/
│       ├── test.yml              # Multi-platform CI testing
│       ├── publish.yml           # PyPI publishing
│       ├── release.yml           # GitHub releases
│       └── fly-deploy.yml        # Fly.io deployment
├── pyproject.toml                # Modern Python project config
├── config.yaml                   # Multi-transport server configuration
├── Dockerfile                    # Docker build instructions
├── fly.toml                      # Fly.io deployment config
├── Makefile                      # Development commands (50+ targets)
├── MANIFEST.in                   # Package distribution files
└── README.md                     # This file

Key Statistics

Total Lines of Code: 3,700+ statements in src/
Test Coverage: 95% overall (716 tests, all passing)
Code Quality Score: 9.8/10 (near perfect compliance)
Games Implemented: 24 complete puzzle types
- 7 Classic Logic Puzzles
- 7 Advanced CP-SAT Puzzles
- 5 Specialized Constraint Puzzles
- 2 Optimization Challenges
- 3 Advanced Reasoning Puzzles
Supported Transports: 4 (Telnet, TCP, WebSocket, WS-Telnet)
Agent-Friendly Mode: Structured output for AI tools
Make Targets: 50+ development commands
All Files: ≥90% test coverage ✅

Use Cases

1. LLM Reasoning Demonstration

Perfect for demonstrating LLM reasoning capabilities:

LLM connects via telnet: telnet localhost 8023
Selects a puzzle: sudoku hard
Receives puzzle in clean ASCII format
Analyzes constraints and generates solution
Submits moves: place 1 5 7
Server validates each move
Puzzle solved! Proof of reasoning capability

2. Constraint Solver Testing

Test the generality of constraint solvers (like MCP solvers):

Different puzzle types → Same underlying solver
Clean ASCII output → Easy for solver parsing
Simple interface → Focus on solving, not UI
Pure validation → Server validates, doesn't solve

3. Educational Tool

Learn about constraint satisfaction problems:

24 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)
- Loop/Edge constraints (Slitherlink)
- Deduction constraints (Mastermind, Logic Grid, Einstein's Puzzle)
- Optimization objectives (Knapsack, Task Scheduler)
- Temporal reasoning (Task Scheduler)
- Connectivity constraints (Nurikabe, Slitherlink)
- Probabilistic reasoning (Minesweeper)
- And more!
Well-documented code showing puzzle generation algorithms
Comprehensive tests (530 tests, 95% coverage) demonstrating validation
Production-ready - 9.8/10 code quality score
Type-safe - Full Pydantic v2 and MyPy compliance
Clean architecture for adding new puzzles

Adding New Puzzle Games

Create a new game file in src/puzzle_arcade_server/games/:

from ..base.puzzle_game import PuzzleGame

class MyPuzzleGame(PuzzleGame):
    @property
    def name(self) -> str:
        return "My Puzzle"

    @property
    def description(self) -> str:
        return "A cool puzzle game"

    def generate_puzzle(self) -> None:
        # Generate puzzle with unique solution
        self.grid = [[0] * self.size for _ in range(self.size)]
        # ... your generation logic
        self.game_started = True

    def validate_move(self, row: int, col: int, num: int) -> tuple[bool, str]:
        # Validate and apply move
        if not self._is_valid(row, col, num):
            return False, "Invalid move!"
        self.grid[row][col] = num
        self.moves_made += 1
        return True, "Number placed successfully!"

    def is_complete(self) -> bool:
        # Check if puzzle is solved
        return all(cell != 0 for row in self.grid for cell in row)

    def render_grid(self) -> str:
        # Return ASCII art representation
        return "  | 1 | 2 | 3 |\n" + ...

    def get_rules(self) -> str:
        return "MY PUZZLE RULES:\n- Rule 1\n- Rule 2"

    def get_commands(self) -> str:
        return "MY PUZZLE COMMANDS:\n  place <row> <col> <num>"

from .my_puzzle import MyPuzzleGame

AVAILABLE_GAMES = {
    "sudoku": SudokuGame,
    "kenken": KenKenGame,
    # ... other games
    "mypuzzle": MyPuzzleGame,  # Add your game
}

Add tests in tests/test_my_puzzle_game.py:

from puzzle_arcade_server.games.my_puzzle import MyPuzzleGame

class TestMyPuzzleGame:
    def test_initialization(self):
        game = MyPuzzleGame("easy")
        assert game.name == "My Puzzle"

    def test_generate_puzzle(self):
        game = MyPuzzleGame("easy")
        game.generate_puzzle()
        assert game.game_started

    # ... more tests (aim for >90% coverage)

Run tests and verify:

make test-cov
make check

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-puzzle)
Make your changes
Run tests and checks (make check)
Ensure coverage stays above 90% (make test-cov)
Commit your changes (git commit -m 'Add amazing puzzle')
Push to the branch (git push origin feature/amazing-puzzle)
Open a Pull Request

Development Guidelines

Follow PEP 8 style guide (enforced by ruff)
Add type hints to all functions
Write tests for new features (>90% coverage)
Update documentation as needed
Ensure all grid headers align properly with rows

Troubleshooting

Server won't start

Ensure chuk-protocol-server is installed: uv pip install chuk-protocol-server
Check ports aren't already in use: lsof -i :8023,8024,8025,8026
Verify Python version is 3.11+: python --version

Tests failing

Install dev dependencies: make dev-install
Clear cache: make clean
Check Python version compatibility

Coverage too low

Run coverage report: make test-cov
View HTML report: make serve-coverage
Add tests for uncovered code

Grid alignment issues

All grid headers must align with row pipes
Use the format " |" for headers to match row format "N |"
Test visually: make example-telnet-kenken

License

MIT License - see the main chuk-protocol-server project for details.

Credits

Built using the chuk-protocol-server framework
Puzzle generation algorithms based on backtracking and constraint propagation
Uses modern Python tooling: UV, Ruff, MyPy, Pytest

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

0.8

Dec 22, 2025

0.7

Dec 21, 2025

0.6

Dec 21, 2025

0.5

Dec 20, 2025

This version

0.4.3

Dec 14, 2025

0.4.2

Dec 14, 2025

0.4.1

Dec 12, 2025

0.4

Dec 12, 2025

0.3

Dec 11, 2025

0.2

Dec 10, 2025

0.1.1

Dec 9, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

puzzle_arcade_server-0.4.3.tar.gz (142.3 kB view details)

Uploaded Dec 14, 2025 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

puzzle_arcade_server-0.4.3-py3-none-any.whl (118.2 kB view details)

Uploaded Dec 14, 2025 Python 3

File details

Details for the file puzzle_arcade_server-0.4.3.tar.gz.

File metadata

Download URL: puzzle_arcade_server-0.4.3.tar.gz
Upload date: Dec 14, 2025
Size: 142.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.12.2

File hashes

Hashes for puzzle_arcade_server-0.4.3.tar.gz
Algorithm	Hash digest
SHA256	`c861029620d6f426a10c5230d9c4230f2c2f44a9d5bf77bf46d3799b2e60081b`
MD5	`c6787030a8f0d1e8d471afc71ab46b34`
BLAKE2b-256	`a762e7948faa940212126ccf80a5a52b9b77ae261069332d4dd920ee5d77fd23`

See more details on using hashes here.

File details

Details for the file puzzle_arcade_server-0.4.3-py3-none-any.whl.

File metadata

Download URL: puzzle_arcade_server-0.4.3-py3-none-any.whl
Upload date: Dec 14, 2025
Size: 118.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.12.2

File hashes

Hashes for puzzle_arcade_server-0.4.3-py3-none-any.whl
Algorithm	Hash digest
SHA256	`fb676949f468889ee88568f036816cfb96c370e3f98b3566b914fb3a8564b03a`
MD5	`440eb97f7ddd4804682680f73bb84041`
BLAKE2b-256	`a6356a8b1c73e0b8b336e0b53fbc9defd5d7e1a404d72f3ae214aa77995e70fb`

See more details on using hashes here.

puzzle-arcade-server 0.4.3

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

Puzzle Arcade Server

Try It Now

Features

Available Games

Classic Logic Puzzles

Advanced CP-SAT Puzzles

Specialized Constraint Puzzles

Optimization Challenges

Advanced Reasoning Puzzles

Solver Profiles & Business Mapping

Example: Query Games by Profile

Quick Reference: Constraint Types to Business Problems

Quick Start

Prerequisites

Installation

From Source (Development)

Using UV (Recommended)

Using pip

Using Make (All Commands)

Docker Setup

Connecting to the Server

Local Development

Game Menu

Agent-Friendly Mode

Enabling Agent Mode

Agent Mode Features

Universal Game Commands

Starting and Managing Games

Playing Games

Special Commands (Game-Specific)

Example Gameplay Sessions

Sudoku

KenKen

Architecture

Game Architecture

Handler Architecture

Development

Setup Development Environment

Testing

Coverage by File

Code Quality

Tooling

Code Standards

Quality Metrics

Running Example Clients

CI/CD

Deployment to Fly.io

Using Make (Recommended)

Manual Deployment

Project Structure

Key Statistics

Use Cases

1. LLM Reasoning Demonstration

2. Constraint Solver Testing

3. Educational Tool

Adding New Puzzle Games

Contributing

Development Guidelines

Troubleshooting

Server won't start

Tests failing

Coverage too low

Grid alignment issues

License

Credits

Links

Project details

Verified details

Maintainers

Unverified details

Project links