Harmon

A research chess project built around a simple idea: model the moves humans actually play, including their mistakes, rather than treating the opponent as a perfect minimax adversary.

The current codebase focuses on the modeling side of that idea. It trains a causal language model on rated Lichess games using a lossless chess tokenizer, and can sample complete move sequences from trained checkpoints.

Status: alpha research code. The human-move model and data pipeline are implemented; the broader "chess engine that exploits likely human mistakes" is the research direction, not a claim that the repository already contains a competitive finished engine.

What is implemented

• streaming download of rated Lichess PGN data
• a lossless tokenizer for chess game text
• context packing for causal language-model training
• GPT-style causal LM training with PyTorch / Hugging Face Transformers
• checkpoint save/resume
• Weights & Biases experiment logging
• interactive generation from trained checkpoints

Train

Install the package with Poetry:

poetry install

Then train with:

poetry run python -m harmon.train

The current training script streams rated games from the Lichess database, tokenizes the PGNs, fills fixed-size contexts, and trains a causal language model by next-token prediction.

Generate

After a checkpoint exists:

poetry run python -m harmon.generate

The generator loads a model checkpoint and streams decoded chess text as tokens are sampled. You can also provide prompts on stdin.

Repository structure

src/harmon/
├── tokenizer.py        # lossless chess tokenizer
├── dataset.py          # PGN download / dataset pipeline
├── context_filler.py   # packs games into model contexts
├── train.py            # causal LM training loop
├── generate.py         # checkpoint sampling / streaming decode
└── utils.py

Research direction

A conventional chess engine asks what happens against optimal or search-derived replies. Harmon is interested in a different quantity: what reply is a particular population of humans likely to make?

A sufficiently good human-move model can become an opponent model inside search, changing the objective from "best move against perfect play" toward "best move against the distribution of mistakes this opponent is likely to make."

License

MIT — see LICENSE.