Release v4.0.0

.cursor/rules/transformerlens.mdc

@@ -3,7 +3,7 @@ description: TransformerLens project conventions for Cursor agents.
 alwaysApply: true
 ---
 
-Read `AGENTS.md` at the repo root before doing any work. It is the single source of truth for project conventions, quickstart commands, repo layout, hook-naming rules, the HookedTransformer ↔ TransformerBridge mirroring rule, PR conventions, and hard rules.
+Read `AGENTS.md` at the repo root before doing any work. It is the single source of truth for project conventions, quickstart commands, repo layout, hook-naming rules, PR conventions, and hard rules.
 
 Sub-folder `AGENTS.md` files apply when you're working in those directories — read them too:
 
@@ -14,7 +14,7 @@ Sub-folder `AGENTS.md` files apply when you're working in those directories —
 Quick reminders that override common defaults:
 
 - Use `uv`, not `pip` or `poetry`. Install with `uv sync`; run commands with `uv run …` or `make` targets.
-- This repo has two parallel systems (`HookedTransformer` legacy and `TransformerBridge` v3). Changes to HookedTransformer that have equivalents in TransformerBridge must be mirrored to TransformerBridge.
+- `TransformerBridge` is the only model system; `HookedTransformer` and the other `Hooked*` model classes were removed in 4.0 (`HookedRootModule` / `HookPoint` remain).
 - Base PRs against `dev`, not `main`. Never name a branch `main` or `dev`.
 - No pre-commit hook is installed. Run `make format` and `uv run mypy .` manually before push.
 - Source `.env` (e.g. `set -a; source .env; set +a`) before any HuggingFace-Hub-hitting command.

.github/copilot-instructions.md

@@ -5,7 +5,7 @@
 ## Top rules to remember
 
 1. **Use `uv`, not `pip` or `poetry`.** `uv sync` to install; `uv run <cmd>` or a `make` target to run anything.
-2. **Mirror `HookedTransformer` → `TransformerBridge`** in the same PR when behaviour exists in both. The HT registry [`transformer_lens/supported_models.py`](../transformer_lens/supported_models.py) is HT-only — Bridge-only models go in the Bridge registry under [`transformer_lens/tools/model_registry/`](../transformer_lens/tools/model_registry/).
+2. **The `Hooked*` model classes were removed in 4.0**; `TransformerBridge` is the one model system. [`transformer_lens/supported_models.py`](../transformer_lens/supported_models.py) is the frozen legacy name/alias ledger; Bridge models live under [`transformer_lens/tools/model_registry/`](../transformer_lens/tools/model_registry/).
 3. **Base PRs against `dev`**, not `main`. PRs to `main` are maintainer-only.
 
 ## Common commands

.github/workflows/checks.yml

@@ -117,7 +117,7 @@ jobs:
       - name: Install dependencies
         run: |
           uv lock --check
-          uv sync
+          uv sync --extra inspect
       - name: Authenticate HuggingFace
         if: env.HF_TOKEN != ''
         run: uv run python -c "import os; from huggingface_hub import login; login(token=os.environ['HF_TOKEN'])"
@@ -135,6 +135,8 @@ jobs:
   mps-checks:
     name: MPS Checks
     runs-on: macos-latest
+    # Bounded so a stall costs 90 minutes of macOS runner time, not the 6-hour default.
+    timeout-minutes: 90
     # Only run on PRs merging to main or pushes directly to main
     if: >
       (github.event_name == 'pull_request' && github.base_ref == 'main') ||
@@ -171,7 +173,7 @@ jobs:
       - name: Install dependencies
         run: |
           uv lock --check
-          uv sync
+          uv sync --extra inspect
       - name: MPS Availability Check
         run: |
           uv run python -c "
@@ -189,11 +191,9 @@ jobs:
           --ignore=tests/unit/model_bridge/test_optimizer_compatibility.py
           --ignore=tests/unit/model_bridge/test_gpt_oss_moe.py
           --ignore=tests/unit/model_bridge/test_component_inspection.py
-          --ignore=tests/unit/model_bridge/test_key_analysis.py
           --ignore=tests/unit/model_bridge/test_benchmark_gated_hooks_fire.py
-          --ignore=tests/unit/model_bridge/test_weight_processing_adapter_paths.py
           --ignore=tests/unit/model_bridge/test_bridge_generate_kv_cache.py
-          --ignore=tests/unit/model_bridge/test_bridge_vs_hooked_transformer_patching.py
+          --ignore=tests/unit/model_bridge/test_bridge_cross_run_qkv_patching.py
           --ignore=tests/unit/model_bridge/compatibility/
         env:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
@@ -347,7 +347,7 @@ jobs:
       - name: Install dependencies
         run: |
           uv lock --check
-          uv sync
+          uv sync --extra inspect
       - name: Authenticate HuggingFace
         if: env.HF_TOKEN != ''
         run: uv run python -c "import os; from huggingface_hub import login; login(token=os.environ['HF_TOKEN'])"

.github/workflows/oracle-parity.yml

@@ -1,17 +1,11 @@
 name: Oracle Parity
 
 # Runs the @pytest.mark.slow oracle parity suite for JacobianLens.
-# Not part of the standard PR gate — requires ~4 GB VRAM and network access.
-# Triggered manually or automatically when the test file or this workflow changes.
+# Not part of the standard PR gate — requires ~4 GB VRAM (or a long CPU run)
+# and network access, so it is manual-trigger only. Run it after changing
+# tests/integration/test_jacobian_lens_oracle_parity.py or this workflow.
 on:
   workflow_dispatch:
-  push:
-    branches:
-      - main
-      - dev*
-    paths:
-      - "tests/integration/test_jacobian_lens_oracle_parity.py"
-      - ".github/workflows/oracle-parity.yml"
 
 permissions:
   contents: read
@@ -21,6 +15,8 @@ jobs:
     name: Oracle Parity Checks
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    env:
+      HAS_HF_TOKEN: ${{ secrets.HF_TOKEN != '' }}
     steps:
       - uses: actions/checkout@v4
 
@@ -46,7 +42,7 @@ jobs:
           uv pip install "git+https://github.com/anthropics/jacobian-lens.git@${ORACLE_COMMIT}"
 
       - name: Authenticate HuggingFace
-        if: env.HF_TOKEN != ''
+        if: ${{ env.HAS_HF_TOKEN == 'true' }}
         run: uv run python -c "import os; from huggingface_hub import login; login(token=os.environ['HF_TOKEN'])"
         env:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}

.github/workflows/slow-tests.yml

@@ -0,0 +1,69 @@
+# Nightly slow-tier run. 20+ integration/acceptance files carry
+# @pytest.mark.slow, and no PR-gating workflow executes them — without this
+# job that coverage reads as CI-gated when it never runs (flagged in the
+# #1593/#1598 reviews). Manual trigger available for pre-merge checks.
+#
+# NOTE: GitHub only fires `schedule` from the default branch, so the cron is
+# inert until this file reaches `main`; use workflow_dispatch (via the API or
+# `gh workflow run --ref <branch>`) before then.
+name: Slow Tests
+
+on:
+  schedule:
+    - cron: "0 5 * * *" # nightly, off-peak
+  workflow_dispatch:
+
+concurrency:
+  group: slow-tests
+  cancel-in-progress: false
+
+jobs:
+  slow-tests:
+    name: Slow Tests (nightly)
+    runs-on: ubuntu-latest
+    timeout-minutes: 300
+    steps:
+      - uses: actions/checkout@v4
+      - name: Free runner disk (slow tier downloads tens of GB of checkpoints)
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
+          df -h /
+      - name: Add swap for fp32 CPU model boots
+        run: |
+          sudo fallocate -l 8G /swapfile
+          sudo chmod 600 /swapfile
+          sudo mkswap /swapfile
+          sudo swapon /swapfile
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.11"
+          activate-environment: true
+          enable-cache: true
+      - name: Re-use HuggingFace models cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface/hub
+          key: ${{ runner.os }}-huggingface-models-v4-slow
+          restore-keys: |
+            ${{ runner.os }}-huggingface-models-v4
+            ${{ runner.os }}-huggingface-models
+      - name: Install dependencies
+        run: |
+          uv lock --check
+          uv sync --extra inspect
+      - name: Authenticate HuggingFace
+        if: env.HF_TOKEN != ''
+        run: uv run python -c "import os; from huggingface_hub import login; login(token=os.environ['HF_TOKEN'])"
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+      # Models needing more RAM/disk than a 16GB/14GB runner (+8G swap) can
+      # serve are deselected explicitly rather than silently OOM-crashing the
+      # job; they need a large-runner or self-hosted follow-up.
+      - name: Slow tests (unit + integration + acceptance)
+        run: >
+          uv run pytest tests/unit tests/integration tests/acceptance
+          -m slow --reruns 2 --reruns-delay 5 --durations=25
+          --ignore=tests/integration/model_bridge/test_nemotron_h_adapter.py
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}

AGENTS.md

@@ -11,7 +11,7 @@ This file is the single source of truth. Vendor-specific files ([CLAUDE.md](CLAU
 1. **Use `uv`**, not `pip` or `poetry` (`uv sync`).
 2. **Source `.env`** (`set -a; source .env; set +a`) before any HF-Hub command.
 3. **Base PRs on `dev`**, not `main`. Never name a branch `main` or `dev`.
-4. **Mirror HookedTransformer → TransformerBridge** when behaviour exists in both ([§2](#2-two-systems-live-in-this-repo)).
+4. **The `Hooked*` model classes were removed in 4.0**; `HookedRootModule` / `HookPoint` are kept ([§2](#2-two-systems-live-in-this-repo)).
 5. **`make format` + `uv run mypy .` before push** — no pre-commit hook.
 6. **Never add `# type: ignore`** ([§10](#10-hard-rules)).
 7. **Never dismiss a failing test as "pre-existing"** ([§10](#10-hard-rules)).
@@ -22,20 +22,20 @@ Sub-folder rules: [tests/AGENTS.md](tests/AGENTS.md) · [supported_architectures
 
 ## 1. What this repo is
 
-**TransformerLens** — mechanistic-interpretability library. Loads 9,000+ models across 50+ architecture families (see [supported_models.json](transformer_lens/tools/model_registry/data/supported_models.json)) and exposes internal activations through a hook system for caching, editing, and ablating intermediate state. Built on HuggingFace `transformers`.
+**TransformerLens** — mechanistic-interpretability library. Loads 15,000+ models across 140+ architecture families (see [supported_models.json](transformer_lens/tools/model_registry/data/supported_models.json)) and exposes internal activations through a hook system for caching, editing, and ablating intermediate state. Built on HuggingFace `transformers`.
 
 ## 2. Two systems live in this repo
 
 | System | Status | Lives in | Numerics | Registry |
 |---|---|---|---|---|
 | **`TransformerBridge`** | v3 — default for new work | [transformer_lens/model_bridge/](transformer_lens/model_bridge/) | Raw HF weights by default; `bridge.enable_compatibility_mode()` for HT-equivalent | [transformer_lens/tools/model_registry/data/supported_models.json](transformer_lens/tools/model_registry/data/supported_models.json) |
-| **`HookedTransformer`** | Legacy, maintenance mode, deprecated in 3.0 | [transformer_lens/HookedTransformer.py](transformer_lens/HookedTransformer.py) + [transformer_lens/components/](transformer_lens/components/) | Folds LayerNorm + centres weights → does NOT match HF | [transformer_lens/supported_models.py](transformer_lens/supported_models.py) (**HT-only**) |
+| **`HookedTransformer`** | **Removed in 4.0** — use `TransformerBridge` + `enable_compatibility_mode()` | *(deleted; see [migrating_to_v4.md](docs/source/content/migrating_to_v4.md))* | — | — |
 
-> ⚠ The **HookedTransformer acceptance suite is quarantined** ([test_hooked_transformer.py](tests/acceptance/test_hooked_transformer.py), [test_hooked_encoder.py](tests/acceptance/test_hooked_encoder.py), [test_hooked_encoder_decoder.py](tests/acceptance/test_hooked_encoder_decoder.py); see [QUARANTINES.md](tests/QUARANTINES.md)). HT changes land untested at the acceptance level — extra manual care required.
+> ⚠ `HookedRootModule` + `HookPoint` survive 4.0 as the supported way to hook an arbitrary `nn.Module`. `supported_models.py` is kept as the frozen legacy name/alias ledger (hosts the case-insensitive `get_official_model_name`). See [QUARANTINES.md](tests/QUARANTINES.md) for test skips.
 
-Bridge architecture-adapter pattern: each HF architecture has one file in [supported_architectures/](transformer_lens/model_bridge/supported_architectures/) mapping HF module paths to canonical names. Bridge hooks are architecture-native (e.g. `blocks.{i}.hook_out`); HT-style aliases live in [bridge.py](transformer_lens/model_bridge/bridge.py).
+Bridge architecture-adapter pattern: each HF architecture has one file in [supported_architectures/](transformer_lens/model_bridge/supported_architectures/) mapping HF module paths to canonical names. Bridge hooks are architecture-native (e.g. `blocks.{i}.hook_out`); HT-style aliases live in [bridge_core.py](transformer_lens/model_bridge/bridge_core.py).
 
-**Mirroring rule:** if you change `HookedTransformer` behaviour that has a `TransformerBridge` counterpart, update both in the same PR. [supported_models.py](transformer_lens/supported_models.py) is HT-only — Bridge-only models go in the Bridge registry data file.
+There is now one model system: `TransformerBridge`. [supported_models.py](transformer_lens/supported_models.py) holds the frozen legacy name/alias ledger; Bridge models live in the Bridge registry data file.
 
 ## 3. Quickstart
 
@@ -81,24 +81,22 @@ Python: **>=3.10, <4.0**. CI tests 3.10, 3.11, 3.12. Format/type/docstring check
 | Path | What's there |
 |---|---|
 | [transformer_lens/](transformer_lens/) | Core package |
-| [transformer_lens/HookedTransformer.py](transformer_lens/HookedTransformer.py) | Legacy `HookedTransformer` API |
-| [transformer_lens/HookedEncoder.py](transformer_lens/HookedEncoder.py), [HookedEncoderDecoder.py](transformer_lens/HookedEncoderDecoder.py), [HookedAudioEncoder.py](transformer_lens/HookedAudioEncoder.py) | Encoder-only / seq2seq / audio variants |
 | [transformer_lens/model_bridge/](transformer_lens/model_bridge/) | `TransformerBridge` system |
 | [transformer_lens/model_bridge/supported_architectures/](transformer_lens/model_bridge/supported_architectures/) | One adapter file per HF architecture |
 | [transformer_lens/model_bridge/generalized_components/](transformer_lens/model_bridge/generalized_components/) | Bridge-side reusable components |
-| [transformer_lens/components/](transformer_lens/components/) | HT-side components (attention, MLP, LN, embed) |
-| [transformer_lens/factories/](transformer_lens/factories/) | `architecture_adapter_factory.py`, `mlp_factory.py`, `activation_function_factory.py` |
-| [transformer_lens/config/](transformer_lens/config/) | `HookedTransformerConfig` and `TransformerBridgeConfig` |
+| [transformer_lens/factories/](transformer_lens/factories/) | `architecture_adapter_factory.py`, `activation_function_factory.py` |
+| [transformer_lens/config/](transformer_lens/config/) | `TransformerBridgeConfig` / `TransformerLensConfig` |
 | [transformer_lens/utilities/](transformer_lens/utilities/) | Device management, weight processing, HF utilities |
 | [transformer_lens/hook_points.py](transformer_lens/hook_points.py) | `HookPoint` class and `LensHandle` |
 | [transformer_lens/supported_models.py](transformer_lens/supported_models.py) | **HT-only** registry (`OFFICIAL_MODEL_NAMES`, `MODEL_ALIASES`) |
 | [transformer_lens/tools/model_registry/](transformer_lens/tools/model_registry/) | Bridge-side registry + `verify_models.py` benchmark suite |
-| [transformer_lens/tools/analysis/](transformer_lens/tools/analysis/) | High-level single-call analyses over the cache (e.g. `direct_logit_attribution`); works with both HT and Bridge |
+| [transformer_lens/tools/analysis/](transformer_lens/tools/analysis/) | High-level single-call analyses over the cache (e.g. `direct_logit_attribution`) on TransformerBridge |
 | [transformer_lens/patching.py](transformer_lens/patching.py), [evals.py](transformer_lens/evals.py) | Activation patching, IOI, ROME, etc. |
 | [tests/unit/](tests/unit/), [tests/integration/](tests/integration/), [tests/acceptance/](tests/acceptance/), [tests/benchmarks/](tests/benchmarks/), [tests/mps/](tests/mps/) | Test tiers |
 | [demos/](demos/) | Jupyter notebooks; a subset runs in CI under `nbval` with sanitization from [demos/doc_sanitize.cfg](demos/doc_sanitize.cfg) |
 | [docs/source/content/](docs/source/content/) | Sphinx markdown sources |
 | [docs/source/content/adapter_development/](docs/source/content/adapter_development/) | Adapter-authoring guides — read these before adding a new architecture |
+| [devtools/adapter_builder/](devtools/adapter_builder/) | Contributor-only agent-team adapter builder (not shipped in the package) — see its [README](devtools/adapter_builder/README.md) |
 | [makefile](makefile) | Canonical test/format/docs targets |
 | [pyproject.toml](pyproject.toml) | Deps, pytest / mypy / format / build config |
 | [.github/workflows/checks.yml](.github/workflows/checks.yml) | CI gates |
@@ -107,13 +105,13 @@ Python: **>=3.10, <4.0**. CI tests 3.10, 3.11, 3.12. Format/type/docstring check
 ## 5. Hook naming — HT vs Bridge
 
 - **HT canonical**: uniform across architectures — `hook_embed`, `blocks.{i}.hook_resid_pre`, `blocks.{i}.attn.hook_q`, `blocks.{i}.hook_resid_post`.
-- **Bridge-native**: architecture-shaped — `blocks.{i}.hook_out`, `blocks.{i}.attn.q.hook_out`. HT aliases registered via `build_alias_to_canonical_map()` in [bridge.py](transformer_lens/model_bridge/bridge.py).
+- **Bridge-native**: architecture-shaped — `blocks.{i}.hook_out`, `blocks.{i}.attn.q.hook_out`. HT aliases registered via `build_alias_to_canonical_map()` in [bridge_core.py](transformer_lens/model_bridge/bridge_core.py).
 
 Prefer Bridge-native names in new code. Raw-HF-forward drivers comparing against `boot_transformers` must match its load configuration (fp32, eager attention) and probe for optional features like `resid_mid` rather than assume.
 
 ## 6. Adding a model
 
-Adapters are written **per architecture family**, not per individual model — adding `gpt2` registers all GPT-2 variants. Full workflow (starter-adapter table, 4-place registration, common gotchas, anti-patterns): **[supported_architectures/AGENTS.md](transformer_lens/model_bridge/supported_architectures/AGENTS.md)**. Verification flow: **[tools/model_registry/AGENTS.md](transformer_lens/tools/model_registry/AGENTS.md)**. Claude Code users: invoke `/add-model-support <hf_repo>`.
+Adapters are written **per architecture family**, not per individual model — adding `gpt2` registers all GPT-2 variants. Full workflow (starter-adapter table, 4-place registration, common gotchas, anti-patterns): **[supported_architectures/AGENTS.md](transformer_lens/model_bridge/supported_architectures/AGENTS.md)**. Verification flow: **[tools/model_registry/AGENTS.md](transformer_lens/tools/model_registry/AGENTS.md)**. Claude Code users: invoke `/add-model-support <hf_repo>`. For batch/autonomous adapter creation there is an agent harness in [devtools/adapter_builder/](devtools/adapter_builder/README.md) — agent-teams mode needs Claude Code Max; its solo mode works on any tier.
 
 ## 7. Prioritization
 
@@ -196,7 +194,7 @@ Claude Code: `/task-complete` automates the last row. See [§15 Workflow shortcu
 
 ## 12. Pointers for further reading
 
-- [docs/source/content/migrating_to_v3.md](docs/source/content/migrating_to_v3.md) — HT → Bridge migration recipes
+- [docs/source/content/migrating_to_v4.md](docs/source/content/migrating_to_v4.md) — 4.0 removed-name → Bridge mapping ([v3 guide](docs/source/content/migrating_to_v3.md) for deeper API recipes)
 - [docs/source/content/adapter_development/](docs/source/content/adapter_development/) — adapter authoring deep dive
 - [docs/source/content/compatibility_mode.md](docs/source/content/compatibility_mode.md) — when to call `bridge.enable_compatibility_mode()`, what each flag does, four-quadrant test matrix
 - [docs/source/content/debugging_numerical_divergence.md](docs/source/content/debugging_numerical_divergence.md) — bisection workflow for HT-vs-Bridge / Bridge-vs-HF logit drift