Protocols

Protocol contracts for pipeline plugins.

@domain protocols @see [[knowledge/architecture/protocols]]

Generative backend protocol.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.backend.GenerationResult(*args, **kwargs)

Bases: Protocol

Minimal generation output consumed by value functions.

property text: str

Return the generated text payload.

class mllm_shap.protocols.backend.GenerativeBackend(*args, **kwargs)

Bases: Protocol

Execute model generation for a masked conversation snapshot.

property model_id: str

Return the backend model identifier.

async generate(snapshot: ConversationSnapshot, generation: GenerationConfig) → GenerationResult

Generate model output for the given snapshot.

class mllm_shap.protocols.backend.SupportsKvCache(*args, **kwargs)

Bases: Protocol

Backend that can reuse prompt-prefix KV state across coalitions.

property kv_cache_hits: int

Return the cumulative number of prefix-cache hits.

property kv_cache_reused_tokens: int

Return the cumulative number of prompt tokens served from the cache.

set_kv_cache_enabled(enabled: bool, max_entries: int) → None

Turn prefix-cache reuse on or off and cap the number of cached prefixes.

class mllm_shap.protocols.backend.SupportsLogprobs(*args, **kwargs)

Bases: Protocol

Backend whose records carry GenerationRecord.logprobs.

The logprob value function requires it; a record that still arrives without logprobs (a server that omits them) raises LogprobsUnavailableError when scored.

property returns_logprobs: bool

Return whether generated records include token logprobs.

class mllm_shap.protocols.backend.SupportsAclose(*args, **kwargs)

Bases: Protocol

Backend holding resources (clients, models) released by aclose.

async aclose() → None

Release backend resources.

Estimator strategy protocols.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.estimator.EstimatorStrategy(*args, **kwargs)

Bases: Protocol

Sample coalitions and turn their payoffs into attributions.

property name: str

Return the registered estimator identifier.

bind_snapshot(snapshot: ConversationSnapshot) → None

Attach the conversation snapshot under explanation.

sample_masks(player_set: PlayerSet, budget_fraction: float, include_minimal_masks: bool, seed: int) → Iterator[CoalitionMask]

Yield coalition masks to evaluate for the player set.

estimate_attributions(masks: Sequence[CoalitionMask], payoffs: Sequence[float], aggregator: EstimandAggregator) → list[float]

Aggregate evaluated coalitions into per-player attributions.

class mllm_shap.protocols.estimator.TwoPhaseEstimator(*args, **kwargs)

Bases: Protocol

Estimator that allocates a second sampling phase from first-phase payoffs.

begin_allocation(masks: Sequence[CoalitionMask], payoffs: Sequence[float]) → None

Consume phase-one payoffs and plan phase two.

sample_allocation_masks() → Iterator[CoalitionMask]

Yield phase-two coalition masks.

Estimand aggregation protocol.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.estimand.EstimandAggregator(*args, **kwargs)

Bases: Protocol

Aggregate coalition payoffs into per-player attributions.

property estimand: Estimand

Return the estimand label produced by this aggregator.

coalition_weight(coalition_size: int, num_players: int) → float

Return coalition weight for the given size excluding the focal player.

aggregate(masks: Sequence[Sequence[bool]], payoffs: Sequence[float]) → list[float]

Aggregate coalition samples into per-player attribution values.

Value function protocol.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.value.ValueFunction(*args, **kwargs)

Bases: Protocol

Score coalition utility relative to a base generation.

property name: str

Return the registered value-function identifier.

score(base: GenerationResult, candidate: GenerationResult) → float

Return utility for candidate relative to base.

class mllm_shap.protocols.value.FittableValueFunction(*args, **kwargs)

Bases: ValueFunction, Protocol

Value function that must see the run’s corpus before it scores.

The pipeline calls fit() with the base generation and every coalition generation before any score() call, in explain and reanalyze.

fit(corpus: Sequence[GenerationRecord]) → None

Freeze corpus statistics used by score().

class mllm_shap.protocols.value.RequiresLogprobs(*args, **kwargs)

Bases: Protocol

Value function that scores GenerationRecord.logprobs.

When needs_logprobs is true the pipeline refuses backends that are not SupportsLogprobs and reanalyze refuses archives whose rows have no logprobs.

property needs_logprobs: bool

Return whether scoring reads logprobs.

class mllm_shap.protocols.value.RequiresEmbeddings(*args, **kwargs)

Bases: Protocol

Value function that scores model embeddings rather than text.

When needs_embeddings is true the pipeline sets GenerationConfig.compute_embeddings for its backend calls, so backends that can (transformers) attach static and contextual embeddings to their records, and scores those records.

property needs_embeddings: bool

Return whether scoring reads embedding or contextual_embedding.

Attribution normalizer protocol.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.normalizer.Normalizer(*args, **kwargs)

Bases: Protocol

Scale aggregated attributions for presentation without mutating archives.

property name: str

Return the registered normalizer identifier.

normalize(values: Sequence[float]) → list[float]

Return presentation-scaled copies of values.

Player partition protocol.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.partition.PlayerPartitioner(*args, **kwargs)

Bases: Protocol

Partition a conversation snapshot into explainability players.

property name: str

Return the registered partition identifier.

partition(snapshot: ConversationSnapshot) → PlayerSet

Derive ordered players and their spans from the snapshot.

The returned PlayerSet must carry one PlayerSpan per player; absence policies and labels read the spans instead of re-tokenising.

Masking and absence policy protocols.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.masking.AbsencePolicy(*args, **kwargs)

Bases: Protocol

Render absent players when building a masked snapshot view.

property name: str

Return the registered absence-policy identifier.

apply(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → ConversationSnapshot

Return a masked snapshot view for coalition evaluation.

Embedding provider protocol.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.embedding.EmbeddingProvider(*args, **kwargs)

Bases: Protocol

Expose embeddings for value functions that operate in embedding space.

property name: str

Return the registered embedding provider identifier.

embed(generation: GenerationResult) → tuple[float, ...]

Return an embedding vector for the generation.

Attribution renderer protocol.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.renderer.AttributionRenderer(*args, **kwargs)

Bases: Protocol

Render per-player attribution values for human review.

property name: str

Return the registered renderer identifier.

render(labels: Sequence[str], values: Sequence[float], *, estimand: Estimand, title: str | None = None) → Any

Return a visualization artifact for the given labels and values.

Options contract for plugins configured through explanation.plugin_options.

@domain protocols @see [[knowledge/architecture/protocols]]

class mllm_shap.protocols.plugin.PluginOptions

Bases: BaseModel

Options a plugin accepts; the base class accepts none.

Subclasses declare one field per option. Unknown keys and values of the wrong type are rejected (extra="forbid", strict types; integers are accepted for float fields).

model_config = {'extra': 'forbid', 'frozen': True, 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mllm_shap.protocols.plugin.DeclaresPluginOptions(*args, **kwargs)

Bases: Protocol

Plugin class that declares the options it accepts.

The registry validates explanation.plugin_options for the plugin against options_model before building it. Plugins without the attribute get their options unchecked.

options_model: ClassVar[type[PluginOptions]]

Pydantic model listing the accepted options.