interpretune.protocol

Functions

gen_protocol_variants(...)

Classes

ActivationCacheProtocol(*args, **kwargs)	Core activation cache protocol.
Adapter(*values)
AllPhases(*values)
AllSteps(*values)
AnalysisCfgProtocol(*args, **kwargs)	Protocol verifying core analysis configuration functionality.
AnalysisOpProtocol(*args, **kwargs)	Protocol defining required interface for analysis operations.
AnalysisRunnerCfgProtocol(*args, **kwargs)	Protocol representing the analysis runner configuration used by adapters.
AnalysisRunnerProtocol(*args, **kwargs)	Protocol verifying presence of analysis_run_cfg attribute.
AnalysisStoreProtocol(*args, **kwargs)	Protocol verifying core analysis store functionality.
AutoStrEnum(new_class_name, /, names, *[, ...])
BaseAnalysisBatchProtocol(*args, **kwargs)	Base protocol defining methods all analysis batches should implement.
CircuitAnalysisBatchProtocol(*args, **kwargs)	Circuit analysis batch protocol defining additional attributes for circuit tracer operations.
CorePhases(*values)
CoreSteps(*values)
DataModuleInvariants(*args, **kwargs)
DataPrepable(*args, **kwargs)	Minimum requirement for an Interpretunable DataModule is to have a prepare_data method and a valid datamodule config.
DefaultAnalysisBatchProtocol(*args, **kwargs)	Default analysis batch protocol defining which dataset columns should have attribute-based access enabled for AnalysisStore objects.
DerivedEnumMeta(clsname, bases, classdict)
GenerativeStepProtocol(*args, **kwargs)	Protocol describing the surface provided by GenerativeStepMixin used by debug utilities.
GraphComponentFactoryProtocol(*args, **kwargs)	Protocol for graph-like objects that can be hydrated from primitive components.
GraphComponentPayload	Primitive graph payload used for Arrow-native graph serialization.
ITModuleBase(*args, **kwargs)	Concrete Protocol combining the two core module protocols.
ITModuleGenDebuggable(*args, **kwargs)	Composite protocol for ITModuleGenDebuggable objects.
InterpretunableTuple(datamodule, module)	Create new instance of InterpretunableTuple(datamodule, module)
LRScheduler(optimizer, *args, **kwargs)
LRSchedulerConfig(scheduler[, name, ...])
LRSchedulerConfigType
LatentAnalysisModuleProtocol(*args, **kwargs)	Protocol requiring both the ITModuleProtocol surface and LatentAnalysisProtocol methods.
LatentAnalysisProtocol(*args, **kwargs)	Protocol for latent analysis components requiring a subset of SAELensAnalysisMixin methods.
LatentDictProtocol(*args, **kwargs)	Protocol for latent model analysis dictionary operations.
LatentModelFqn(release, sae_id)	Create new instance of LatentModelFqn(release, sae_id)
ModuleInvariants(*args, **kwargs)
Optimizable(*args, **kwargs)	To structurally type optimizer
OptimizerLRSchedulerConfig
PredictLoadable(*args, **kwargs)
PredictSteppable(*args, **kwargs)
ReduceLROnPlateau(optimizer[, mode, factor, ...])
RunnerCfgProtocol(*args, **kwargs)	Protocol representing the base Session/Runner configuration object.
SaveHyperparametersProtocol(*args, **kwargs)	Simple protocol indicating an object exposes a save_hyperparameters method.
SetDerivedEnum(new_class_name, /, names, *)
Steppable(*args, **kwargs)	To structurally type optimizer.step()
TestLoadable(*args, **kwargs)
TestSteppable(*args, **kwargs)
TrainLoadable(*args, **kwargs)
TrainSteppable(*args, **kwargs)
ValLoadable(*args, **kwargs)
ValidationSteppable(*args, **kwargs)

class interpretune.protocol.ActivationCacheProtocol(*args, **kwargs)

Core activation cache protocol.

class interpretune.protocol.Adapter(*values)

class interpretune.protocol.AllPhases(*values)

class interpretune.protocol.AllSteps(*values)

class interpretune.protocol.AnalysisCfgProtocol(*args, **kwargs)

Protocol verifying core analysis configuration functionality.

class interpretune.protocol.AnalysisOpProtocol(*args, **kwargs)

Protocol defining required interface for analysis operations.

class interpretune.protocol.AnalysisRunnerCfgProtocol(*args, **kwargs)

Protocol representing the analysis runner configuration used by adapters.

Matches the public surface of AnalysisRunnerCfg (see config/runner.py).

class interpretune.protocol.AnalysisRunnerProtocol(*args, **kwargs)

Protocol verifying presence of analysis_run_cfg attribute.

This minimal structural protocol is used by adapters to access runner-provided analysis configuration without importing the runner implementation.

class interpretune.protocol.AnalysisStoreProtocol(*args, **kwargs)

Protocol verifying core analysis store functionality.

class interpretune.protocol.AutoStrEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

class interpretune.protocol.BaseAnalysisBatchProtocol(*args, **kwargs)

Base protocol defining methods all analysis batches should implement.

Subclasses should define which dataset columns will have attribute-based access enabled for associated AnalysisStore objects.

class interpretune.protocol.CircuitAnalysisBatchProtocol(*args, **kwargs)

Circuit analysis batch protocol defining additional attributes for circuit tracer operations.

Extends the default protocol with circuit tracing specific attributes.

attribution_graphs

Generated attribution graphs for each prompt in the batch

Type:

list | None

graph_metadata

Metadata for each generated graph including parameters used

Type:

list[dict] | None

graph_paths

File paths where graphs are saved (if saved)

Type:

list[str] | None

circuit_prompts

Prompts used for circuit attribution (may differ from input prompts)

Type:

list[str] | None

class interpretune.protocol.CorePhases(*values)

class interpretune.protocol.CoreSteps(*values)

class interpretune.protocol.DataModuleInvariants(*args, **kwargs)

class interpretune.protocol.DataPrepable(*args, **kwargs)

Minimum requirement for an Interpretunable DataModule is to have a prepare_data method and a valid datamodule config.

class interpretune.protocol.DefaultAnalysisBatchProtocol(*args, **kwargs)

Default analysis batch protocol defining which dataset columns should have attribute-based access enabled for AnalysisStore objects. Subclasses can extend this protocol (or the base one) to add additional attributes or change existing attributes as needed.

logit_diffs

Per batch logit differences with shape [batch_size]

Type:

torch.Tensor | dict[str, dict[int, torch.Tensor]] | None

answer_logits

Model output logits with shape [batch_size, 1, num_classes]

Type:

torch.Tensor | dict[str, dict[int, torch.Tensor]] | None

loss

Loss values with shape [batch_size]

Type:

torch.Tensor | dict[str, dict[int, torch.Tensor]] | None

label_ids

Input labels translated to token ids with shape [batch_size] (if labels provided & translation is needed)

Type:

torch.Tensor | None

orig_labels

Ground truth unmodified labels with shape [batch_size]

Type:

torch.Tensor | None

preds

Model predictions with shape [batch_size]

Type:

torch.Tensor | dict[str, dict[int, torch.Tensor]] | None

cache

Forward pass activation cache

Type:

ActivationCacheProtocol | None

grad_cache

Backward pass gradient cache

Type:

ActivationCacheProtocol | None

answer_indices

Indices of answers with shape [batch_size]

Type:

torch.Tensor | None

alive_latents

Active latent indices per latent model hook

Type:

dict[str, list[int]] | None

correct_activations

Latent model activations after corrections with shape [batch_size, d_sae] for each latent model

Type:

dict[str, torch.Tensor] | None

attribution_values

Attribution values per latent model hook

Type:

dict[str, torch.Tensor] | None

tokens

Input token IDs

Type:

torch.Tensor | None

prompts

Text prompts

Type:

list[str] | None

class interpretune.protocol.DerivedEnumMeta(clsname, bases, classdict)

class interpretune.protocol.GenerativeStepProtocol(*args, **kwargs)

Protocol describing the surface provided by GenerativeStepMixin used by debug utilities.

This is intentionally small: it only includes the methods/properties the debug generation code relies on.

class interpretune.protocol.GraphComponentFactoryProtocol(*args, **kwargs)

Protocol for graph-like objects that can be hydrated from primitive components.

class interpretune.protocol.GraphComponentPayload

Primitive graph payload used for Arrow-native graph serialization.

class interpretune.protocol.ITModuleBase(*args, **kwargs)

Concrete Protocol combining the two core module protocols.

NOTE: As ITModuleProtocol is a union of dynamically created Protocol variants it can’t be used as a direct base class in a class statement without metaclass conflict (it’s a typealias of a union so it has a metaclass of types.UnionType and our derived class’s metaclass (_ProtocolMeta) isn’t a subclass of types.UnionType). ITModuleBase provides a stable Protocol class that composes the structural requirements of our module and can be used safely as a base for further composite Protocols.

class interpretune.protocol.ITModuleGenDebuggable(*args, **kwargs)

Composite protocol for ITModuleGenDebuggable objects.

Requires both module-like surface and generative-step helpers.

Use this as an annotation for attributes that must behave like a given module composition that also supports generation helper methods (e.g., it_generate).

class interpretune.protocol.InterpretunableTuple(datamodule, module)

Create new instance of InterpretunableTuple(datamodule, module)

Parameters:

• datamodule (BuiltTrainLoadable | BuiltValLoadable | BuiltTestLoadable | BuiltPredictLoadable | None)

• module (BuiltTrainSteppable | BuiltValidationSteppable | BuiltTestSteppable | BuiltPredictSteppable | None)

datamodule: BuiltTrainLoadable | BuiltValLoadable | BuiltTestLoadable | BuiltPredictLoadable | None

Alias for field number 0

module: BuiltTrainSteppable | BuiltValidationSteppable | BuiltTestSteppable | BuiltPredictSteppable | None

Alias for field number 1

class interpretune.protocol.LRScheduler(optimizer, *args, **kwargs)

Parameters:

• optimizer (Optimizer)

• args (Any)

• kwargs (Any)

class interpretune.protocol.LRSchedulerConfig(scheduler, name=None, interval='epoch', frequency=1, reduce_on_plateau=False, monitor=None, strict=True)

Parameters:

• scheduler (LRScheduler | ReduceLROnPlateau)

• name (str | None)

• interval (str)

• frequency (int)

• reduce_on_plateau (bool)

• monitor (str | None)

• strict (bool)

class interpretune.protocol.LRSchedulerConfigType

class interpretune.protocol.LatentAnalysisModuleProtocol(*args, **kwargs)

Protocol requiring both the ITModuleProtocol surface and LatentAnalysisProtocol methods.

Inheriting both interfaces expresses the intersection of the two required structural surfaces so static checkers (like pyright) will require both sets of attributes/methods.

class interpretune.protocol.LatentAnalysisProtocol(*args, **kwargs)

Protocol for latent analysis components requiring a subset of SAELensAnalysisMixin methods.

class interpretune.protocol.LatentDictProtocol(*args, **kwargs)

Protocol for latent model analysis dictionary operations.

class interpretune.protocol.LatentModelFqn(release, sae_id)

Create new instance of LatentModelFqn(release, sae_id)

Parameters:

• release (str)

• sae_id (str)

release: str

Alias for field number 0

sae_id: str

Alias for field number 1

class interpretune.protocol.ModuleInvariants(*args, **kwargs)

class interpretune.protocol.Optimizable(*args, **kwargs)

To structurally type optimizer

class interpretune.protocol.OptimizerLRSchedulerConfig

class interpretune.protocol.PredictLoadable(*args, **kwargs)

class interpretune.protocol.PredictSteppable(*args, **kwargs)

class interpretune.protocol.ReduceLROnPlateau(optimizer, mode=Ellipsis, factor=Ellipsis, patience=Ellipsis, verbose=Ellipsis, threshold=Ellipsis, threshold_mode=Ellipsis, cooldown=Ellipsis, min_lr=Ellipsis, eps=Ellipsis)

Parameters:

• optimizer (Optimizer)

• mode (str)

• factor (float)

• patience (int)

• verbose (bool)

• threshold (float)

• threshold_mode (str)

• cooldown (int)

• min_lr (float)

• eps (float)

class interpretune.protocol.RunnerCfgProtocol(*args, **kwargs)

Protocol representing the base Session/Runner configuration object.

class interpretune.protocol.SaveHyperparametersProtocol(*args, **kwargs)

Simple protocol indicating an object exposes a save_hyperparameters method.

Intentionally framework-agnostic, but see Lightning HyperparametersMixin.save_hyperparameters for an example implementation. The method is expected to return None.

class interpretune.protocol.SetDerivedEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

class interpretune.protocol.Steppable(*args, **kwargs)

To structurally type optimizer.step()

class interpretune.protocol.TestLoadable(*args, **kwargs)

class interpretune.protocol.TestSteppable(*args, **kwargs)

class interpretune.protocol.TrainLoadable(*args, **kwargs)

class interpretune.protocol.TrainSteppable(*args, **kwargs)

class interpretune.protocol.ValLoadable(*args, **kwargs)

class interpretune.protocol.ValidationSteppable(*args, **kwargs)