unified-xai 0.1.1
Unified XAI: An Explainable AI library for interpretable machine learning, Deep Learning and Artifical Intelligence.
License: MIT
Requires Python: >=3.8

# Unified XAI

### Production-Ready Explainable AI Library for Deep Learning

[![PyPI version](https://badge.fury.io/py/unified-xai.svg)](https://badge.fury.io/py/unified-xai)
[![Python](https://img.shields.io/pypi/pyversions/unified-xai.svg)](https://pypi.org/project/unified-xai/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Documentation](https://readthedocs.org/projects/unified-xai/badge/?version=latest)](https://unified-xai.readthedocs.io/en/latest/?badge=latest)
<!-- [![Tests](https://github.com/SatyamSingh8306/unified-xai/workflows/Tests/badge.svg)](https://github.com/SatyamSingh8306/unified-xai/actions) -->
<!-- [![Coverage](https://codecov.io/gh/yourusername/unified-xai/branch/main/graph/badge.svg)](https://codecov.io/gh/yourusername/unified-xai) -->
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

[**Documentation**](https://satyamsingh8306.github.io/unified-xai/) | [**Tutorials**](https://satyamsingh8306.github.io/unified-xai/) | [**API Reference**](https://satyamsingh8306.github.io/unified-xai/)
</div>

---

## 🎯 Overview

**Unified XAI** is a comprehensive, production-ready library for explaining deep learning models across multiple frameworks and modalities. It provides a unified API for various explainability methods, making it easy to understand, debug, and improve your AI models.

### ✨ Key Features

- 🔄 **Framework Agnostic**: Seamless support for PyTorch, TensorFlow, Keras, and ONNX
- 📊 **Multiple Modalities**: Image, text, tabular, time-series, and multimodal data
- 🎨 **Rich Visualizations**: Interactive plots, heatmaps, and dashboards
- 📈 **Comprehensive Metrics**: Faithfulness, stability, complexity evaluations
- ⚡ **High Performance**: Optimized implementations with caching and parallelization
- 🔧 **Production Ready**: Type hints, extensive testing, and robust error handling
- 🚀 **Easy to Use**: Simple API with sensible defaults
- 📦 **Extensible**: Plugin architecture for custom methods

## 🚀 Quick Start

### Installation

```bash
# Basic installation
pip install unified-xai

# With specific framework support
pip install unified-xai[torch]  # PyTorch support
pip install unified-xai[tf]     # TensorFlow support
pip install unified-xai[all]    # All frameworks

# Development installation
pip install unified-xai[dev]

# With dashboard support
pip install unified-xai[dashboard]
```

### Basic Usage

```python
import torch
from unified_xai import XAIAnalyzer, XAIConfig
from unified_xai.config import Framework, Modality

# Load your model
model = torch.load('your_model.pth')

# Configure XAI
config = XAIConfig(
    framework=Framework.PYTORCH,
    modality=Modality.IMAGE
)

# Initialize analyzer
analyzer = XAIAnalyzer(model, config)

# Generate explanation
explanation = analyzer.explain(
    input_data, 
    method='integrated_gradients',
    target=class_idx
)

# Visualize
fig = analyzer.visualize(explanation, original_input=input_data)
```

## 📚 Supported Methods

### Gradient-Based Methods
- ✅ Vanilla Gradient
- ✅ Integrated Gradients
- ✅ SmoothGrad
- ✅ Grad-CAM / Grad-CAM++
- ✅ Guided Backpropagation
- ✅ DeepLIFT

### Perturbation-Based Methods
- ✅ LIME (Local Interpretable Model-agnostic Explanations)
- ✅ SHAP (SHapley Additive exPlanations)
- ✅ Occlusion Sensitivity
- ✅ Meaningful Perturbations

### Attention-Based Methods
- ✅ Attention Rollout
- ✅ Attention Flow
- ✅ LRP (Layer-wise Relevance Propagation)

### Example-Based Methods
- ✅ Influence Functions
- ✅ Prototype Selection
- ✅ Counterfactual Explanations

## 🎯 Use Cases

<details>
<summary><b>Computer Vision</b></summary>

```python
# Explain image classification
explanation = analyzer.explain(image, method='gradcam')

# Compare multiple methods
comparison = analyzer.compare_methods(
    image,
    methods=['gradcam', 'integrated_gradients', 'lime'],
    metrics=['faithfulness', 'complexity']
)
```
</details>

<details>
<summary><b>Natural Language Processing</b></summary>

```python
# Explain text classification
config = XAIConfig(framework=Framework.PYTORCH, modality=Modality.TEXT)
analyzer = XAIAnalyzer(bert_model, config)

explanation = analyzer.explain(
    text_tokens, 
    method='integrated_gradients'
)
```
</details>

<details>
<summary><b>Tabular Data</b></summary>

```python
# Explain tabular predictions
config = XAIConfig(modality=Modality.TABULAR)
analyzer = XAIAnalyzer(model, config)

explanation = analyzer.explain(
    tabular_data,
    method='shap',
    background_data=train_data
)
```
</details>

## 📊 Evaluation Metrics

Unified XAI provides comprehensive metrics to evaluate explanation quality:

```python
# Evaluate explanation
metrics = analyzer.evaluator.evaluate(
    explanation,
    input_data,
    metrics=['faithfulness', 'stability', 'complexity', 'sensitivity']
)

# Compare methods quantitatively
rankings = analyzer.compare_methods(
    input_data,
    methods=['gradcam', 'lime', 'shap'],
    metrics=['faithfulness', 'stability']
)
```

## 🎨 Visualization Dashboard

Launch interactive dashboard for exploration:

```bash
# Command line
unified-xai dashboard --model path/to/model --port 8080

# Or in Python
from unified_xai.dashboard import launch_dashboard
launch_dashboard(model, port=8080)
```

## 🏗️ Architecture

```
unified-xai/
├── core/              # Core abstractions and base classes
├── methods/           # Explanation method implementations
│   ├── gradient/      # Gradient-based methods
│   ├── perturbation/  # Perturbation-based methods
│   ├── attention/     # Attention-based methods
│   └── example/       # Example-based methods
├── frameworks/        # Framework-specific adapters
├── visualization/     # Visualization utilities
├── metrics/          # Evaluation metrics
├── utils/            # Helper utilities
└── dashboard/        # Web dashboard
```

## 🔧 Configuration

Unified XAI supports various configuration options:

```python
# From file
config = XAIConfig.from_file('config.yaml')

# Programmatic
config = XAIConfig(
    framework=Framework.PYTORCH,
    modality=Modality.IMAGE,
    gradient_config={
        'normalize': True,
        'smooth_samples': 50
    },
    visualization_config={
        'cmap': 'RdBu_r',
        'overlay': True
    }
)
```

Example `config.yaml`:
```yaml
framework: pytorch
modality: image
batch_size: 32
device: cuda

gradient_config:
  normalize: true
  smooth_samples: 50
  
lime_config:
  num_samples: 1000
  num_features: 10
  
visualization_config:
  cmap: RdBu_r
  alpha: 0.7
```

## 🧪 Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=unified_xai

# Run specific test module
pytest tests/test_methods.py

# Run benchmarks
pytest tests/benchmarks/ --benchmark-only
```

## 📖 Documentation

Full documentation is available at [https://unified-xai.readthedocs.io](https://unified-xai.readthedocs.io)

- [Getting Started Guide](https://unified-xai.readthedocs.io/getting-started)
- [API Reference](https://unified-xai.readthedocs.io/api)
- [Tutorials](https://unified-xai.readthedocs.io/tutorials)
- [Method Descriptions](https://unified-xai.readthedocs.io/methods)
- [Best Practices](https://unified-xai.readthedocs.io/best-practices)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

```bash
# Setup development environment
git clone https://github.com/yourusername/unified-xai.git
cd unified-xai
pip install -e ".[dev]"
pre-commit install

# Run checks before committing
make lint
make test
make docs
```

## 📊 Benchmarks

Performance comparisons across different methods and frameworks:

| Method | PyTorch (ms) | TensorFlow (ms) | Accuracy |
|--------|-------------|-----------------|----------|
| Integrated Gradients | 45 | 52 | 0.94 |
| LIME | 890 | 920 | 0.89 |
| SHAP | 340 | 380 | 0.91 |
| Grad-CAM | 23 | 28 | 0.87 |

## 🎓 Citation

If you use Unified XAI in your research, please cite:

```bibtex
@software{unified_xai,
  title = {Unified XAI: A Production-Ready Explainable AI Library},
  author = {Satyam Singh},
  year = {2025},
  url = {https://github.com/SatyamSingh8306/unified-xai}
}
```

## 📝 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Thanks to all contributors and the open-source community
- Inspired by Captum, SHAP, LIME, and other XAI libraries
- Supported by [Your Organization]

## 📬 Contact

- **Issues**: [GitHub Issues](https://github.com/SatyamSingh8306/unified-xai/issues)
- **Discussions**: [GitHub Discussions](https://github.com/SatyamSingh8306/unified-xai/discussions)
- **Email**: satyamsingh7734@gmail.com
- **Twitter**: [@unified_xai](https://x.com/Satyam8306)

## 🗺️ Roadmap

- [ ] Support for Vision Transformers
- [ ] Additional evaluation metrics
- [ ] Model-specific explanations
- [ ] Distributed computing support
- [ ] AutoML integration
- [ ] Mobile deployment

---

<div align="center">
Made with ❤️ by the Satyam Singh
</div>