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

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:
fen: the position to solvefenBefore,lastMove: the move that set it up, for animationsolution: alternating UCI moves, the player's first and last. WhenacceptAnyMateis true, any mate is accepted on the last move.themes- whether the player found it in the game
- game metadata: link, date, time control, ratings, opening, result, and the player's clock at that moment