Fiche bilingue anglais / français

README.md

@@ -1,6 +1,8 @@
 ---
 license: mit
-language: fr
+language:
+  - en
+  - fr
 library_name: transformers
 pipeline_tag: text-generation
 tags:
@@ -13,6 +15,158 @@ tags:
 
 # Philidor 51M
 
+*[Version française plus bas](#philidor-51m-français)*
+
+A language model trained **from scratch** to play chess, without ever being
+given a single rule of the game.
+
+It never sees a board. It does not know that pieces, squares or a king exist.
+It receives a sequence of moves in UCI notation and predicts the next one,
+exactly the way a language model predicts the next word.
+
+> *"Pawns are the soul of chess."*
+> François-André Danican Philidor, 1749
+
+## Result
+
+**97.86 % of the moves it proposes are legal**, in free generation, with no
+constraint whatsoever. 95 % confidence interval: [97.65 – 98.05], measured on 20,000
+positions from held-out games.
+
+No rule was ever hard-coded. The model inferred the mechanics of the game from
+790 million moves played by humans.
+
+## Usage
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+tok = AutoTokenizer.from_pretrained("billygeekourson/philidor-51m")
+model = AutoModelForCausalLM.from_pretrained("billygeekourson/philidor-51m")
+
+ids = tok("e2e4 e7e5 g1f3 b8c6", return_tensors="pt").input_ids
+out = model.generate(ids, max_new_tokens=20, do_sample=True,
+                     temperature=0.6, top_k=20, pad_token_id=0)
+print(tok.decode(out[0], skip_special_tokens=True))
+```
+
+Moves are written in UCI, separated by spaces. **One move is exactly one
+token**, so an 80-ply game takes 80 tokens.
+
+## Playing without ever producing an illegal move
+
+The bundled `vocab_uci.json` lets you mask impossible moves before choosing.
+A single forward pass is enough, and the model keeps its preference ordering
+among the playable moves.
+
+```python
+import json, torch, chess
+from huggingface_hub import hf_hub_download
+
+v = json.load(open(hf_hub_download("billygeekourson/philidor-51m",
+                                   "vocab_uci.json")))
+board = chess.Board()
+board.push_uci("e2e4"); board.push_uci("c7c5")
+
+logits = model(tok("e2e4 c7c5", return_tensors="pt").input_ids).logits[0, -1]
+mask = torch.full_like(logits, float("-inf"))
+for move in board.legal_moves:
+    i = v["stoi"][move.uci()]
+    mask[i] = logits[i]
+
+print(v["itos"][int(mask.argmax())])   # g1f3
+```
+
+## Architecture
+
+Decoder-only Transformer: 16 layers, width 512, 8 attention heads, hidden MLP 1408. Pre-norm, RMSNorm, RoPE, SwiGLU, tied
+embeddings. Context of 256 moves, i.e. a whole game.
+
+**51,397,120 non-embedding parameters** (52,406,272 total).
+
+The architecture happens to match Llama exactly, which was not planned: the
+four building blocks were each chosen on their own merits. The model therefore
+loads as a standard `LlamaForCausalLM`, and the conversion was verified with a
+maximum logit difference of `0.00e+00` at every sequence length.
+
+## Vocabulary
+
+**1,971 tokens**: the 1,968 geometrically possible UCI moves on a chessboard,
+plus `<pad>`, `<bos>` and `<eos>`.
+
+No BPE. The vocabulary is finite and known in advance, which makes legality
+masking possible and spares the model from relearning that `e2` and `e4` form
+a single unit.
+
+## Data
+
+One month of public Lichess archives, July 2026.
+
+| | |
+|---|---|
+| Games read | 89,288,421 |
+| Games kept | 11,035,777 (12.4 %) |
+| Training tokens | 803,780,147 |
+
+Filtering: both players between 1800 and 2600 Elo, bullet excluded, normal
+termination, between 20 and 300 plies. The validation split is done **per
+game**, never per token, so that no game is cut between the two sets.
+
+## Training
+
+A single RTX 3090. **2 hours**, 16,300 steps, one full epoch. bf16, AdamW,
+cosine schedule with warmup, effective batch of 49,152 tokens. Measured MFU:
+64 %.
+
+Final loss: 1.6024 training, 1.6434 validation. Both curves stay
+superimposed, so no overfitting.
+
+## What the model knows
+
+| Metric | Value |
+|---|---|
+| Legal moves in free generation | **97.86 %** |
+| Agreement with the human move, top-1 | 51.42 % |
+| Agreement with the human move, top-5 | 88.72 % |
+| Castling | 100.00 % |
+| En passant | 100.00 % |
+| Promotion | 98.60 % |
+| Getting out of check | 96.60 % |
+
+All measurements are on held-out validation positions, at temperature 1.0 for
+legality and on the argmax for the rest.
+
+## Known limitations
+
+**No board representation.** The model only understands a sequence of moves
+from the initial position. It cannot resume from an arbitrary FEN position.
+
+**About two moves in a hundred are illegal** without masking. For actual play, masking is essential.
+
+**Modest playing strength.** On par with Stockfish capped at skill level 0, it
+drops off at level 1. This is a search-free model: it plays the most probable
+move after a single forward pass, with no lookahead.
+
+**It plays endgames less well than openings.** Positions with few pieces offer
+less statistical regularity to exploit.
+
+## Related model
+
+`philidor-142m`: same method, 142 M parameters, four months of data, twenty hours of training, 98.85 % legal moves. In a 400-game head-to-head it beats this model 305 to 32, a 290 Elo gap.
+
+The interesting part: at equal data volume, tripling the model size barely changes legality, but gains two to three points of agreement with the human move. What drives playing strength is the amount of data, not model size.
+
+## License
+
+MIT for the model. Data comes from the public Lichess archives, released under
+CC0.
+
+---
+---
+
+# Philidor 51M (français)
+
+
 Un modèle de langage entraîné **de zéro** à jouer aux échecs, sans qu'aucune
 règle du jeu ne lui ait jamais été donnée.