Metadata-Version: 2.4
Name: nlp-shap
Version: 0.1.16
Summary: Multimodal explainability tool for NLP based on Shapley value.
Keywords: explainability,llms,multimodal,nlp,shapley-value,xai
Author: Paweł Pozorski
Author-email: Paweł Pozorski <pozorski.paul@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: logging518>=1.0.0,<2.0.0
Requires-Dist: numpy>=2.0.0,<3.0.0
Requires-Dist: pydantic>=2.11.0,<3.0.0
Requires-Dist: pyyaml>=6.0.2,<7.0.0
Requires-Dist: httpx>=0.28.0 ; extra == 'api'
Requires-Dist: bandit>=1.9.4 ; extra == 'dev'
Requires-Dist: httpx>=0.28.0 ; extra == 'dev'
Requires-Dist: matplotlib>=3.9.0 ; extra == 'dev'
Requires-Dist: seaborn>=0.13.0 ; extra == 'dev'
Requires-Dist: mypy>=1.16.0 ; extra == 'dev'
Requires-Dist: prek>=0.4.9 ; extra == 'dev'
Requires-Dist: pytest>=8.4.2 ; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0 ; extra == 'dev'
Requires-Dist: ruff>=0.15.20 ; extra == 'dev'
Requires-Dist: lmstudio>=1.5.0 ; extra == 'lmstudio'
Requires-Dist: accelerate>=1.0.0 ; extra == 'transformers'
Requires-Dist: torch>=2.5.0 ; extra == 'transformers'
Requires-Dist: transformers>=4.40.0 ; extra == 'transformers'
Requires-Dist: matplotlib>=3.9.0 ; extra == 'viz'
Requires-Dist: seaborn>=0.13.0 ; extra == 'viz'
Requires-Dist: ipywidgets>=8.1.0 ; extra == 'viz'
Maintainer: Paweł Pozorski
Maintainer-email: Paweł Pozorski <pozorski.paul@gmail.com>
Requires-Python: >=3.12, <3.13
Project-URL: Homepage, https://github.com/Pawlo77/nlp-shap
Project-URL: Documentation, https://pawlo77.github.io/nlp-shap/
Project-URL: Repository, https://github.com/Pawlo77/nlp-shap
Project-URL: Issues, https://github.com/Pawlo77/nlp-shap/issues
Provides-Extra: api
Provides-Extra: dev
Provides-Extra: lmstudio
Provides-Extra: transformers
Provides-Extra: viz
Description-Content-Type: text/markdown

<div align="center">
  <h1>📦 nlp-shap</h1>
  <p><strong>Multimodal explainability for NLP and multimodal models based on Shapley-style cooperative game theory.</strong></p>
  <p>
    <a href="https://pypi.org/project/nlp-shap/"><img src="https://img.shields.io/pypi/v/nlp-shap.svg" alt="PyPI"></a>
    <a href="https://pypi.org/project/nlp-shap/"><img src="https://img.shields.io/pypi/pyversions/nlp-shap.svg" alt="Python"></a>
    <a href="https://pawlo77.github.io/nlp-shap/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Documentation"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
  </p>
</div>

## Installation

```bash
pip install nlp-shap
```

Optional backends and visualization:

```bash
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](https://pawlo77.github.io/nlp-shap/guides/extending.html) for plugin entry points.

## Quickstart

```python
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:

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

Requires Python 3.12 and [uv](https://docs.astral.sh/uv/).

## Documentation

Full documentation: **[pawlo77.github.io/nlp-shap](https://pawlo77.github.io/nlp-shap/)**

- [Getting started](https://pawlo77.github.io/nlp-shap/guides/getting_started.html)
- [User guide — estimands](https://pawlo77.github.io/nlp-shap/guides/estimands.html)
- [User guide — masking](https://pawlo77.github.io/nlp-shap/guides/masking.html)
- [User guide — runtime](https://pawlo77.github.io/nlp-shap/guides/runtime.html)
- [User guide — exact estimation](https://pawlo77.github.io/nlp-shap/guides/exact.html)
- [User guide — approximate estimation](https://pawlo77.github.io/nlp-shap/guides/approximation.html)
- [User guide — visualization](https://pawlo77.github.io/nlp-shap/guides/visualization.html)
- [Examples (notebooks)](https://pawlo77.github.io/nlp-shap/examples.html)
- [API reference](https://pawlo77.github.io/nlp-shap/api.html)

## Examples

Runnable **Jupyter notebooks** in [`examples/`](examples/):

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

Setup and details: [`examples/README.md`](examples/README.md). Embedded walkthroughs: [docs/examples](https://pawlo77.github.io/nlp-shap/examples.html).

## Development

```bash
make install
make check
```

Run `make help` for other targets.

## License

Apache License 2.0. See [LICENSE](LICENSE).

Copyright 2026 Paweł Pozorski.
