Tell a chess model how to play.

Text in, move out

A frozen EmbeddingGemma-300m encodes the prompt. Gated cross-attention in the top 6 of 12 decoder layers reads every token of it.

Legal by construction

Each move is a tuple (source, destination, piece, promotion) with one output head per field. The model scores only the legal moves of the position.

No search

One forward pass per move: the model plays its highest-scoring legal move. That is fast enough to run in a browser tab.

Score moves from Python

# needs a Rust toolchain for the tokenizer (https://rustup.rs)
git clone https://github.com/nov3o/llm_chess-demo
cd llm_chess-demo && pip install -r requirements.txt
hf auth login   # once: the prompt encoder is gated

from chsm8 import CHSM8

model = CHSM8.from_pretrained()   # LegumMagister/chsm8
moves = model.score("1. e4 e5 2. Nf3",
    "castle queenside and storm the enemy king with your pawns")
print(moves[:3])   # legal moves with log-probabilities, best first

An empty prompt gives the model's own play. Other weights: CHSM8.from_pretrained("LegumMagister/chsm8-sft"), or filename="full_pass/model.pt" for the full-pass DPO model. Accept the EmbeddingGemma-300m license on Hugging Face first.

Tokenizer and data

pip install "git+https://huggingface.co/LegumMagister/chsm8-tokenizer"

import chsm8_tok
chsm8_tok.tokenize("1. e4 e5 2. Nf3")   # [1804, 2356, 1350]
chsm8_tok.convert("1. e4 e5 2. Nf3", dst="lan", type="text")
# 'e2-e4 e7-e5 Ng1-f3'

from datasets import load_dataset
games = load_dataset("LegumMagister/chsm8-pre-training",
                     split="train", streaming=True)
labels = load_dataset("LegumMagister/chsm8-post-training",
                      split="validation")

Games join their style labels on (month, row_idx), the stable game id of every CHSM8 dataset.

Main comparison

Each metric is measured under its own prompt; queenside castling is the share of castling. The main model is a 20-minute DPO run on 1 GPU; a full pass over the data did not improve on it. Strength without a prompt is unchanged.

The cost of following risky prompts

Told to attack at all costs and sacrifice material, chsm8 does, and without search it loses about 150 Elo against an accurate engine (SFT: about 40). Training games labeled as sacrificial were not lost more often.

Strong without search

chsm8-pt against other public models trained without preference tuning, rewards or search: 200 games each, from 100 openings with colors swapped. Elo advantage with 95% CI. It wins every match, including against a 2.8B model.

Strength during pretraining

200 games per checkpoint (±50 Elo); final model 999 games, 1837 Elo (95% CI 1817 to 1856). The pass was restarted at 60% with the remaining data reshuffled, after a loss bump tied to the 2021-09 to 2022-05 Lichess months.

Player prompts

On about 1,000 held-out games for each of the 20 top players with the most data, "play like {player}" with the right name makes the player's real moves more likely than the same wording with another top player's name, for all 20 players.

Across all 99 players, the right name wins in cross-entropy for 94 (SFT) and 96 (DPO). The effect is modest because top players differ little in their moves.

Labels that agree with the board

Gemma-4-31B described 3.02M game sides from their moves plus a card of features measured on the board. A Gemma-3-1B student, distilled from the 2.4M teacher sets that contradict nothing on the board, labeled the rest.

The student carries as much signal about the game as its teacher. A second teacher, Apertus-70B, wrote vivid labels that carried 4 to 5 times less signal, so it was dropped.