Generate unique-solution Kakuro puzzles, store them in SQLite and export print-ready PDF booklets with compact solution pages.
The generator supports independent puzzle counts and board sizes for Easy, Medium, Hard and Evil difficulties, deterministic generation from a master seed, multiprocessing, incremental SQLite persistence and duplicate protection.
- Four difficulty levels: Easy ★, Medium ★★, Hard ★★★, Evil ★★★★
- Independent board size for each difficulty
- Mixed-difficulty booklet generation in a single command
- Reproducible generation from a master seed
- Unique-solution verification
- Multiprocessing with configurable worker count
- Deterministic retries for failed generation slots
- Incremental SQLite persistence
- Duplicate-puzzle protection in SQLite
- Export selected database puzzles by ID
- PDF puzzle booklet with compact solution pages
- Gray clue/block cells by default, with optional black style
- A4, Letter, Legal, 6×9 and 8×10 page formats
- Graceful Ctrl+C handling that preserves already committed puzzles
- Python 3.9+
- ReportLab 4.2.2+
- pytest 8.0+ for testing
Using Conda:
conda create -n kakuro-generator python=3.11 -y
conda activate kakuro-generator
pip install -r requirements.txt
pip install -e .The package installs the kakuro-generator command-line entry point.
Generate a single medium puzzle:
kakuro-generator --pages 1 --difficulty medium --seed 20260815Generate puzzles into SQLite without creating a PDF:
kakuro-generator --easy 8 --size 8 --workers 2 --seed 20260815 --db puzzles.db --no-pdfPuzzle counts and sizes can be configured independently for each difficulty.
kakuro-generator --easy 8 --easy-size 8 --medium 8 --medium-size 9 --hard 8 --hard-size 10 --evil 8 --evil-size 10 --workers 2 --seed 20260815 --db puzzles.db --outfile kakuro_booklet.pdfThis generates one 32-puzzle booklet containing:
| Difficulty | Count | Board size |
|---|---|---|
| Easy ★ | 8 | 8×8 |
| Medium ★★ | 8 | 9×9 |
| Hard ★★★ | 8 | 10×10 |
| Evil ★★★★ | 8 | 10×10 |
kakuro-generator \
--easy 8 --easy-size 8 \
--medium 8 --medium-size 9 \
--hard 8 --hard-size 10 \
--evil 8 --evil-size 10 \
--workers 2 \
--seed 20260815 \
--db puzzles.db \
--outfile kakuro_booklet.pdfUse --pages together with --difficulty:
kakuro-generator --pages 5 --difficulty medium --size 9 --db puzzles.db --outfile medium_booklet.pdf--difficulty accepts:
easymediumhardevil
Use any combination of:
--easy N
--medium N
--hard N
--evil N
When mixed generation is used, the corresponding count options define the generation schedule.
--size sets a global/fallback square board size:
kakuro-generator --hard 4 --size 10Difficulty-specific overrides are also available:
--easy-size N
--medium-size N
--hard-size N
--evil-size N
A difficulty-specific size overrides --size for that difficulty.
Supported sizes are 7 through 15.
For example:
kakuro-generator --easy 4 --easy-size 8 --medium 4 --medium-size 9 --size 10Here Easy uses 8×8, Medium uses 9×9 and any other requested difficulty falls back to 10×10.
Use --seed to initialize the master random generator:
kakuro-generator --easy 8 --size 8 --seed 20260815 Each requested puzzle receives a derived child seed.
If a generation slot exhausts its normal generation attempts, --task-retries retries that slot with deterministically derived seeds:
kakuro-generator --evil 4 --size 10 --task-retries 8The default is:
--max-attempts 24
--task-retries 3
Because retry seeds are derived deterministically, a fixed configuration and master seed remain reproducible.
Provide --db to persist generated puzzles:
kakuro-generator --medium 8 --size 9 --db puzzles.dbThe database stores generation runs and generated puzzles. Completed puzzles are inserted and committed incrementally, rather than waiting for the entire batch to finish.
This means that successfully completed work is preserved if a later slot fails or generation is interrupted.
Duplicate puzzle insertion is rejected by the database layer, preventing an already stored Kakuro from being inserted again.
Previously generated puzzles can be selected from SQLite and exported without generating new ones:
kakuro-generator --db puzzles.db --export-ids 3,7,11,16 --outfile curated_booklet.pdfMissing IDs are skipped.
--export-ids requires --db and cannot be combined with --no-pdf.
Unless --no-pdf is specified, generated puzzles are written to a PDF followed by compact solution pages.
Default output:
kakuro_puzzles.pdf
Choose another filename with:
--outfile kakuro_booklet.pdfSupported page sizes:
A4
LETTER
LEGAL
6X9
8X10
Example:
kakuro-generator --medium 8 --size 9 --pagesize LETTER --outfile kakuro_letter.pdfGray clue/block cells are the default:
--block-color gray
A black style is also available:
kakuro-generator --easy 8 --size 8 --block-color black| Option | Purpose |
|---|---|
--pages N |
Number of puzzles in single-difficulty mode |
--difficulty LEVEL |
easy, medium, hard or evil |
--easy N |
Number of Easy puzzles |
--medium N |
Number of Medium puzzles |
--hard N |
Number of Hard puzzles |
--evil N |
Number of Evil puzzles |
--size N |
Global/fallback board size, 7–15 |
--easy-size N |
Easy board-size override |
--medium-size N |
Medium board-size override |
--hard-size N |
Hard board-size override |
--evil-size N |
Evil board-size override |
--seed N |
Master random seed |
--workers N |
Number of worker processes |
--max-attempts N |
Generation attempts inside each puzzle-generation call |
--task-retries N |
Deterministic retries for a failed puzzle slot |
--db PATH |
SQLite database path |
--outfile PATH |
Output PDF path |
--pagesize SIZE |
PDF page size |
--block-color COLOR |
gray or black; default gray |
--no-pdf |
Generate/store puzzles without PDF output |
--export-ids IDS |
Export comma-separated SQLite puzzle IDs |
--quiet |
Suppress normal progress output |
For the authoritative option list:
kakuro-generator --helpGeneration is stochastic, so an individual requested slot can occasionally fail even after retries.
A failed slot is skipped rather than terminating the whole batch. Other successful puzzles continue to be generated and, when SQLite is enabled, are committed immediately.
On Ctrl+C, queued work is cancelled and worker processes are terminated on a best-effort basis. Puzzles already committed to SQLite remain available.
- White cells contain digits 1–9.
- Digits may not repeat within a horizontal or vertical run.
- The digits in each run must sum to its clue.
- Every generated puzzle is verified to have exactly one solution.
Difficulty is treated separately from board size.
The generator can therefore create, for example, both Hard and Evil puzzles on the same 10×10 board size while targeting different puzzle characteristics.
Difficulty scoring is based on puzzle structure and solver behavior rather than simply assigning difficulty from dimensions alone.
A practical workflow is:
- Generate a reproducible batch with a master seed.
- Persist every successful puzzle to SQLite.
- Let duplicate protection reject previously stored puzzles.
- Review or curate the stored puzzle collection.
- Export selected puzzle IDs into a final booklet.
This separates generation, persistence and publication, while still allowing a complete booklet to be produced in one command.
Install the development requirements and run:
pytest