← back

Chess Puzzle Maker

Mines my own games for the puzzles on this page

Python · Stockfishcode ↗

Turns Lichess games into puzzles: positions where the opponent slipped and exactly one move wins. The output feeds a puzzle widget on a website.

A generated puzzle board
Black to play and mate in 3.

Pipeline

fetch.py    download every game from the Lichess API         -> data/<user>.ndjson
analyze.py  Stockfish scan + uniqueness check on every swing  -> data/<user>.puzzles.json
export.py   rank, dedupe, pick the top 100                    -> out/puzzles.json

fetch.py streams games oldest-first and resumes from the last one saved, so re-running it only fetches new games. Set LICHESS_TOKEN for faster downloads.

analyze.py gets an eval for every position, reusing Lichess's own analysis where it exists and running a depth-12 Stockfish pass on the rest across a pool of engines. A candidate is any opponent move that swings the game from level (≤ +1.5) to winning (≥ +3) for the player. Each candidate is checked with multipv=2. It's a puzzle only if one move wins and the second-best doesn't. The line keeps extending while the player's next move is also the only one that wins. As on Lichess, the final mating move can have alternatives. One-move "take the hanging piece" positions are dropped.

export.py keeps puzzles that end in mate or are at least two moves long, takes the best one per game, skips games against the computer or anonymous players, and ranks by length, mate, sacrifice, quiet first move, opponent rating, and time control.

Usage

Needs Python 3.10+ and a Stockfish binary (on PATH, in $STOCKFISH, or anywhere under bin/).

pip install -r requirements.txt
python fetch.py <username>
python analyze.py <username>
python export.py <username>

Output

out/puzzles.json has one entry per puzzle with: