Skip to main content

chessformer_lens

A Library for Mechanistic Interpretability of Transformer-Based Chess Models.

Created by David Litman.

DOI

Try the app in your browser, no install needed $\longrightarrow$ Open In Colab

The app


Paper: Increasing Skill Level Recruits Deeper Attention Layers in a Frozen Chess Transformer (Litman, 2026). Every figure and most of the analysis in this paper was made with this library.


Pip install:

python3 -m venv .venv && source .venv/bin/activate
pip install chessformer_lens
# for Maia-3 models, first: pip install https://github.com/CSSLab/maia3/archive/1e13597c42d4858b7cfd7cfdae01e297263364b2.zip
# Leela's BT4 net downloads itself on first use
# for DeepMind's searchless models, first: pip install tensorstore (reads their checkpoints, once)

or Clone if you want to edit the code:

git clone https://github.com/chessformer-lens/chessformer_lens
cd chessformer_lens
pip install -r requirements.txt

Demo Notebook: Open In Colab


A knight-fork position's move report

There is wonderful prior chess-interp work, for instance: McGrath et al. on AlphaZero concepts, Jenner et al. on lookahead in Leela, Karvonen on chess-GPT, but there is no general infrastructure for rigorous interpretability work or interactive visualization for these models.

Chessformer_lens is built to do both, especially inspired by Neel Nanda's transformer_lens library.

Chess is unusually suited for AI interpretability because it requires complex and structured reasoning in a compact domain, and it has a hierarchy of human concepts (squares -> threats -> tactics -> strategy) which can provide deep insight into how AI carves features.

Transformer based chess models ("chessformer") are a good lens for studying LLMs because outputs have a clear ground source for the evaluation of a move and so avoid the vagueness of language, because attention functions with clearly interpretable roles on a chess board, and because informative chessformer results are straightforward to scale and investigate in LLMs.


This repo's core is one engine with three frontends: engine.py is the interp core (model + hooks + logit lens + head ablation + list of values through depth). It does all of the analysis for:

  • app.py
  • interp_plot.py
  • interp_widget.py

Users are encouraged to read the user guides for each of these modules which can be found at the top of the respective scripts. Image from paper produced with the library Image from paper produced with chessformer_lens


Leela Chess Zero

This is an extremely strong engine that has many many more layers and parameters but the same square-token design as others like Maia-3.

Weights: bt4 (the base BT4 net) or bt4-332 (its policytune-332 fine-tune) download from lczero.org on first use into ~/.cache/chessformer_lens. A path to any lc0 .pb.gz works too.

Load. One alias table covers every family; none is a default.

from chessformer_lens import LeelaEngine, load_engine
eng = LeelaEngine("bt4")

Quickstart in notebook:

Recall that FEN is the modern notation for a chess position

!pip install -q https://github.com/CSSLab/maia3/archive/1e13597c42d4858b7cfd7cfdae01e297263364b2.zip
!pip install -q "chessformer_lens>=3.0"

import chess
from chessformer_lens import MaiaEngine
import chessformer_lens.interp_widget as iw

eng = MaiaEngine()          
# Opera Game FEN right at legendary queen sacrifice 
fen = "4kb1r/p2n1ppp/4q3/4p1B1/4P3/1Q6/PPP2PPP/2KR4 w k - 0 16" 
# [or insert another FEN string]

try:
    board = chess.Board(fen)
except ValueError as e:
    print(f"Invalid FEN: {e}")   

#Interact with the attention widget
#click between different layers and heads in the widget
iw.attention_widget(eng, board, 1500,layer=4,head=3) 

The app

To me, the app is the pièce de résistance and usage should be rather intuitive, nonetheless, a detailed guide can be found in chessformer_lens/app_guide.md.

Play a transformer-based chess bot ("chessformer") and watch its move policy, its attention (both semantic QKᵀ and unique geometric GAB), and — for any move you click — its logit through depth, the heads that carry it, and the neurons that carry it. The model loads on a background thread so the window opens instantly.

#Various ways to launch, note that higher parameter models have 16 and 32 heads per layer, and 512 and 1024 dim of the model (d_model):
chessformer_lens                    # no model named: opens a model picker
chessformer_lens --list             # print every engine and its aliases
chessformer_lens 23m               
chessformer_lens --model maia3-79m 
CHESSFORMER_MODEL=5m chessformer_lens
chessformer_lens bt4                # Leela Chess Zero BT4 — see above   
chessformer_lens searchless-9m      # DeepMind's searchless chess, 9M (also 136m, 270m)
chessformer_lens --web              # the same app in your web browser

Code layout: all found within the chessformer_lens package

  • __init__.py — the package surface: MaiaEngine, LeelaEngine, SearchlessEngine, load_engine, build_cfg, pick_device, Conditioning, ModelAdapter, register_adapter, available_models, attention_widget, gab_widget, __version__.
  • engine.py — the interp core (model + hooks + logit lens + head ablation + list of values through depth): ChessformerEngine holds every method and works on any model a ModelAdapter describes; MaiaEngine, LeelaEngine and SearchlessEngine are thin wrappers. No UI deps; imports cleanly in a notebook.
  • core.py — the model-agnostic layer: ModelAdapter, the adapter registry, and the types the engine speaks in (Conditioning, TokenLayout, ValueEstimate, …).
  • adapters/ — one adapter per model family: lc0.py (Leela BT4, no maia3 needed), maia3.py (Maia-3), searchless.py (DeepMind's searchless chess), smolgen.py (the smolgen/GAB attention the first two use).
  • interp_plot.py — matplotlib figures that the app uses
  • interp_widget.py — the app's two interactive panels as a self-contained notebook cell or standalone HTML page
  • piece_art.py — the cburnett pieces as PNGs, for the matplotlib figures
  • bridge.py — the game state + the JSON API the UI calls (LensApi).
  • ui.py — the whole interface (HTML/CSS/JS) as one string including guide to change template.
  • app.py — app launcher (native window via pywebview); the chessformer_lens command is its main().
  • web.py — the same app served to a web browser (chessformer_lens --web, or web.serve() in a notebook).

These come with concise but detailed docstrings.


General color guide

Blue and orange is used for diverging signed values; negative is blue, positive is orange. Viridis is used for magnitudes like attention weights. Green has to do with a specific chess move. Red has to do with undesirable things. The black and white halo lens denotes a query square.


Notes

Created by David Litman

Maia-3 comes from: Chessformer / Maia-3 (Monroe et al., ICLR 2026).

BT4 comes from the Leela Chess Zero project (lczero.org); the smolgen / attention-body design it uses is described in the Chessformer paper and in lc0's own writeups.

The searchless models come from DeepMind: Ruoss, Delétang, Medapati, Grau-Moya, Wenliang, Catt, Reid, Lewis, Veness, Genewein (2024), "Amortized Planning with Large-Scale Transformers: A Case Study on Chess", arXiv:2402.04494. Their weights are CC-BY 4.0; their tokenizer and move list are ported from the Apache-2.0 code.

Maia-3, Leela BT4 and DeepMind's searchless models are supported. The first two treat each square as a token—which allows for beautiful board readable attention patterns. The searchless models output one move's win probability per sequence and have no policy head, so the logit lens (and the depth curves built on it) does not apply to them. The core works through model adapters, so other models can plug in; for models whose stream isn't the 64 squares alone, the board views show a "not available yet" notice for now.

Please don't hesitate to give me feedback or thoughts by email found at my personal website. I hope for this to be a useful and intuitive tool for the community.


Citing

If chessformer_lens contributes to published work, a citation is very appreciated and helps others find it! Use GitHub's "Cite this repository" button, or DOI 10.5281/zenodo.21877655.

Metadata

Release files for chessformer-lens 3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for chessformer-lens 3.2
File Size Uploaded Provenance Actions
chessformer_lens-3.2.tar.gz 321.6 kB Without provenance Details for chessformer_lens-3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for chessformer-lens 3.2
File Interpreter ABI Platform Actions
chessformer_lens-3.2-py3-none-any.whl Python 3 none any Details for chessformer_lens-3.2-py3-none-any.whl

Total release size: 628.6 kB

Release files / chessformer_lens-3.2.tar.gz

Download URL chessformer_lens-3.2.tar.gz
Size 321.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1541eb0e9368fa872df3f099eb07bd57a13c4b0c38425d10711dde8d98632236
BLAKE2b-256 checksum
How to use checksums
2c1b349b02a3697ebf0e44ca803ab23055183f462f591f1e2a8b9db7391fdaba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.6

Release files / chessformer_lens-3.2-py3-none-any.whl

Download URL chessformer_lens-3.2-py3-none-any.whl
Size 307.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e652a19cc103f844785d8a2adf92dade67384a70ac6f8fce8133bccf39b4284c
BLAKE2b-256 checksum
How to use checksums
b8e2cbca4063af8671248222f58273d36b1c5b95cddcd161a2497217f4a75a60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.6

Security for chessformer-lens 3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page