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
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 exact estimation.
ExactEstimator	Exact coalition enumeration. See Estimand aggregators and exact estimation.
BanzhafAggregator	Uniform Banzhaf coalition aggregation. See Estimand aggregators and exact 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 exact estimation

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]) → CoalitionMask

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.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, ...]) → ConversationSnapshot

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.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(use_v2=True, 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, 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.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.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.

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.

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.

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