Coverage for transformer_lens/tools/analysis/__init__.py: 100%

1"""Analysis tools for TransformerLens. 

2 

3This subpackage collects high-level, single-call interpretability analyses that 

4sit on top of the hook/cache system. Model support is documented per tool; 

5new analyses may target the ``TransformerBridge`` API exclusively. 

6 

7Tools: 

8 - attribution_patching: Attribution patching (gradient-linearized activation 

9 patching) over residual-stream nodes and edges: typed computational graph, 

10 a names-filtered manual-backward gradient cache, and signed node and edge 

11 scores (EAP). Integrated gradients (EAP-IG) and ablate-outside faithfulness 

12 are not implemented yet. 

13 - backward_lens: GPT-2 MLP weight-gradient factors projected into vocabulary 

14 space with explicit raw-gradient sign semantics. 

15 - direct_logit_attribution: Direct Logit Attribution (DLA) over components, 

16 layers, or attention heads. 

17 - direct_path_patching: Direct path patching for head-to-head circuit 

18 analysis. 

19 - jacobian_lens: The Jacobian lens (J-lens) — per-layer causal transport to 

20 the output vocabulary basis, with loading of published lens artifacts, 

21 native fitting, readouts, interventions, J-space sparse decomposition, and 

22 anchored coordinate patching (offline and dynamic/hooked). 

23 - jacobian_lens_causal_swap_benchmark: A causal coordinate-swap benchmark for 

24 ``coordinate_patch_hooks``, with baseline-capability filtering, 

25 displacement-matched random-atom controls, exact Clopper-Pearson confidence 

26 intervals, and a versioned, fingerprinted JSON artifact schema. Its 

27 ``_cli`` sibling is the artifact-generation entry point and is deliberately 

28 not imported here, so ``python -m`` runs it once. 

29 - logit_lens: One-call logit lens over the accumulated residual stream and 

30 the ``logit_readout`` kernel that reads any ``d_model`` vector through the 

31 real final norm, unembedding and adapter output transform, chunked over 

32 the vocabulary with target ranks, top-k and vocabulary subsets. 

33 - projection_kernel: Basis-invariant subspace overlap and TransformerBridge 

34 attention-head OQ/OK/OV affinity. 

35 - sparse_probing: Leakage-safe k-sparse binary probes over supplied 

36 activation tensors, with train-only selection and raw null controls. 

37 - svd_circuits: Per-head QK/OV singular-vector decomposition with a 

38 degeneracy guard, OV vocab and logit readout, per-position activation 

39 projection onto singular directions, and a mandatory causal patch gate 

40 that reconstructs a head's output onto a chosen singular subspace. 

41""" 

42 

43from transformer_lens.tools.analysis.attribution_patching import ( 

44 AttributionResult, 

45 EdgeAttributionConfig, 

46 Node, 

47 attribution_patch, 

48) 

49from transformer_lens.tools.analysis.backward_lens import ( 

50 BackwardLens, 

51 BackwardLensLayerResult, 

52 BackwardLensMatrixResult, 

53 BackwardLensResult, 

54 LinearGradientFactors, 

55 ProjectedFactor, 

56 VocabularyRanking, 

57 WeightLayout, 

58) 

59from transformer_lens.tools.analysis.direct_logit_attribution import ( 

60 DirectLogitAttribution, 

61 direct_logit_attribution, 

62) 

63from transformer_lens.tools.analysis.direct_path_patching import ( 

64 get_act_patch_direct_path, 

65 get_act_patch_direct_path_all_sources, 

66) 

67from transformer_lens.tools.analysis.jacobian_lens import ( 

68 JacobianLens, 

69 JacobianLensReadout, 

70) 

71from transformer_lens.tools.analysis.jacobian_lens_causal_swap_benchmark import ( 

72 BenchmarkCorpus, 

73 FunctionSpec, 

74 corpus_definition, 

75 load_artifact, 

76 run_causal_swap_benchmark, 

77 select_displacement_matched_control_token, 

78 success_rate_ci, 

79) 

80from transformer_lens.tools.analysis.jacobian_lens_coordinate_patch import ( 

81 CoordinatePatch, 

82 solve_coordinate_patch, 

83 solve_coordinate_patch_positions, 

84) 

85from transformer_lens.tools.analysis.jacobian_lens_decomposition import ( 

86 JSpaceDecomposition, 

87 JSpaceOccupancy, 

88 JSpaceVarianceProfile, 

89 estimate_occupancy, 

90 get_sparse_decomposition, 

91) 

92from transformer_lens.tools.analysis.logit_lens import ( 

93 LogitLensResult, 

94 LogitReadout, 

95 logit_lens, 

96 logit_readout, 

97) 

98from transformer_lens.tools.analysis.projection_kernel import ( 

99 AttentionHeadRef, 

100 HeadAffinityPair, 

101 HeadAffinityResult, 

102 ProjectionKernelResult, 

103 RandomSubspaceReference, 

104 SubspaceBasis, 

105 attention_head_subspace_affinity, 

106 orthonormal_subspace, 

107 projection_kernel, 

108 random_projection_kernel_moments, 

109) 

110from transformer_lens.tools.analysis.sparse_probing import ( 

111 SparseProbeControl, 

112 SparseProbeConvergenceError, 

113 SparseProbeMetrics, 

114 SparseProbeRejection, 

115 SparseProbeResult, 

116 SparseProbeSweep, 

117 fit_sparse_probe, 

118 sweep_sparse_probe, 

119) 

120from transformer_lens.tools.analysis.svd_circuits import ( 

121 ActivationProjection, 

122 DegenerateDirectionError, 

123 HeadDecomposition, 

124 HeadSVD, 

125 LogitSignature, 

126 PatchResult, 

127 RankReportRow, 

128 decompose_head, 

129 logit_signature, 

130 patch_along_directions, 

131 project_activations, 

132 vocab_readout, 

133) 

134 

135__all__ = [ 

136 "ActivationProjection", 

137 "AttentionHeadRef", 

138 "AttributionResult", 

139 "BackwardLens", 

140 "BackwardLensLayerResult", 

141 "BackwardLensMatrixResult", 

142 "BackwardLensResult", 

143 "BenchmarkCorpus", 

144 "CoordinatePatch", 

145 "DegenerateDirectionError", 

146 "DirectLogitAttribution", 

147 "EdgeAttributionConfig", 

148 "FunctionSpec", 

149 "HeadAffinityPair", 

150 "HeadAffinityResult", 

151 "HeadDecomposition", 

152 "HeadSVD", 

153 "JSpaceDecomposition", 

154 "JSpaceOccupancy", 

155 "JSpaceVarianceProfile", 

156 "JacobianLens", 

157 "JacobianLensReadout", 

158 "LinearGradientFactors", 

159 "LogitLensResult", 

160 "LogitReadout", 

161 "LogitSignature", 

162 "Node", 

163 "PatchResult", 

164 "ProjectedFactor", 

165 "ProjectionKernelResult", 

166 "RandomSubspaceReference", 

167 "RankReportRow", 

168 "SparseProbeControl", 

169 "SparseProbeConvergenceError", 

170 "SparseProbeMetrics", 

171 "SparseProbeRejection", 

172 "SparseProbeResult", 

173 "SparseProbeSweep", 

174 "SubspaceBasis", 

175 "VocabularyRanking", 

176 "WeightLayout", 

177 "attention_head_subspace_affinity", 

178 "attribution_patch", 

179 "decompose_head", 

180 "direct_logit_attribution", 

181 "estimate_occupancy", 

182 "fit_sparse_probe", 

183 "get_act_patch_direct_path", 

184 "get_act_patch_direct_path_all_sources", 

185 "get_sparse_decomposition", 

186 "load_artifact", 

187 "logit_lens", 

188 "logit_readout", 

189 "logit_signature", 

190 "orthonormal_subspace", 

191 "patch_along_directions", 

192 "project_activations", 

193 "projection_kernel", 

194 "random_projection_kernel_moments", 

195 "run_causal_swap_benchmark", 

196 "select_displacement_matched_control_token", 

197 "solve_coordinate_patch", 

198 "solve_coordinate_patch_positions", 

199 "success_rate_ci", 

200 "sweep_sparse_probe", 

201 "vocab_readout", 

202]