01 / THE LEARNING LOOP
A network proposes. Search investigates.
The project is an AlphaZero-style chess system with a practical starting point: supervised learning from recorded games before self-play. Human moves provide initial policy targets, while game outcomes provide value targets. That gives early searches more direction than a randomly initialized network.
The ambition is to improve through experience rather than hand-author a complete position evaluator. This is an experimental implementation, not a claim to reproduce AlphaZero’s playing strength or training scale.
- Champion networkEstimate moves and position value
- Guided tree searchInvestigate promising continuations
- Self-play + replayStore positions, visits, and outcomes
- Train + challengeEvaluate a candidate against the champion
The repository contains self-play, candidate training, and paired-color arena evaluation. These notes describe those mechanisms. A verified Elo rating or a sustained improvement claim would require separate match results.
02 / READING THE BOARD
Two questions, one shared representation.
The board is encoded as a 34 × 8 × 8 tensor. A convolutional stem and a residual tower build features that feed two heads. The policy head scores possible actions. The value head estimates the outcome from the side-to-move perspective, on a scale from −1 to +1.
The documented self-learning setup uses 12 residual blocks and 128 channels. The loaded checkpoint’s metadata determines the actual architecture; defaults elsewhere in the repository are not a reliable substitute.
| Input | 34 planes across an 8 × 8 board |
|---|---|
| Policy space | 8 × 8 × 73 = 4,672 action slots |
| Policy legality | Only legal moves participate in search |
| Value output | A scalar bounded by tanh |
| Search | PUCT with batched neural evaluation |
Most action slots are not legal in a given position. The encoder, network output order, and legal-move mask must agree exactly. A correct tensor shape is necessary, but it cannot prove that a move is attached to the right score.
03 / TRY THE SEARCH RULE
Explore what looks promising—and what is underexplored.
Search balances the value observed so far with a bonus for moves that deserve more investigation. In a simplified PUCT rule, the score is Q + c × P × √N / (1 + n). Here Q is the move’s estimated value from the parent’s perspective, P is its policy prior, N is the parent’s visit count, and n is the move’s visit count.
Turn the exploration weight
ILLUSTRATIVE DATAThese three invented candidates hold their values, priors, and visits fixed. Moving the slider changes which branch receives the highest selection score. This is a search-rule demonstration, not a live engine evaluation.
| Candidate | Q | Prior | Visits | Score |
|---|
The production search uses a visit-dependent exploration coefficient and virtual reservations for outstanding batched work. It also reuses subtrees. Batching lets several leaf positions share a neural-network call rather than requesting one tiny inference at a time.
from math import sqrt
def selection_score(q, prior, visits, parent_visits, c=1.25):
exploration = c * prior * sqrt(parent_visits) / (1 + visits)
return q + exploration
# Q is already expressed from the parent's perspective.
score = selection_score(0.20, 0.35, 5, 100)
print(round(score, 4)) # 0.929204 / LEARNING FROM GAMES
Search leaves behind a richer lesson than one move.
A recorded human game supplies the move that was played. Self-play can instead supply a distribution over explored moves, derived from visit counts. That distribution becomes a policy target; the eventual game result provides the value target.
The bootstrap pipeline separates large position tensors in HDF5 shards from searchable game metadata in SQLite. The self-play pipeline stores sparse policy targets so replay does not need a dense vector of thousands of actions for every position.
Candidate training can mix recent self-play with human-game rehearsal. The supplied configuration uses a 25% bootstrap mix and retains eight replay iterations. Those settings describe the configured experiment, not a demonstrated optimal recipe.
Training only on the newest batch can narrow what the model sees. Replay and rehearsal provide continuity, but they also influence which errors and habits persist. Their value must be checked against held-out positions and match results.
05 / BUGS THAT LOOK PLAUSIBLE
A legal-looking move can hide an indexing error.
The current network permutes its policy tensor from channel-first order to square-first order before flattening. That detail connects the convolutional output to the action encoder. Flattening the wrong dimension order still produces 4,672 values, but assigns them to different moves.
A useful test starts with a known legal move, encodes its index, places a score at the corresponding policy location, then decodes the selected result. Sliding moves, knight moves, castling, and promotions all need coverage.
Whose value is it?
The side to move changes after a move. A favorable position for a child can be unfavorable for its parent, so search must apply the correct sign when values cross that boundary. A sign bug can run quickly, generate games, and train on its own mistakes.
Parallel search needs cleanup
When several searches are in flight, paths are temporarily reserved to encourage useful parallel work. Reservations must be removed when evaluations return. Board apply/undo operations must also restore the exact state. The repository’s smoke tests explicitly check these boundaries and visit accounting.
06 / EARNING A PROMOTION
Finishing a training job is not a win.
A candidate faces the current champion in an arena with paired colors. Wins, losses, and draws determine whether the candidate is promoted. Lower training loss alone does not justify replacing the champion.
The supplied arena configuration uses 40 games and a 55% promotion threshold, and explicitly labels that game count as suitable for plumbing tests. A meaningful strength claim needs a larger evaluation, consistent search budgets, and uncertainty estimates. Small match sets can swing on a handful of results.
The next useful result
First establish a correct, repeatable loop. Then measure whether successive candidates actually improve under fixed conditions. The interesting question is not just whether the bot can play a game—it is whether the training process reliably teaches it to play a better one.