📦 nlp-shap

Multimodal explainability for NLP and multimodal models based on Shapley-style cooperative game theory.

Installation

pip install nlp-shap

Optional backends and visualization:

pip install "nlp-shap[transformers]"   # Hugging Face text backend
pip install "nlp-shap[lmstudio]"       # LM Studio SDK
pip install "nlp-shap[api]"            # OpenAI-compatible HTTP API
pip install "nlp-shap[viz]"            # matplotlib token charts

The core package does not install PyTorch. See the extending guide for plugin entry points.

Quickstart

from nlp_shap import ExplainConfig, ExplainRunner
from nlp_shap.domain.conversation import ConversationSnapshot, Message, Turn
from nlp_shap.domain.enums import Role

snapshot = ConversationSnapshot.from_turns((
    Turn(messages=(Message(role=Role.USER, text="refund my order"),)),
))
config = ExplainConfig.model_validate({
    "backend": {"kind": "mock", "model_id": "stub"},
    "explanation": {"estimator": "exact", "value_fn": "tfidf_cosine"},
})
output = ExplainRunner(config).explain_sync(snapshot)
print(output.result.values)

From source:

git clone https://github.com/Pawlo77/nlp-shap
cd nlp-shap
make install

Requires Python 3.12 and uv.

Documentation

Full documentation: pawlo77.github.io/nlp-shap

Examples

Runnable Jupyter notebooks in examples/:

Notebook	What it demonstrates
`estimands_toy_game.ipynb`	Shapley vs Banzhaf aggregators, coalition weights, labelled results, manifests, plugin entry points
`masking_views.ipynb`	Token partitioning, absence policies, masked views, mask codec, mask space, plugin registry
`runtime_core.ipynb`	Run archive, coalition dedup, hot LRU cache, async scheduler with bounded concurrency
`exact_estimation.ipynb`	Exact coalition enumeration, estimand delegation, budget guard, plugin resolution
`estimator_comparison.ipynb`	Eight-player cap≤20 benchmark + five-player fraction sweep 0.1–0.5, MC bias analysis
`attribution_viz.ipynb`	Per-token Shapley visualization with `token_text` and `token_bar` renderers
`text_explain_e2e.ipynb`	Full explain pipeline on a refund FAQ prompt — LM Studio + transformers + charts

Setup and details: examples/README.md. Embedded walkthroughs: docs/examples.

Development

make install
make check

Run make help for other targets.

License

Apache License 2.0. See LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nlp_shap-0.1.15.tar.gz (50.2 kB view details)

Uploaded Jul 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

nlp_shap-0.1.15-py3-none-any.whl (85.5 kB view details)

Uploaded Jul 15, 2026 Python 3

File details

Details for the file nlp_shap-0.1.15.tar.gz.

File metadata

Download URL: nlp_shap-0.1.15.tar.gz
Upload date: Jul 15, 2026
Size: 50.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for nlp_shap-0.1.15.tar.gz
Algorithm	Hash digest
SHA256	`4fc8d37f0255302c54ef1b91a5ef084d57581c85ddd6dcbdbcd54bdd39c29e8c`
MD5	`fa52f2971fb140851a48c15cb6a3b7fb`
BLAKE2b-256	`282edd366f00ef02d0278e3d990ffc1b0d1c4a2075d72638d1155d3beb8334b4`

See more details on using hashes here.

File details

Details for the file nlp_shap-0.1.15-py3-none-any.whl.

File metadata

Download URL: nlp_shap-0.1.15-py3-none-any.whl
Upload date: Jul 15, 2026
Size: 85.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for nlp_shap-0.1.15-py3-none-any.whl
Algorithm	Hash digest
SHA256	`cffd81ec6f9fc00a116a8998a74143df182ffce5f74ba4cf5a2eb99045068543`
MD5	`19dea06cc42b05a6c09a01efaa73641a`
BLAKE2b-256	`59cd268800501f199e0b3ba6b25cc407a2269430d22bdce23c0b15b53d418dba`