maia3-local-stack

Run Maia 3 locally as a human-like UCI chess engine, with En Croissant integration, Stockfish side-by-side analysis, and locally generated Lichess-based opening books for Linux and Apple Silicon macOS.

Status

This repository is the clean Maia 3 successor to the earlier Maia 2 local-stack project.

Current scope:

• install Maia 3 in a local venv from the upstream GitHub repo
• launch Maia 3 through a thin compatibility wrapper with optional opening-book and HumanTime support
• build Polyglot opening books from Lichess data
• document Linux and Apple Silicon macOS setup

Planned next:

• calibration guidance after live testing
• optional installer polish / post-install smoke test
• more GUI screenshots once the end-to-end flow is exercised visually

Quick start

git clone https://github.com/Dash1971/maia3-local-stack.git
cd maia3-local-stack
chmod +x *.sh
./setup-maia3.sh

That creates a local install under ~/chess/maia3-engine/ and prints the engine path to use in your GUI.

On Linux, setup-maia3.sh deliberately installs the CPU-only PyTorch build to avoid dragging in a multi-gigabyte CUDA stack on non-GPU systems.

To build opening books:

./build-books.sh

Opening books are optional. Maia3 can play directly from the position without a book; BookFile is there when you want a local Polyglot book to steer the opening phase toward rating/time-control-specific human games.

Quick verification after setup:

~/chess/maia3-engine/maia3-engine.sh --list-models
printf 'uci\nisready\nquit\n' | ~/chess/maia3-engine/maia3-engine.sh

Deterministic wrapper/book fixture check:

~/chess/maia3-engine/venv/bin/python tests/generate_startpos_book.py
printf 'uci\nsetoption name BookFile value %s\nposition startpos\ngo\nquit\n' \
  "$PWD/tests/fixtures/startpos-e2e4.bin" | ~/chess/maia3-engine/maia3-engine.sh

That fixture path should emit both:

• info string book move
• bestmove e2e4

For the exact En Croissant setup flow, use:

• GUIDE.md for Linux
• GUIDE-macOS.md for Apple Silicon macOS

Files

File	Purpose
setup-maia3.sh	Create a local Maia 3 environment and install a launcher
maia3-engine.sh	Thin launcher for the local wrapper
maia3_wrapper.py	UCI compatibility layer adding BookFile and HumanTime
build-books.sh	Build Polyglot opening books from Lichess archives
GUIDE.md	Linux setup notes
GUIDE-macOS.md	Apple Silicon macOS setup notes

Notes

• Default model is currently maia3-79m.
• If you want a lighter fallback, set MAIA3_MODEL=maia3-23m before launching or running setup.
• The setup script installs Maia3 from the upstream GitHub repository, not from PyPI.
• The local wrapper adds BookFile and HumanTime while keeping upstream Maia3 as the underlying move picker.
• In En Croissant, you can create multiple engine entries that point to the same maia3-engine.sh launcher. Treat each entry as a separate profile: customize its UCI options independently. A common setup is one Maia3 profile for play with your target Elo, a matching opening BookFile, and HumanTime=true; and a second Maia3 analysis profile at the same Elo with HumanTime=false so recommended moves appear without the artificial delay.
• BookFile has been smoke-tested with a deterministic Polyglot fixture from the starting position.
• The first engine run downloads the chosen checkpoint from Hugging Face and reuses the local cache after that.
• The wrapper is intentionally thin: upstream Maia3 stays authoritative for model behavior.
• tests/generate_startpos_book.py is easiest to run with the installed engine venv Python, since that environment already has python-chess.

License

MIT for repository code and scripts. Maia 3 model weights and upstream engine code have their own licenses; see the upstream CSSLab repository and Hugging Face model pages.