interp-engine

🔗 interp-engine.org

interp-engine is an interpretability engine that is fast, standardized (34 'points'/addresses across architectures), and easy to use and debug. It powers all of Neuronpedia's inference and is checked for accuracy against HF Transformers and other engines.

This repo contains:

1. validator/, which compares/validates it against TransformerLens, and nnsight/nnterp on real architectures.
2. visualizer-web/, a "cheat sheet" hosted at interp-engine.org of each 'point' (eg resid_post.16), standardized across architectures.

Installation

pip install 'interp-engine[vllm]'  # preferred install: includes vLLM support (CUDA required)
pip install interp-engine          # eager backend only

Simple Usage

from interp_engine import Address, load_model, run_with_cache

# VLLM (default): low VRAM, medium speed, every point, chosen per request
model = load_model("Qwen/Qwen3-8B")

# VLLM-STATIC: high VRAM, high speed, only the points you declare (default resid_post)
# model = load_model("Qwen/Qwen3-8B", backend="vllm-static")

# VLLM-GENERATE: fastest, generation only -- no capture, no steering
# model = load_model("Qwen/Qwen3-8B", backend="vllm-generate")

# EAGER: low VRAM, low speed
# model = load_model("Qwen/Qwen3-8B", backend="eager")

point = Address("resid_post", 10)      # or string: "resid_post.10"
cache = run_with_cache(model, model.to_tokens("Hello, world"), [point])
cache[point]  # [batch, pos, ...]

AI Agents

Add "use interp-engine" to your prompt and let your agent figure it out - everything is fully documented in this repo and open source.

Supported Points ("Addresses")

interp-engine supports 34 standardized points ("Addresses") across architectures: every one of them on the eager backend, 28 of them on vLLM. Check interp-engine.org for the "cheat sheet", or SUPPORTED_POINTS.md for a markdown version with the per-backend detail.

Performance / Speed

vLLM gives interp-engine high throughput via concurrency, and backend="vllm-static" gives even higher throughput at the cost of higher VRAM usage. Every column below is capture-capable.

Measured on NVIDIA B200, bf16, 512-token prompt, 128 new tokens.

One stream (tok/s):

8 concurrent requests (aggregate tok/s):

backend="vllm-static" is opt-in, and serves only the tap set it declared — static_points="auto" by default, or a list you name. PERFORMANCE.md has how it works and what it trades; benchmarks/results-latest.md has every figure at full precision, including capture, steering and lens latencies; benchmarks/README.md has how the tables above are rounded.

Correctness

We verify correctness in two main ways:

1. A test suite that checks results across several models - what each check is designed to catch is in INTERNALS.md.
2. A full validator comparison engine that checks most hook points across 50+ models, at early, middle and late layers - fully reproducible, with detailed results saved in the git repo at validator/.

Why use an Interpretability Engine instead of building from scratch?

1. Speed: Get performance without sacrificing correctness.
2. Standardization + Verification: Eliminate ambiguity when referring to points, plus a full test suite included.
3. Faster Dev / Fewer Tokens Used: You could spend ten million tokens and have your AI write, test, and make production-ready an interpretability engine. Or you could just pip install interp-engine[vllm].

Development / Contributing

Activate the shared git hooks once per clone — they format staged Python, rebuild the generated files, and run CI's static checks before a push. Details in CONTRIBUTING.md.

make hooks    # or: git config core.hooksPath .githooks

Contact

Bugs and feature requests belong in issues. For anything else: johnny@neuronpedia.org.

License

Apache 2.0