Metadata-Version: 2.4
Name: vlmprobe
Version: 1.0.1
Summary: Lens, attention, causal and sparse feature probes for language, vision and multimodal models
Author: Gexin Huang, Haisheng Fu, Ruinan Jin, Xiaoxiao Li
Project-URL: Homepage, https://ubc-tea.github.io/vlm-probe/
Project-URL: Documentation, https://github.com/ubc-tea/vlm-probe/tree/main/docs
Project-URL: Source, https://github.com/ubc-tea/vlm-probe
Project-URL: Issues, https://github.com/ubc-tea/vlm-probe/issues
Project-URL: Report, https://github.com/ubc-tea/vlm-probe/blob/main/docs/assets/vlmprobe-technical-report.pdf
Project-URL: Personal mirror, https://github.com/gexinh/vlm-prob
Project-URL: Report sources, https://github.com/gexinh/vlm-probing-report
Keywords: interpretability,probing,vision-language-models,mechanistic-interpretability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.2
Provides-Extra: sae
Requires-Dist: numpy<3,>=1.26; extra == "sae"
Requires-Dist: safetensors<1,>=0.4; extra == "sae"
Requires-Dist: huggingface_hub<2,>=0.30; extra == "sae"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.8; extra == "visualization"
Requires-Dist: Pillow>=10; extra == "visualization"
Requires-Dist: numpy>=1.26; extra == "visualization"
Provides-Extra: transformers
Requires-Dist: transformers<5.4,>=5.3; extra == "transformers"
Requires-Dist: torch>=2.4; extra == "transformers"
Requires-Dist: torchvision>=0.19; extra == "transformers"
Requires-Dist: accelerate>=1.0; extra == "transformers"
Requires-Dist: Pillow>=10; extra == "transformers"
Provides-Extra: notebooks
Requires-Dist: jupyterlab>=4; extra == "notebooks"
Requires-Dist: nbclient>=0.10; extra == "notebooks"
Requires-Dist: matplotlib>=3.8; extra == "notebooks"
Requires-Dist: Pillow>=10; extra == "notebooks"
Requires-Dist: numpy>=1.26; extra == "notebooks"
Requires-Dist: tokenizers>=0.22; extra == "notebooks"

<p align="center">
  <img src="https://raw.githubusercontent.com/gexinh/vlm-prob/main/docs/assets/vlm-probing-icon.svg" width="112" alt="vlmprobe icon">
</p>

<h1 align="center">vlmprobe</h1>

<p align="center"><strong>Exploring Model Internals Beyond the Answer</strong></p>

<p align="center">
  <a href="https://gexinh.github.io/vlm-prob/"><img src="https://img.shields.io/badge/Project%20Page-Visit%20Website-3266e5?style=for-the-badge" alt="Visit the vlmprobe project page"></a>
</p>

vlmprobe brings lens readouts, attention explanations, causal interventions,
and sparse autoencoders into one model-bound interface. It supports vision-language
models, language models, and a ViT image-classification control. Bind a loaded
model once, select layers and token groups, and inspect how its internal
computation relates to a chosen answer.

- **Lens:** read vocabulary predictions from residual states, attention heads,
  or projected visual embeddings.
- **Attention:** compare attention patterns and target-conditioned spatial
  attributions on the same input.
- **Causal:** replace activations, isolate paths, block attention routes, or steer
  residual states and measure the resulting change.
- **SAE:** train or load sparse dictionaries, inspect feature activity, and
  measure feature interventions with reconstruction controls.

Explicit adapters handle hook locations, expanded visual-token coordinates,
and model readouts. Results retain tensors and experiment metadata; shared
visualization functions turn them into heatmaps, image overlays, curves, and
connection graphs. Capability checks distinguish an unsupported operation from
a measured zero effect.

<p align="center">
  <img src="https://raw.githubusercontent.com/gexinh/vlm-prob/main/docs/assets/library-overview-sae.svg" width="100%" alt="Model inputs, adapter configuration, lens/attention/causal/SAE tools, and structured results">
</p>

[Documentation](docs/README.md) · [Demos](demos/README.md) ·
[Visualization](docs/VISUALIZATION.md) ·
[Technical report](docs/assets/vlmprobe-technical-report.pdf) ·
[Papers and datasets](docs/REFERENCES.md)

## Installation

Python 3.10+ is required. Install release **1.0.1** from GitHub:

```bash
python -m pip install "vlmprobe[sae,transformers,visualization] @ git+https://github.com/gexinh/vlm-prob.git@v1.0.1"
```

The published package is also available on [PyPI](https://pypi.org/project/vlmprobe/):

```bash
python -m pip install --upgrade "vlmprobe[sae,transformers,visualization]"
```

For tensor methods and custom PyTorch adapters, install the base package:

```bash
python -m pip install vlmprobe
```

The Python import name is **`vlmprobe`**. Existing `vlm_probing` imports remain
compatible, including adapter registration and saved Python objects.

```python
import vlmprobe

probe = vlmprobe.Prober(model, processor)  # use your loaded model
result = probe.lens.logit(tokens="last_prompt").run(inputs)
```

The base package requires only PyTorch. The `transformers` extra targets
Transformers 5.3.x and includes Accelerate, Torchvision, and Pillow;
`visualization` provides the plotting dependencies. Add `notebooks` when using
Jupyter. Model weights and complete datasets are downloaded separately.

To develop the library in a checkout, use
`python -m pip install -e ".[transformers,visualization,notebooks]"`.
The [package guide](docs/PACKAGING.md) covers wheels and release publication.

## Quick Start

This example loads **Qwen3-VL-2B-Instruct** on one CUDA GPU. Replace
`example.jpg` with your image, or use an image from [the bundled demos](demos/README.md).

```python
import torch
from PIL import Image
from transformers import AutoModelForImageTextToText, AutoProcessor
from vlmprobe import Prober

model_id = "Qwen/Qwen3-VL-2B-Instruct"
model = AutoModelForImageTextToText.from_pretrained(
    model_id, dtype=torch.bfloat16, device_map={"": "cuda:0"},
    attn_implementation="eager",
)
processor = AutoProcessor.from_pretrained(model_id)
probe = Prober(model, processor)

messages = [{"role": "user", "content": [
    {"type": "image"},
    {"type": "text", "text": "What is in this image?"},
]}]
prompt = processor.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True,
)
inputs = probe.prepare(
    prompt=prompt, image=Image.open("example.jpg").convert("RGB"), device="cuda:0",
)

print(probe.describe()["methods"]["lens.logit"])
result = probe.lens.logit(layers=[0, 13, 27], tokens="last_prompt").run(inputs)
token_id = result.tensors["logits"][-1, 0].argmax().item()
print(processor.tokenizer.decode([token_id]))
result.save("outputs/logit_lens")

# Read projected image tokens in the input embedding space.
visual = probe.lens.embed(tokens="visual").run(inputs, top_k=5)

# Observe the attention actually used by the language decoder.
attention = probe.attention.profile(
    layers=[27], queries="last_prompt", include_attention=True,
).run(inputs)
```

Use a model you have already loaded, and pass its native processor dictionary
directly to `.run(...)` when convenient. Layer indices are zero-based; tokens
refer to the expanded sequence, including image positions. The
[model guides](docs/models/README.md) explain each architecture's input contract.

```python
from vlmprobe import visualization as viz

answer_id = processor.tokenizer.encode(" yellow", add_special_tokens=False)[0]
ax = viz.plot_lens_heatmap(result, target_token_id=answer_id)
ax.figure.savefig("outputs/lens.png", bbox_inches="tight")
```

This plots one vocabulary token's rank across selected layers and positions.
A complete answer can contain several tokens; choose the intended subword
explicitly, or use complete-answer metrics for interventions.

| Common operation | Purpose |
| --- | --- |
| `Prober(model, processor=None)` | Bind a caller-owned model and resolve its adapter. |
| `probe.describe()` | Inspect available methods, sites, and missing capabilities. |
| `probe.prepare(prompt=..., image=..., device=...)` | Convert formatted text and images into native inputs. |
| `probe.lens / probe.attention / probe.causal / probe.sae` | Configure a model-bound analysis method. |
| `method.run(inputs, ...)` | Execute a probe and return `ProbeResult`. |
| `method.fit_batches(...)` / `method.load(...)` | Calibrate or restore Tuned/Attention Lens; Jacobian Lens has a separate estimator. |
| `result.save(directory)` | Save CPU tensors and JSON metadata. |

[The API guide](docs/API.md) covers selectors, complete-answer metrics,
paired-input alignment, and result shapes. [Visualization](docs/VISUALIZATION.md)
describes reusable plotting functions. The [demos](demos/README.md) walk through
input preparation, live model calls, calibration when needed, and plotting.
Every [method guide](docs/methods/README.md) includes parameter defaults and a complete input-to-output example.
A [small CPU example](examples/prober_quickstart.py)
exercises the API without downloading pretrained weights.

## Model Support

Eight VLM families have explicit adapters. Text-only GPT-2/Llama and a ViT
classifier provide complementary controls. Availability is method-specific;
see the [capability matrix](docs/models/README.md).

| Family | Example checkpoint | Guide |
| --- | --- | --- |
| Qwen3-VL | Qwen3-VL-2B-Instruct | [Usage](docs/models/qwen3_vl.md) |
| Qwen2.5-VL | Qwen2.5-VL-3B-Instruct | [Usage](docs/models/qwen2_5_vl.md) |
| Qwen2-VL | Qwen2-VL-2B-Instruct | [Usage](docs/models/qwen2_vl.md) |
| Qwen3.5 | Qwen3.5-4B; hybrid attention restrictions | [Usage](docs/models/qwen3_5.md) |
| SmolVLM | SmolVLM-500M-Instruct | [Usage](docs/models/smolvlm.md) |
| InternVL | InternVL3-1B-hf | [Usage](docs/models/internvl.md) |
| LLaVA | llava-1.5-7b-hf | [Usage](docs/models/llava.md) |
| Pixtral | Pixtral-12B-2409 | [Usage](docs/models/pixtral.md) |
| Language models | GPT-2 / Llama | [GPT-2](docs/models/gpt2.md) · [Llama](docs/models/llama.md) |
| Vision classifier | ViT-B/16 | [Usage](docs/models/vit.md) |

## Methods

Each guide explains the implemented computation, parameters, outputs, and
relationship to its original paper. Reusable primitives are labeled separately
from paper methods.

| Family | Method guides |
| --- | --- |
| Lens | [Logit](docs/methods/logit_lens.md) · [Tuned](docs/methods/tuned_lens.md) · [Attention Lens](docs/methods/attention_lens.md) · [Jacobian](docs/methods/jacobian_lens.md) · [EmbedLens](docs/methods/embed_lens.md) · [Patchscopes](docs/methods/patchscope.md) |
| Attention | [Rollout](docs/methods/attention_rollout.md) · [Grad-CAM, ATTATTR, TAM, Beyond Intuition](docs/methods/attention_maps.md) · [Generic relevance](docs/methods/attention_relevance.md) · [ViT DTD/LRP](docs/methods/chefer_lrp.md) |
| Causal | [Activation patching](docs/methods/activation_patching.md) · [IOI-style path patching](docs/methods/path_patching.md) · [Attribution patching](docs/methods/attribution_patching.md) · [Attention Knockout](docs/methods/attention_knockout.md) · [EAP / EAP-IG](docs/methods/eap_ig.md) · [Residual steering / VSV](docs/methods/steering.md) |
| SAE | [ReLU](docs/methods/sae/relu.md) · [TopK](docs/methods/sae/topk.md) · [Gated](docs/methods/sae/gated.md) · [JumpReLU](docs/methods/sae/jumprelu.md) · [AbsTopK](docs/methods/sae/abstopk.md) · [BatchTopK](docs/methods/sae/batchtopk.md) · [Matryoshka BatchTopK](docs/methods/sae/matryoshka_batchtopk.md) · [Archetypal TopK](docs/methods/sae/archetypal_topk.md) · [Archetypal JumpReLU](docs/methods/sae/archetypal_jumprelu.md) · [Matching Pursuit](docs/methods/sae/matching_pursuit.md) · [Signed MP](docs/methods/sae/signed_matching_pursuit.md) · [Nonnegative OMP](docs/methods/sae/orthogonal_matching_pursuit.md) · [Signed OMP](docs/methods/sae/signed_orthogonal_matching_pursuit.md) · [QSAE](docs/methods/sae/qsae.md) |
| Supporting tools | [Attention profile](docs/methods/attention_profile.md) · [Head logit attribution](docs/methods/head_logit_attribution.md) · [Probability reweighting](docs/methods/attention_reweight.md) · [Temperature](docs/methods/attention_temperature.md) |

## Package Architecture

```text
src/vlmprobe/    # public import name; shares the implementation below
src/vlm_probing/
  prober.py       # shared model-bound entry point
  api/           # method factories, capture and replay
  adapters/      # explicit architecture and token-layout contracts
  lenses/        # BaseLens and concrete readout methods
  attention/     # BaseAttention and concrete attention methods
  causal/        # BaseCausal and concrete interventions/estimators
  sae/           # native dictionaries, one trainer, artifacts and model cards
  training/      # calibration, checkpoint import and resume
  visualization/ # shared heatmaps, overlays, curves and graphs
  core/          # results and execution traces
demos/           # runnable notebooks, compact measurements and input images
docs/            # model, method, API and source guides
```

Family base classes keep algorithm implementations small; adapters let them
share model execution. [Architecture](docs/ARCHITECTURE.md) and
[adapter contracts](docs/ADAPTERS.md) describe these boundaries.

## References

The [paper and dataset index](docs/REFERENCES.md) links the original method
papers, author implementations, and datasets used for demonstrations and lens
calibration. The
[technical report](docs/assets/vlmprobe-technical-report.pdf)
compares real readouts, explanations, and interventions on shared cases across
five pretrained VLMs, with language and vision controls.

## Credits

SAE integration draws on [SAELens](https://github.com/decoderesearch/SAELens),
[ViT-Prisma](https://github.com/Prisma-Multimodal/ViT-Prisma) and
[Overcomplete](https://github.com/KempnerInstitute/overcomplete).
Our native algorithms and checkpoint converters retain source attribution and
MIT license notices; see [SAE provenance](docs/methods/sae/SOURCES.md).
