Analysis Tools Review & Re-contextualization

[jlarson4]

Description

After a thorough review of all the Analysis Tools that have been built over the last several months, it was determined that we need to refocus some of these efforts. We are building tools with too narrow a scope, or tools that can be recreated using base-bridge functionalities.

This is the resulting size-reduction pass over transformer_lens.tools.analysis: two tools are removed or redesigned to better fit the library, two other tools are demoted to demos, one tool is rebuilt as part of the existing patching library, shared helpers are consolidated, and the public surface shrinks substantially. All changes tested bit-indentical on real models.

• Relevance lens removed – RelevanceLens, _relevance_rules and the rule hooks in NormalizationBridge, GatedMLPBridge and JointGateUpMLPBridge have been removed, due to forward costs.
• Backward Lens and SVD circuits become demos – Backward_Lens_Demo.ipynb and SVD_Circuits_Demo.ipynb are rewritten to use self-contained on bridge hooks, FactoredMatrix.svd and logit_readout. They successfully reproduce the previous outputs without the need for an expansive analysis tool
• Causal-swap benchmark moves to scripts/ – benchmark and CLI are one script with unchanged logic; it regenerates the frozen demo artifact byte for byte. success_rate_ci now lives in transformer_lens.utilities and the old package path forwards with a DeprecationWarning.
• Direct-path patching is exact and lives in transformer_lens.patching – the clean-minus-corrupted source-head write is added to the destination head's pre-norm fork input (split-QKV enabled for the sweep and restored), so LayerNorm recomputes. It matches the attribution module's edge ablation to fp64 precision; the frozen-scale approximation and its unfolded-LN warning are gone, so numbers change. Sources without a fork (boot_native, GPT-J, GPT-Neo, OPT, BERT) and post-norm, scaled-residual or parallel-mixer source blocks are refused before any forward; K/V on grouped-query attention stays refused. The old module path forwards with a FutureWarning.
• Shared helpers consolidated – hybrid_block_types, compute_dtype, require_int and to_token_ids in _model_state.py replace inlined copies across the logit lens, DLA, projection kernel, sparse probing and the Jacobian lens; attribution patching shares one clean/corrupt pair check.
• Jacobian lens tightened – readout goes through logit_readout (bit-identical, now subject to its guards), swap_clamp_hooks folds into swap_hooks(clamp_to=) with a deprecated forward, coordinate_patch_hooks uses the shared intervention hook, occupancy controls are drawn on the CPU so every device agrees (slower on accelerators; documented), and registry lenses load at the registry's pinned revision.
• Public surface trimmed – tools.analysis.__all__ now only exports 35 items; result dataclasses stay importable from their modules.
• Smaller behaviour changes – token ids follow one contract in both lenses (numpy and 0-d tensor ids accepted, bools and floats refused); alpha in swap_hooks(clamp_to=) is the fraction of the way to the clamped coordinates; a few validation messages are reworded.

Verified with the unit, docstring, acceptance and integration tiers, mypy ., formatting, nbval on the four touched notebooks and the docs build; per-test regression checked against the base run.

Fixes #1832 (Backward Lens leaves the package, so #1833 will not be merged).

Type of change

• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist:

• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes