Metadata-Version: 2.4
Name: torchxai-tools
Version: 0.1.3
Summary: TorchXAI is a PyTorch-based toolkit for evaluating machine learning models using explainability techniques.
Author-email: Saifullah <saifullah.saifullah@dfki.de>
Maintainer-email: Saifullah <saifullah.saifullah@dfki.de>
License: MIT License
        
        Copyright (c) [year] [fullname]
        
        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/atriaml/torchxai/
Project-URL: Bug Reports, https://github.com/atriaml/torchxai/issues
Project-URL: Source, https://github.com/atriaml/torchxai/
Project-URL: Documentation, https://saifullah3396.github.io/torchxai/
Keywords: torch,explainable-ai,interpretability,machine-learning,deep-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: torch>=2.1.0
Requires-Dist: captum>=0.7.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: numpy<2.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: overrides>=7.0.0
Requires-Dist: nltk>=3.9.4
Requires-Dist: anls>=0.0.2
Provides-Extra: vision
Requires-Dist: torchvision>=0.16.0; extra == "vision"
Provides-Extra: dev
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: pytest>=9.0.0; extra == "dev"
Requires-Dist: ruff>=0.14.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: transformers>=4.37.0; extra == "dev"
Dynamic: license-file

# TorchXAI

TorchXAI is a lightweight PyTorch toolkit for evaluating machine learning models using explainability techniques. It wraps [Captum](https://captum.ai/) attribution methods and adds **multi-target attribution** — explain multiple output classes in a single forward pass — plus ready-to-use metrics for quantifying explanation quality.

- **Captum-compatible** — works alongside the Captum explainers you already use
- **Multi-target** — compute attributions for all targets at once, not one at a time
- **Batch & scalable** — built for dataset-scale evaluation across many inputs and explainers

## Installation

```bash
pip install torchxai-tools
```

The PyPI distribution is named `torchxai-tools`; the import name is `torchxai`.

```python
from torchxai.explainers import SaliencyExplainer   # import name is torchxai
```

## Quick start

### Generating explanations

```python
import torch
import torch.nn as nn
from torchxai.explainers import SaliencyExplainer, IntegratedGradientsExplainer
from torchxai.data_types import SingleTargetAcrossBatch

model = nn.Sequential(nn.Linear(10, 5), nn.ReLU(), nn.Linear(5, 3))
model.eval()
inputs = torch.randn(1, 10)

# Single target
explainer = SaliencyExplainer(model)
attrs = explainer.explain(inputs=inputs, target=SingleTargetAcrossBatch(index=0))
print(attrs.shape)   # (1, 10)

# All three classes in one call
explainer_mt = SaliencyExplainer(model, multi_target=True)
targets = [SingleTargetAcrossBatch(index=i) for i in range(3)]
attrs_list = explainer_mt.explain(inputs=inputs, target=targets)
print(len(attrs_list), attrs_list[0].shape)   # 3, (1, 10)
```

### With a baseline (IntegratedGradients, DeepLift, …)

```python
from torchxai.explainers import IntegratedGradientsExplainer

baseline = torch.zeros_like(inputs)
explainer = IntegratedGradientsExplainer(model)
attrs = explainer.explain(
    inputs=inputs,
    baselines=baseline,
    target=SingleTargetAcrossBatch(index=0),
)
```

### Evaluating explanation quality

```python
from torchxai.metrics.axiomatic import completeness
from captum.attr import Saliency

net = ...   # your model
saliency = Saliency(net)
input = torch.randn(2, 3, 32, 32, requires_grad=True)
baselines = torch.zeros(2, 3, 32, 32)

attribution = saliency.attribute(input, target=3)
score = completeness(net, input, attribution, baselines)
print("Completeness:", score)
```

## Supported explainers

| Explainer | Requires baseline | Notes |
|---|:---:|---|
| `SaliencyExplainer` | ✗ | |
| `InputXGradientExplainer` | ✗ | |
| `GuidedBackpropExplainer` | ✗ | Not compatible with transformers |
| `RandomExplainer` | ✗ | Baseline for sanity-checking |
| `IntegratedGradientsExplainer` | ✓ | |
| `DeepLiftExplainer` | ✓ | Not compatible with transformers |
| `InputXBaselineGradientExplainer` | ✓ | |
| `DeepLiftShapExplainer` | ✓ distribution | Not compatible with transformers |
| `GradientShapExplainer` | ✓ distribution | |
| `FeatureAblationExplainer` | ✗ | Optional `feature_mask` |
| `LimeExplainer` | ✗ | Optional `feature_mask` |
| `KernelShapExplainer` | ✗ | Optional `feature_mask` |
| `OcclusionExplainer` | ✗ | Requires `sliding_window_shapes` |

## Documentation

Full documentation including per-explainer API reference and end-to-end examples (image classification, BERT sequence classification, NER):

**[saifullah3396.github.io/torchxai](https://saifullah3396.github.io/torchxai/)**

## License

MIT — see [LICENSE.txt](LICENSE.txt).
