We built TransformerLens for language models. Nobody did the same for vision.

Why this exists

TransformerLens gave researchers a way to look inside language models. Cache every activation, trace every attention head, run causal interventions with a few lines of code. It changed how the field debugs transformers.

But when the field moved to vision-language models, that toolkit hit a wall.

"Vision-language models expose rich internals: attentions, hidden states, embeddings. But interpretability tooling remains architecture-specific and difficult to operationalize." MultiModalLens Research Paper

The problem is structural. Every VLM family processes images differently:

• CLIP uses dual encoders with independent vision and text towers
• BLIP-2 routes frozen vision features through a Q-Former into a frozen LLM
• LLaVA interleaves image tokens directly into an autoregressive decoder

Each architecture requires different extraction logic, different attention surgery, different faithfulness testing. Researchers were building one-off scripts for every model they wanted to debug. There was no unified tool.

MultiModalLens fills that gap. One adapterized framework. One debugging interface. Faithfulness checks included.

The timeline

2019 — BertViz popularizes interactive attention visualization for language transformers.

2022 — TransformerLens ships mechanistic interpretability as a first-class API for LLMs.

2023 — Jain & Wallace demonstrate "Attention is not Explanation." The field realizes heatmaps alone are not enough. Faithfulness testing becomes critical.

2023 — CLIP, BLIP-2, and LLaVA drive massive VLM adoption. Still no unified interpretability tooling.

2024 — The VLM ecosystem explodes: Qwen2-VL, InternVL, PaliGemma, Pixtral, Idefics3, and dozens more.

2025 — MultiModalLens v0.1.0 ships with the adapterized framework and faithfulness diagnostics.

2026 — v0.2.0 adds mechanistic probes, direct logit attribution, path patching, interactive dashboards, and a PyPI release.

How it works

The core design principle: isolate model-specific logic behind a single interface. The UI, CLI, and evaluation layers never see model-specific code.

Four canonical adapters implement the same load(), prepare(), analyze(), and score() interface:

• CLIPAdapter — dual-encoder extraction (CLIP, SigLIP, AltCLIP, X-CLIP, Chinese CLIP)
• BLIP2Adapter — Q-Former + language model extraction (BLIP-2, InstructBLIP)
• LlavaAdapter — interleaved decoder extraction (LLaVA, Qwen2-VL, InternVL, MLLaMA, MiniCPM, and 8 more)
• GenericVLMAdapter — config-driven fallback for anything that doesn't fit the canonical patterns

The hook infrastructure is built on PyTorch's register_forward_hook, the same approach TransformerLens uses. It auto-discovers transformer layer paths by scanning model.named_modules(), so you never have to manually specify layer indices.

The two APIs

MultiModalLens exposes two ways to interact with models:

HookedVLM is the TransformerLens-style programmatic API. Load a model, run it with cache or hooks, access activations by name:

from multimodallens import HookedVLM
from PIL import Image

vlm = HookedVLM.from_pretrained("openai/clip-vit-base-patch32", device="auto")

# Run with full activation cache
result, cache = vlm.run_with_cache(Image.open("cat.jpg"), "a photo of a cat")

# Access any layer's activations
layer_5 = cache["vision_encoder.layers.5"]

# Zero-ablate a layer on the fly
patched = vlm.run_with_hooks(
    image=Image.open("cat.jpg"),
    prompt="a photo of a cat",
    fwd_hooks=[("vision_encoder.layers.5", lambda t: t * 0.0)]
)

LensPipeline is the stateful orchestration layer used by the Gradio UI and CLI. It caches adapters, manages model loading, and runs the full analysis suite:

# Launch the interactive web UI
multimodallens ui

# Single analysis with JSON output
multimodallens analyze --model openai/clip-vit-base-patch32 --image photo.jpg --prompt "a dog"

# Batch evaluation over a dataset
multimodallens eval --dataset dataset.jsonl --model openai/clip-vit-base-patch32

Supported models

23 family aliases map to 4 canonical adapters, plus automatic inference from Hugging Face's AutoConfig:

New VLM families can be added without writing adapter code. Define the vision tower path, projector path, language model path, and image token string in a MultimodalConfig and the generic adapter handles the rest.

The methodology

MultiModalLens is not just a visualization dashboard. It combines three complementary evidence channels to avoid over-reliance on any single explanation primitive.

Structural signal: attention

Residual-augmented rollout propagates attention through all layers while accounting for skip connections. The resulting matrix R captures each token's total attention to every image patch across the full network depth. Reshaped to a patch grid, it becomes the heatmap overlay.

Representation signal: alignment

Token-patch cosine similarity in shared latent space. The alignment matrix S shows which text tokens attend to which visual patches. Per-token saliency scores identify the most grounding-relevant words.

Causal signal: faithfulness

Attention is not explanation. MultiModalLens verifies that heatmaps actually reflect causal importance through:

• Deletion curves — progressively mask top-ranked patches, track score drop
• Insertion curves — progressively preserve top patches, track score recovery
• Counterfactual drop — single-shot top-k% masking effect
• Attention-gradient agreement — Spearman correlation between attention and gradient maps

Mechanistic probes

Beyond visualization, MultiModalLens includes TransformerLens-style mechanistic probes:

• Forward-hook activation caching — capture per-layer tensors during a regular forward pass
• Cross-modal activation patching — swap activations between source and target images to test causality
• Multimodal logit lens — decode intermediate hidden states through the vocabulary layer by layer
• Grounding head discovery — identify which attention heads carry visual grounding information
• Direct logit attribution — decompose target token logit into per-head and per-MLP contributions
• Causal path patching — edge-level intervention analysis between sender and receiver components

The library also includes weight processing utilities (LayerNorm folding, writing weight centering, unembedding centering) for cleaner decomposition, and a FactoredMatrix class for efficient OV/QK circuit analysis via SVD.

Your first analysis in three steps

1. Install — pip install multimodallens
2. Load and run — three lines of Python:
   quickstart.py

   from multimodallens import HookedVLM
   vlm = HookedVLM.from_pretrained("openai/clip-vit-base-patch32")
   result = vlm.analyze("cat.jpg", "a photo of a cat")

3. Read the output — you get attention maps, alignment scores, a global score, and faithfulness metrics. Four signals, not one heatmap.

Five tutorial notebooks cover everything from quickstart to model comparison. The GitHub repo has the full source, and the PyPI package is ready to install. For the theory behind the methodology, read the methodology document or the research paper draft.