lczerolens 0.4.0

Interpretability for LeelaChessZero networks.

lczerolens 🔍

Leela Chess Zero (lc0) Lens (lczerolens): a set of utilities to make interpretability easy and framework-agnostic (PyTorch): use it with tdhook, captum, zennit, or nnsight.

Getting Started

Installs

pip install lczerolens

Most examples below use models from Hugging Face Hub, so install the hf extra as well:

pip install "lczerolens[hf]"

Take the viz extra to render heatmaps and the backends extra to use the lc0 backends.

Run Models

Get the best move predicted by a model:

from lczerolens import LczeroBoard, LczeroModel

model = LczeroModel.from_hf("lczerolens/maia-1100")
board = LczeroBoard()

output = model(board)
best_move_idx = output["policy"].argmax()
print(board.decode_move(best_move_idx))

Framework-Agnostic Interpretability

Use lczerolens with your preferred PyTorch interpretability framework (tdhook, captum, zennit, nnsight). More examples in the framework-agnostic interpretability notebook.

from lczerolens import LczeroBoard, LczeroModel
from tdhook.attribution import Saliency
from tensordict import TensorDict

model = LczeroModel.from_hf("lczerolens/maia-1100")
board = LczeroBoard()

def best_logit_init_targets(td: TensorDict, _):
    policy = td["policy"]
    best_logit = policy.max(dim=-1).values
    return TensorDict(out=best_logit, batch_size=td.batch_size)

saliency_context = Saliency(init_attr_targets=best_logit_init_targets)
with saliency_context.prepare(model) as hooked_model:
    output = hooked_model(TensorDict(board=model.prepare_boards(board), batch_size=1))
    attr = output.get(("attr", "board"))

Features

• Encode Boards:
• Load Models:
• Move Prediction:
• Run Models on GPU:
• Evaluate Models on Puzzles:
• Convert Official Weights:
• Visualise Heatmaps:
• Probe Concepts:

Tutorials

• Walkthrough:
• Framework-Agnostic Interpretability:
• More to come...

Demo

Spaces

Some Hugging Face Spaces are available to try out the library. The demo (:red_circle: in construction) will showcase some of the features of the library and the backends demo makes the conversion of lc0 models to onnx easy.

• Lczerolens Demo: Showcase some of the features of the library.
• Lczerolens Backends Demo: Make the conversion of lc0 models to onnx easy.
• Lczerolens Puzzles Leaderboard: Coming soon...

Local Demo

Additionally, you can run the gradio demos locally. First you'll need to clone the spaces (after cloning the repo):

git clone https://huggingface.co/spaces/lczerolens/demo spaces/demo

And optionally the backends demo:

git clone https://huggingface.co/spaces/lczerolens/backends-demo spaces/backends-demo

And then launch the demo (running on port 8000):

just demo

To test the backends use:

just demo-backends

Full Documentation

See the full documentation.

Contribute

See the guidelines in CONTRIBUTING.md.

Citation

If you're using lczerolens in your research, please cite it using the following BibTeX entry:

@software{poupart_lczerolens_2026,
  author = {Poupart, Yoann},
  title = {LCZeroLens},
  version = {0.4.0},
  year = {2026},
  url = {https://github.com/Xmaster6y/lczerolens}
}

License

lczerolens is licensed under the MIT License. See LICENSE for details.