### Setup Environment and Install Dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Interactive_Neuroscope.ipynb

Configures the environment for Colab or VSCode and installs necessary libraries like transformer_lens, gradio, and datasets. Use this for initial setup.

```python
# NBVAL_IGNORE_OUTPUT
# Janky code to do different setup when run in a Colab notebook vs VSCode
import os

DEVELOPMENT_MODE = True
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab

    IN_COLAB = True
    print("Running as a Colab notebook")
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")

if IN_COLAB or IN_GITHUB:
    %pip install transformer_lens
    %pip install gradio
    %pip install datasets==2.19.1
```

--------------------------------

### Setup Environment and Install Dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/No_Position_Experiment.ipynb

Configures the environment for Colab or GitHub Actions, installing necessary libraries like einops and transformer_lens. It also includes commented-out code for PySvelte.

```python
# NBVAL_IGNORE_OUTPUT
import os

# Janky code to do different setup when run in a Colab notebook vs VSCode
DEVELOPMENT_MODE = False
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab

    IN_COLAB = True
    print("Running as a Colab notebook")
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")

if IN_COLAB or IN_GITHUB:
    %pip install einops
    %pip install transformer_lens@v1.15.0

    # PySvelte is an unmaintained visualization library, use it as a backup if circuitsvis isn't working
    # # Install another version of node that makes PySvelte work way faster
    # !curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -; sudo apt-get install -y nodejs
    # %pip install git+https://github.com/neelnanda-io/PySvelte.git

from transformer_lens import HookedTransformer, HookedTransformerConfig
import torch
import numpy as np
import plotly.express as px
import plotly.io as pio

pio.renderers.default = "colab"
import tqdm.auto as tqdm
import einops
from transformer_lens.utilities import to_numpy

device = "cuda" if torch.cuda.is_available() else "cpu"
```

--------------------------------

### Install default dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/README.md

Use this command for a standard contributor setup to install all default dependency groups.

```bash
uv sync
```

--------------------------------

### Setup Environment and Install Packages

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/LIT_Integration_Demo.ipynb

Detects the environment (Colab or local) and installs necessary packages like transformer_lens and lit-nlp if running in Colab. Includes optional autoreload for development.

```python
# Detect environment
import os

DEVELOPMENT_MODE = False

# Detect if we're running in Google Colab
try:
    import google.colab
    IN_COLAB = True
    print("Running in Google Colab")
except ImportError:
    IN_COLAB = False
    print("Running locally (VSCode/Jupyter)")

# Install packages if in Colab
if IN_COLAB:
    %pip install -q transformer_lens lit-nlp

# Hot reload in development mode
if not IN_COLAB and DEVELOPMENT_MODE:
    from IPython import get_ipython
    ip = get_ipython()
    if ip is not None and not ip.extension_manager.loaded:
        ip.extension_manager.load('autoreload')
        %autoreload 2
```

--------------------------------

### Environment Setup and Dependency Installation

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Othello_GPT.ipynb

Configures the environment for either Google Colab or local Jupyter notebooks, installing necessary libraries like transformer_lens and circuitsvis.

```python
# NBVAL_IGNORE_OUTPUT
import os

# Janky code to do different setup when run in a Colab notebook vs VSCode
DEVELOPMENT_MODE = False
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab

    IN_COLAB = True
    print("Running as a Colab notebook")

    # PySvelte is an unmaintained visualization library, use it as a backup if circuitsvis isn't working
    # # Install another version of node that makes PySvelte work way faster
    # !curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -; sudo apt-get install -y nodejs
    # %pip install git+https://github.com/neelnanda-io/PySvelte.git
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")

if IN_COLAB or IN_GITHUB:
    %pip install transformer_lens
    %pip install circuitsvis
```

--------------------------------

### Basic Hello World Example

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/T5.ipynb

A simple example demonstrating the basic functionality of the library.

```python
cv.examples.hello("Neel")
```

--------------------------------

### Environment Setup and Dependency Installation

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Grokking_Demo.ipynb

Detects the execution environment (Colab vs. local) and installs necessary packages.

```python
# Janky code to do different setup when run in a Colab notebook vs VSCode
import os

DEVELOPMENT_MODE = True
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
    
    # PySvelte is an unmaintained visualization library, use it as a backup if circuitsvis isn't working
    # # Install another version of node that makes PySvelte work way faster
    # !curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -; sudo apt-get install -y nodejs
    # %pip install git+https://github.com/neelnanda-io/PySvelte.git
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")
    
if IN_COLAB or IN_GITHUB:
    %pip install transformer_lens
    %pip install circuitsvis
```

--------------------------------

### Environment Setup and Dependency Installation

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Bridge_Evals_Demo.ipynb

Configures the environment for Colab or GitHub Actions and installs necessary dependencies including transformer_lens and lm-eval.

```python
# NBVAL_IGNORE_OUTPUT
import os

IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab

    IN_COLAB = True
    print("Running as a Colab notebook")
except ImportError:
    IN_COLAB = False

if not IN_GITHUB and not IN_COLAB:
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")

if IN_COLAB or IN_GITHUB:
    %pip install transformer_lens
    %pip install lm-eval
```

--------------------------------

### Install and Import Dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/direct_path_patching_ioi.ipynb

Sets up the environment by installing transformer_lens and importing necessary modules.

```python
# NBVAL_IGNORE_OUTPUT
import os
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
    %pip install transformer_lens
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook")
```

```python
import torch
from transformer_lens import HookedTransformer
from transformer_lens.direct_path_patching import get_act_patch_direct_path
```

--------------------------------

### Setup Environment and Install Dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/T5.ipynb

Installs necessary libraries like transformer_lens, torchtyping, circuitsvis, and specific versions of typeguard. It also configures Plotly renderers based on the execution environment (Colab vs. others).

```python
# NBVAL_IGNORE_OUTPUT
# Janky code to do different setup when run in a Colab notebook vs VSCode
import os

DEBUG_MODE = False
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab

    IN_COLAB = True
    print("Running as a Colab notebook")
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")

if IN_COLAB or IN_GITHUB:
    %pip install transformer_lens
    %pip install torchtyping
    # Install my janky personal plotting utils
    %pip install git+https://github.com/TransformerLensOrg/neel-plotly.git
    # Install another version of node that makes PySvelte work way faster
    %pip install circuitsvis
    # Needed for PySvelte to work, v3 came out and broke things...
    %pip install typeguard==2.13.3
```

```python
# Plotly needs a different renderer for VSCode/Notebooks vs Colab argh
import plotly.io as pio

if IN_COLAB or not DEBUG_MODE:
    # Thanks to annoying rendering issues, Plotly graphics will either show up in colab OR Vscode depending on the renderer - this is bad for developing demos! Thus creating a debug mode.
    pio.renderers.default = "colab"
else:
    pio.renderers.default = "notebook_connected"
```

--------------------------------

### setup

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.md

Initializes the model structure and hook points.

```APIDOC
## setup()

### Description
Sets up the model. This function must be called in the model’s __init__ method AFTER defining all layers. It adds a parameter to each module containing its name, builds a dictionary mapping module names to instances, and initializes a hook dictionary for modules of type “HookPoint”.
```

--------------------------------

### setup

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.HookedRootModule.md

Initializes the model structure, mapping module names to instances and setting up hook dictionaries.

```APIDOC
## setup

### Description
Sets up the model by mapping module names to instances and initializing hook dictionaries for modules of type 'HookPoint'. This must be called in the model's __init__ method after all layers are defined.
```

--------------------------------

### Setup for Colab/Jupyter Environment

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Head_Detector_Demo.ipynb

Installs necessary libraries like transformer_lens, circuitsvis, and neel-plotly. It includes logic to detect if the code is running in Google Colab or a local Jupyter environment and adjusts setup accordingly.

```python
# NBVAL_IGNORE_OUTPUT
# Janky code to do different setup when run in a Colab notebook vs VSCode
import os

DEVELOPMENT_MODE = False
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
except:
    IN_COLAB = False

if not IN_GITHUB and not IN_COLAB:
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")

if IN_COLAB:
    %pip install transformer_lens
    %pip install circuitsvis
    %pip install git+https://github.com/neelnanda-io/neel-plotly.git
```

--------------------------------

### Example package file structure

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/content/adapter_development/external-adapter-registration.md

Recommended directory layout for a package containing a custom architecture adapter.

```text
my_transformer_plugin/
├── pyproject.toml          # declares the entry point
└── my_transformer_plugin/
    ├── __init__.py
    └── adapters.py         # contains MyArchitectureAdapter
```

--------------------------------

### Setup for Colab/VSCode Environment

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/SVD_Interpreter_Demo.ipynb

Installs necessary libraries and configures the environment for TransformerLens and its dependencies. Includes specific versions for PySvelte and typeguard for compatibility.

```python
# Janky code to do different setup when run in a Colab notebook vs VSCode
DEBUG_MODE = False
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
    %pip install git+https://github.com/JayBaileyCS/TransformerLens.git # TODO: Change!
    # Install Neel's personal plotting utils
    %pip install git+https://github.com/neelnanda-io/neel-plotly.git
    # Install another version of node that makes PySvelte work way faster
    !curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -; sudo apt-get install -y nodejs
    %pip install git+https://github.com/neelnanda-io/PySvelte.git
    # Needed for PySvelte to work, v3 came out and broke things...
    %pip install typeguard==2.13.3
    %pip install typing-extensions
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")
```

```python
# Plotly needs a different renderer for VSCode/Notebooks vs Colab argh
import plotly.io as pio

if IN_COLAB or not DEBUG_MODE:
    # Thanks to annoying rendering issues, Plotly graphics will either show up in colab OR Vscode depending on the renderer - this is bad for developing demos! Thus creating a debug mode.
    pio.renderers.default = "colab"
else:
    pio.renderers.default = "png"
```

--------------------------------

### Install TransformerLens

Source: https://github.com/transformerlensorg/transformerlens/blob/main/README.md

Standard installation command for the library.

```shell
pip install transformer_lens
```

--------------------------------

### Install documentation dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/README.md

Use this command to install only the documentation group for a focused environment.

```bash
uv sync --no-default-groups --group docs
```

--------------------------------

### serve()

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.lit.md

Starts a LIT server to facilitate interactive exploration of models and datasets.

```APIDOC
## transformer_lens.lit.serve(models: Dict[str, Any] | Any, datasets: Dict[str, Any] | Any, port: int = 5432, host: str = 'localhost', page_title: str = 'TransformerLens + LIT', **kwargs) → None

### Description
Start a LIT server with the given models and datasets. This is a convenience function to quickly start a LIT server for interactive model exploration.

* **Parameters:**
  * **models** – Either a single HookedTransformer/HookedTransformerLIT, or a dictionary mapping model names to model wrappers.
  * **datasets** – Either a single dataset, or a dictionary mapping dataset names to datasets.
  * **port** – Port number for the server.
  * **host** – Host address for the server.
  * **page_title** – Title shown in the browser tab.
  * **kwargs** – Additional arguments passed to LIT server.

### Example
```pycon
>>> from transformer_lens import HookedTransformer
>>> from transformer_lens.lit import SimpleTextDataset, serve
>>> 
>>> model = HookedTransformer.from_pretrained("gpt2-small")
>>> dataset = SimpleTextDataset.from_strings(["Hello world!"])
>>> 
>>> # Simple usage with single model and dataset
>>> serve(model, dataset)
>>> 
>>> # Or with explicit names
>>> serve({"gpt2": model}, {"examples": dataset})
```

#### NOTE
This function will block and run the server. Press Ctrl+C to stop.
```

--------------------------------

### Setup Environment for Colab/Jupyter

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Attribution_Patching_Demo.ipynb

Configures the environment based on whether it's running in Google Colab, GitHub Actions, or a local Jupyter notebook. Installs necessary libraries like transformer_lens, torchtyping, neel-plotly, circuitsvis, and typeguard.

```python
# NBVAL_IGNORE_OUTPUT
# Janky code to do different setup when run in a Colab notebook vs VSCode
import os

DEBUG_MODE = False
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab

    IN_COLAB = True
    print("Running as a Colab notebook")
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")

if IN_COLAB or IN_GITHUB:
    %pip install transformer_lens
    %pip install torchtyping
    # Install my janky personal plotting utils
    %pip install git+https://github.com/neelnanda-io/neel-plotly.git
    # Install another version of node that makes PySvelte work way faster
    %pip install circuitsvis
    # Needed for PySvelte to work, v3 came out and broke things...
    %pip install typeguard==2.13.3
```

--------------------------------

### Setup Environment for TransformerLens

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Patchscopes_Generation_Demo.ipynb

Configures the environment for running TransformerLens, handling differences between Colab, GitHub Actions, and local Jupyter notebooks. Installs necessary libraries like transformer_lens, torchtyping, neel-plotly, circuitsvis, and typeguard.

```python
# NBVAL_IGNORE_OUTPUT
# Janky code to do different setup when run in a Colab notebook vs VSCode
import os

DEBUG_MODE = False
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"
try:
    import google.colab

    IN_COLAB = True
    print("Running as a Colab notebook")
except:
    IN_COLAB = False

if not IN_GITHUB and not IN_COLAB:
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")

if IN_COLAB or IN_GITHUB:
    %pip install transformer_lens
    %pip install torchtyping
    # Install my janky personal plotting utils
    %pip install git+https://github.com/neelnanda-io/neel-plotly.git
    # Install another version of node that makes PySvelte work way faster
    %pip install circuitsvis
    # Needed for PySvelte to work, v3 came out and broke things...
    %pip install typeguard==2.13.3

import torch
from typing import List, Callable, Tuple, Union
from functools import partial
from jaxtyping import Float
from transformer_lens.model_bridge import TransformerBridge
from transformer_lens.ActivationCache import ActivationCache
import transformer_lens.utils as utils
from transformer_lens.hook_points import (
    HookPoint,
)  # Hooking utilities
```

--------------------------------

### Install LIT

Source: https://github.com/transformerlensorg/transformerlens/blob/main/transformer_lens/lit/README.md

Command to install the LIT library if it is not found.

```bash
pip install lit-nlp
```

--------------------------------

### Install Quantization Dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/LLaMA_GPU_Quantized.ipynb

Install the necessary packages for 4-bit quantization support.

```bash
uv sync --group quantization
```

--------------------------------

### Quick Start: Load Model and Serve LIT

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.lit.md

Load a TransformerLens model, wrap it with HookedTransformerLIT, create a dataset, and start the LIT server. This is the primary way to use LIT with TransformerLens.

```python
from transformer_lens import HookedTransformer
from transformer_lens.lit import HookedTransformerLIT, SimpleTextDataset, serve

# Load model and create LIT wrapper
model = HookedTransformer.from_pretrained("gpt2-small")
lit_model = HookedTransformerLIT(model)

# Create a dataset
dataset = SimpleTextDataset.from_strings([
    "The capital of France is Paris.",
    "Machine learning is a field of AI.",
])

# Start LIT server
serve({"gpt2": lit_model}, {"examples": dataset})
```

--------------------------------

### transformer_lens.lit.utils.batch_examples

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.lit.utils.md

Split examples into batches for LIT integration.

```APIDOC
## transformer_lens.lit.utils.batch_examples(examples: List[Dict[str, Any]], batch_size: int) -> List[List[Dict[str, Any]]]

### Description
Split examples into batches.

### Parameters
#### Parameters
- **examples** (List[Dict[str, Any]]) - List of example dictionaries.
- **batch_size** (int) - Size of each batch.

### Returns
List of batches, where each batch is a list of examples.
```

--------------------------------

### Initialize SimpleTextDataset

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.lit.dataset.md

Create a dataset holding simple text examples. Each example is a dictionary with a 'text' field, suitable for basic text analysis tasks.

```python
>>> dataset = SimpleTextDataset([
...     {"text": "Hello world"},
...     {"text": "How are you?"},
... ])
>>> len(dataset.examples)
2
```

--------------------------------

### Verify CircuitsVis installation

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/BERT.ipynb

Tests the CircuitsVis library by rendering a hello message.

```python
import circuitsvis as cv

# Testing that the library works
cv.examples.hello("Neel")
```

--------------------------------

### Install TransformerLens with LIT support

Source: https://github.com/transformerlensorg/transformerlens/blob/main/transformer_lens/lit/README.md

Use this command to install TransformerLens with all necessary dependencies for LIT integration.

```bash
pip install transformer-lens[lit]
```

--------------------------------

### Example pyproject.toml configuration

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/content/adapter_development/external-adapter-registration.md

Complete configuration for a plugin package including dependencies and entry point registration.

```toml
[project]
name = "my-transformer-plugin"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["transformer-lens>=3.0"]

[project.entry-points."transformer_lens.architectures"]
"MyModelForCausalLM" = "my_transformer_plugin.adapters:MyArchitectureAdapter"
```

--------------------------------

### Run documentation hot-reloading

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/README.md

Starts a development server with hot-reloading enabled for documentation changes.

```bash
uv run docs-hot-reload
```

--------------------------------

### Example adapter implementation

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/content/adapter_development/external-adapter-registration.md

Skeleton code for defining a custom adapter class inheriting from ArchitectureAdapter.

```python
from transformer_lens.model_bridge.architecture_adapter import ArchitectureAdapter
from transformer_lens.model_bridge.generalized_components import (
    BlockBridge,
    EmbeddingBridge,
    # ... import the bridge components you need
)

class MyArchitectureAdapter(ArchitectureAdapter):
    def __init__(self, cfg):
        super().__init__(cfg)
        # Set config, weight processing, component mapping
        # See the Adapter Creation Guide for details
```

--------------------------------

### Serve LIT

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.lit.md

Starts the LIT server with the provided models and datasets.

```APIDOC
## Function: serve

### Description
Starts the LIT server with the provided models and datasets.

### Parameters
* **models** – A dictionary mapping model names to LIT model wrappers.
* **datasets** – A dictionary mapping dataset names to LIT datasets.

### Example
```pycon
>>> from transformer_lens import HookedTransformer
>>> from transformer_lens.lit import HookedTransformerLIT, SimpleTextDataset, serve
>>> model = HookedTransformer.from_pretrained("gpt2-small")
>>> lit_model = HookedTransformerLIT(model)
>>> dataset = SimpleTextDataset.from_strings([
...     "The capital of France is Paris.",
...     "Machine learning is a field of AI.",
... ])
>>> serve({"gpt2": lit_model}, {"examples": dataset})
```
```

--------------------------------

### Configure Environment and Dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/LLaMA.ipynb

Sets up the environment for either Colab or local development and installs necessary packages.

```python
# NBVAL_IGNORE_OUTPUT
# Janky code to do different setup when run in a Colab notebook vs VSCode
import os
os.environ["TOKENIZERS_PARALLELISM"] = "false"

DEVELOPMENT_MODE = False
IN_VSCODE = False
IN_GITHUB = os.getenv("GITHUB_ACTIONS") == "true"

try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")

if IN_GITHUB or IN_COLAB:
    %pip install transformer_lens
    %pip install circuitsvis
    %pip install sentencepiece

# Plotly needs a different renderer for VSCode/Notebooks vs Colab argh
import plotly.io as pio
if IN_COLAB or not DEVELOPMENT_MODE:
    pio.renderers.default = "colab"
else:
    pio.renderers.default = "notebook_connected"
print(f"Using renderer: {pio.renderers.default}")

import circuitsvis as cv
```

--------------------------------

### Register in __init__.py

Source: https://github.com/transformerlensorg/transformerlens/blob/main/transformer_lens/model_bridge/supported_architectures/AGENTS.md

Import the new adapter and add it to the __all__ list to ensure it is available at boot.

```python
from transformer_lens.model_bridge.supported_architectures.myarch import (
    MyArchitectureAdapter,
)
```

--------------------------------

### __init__

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.model_bridge.supported_architectures.qwen3_moe.md

Initializes the Qwen3MoE architecture adapter with the provided configuration.

```APIDOC
#### __init__(cfg: Any) → None

Initialize the Qwen3MoE architecture adapter.
```

--------------------------------

### Build documentation once

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/README.md

Executes a single build of the documentation.

```bash
uv run build-docs
```

--------------------------------

### Basic Model Configuration Example

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Config_Overhaul.ipynb

Demonstrates how a user might instantiate and configure a model using the proposed `ModelConfig` class. It shows setting core parameters and enabling/customizing specific features.

```python
config = ModelConfig(
    d_model=4096,
    d_head=8192 // 64,
    n_heads=64,
    act_fn="silu"
    # Other universally required properties across all models go here in the constructor
)
# Enabling specific features not universal among all models
config.enabled_gated_mlp()
# Customizing optional attributes
config.set_positional_embedding_type("alibi")

# and so on, until the full configuration is set


```

--------------------------------

### Import libraries and configure environment

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Gemma3_Multimodal.ipynb

Sets up the device, imports required modules, and initializes the TransformerBridge.

```python
# NBVAL_IGNORE_OUTPUT
import torch
from PIL import Image
import requests
from io import BytesIO

device = 'cuda' if torch.cuda.is_available() else 'cpu'

import matplotlib.pyplot as plt
%matplotlib inline

from transformer_lens.model_bridge import TransformerBridge

try:
    import circuitsvis as cv
except ImportError:
    print('circuitsvis not installed, attention visualization will not work')
    cv = None
```

--------------------------------

### Setup Environment for Colab vs. VSCode

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Activation_Patching_in_TL_Demo.ipynb

Configures the environment by installing necessary libraries like transformer_lens and neel-plotly. It detects if running in Google Colab or a local Jupyter environment and adjusts package installations and notebook reloads accordingly.

```python
# Janky code to do different setup when run in a Colab notebook vs VSCode
DEBUG_MODE = False
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
    %pip install transformer_lens
    # Install my janky personal plotting utils
    %pip install git+https://github.com/neelnanda-io/neel-plotly.git
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the TransformerBridge code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")
```

--------------------------------

### Call Get Source Representation

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Patchscopes_Generation_Demo.ipynb

Example usage of the `get_source_representation` function to extract hidden states from a specific layer and position.

```python
source_rep = get_source_representation(
    prompts=["Patchscopes is a nice tool to inspect hidden representation of language model"],
    layer_id=2,
    model=model,
    pos_id=5
)
```

--------------------------------

### Setup Environment for TransformerLens

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/stable_lm.ipynb

Configures the environment for running TransformerLens, detecting whether it's in a Colab notebook or a Jupyter environment. Installs the library if in Colab.

```python
# Janky code to do different setup when run in a Colab notebook vs VSCode
DEVELOPMENT_MODE = False
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
    %pip install git+https://github.com/TransformerLensOrg/TransformerLens.git
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    from IPython import get_ipython

    ipython = get_ipython()
    # Code to automatically update the HookedTransformer code as its edited without restarting the kernel
    ipython.run_line_magic("load_ext", "autoreload")
    ipython.run_line_magic("autoreload", "2")
```

--------------------------------

### Environment Setup and Development Commands

Source: https://github.com/transformerlensorg/transformerlens/blob/main/AGENTS.md

Use these bash commands to bootstrap the environment, run tests, format code, and manage documentation. Note that these commands require a Unix-like environment and are not compatible with PowerShell.

```bash
# Bootstrap uv if missing
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install — uv only (not pip, not poetry)
uv sync
source .venv/bin/activate

# First-time only: create .env from the template, then fill in HF_TOKEN
cp .env.example .env

# Source HF token before any HF-Hub-hitting command
set -a; source .env; set +a

# Tests
make unit-test          # fast, no model loads
make integration-test   # cross-component
make acceptance-test    # end-to-end
make docstring-test     # doctest + doctest-plus
make notebook-test      # slow; subset run in CI
make test-pr            # unit + docstring + acceptance + integration (PR-review surface)
make test               # everything (long; includes benchmarks + notebooks)

# Format + typecheck — no pre-commit hook; run manually before push
make format             # pycln + isort + black
make check-format       # CI-equivalent check
uv run mypy .

# Docs
uv run docs-hot-reload  # live preview
uv run build-docs       # build to docs/build/
```

--------------------------------

### setup_component_testing

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.model_bridge.supported_architectures.openelm.md

Sets up references for OpenELM component testing.

```APIDOC
#### setup_component_testing(hf_model: Any, bridge_model: Any = None) -> None

Set up references for OpenELM component testing.

* **Parameters:**
  * **hf_model** – The HuggingFace OpenELM model instance
  * **bridge_model** – The TransformerBridge model (if available)
```

--------------------------------

### transformer_lens.patching.get_act_patch_resid_pre

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.patching.md

Function to get activation patching results for the residual stream (at the start of each block) (by position). Returns a tensor of shape [n_layers, pos]. See generic_activation_patch for a more detailed explanation of activation patching.

```APIDOC
## transformer_lens.patching.get_act_patch_resid_pre

### Description
Function to get activation patching results for the residual stream (at the start of each block) (by position). Returns a tensor of shape [n_layers, pos].

See generic_activation_patch for a more detailed explanation of activation patching.

### Parameters
* **model** – The relevant model
* **corrupted_tokens** (*torch.Tensor*) – The input tokens for the corrupted run. Has shape [batch, pos]
* **clean_cache** (*ActivationCache*) – The cached activations from the clean run
* **patching_metric** – A function from the model’s output logits to some metric (eg loss, logit diff, etc)
* **patch_setter** (*Callable[[CorruptedActivation, Sequence[int], ActivationCache], PatchedActivation]*, optional) – Defaults to <function layer_pos_patch_setter>.
* **activation_name** (*str*, optional) – Defaults to 'resid_pre'.
* **index_axis_names** (*Optional[Sequence[AxisNames]]*, optional) – Defaults to ('layer', 'pos').
* **index_df** (*Optional[pd.DataFrame]*, optional) – Defaults to None.
* **return_index_df** (*bool*, optional) – Defaults to False.

### Returns
The tensor of the patching metric for each resid_pre patch. Has shape [n_layers, pos]

### Return type
patched_output (torch.Tensor)
```

--------------------------------

### Setup Imports and Device Configuration

Source: https://github.com/transformerlensorg/transformerlens/blob/main/debugging/hf-tl-logit-comparator.ipynb

Imports necessary libraries and sets up the computation device (MPS, CUDA, or CPU). Disables gradient calculation for efficiency.

```python
from transformers import AutoTokenizer, AutoModelForCausalLM
from transformer_lens import HookedTransformer
import torch
import torch.nn.functional as F

if torch.backends.mps.is_available():
    device = "mps"
else:
    device = "cuda" if torch.cuda.is_available() else "cpu"

# NBVAL_IGNORE_OUTPUT
_ = torch.set_grad_enabled(False)
```

--------------------------------

### SymbolicBridge Initialization Example

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.model_bridge.generalized_components.symbolic.md

Demonstrates how to initialize a SymbolicBridge for a model like OPT, which lacks an 'mlp' container. Submodules like 'in' and 'out' (mapping to 'fc1' and 'fc2') are defined within the bridge. These submodules will be accessible via the parent component after setup.

```python
mlp: SymbolicBridge(
  submodules={
    "in": LinearBridge(name="fc1"),
    "out": LinearBridge(name="fc2"),
  },
)
```

--------------------------------

### transformer_lens.patching.get_act_patch_block_every

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.patching.md

Helper function to get activation patching results for the residual stream (at the start of each block), output of each Attention layer and output of each MLP layer. Wrapper around each’s patching function, returns a stacked tensor of shape [3, n_layers, pos].

```APIDOC
## transformer_lens.patching.get_act_patch_block_every

### Description
Helper function to get activation patching results for the residual stream (at the start of each block), output of each Attention layer and output of each MLP layer. Wrapper around each’s patching function, returns a stacked tensor of shape [3, n_layers, pos].

### Parameters
* **model** – The relevant model
* **corrupted_tokens** (*torch.Tensor*) – The input tokens for the corrupted run. Has shape [batch, pos]
* **clean_cache** (*ActivationCache*) – The cached activations from the clean run
* **metric** – A function from the model’s output logits to some metric (eg loss, logit diff, etc)

### Returns
The tensor of the patching metric for each patch. Has shape [3, n_layers, pos]

### Return type
patched_output (torch.Tensor)
```

--------------------------------

### main

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.benchmarks.main_benchmark.md

Run benchmarks from command line.

```APIDOC
## main()

### Description
Run benchmarks from command line.
```

--------------------------------

### __init__

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.model_bridge.supported_architectures.stablelm.md

Initializes the StableLM architecture adapter with the provided configuration.

```APIDOC
#### __init__(cfg: Any) -> None

Initialize the StableLM architecture adapter.
```

--------------------------------

### SimpleTextDataset

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.lit.dataset.md

A basic dataset class that holds text examples for analysis with LIT. Each example is a dictionary with at least a 'text' field. It can be initialized with examples, loaded from a file, or created from a list of strings.

```APIDOC
## class transformer_lens.lit.dataset.SimpleTextDataset

Bases: `object`

Simple text dataset for use with HookedTransformerLIT.

This is a basic dataset class that holds text examples for analysis
with LIT. Each example is a dictionary with at least a “text” field.

### Example

```pycon
>>> dataset = SimpleTextDataset([
...     {"text": "Hello world"},
...     {"text": "How are you?"},
... ])
>>> len(dataset.examples)
2
```

#### __init__(examples: List[Dict[str, Any]] | None = None, name: str = 'SimpleTextDataset')

Initialize the dataset.

* **Parameters:**
  * **examples** – List of example dictionaries with “text” field.
  * **name** – Name for the dataset (shown in LIT UI).

#### __iter__()

Iterate over examples.

#### __len__() → int

Return the number of examples.

#### description() → str

Return a description of the dataset.

#### *property* examples *: List[Dict[str, Any]]*

Return all examples in the dataset.

#### *classmethod* from_file(filepath: str | Path, name: str | None = None, max_examples: int | None = None) → [SimpleTextDataset](#transformer_lens.lit.dataset.SimpleTextDataset)

Load a dataset from a text file.

Each line in the file becomes one example.

* **Parameters:**
  * **filepath** – Path to the text file.
  * **name** – Optional dataset name (defaults to filename).
  * **max_examples** – Maximum number of examples to load.
* **Returns:**
  SimpleTextDataset instance.

#### *classmethod* from_strings(texts: Sequence[str], name: str = 'TextDataset') → [SimpleTextDataset](#transformer_lens.lit.dataset.SimpleTextDataset)

Create a dataset from a list of strings.

* **Parameters:**
  * **texts** – Sequence of text strings.
  * **name** – Dataset name.
* **Returns:**
  SimpleTextDataset instance.

### Example

```pycon
>>> dataset = SimpleTextDataset.from_strings([
...     "First example",
...     "Second example",
... ])
```

#### spec() → Dict[str, Any]

Return the spec describing the dataset fields.

This tells LIT what fields each example contains and their types.

* **Returns:**
  Dictionary mapping field names to LIT type specs.
```

--------------------------------

### Install LIT separately

Source: https://github.com/transformerlensorg/transformerlens/blob/main/transformer_lens/lit/README.md

Alternatively, install TransformerLens and LIT as separate packages.

```bash
pip install transformer-lens lit-nlp
```

--------------------------------

### Initialize development environment with UV

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/content/contributing.md

Use these commands to resolve dependencies, activate the virtual environment, and initialize the environment configuration file.

```bash
# resolves and installs dependencies into .venv
uv sync
# activate the virtual environment
source .venv/bin/activate
# first-time only: create .env from the template, then fill in HF_TOKEN for gated models
cp .env.example .env
```

--------------------------------

### __init__

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.model_bridge.supported_architectures.openelm.md

Initializes the OpenELM architecture adapter.

```APIDOC
#### __init__(cfg: Any) -> None

Initialize the OpenELM architecture adapter.
```

--------------------------------

### Configure Environment and Run Scraper

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/content/adapter_development/hf-scraper.md

Load the required HF token from the environment and execute the scraper using uv.

```bash
set -a; source .env; set +a
```

```bash
uv run python -m transformer_lens.tools.model_registry.hf_scraper [flags]
```

--------------------------------

### Install Dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Tracr_to_Transformer_Lens_Demo.ipynb

Installs TransformerLens and Tracr libraries, with conditional logic for Colab environments.

```python
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
    %pip install git+https://github.com/TransformerLensOrg/TransformerLens.git@dev
    %pip install git+https://github.com/google-deepmind/tracr.git
    
except:
    IN_COLAB = False
    print("Running as a Jupyter notebook - intended for development only!")
    # from IPython import get_ipython

    # ipython = get_ipython()
    # # Code to automatically update the TransformerLens code as its edited without restarting the kernel
    # ipython.run_line_magic("load_ext", "autoreload")
    # ipython.run_line_magic("autoreload", "2")
```

--------------------------------

### Import Libraries and Setup Device

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/LLaVA.ipynb

Imports core libraries for model interaction, image handling, and visualization. Sets up the device to use CUDA if available, otherwise CPU.

```python
# NBVAL_IGNORE_OUTPUT
import sys
import torch
from PIL import Image
import requests
from io import BytesIO

device = 'cuda' if torch.cuda.is_available() else 'cpu'

import matplotlib.pyplot as plt
%matplotlib inline

from transformer_lens.model_bridge import TransformerBridge

try:
    import circuitsvis as cv
except ImportError:
    print('circuitsvis not installed, attention visualization will not work')
    cv = None
```

--------------------------------

### __init__

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.model_bridge.supported_architectures.olmo2.md

Initializes the OLMo 2 architecture adapter with the provided configuration.

```APIDOC
#### __init__(cfg: Any) → None

Initialize the OLMo 2 architecture adapter.
```

--------------------------------

### Install dependencies in Colab

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Gemma3_Multimodal.ipynb

Detects if the environment is Google Colab and installs the necessary libraries.

```python
# Detect Colab and install dependencies if needed
DEVELOPMENT_MODE = False
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
    %pip install transformer_lens
    %pip install circuitsvis
except:
    IN_COLAB = False
```

--------------------------------

### Example Output for Environment Initialization

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Realtime_Training_Telemetry_Demo.ipynb

Displays the expected console output when running the initialization code in a local Jupyter environment.

```text
Output:
Environment: Local / Standard Jupyter
Plotly Renderer: notebook_connected
Running on cpu
```

--------------------------------

### setup_components

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.model_bridge.component_setup.md

Configures various components on a bridge module.

```APIDOC
## setup_components

### Description
Set up components on the bridge module.

### Parameters
* **components** (dict[str, Any]) – Dictionary of component name to bridge component mappings
* **bridge_module** (Module) – The bridge module to configure
* **architecture_adapter** (ArchitectureAdapter) – The architecture adapter
* **original_model** (Module) – The original model to get components from

### Returns
None
```

--------------------------------

### Install TransformerLens for Python 3.8 or 3.9

Source: https://github.com/transformerlensorg/transformerlens/blob/main/README.md

Version-specific installation command for older Python environments.

```shell
pip install 'transformer_lens~=2.0'
```

--------------------------------

### Check if LIT is installed

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.lit.md

Verify if the LIT (lit-nlp) library is installed in the current environment. Returns a boolean.

```python
>>> from transformer_lens.lit import check_lit_installed
>>> check_lit_installed()
True
```

--------------------------------

### __init__

Source: https://github.com/transformerlensorg/transformerlens/blob/main/docs/source/generated/code/transformer_lens.model_bridge.supported_architectures.cohere.md

Initializes the Cohere architecture adapter.

```APIDOC
## __init__(cfg: Any) -> None

Initialize the Cohere architecture adapter.
```

--------------------------------

### Install Dependencies in Colab

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/LLaVA.ipynb

Installs necessary libraries like transformer_lens and circuitsvis if running in a Google Colab environment.

```python
# Detect Colab and install dependencies if needed
DEVELOPMENT_MODE = False
try:
    import google.colab
    IN_COLAB = True
    print("Running as a Colab notebook")
    %pip install transformer_lens
    %pip install circuitsvis
except:
    IN_COLAB = False
```

--------------------------------

### Install TransformerLens and Dependencies

Source: https://github.com/transformerlensorg/transformerlens/blob/main/demos/Qwen.ipynb

Installs necessary libraries for TransformerLens, including transformers, plotly, and others. This is a prerequisite for running the demos.

```python
# NBVAL_IGNORE_OUTPUT
%pip install transformers_stream_generator plotly circuitsvis huggingface_hub einops tiktoken datasets
```