https://github.com/xmaster6y/lczerolens
🔬 Interpretability for Leela Chess Zero networks.
https://github.com/xmaster6y/lczerolens
chess lc0 xai
Last synced: 24 days ago
JSON representation
🔬 Interpretability for Leela Chess Zero networks.
- Host: GitHub
- URL: https://github.com/xmaster6y/lczerolens
- Owner: Xmaster6y
- License: mit
- Created: 2024-01-18T15:27:27.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-02T09:08:30.000Z (about 1 month ago)
- Last Synced: 2025-09-02T10:08:18.866Z (about 1 month ago)
- Topics: chess, lc0, xai
- Language: Python
- Homepage: https://lczerolens.readthedocs.io
- Size: 1.66 MB
- Stars: 15
- Watchers: 5
- Forks: 3
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# lczerolens 🔍
[](https://lczerolens.readthedocs.io)
[](https://pypi.org/project/lczerolens/)
[](https://github.com/Xmaster6y/lczerolens/blob/main/LICENSE)
[](https://github.com/astral-sh/uv)
[](https://github.com/astral-sh/ruff)
[](https://www.python.org/downloads/)
[](https://codecov.io/gh/Xmaster6y/lczerolens)
[](https://lczerolens.readthedocs.io/en/latest/?badge=latest)
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
```bash
pip install lczerolens
```
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:
```python
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](https://lczerolens.readthedocs.io/en/latest/notebooks/tutorials/framework-agnostic-interpretability.html).
```python
from lczerolens import LczeroBoard, LczeroModel
model = LczeroModel.from_hf("lczerolens/maia-1100")
board = LczeroBoard()
# TODO: complete this example
```
### Features
- [Encode Boards](https://lczerolens.readthedocs.io/en/latest/notebooks/features/encode-boards.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/features/encode-boards.ipynb)
- [Load Models](https://lczerolens.readthedocs.io/en/latest/notebooks/features/load-models.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/features/load-models.ipynb)
- [Move Prediction](https://lczerolens.readthedocs.io/en/latest/notebooks/features/move-prediction.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/features/move-prediction.ipynb)
- [Run Models on GPU](https://lczerolens.readthedocs.io/en/latest/notebooks/features/run-models-on-gpu.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/features/run-models-on-gpu.ipynb)
- [Evaluate Models on Puzzles](https://lczerolens.readthedocs.io/en/latest/notebooks/features/evaluate-models-on-puzzles.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/features/evaluate-models-on-puzzles.ipynb)
- [Convert Official Weights](https://lczerolens.readthedocs.io/en/latest/notebooks/features/convert-official-weights.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/features/convert-official-weights.ipynb)
- [Visualise Heatmaps](https://lczerolens.readthedocs.io/en/latest/notebooks/features/visualise-heatmaps.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/features/visualise-heatmaps.ipynb)
- [Probe Concepts](https://lczerolens.readthedocs.io/en/latest/notebooks/features/probe-concepts.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/features/probe-concepts.ipynb)
### Tutorials
- [Walkthrough](https://lczerolens.readthedocs.io/en/latest/notebooks/walkthrough.html): [](https://colab.research.google.com/github/Xmaster6y/docs/source/notebooks/walkthrough.ipynb)
- [Framework-Agnostic Interpretability](https://lczerolens.readthedocs.io/en/latest/notebooks/tutorials/framework-agnostic-interpretability.html): [](https://colab.research.google.com/github/Xmaster6y/lczerolens/blob/main/docs/source/notebooks/tutorials/framework-agnostic-interpretability.ipynb)
- More to come...
## Demo
### Spaces
Some [Hugging Face Spaces](https://huggingface.co/spaces/lczerolens) 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](https://huggingface.co/spaces/lczerolens/demo)
- [Lczerolens Backends Demo](https://huggingface.co/spaces/lczerolens/backends-demo)
- [Lczerolens Puzzles Leaderboard](https://huggingface.co/spaces/lczerolens/puzzles-leaderboard)
### Local Demo
Additionally, you can run the gradio demos locally. First you'll need to clone the spaces (after cloning the repo):
```bash
git clone https://huggingface.co/spaces/lczerolens/demo spaces/demo
```
And optionally the backends demo:
```bash
git clone https://huggingface.co/spaces/lczerolens/backends-demo spaces/backends-demo
```
And then launch the demo (running on port `8000`):
```bash
just demo
```
To test the backends use:
```bash
just demo-backends
```
## Full Documentation
See the full [documentation](https://lczerolens.readthedocs.io).
## Contribute
See the guidelines in [CONTRIBUTING.md](CONTRIBUTING.md).