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.
3. gpu-sizer/, which finds the GPU/config you need to fit an interp-engine model (and what performance you'll get), to avoid OOMing while working. docs | API

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/.

GPU-Sizer

docs | API

Never OOM again - interp-engine includes gpu-sizer, an intuitive UI which tells you what GPU(s) and configs you need to get the best performance out of your selected model. For example, interp-engine.org/sizer/Qwen/Qwen3.6-27B shows that you can run Qwen3.6-27B with interp-engine's vllm-static backend for max speed while keeping it in a single 80GB A100, and have ~160k tokens for the KV Cache.

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].

Caveats

• Gemma 4 requires transformers 5.14.1 because 5.15 moved head_dim into per_layer_config and vLLM's config read dies before a weight loads (vllm#51744).
• DeepSeek-V2 on transformers older than 5.15.0 captures a wrong attention temperature — the engine warns at load, and upgrading is the fix (COMPATIBILITY.md).
• DeepSeek-V4 on the eager backend needs two flags outside Hopper. Its FP8 paths reach for kernels-community/deep-gemm, which declares a 9.0a build, and with kernels >= 0.16.1 the arch refusal escapes transformers' Triton fallback and kills the first forward. Load with TRANSFORMERS_DISABLE_DEEPGEMM_LINEAR=1 and experts_implementation="grouped_mm", which transformers already recommends on B200 for an unrelated DeepGEMM accuracy problem. The engine raises HubKernelUnsupported naming both; vLLM is unaffected.
• MXFP4 checkpoints (gpt-oss) need interp-engine[quant], which the [vllm] extra does not include; without it transformers dequantizes them to bf16 at roughly 3x the weights, which can turn a model that fits into one that does not.
• gemma-4-26B-A4B-it on the static vLLM backend needs VLLM_BATCH_INVARIANT=1 on B200/B300. On compute capability 10.x, vLLM's own greedy output moves by up to 6.8 nats under the CUDA-graph replay a static set requires, so the taps would report a forward pass vLLM itself gets wrong (vllm#55238). The engine refuses this combination at load and names the flag; capability 9.x and 12.x are bit-identical and unaffected.

Per-architecture structural quirks — which points a family serves and why — are not caveats but facts about the architecture, and live in ARCHITECTURE_QUIRKS.md.

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