Metadata-Version: 2.4
Name: unifiedig
Version: 0.1.0.dev3
Summary: A unified, model-agnostic interface for Integrated Gradients
Author: Ludger Hentschel
License-Expression: MIT
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scikit-learn>=1.2
Provides-Extra: shap
Requires-Dist: shap>=0.42; extra == "shap"
Provides-Extra: torch
Requires-Dist: captum>=0.7; extra == "torch"
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: trees
Requires-Dist: treeig>=0.1.8; extra == "trees"
Provides-Extra: test
Requires-Dist: build>=1; extra == "test"
Requires-Dist: matplotlib>=3.6; extra == "test"
Requires-Dist: pandas>=1.5; extra == "test"
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: shap>=0.42; extra == "test"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "test"
Requires-Dist: twine>=5; extra == "test"
Dynamic: license-file

# Unified IG

Unified IG provides one small, SHAP-like API for Integrated Gradients across
model families. The first implementation supports closed-form attributions for
scikit-learn linear models and multilayer perceptrons.

```python
import unifiedig as uig

explainer = uig.Explainer(model, baseline)
explanation = explainer(X)
```

For numerical backends, the quadrature resolution is configurable:

```python
explainer = uig.Explainer(model, baseline, n_steps=128)
```

`Explanation` is lightweight and has SHAP-compatible fields. SHAP remains an
optional dependency; call `explanation.to_shap()` to use its plotting tools.

## Installation

During development, install the project and its test dependencies with:

```console
python -m pip install -e ".[test]"
```

## Output semantics

For regression, attributions sum to the difference between the prediction and
the baseline prediction. Binary classifiers are explained on their
decision-score (logit) scale; probability attributions are not part of V1.
See `docs/semantics.md` for the complete array-shape and output contract.

Numerical explanations expose their observed completeness residual:

```python
explanation.completeness_error
explanation.max_abs_completeness_error
```

Unified IG warns when this error exceeds the configured tolerance. Increasing
`n_steps` usually improves it. See the `examples/` directory for complete
linear, logistic, MLP regression, and MLP classification programs.

## Supported models

- `sklearn.linear_model.LinearRegression` (closed form)
- Binary `sklearn.linear_model.LogisticRegression` (closed form)
- `sklearn.neural_network.MLPRegressor` (analytic gradients and quadrature)
- Binary `sklearn.neural_network.MLPClassifier` (analytic logit gradients and quadrature)
- PyTorch modules with one raw scalar output per sample (Captum, optional)
- TreeIG-supported sklearn, XGBoost, and LightGBM trees (exact, optional)

Install PyTorch support separately so the core package remains lightweight:

```console
pip install "unifiedig[torch]"
```

Install exact tree-model support separately:

```console
pip install "unifiedig[trees]"
```

Tree attributions are computed by TreeIG; Unified IG normalizes the input and
baseline and adapts TreeIG's exact result to `Explanation`.

PyTorch models may accept tabular or structured single-tensor inputs. Unified IG
preserves the model's device and floating-point dtype, temporarily evaluates the
model in inference mode, and restores every module's prior training state. V1
expects one raw scalar output per sample. For binary classification that output
must be the logit, not a sigmoid probability.

## Development

Run the tests and validate distribution artifacts with:

```console
pytest
python -m build
python -m twine check dist/*
```

See `CONTRIBUTING.md` for the development workflow.
