explainiverse 0.2.1__tar.gz → 0.2.3__tar.gz

{explainiverse-0.2.1 → explainiverse-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.2.1
+Version: 0.2.3
 Summary: Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more
 Home-page: https://github.com/jemsbhai/explainiverse
 License: MIT
@@ -17,11 +17,13 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Provides-Extra: torch
 Requires-Dist: lime (>=0.2.0.1,<0.3.0.0)
 Requires-Dist: numpy (>=1.24,<2.0)
 Requires-Dist: scikit-learn (>=1.1,<1.6)
 Requires-Dist: scipy (>=1.10,<2.0)
 Requires-Dist: shap (>=0.48.0,<0.49.0)
+Requires-Dist: torch (>=2.0) ; extra == "torch"
 Requires-Dist: xgboost (>=1.7,<3.0)
 Project-URL: Repository, https://github.com/jemsbhai/explainiverse
 Description-Content-Type: text/markdown
@@ -29,7 +31,7 @@ Description-Content-Type: text/markdown
 # Explainiverse
 
 **Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI).  
-It provides a standardized interface for model-agnostic explainability with 8 state-of-the-art XAI methods, evaluation metrics, and a plugin registry for easy extensibility.
+It provides a standardized interface for model-agnostic explainability with 10 state-of-the-art XAI methods, evaluation metrics, and a plugin registry for easy extensibility.
 
 ---
 
@@ -40,6 +42,8 @@ It provides a standardized interface for model-agnostic explainability with 8 st
 **Local Explainers** (instance-level explanations):
 - **LIME** - Local Interpretable Model-agnostic Explanations ([Ribeiro et al., 2016](https://arxiv.org/abs/1602.04938))
 - **SHAP** - SHapley Additive exPlanations via KernelSHAP ([Lundberg & Lee, 2017](https://arxiv.org/abs/1705.07874))
+- **TreeSHAP** - Exact SHAP values for tree models, 10x+ faster ([Lundberg et al., 2018](https://arxiv.org/abs/1802.03888))
+- **Integrated Gradients** - Axiomatic attributions for neural networks ([Sundararajan et al., 2017](https://arxiv.org/abs/1703.01365))
 - **Anchors** - High-precision rule-based explanations ([Ribeiro et al., 2018](https://ojs.aaai.org/index.php/AAAI/article/view/11491))
 - **Counterfactual** - DiCE-style diverse counterfactual explanations ([Mothilal et al., 2020](https://arxiv.org/abs/1905.07697))
 
@@ -62,7 +66,7 @@ It provides a standardized interface for model-agnostic explainability with 8 st
 ### 🧪 Standardized Interface
 - Consistent `BaseExplainer` API
 - Unified `Explanation` output format
-- Model adapters for sklearn and more
+- Model adapters for sklearn and PyTorch
 
 ---
 
@@ -74,6 +78,12 @@ From PyPI:
 pip install explainiverse
 ```
 
+With PyTorch support (for neural network explanations):
+
+```bash
+pip install explainiverse[torch]
+```
+
 For development:
 
 ```bash
@@ -100,7 +110,7 @@ adapter = SklearnAdapter(model, class_names=iris.target_names.tolist())
 
 # List available explainers
 print(default_registry.list_explainers())
-# ['lime', 'shap', 'anchors', 'counterfactual', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
+# ['lime', 'shap', 'treeshap', 'integrated_gradients', 'anchors', 'counterfactual', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
 
 # Create and use an explainer
 explainer = default_registry.create(
@@ -119,11 +129,11 @@ print(explanation.explanation_data["feature_attributions"])
 ```python
 # Find local explainers for tabular data
 local_tabular = default_registry.filter(scope="local", data_type="tabular")
-print(local_tabular)  # ['lime', 'shap', 'anchors', 'counterfactual']
+print(local_tabular)  # ['lime', 'shap', 'treeshap', 'integrated_gradients', 'anchors', 'counterfactual']
 
-# Find global explainers
-global_explainers = default_registry.filter(scope="global")
-print(global_explainers)  # ['permutation_importance', 'partial_dependence', 'ale', 'sage']
+# Find explainers optimized for tree models
+tree_explainers = default_registry.filter(model_type="tree")
+print(tree_explainers)  # ['treeshap']
 
 # Get recommendations
 recommendations = default_registry.recommend(
@@ -133,6 +143,90 @@ recommendations = default_registry.recommend(
 )
 ```
 
+### TreeSHAP for Tree Models (10x+ Faster)
+
+```python
+from explainiverse.explainers import TreeShapExplainer
+from sklearn.ensemble import RandomForestClassifier
+
+# Train a tree-based model
+model = RandomForestClassifier(n_estimators=100).fit(X_train, y_train)
+
+# TreeSHAP works directly with the model (no adapter needed)
+explainer = TreeShapExplainer(
+    model=model,
+    feature_names=feature_names,
+    class_names=class_names
+)
+
+# Single instance explanation
+explanation = explainer.explain(X_test[0])
+print(explanation.explanation_data["feature_attributions"])
+
+# Batch explanations (efficient)
+explanations = explainer.explain_batch(X_test[:10])
+
+# Feature interactions
+interactions = explainer.explain_interactions(X_test[0])
+print(interactions.explanation_data["interaction_matrix"])
+```
+
+### PyTorch Adapter for Neural Networks
+
+```python
+from explainiverse import PyTorchAdapter
+import torch.nn as nn
+
+# Define a PyTorch model
+model = nn.Sequential(
+    nn.Linear(10, 64),
+    nn.ReLU(),
+    nn.Linear(64, 3)
+)
+
+# Wrap with adapter
+adapter = PyTorchAdapter(
+    model,
+    task="classification",
+    class_names=["cat", "dog", "bird"]
+)
+
+# Use with any explainer
+predictions = adapter.predict(X)  # Returns numpy array
+
+# Get gradients for attribution methods
+predictions, gradients = adapter.predict_with_gradients(X)
+
+# Access intermediate layers
+activations = adapter.get_layer_output(X, layer_name="0")
+```
+
+### Integrated Gradients for Neural Networks
+
+```python
+from explainiverse.explainers import IntegratedGradientsExplainer
+from explainiverse import PyTorchAdapter
+
+# Wrap your PyTorch model
+adapter = PyTorchAdapter(model, task="classification", class_names=class_names)
+
+# Create IG explainer
+explainer = IntegratedGradientsExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    n_steps=50  # More steps = more accurate
+)
+
+# Explain a prediction
+explanation = explainer.explain(X_test[0])
+print(explanation.explanation_data["feature_attributions"])
+
+# Check convergence (sum of attributions ≈ F(x) - F(baseline))
+explanation = explainer.explain(X_test[0], return_convergence_delta=True)
+print(f"Convergence delta: {explanation.explanation_data['convergence_delta']}")
+```
+
 ### Using Specific Explainers
 
 ```python
@@ -233,12 +327,14 @@ poetry run pytest tests/test_new_explainers.py -v
 ## Roadmap
 
 - [x] LIME, SHAP (KernelSHAP)
+- [x] TreeSHAP (optimized for tree models) ✅
 - [x] Anchors, Counterfactuals
 - [x] Permutation Importance, PDP, ALE, SAGE
 - [x] Explainer Registry with filtering
-- [ ] TreeSHAP (optimized for tree models)
-- [ ] Integrated Gradients (gradient-based for neural nets)
-- [ ] PyTorch/TensorFlow adapters
+- [x] PyTorch Adapter ✅
+- [x] Integrated Gradients ✅ NEW
+- [ ] GradCAM for CNNs
+- [ ] TensorFlow adapter
 - [ ] Interactive visualization dashboard
 
 ---

{explainiverse-0.2.1 → explainiverse-0.2.3}/README.md

@@ -1,7 +1,7 @@
 # Explainiverse
 
 **Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI).  
-It provides a standardized interface for model-agnostic explainability with 8 state-of-the-art XAI methods, evaluation metrics, and a plugin registry for easy extensibility.
+It provides a standardized interface for model-agnostic explainability with 10 state-of-the-art XAI methods, evaluation metrics, and a plugin registry for easy extensibility.
 
 ---
 
@@ -12,6 +12,8 @@ It provides a standardized interface for model-agnostic explainability with 8 st
 **Local Explainers** (instance-level explanations):
 - **LIME** - Local Interpretable Model-agnostic Explanations ([Ribeiro et al., 2016](https://arxiv.org/abs/1602.04938))
 - **SHAP** - SHapley Additive exPlanations via KernelSHAP ([Lundberg & Lee, 2017](https://arxiv.org/abs/1705.07874))
+- **TreeSHAP** - Exact SHAP values for tree models, 10x+ faster ([Lundberg et al., 2018](https://arxiv.org/abs/1802.03888))
+- **Integrated Gradients** - Axiomatic attributions for neural networks ([Sundararajan et al., 2017](https://arxiv.org/abs/1703.01365))
 - **Anchors** - High-precision rule-based explanations ([Ribeiro et al., 2018](https://ojs.aaai.org/index.php/AAAI/article/view/11491))
 - **Counterfactual** - DiCE-style diverse counterfactual explanations ([Mothilal et al., 2020](https://arxiv.org/abs/1905.07697))
 
@@ -34,7 +36,7 @@ It provides a standardized interface for model-agnostic explainability with 8 st
 ### 🧪 Standardized Interface
 - Consistent `BaseExplainer` API
 - Unified `Explanation` output format
-- Model adapters for sklearn and more
+- Model adapters for sklearn and PyTorch
 
 ---
 
@@ -46,6 +48,12 @@ From PyPI:
 pip install explainiverse
 ```
 
+With PyTorch support (for neural network explanations):
+
+```bash
+pip install explainiverse[torch]
+```
+
 For development:
 
 ```bash
@@ -72,7 +80,7 @@ adapter = SklearnAdapter(model, class_names=iris.target_names.tolist())
 
 # List available explainers
 print(default_registry.list_explainers())
-# ['lime', 'shap', 'anchors', 'counterfactual', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
+# ['lime', 'shap', 'treeshap', 'integrated_gradients', 'anchors', 'counterfactual', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
 
 # Create and use an explainer
 explainer = default_registry.create(
@@ -91,11 +99,11 @@ print(explanation.explanation_data["feature_attributions"])
 ```python
 # Find local explainers for tabular data
 local_tabular = default_registry.filter(scope="local", data_type="tabular")
-print(local_tabular)  # ['lime', 'shap', 'anchors', 'counterfactual']
+print(local_tabular)  # ['lime', 'shap', 'treeshap', 'integrated_gradients', 'anchors', 'counterfactual']
 
-# Find global explainers
-global_explainers = default_registry.filter(scope="global")
-print(global_explainers)  # ['permutation_importance', 'partial_dependence', 'ale', 'sage']
+# Find explainers optimized for tree models
+tree_explainers = default_registry.filter(model_type="tree")
+print(tree_explainers)  # ['treeshap']
 
 # Get recommendations
 recommendations = default_registry.recommend(
@@ -105,6 +113,90 @@ recommendations = default_registry.recommend(
 )
 ```
 
+### TreeSHAP for Tree Models (10x+ Faster)
+
+```python
+from explainiverse.explainers import TreeShapExplainer
+from sklearn.ensemble import RandomForestClassifier
+
+# Train a tree-based model
+model = RandomForestClassifier(n_estimators=100).fit(X_train, y_train)
+
+# TreeSHAP works directly with the model (no adapter needed)
+explainer = TreeShapExplainer(
+    model=model,
+    feature_names=feature_names,
+    class_names=class_names
+)
+
+# Single instance explanation
+explanation = explainer.explain(X_test[0])
+print(explanation.explanation_data["feature_attributions"])
+
+# Batch explanations (efficient)
+explanations = explainer.explain_batch(X_test[:10])
+
+# Feature interactions
+interactions = explainer.explain_interactions(X_test[0])
+print(interactions.explanation_data["interaction_matrix"])
+```
+
+### PyTorch Adapter for Neural Networks
+
+```python
+from explainiverse import PyTorchAdapter
+import torch.nn as nn
+
+# Define a PyTorch model
+model = nn.Sequential(
+    nn.Linear(10, 64),
+    nn.ReLU(),
+    nn.Linear(64, 3)
+)
+
+# Wrap with adapter
+adapter = PyTorchAdapter(
+    model,
+    task="classification",
+    class_names=["cat", "dog", "bird"]
+)
+
+# Use with any explainer
+predictions = adapter.predict(X)  # Returns numpy array
+
+# Get gradients for attribution methods
+predictions, gradients = adapter.predict_with_gradients(X)
+
+# Access intermediate layers
+activations = adapter.get_layer_output(X, layer_name="0")
+```
+
+### Integrated Gradients for Neural Networks
+
+```python
+from explainiverse.explainers import IntegratedGradientsExplainer
+from explainiverse import PyTorchAdapter
+
+# Wrap your PyTorch model
+adapter = PyTorchAdapter(model, task="classification", class_names=class_names)
+
+# Create IG explainer
+explainer = IntegratedGradientsExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    n_steps=50  # More steps = more accurate
+)
+
+# Explain a prediction
+explanation = explainer.explain(X_test[0])
+print(explanation.explanation_data["feature_attributions"])
+
+# Check convergence (sum of attributions ≈ F(x) - F(baseline))
+explanation = explainer.explain(X_test[0], return_convergence_delta=True)
+print(f"Convergence delta: {explanation.explanation_data['convergence_delta']}")
+```
+
 ### Using Specific Explainers
 
 ```python
@@ -205,12 +297,14 @@ poetry run pytest tests/test_new_explainers.py -v
 ## Roadmap
 
 - [x] LIME, SHAP (KernelSHAP)
+- [x] TreeSHAP (optimized for tree models) ✅
 - [x] Anchors, Counterfactuals
 - [x] Permutation Importance, PDP, ALE, SAGE
 - [x] Explainer Registry with filtering
-- [ ] TreeSHAP (optimized for tree models)
-- [ ] Integrated Gradients (gradient-based for neural nets)
-- [ ] PyTorch/TensorFlow adapters
+- [x] PyTorch Adapter ✅
+- [x] Integrated Gradients ✅ NEW
+- [ ] GradCAM for CNNs
+- [ ] TensorFlow adapter
 - [ ] Interactive visualization dashboard
 
 ---

{explainiverse-0.2.1 → explainiverse-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "explainiverse"
-version = "0.2.1"
+version = "0.2.3"
 description = "Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more"
 authors = ["Muntaser Syed <jemsbhai@gmail.com>"]
 license = "MIT"
@@ -29,6 +29,10 @@ scikit-learn = ">=1.1,<1.6"
 shap = "^0.48.0"
 scipy = ">=1.10,<2.0"
 xgboost = ">=1.7,<3.0"
+torch = { version = ">=2.0", optional = true }
+
+[tool.poetry.extras]
+torch = ["torch"]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0"

{explainiverse-0.2.1 → explainiverse-0.2.3}/src/explainiverse/__init__.py

@@ -2,8 +2,9 @@
 """
 Explainiverse - A unified, extensible explainability framework.
 
-Supports multiple XAI methods including LIME, SHAP, Anchors, Counterfactuals,
-Permutation Importance, PDP, ALE, and SAGE through a consistent interface.
+Supports multiple XAI methods including LIME, SHAP, TreeSHAP, Anchors, 
+Counterfactuals, Permutation Importance, PDP, ALE, and SAGE through a 
+consistent interface.
 
 Quick Start:
     from explainiverse import default_registry
@@ -14,6 +15,10 @@ Quick Start:
     # Create an explainer
     explainer = default_registry.create("lime", model=adapter, training_data=X, ...)
     explanation = explainer.explain(instance)
+    
+For PyTorch models:
+    from explainiverse import PyTorchAdapter  # Requires torch
+    adapter = PyTorchAdapter(model, task="classification")
 """
 
 from explainiverse.core.explainer import BaseExplainer
@@ -25,9 +30,10 @@ from explainiverse.core.registry import (
     get_default_registry,
 )
 from explainiverse.adapters.sklearn_adapter import SklearnAdapter
+from explainiverse.adapters import TORCH_AVAILABLE
 from explainiverse.engine.suite import ExplanationSuite
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 __all__ = [
     # Core
@@ -40,6 +46,12 @@ __all__ = [
     "get_default_registry",
     # Adapters
     "SklearnAdapter",
+    "TORCH_AVAILABLE",
     # Engine
     "ExplanationSuite",
 ]
+
+# Conditionally export PyTorchAdapter if torch is available
+if TORCH_AVAILABLE:
+    from explainiverse.adapters import PyTorchAdapter
+    __all__.append("PyTorchAdapter")

explainiverse-0.2.3/src/explainiverse/adapters/__init__.py

@@ -0,0 +1,19 @@
+# src/explainiverse/adapters/__init__.py
+"""
+Model adapters - wrappers that provide a consistent interface for different ML frameworks.
+
+Available adapters:
+- SklearnAdapter: For scikit-learn models (always available)
+- PyTorchAdapter: For PyTorch nn.Module models (requires torch)
+"""
+
+from explainiverse.adapters.base_adapter import BaseModelAdapter
+from explainiverse.adapters.sklearn_adapter import SklearnAdapter
+
+# Conditionally import PyTorchAdapter if torch is available
+try:
+    from explainiverse.adapters.pytorch_adapter import PyTorchAdapter, TORCH_AVAILABLE
+    __all__ = ["BaseModelAdapter", "SklearnAdapter", "PyTorchAdapter", "TORCH_AVAILABLE"]
+except ImportError:
+    TORCH_AVAILABLE = False
+    __all__ = ["BaseModelAdapter", "SklearnAdapter", "TORCH_AVAILABLE"]