API reference

nlp-shap exposes a small, typed public surface. Import the symbols below from nlp_shap or follow the module pages for implementation detail.

Public exports

Symbol	Description
render_attribution()	Render token attributions with a registered viz plugin. See Visualization.
render_attribution_html()	Return inline HTML for Jupyter token coloring. See Visualization.
ExplainRunner	End-to-end explain pipeline entry point. See Pipeline configuration.
ExplainConfig	Top-level explain pipeline configuration. See Pipeline configuration.
explain_config_from_yaml()	Parse YAML into ExplainConfig.
explain_config_to_yaml()	Serialize ExplainConfig to YAML.
ConversationSnapshot	Frozen conversation input for explainability. See Domain types.
PlayerSet	Ordered explainability players. See Domain types.
CoalitionMask	Boolean coalition presence mask. See Domain types.
CooperativeGame	Cooperative-game player set and references. See Domain types.
PluginRegistry	Plugin discovery and resolution. See Plugins.
TokenPartitioner	Whitespace token partition plugin. See Masking.
MaskBuilder	Shared masked snapshot views. See Masking.
RunArchive	SQLite + blob coalition archive. See Runtime.
InferenceScheduler	Async bounded coalition execution. See Runtime.
Estimand	Estimand label enum (shapley | banzhaf). See Domain types.
ShapleyAggregator	Shapley-weighted coalition aggregation. See Estimand aggregators and estimation.
ExactEstimator	Exact coalition enumeration. See Estimand aggregators and estimation.
BanzhafAggregator	Uniform Banzhaf coalition aggregation. See Estimand aggregators and estimation.
ExplainResult	Labelled explain output. See Pipeline configuration.
RunManifest	Run-archive metadata builder. See Pipeline configuration.
parse_manifest()	Parse manifest payloads at archive boundaries. See Pipeline configuration.

Modules

• Domain types
• Protocols
• Plugins
• Pipeline configuration
• Masking
• Runtime
• Estimand aggregators and estimation
• Value functions
• Backends
• Visualization

Package version

Multimodal explainability tool for NLP based on Shapley value.

class nlp_shap.BanzhafAggregator

Bases: object

Aggregate coalition samples with uniform Banzhaf coalition weights.

property estimand: Estimand

Return the Banzhaf estimand label.

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

Return uniform Banzhaf coalition weight 1/2^(n-1).

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

Aggregate coalition samples into Banzhaf indices.

class nlp_shap.CoalitionMask(present: tuple[bool, ...])

Bases: object

Boolean presence mask aligned with a player set.

present: tuple[bool, ...]

Presence flags aligned with PlayerSet order.

classmethod from_sequence(present: Sequence[bool]) → Self

Build a mask from any boolean sequence.

coalition_size() → int

Return the number of present players.

validate_against(player_set: PlayerSet) → None

Ensure the mask length matches the player set.

class nlp_shap.ComplementaryEstimator

Bases: object

Sample complementary coalition pairs and aggregate CC attributions.

property name: str

Return the registered estimator identifier.

property m_counts: ndarray | None

Return the latest complementary M-matrix counts from sampling.

bind_snapshot(snapshot: ConversationSnapshot) → None

Attach the conversation snapshot under explanation.

reset_sampling_state(num_players: int) → None

Reset complementary M-matrix counts before a new sampling run.

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

Yield complementary coalition pairs up to the configured budget.

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

Aggregate complementary pair payoffs into CC Shapley attributions.

class nlp_shap.ConversationSnapshot(turns: tuple[Turn, ...], snapshot_id: str)

Bases: object

Frozen conversation state used as the explainability input.

turns: tuple[Turn, ...]

Ordered turns that define the conversation under study.

snapshot_id: str

Stable identifier used for deduplication and run archives.

classmethod from_turns(turns: tuple[Turn, ...]) → Self

Build a snapshot with a stable content-derived identifier.

class nlp_shap.CooperativeGame(player_set: PlayerSet, empty_value: float = 0.0)

Bases: object

Player set and reference values for a characteristic function.

player_set: PlayerSet

Ordered explainability players that define the game.

empty_value: float

Reference payoff \(v(\emptyset)\) for the characteristic function.

class nlp_shap.CosineEmbeddingValue(embedding_mode: EmbeddingMode = EmbeddingMode.STATIC, provider: EmbeddingProvider | None = None)

Bases: object

Cosine similarity between static or contextual embeddings (U1/U2).

property name: str

Return the registered value-function identifier.

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

Return cosine similarity between embedding vectors.

class nlp_shap.Estimand(*values)

Bases: StrEnum

Supported cooperative-game value formulations.

SHAPLEY = 'shapley'

Shapley value with coalition weights k!(n-k-1)!/n!.

BANZHAF = 'banzhaf'

Banzhaf index with uniform coalition weights 1/2^(n-1).

class nlp_shap.ExactEstimator

Bases: object

Enumerate all coalitions and delegate attribution to an estimand plugin.

property name: str

Return the registered estimator identifier.

static num_coalitions(num_players: int) → int

Return the number of coalitions evaluated by exact enumeration.

static iter_mask_ints(num_players: int) → Iterator[int]

Lazily yield coalition bitmasks except the all-present coalition.

static mask_int_to_present(mask_int: int, num_players: int) → tuple[bool, ...]

Decode a coalition bitmask into presence flags.

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 every coalition mask except the grand coalition.

static iter_masks(player_set: PlayerSet) → Iterator[CoalitionMask]

Lazily yield coalition masks except the all-present coalition.

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

Aggregate coalition payoffs with the selected estimand plugin.

class nlp_shap.ExplainConfig(*, backend: BackendConfig, generation: GenerationConfig = GenerationConfig(max_new_tokens=128, temperature=0.0, top_k=1, precompute_base=True), explanation: ExplanationConfig = ExplanationConfig(estimand=<Estimand.SHAPLEY: 'shapley'>, estimator='neyman_cc', value_fn='tfidf_cosine', normalizer='identity', players='tokens', absence_policy='delete', budget=BudgetConfig(fraction=1.0), include_minimal_masks=False, neyman=NeymanConfig(use_standard_method=False, initial_fraction=None, initial_num_samples=None), max_inflight=2, archive=ArchiveConfig(path='./runs/{run_id}', flush_every=50), dedup=DedupConfig(enabled='auto'), kv_cache=KvCacheConfig(enabled=True), embedding_mode=<EmbeddingMode.STATIC: 'static'>, seed=42))

Bases: BaseModel

Top-level explain pipeline configuration.

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

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

backend: BackendConfig

Backend selection and connection parameters.

generation: GenerationConfig

Generation parameters for base and coalition evaluations.

explanation: ExplanationConfig

Explanation algorithm and runtime controls.

class nlp_shap.ExplainResult(estimand: Estimand, values: tuple[float, ...])

Bases: object

Attribution output for a single explain run.

estimand: Estimand

Estimand used to aggregate coalition samples.

values: tuple[float, ...]

Per-player attribution values.

class nlp_shap.ExplainRunOutput(result: ExplainResult, metrics: SchedulerMetrics, run_id: str, manifest: RunManifest, perf: PerfSummary | None = None)

Bases: object

Explain pipeline output including scheduler metrics.

result: ExplainResult

Aggregated and normalized attribution values.

metrics: SchedulerMetrics

Coalition scheduler counters for the run.

run_id: str

Stable identifier for the explain run.

manifest: RunManifest

Manifest metadata persisted with optional archives.

perf: PerfSummary | None

Optional wall-clock breakdown for the run.

class nlp_shap.ExplainRunner(config: ExplainConfig, registry: PluginRegistry | None = None, telemetry: ObservabilitySink | None = None, progress: CoalitionProgress | None = None)

Bases: object

Run the explain pipeline for a conversation snapshot.

async explain(snapshot: ConversationSnapshot) → ExplainRunOutput

Execute the async explain pipeline.

explain_sync(snapshot: ConversationSnapshot) → ExplainRunOutput

Execute the explain pipeline on the current event loop policy.

reanalyze(archive_root: Path | str) → ExplainRunOutput

Rescore an archived run with the runner’s current explain settings.

class nlp_shap.GenerationRecord(text: str, text_token_rows: tuple[tuple[int, ...], ...] = (), audio_token_rows: tuple[tuple[int, ...], ...] = (), logprobs: tuple[float, ...] = (), embedding: tuple[float, ...] = (), contextual_embedding: tuple[float, ...] = ())

Bases: object

Concrete generation output consumed by built-in value functions.

text: str

Generated text payload.

text_token_rows: tuple[tuple[int, ...], ...] = ()

Token rows hashed for TF-IDF similarity (multimodal text stream).

audio_token_rows: tuple[tuple[int, ...], ...] = ()

Token rows hashed for TF-IDF similarity (multimodal audio stream).

logprobs: tuple[float, ...] = ()

Per-token log probabilities when the backend exposes them.

embedding: tuple[float, ...] = ()

Static embedding vector for embedding-based value functions.

contextual_embedding: tuple[float, ...] = ()

Contextual embedding vector for U2-style scoring.

class nlp_shap.IdentityNormalizer

Bases: object

Return attributions unchanged.

property name: str

Return the registered normalizer identifier.

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

Return a copy of values.

class nlp_shap.LogprobValue

Bases: object

Score generations from summed token log probabilities.

property name: str

Return the registered value-function identifier.

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

Return utility from candidate logprobs relative to base.

class nlp_shap.Message(role: Role, text: str)

Bases: object

A single explainable text unit with an attached role.

role: Role

Participant role for this text unit.

text: str

Token or span text included in the explainability input.

class nlp_shap.MinMaxNormalizer

Bases: object

Min-max scale to [0, 1] then normalize to sum one.

property name: str

Return the registered normalizer identifier.

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

Return min-max scaled attributions that sum to one.

class nlp_shap.MonteCarloEstimator

Bases: object

Sample random coalitions and delegate attribution to an estimand plugin.

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 random coalition masks up to the configured budget.

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

Aggregate sampled coalition payoffs with the selected estimand plugin.

class nlp_shap.NeymanEstimator(initial_fraction: float | None = None, initial_num_samples: int | None = None, use_standard_method: bool = False)

Bases: ComplementaryEstimator

Two-phase complementary estimator with Neyman coalition-size allocation.

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 phase-one Neyman masks until the initial M-matrix grid is filled.

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

Estimate Neyman allocation after phase-one payoffs are available.

sample_allocation_masks() → Iterator[CoalitionMask]

Yield phase-two masks according to the estimated Neyman allocation.

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

Aggregate Neyman CC payoffs into Shapley-style attributions.

class nlp_shap.PlayerSet(player_ids: tuple[str, ...])

Bases: object

Ordered explainability players aligned with coalition masks.

player_ids: tuple[str, ...]

Stable player identifiers in coalition-mask order.

property num_players: int

Return the number of players in the set.

class nlp_shap.PluginGroup(*values)

Bases: StrEnum

Entry-point groups registered in packaging metadata.

ESTIMATORS = 'nlp_shap.estimators'

Coalition-sampling estimator plugins.

ESTIMANDS = 'nlp_shap.estimands'

Coalition payoff aggregation plugins.

VALUE_FNS = 'nlp_shap.value_fns'

Utility scoring plugins for coalition outputs.

NORMALIZERS = 'nlp_shap.normalizers'

Post-aggregation presentation normalizer plugins.

BACKENDS = 'nlp_shap.backends'

Model inference backend plugins.

PARTITIONS = 'nlp_shap.partitions'

Player-partitioning plugins for conversation snapshots.

ABSENCE_POLICIES = 'nlp_shap.absence_policies'

Absence-policy plugins for rendering masked snapshots.

RENDERERS = 'nlp_shap.renderers'

Attribution visualization renderer plugins.

class nlp_shap.PluginRegistry

Bases: object

Register and resolve pipeline plugins by group and name.

register(group: PluginGroup | str, name: str, factory: Callable[[], object]) → None

Register a plugin factory under group and name.

resolve(group: PluginGroup | str, name: str) → object

Instantiate a plugin registered under group and name.

resolve_factory(group: PluginGroup | str, name: str) → Callable[[], object]

Return the factory registered under group and name.

resolve_type(group: PluginGroup | str, name: str) → type

Return a plugin class registered under group and name.

names(group: PluginGroup | str) → tuple[str, ...]

Return sorted plugin names registered for group.

load_entry_points(group: PluginGroup | str) → None

Discover and register plugins from a packaging entry-point group.

class nlp_shap.Role(*values)

Bases: StrEnum

Participant role attached to a message or token.

USER = 'user'

End-user or human-provided input.

ASSISTANT = 'assistant'

Model-generated output.

SYSTEM = 'system'

System-level instruction or steering text.

class nlp_shap.RunManifest(estimand: Estimand, run_id: str)

Bases: object

Top-level metadata persisted alongside a run archive.

estimand: Estimand

Estimand label recorded for every attribution output.

run_id: str

Stable identifier for the explain run.

to_dict() → RunManifestPayload

Serialize manifest fields to JSON-compatible primitives.

class nlp_shap.ShapleyAggregator

Bases: object

Aggregate coalition samples with Shapley coalition weights.

property estimand: Estimand

Return the Shapley estimand label.

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

Return Shapley coalition weight k!(n-k-1)!/n!.

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

Aggregate coalition samples into Shapley values.

class nlp_shap.TfIdfCosineValue

Bases: object

Score generations with cosine similarity of frozen TF-IDF vectors.

property name: str

Return the registered value-function identifier.

fit(corpus: Sequence[GenerationRecord]) → None

Freeze inverse document frequency weights from corpus.

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

Return TF-IDF cosine similarity between candidate and base.

class nlp_shap.Turn(messages: tuple[Message, ...])

Bases: object

One conversational turn composed of ordered messages.

messages: tuple[Message, ...]

Ordered messages that make up this turn.

nlp_shap.explain_config_from_yaml(text: str) → ExplainConfig

Parse YAML text into a validated ExplainConfig.

nlp_shap.explain_config_to_yaml(config: ExplainConfig) → str

Serialize a config to YAML with stable key ordering within sections.

nlp_shap.parse_manifest(payload: RunManifestPayload) → RunManifest

Parse a typed manifest payload into a run manifest.