explainiverse 0.1.1a0__tar.gz → 0.2.0__tar.gz

explainiverse-0.2.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.1
+Name: explainiverse
+Version: 0.2.0
+Summary: Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more
+Home-page: https://github.com/jemsbhai/explainiverse
+License: MIT
+Keywords: xai,explainability,interpretability,machine-learning,lime,shap,anchors
+Author: Muntaser Syed
+Author-email: jemsbhai@gmail.com
+Requires-Python: >=3.10,<3.13
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+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: xgboost (>=1.7,<3.0)
+Project-URL: Repository, https://github.com/jemsbhai/explainiverse
+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.
+
+---
+
+## Features
+
+### 🎯 Comprehensive XAI Coverage
+
+**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))
+- **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))
+
+**Global Explainers** (model-level explanations):
+- **Permutation Importance** - Feature importance via performance degradation ([Breiman, 2001](https://link.springer.com/article/10.1023/A:1010933404324))
+- **Partial Dependence (PDP)** - Marginal feature effects ([Friedman, 2001](https://projecteuclid.org/euclid.aos/1013203451))
+- **ALE** - Accumulated Local Effects, unbiased for correlated features ([Apley & Zhu, 2020](https://academic.oup.com/jrsssb/article/82/4/1059/7056085))
+- **SAGE** - Shapley Additive Global importancE ([Covert et al., 2020](https://arxiv.org/abs/2004.00668))
+
+### 🔌 Extensible Plugin Registry
+- Register custom explainers with rich metadata
+- Filter by scope (local/global), model type, data type
+- Automatic recommendations based on use case
+
+### 📊 Evaluation Metrics
+- **AOPC** (Area Over Perturbation Curve)
+- **ROAR** (Remove And Retrain)
+- Multiple baseline options and curve generation
+
+### 🧪 Standardized Interface
+- Consistent `BaseExplainer` API
+- Unified `Explanation` output format
+- Model adapters for sklearn and more
+
+---
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install explainiverse
+```
+
+For development:
+
+```bash
+git clone https://github.com/jemsbhai/explainiverse.git
+cd explainiverse
+poetry install
+```
+
+---
+
+## Quick Start
+
+### Using the Registry (Recommended)
+
+```python
+from explainiverse import default_registry, SklearnAdapter
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.datasets import load_iris
+
+# Train a model
+iris = load_iris()
+model = RandomForestClassifier().fit(iris.data, iris.target)
+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']
+
+# Create and use an explainer
+explainer = default_registry.create(
+    "lime",
+    model=adapter,
+    training_data=iris.data,
+    feature_names=iris.feature_names,
+    class_names=iris.target_names.tolist()
+)
+explanation = explainer.explain(iris.data[0])
+print(explanation.explanation_data["feature_attributions"])
+```
+
+### Filter Explainers by Criteria
+
+```python
+# Find local explainers for tabular data
+local_tabular = default_registry.filter(scope="local", data_type="tabular")
+print(local_tabular)  # ['lime', 'shap', 'anchors', 'counterfactual']
+
+# Find global explainers
+global_explainers = default_registry.filter(scope="global")
+print(global_explainers)  # ['permutation_importance', 'partial_dependence', 'ale', 'sage']
+
+# Get recommendations
+recommendations = default_registry.recommend(
+    model_type="any",
+    data_type="tabular",
+    scope_preference="local"
+)
+```
+
+### Using Specific Explainers
+
+```python
+# Anchors - Rule-based explanations
+from explainiverse.explainers import AnchorsExplainer
+
+anchors = AnchorsExplainer(
+    model=adapter,
+    training_data=X_train,
+    feature_names=feature_names,
+    class_names=class_names
+)
+explanation = anchors.explain(instance)
+print(explanation.explanation_data["rules"])
+# ['petal length (cm) > 2.45', 'petal width (cm) <= 1.75']
+
+# Counterfactual - What-if explanations
+from explainiverse.explainers import CounterfactualExplainer
+
+cf = CounterfactualExplainer(
+    model=adapter,
+    training_data=X_train,
+    feature_names=feature_names
+)
+explanation = cf.explain(instance, num_counterfactuals=3)
+print(explanation.explanation_data["changes"])
+
+# SAGE - Global Shapley importance
+from explainiverse.explainers import SAGEExplainer
+
+sage = SAGEExplainer(
+    model=adapter,
+    X=X_train,
+    y=y_train,
+    feature_names=feature_names
+)
+explanation = sage.explain()
+print(explanation.explanation_data["feature_attributions"])
+```
+
+### Explanation Suite (Multi-Explainer Comparison)
+
+```python
+from explainiverse import ExplanationSuite
+
+suite = ExplanationSuite(
+    model=adapter,
+    explainer_configs=[
+        ("lime", {"training_data": X_train, "feature_names": feature_names, "class_names": class_names}),
+        ("shap", {"background_data": X_train[:50], "feature_names": feature_names, "class_names": class_names}),
+    ]
+)
+
+results = suite.run(instance)
+suite.compare()
+```
+
+---
+
+## Registering Custom Explainers
+
+```python
+from explainiverse import ExplainerRegistry, ExplainerMeta, BaseExplainer
+
+@default_registry.register_decorator(
+    name="my_explainer",
+    meta=ExplainerMeta(
+        scope="local",
+        model_types=["any"],
+        data_types=["tabular"],
+        description="My custom explainer",
+        paper_reference="Author et al., 2024"
+    )
+)
+class MyExplainer(BaseExplainer):
+    def explain(self, instance, **kwargs):
+        # Your implementation
+        return Explanation(...)
+```
+
+---
+
+## Running Tests
+
+```bash
+# Run all tests
+poetry run pytest
+
+# Run with coverage
+poetry run pytest --cov=explainiverse
+
+# Run specific test file
+poetry run pytest tests/test_new_explainers.py -v
+```
+
+---
+
+## Roadmap
+
+- [x] LIME, SHAP (KernelSHAP)
+- [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
+- [ ] Interactive visualization dashboard
+
+---
+
+## Citation
+
+If you use Explainiverse in your research, please cite:
+
+```bibtex
+@software{explainiverse2024,
+  title = {Explainiverse: A Unified Framework for Explainable AI},
+  author = {Syed, Muntaser},
+  year = {2024},
+  url = {https://github.com/jemsbhai/explainiverse}
+}
+```
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

explainiverse-0.2.0/README.md

@@ -0,0 +1,235 @@
+# 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.
+
+---
+
+## Features
+
+### 🎯 Comprehensive XAI Coverage
+
+**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))
+- **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))
+
+**Global Explainers** (model-level explanations):
+- **Permutation Importance** - Feature importance via performance degradation ([Breiman, 2001](https://link.springer.com/article/10.1023/A:1010933404324))
+- **Partial Dependence (PDP)** - Marginal feature effects ([Friedman, 2001](https://projecteuclid.org/euclid.aos/1013203451))
+- **ALE** - Accumulated Local Effects, unbiased for correlated features ([Apley & Zhu, 2020](https://academic.oup.com/jrsssb/article/82/4/1059/7056085))
+- **SAGE** - Shapley Additive Global importancE ([Covert et al., 2020](https://arxiv.org/abs/2004.00668))
+
+### 🔌 Extensible Plugin Registry
+- Register custom explainers with rich metadata
+- Filter by scope (local/global), model type, data type
+- Automatic recommendations based on use case
+
+### 📊 Evaluation Metrics
+- **AOPC** (Area Over Perturbation Curve)
+- **ROAR** (Remove And Retrain)
+- Multiple baseline options and curve generation
+
+### 🧪 Standardized Interface
+- Consistent `BaseExplainer` API
+- Unified `Explanation` output format
+- Model adapters for sklearn and more
+
+---
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install explainiverse
+```
+
+For development:
+
+```bash
+git clone https://github.com/jemsbhai/explainiverse.git
+cd explainiverse
+poetry install
+```
+
+---
+
+## Quick Start
+
+### Using the Registry (Recommended)
+
+```python
+from explainiverse import default_registry, SklearnAdapter
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.datasets import load_iris
+
+# Train a model
+iris = load_iris()
+model = RandomForestClassifier().fit(iris.data, iris.target)
+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']
+
+# Create and use an explainer
+explainer = default_registry.create(
+    "lime",
+    model=adapter,
+    training_data=iris.data,
+    feature_names=iris.feature_names,
+    class_names=iris.target_names.tolist()
+)
+explanation = explainer.explain(iris.data[0])
+print(explanation.explanation_data["feature_attributions"])
+```
+
+### Filter Explainers by Criteria
+
+```python
+# Find local explainers for tabular data
+local_tabular = default_registry.filter(scope="local", data_type="tabular")
+print(local_tabular)  # ['lime', 'shap', 'anchors', 'counterfactual']
+
+# Find global explainers
+global_explainers = default_registry.filter(scope="global")
+print(global_explainers)  # ['permutation_importance', 'partial_dependence', 'ale', 'sage']
+
+# Get recommendations
+recommendations = default_registry.recommend(
+    model_type="any",
+    data_type="tabular",
+    scope_preference="local"
+)
+```
+
+### Using Specific Explainers
+
+```python
+# Anchors - Rule-based explanations
+from explainiverse.explainers import AnchorsExplainer
+
+anchors = AnchorsExplainer(
+    model=adapter,
+    training_data=X_train,
+    feature_names=feature_names,
+    class_names=class_names
+)
+explanation = anchors.explain(instance)
+print(explanation.explanation_data["rules"])
+# ['petal length (cm) > 2.45', 'petal width (cm) <= 1.75']
+
+# Counterfactual - What-if explanations
+from explainiverse.explainers import CounterfactualExplainer
+
+cf = CounterfactualExplainer(
+    model=adapter,
+    training_data=X_train,
+    feature_names=feature_names
+)
+explanation = cf.explain(instance, num_counterfactuals=3)
+print(explanation.explanation_data["changes"])
+
+# SAGE - Global Shapley importance
+from explainiverse.explainers import SAGEExplainer
+
+sage = SAGEExplainer(
+    model=adapter,
+    X=X_train,
+    y=y_train,
+    feature_names=feature_names
+)
+explanation = sage.explain()
+print(explanation.explanation_data["feature_attributions"])
+```
+
+### Explanation Suite (Multi-Explainer Comparison)
+
+```python
+from explainiverse import ExplanationSuite
+
+suite = ExplanationSuite(
+    model=adapter,
+    explainer_configs=[
+        ("lime", {"training_data": X_train, "feature_names": feature_names, "class_names": class_names}),
+        ("shap", {"background_data": X_train[:50], "feature_names": feature_names, "class_names": class_names}),
+    ]
+)
+
+results = suite.run(instance)
+suite.compare()
+```
+
+---
+
+## Registering Custom Explainers
+
+```python
+from explainiverse import ExplainerRegistry, ExplainerMeta, BaseExplainer
+
+@default_registry.register_decorator(
+    name="my_explainer",
+    meta=ExplainerMeta(
+        scope="local",
+        model_types=["any"],
+        data_types=["tabular"],
+        description="My custom explainer",
+        paper_reference="Author et al., 2024"
+    )
+)
+class MyExplainer(BaseExplainer):
+    def explain(self, instance, **kwargs):
+        # Your implementation
+        return Explanation(...)
+```
+
+---
+
+## Running Tests
+
+```bash
+# Run all tests
+poetry run pytest
+
+# Run with coverage
+poetry run pytest --cov=explainiverse
+
+# Run specific test file
+poetry run pytest tests/test_new_explainers.py -v
+```
+
+---
+
+## Roadmap
+
+- [x] LIME, SHAP (KernelSHAP)
+- [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
+- [ ] Interactive visualization dashboard
+
+---
+
+## Citation
+
+If you use Explainiverse in your research, please cite:
+
+```bibtex
+@software{explainiverse2024,
+  title = {Explainiverse: A Unified Framework for Explainable AI},
+  author = {Syed, Muntaser},
+  year = {2024},
+  url = {https://github.com/jemsbhai/explainiverse}
+}
+```
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

explainiverse-0.2.0/pyproject.toml

@@ -0,0 +1,64 @@
+[tool.poetry]
+name = "explainiverse"
+version = "0.2.0"
+description = "Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more"
+authors = ["Muntaser Syed <jemsbhai@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/jemsbhai/explainiverse"
+homepage = "https://github.com/jemsbhai/explainiverse"
+packages = [{ include = "explainiverse", from = "src" }]
+keywords = ["xai", "explainability", "interpretability", "machine-learning", "lime", "shap", "anchors"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.13"
+numpy = ">=1.24,<2.0"
+lime = "^0.2.0.1"
+scikit-learn = ">=1.1,<1.6"
+shap = "^0.48.0"
+scipy = ">=1.10,<2.0"
+xgboost = ">=1.7,<3.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-cov = "^4.1"
+black = "^24.0"
+isort = "^5.13"
+mypy = "^1.8"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::FutureWarning",
+]
+
+[tool.black]
+line-length = 100
+target-version = ['py310', 'py311', 'py312']
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[project.urls]
+"Bug Tracker" = "https://github.com/jemsbhai/explainiverse/issues"
+"Documentation" = "https://github.com/jemsbhai/explainiverse#readme"

explainiverse-0.2.0/src/explainiverse/__init__.py

@@ -0,0 +1,45 @@
+# src/explainiverse/__init__.py
+"""
+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.
+
+Quick Start:
+    from explainiverse import default_registry
+    
+    # List available explainers
+    print(default_registry.list_explainers())
+    
+    # Create an explainer
+    explainer = default_registry.create("lime", model=adapter, training_data=X, ...)
+    explanation = explainer.explain(instance)
+"""
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+from explainiverse.core.registry import (
+    ExplainerRegistry,
+    ExplainerMeta,
+    default_registry,
+    get_default_registry,
+)
+from explainiverse.adapters.sklearn_adapter import SklearnAdapter
+from explainiverse.engine.suite import ExplanationSuite
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Core
+    "BaseExplainer",
+    "Explanation",
+    # Registry
+    "ExplainerRegistry",
+    "ExplainerMeta",
+    "default_registry",
+    "get_default_registry",
+    # Adapters
+    "SklearnAdapter",
+    # Engine
+    "ExplanationSuite",
+]

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

@@ -0,0 +1,9 @@
+# src/explainiverse/adapters/__init__.py
+"""
+Model adapters - wrappers that provide a consistent interface for different ML frameworks.
+"""
+
+from explainiverse.adapters.base_adapter import BaseModelAdapter
+from explainiverse.adapters.sklearn_adapter import SklearnAdapter
+
+__all__ = ["BaseModelAdapter", "SklearnAdapter"]

{explainiverse-0.1.1a0 → explainiverse-0.2.0}/src/explainiverse/adapters/base_adapter.py

@@ -1,25 +1,25 @@
-# src/explainiverse/adapters/base_adapter.py
-
-from abc import ABC, abstractmethod
-
-class BaseModelAdapter(ABC):
-    """
-    Abstract base class for all model adapters.
-    """
-
-    def __init__(self, model, feature_names=None):
-        self.model = model
-        self.feature_names = feature_names
-
-    @abstractmethod
-    def predict(self, data):
-        """
-        Returns prediction probabilities or outputs in a standard format.
-
-        Args:
-            data: Input data (single instance or batch).
-
-        Returns:
-            List or NumPy array of prediction scores.
-        """
-        pass
+# src/explainiverse/adapters/base_adapter.py
+
+from abc import ABC, abstractmethod
+
+class BaseModelAdapter(ABC):
+    """
+    Abstract base class for all model adapters.
+    """
+
+    def __init__(self, model, feature_names=None):
+        self.model = model
+        self.feature_names = feature_names
+
+    @abstractmethod
+    def predict(self, data):
+        """
+        Returns prediction probabilities or outputs in a standard format.
+
+        Args:
+            data: Input data (single instance or batch).
+
+        Returns:
+            List or NumPy array of prediction scores.
+        """
+        pass