API reference

mllm-shap exposes a small, typed public surface. Import the symbols below from mllm_shap; the module pages document every class and function where it is defined.

Public exports

The table is generated from mllm_shap.__all__ at build time, so it always lists what from mllm_shap import ... accepts.

Symbol	Summary
AbsSumNormalizer	Scale attributions by the sum of absolute values.
ApiBackend	Generate text through an OpenAI-compatible /chat/completions endpoint.
ArchiveCorruptError	Raised when a run archive or its manifest cannot be read or parsed.
ArchiveExistsError	Raised when a run archive already exists and on_exists is "error".
ArchiveIncompleteError	Raised when reanalyze meets an archive of a run that did not finish.
ArchiveNotFoundError	Raised when a run archive lacks its manifest or SQLite database.
AudioPart	Audio content of a message, held in memory or referenced by path.
BackendUnavailableError	Raised when a configured generative backend cannot be reached.
BanzhafAggregator	Aggregate coalition samples with uniform Banzhaf coalition weights.
CoalitionMask	Boolean presence mask aligned with a player set.
CoalitionProgress	Sync hooks notified as coalition jobs are planned and finished.
ComplementaryEstimator	Sample complementary coalition pairs and aggregate CC attributions.
ConfigError	Raised when configuration values are invalid or inconsistent.
ConversationSnapshot	Frozen conversation state used as the explainability input.
CooperativeGame	Player set and reference values for a characteristic function.
CosineEmbeddingValue	Cosine similarity between static or contextual embeddings (U1/U2).
DeletePolicy	Remove absent players from the rendered conversation.
DeletionCurve	Value of the coalition left after removing the top-k players, per k.
Estimand	Supported cooperative-game value formulations.
EuclideanEmbeddingValue	Similarity 1 / (1 + distance) between embeddings (U4).
ExactEstimator	Enumerate all coalitions and delegate attribution to an estimand plugin.
ExplainConfig	Top-level explain pipeline configuration.
ExplainResult	Attribution output for a single explain run.
ExplainRunOutput	Explain pipeline output including scheduler metrics.
ExplainRunner	Run the explain pipeline for a conversation snapshot.
GenerationRecord	Concrete generation output consumed by built-in value functions.
IdentityNormalizer	Return attributions unchanged.
InMemoryObservabilitySink	Collect span records in memory for tests and diagnostics.
LeaveOneOutEstimator	Attribute v(N) - v(N - {i}) to player i from n + 1 coalitions.
LmStudioBackend	Generate text through a local LM Studio API server.
LogprobValue	Score a coalition by the model’s confidence in its own generation.
LogprobsUnavailableError	Raised when a value function needs token logprobs a generation lacks.
ManifestVersionError	Raised when a run manifest or archive uses an unsupported schema version.
Message	One message of a conversation: a role and ordered content parts.
MessagePartitioner	Partition a snapshot into one player per non-empty message.
MinMaxNormalizer	Min-max scale to [0, 1] then normalize to sum one.
MllmShapError	Root of every error raised on purpose by mllm-shap.
MockAudioBackend	Echo text words and answer one token per voiced run of every audio part.
MockBackend	Hash-based generative backend with no external model dependencies.
MonteCarloEstimator	Sample random coalitions and delegate attribution to an estimand plugin.
NeutralPolicy	Replace absent players with neutral fillers that preserve their width.
NeymanEstimator	Two-phase complementary estimator with Neyman coalition-size allocation.
ObservabilitySink	Protocol for recording explain pipeline stage spans.
PadPolicy	Replace absent players with a fixed mask placeholder.
PlayerSet	Ordered explainability players aligned with coalition masks.
PlayerSpan	Where one player sits in the conversation it was partitioned from.
PluginConflictError	Raised when a plugin name is registered twice without replace=True.
PluginContext	Inputs a plugin factory receives when the registry builds a plugin.
PluginGroup	Entry-point groups registered in packaging metadata.
PluginLoadError	Raised when a packaging entry point cannot be imported.
PluginNotFoundError	Raised when no plugin is registered under the requested group and name.
PluginRegistry	Register and resolve pipeline plugins by group and name.
PowerShiftNormalizer	Shift to non-negative values, apply a power, then scale to sum one.
ReanalyzeMismatchError	Raised when reanalyze settings disagree with the archived run.
ReferenceWerValue	Score 1 - min(1, WER) of a coalition’s answer against a reference.
Role	Participant role attached to a message or token.
RunManifest	Top-level metadata persisted alongside a run archive.
SgpaSegmentPartitioner	Make each spellable word of every audio message’s transcript a player.
ShapleyAggregator	Aggregate coalition samples with Shapley coalition weights.
TextPart	Text content of a message.
TfIdfCosineValue	Score generations with cosine similarity of frozen TF-IDF vectors.
TokenBarRenderer	Render attributions as a SHAP-style horizontal bar chart.
TokenPartitioner	Partition a snapshot into whitespace-delimited text tokens.
TokenTextRenderer	Render attributions as inline colored tokens.
TransformersTextBackend	Generate text with a local Hugging Face language model.
Turn	One conversational turn composed of ordered messages.
configure_logging	Configure the mllm_shap loggers from TOML or with one stderr handler.
default_registry	Return a registry with the built-in plugins and third-party entry points.
deletion_curve	Score snapshot with its k highest-attributed players removed at once.
display_attribution_html	Display colored token HTML when IPython is available.
explain_config_from_yaml	Parse YAML text into a validated ExplainConfig.
explain_config_to_yaml	Serialize a config to YAML with stable key ordering within sections.
parse_manifest	Parse a JSON manifest payload into a run manifest.
render_attribution	Render output attributions with a registered renderer plugin.
render_attribution_html	Return an HTML fragment for inline token coloring in Jupyter.

Modules

• Domain types
• Protocols
• Plugins
• Pipeline
• Command line
• Errors
• Masking
• Runtime
• Estimation
• Value functions
• Backends
• Visualization
• Alignment

Package-level objects

Shapley-value attributions for conversational language models.

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

mllm_shap.configure_logging(config_path: Path | str | None = None, level: int | str | None = None, json: bool = False) → Path | None

Configure the mllm_shap loggers from TOML or with one stderr handler.

Without level and json the [tool.logging] section of a TOML file is applied. With either of them and no config_path, the package logger gets a single stderr handler instead (replacing earlier handlers) and stops propagating to the root logger (propagate=False), so records are not printed twice by a root handler; configure_logging(level="INFO") shows the pipeline’s stage events.

Parameters:

• config_path – TOML file to read. Defaults to MLLM_SHAP_LOGGING_CONFIG or the nearest pyproject.toml above the working directory.

• level – Level of the mllm_shap logger ("INFO", logging.DEBUG…); overrides the TOML level when both are given. Defaults to INFO for the stderr handler.

• json – Emit one JSON object per record (time, level, logger, message) instead of plain lines. Only for the stderr handler.

Returns:

The TOML file that was read, or None when none was (a NullHandler is installed when neither a file nor level/json was given).

Raises:

ValueError – If json is combined with config_path; the TOML file defines its own formatters.

mllm_shap.__version__: str

Installed package version, read from the distribution metadata (0.0.0+unknown when the package is not installed).