chessformer_lens

An interpretability lens for square-token chess transformers.

chessformer_lens reads the internals of chess models that represent the board as 64 square tokens with a from×to policy head — the "chessformer" architecture family (MAIA-3 today; Leela Chess Zero's BT transformers next). It is to chess transformers roughly what TransformerLens is to language models: instrumentation for looking at what the network computes, not just what it plays.

Status: pre-alpha (0.0.1). This release reserves the package name. The functional API is being extracted from a working MAIA-3 research harness and lands next. Watch the repo if you want the first usable cut.

What it will expose

• Logit-lens depth curves — track any move's logit / probability / rank at every readout point of the residual stream and watch it "snap" into the model's plan.
• Causal ablation grids — remove a single attention head's exact write and measure the effect on a move, across the full block×head grid. Sign convention: Δ = ablated − clean, so a positive Δ means the head was suppressing the move and a negative Δ means it was carrying it.
• Attention decomposition — per-head attention maps split into geometry vs. semantics, for asking which head routes which relationship on the board.
• Skill-conditioned diffs — for models with a skill/Elo embedding (e.g. MAIA), diff the same position at two ratings, activation-by-activation, to see where expertise lives.

Design

The coupling to any specific engine lives behind a small adapter (residual-stream readout points, hookable forward pass, exact per-head writes, and a policy-logit decode). Any square-token transformer with a from×to policy head can be plugged in — which is why the roadmap is MAIA-3 → Lc0-BT, the two current members of that family.

Roadmap

• 0.1 — MAIA-3 backend: logit lens, ablation grids, attention maps, skill diffs
• Lc0-BT backend (weight conversion + Smolgen handling)
• Interactive board-native visualizer

License

MIT © 2026 David Litman

Citing

If chessformer_lens contributes to published work, a citation helps others find it — see CITATION.cff (GitHub's "Cite this repository" button) once the first release is out.