mllm-shap¶

Shapley-value attributions for conversational language models. mllm-shap separates what you measure (the estimand: Shapley or Banzhaf), how you sample coalitions (the estimator) and how you score outputs (the value function), and archives every run so it can be reproduced and re-analysed.

Getting started

Install mllm-shap and explain a first prompt, then check that the values add up.

Getting started

How a run works

The stages of an explanation run, its counters, archives and hooks.

How a run works

Theory

Shapley axioms, cooperative games, estimands, and when they diverge.

Shapley values and axioms

Applications

Business, compliance, and LLM operations use cases for attribution.

Business and compliance applications

API reference

Typed public modules, protocols, and re-exported symbols.

API reference

Examples

Runnable Jupyter notebooks with end-to-end walkthroughs (estimands, masking, runtime, exact and approximate estimation).

Examples

Citing

How to cite mllm-shap and the methods behind it.

Citing mllm-shap

Contributing

Development setup, quality gates and pull request conventions.

Contributing to mllm-shap

Knowledge vault

Architecture, design decisions, known issues and papers, kept as an Obsidian vault in the repository.

https://github.com/Pawlo77/MLLM-SHAP/blob/main/knowledge/mllm-shap.md

How it compares¶

shap (KernelExplainer, PartitionExplainer), captum (ShapleyValueSampling) and TokenSHAP also estimate Shapley values for text. mllm-shap differs in four ways:

the estimand (Shapley or Banzhaf) is an explicit label on every result, separate from the estimator (Estimands: Shapley vs Banzhaf);
every run is archived and can be rescored without backend calls (reanalyze(), Runtime core);
backends are plugins: mock, LM Studio, Hugging Face transformers and OpenAI-compatible APIs (Generative backends);
complementary-contribution and Neyman estimators sit next to Monte Carlo and exact enumeration (Approximate estimation).

Quick install¶

pip install mllm-shap

Requires Python 3.12 or newer. See Getting started for a full walkthrough.

Optional extras:

pip install "mllm-shap[transformers]"   # Hugging Face backend
pip install "mllm-shap[lmstudio]"       # LM Studio backend
pip install "mllm-shap[api]"            # OpenAI-compatible HTTP API
pip install "mllm-shap[viz]"            # matplotlib attribution charts

See Extending mllm-shap for the full extras and entry-point matrix.