interpkit 0.1.0__tar.gz

interpkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Zani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

interpkit-0.1.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: interpkit
+Version: 0.1.0
+Summary: Mech interp for any HuggingFace model.
+Author: Davide Zani
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/davidezani/InterpKit
+Project-URL: Repository, https://github.com/davidezani/InterpKit
+Project-URL: Issues, https://github.com/davidezani/InterpKit/issues
+Keywords: mechanistic-interpretability,pytorch,transformers,mech-interp,interpretability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.1
+Requires-Dist: transformers>=4.36
+Requires-Dist: nnsight>=0.3
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Requires-Dist: Pillow>=10.0
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: huggingface-hub>=0.20
+Provides-Extra: probe
+Requires-Dist: scikit-learn>=1.3; extra == "probe"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.2; extra == "dev"
+Requires-Dist: scikit-learn>=1.3; extra == "dev"
+Dynamic: license-file
+
+# InterpKit
+
+> Mech interp for any HuggingFace model.
+
+[![PyPI version](https://img.shields.io/pypi/v/interpkit.svg)](https://pypi.org/project/interpkit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## The Problem
+
+TransformerLens is excellent — but only works on GPT-style decoder-only transformers. The moment you step outside that (Mamba, SSMs, ViT, CNNs, BERT, T5, MoE models), there is no equivalent tool. You write hook code from scratch every time.
+
+InterpKit fills this gap: the same standard mech interp operations, on any HuggingFace model, with no annotation required.
+
+---
+
+## Install
+
+```bash
+pip install interpkit
+
+# For linear probe support:
+pip install interpkit[probe]
+```
+
+Or install from source for development:
+
+```bash
+git clone https://github.com/davidezani/InterpKit.git
+cd InterpKit
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart
+
+```python
+import interpkit
+
+model = interpkit.load("gpt2")
+
+model.inspect()                    # module tree with roles, params, shapes
+model.trace("...Paris...", "...Rome...", top_k=20)   # causal tracing
+model.patch("...Paris...", "...Rome...", at="transformer.h.8.mlp")
+model.lens("The capital of France is")               # logit lens
+model.attribute("The capital of France is")          # gradient saliency
+```
+
+Works the same on any HF architecture:
+
+```python
+model = interpkit.load("state-spaces/mamba-370m")
+model = interpkit.load("google/vit-base-patch16-224")
+model = interpkit.load("bert-base-uncased")
+```
+
+---
+
+## Operations
+
+| Operation | What it does | Works on |
+|-----------|-------------|----------|
+| `inspect` | Module tree with types, param counts, shapes | Any model |
+| `patch` | Activation patching at a named module | Any model |
+| `trace` | Causal tracing across modules, ranked by effect | Any model |
+| `attribute` | Gradient saliency over inputs | Any model |
+| `lens` | Logit lens — project activations to vocabulary | LMs (auto-detected) |
+| `activations` | Extract raw activation tensors at any module | Any model |
+| `ablate` | Zero/mean ablate a component and measure effect | Any model |
+| `attention` | Visualize attention patterns per layer/head | Transformers |
+| `steer` | Extract and apply steering vectors | Any model |
+| `probe` | Linear probe on activations | Any model |
+| `diff` | Compare activations between two models | Any model |
+| `features` | SAE feature decomposition | Any model |
+
+---
+
+## Activations, Ablation, Attention
+
+```python
+# Extract raw activations
+act = model.activations("The capital of France is", at="transformer.h.8.mlp")
+acts = model.activations("...", at=["transformer.h.0", "transformer.h.8.mlp"])
+
+# Ablation — zero or mean
+result = model.ablate("The capital of France is", at="transformer.h.8.mlp")
+result = model.ablate("...", at="transformer.h.8.mlp", method="mean")
+
+# Attention patterns
+model.attention("The capital of France is")                   # all layers
+model.attention("The capital of France is", layer=8, head=3)  # single head
+```
+
+## Steering
+
+```python
+# 1. Extract a steering vector
+vector = model.steer_vector("Love", "Hate", at="transformer.h.8")
+
+# 2. Apply during inference — side-by-side comparison
+model.steer("The weather today is", vector=vector, at="transformer.h.8", scale=2.0)
+```
+
+## Linear Probe
+
+```python
+result = model.probe(
+    texts=["The cat sat", "The dog ran", "A bird flew", "A fish swam"],
+    labels=[0, 0, 1, 1],
+    at="transformer.h.8",
+)
+print(result["accuracy"])
+```
+
+## Model Diff
+
+```python
+base = interpkit.load("gpt2")
+finetuned = interpkit.load("my-finetuned-gpt2")
+interpkit.diff(base, finetuned, "The capital of France is")
+```
+
+## SAE Features
+
+Decompose activations into interpretable features using pre-trained Sparse Autoencoders from HuggingFace:
+
+```python
+model.features(
+    "The capital of France is",
+    at="transformer.h.8",
+    sae="jbloom/GPT2-Small-SAEs-Reformatted",
+)
+```
+
+No SAELens dependency — weights are loaded directly via `safetensors`.
+
+## Activation Cache
+
+Avoid redundant forward passes when exploring the same input with multiple operations:
+
+```python
+model.cache("The capital of France is")  # one forward pass, cache all layers
+model.activations("The capital of France is", at="transformer.h.8.mlp")  # instant
+model.activations("The capital of France is", at="transformer.h.0.mlp")  # instant
+
+model.clear_cache()  # free memory
+```
+
+---
+
+## Visualizations
+
+Pass `save="path.png"` to export a static matplotlib figure, or `html="path.html"` for an interactive visualization:
+
+```python
+model.attention("hello world", layer=0, head=0, save="attention.png")
+model.trace("...Paris...", "...Rome...", save="trace.png")
+model.lens("The capital of France is", save="lens.png")
+model.steer("The weather is", vector=vector, at="transformer.h.8", save="steer.png")
+model.attribute("The capital of France is", save="attribution.png")
+interpkit.diff(base, finetuned, "...", save="diff.png")
+
+# Interactive HTML — self-contained files with hover tooltips, filters, and sliders
+model.attention("hello world", html="attention.html")
+model.trace("...Paris...", "...Rome...", html="trace.html")
+model.attribute("The capital of France is", html="attribution.html")
+```
+
+---
+
+## CLI
+
+```bash
+interpkit inspect gpt2
+interpkit trace gpt2 --clean "...Paris..." --corrupted "...Rome..." --top-k 20
+interpkit lens gpt2 "The capital of France is"
+interpkit attention gpt2 "The capital of France is" --layer 8 --save attention.png
+interpkit steer gpt2 "The weather is" --positive Love --negative Hate --at transformer.h.8
+interpkit ablate gpt2 "The capital of France is" --at transformer.h.8.mlp
+interpkit diff gpt2 my-finetuned-gpt2 "The capital of France is" --save diff.png
+interpkit features gpt2 "The capital of France is" --at transformer.h.8 --sae jbloom/GPT2-Small-SAEs-Reformatted
+
+# Interactive HTML output
+interpkit attention gpt2 "hello world" --html attention.html
+interpkit trace gpt2 --clean "...Paris..." --corrupted "...Rome..." --html trace.html
+interpkit attribute gpt2 "The capital of France is" --html attribution.html
+
+# Vision models — auto-preprocessed
+interpkit attribute microsoft/resnet-50 cat.jpg --target 281
+```
+
+Run `interpkit` with no arguments for a full command reference.
+
+---
+
+## TransformerLens interop
+
+Already using TransformerLens? Pass your `HookedTransformer` directly into InterpKit — it auto-detects the model and extracts the tokenizer:
+
+```python
+from transformer_lens import HookedTransformer
+import interpkit
+
+tl_model = HookedTransformer.from_pretrained("gpt2")
+model = interpkit.load(tl_model)
+
+# All InterpKit operations work on TL models
+model.trace("The Eiffel Tower is in Paris", "The Eiffel Tower is in Rome", top_k=20)
+model.attention("The capital of France is", save="attention.png")
+model.steer("The weather is", vector=vector, at="blocks.8", scale=2.0)
+```
+
+Translate between native and TL hook point names:
+
+```python
+interpkit.to_tl_name("transformer.h.8.mlp")       # -> "blocks.8.mlp"
+interpkit.to_native_name("blocks.8.attn", model.arch_info)  # -> "transformer.h.8.attn"
+interpkit.list_tl_hooks(tl_model)                  # -> ["blocks.0.hook_resid_pre", ...]
+```
+
+---
+
+## Local models
+
+```python
+import torch.nn as nn
+import interpkit
+
+my_model = MyCustomModel()
+interpkit.register(my_model, layers=["blocks.0", "blocks.1"], output_head="head")
+model = interpkit.load(my_model, tokenizer=my_tokenizer)
+model.trace(input_a, input_b, top_k=10)
+```
+
+---
+
+## Examples
+
+See the [`examples/`](examples/) directory for Jupyter notebooks:
+
+| Notebook | Topics |
+|----------|--------|
+| `01_quickstart` | Inspect, trace, lens, attribution, patching, ablation |
+| `02_attention_patterns` | Per-head heatmaps, layer filtering, HTML export |
+| `03_steering_vectors` | Extract and apply steering vectors at different layers/scales |
+| `04_sae_features` | Sparse Autoencoder feature decomposition |
+| `05_caching_and_probing` | Activation cache, linear probes across layers |
+| `06_model_comparison` | Diff two models, side-by-side tracing and logit lens |
+| `07_vision_models` | ResNet/ViT attribution, ablation, activations |
+
+---
+
+## License
+
+MIT

interpkit-0.1.0/README.md

@@ -0,0 +1,258 @@
+# InterpKit
+
+> Mech interp for any HuggingFace model.
+
+[![PyPI version](https://img.shields.io/pypi/v/interpkit.svg)](https://pypi.org/project/interpkit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## The Problem
+
+TransformerLens is excellent — but only works on GPT-style decoder-only transformers. The moment you step outside that (Mamba, SSMs, ViT, CNNs, BERT, T5, MoE models), there is no equivalent tool. You write hook code from scratch every time.
+
+InterpKit fills this gap: the same standard mech interp operations, on any HuggingFace model, with no annotation required.
+
+---
+
+## Install
+
+```bash
+pip install interpkit
+
+# For linear probe support:
+pip install interpkit[probe]
+```
+
+Or install from source for development:
+
+```bash
+git clone https://github.com/davidezani/InterpKit.git
+cd InterpKit
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart
+
+```python
+import interpkit
+
+model = interpkit.load("gpt2")
+
+model.inspect()                    # module tree with roles, params, shapes
+model.trace("...Paris...", "...Rome...", top_k=20)   # causal tracing
+model.patch("...Paris...", "...Rome...", at="transformer.h.8.mlp")
+model.lens("The capital of France is")               # logit lens
+model.attribute("The capital of France is")          # gradient saliency
+```
+
+Works the same on any HF architecture:
+
+```python
+model = interpkit.load("state-spaces/mamba-370m")
+model = interpkit.load("google/vit-base-patch16-224")
+model = interpkit.load("bert-base-uncased")
+```
+
+---
+
+## Operations
+
+| Operation | What it does | Works on |
+|-----------|-------------|----------|
+| `inspect` | Module tree with types, param counts, shapes | Any model |
+| `patch` | Activation patching at a named module | Any model |
+| `trace` | Causal tracing across modules, ranked by effect | Any model |
+| `attribute` | Gradient saliency over inputs | Any model |
+| `lens` | Logit lens — project activations to vocabulary | LMs (auto-detected) |
+| `activations` | Extract raw activation tensors at any module | Any model |
+| `ablate` | Zero/mean ablate a component and measure effect | Any model |
+| `attention` | Visualize attention patterns per layer/head | Transformers |
+| `steer` | Extract and apply steering vectors | Any model |
+| `probe` | Linear probe on activations | Any model |
+| `diff` | Compare activations between two models | Any model |
+| `features` | SAE feature decomposition | Any model |
+
+---
+
+## Activations, Ablation, Attention
+
+```python
+# Extract raw activations
+act = model.activations("The capital of France is", at="transformer.h.8.mlp")
+acts = model.activations("...", at=["transformer.h.0", "transformer.h.8.mlp"])
+
+# Ablation — zero or mean
+result = model.ablate("The capital of France is", at="transformer.h.8.mlp")
+result = model.ablate("...", at="transformer.h.8.mlp", method="mean")
+
+# Attention patterns
+model.attention("The capital of France is")                   # all layers
+model.attention("The capital of France is", layer=8, head=3)  # single head
+```
+
+## Steering
+
+```python
+# 1. Extract a steering vector
+vector = model.steer_vector("Love", "Hate", at="transformer.h.8")
+
+# 2. Apply during inference — side-by-side comparison
+model.steer("The weather today is", vector=vector, at="transformer.h.8", scale=2.0)
+```
+
+## Linear Probe
+
+```python
+result = model.probe(
+    texts=["The cat sat", "The dog ran", "A bird flew", "A fish swam"],
+    labels=[0, 0, 1, 1],
+    at="transformer.h.8",
+)
+print(result["accuracy"])
+```
+
+## Model Diff
+
+```python
+base = interpkit.load("gpt2")
+finetuned = interpkit.load("my-finetuned-gpt2")
+interpkit.diff(base, finetuned, "The capital of France is")
+```
+
+## SAE Features
+
+Decompose activations into interpretable features using pre-trained Sparse Autoencoders from HuggingFace:
+
+```python
+model.features(
+    "The capital of France is",
+    at="transformer.h.8",
+    sae="jbloom/GPT2-Small-SAEs-Reformatted",
+)
+```
+
+No SAELens dependency — weights are loaded directly via `safetensors`.
+
+## Activation Cache
+
+Avoid redundant forward passes when exploring the same input with multiple operations:
+
+```python
+model.cache("The capital of France is")  # one forward pass, cache all layers
+model.activations("The capital of France is", at="transformer.h.8.mlp")  # instant
+model.activations("The capital of France is", at="transformer.h.0.mlp")  # instant
+
+model.clear_cache()  # free memory
+```
+
+---
+
+## Visualizations
+
+Pass `save="path.png"` to export a static matplotlib figure, or `html="path.html"` for an interactive visualization:
+
+```python
+model.attention("hello world", layer=0, head=0, save="attention.png")
+model.trace("...Paris...", "...Rome...", save="trace.png")
+model.lens("The capital of France is", save="lens.png")
+model.steer("The weather is", vector=vector, at="transformer.h.8", save="steer.png")
+model.attribute("The capital of France is", save="attribution.png")
+interpkit.diff(base, finetuned, "...", save="diff.png")
+
+# Interactive HTML — self-contained files with hover tooltips, filters, and sliders
+model.attention("hello world", html="attention.html")
+model.trace("...Paris...", "...Rome...", html="trace.html")
+model.attribute("The capital of France is", html="attribution.html")
+```
+
+---
+
+## CLI
+
+```bash
+interpkit inspect gpt2
+interpkit trace gpt2 --clean "...Paris..." --corrupted "...Rome..." --top-k 20
+interpkit lens gpt2 "The capital of France is"
+interpkit attention gpt2 "The capital of France is" --layer 8 --save attention.png
+interpkit steer gpt2 "The weather is" --positive Love --negative Hate --at transformer.h.8
+interpkit ablate gpt2 "The capital of France is" --at transformer.h.8.mlp
+interpkit diff gpt2 my-finetuned-gpt2 "The capital of France is" --save diff.png
+interpkit features gpt2 "The capital of France is" --at transformer.h.8 --sae jbloom/GPT2-Small-SAEs-Reformatted
+
+# Interactive HTML output
+interpkit attention gpt2 "hello world" --html attention.html
+interpkit trace gpt2 --clean "...Paris..." --corrupted "...Rome..." --html trace.html
+interpkit attribute gpt2 "The capital of France is" --html attribution.html
+
+# Vision models — auto-preprocessed
+interpkit attribute microsoft/resnet-50 cat.jpg --target 281
+```
+
+Run `interpkit` with no arguments for a full command reference.
+
+---
+
+## TransformerLens interop
+
+Already using TransformerLens? Pass your `HookedTransformer` directly into InterpKit — it auto-detects the model and extracts the tokenizer:
+
+```python
+from transformer_lens import HookedTransformer
+import interpkit
+
+tl_model = HookedTransformer.from_pretrained("gpt2")
+model = interpkit.load(tl_model)
+
+# All InterpKit operations work on TL models
+model.trace("The Eiffel Tower is in Paris", "The Eiffel Tower is in Rome", top_k=20)
+model.attention("The capital of France is", save="attention.png")
+model.steer("The weather is", vector=vector, at="blocks.8", scale=2.0)
+```
+
+Translate between native and TL hook point names:
+
+```python
+interpkit.to_tl_name("transformer.h.8.mlp")       # -> "blocks.8.mlp"
+interpkit.to_native_name("blocks.8.attn", model.arch_info)  # -> "transformer.h.8.attn"
+interpkit.list_tl_hooks(tl_model)                  # -> ["blocks.0.hook_resid_pre", ...]
+```
+
+---
+
+## Local models
+
+```python
+import torch.nn as nn
+import interpkit
+
+my_model = MyCustomModel()
+interpkit.register(my_model, layers=["blocks.0", "blocks.1"], output_head="head")
+model = interpkit.load(my_model, tokenizer=my_tokenizer)
+model.trace(input_a, input_b, top_k=10)
+```
+
+---
+
+## Examples
+
+See the [`examples/`](examples/) directory for Jupyter notebooks:
+
+| Notebook | Topics |
+|----------|--------|
+| `01_quickstart` | Inspect, trace, lens, attribution, patching, ablation |
+| `02_attention_patterns` | Per-head heatmaps, layer filtering, HTML export |
+| `03_steering_vectors` | Extract and apply steering vectors at different layers/scales |
+| `04_sae_features` | Sparse Autoencoder feature decomposition |
+| `05_caching_and_probing` | Activation cache, linear probes across layers |
+| `06_model_comparison` | Diff two models, side-by-side tracing and logit lens |
+| `07_vision_models` | ResNet/ViT attribution, ablation, activations |
+
+---
+
+## License
+
+MIT

interpkit-0.1.0/interpkit/__init__.py

@@ -0,0 +1,15 @@
+"""interpkit — mech interp for any HuggingFace model."""
+
+from interpkit.core.model import load
+from interpkit.core.registry import register
+from interpkit.core.tl_compat import list_tl_hooks, to_native_name, to_tl_name
+
+
+def diff(model_a, model_b, input_data, *, save=None):
+    """Compare activations between two models on the same input."""
+    from interpkit.ops.diff import run_diff
+
+    return run_diff(model_a, model_b, input_data, save=save)
+
+
+__all__ = ["load", "register", "diff", "to_tl_name", "to_native_name", "list_tl_hooks"]