Alpha Dots & Boxes

Every line changes the game.

A graph network that learns the classic pencil-and-paper game by playing itself.

Draw a line. Close a box. Take another turn. Behind this simple game is a tricky question: when should you take a box, and when should you give one away?

Alpha Dots & Boxes learns through self-play and looks ahead before moving. Its network represents the relationships between edges and boxes, so the same weights work on square and rectangular boards of different sizes.

Play locally

Python 3.11 or newer is required. Playing uses NumPy; no GPU or training framework is needed.

git clone https://github.com/IlyaKhalafi/AlphaDotsAndBoxes.git
cd AlphaDotsAndBoxes
python -m venv .venv
source .venv/bin/activate
python -m pip install .
adb serve --checkpoint models/larger.npz

Open http://127.0.0.1:8000. Choose a board, adjust thinking time, and play. The interface supports hints, undo, keyboard controls, custom rectangular boards, and an agent-versus-agent watch mode. Select Agent vs Agent under Players to watch both sides, adjust Move delay, and pause or resume. Board dimensions count boxes, not dots.

Choose Quick, Standard, or Deep thinking. By default, NumPy play uses a supervised 1.9-second decision deadline, including on 10×10 boards. Improved search scored 66.25% on 4×4 and 82.5% on 5×5 against the previous agent in fresh matches. See the results and timing checks. An experimental alpha–beta engine is also available.

For stronger 10×10 play, enable longer thinking:

adb serve --checkpoint models/larger.npz --extended-search

On large boards, Deep · up to 60 s gives the agent more time. It won 35 of 40 fresh 10×10 games against the same model with a smaller search budget, averaging about 19 seconds per decision in those tests. Small boards keep the short deadline. See the large-board results for the comparison and limits.

For an optional speed boost, see the setup and measurements.

The included model has trained on boards through 5×5. The UI also solves small endgames exactly when time allows. Launching adb serve without a checkpoint selects a clearly labeled tactical opponent.

Or deploy the included model with Docker:

docker build -t alpha-dots-and-boxes .
docker run --rm -p 9003:8000 alpha-dots-and-boxes

Open http://localhost:9003. See deployment notes for custom models and hosting.

What makes it different

• One network, many boards. No fixed board-sized output layer.
• Learned by playing. Search decisions and final results become training data.
• Correct extra turns. Capturing a box keeps the player active in both rules and search.
• Built with RLlib. Its learner updates the graph network; Ray workers collect games in parallel.
• Measured openly. Results, raw outcomes, settings, and limitations live in docs/results.md.

The released model is an experimental opponent. Beating expert humans has not been demonstrated; that requires stronger training and actual human matches.

A look inside

The network asks two questions: where should I draw? and can I win? Search uses those answers to explore possible moves. After the game, RLlib updates the network from the choices it searched and the result it reached.

See the architecture notes for the detailed design.

Train your own

Install the optional training tools; PyTorch and RLlib are used only here:

python -m pip install -e '.[train]'

A short CPU run checks the complete pipeline:

adb train --config configs/smoke.json --output runs/smoke

For a first training run:

adb train --config configs/bootstrap.json --output runs/bootstrap

Use --device cuda to train the learner on a GPU. CPU search workers remain separate. GPU training has a configurable allocation cap and pacing; review the training guide before using shared hardware.

adb train --config configs/bootstrap.json --output runs/bootstrap --device cuda
adb export --checkpoint runs/bootstrap/latest.pt --output models/custom.npz
adb serve --checkpoint models/custom.npz

Runs save progress, portable agent checkpoints, and a resumable learner state. The training guide covers resuming, refinement, and a longer campaign with larger boards. Local speed measurements are recorded in the performance notes. Ongoing improvement experiments and their decisions are recorded in the refinement notes.

Evaluate and develop

adb evaluate --checkpoint models/larger.npz --games 40 --sizes 2x2,3x3,4x4
python -m pip install -e '.[dev]'
pytest -q

Evaluation alternates seats and tests random, tactical, and exact-search opponents where practical. Its default disables the agent's exact endgame aid.

src/alphaboxes/   rules, graphs, search, RLlib training, evaluation, web UI
configs/         smoke, bootstrap, refinement, and longer training presets
models/          playable checkpoint and model notes
docs/            architecture, training, measurements, and visual assets
tests/           rules, invariance, search, learner resume, and API checks

To regenerate the UI recording, install the optional media tools, start the server, and run:

python -m pip install -e '.[media]'
playwright install chromium
python scripts/capture_ui.py

MIT licensed. Improvements backed by reproducible experiments are welcome.