Metadata-Version: 2.4
Name: chessformer_lens
Version: 0.0.2
Summary: An interpretability lens for square-token chess transformers (MAIA-3 backend; Lc0-BT next).
Author-email: David Litman <david.litman1@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/chessformer-lens/chessformer_lens
Project-URL: Repository, https://github.com/chessformer-lens/chessformer_lens
Project-URL: Issues, https://github.com/chessformer-lens/chessformer_lens/issues
Keywords: chess,transformer,mechanistic-interpretability,interpretability,maia,leela,lc0,attention,logit-lens,ablation
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# chessformer_lens

**An mechanistic interpretability lens and visualize for square-token chess transformers.**


![chessformer_lens live visualizer](https://raw.githubusercontent.com/chessformer-lens/chessformer_lens/main/screenshot.png)

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.
