chesslm

A tiny neural chess evaluator with alpha-beta search and a desktop chess game.

Quick start · Desktop game · Training · Benchmarking · Development

chesslm combines a small NumPy network with a fixed material evaluator to choose chess moves. Play against the included model.npz in a Tkinter window, or request a move from the command line. Playing uses your CPU and requires no Stockfish process. Stockfish supplies training labels and benchmark comparisons.

The network has 100,353 parameters and 401,412 bytes of float32 weights, about 392 KiB. Despite the name, it is not a language model. The included checkpoint's training history and playing strength have not been verified; no Elo is claimed.

Quick start

Use Python 3.10 or newer. Run these commands in a POSIX shell:

git clone https://github.com/skorotkiewicz/chesslm.git
cd chesslm
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python chess_game.py

The desktop game needs Tkinter and a display. Some Linux distributions provide Tkinter separately in a package named python3-tk or tk. On Windows, activate the environment with .venv\Scripts\Activate.ps1 in PowerShell.

For a terminal-only first move, run this from the project directory:

OPENBLAS_NUM_THREADS=1 python chesslm.py play --model model.npz

The OPENBLAS_NUM_THREADS=1 prefix limits OpenBLAS threading for the small network. In PowerShell, set $env:OPENBLAS_NUM_THREADS = "1" before running the Python command. The desktop game sets this default automatically.

python chess_game.py
python chess_game.py --color black
python chess_game.py --model model.npz --depth 3 --max-nodes 20000

uv run --python /usr/bin/python chess_game.py
uv run --python /usr/bin/python chess_game.py --color black

python web/chess_web.py
# Or use an isolated uv environment:
uv run --python /usr/bin/python web/chess_web.py

python web/build_pages.py
python -m http.server 8001 --bind 127.0.0.1 --directory _site

Command-line play

OPENBLAS_NUM_THREADS=1 python chesslm.py play \
  --model model.npz --depth 3 --max-nodes 20000

The command prints JSON with move, a UCI move string such as e2e4, and nodes, the visited node count. When the game has ended, move is null. Add --fen '...' with a valid FEN to choose a move in another position.

This command chooses one move per invocation; it does not implement a UCI engine server. CLI model paths are relative to your working directory.

How it works

The weight size excludes the NPZ header, Python, NumPy, and process memory.

A node limit can leave only a shallow completed search iteration. If none finishes, search returns a legal fallback move. Long tactics remain a limitation. The game and search recognize automatic draws but do not implement optional draw claims. A FEN does not include prior repetition history.

Training

Training is optional. The included checkpoint is enough to play.

Data generation and benchmarking require a Stockfish executable. Stockfish is not tracked in this repository. The default path is stockfish/stockfish-linux-x86-64-universal, relative to chesslm.py, for x86-64 Linux. Supply --engine /path/to/stockfish to use another location or a binary for your platform.

Run these commands on your training machine. Output files must not already exist; model-trained.npz leaves the included checkpoint available.

python chesslm.py generate \
  --engine /path/to/stockfish \
  --positions 100000 --nodes 20000 --threads 2 \
  --output positions-train.jsonl

OPENBLAS_NUM_THREADS=2 python chesslm.py train \
  --data positions-train.jsonl --epochs 30 --output model-trained.npz

Stockfish labels self-play positions with White's centipawn evaluation using a three-line search. Opening choices vary among those lines, with occasional variation later. Mate labels use ±10,000 centipawns. The node budget bounds Stockfish's search work, not elapsed time.

Validation holds out entire games and removes positions shared with those games from training. A dataset needs at least two games and some distinct positions. Training saves the initial weights if no epoch improves validation loss.

The dataset is loaded into memory. Input arrays need roughly 313 MB per 100,000 positions, plus JSON rows and temporary arrays. Larger datasets need more RAM.

Copy model-trained.npz to your playing machine and select it explicitly:

python chess_game.py --model model-trained.npz

Benchmarking

Generate a separate corpus with a different seed. Do not train on this file. Use fresh output filenames if you repeat the workflow.

python chesslm.py generate \
  --engine /path/to/stockfish \
  --seed 9001 --positions 5000 --nodes 20000 \
  --output positions-benchmark.jsonl

OPENBLAS_NUM_THREADS=1 python chesslm.py benchmark \
  --engine /path/to/stockfish \
  --model model-trained.npz --data positions-benchmark.jsonl \
  --positions 100 --nodes 50000

The JSON report contains the position count, best-move agreement, and mean centipawn loss against Stockfish. These are noisy, node-limited estimates. Different seeds can still produce repeated openings, and match testing is needed to establish an Elo rating. A tiny distilled model should not be expected to match Stockfish.

Development

From an environment containing requirements.txt, run:

OPENBLAS_NUM_THREADS=1 python -m unittest -v
python chesslm.py --help
python chess_game.py --help
python web/chess_web.py --help

Tests cover encoding, checkpoint size and loading, gradient math, invalid positions, validation separation, node limits, promotions, check evasion, forced mates, a free queen capture, and desktop interactions. GUI tests skip when no display is available.

The tests do not run Stockfish, generate data, or optimize model weights. Search tests use hand-set zero weights; the derivative check uses random weights without optimization. Passing them does not measure the supplied checkpoint's strength. Generation and training still need end-to-end verification on the training machine.

Project files

License

MIT.