Main Functions

The functions described in this section can be called from the top level of the inseq library and implement the base functionalities required for its usage.

inseq.get_version() → str[source]: Returns the current version of the Inseq library.

inseq.explain(id: str) → None[source]

Given an identifier, prints a short explanation of what it represents in the Inseq library. Identifiers are used for attribution methods, aggregators, aggregation functions, and step functions.

Example: explain(“attention”) prints the documentation for the attention attribution method.

inseq.load_model(model: str | PreTrainedModel, attribution_method: str | None = None, framework: str = 'hf_transformers', **kwargs) → AttributionModel[source]

Factory function to load a model with or without attribution methods.

Parameters:

model (Union[ModelIdentifier, ModelClass]) – Either a model identifier (e.g. gpt2 in HF transformers) or an instance of a model class supported by the selected modeling framework.
attribution_method (Optional[str], optional, defaults to None) – Identifier for the attribution method to use. If None, the model will be loaded without any attribution methods, which can be added during attribution.
framework (str, optional, defaults to “hf_transformers”) – The framework to use for loading the model. Currently, only HF transformers is supported.

Returns:

An instance of one of AttributionModel children classes matching the selected framework and model architecture.

Return type:

AttributionModel

inseq.register_step_function(fn: StepFunction, identifier: str, aggregate_map: dict[str, str] | None = None, overwrite: bool = False) → None[source]

Registers a function to be used to compute step scores and store them in the FeatureAttributionOutput object. Registered step functions can also be used as attribution targets by gradient-based feature attribution methods.

Parameters:

fn (callable) –
The function to be used to compute step scores. Default parameters (use kwargs to capture unused ones when defining your function):
- attribution_model: an AttributionModel instance, corresponding to the model
  used for computing the score.
- forward_output: the output of the forward pass from the attribution model.
- encoder_input_ids, decoder_input_ids, encoder_input_embeds,
  decoder_input_embeds, encoder_attention_mask, decoder_attention_mask: all the elements composing the Batch used as context of the model.
- target_ids: torch.Tensor of target token ids of size (batch_size,) and type long,
  corresponding to the target predicted tokens for the next generation step.
The function can also define an arbitrary number of custom parameters that can later be provided directly to the model.attribute function call, and it must return a torch.Tensor of size (batch_size,) of float or long. If parameter names conflict with model.attribute ones, pass them as key-value pairs in the step_scores_args dict parameter.
identifier (str) – The identifier that will be used for the registered step score.
aggregate_map (dict, optional) – An optional dictionary mapping from Aggregator name identifiers to aggregation function identifiers. A list of available aggregation functions is available using list_aggregation_functions().
overwrite (bool, optional, defaults to False) – Whether to overwrite an existing function registered with the same identifier.

inseq.register_model_config(model_type: str, config: dict, overwrite: bool = False, allow_partial: bool = False) → None[source]

Allows to register a model configuration for a given model type. The configuration is a dictionary containing information required the methods for which the attribute use_model_config=True.

Parameters:

model_type (str) – The class of the model for which the configuration is registered, used as key in the stored configuration. E.g. GPT2LMHeadModel for the GPT-2 model in HuggingFace Transformers.
config (dict) – A dictionary containing the configuration for the model. The fields should match those of the ModelConfig class.
overwrite (bool, optional, defaults to False) – If True, the configuration will be overwritten if it already exists.
allow_partial (bool, optional, defaults to False) – If True, the configuration can be partial, i.e. it can contain only a subset of the fields of the ModelConfig class. The missing fields will be set to None.

Raises:

ValueError – If the model type is already registered and overwrite=False, or if the configuration is partial and allow_partial=False.

inseq.list_feature_attribution_methods()[source]: Lists identifiers for all available feature attribution methods. A feature attribution method identifier (e.g. integrated_gradients) can be passed to AttributionModel or load_model() to define a model for attribution.

inseq.list_aggregators() → list[str][source]: Lists identifiers for all available aggregators.

inseq.list_step_functions() → list[str][source]: Lists identifiers for all available step scores. One or more step scores identifiers can be passed to the attribute() method either to compute scores while attributing (step_scores parameter), or as target function for the attribution, if supported by the attribution method (attributed_fn parameter).

inseq.list_aggregation_functions() → list[str][source]: Lists identifiers for all available aggregation functions.

inseq.show_attributions(attributions: FeatureAttributionSequenceOutput, min_val: int | None = None, max_val: int | None = None, display: bool = True, return_html: bool | None = False) → str | None[source]

Core function allowing for visualization of feature attribution maps in console/HTML format.

Parameters:

attributions (FeatureAttributionSequenceOutput) – Sequence attributions to be visualized.
min_val (Optional[int], optional, defaults to None) – Lower attribution score threshold for color map.
max_val (Optional[int], optional, defaults to None) – Upper attribution score threshold for color map.
display (bool, optional, defaults to True) – Whether to show the output of the visualization function.
return_html (Optional[bool], optional, defaults to False) – If true, returns the HTML corresponding to the notebook visualization of the attributions in string format, for saving purposes.

Returns:

Returns the HTML output if return_html=True

Return type:

Optional[str]

Visualizes granular attribution heatmaps in HTML format.

Parameters:

attributions (FeatureAttributionSequenceOutput) – Sequence attributions to be visualized. Does not require pre-aggregation.
min_val (int, optional, defaults to None) – Lower attribution score threshold for color map.
max_val (int, optional, defaults to None) – Upper attribution score threshold for color map.
max_show_size (int, optional, defaults to None) – Maximum dimension size for additional dimensions to be visualized. Default: 20.
show_dim (int or str, optional, defaults to None) – Dimension to be visualized along with the source and target tokens. Can be either the dimension index or the dimension name. Works only if the dimension size is less than or equal to max_show_size.
slice_dims (dict[int or str, tuple[int, int]], optional, defaults to None) – Dimensions to be sliced and visualized along with the source and target tokens. The dictionary should contain the dimension index or name as the key and the slice range as the value.
display (bool, optional, defaults to True) – Whether to show the output of the visualization function.
return_html (bool, optional, defaults to False) – If true, returns the HTML corresponding to the notebook visualization of the attributions in string format, for saving purposes.
return_figure (bool, optional, defaults to False) – If true, returns the Treescope figure object for further manipulation.

Returns:

Returns the HTML output if return_html=True

Return type:

str

Visualizes token-level attributions in HTML format.

Parameters:

attributions (FeatureAttributionSequenceOutput) – Sequence attributions to be visualized.
min_val (Optional[int], optional, defaults to None) – Lower attribution score threshold for color map.
max_val (Optional[int], optional, defaults to None) – Upper attribution score threshold for color map.
display (bool, optional, defaults to True) – Whether to show the output of the visualization function.
return_html (Optional[bool], optional, defaults to False) – If true, returns the HTML corresponding to the notebook visualization of the attributions in string format, for saving purposes.
return_figure (Optional[bool], optional, defaults to False) – If true, returns the Treescope figure object for further manipulation.
replace_char (Optional[dict[str, str]], optional, defaults to None) – Dictionary mapping strings to be replaced to replacement options, used for cleaning special characters. Default: {}.
wrap_after (Optional[int | str | list[str] | tuple[str]], optional, defaults to None) – Token indices or tokens after which to wrap lines. E.g. 10 = wrap after every 10 tokens, “hi” = wrap after word hi occurs, [“.” “!”, “?”] or “.!?” = wrap after every sentence-ending punctuation.
step_score_highlight (Optional[str], optional, defaults to None) – Name of the step score to use to highlight generated tokens in the visualization. If None, no highlights are shown. Default: None.

inseq.merge_attributions(attributions: list[FeatureAttributionOutput]) → FeatureAttributionOutput[source]

Merges multiple FeatureAttributionOutput objects into a single one.

Merging is allowed only if the two outputs match on the fields specified in _merge_match_info_fields.

Parameters:: attributions (list of FeatureAttributionOutput) – The FeatureAttributionOutput objects to be merged.
Returns:: Merged object.
Return type:: FeatureAttributionOutput