explainiverse 0.1.0a1__tar.gz

explainiverse-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Muntaser Syed
+
+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.

explainiverse-0.1.0a1/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.1
+Name: explainiverse
+Version: 0.1.0a1
+Summary: Unified, extensible explainability framework supporting LIME, SHAP, and custom adapters
+Home-page: https://github.com/jemsbhai/explainiverse
+License: MIT
+Author: Muntaser Syed
+Author-email: jemsbhai@gmail.com
+Requires-Python: >=3.10,<3.13
+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
+Requires-Dist: lime (>=0.2.0.1,<0.3.0.0)
+Requires-Dist: numpy (==1.24.4)
+Requires-Dist: scikit-learn (>=1.1,<1.4)
+Requires-Dist: shap (>=0.48.0,<0.49.0)
+Project-URL: Repository, https://github.com/jemsbhai/explainiverse
+Description-Content-Type: text/markdown
+
+# Explainiverse
+
+Explainiverse is a unified, extensible, and testable Python framework for explainable AI (XAI).  
+It provides a consistent API and support for post-hoc explainers like LIME and SHAP, model adapters, and rigorous evaluation strategies.
+
+---
+
+## Features
+
+- Standardized Explainer interface (`BaseExplainer`)
+- Support for classification, regression, and multi-class models
+- Integrated explainers:
+  - LIME (Local surrogate models)
+  - SHAP (KernelExplainer with per-class and global support)
+- Adapter layer for scikit-learn models
+- Explanation object with structured output and future extensibility for `.plot()`
+- Full unit test suite covering classification, regression, global/cohort SHAP, and adapter behavior
+
+---
+
+## Installation
+
+This package will soon be available on PyPI.
+
+For development use:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/explainiverse.git
+cd explainiverse
+poetry install
+```
+
+---
+
+## Running Tests
+
+All tests can be run using:
+
+```bash
+poetry run python tests/test_all.py
+```
+
+For individual component testing:
+
+```bash
+poetry run python tests/test_shap_explainer.py
+poetry run python tests/test_lime_explainer.py
+```
+
+---
+
+## Documentation
+
+Documentation is currently in development.  
+Until then, test files (especially `test_shap_explainer.py`) demonstrate usage and structure.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+

explainiverse-0.1.0a1/README.md

@@ -0,0 +1,61 @@
+# Explainiverse
+
+Explainiverse is a unified, extensible, and testable Python framework for explainable AI (XAI).  
+It provides a consistent API and support for post-hoc explainers like LIME and SHAP, model adapters, and rigorous evaluation strategies.
+
+---
+
+## Features
+
+- Standardized Explainer interface (`BaseExplainer`)
+- Support for classification, regression, and multi-class models
+- Integrated explainers:
+  - LIME (Local surrogate models)
+  - SHAP (KernelExplainer with per-class and global support)
+- Adapter layer for scikit-learn models
+- Explanation object with structured output and future extensibility for `.plot()`
+- Full unit test suite covering classification, regression, global/cohort SHAP, and adapter behavior
+
+---
+
+## Installation
+
+This package will soon be available on PyPI.
+
+For development use:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/explainiverse.git
+cd explainiverse
+poetry install
+```
+
+---
+
+## Running Tests
+
+All tests can be run using:
+
+```bash
+poetry run python tests/test_all.py
+```
+
+For individual component testing:
+
+```bash
+poetry run python tests/test_shap_explainer.py
+poetry run python tests/test_lime_explainer.py
+```
+
+---
+
+## Documentation
+
+Documentation is currently in development.  
+Until then, test files (especially `test_shap_explainer.py`) demonstrate usage and structure.
+
+---
+
+## License
+
+This project is licensed under the MIT License.

explainiverse-0.1.0a1/pyproject.toml

@@ -0,0 +1,26 @@
+[tool.poetry]
+name = "explainiverse"
+version = "0.1.0a1"
+description = "Unified, extensible explainability framework supporting LIME, SHAP, and custom adapters"
+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" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.13"
+numpy = "1.24.4"
+lime = "^0.2.0.1"
+scikit-learn = ">=1.1,<1.4"
+shap = "^0.48.0"
+
+
+[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.1.0a1/src/explainiverse/__init__.py

@@ -0,0 +1 @@
+# Explainiverse Init

explainiverse-0.1.0a1/src/explainiverse/adapters/base_adapter.py

@@ -0,0 +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

explainiverse-0.1.0a1/src/explainiverse/adapters/sklearn_adapter.py

@@ -0,0 +1,32 @@
+# src/explainiverse/adapters/sklearn_adapter.py
+
+import numpy as np
+from .base_adapter import BaseModelAdapter
+
+class SklearnAdapter(BaseModelAdapter):
+    """
+    Adapter for Scikit-learn classifiers.
+    """
+
+    def __init__(self, model, feature_names=None, class_names=None):
+        super().__init__(model, feature_names)
+        self.class_names = class_names
+
+    def predict(self, data: np.ndarray) -> np.ndarray:
+        """
+        Returns prediction probabilities.
+
+        Args:
+            data: A 2D numpy array of inputs.
+
+        Returns:
+            Array of shape (n_samples, n_classes).
+        """
+        if hasattr(self.model, "predict_proba"):
+            return self.model.predict_proba(data)
+        else:
+            preds = self.model.predict(data)
+            if self.class_names:
+                return np.eye(len(self.class_names))[preds]
+            else:
+                return preds.reshape(-1, 1)  # regression: raw outputs

explainiverse-0.1.0a1/src/explainiverse/core/explainer.py

@@ -0,0 +1,31 @@
+# src/explainiverse/core/explainer.py
+
+from abc import ABC, abstractmethod
+
+class BaseExplainer(ABC):
+    """
+    Abstract base class for all explainers in Explainiverse.
+    """
+
+    def __init__(self, model):
+        """
+        Initialize with a model adapter or raw model.
+
+        Args:
+            model: A wrapped ML model with a standardized `predict` method.
+        """
+        self.model = model
+
+    @abstractmethod
+    def explain(self, instance, **kwargs):
+        """
+        Generate an explanation for a single input instance.
+
+        Args:
+            instance: The input to explain (e.g., feature vector, image, text).
+            **kwargs: Optional method-specific parameters.
+
+        Returns:
+            An Explanation object or dict.
+        """
+        pass

explainiverse-0.1.0a1/src/explainiverse/core/explanation.py

@@ -0,0 +1,24 @@
+# src/explainiverse/core/explanation.py
+
+class Explanation:
+    """
+    Unified container for explanation results.
+    """
+
+    def __init__(self, explainer_name: str, target_class: str, explanation_data: dict):
+        self.explainer_name = explainer_name
+        self.target_class = target_class
+        self.explanation_data = explanation_data  # e.g., {'feature_attributions': {...}}
+
+    def __repr__(self):
+        return (f"Explanation(explainer='{self.explainer_name}', "
+                f"target='{self.target_class}', "
+                f"keys={list(self.explanation_data.keys())})")
+
+    def plot(self, type='bar'):
+        """
+        Visualizes the explanation.
+        This will later integrate with a proper visualization backend.
+        """
+        print(f"[plot: {type}] Plotting explanation for {self.target_class} "
+              f"from {self.explainer_name}.")

explainiverse-0.1.0a1/src/explainiverse/explainers/attribution/lime_wrapper.py

@@ -0,0 +1,63 @@
+# src/explainiverse/explainers/attribution/lime_wrapper.py
+
+import numpy as np
+from lime.lime_tabular import LimeTabularExplainer
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class LimeExplainer(BaseExplainer):
+    """
+    Wrapper for LIME that conforms to the BaseExplainer API.
+    """
+
+    def __init__(self, model, training_data, feature_names, class_names, mode="classification"):
+        """
+        Args:
+            model: A model adapter (implements .predict()).
+            training_data: The data used to initialize LIME (2D np.ndarray).
+            feature_names: List of feature names.
+            class_names: List of class names.
+            mode: 'classification' or 'regression'.
+        """
+        super().__init__(model)
+        self.feature_names = feature_names
+        self.class_names = class_names
+        self.mode = mode
+
+        self.explainer = LimeTabularExplainer(
+            training_data=training_data,
+            feature_names=feature_names,
+            class_names=class_names,
+            mode=mode
+        )
+
+    def explain(self, instance, num_features=5, top_labels=1):
+        """
+        Generate a local explanation for the given instance.
+
+        Args:
+            instance: 1D numpy array (single row)
+            num_features: Number of top features to include
+            top_labels: Number of top labels to explain
+
+        Returns:
+            Explanation object
+        """
+        lime_exp = self.explainer.explain_instance(
+            data_row=instance,
+            predict_fn=self.model.predict,
+            num_features=num_features,
+            top_labels=top_labels
+        )
+
+        label_index = lime_exp.top_labels[0]
+        label_name = self.class_names[label_index]
+        attributions = dict(lime_exp.as_list(label=label_index))
+
+        return Explanation(
+            explainer_name="LIME",
+            target_class=label_name,
+            explanation_data={"feature_attributions": attributions}
+        )

explainiverse-0.1.0a1/src/explainiverse/explainers/attribution/shap_wrapper.py

@@ -0,0 +1,66 @@
+# src/explainiverse/explainers/attribution/shap_wrapper.py
+
+import shap
+import numpy as np
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class ShapExplainer(BaseExplainer):
+    """
+    SHAP explainer (KernelSHAP-based) for model-agnostic explanations.
+    """
+
+    def __init__(self, model, background_data, feature_names, class_names):
+        """
+        Args:
+            model: A model adapter with a .predict method.
+            background_data: A 2D numpy array used as SHAP background distribution.
+            feature_names: List of feature names.
+            class_names: List of class labels.
+        """
+        super().__init__(model)
+        self.feature_names = feature_names
+        self.class_names = class_names
+        self.explainer = shap.KernelExplainer(model.predict, background_data)
+
+
+    def explain(self, instance, top_labels=1):
+        """
+        Generate SHAP explanation for a single instance.
+
+        Args:
+            instance: 1D numpy array of input features.
+            top_labels: Number of top classes to explain (default: 1)
+
+        Returns:
+            Explanation object
+        """
+        instance = np.array(instance).reshape(1, -1)  # Ensure 2D
+        shap_values = self.explainer.shap_values(instance)
+
+        if isinstance(shap_values, list):
+            # Multi-class: list of arrays, one per class
+            predicted_probs = self.model.predict(instance)[0]
+            top_indices = np.argsort(predicted_probs)[-top_labels:][::-1]
+            label_index = top_indices[0]
+            label_name = self.class_names[label_index]
+            class_shap = shap_values[label_index][0]
+        else:
+            # Single-class (regression or binary classification)
+            label_index = 0
+            label_name = self.class_names[0] if self.class_names else "class_0"
+            class_shap = shap_values[0]
+
+            flat_shap = np.array(class_shap).flatten()
+            attributions = {
+                fname: float(flat_shap[i])
+                for i, fname in enumerate(self.feature_names)
+            }
+
+        return Explanation(
+            explainer_name="SHAP",
+            target_class=label_name,
+            explanation_data={"feature_attributions": attributions}
+        )