📦 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
- Getting started
- User guide — estimands
- User guide — masking
- User guide — runtime
- User guide — exact estimation
- User guide — approximate estimation
- User guide — visualization
- Examples (notebooks)
- API reference
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.
Copyright 2026 Paweł Pozorski.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file nlp_shap-0.1.14.tar.gz.
File metadata
- Download URL: nlp_shap-0.1.14.tar.gz
- Upload date:
- 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
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
45ada128d91e78c1f380f7b95c311880da2802a26d7033135847bc401116dd01
|
|
| MD5 |
7d1a9edd0718b1855503622d13862880
|
|
| BLAKE2b-256 |
259bdc31bf7f60a68513a0e1521da893bad578a040669059effe007014e07495
|
File details
Details for the file nlp_shap-0.1.14-py3-none-any.whl.
File metadata
- Download URL: nlp_shap-0.1.14-py3-none-any.whl
- Upload date:
- 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
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7f2316ed86dca7e5b57bbba00ee3d59dbbac2e8cefca983df59a13424d2965d3
|
|
| MD5 |
7f22eaa002625f49af986cdc7223f6a4
|
|
| BLAKE2b-256 |
4f12840640d902bc5e7ef801647f0e6a8b30711c7000b04505356eb7261b6842
|
