Chess AI
A fully playable chess game where the rules engine decides every legal move and the opponent — a neural network trained on human games — runs entirely client-side. Beat it on any difficulty while signed in for a one-time +5 JTB credit reward, verified by replaying your moves on the server.
Problem
Two problems, and they have to be solved in the right order. The opponent had to be a real trained model that runs entirely in the browser — no server, no API key, no download-on-homepage — while still offering three difficulties that actually feel different. And the credit economy cannot trust the client: any browser can claim 'I won', so a reward must be derivable from the moves alone, replayed by the server, and awarded at most once per user.
Approach
Build the game completely and the model to a contract. Board, legal-move validation, game state, termination, and three difficulties all ship behind one opponent interface, so the trained models were drop-in replacements rather than a rewrite. The encoding — 17 perspective-relative planes from the FEN string, a 4096-entry from×to policy — is written once and implemented twice, independently in Python for training and TypeScript for inference, with golden fixtures proving the two implementations agree bit-for-bit; that parity check is what makes it safe for a trained network to be consumed by a browser runtime nobody trains against. The UI never applies an opponent's move directly — it passes the chosen move back through the engine's validator, so even a corrupted model file can only degrade play quality through the fallback, never produce an illegal move. Quantization is gated, not assumed: int8 candidates were rejected because they changed the model's pick on golden positions, and fp16 shipped only after proving byte-identical behaviour at half the size.
Models
One 346,880-parameter policy CNN (a 17-channel board stem, four residual blocks, a 4096-logit move head) trained three times — once per difficulty band — on human games from Lichess's open 2024-01 rated dataset (CC0): the easy model saw only sub-1200 games, the medium 1200–1799, the hard 1800+. The input is 17 perspective-relative 8×8 planes built from the 6-field FEN alone; the output scores every from→to move, and the rules engine — not the model — masks that scoring down to legal moves before the argmax. The same 349k-parameter architecture produces three distinct opponents because the training data, not the network, encodes the skill level. Artifacts are fp16-quantized ONNX (~0.7 MB each), lazy-loaded by difficulty through ONNX Runtime Web's wasm backend, with a self-hosted runtime and a heuristic fallback through the same interface if a model fails to load.
Evaluation
Move prediction on held-out Lichess validation positions (masking by legality, the exact browser decision rule): the easy model plays the human move 38% of the time (top-3 64%), medium 42% (top-3 69%), hard 41% (top-3 68%) — percentages that are not comparable across bands because each model is measured against its own rating pool's move distribution, and stronger players are harder to predict. Between 95.7% and 98.1% of raw argmax picks were already legal before masking. The decisive strength test is play-offs against ports of the site's previous heuristic opponents: every model beats random and material-greedy heuristics without losing a game, and the hard model beats a depth-2 alpha-beta search heuristic with a majority (50% wins / 20% losses / 30% draws over 20 games) — the bar the easy model fails badly (10% wins). Model behavior is locked by regression fixtures: cross-language parity tests prove the Python trainer and the TypeScript encoder produce byte-identical board tensors, and every shipped artifact must reproduce its recorded top-1 move on 12 golden positions under the same wasm runtime the browser uses. The reward path is verified separately: the server replays the submitted move list from the initial position through its own rules engine, requires a legal game ending in checkmate won by the submitter, rate-limits claim attempts, and enforces once-per-user with a unique-gated database function.
Results
Three ~0.7 MB fp16 ONNX artifacts ship in the browser, one per difficulty, each lazy-loaded only when its difficulty is selected — nothing model-related is on the homepage or the initial chess page load. All bands clear 35% masked top-1 on their own band's held-out games, and every model beats the site's previous heuristic opponents, with hard defeating a depth-2 alpha-beta search heuristic 50–20 over 20 games. On unhappy paths the discipline shows: an interrupted or failed model load falls back to the heuristic opponent mid-game without the status line sticking, reward claims are replayed server-side rather than trusted, resubmitting an already-claimed win answers as already-claimed, an illegal move list is rejected with the index of the first illegal move, and a loss or draw is rejected as not a win.
Lessons
The contract is the deliverable. The encoding spec — 17 planes, 4096 logits, from×to layout, perspective mirroring — is what let a PyTorch training pipeline and a browser inference runtime be built by different processes and still agree on move indices, and the parity fixtures caught interpretation drift (head layout, promotion encoding, en-passant conventions) before it could ship. Quantization taught the same lesson from the other side: 'smaller' is not a claim you can ship on faith — int8 looked like a clean 4× win until the gate showed it changing moves on golden positions. And in a credit economy, the interesting engineering is rarely the game itself; it is refusing to trust the client that played it.
Technical Stack
- PyTorch
- ONNX
- ONNX Runtime Web
- Next.js
- TypeScript
- React
- chess.js
- Next.js server routes
- Postgres
- Supabase