Examples

The examples/ directory contains Jupyter notebooks with runnable mllm-shap workflows. They complement guides, theory pages, and the API reference.

Setup

Install the package:

pip install mllm-shap

From a local clone:

make install

make notebooks re-executes every notebook and stores its outputs. For interactive work, register the project environment as a kernel with make kernel (mllm-shap (uv)) or select .venv as the kernel.

Notebooks

Each row links to the rendered walkthrough in these docs. Use Source to open the .ipynb on GitHub or browse the full catalog in examples/README.md.

Notebook	What it demonstrates	Extras	Source
Explain a conversation with ExplainRunner	ExplainRunner end to end: content parts and snapshot JSON, PlayerSet spans, YAML configuration and its ConfigError guards, the efficiency check, to_dict(), every estimator and estimand, progress callbacks, stage spans and logging.	none	GitHub
Run archives and reanalyze	Run archives (manifest version 4, WAL, on_exists), reanalyze() reproducing explain, rescoring with every value function and normalizer, the archive errors and strict=True.	none	GitHub
Command line: mllm-shap	mllm-shap explain, reanalyze, plugins and config; JSON and PNG output; exit codes 0, 2 and 3.	[viz]	GitHub
Plugins: registry, context and options	default_registry(), PluginContext, plugin_options and their validation, a custom backend and value function, plugin conflicts and entry points.	none	GitHub
Shapley vs Banzhaf on toy cooperative games	Shapley and Banzhaf aggregators on majority vs additive games; ExplainResult labelling and RunManifest wire format.	none	GitHub
Coalition masking and absence policies	Token partition, delete/pad/neutral absence policies, MaskedSnapshot, MaskCodec, and MaskSpace.	none	GitHub
Runtime archive, deduplication, and async scheduling	Run archive persistence, coalition dedup keys, hot LRU cache, and async InferenceScheduler metrics.	none	GitHub
Exact estimation with estimand plugins	ExactEstimator enumeration of all \(2^n\) coalitions and estimate_attributions() estimand delegation with budget guards.	none	GitHub
Estimator comparison: budget, variance, and accuracy	Monte Carlo, complementary and Neyman-CC against exact Shapley values; relative L1 error as the budget fraction grows.	[viz]	GitHub
Attribution visualization	Real-model attributions of a prompt (words), a multi-speaker conversation (messages, Shapley and Banzhaf) and a spoken sentence (audio words), rendered with token_text, token_bar, display_attribution_html(), render_attribution_html(), the renderer classes and plot_audio_segments().	[viz], [transformers], [audio]	GitHub
End-to-end text explainability on real backends	One refund question, guarded by a system prompt, on the LM Studio, transformers (KV cache, dtype, pinned revision) and HTTP API backends from the config/ presets, then visualized with render_attribution(); LM Studio is skipped when no server runs.	[lmstudio], [transformers], [api], [viz]	GitHub
Audio alignment with SGPA	SpectrogramGuidedAligner on a recorded sentence with a pinned Wav2Vec2 model: word segments, shared refined boundaries, boundary weights, attached segment audio, the ValueError guards and a custom CtcModel.	[audio], [transformers]	GitHub
Audio runs on the mock backend	MockAudioBackend on a synthesised clip: heard tokens per voiced run, a silenced word, max_new_tokens, an explanation with backend.kind: mock_audio and the undecodable-audio guard.	(core)	GitHub
Explaining a spoken sentence with an audio language model	Granite Speech hears a recorded sentence through the transformers backend, then sgpa_segments attributes its answer to the spoken words; the lmstudio audio refusal.	[audio], [transformers]	GitHub