Update Readme

.gitignore

@@ -0,0 +1 @@
+convert_checkpoint.py

README.md

@@ -1,46 +1,80 @@
-# Chess Transition Policy
+# Charles the Chess Bot
+
+This is Charles, a bot designed by me for [EnderChef's](https://huggingface.co/Enderchef) chess model competition. Charles moves quickly and does not search deeply; it chooses the move that best matches the current board according to its learned policy.
+
+I describe Charles' architecture as zero-shot as after hearing about the competition, I came up with the whole thing while walking home in around 20 minutes, without looking at any other engine architectures. There were no iterations during training, so the model has clear design limitations.
 
 ## Architecture
 
-Chess move-ranking model with 32,537,088 parameters. It receives a current
-board and every legal successor board, then returns one score per candidate.
-Legal move generation remains outside the model.
-
-- Board input: `[B, 64]` mover-relative piece IDs (`0`–`12`), with Black
-  positions rank-flipped using `square ^ 56`.
-- Board encoder: piece and square embeddings, learned summary token, and 6
-  fully bidirectional transformer layers.
-- Move representation: `encoded_successor - encoded_current`.
-- Candidate encoder: current board plus move transitions, 12 fully
-  bidirectional transformer layers, and board/move type embeddings.
-- Hidden size: 384; attention heads: 6; head dimension: 64.
-- Feed-forward: SwiGLU with hidden size 1,040.
-- Scoring: RMS-normalized query/key projections and scaled dot product.
-- Output: `logits[B, M]`, preserving the caller’s legal-move order; padded
-  candidates are `-inf`.
+Charles contains 32,537,088 parameters and consists of two primary parts: the Board Encoder and the Move Decider. The data flow is:
+
+1. The Board Encoder encodes the current board state.
+2. The Board Encoder encodes the board state after every legal move.
+3. Move embeddings are created by subtracting the current board embedding from the corresponding successor-board embedding. This produces one transition embedding per legal move, typically around 20.
+4. The original current-board embedding is preserved unchanged as the fixed scoring query.
+5. A copy of the current-board embedding is prepended to the move embeddings and passed through the Move Decider.
+6. The Move Decider contextualizes the copied board token and all move tokens using bidirectional attention.
+7. The contextualized move embeddings are projected through a learned, bias-free key matrix.
+8. The original, unaltered current-board embedding is projected through a learned, bias-free query matrix.
+9. Query and key vectors are RMS-normalized and compared with scaled dot products to produce one logit per legal move.
+10. The highest-scoring legal move is selected greedily.
+
+### Board Encoder
+
+| Component | Details |
+|---|---|
+| Input | Tokenized board `[64]` |
+| Piece vocabulary | 13 IDs: empty, mover pieces, opponent pieces |
+| Piece embedding | `13 x 384` |
+| Square embedding | Learned absolute `64 x 384` embeddings |
+| Board tokens | Piece embedding + square embedding |
+| Summary token | Learned `384`-dimensional token prepended |
+| Transformer | 6 bidirectional transformer layers |
+| Attention | 6 heads, 64 dimensions per head |
+| Feed-forward | SwiGLU, hidden size 1,040 |
+| Output | One `384`-dimensional board embedding |
+| Causal masking | None |
+
+### Move Decider
+
+| Component | Details |
+|---|---|
+| Current board | Encoded once by the Board Encoder |
+| Successor boards | Encoded once per legal move |
+| Move embeddings | `successor_embedding - current_embedding` |
+| Candidate count | Typically around 20 legal moves |
+| Candidate sequence | Current board copy + all move embeddings |
+| Type embeddings | Separate board-token and move-token embeddings |
+| Candidate positions | No candidate position embeddings |
+| Transformer | 12 bidirectional transformer layers |
+| Attention | 6 heads, 64 dimensions per head |
+| Feed-forward | SwiGLU, hidden size 1,040 |
+| Query source | Original, unaltered current-board embedding |
+| Query projection | Bias-free `384 x 384` linear layer |
+| Key source | Contextualized move embeddings |
+| Key projection | Bias-free `384 x 384` linear layer |
+| Normalization | Parameter-free RMSNorm on queries and keys |
+| Scoring | Scaled query-key dot product |
+| Output | One logit per legal move |
+| Padding | Invalid candidates masked to `-inf` |
 
 ## Training
 
-The model was trained on chess positions from tournament games using legal
-successor boards generated with `python-chess`. Training used supervised move
-targets and optional Stockfish teacher-logit distillation.
+The model was trained in three phases on tournament chess positions. Legal moves and successor boards were generated with `python-chess`.
 
-- Optimizer: AdamW.
-- Precision: BF16 autocast on supported CUDA hardware.
-- Attention: PyTorch scaled-dot-product attention, fully bidirectional.
-- Dropout: 0.0 by default.
-- Checkpoints contain model weights, optimizer/scheduler state, training step,
-  and architecture configuration.
+| Phase | Data and process | Objective and details | Approx. Elo |
+|---|---|---|---|
+| 1. Supervised policy | Human tournament positions; the recorded human move is the target | Cross-entropy over all legal moves. AdamW; learning rate `4e-4 -> 3e-5`; 2,000-step warmup; batch size 32; gradient accumulation 4; BF16 autocast; 0.0 dropout | 1300-1400 |
+| 2. Stockfish distillation | The same positions annotated with Stockfish scores for every legal move | KL distillation against the full Stockfish move distribution. Stockfish depth 12; teacher temperature 30; student temperature 1.0; fine-tuned from Phase 1 | 1700-1800 |
+| 3. On-policy training | The model generates fresh games while Stockfish plays the opponent; completed rollouts are used once | For the move selected by the model, minimize `(model_probability - Stockfish_probability) ** 2`. Unchosen moves receive no direct loss. Muon for matrix weights plus AdamW for other parameters; Opponent depth 8; Teacher depth 10; 10,000-step schedule | ~2000 |
 
-Convert a project checkpoint with:
+All phases use fully bidirectional scaled-dot-product attention. Phase 3 keeps the model's own actions rather than replacing them with Stockfish's best move, so the rollout distribution remains on-policy.
 
-```powershell
-python convert_checkpoint.py --checkpoint ../../checkpoints/policy/on-policy/step-0006000.pt
-```
+## Changes 
 
-The published weights in this folder are from the on-policy step-6000
-checkpoint:
+Changes id make if I had the time to iterate include:
 
-```text
-../../checkpoints/policy/on-policy/step-0006000.pt
-```
+- Static + RoPE Square embeddings: As squares both have absolute identities and relative identities
+- Replace move subtraction: I reckon a linear subtraction is a rich enough transform for this task
+- More Capacity: Since this Charles relies on alot of emergent properties such as next move planning and overall generalization, more capacity would almost certainly help
+- Self Play: This was originally planned but ran out of time