Metadata-Version: 2.4
Name: mlflow-shap
Version: 0.1.1
Summary: Log and load SHAP explainers as MLflow artifacts with a one-liner.
Author-email: Pongsakorn <prince.pongsakorn@outlook.com>
License: MIT License
        
        Copyright (c) 2026 Pongsakorn
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/princepongsakorn/mlflow-shap
Project-URL: Repository, https://github.com/princepongsakorn/mlflow-shap
Project-URL: Issues, https://github.com/princepongsakorn/mlflow-shap/issues
Project-URL: Changelog, https://github.com/princepongsakorn/mlflow-shap/blob/main/CHANGELOG.md
Keywords: mlflow,shap,xai,explainable-ai,machine-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mlflow<4,>=2.0
Requires-Dist: shap>=0.42
Requires-Dist: joblib>=1.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: scikit-learn>=1.2; extra == "dev"
Requires-Dist: numpy>=1.23; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# mlflow-shap

[![PyPI version](https://img.shields.io/pypi/v/mlflow-shap.svg)](https://pypi.org/project/mlflow-shap/)
[![Python versions](https://img.shields.io/pypi/pyversions/mlflow-shap.svg)](https://pypi.org/project/mlflow-shap/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Log and load [SHAP](https://github.com/shap/shap) explainers as [MLflow](https://mlflow.org/) artifacts with a one-liner. Drop-in for any model that `shap.Explainer` accepts (tree models, linear models, deep nets, etc.).

---

## Installation

```bash
pip install mlflow-shap
```

## Quick start

### Log an explainer

```python
import mlflow
from sklearn.ensemble import RandomForestClassifier
from mlflow_shap import log_explainer

with mlflow.start_run() as run:
    model = RandomForestClassifier().fit(X_train, y_train)
    mlflow.sklearn.log_model(model, artifact_path="model")
    log_explainer(model, X_train)
```

### Load it back

```python
from mlflow_shap import load_explainer

explainer = load_explainer(run_id="abc123")
shap_values = explainer(X_test)
```

That's it. The explainer is serialized with `joblib` and stored under the run's `shap_explainer/` artifact directory.

---

## API

### `log_explainer`

```python
log_explainer(
    model,
    data,
    *,
    explainer=None,
    artifact_path="shap_explainer",
    file_name="shap_explainer.pkl",
    explainer_kwargs=None,
    run_id=None,
) -> str
```

Returns the artifact URI (`runs:/<id>/<artifact_path>/<file_name>`).

| Argument | Description |
|---|---|
| `model` | Trained model. Ignored when `explainer` is supplied. |
| `data` | Background data passed to `shap.Explainer`. |
| `explainer` | Pre-built `shap.Explainer` (e.g. `TreeExplainer`, `DeepExplainer`). Skips auto-construction. |
| `artifact_path` | Sub-directory inside the run's artifact root. Default `shap_explainer`. |
| `file_name` | Pickle file name. Default `shap_explainer.pkl`. |
| `explainer_kwargs` | Extra kwargs forwarded to `shap.Explainer(...)`. |
| `run_id` | Target run. Default uses the active run. |

### `load_explainer`

```python
load_explainer(
    run_id,
    artifact_path="shap_explainer/shap_explainer.pkl",
    *,
    dst_path=None,
) -> shap.Explainer
```

Downloads the artifact and deserializes via `joblib`.

---

## Advanced usage

### Use a specific explainer

```python
import shap
from mlflow_shap import log_explainer

tree_explainer = shap.TreeExplainer(model)
log_explainer(model, X_train, explainer=tree_explainer)
```

### Log into a specific run (no active run)

```python
log_explainer(model, X_train, run_id="abc123")
```

### Custom artifact location

```python
log_explainer(model, X_train, artifact_path="explainability/shap", file_name="rf_v2.pkl")
```

---

## Exceptions

| Exception | When raised |
|---|---|
| `NoActiveRunError` | No active MLflow run and no `run_id` was passed. |
| `ExplainerCreationError` | `shap.Explainer(model, data)` failed. Wraps the original error. |
| `MLflowSHAPError` | Base class for the above. |

---

## Compatibility

- Python: 3.9, 3.10, 3.11, 3.12
- MLflow: >= 2.0
- SHAP: >= 0.42

---

## Development

```bash
git clone https://github.com/princepongsakorn/mlflow-shap.git
cd mlflow-shap
pip install -e ".[dev]"
pytest
```

## License

MIT — see [LICENSE](LICENSE).
