Metadata-Version: 2.4
Name: chessformer_lens
Version: 0.0.1
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 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](https://lczero.org)'s BT transformers next). It is to
chess transformers roughly what [TransformerLens](https://github.com/TransformerLensOrg/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.
