nnterp: Standardized Interpretability for Transformers

• nnterp is a library that provides a standardized interface for mechanistic interpretability in transformer models, preserving numerical fidelity with HuggingFace implementations.
• It employs a lightweight renaming and validation layer atop NNsight to offer unified accessors for over 50 transformer variants, streamlining cross-model analyses.
• The library supports interventions like logit lens, patchscope, and activation steering while maintaining rigorous numerical equivalence and performance benchmarks.

nnterp is a library that establishes a standardized interface for mechanistic interpretability research on transformer-based LLMs, providing a solution that preserves the numerical fidelity of original HuggingFace model implementations while enabling a unified, portable workflow for model analysis and intervention (Dumas, 18 Nov 2025). By leveraging a lightweight renaming and validation layer on top of NNsight—and not reimplementing transformer code—nnterp bridges the long-standing tradeoff between API uniformity (as in TransformerLens) and exact behavior (as in direct HuggingFace model access), thereby addressing critical bottlenecks in multi-architecture interpretability pipelines.

1. Motivation and Design Objectives

The central challenge addressed by nnterp is the tension between correctness and usability inherent in existing interpretability tooling:

• TransformerLens-style approaches reimplement models from scratch, enforcing API consistency and precise tensor hooks, but require large volumes of custom code for each architecture and can introduce subtle numerical deviations due to differences in layer-norm ordering, dropout, or random initializations.
• Direct HuggingFace-based tools (e.g., NNsight) preserve the exact model behavior with support for high-performance kernels, but lack a standardized module structure and interface, making cross-model workflows brittle with respect to both architectural differences and upstream refactoring.

nnterp’s key insight is that a minimal wrapper atop NNsight’s model tracing enables both (1) exact HuggingFace equivalence (output and activation-wise) and (2) a uniform set of accessors for layers, attention modules, and interventions across 50+ transformer variants and 16 architecture families. This standardization eliminates the need for model-specific intervention scripts and validation infrastructure.

2. Architectural Structure and Unified API

The nnterp core abstraction, StandardizedTransformer, subclasses NNsight.LanguageModel and executes two key initialization steps:

• Module Renaming: Architecture-specific lookup tables provide rules for renaming original HuggingFace submodules to a canonical hierarchy. For example, model.transformer.h (GPT-2) or model.model.layers (LLaMA) are both mapped to model.layers. Similarly, nested modules such as attn, mlp.c_fc/mlp.c_proj, and transformer.ln_f are mapped to standardized names like self_attn, mlp_input/mlp_output, and ln_final.
• Standardized I/O Accessors: Properties such as model.layers_input[i], model.layers_output[i], model.attentions_input[i], and model.mlps_output[i] provide getter-setter access to activations, supporting both singleton and tuple return conventions.

This architecture allows transparent intervention and monitoring. The directory-like internal structure is summarized below:

Component	Standardized Name	Notes
Token embedding	embed_tokens	Shared across variants
Transformer block	layers[i]	List of canonical blocks
Attention module	self_attn	Submodule within layers[i]
Attention I/O	self_attn_input/output	Pre/post attention hooks
MLP I/O	mlp_input/output	Pre/post MLP hooks
Layer normalization	layer_norm/ln_final	Final normalization before head
Output head	lm_head	Tied output for language modeling

3. Module Renaming Logic and Fidelity Guarantees

nnterp maintains a registry mapping HuggingFace model class names to deterministic renaming rules, enabling fully automated construction of standardized interfaces. For each encountered module during introspection:

• The Python class type is checked against a built-in mapping (e.g., GPT2Block, LlamaDecoderLayer).
• If a match is found, the renaming rules are invoked and passed to NNsight’s rename argument, resulting in a fully instrumented model with both original and canonical names.

Validation is integral: for any given input batch, both end-to-end logits and intermediate activations are compared between the native HuggingFace forward and the nnterp-wrapped version using the infinity norm, asserting strict equivalence up to tolerance $10^{-6}$:

$$\|\mathrm{HF\_logits} - \mathrm{nnterp\_logits}\|_\infty < \varepsilon \,, \quad \varepsilon = 10^{-6}$$

At the layer level, each standardized accessor (e.g., layers_output[i]) must match the original module output to within this threshold.

4. Built-in Interpretability and Intervention Methods

Three canonical mechanistic interpretability tools are included by default, all leveraging the standardized API:

• Logit Lens: At layer $k$, computes projected logits via

$$\mathrm{logits}_k = h_k W_{\mathrm{unembed}} + b_{\mathrm{unembed}}$$

permitting direct inspection of the model’s next-token distribution if cut at layer $k$.

• Patchscope: Given contexts A and B with respective hidden activations $h_k^A$, $h_k^B$, produces patched residuals by

$$\tilde h_{>k} = \mathrm{forward}_{>k}\bigl(h_k^B + (h_k^A - h_k^{A,\mathrm{detach}})\bigr)$$

quantifying the downstream causal effect of activations at a given layer.

• Activation Steering: Permits additive intervention by injecting a scaled vector $\Delta$ into a hidden state:

$h_k \leftarrow h_k + \alpha \Delta$

and forwarding the modified state to analyze the induced distributional shift.

Each method is guaranteed to function across all supported architectures using identical call signatures.

5. Validation Test Suite

nnterp provides a bundled test suite (python -m nnterp run_tests) to certify installation and model-specific compatibility:

• Shape Checks: Ensures I/O shapes of all accessor outputs match the corresponding HuggingFace modules.
• Numerical Equivalence: Verifies that final logits and all layer activations match the HuggingFace baseline within $10^{-6}$ absolute error in the infinity norm.
• Attention Probability Normalization: For architectures with enabled attention probability collection,

$\left|\sum_j P_{ij} - 1\right| < 10^{-6}$

• Intervention Validation: Demonstrates that causal hooks produce observable changes in output logits when ablating a layer, confirming effective intercept-and-reinsert semantics.

6. Typical Usage Patterns

Illustrative patterns highlight portability and ease of intervention:

• Model Loading:

from nnterp import StandardizedTransformer model = StandardizedTransformer("gpt2") tokenizer = model.tokenizer # Example: model.layers_output[5] yields post-residual activations

• Accessing Attention Probabilities:

model = StandardizedTransformer("gpt2", enable_attention_probs=True) inputs = tokenizer("Hello world", return_tensors="pt") attn_probs = model.attention_probabilities[2] # [B, heads, L, L]

• Activation Steering:

from nnterp.interventions import steering target_id = tokenizer("Paris", add_special_tokens=False).input_ids[0] Delta = model.lm_head.weight[target_id] patched_logits = steering(model, layer=4, steering_vector=Delta, scale=0.2, batch=inputs["input_ids"])

• Logit Lens:

from nnterp.interventions import logit_lens ll7 = logit_lens(model, layer=7, batch=inputs["input_ids"]) top5 = ll7.softmax(-1).topk(5)

All code paths and interventions are unified; no model-specific conditionals are required.

7. Performance, Current Limitations, and Outlook

nnterp inherits NNsight’s computational efficiency and compatibility with fast attention kernels and fused MLPs, yielding runtime and memory benchmarks on par with or better than TransformerLens. The additional interface layer imposes negligible overhead, being limited to dynamic property resolution in Python.

Key known limitations:

• The default test suite provides strong sanity checks but not complete formal correctness guarantees.
• The collection of attention probabilities is contingent on support in the HuggingFace base model; some MoE or flash-attention variants may lack compatibility due to upstream variable refactoring.
• Encoder-decoder and bidirectional models (e.g., BERT) are not yet supported—current coverage is limited to causal LLM architectures.

Planned enhancements include: automatic architecture detection and renaming rule inference, complete support for encoder-decoder and bidirectional models, additional hooks for sub-components (such as key/value/query projections or MoE routing), and integration with distributed tooling (e.g., NDIF).

In summary, nnterp establishes a validated, minimal-abstraction standard for transformer interpretability, enabling cross-architecture, exact-gradient, and numerically stable analysis workflows with minimal model-specific adaptation (Dumas, 18 Nov 2025).