typedefs

typedefs

Shared explainability type aliases.

VisionExplainableModule dataclass

VisionExplainableModule(name, module, target, camera_keys, capture_mode)

Camera-addressable visual module exposed to the explainer.

Attributes:

Name	Type	Description
name	str	Stable module path used by runner filters and output metadata.
module	Module	Module that owns target and participates in policy forward passes.
target	VisionExplanationTarget	Target layer metadata used to capture activations and reshape feature maps.
camera_keys	tuple[str, ...]	Observation camera keys that can be attributed through this module.
capture_mode	str	Hook routing mode from VisionCaptureMode. It tells attribution code whether the target layer runs once, once per camera, or once on a stacked camera batch.

CameraExplanationTarget dataclass

CameraExplanationTarget(camera_key, vision_module_name, target, capture_mode, invocation_index=None, stacked_camera_index=None, stacked_camera_count=None)

Concrete visual target for one output camera heatmap.

Attributes:

Name	Type	Description
camera_key	str	Observation camera key whose overlay should be generated.
vision_module_name	str	Name of the module that produced the target activation.
target	VisionExplanationTarget	Target layer metadata used by Grad-CAM and Ablation-CAM.
capture_mode	str	Hook routing mode from VisionCaptureMode.
invocation_index	int | None	Selected forward-hook call for modules invoked once per camera. None means the first captured call is used.
stacked_camera_index	int | None	Camera index inside a stacked camera batch when capture_mode is stacked_camera_batch.
stacked_camera_count	int | None	Number of cameras inside the stacked batch.

ExplanationHeatmapFunction

Bases: Protocol

Callable contract used by the explanation method registry.

__call__

__call__(policy, observation, actions, target_camera, target_vision_module_names, preprocess_observation)

Compute heatmaps for one explanation method.

Parameters:

Name	Type	Description	Default
policy	Policy	Policy whose prediction is being explained.	required
observation	ObservationBatch	Observation tensors keyed by observation-space names.	required
actions	ActionBatch | None	Optional action tensors used by discrete predictors to score teacher-forced action-token likelihoods.	required
target_camera	str | None	Optional camera key selected by runner filtering.	required
target_vision_module_names	list[str] | None	Optional visual module allowlist.	required
preprocess_observation	bool	Whether to run policy preprocessing before attribution.	required

Returns:

Type	Description
dict[str, Tensor]	Heatmaps keyed by camera name.

Source code in src/versatil/explainability/typedefs.py

def __call__(
    self,
    policy: Policy,
    observation: ObservationBatch,
    actions: ActionBatch | None,
    target_camera: str | None,
    target_vision_module_names: list[str] | None,
    preprocess_observation: bool,
) -> dict[str, torch.Tensor]:
    """Compute heatmaps for one explanation method.

    Args:
        policy: Policy whose prediction is being explained.
        observation: Observation tensors keyed by observation-space names.
        actions: Optional action tensors used by discrete predictors to
            score teacher-forced action-token likelihoods.
        target_camera: Optional camera key selected by runner filtering.
        target_vision_module_names: Optional visual module allowlist.
        preprocess_observation: Whether to run policy preprocessing before
            attribution.

    Returns:
        Heatmaps keyed by camera name.
    """