chessformer_lens

A mechanistic interpretability lens and visualizer for square-token chess transformers.

Play a transformer based chess bot (Maia 3) trained to mimic human play and watch its move policy, its attention (self attention vs unique geometric attention), and how its residual stream evolves with depth LIVE.

Visualize mechanistic interpretability tools like logit lens and head ablations.

Take the geometric attention bias (GAB / "smolgen") apart live, see the 64 static templates every layer shares, and the linear combination of templates used for a pair of squares or go move centric with move microscope: one move's logit at all residual readout points. Ablate any head with a click and see the causal effects. Drag the ELO slider to re-evaluate a position at different skill levels.

Code layout

• engine.py — MaiaEngine: the interp core (model + hooks + logit lens + head ablation). No UI deps; imports cleanly in a notebook.
• bridge.py — game state + the JSON API the UI calls.
• ui.py — the whole interface (HTML/CSS/JS) as one string.
• pieces.py — SVG piece set as data URIs.
• app.py — launcher (native window via pywebview).

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.