CircuitsVis

Mechanistic Interpretability visualizations, that work both in both Python (e.g. with Jupyter Lab) and JavaScript (e.g. React or plain HTML).

View them all at https://transformerlensorg.github.io/CircuitsVis

Use

Install

Python

pip install circuitsvis

React

yarn add circuitsvis

Add visualizations

You can use any of the components from the demo page. These show the source code for use with React, and for Python you can instead import the function with the same name.

# Python Example
from circuitsvis.tokens import colored_tokens
colored_tokens(["My", "tokens"], [0.123, -0.226])

// React Example
import ColoredTokens from "circuitsvis";

function Example() {
    <ColoredTokens
        tokens=["My", "tokens"]
        values=[0.123, -0.266]
    />
}

Contribute

Development requirements

DevContainer

For a one-click setup of your development environment, this project includes a DevContainer. It can be used locally with VS Code or with GitHub Codespaces.

Manual setup

To create new visualizations you need Node (including yarn) and Python (with Poetry).

Once you have these, you need to install both the Node & Python packages (note that for Python we use the Poetry package management system).

cd react && yarn

cd python && poetry install --with dev

Jupyter install

If you want Jupyter as well, run poetry install --with jupyter or, if this fails due to a PyTorch bug on M1 MacBooks, run poetry run pip install jupyter.

Creating visualizations

React

You'll first want to create the visualisation in React. To do this, you can copy the example from /react/src/examples/Hello.tsx. To view changes whilst editing this (in Storybook), run the following from the /react/ directory:

yarn storybook

Python

This project uses Poetry for package management. To install run:

poetry install

Once you've created your visualization in React, you can then create a short function in the Python library to render it. You can see an example in /python/circuitsvis/examples.py.

Note that this example will render from the CDN, unless development mode is specified. Your visualization will only be available on the CDN once it has been released to the latest production version of this library.

Publishing a new release

When a new GitHub release is created, the codebase will be automatically built and deployed to PyPI.

Citation

Please cite this library as:

@misc{cooney2023circuitsvis,
    title = {CircuitsVis},
    author = {Alan Cooney and Neel Nanda},
    year = {2023},
    howpublished = {\url{https://github.com/TransformerLensOrg/CircuitsVis}},
}