Protocols

Generative backend protocol.

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

Bases: Protocol

Minimal generation output consumed by value functions.

property text: str

Return the generated text payload.

class nlp_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, max_new_tokens: int, temperature: float, top_k: int) → GenerationResult

Generate model output for the given snapshot.

Estimator strategy protocol.

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

Bases: Protocol

Sample coalitions and drive coalition evaluation for an explain run.

property name: str

Return the registered estimator identifier.

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.

bind_snapshot(snapshot: ConversationSnapshot) → None

Attach the conversation snapshot under explanation.

Estimand aggregation protocol.

class nlp_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.

class nlp_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.

Player partition protocol.

class nlp_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 from the snapshot.

Masking and absence policy protocols.

class nlp_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.

class nlp_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.