nnsightful

A higher-level extension of NNsight providing ready-to-use mechanistic interpretability methods and interactive visualizations for exploring the results.

Installation

pip install nnsightful

Usage

Running interpretability methods

from nnterp import StandardizedTransformer
from nnsightful import logit_lens, activation_patching

model = StandardizedTransformer("gpt2")

# Logit lens — returns LogitLensData directly
data = logit_lens.logit_lens(model, prompt, top_k=10)

# With sparse layer/position selection
data = logit_lens.logit_lens(model, prompt, layers=[0, 5, -1], positions=-1, top_k=5, top_p=0.9)

# Activation patching — returns ActivationPatchingData directly
data = activation_patching.activation_patching(model, src_prompt, tgt_prompt, src_pos, tgt_pos, tgt_freeze)

Jupyter visualizations

from nnsightful import display_logit_lens, display_line_plot

# Display a logit lens heatmap + trajectory chart
display_logit_lens(data, dark_mode=True)

# Display an activation patching line plot
display_line_plot(data, options={"mode": "probability"})

React components

import { LogitLensWidget, LinePlotWidget } from "nnsightful";

<LogitLensWidget data={data} darkMode={true} />
<LinePlotWidget data={data} darkMode={true} />

Project Structure

nnsightful/
├── src/
│   ├── charts/              # JS/TS visualization library
│   │   ├── core/            # Framework-agnostic widget implementations
│   │   ├── react/           # Thin React wrappers
│   │   └── types/           # TypeScript type definitions
│   └── nnsightful/          # Python package
│       ├── tools/           # Interpretability methods (logit lens, activation patching)
│       ├── types.py         # Pydantic data models
│       └── viz/             # Jupyter display helpers (includes bundled charts.js)
├── examples/                # Example notebooks
├── dist/                    # JS build output (ESM for React/Next.js apps)
├── package.json             # npm package config
└── pyproject.toml           # pip package config

Development

Building the JS/TS visualizations

npm install
npm run build

This produces:

• dist/index.mjs — ESM bundle (React externalized) for use in React/Next.js apps
• src/nnsightful/viz/charts.js — Self-contained IIFE bundle for Jupyter notebooks, bundled with the Python package

Editable Python install

pip install -e .