explainiverse 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

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.0"
+__version__ = "0.2.2"
 
 __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/adapters/__init__.py

@@ -1,9 +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
 
-__all__ = ["BaseModelAdapter", "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"]

explainiverse/adapters/pytorch_adapter.py

@@ -0,0 +1,396 @@
+# src/explainiverse/adapters/pytorch_adapter.py
+"""
+PyTorch Model Adapter for Explainiverse.
+
+Provides a unified interface for PyTorch neural networks, enabling
+compatibility with all explainers in the framework.
+
+Example:
+    import torch.nn as nn
+    from explainiverse.adapters import PyTorchAdapter
+    
+    model = nn.Sequential(
+        nn.Linear(10, 64),
+        nn.ReLU(),
+        nn.Linear(64, 3)
+    )
+    
+    adapter = PyTorchAdapter(
+        model,
+        task="classification",
+        class_names=["cat", "dog", "bird"]
+    )
+    
+    probs = adapter.predict(X)  # Returns numpy array
+"""
+
+import numpy as np
+from typing import List, Optional, Union, Callable
+
+from .base_adapter import BaseModelAdapter
+
+# Check if PyTorch is available
+try:
+    import torch
+    import torch.nn as nn
+    TORCH_AVAILABLE = True
+except ImportError:
+    TORCH_AVAILABLE = False
+    torch = None
+    nn = None
+
+
+def _check_torch_available():
+    """Raise ImportError if PyTorch is not installed."""
+    if not TORCH_AVAILABLE:
+        raise ImportError(
+            "PyTorch is required for PyTorchAdapter. "
+            "Install it with: pip install torch"
+        )
+
+
+class PyTorchAdapter(BaseModelAdapter):
+    """
+    Adapter for PyTorch neural network models.
+    
+    Wraps a PyTorch nn.Module to provide a consistent interface for
+    explainability methods. Handles device management, tensor/numpy
+    conversions, and supports both classification and regression tasks.
+    
+    Attributes:
+        model: The PyTorch model (nn.Module)
+        task: "classification" or "regression"
+        device: torch.device for computation
+        class_names: List of class names (for classification)
+        feature_names: List of feature names
+        output_activation: Optional activation function for outputs
+    
+    Example:
+        >>> model = MyNeuralNetwork()
+        >>> adapter = PyTorchAdapter(model, task="classification")
+        >>> probs = adapter.predict(X_numpy)  # Returns probabilities
+    """
+    
+    def __init__(
+        self,
+        model,
+        task: str = "classification",
+        feature_names: Optional[List[str]] = None,
+        class_names: Optional[List[str]] = None,
+        device: Optional[str] = None,
+        output_activation: Optional[str] = "auto",
+        batch_size: int = 32
+    ):
+        """
+        Initialize the PyTorch adapter.
+        
+        Args:
+            model: A PyTorch nn.Module model.
+            task: "classification" or "regression".
+            feature_names: List of input feature names.
+            class_names: List of output class names (classification only).
+            device: Device to run on ("cpu", "cuda", "cuda:0", etc.).
+                   If None, auto-detects based on model parameters.
+            output_activation: Activation for output layer:
+                - "auto": softmax for classification, none for regression
+                - "softmax": Apply softmax (classification)
+                - "sigmoid": Apply sigmoid (binary classification)
+                - "none" or None: No activation (raw logits/values)
+            batch_size: Batch size for large inputs (default: 32).
+        """
+        _check_torch_available()
+        
+        if not isinstance(model, nn.Module):
+            raise TypeError(
+                f"Expected nn.Module, got {type(model).__name__}. "
+                "For sklearn models, use SklearnAdapter instead."
+            )
+        
+        super().__init__(model, feature_names)
+        
+        self.task = task
+        self.class_names = list(class_names) if class_names else None
+        self.batch_size = batch_size
+        
+        # Determine device
+        if device is not None:
+            self.device = torch.device(device)
+        else:
+            # Auto-detect from model parameters
+            try:
+                param = next(model.parameters())
+                self.device = param.device
+            except StopIteration:
+                # Model has no parameters, use CPU
+                self.device = torch.device("cpu")
+        
+        # Move model to device and set to eval mode
+        self.model = model.to(self.device)
+        self.model.eval()
+        
+        # Configure output activation
+        if output_activation == "auto":
+            if task == "classification":
+                self.output_activation = "softmax"
+            else:
+                self.output_activation = None
+        else:
+            self.output_activation = output_activation if output_activation != "none" else None
+    
+    def _to_tensor(self, data: np.ndarray) -> "torch.Tensor":
+        """Convert numpy array to tensor on the correct device."""
+        if isinstance(data, torch.Tensor):
+            return data.to(self.device).float()
+        return torch.tensor(data, dtype=torch.float32, device=self.device)
+    
+    def _to_numpy(self, tensor: "torch.Tensor") -> np.ndarray:
+        """Convert tensor to numpy array."""
+        return tensor.detach().cpu().numpy()
+    
+    def _apply_activation(self, output: "torch.Tensor") -> "torch.Tensor":
+        """Apply output activation function."""
+        if self.output_activation == "softmax":
+            return torch.softmax(output, dim=-1)
+        elif self.output_activation == "sigmoid":
+            return torch.sigmoid(output)
+        return output
+    
+    def predict(self, data: np.ndarray) -> np.ndarray:
+        """
+        Generate predictions for input data.
+        
+        Args:
+            data: Input data as numpy array. Shape: (n_samples, n_features)
+                  or (n_samples, channels, height, width) for images.
+        
+        Returns:
+            Predictions as numpy array:
+            - Classification: probabilities of shape (n_samples, n_classes)
+            - Regression: values of shape (n_samples, n_outputs)
+        """
+        data = np.array(data)
+        
+        # Handle single instance
+        if data.ndim == 1:
+            data = data.reshape(1, -1)
+        
+        n_samples = data.shape[0]
+        outputs = []
+        
+        with torch.no_grad():
+            for i in range(0, n_samples, self.batch_size):
+                batch = data[i:i + self.batch_size]
+                tensor_batch = self._to_tensor(batch)
+                
+                output = self.model(tensor_batch)
+                output = self._apply_activation(output)
+                outputs.append(self._to_numpy(output))
+        
+        return np.vstack(outputs)
+    
+    def predict_with_gradients(
+        self,
+        data: np.ndarray,
+        target_class: Optional[int] = None
+    ) -> tuple:
+        """
+        Generate predictions and compute gradients w.r.t. inputs.
+        
+        This is essential for gradient-based attribution methods like
+        Integrated Gradients, GradCAM, and Saliency Maps.
+        
+        Args:
+            data: Input data as numpy array.
+            target_class: Class index for gradient computation.
+                         If None, uses the predicted class.
+        
+        Returns:
+            Tuple of (predictions, gradients) as numpy arrays.
+        """
+        data = np.array(data)
+        if data.ndim == 1:
+            data = data.reshape(1, -1)
+        
+        # Convert to tensor with gradient tracking
+        tensor_data = self._to_tensor(data)
+        tensor_data.requires_grad_(True)
+        
+        # Forward pass
+        output = self.model(tensor_data)
+        activated_output = self._apply_activation(output)
+        
+        # Determine target for gradient
+        if self.task == "classification":
+            if target_class is None:
+                target_class = output.argmax(dim=-1)
+            elif isinstance(target_class, int):
+                target_class = torch.tensor([target_class] * data.shape[0], device=self.device)
+            
+            # Select target class scores for gradient
+            target_scores = output.gather(1, target_class.view(-1, 1)).squeeze()
+        else:
+            # Regression: gradient w.r.t. output
+            target_scores = output.squeeze()
+        
+        # Backward pass
+        if target_scores.dim() == 0:
+            target_scores.backward()
+        else:
+            target_scores.sum().backward()
+        
+        gradients = tensor_data.grad
+        
+        return (
+            self._to_numpy(activated_output),
+            self._to_numpy(gradients)
+        )
+    
+    def get_layer_output(
+        self,
+        data: np.ndarray,
+        layer_name: str
+    ) -> np.ndarray:
+        """
+        Get intermediate layer activations.
+        
+        Useful for methods like GradCAM that need feature map activations.
+        
+        Args:
+            data: Input data as numpy array.
+            layer_name: Name of the layer to extract (as registered in model).
+        
+        Returns:
+            Layer activations as numpy array.
+        """
+        data = np.array(data)
+        if data.ndim == 1:
+            data = data.reshape(1, -1)
+        
+        activations = {}
+        
+        def hook_fn(module, input, output):
+            activations['output'] = output
+        
+        # Find and hook the layer
+        layer = dict(self.model.named_modules()).get(layer_name)
+        if layer is None:
+            available = list(dict(self.model.named_modules()).keys())
+            raise ValueError(
+                f"Layer '{layer_name}' not found. Available layers: {available}"
+            )
+        
+        handle = layer.register_forward_hook(hook_fn)
+        
+        try:
+            with torch.no_grad():
+                tensor_data = self._to_tensor(data)
+                _ = self.model(tensor_data)
+        finally:
+            handle.remove()
+        
+        return self._to_numpy(activations['output'])
+    
+    def get_layer_gradients(
+        self,
+        data: np.ndarray,
+        layer_name: str,
+        target_class: Optional[int] = None
+    ) -> tuple:
+        """
+        Get gradients of output w.r.t. a specific layer's activations.
+        
+        Essential for GradCAM and similar visualization methods.
+        
+        Args:
+            data: Input data as numpy array.
+            layer_name: Name of the layer for gradient computation.
+            target_class: Target class for gradient (classification).
+        
+        Returns:
+            Tuple of (layer_activations, layer_gradients) as numpy arrays.
+        """
+        data = np.array(data)
+        if data.ndim == 1:
+            data = data.reshape(1, -1)
+        
+        activations = {}
+        gradients = {}
+        
+        def forward_hook(module, input, output):
+            activations['output'] = output
+        
+        def backward_hook(module, grad_input, grad_output):
+            gradients['output'] = grad_output[0]
+        
+        # Find and hook the layer
+        layer = dict(self.model.named_modules()).get(layer_name)
+        if layer is None:
+            available = list(dict(self.model.named_modules()).keys())
+            raise ValueError(
+                f"Layer '{layer_name}' not found. Available layers: {available}"
+            )
+        
+        forward_handle = layer.register_forward_hook(forward_hook)
+        backward_handle = layer.register_full_backward_hook(backward_hook)
+        
+        try:
+            tensor_data = self._to_tensor(data)
+            tensor_data.requires_grad_(True)
+            
+            output = self.model(tensor_data)
+            
+            if self.task == "classification":
+                if target_class is None:
+                    target_class = output.argmax(dim=-1)
+                elif isinstance(target_class, int):
+                    target_class = torch.tensor([target_class] * data.shape[0], device=self.device)
+                
+                target_scores = output.gather(1, target_class.view(-1, 1)).squeeze()
+            else:
+                target_scores = output.squeeze()
+            
+            if target_scores.dim() == 0:
+                target_scores.backward()
+            else:
+                target_scores.sum().backward()
+        finally:
+            forward_handle.remove()
+            backward_handle.remove()
+        
+        return (
+            self._to_numpy(activations['output']),
+            self._to_numpy(gradients['output'])
+        )
+    
+    def list_layers(self) -> List[str]:
+        """
+        List all named layers/modules in the model.
+        
+        Returns:
+            List of layer names that can be used with get_layer_output/gradients.
+        """
+        return [name for name, _ in self.model.named_modules() if name]
+    
+    def to(self, device: str) -> "PyTorchAdapter":
+        """
+        Move the model to a different device.
+        
+        Args:
+            device: Target device ("cpu", "cuda", "cuda:0", etc.)
+        
+        Returns:
+            Self for chaining.
+        """
+        self.device = torch.device(device)
+        self.model = self.model.to(self.device)
+        return self
+    
+    def train_mode(self) -> "PyTorchAdapter":
+        """Set model to training mode (enables dropout, batchnorm updates)."""
+        self.model.train()
+        return self
+    
+    def eval_mode(self) -> "PyTorchAdapter":
+        """Set model to evaluation mode (disables dropout, freezes batchnorm)."""
+        self.model.eval()
+        return self

explainiverse/core/registry.py

@@ -362,6 +362,7 @@ def _create_default_registry() -> ExplainerRegistry:
     """Create and populate the default global registry."""
     from explainiverse.explainers.attribution.lime_wrapper import LimeExplainer
     from explainiverse.explainers.attribution.shap_wrapper import ShapExplainer
+    from explainiverse.explainers.attribution.treeshap_wrapper import TreeShapExplainer
     from explainiverse.explainers.rule_based.anchors_wrapper import AnchorsExplainer
     from explainiverse.explainers.global_explainers.permutation_importance import PermutationImportanceExplainer
     from explainiverse.explainers.global_explainers.partial_dependence import PartialDependenceExplainer
@@ -409,6 +410,23 @@ def _create_default_registry() -> ExplainerRegistry:
         )
     )
     
+    # Register TreeSHAP (optimized for tree models)
+    registry.register(
+        name="treeshap",
+        explainer_class=TreeShapExplainer,
+        meta=ExplainerMeta(
+            scope="local",
+            model_types=["tree", "ensemble"],
+            data_types=["tabular"],
+            task_types=["classification", "regression"],
+            description="TreeSHAP - exact SHAP values for tree-based models (RandomForest, XGBoost, etc.)",
+            paper_reference="Lundberg et al., 2018 - 'Consistent Individualized Feature Attribution for Tree Ensembles'",
+            complexity="O(TLD^2) - polynomial in tree depth",
+            requires_training_data=False,
+            supports_batching=True
+        )
+    )
+    
     # Register Anchors
     registry.register(
         name="anchors",

explainiverse/explainers/__init__.py

@@ -4,7 +4,8 @@ Explainiverse Explainers - comprehensive XAI method implementations.
 
 Local Explainers (instance-level):
 - LIME: Local Interpretable Model-agnostic Explanations
-- SHAP: SHapley Additive exPlanations
+- SHAP: SHapley Additive exPlanations (KernelSHAP - model-agnostic)
+- TreeSHAP: Optimized exact SHAP for tree-based models
 - Anchors: High-precision rule-based explanations
 - Counterfactual: Diverse counterfactual explanations
 
@@ -17,6 +18,7 @@ Global Explainers (model-level):
 
 from explainiverse.explainers.attribution.lime_wrapper import LimeExplainer
 from explainiverse.explainers.attribution.shap_wrapper import ShapExplainer
+from explainiverse.explainers.attribution.treeshap_wrapper import TreeShapExplainer
 from explainiverse.explainers.rule_based.anchors_wrapper import AnchorsExplainer
 from explainiverse.explainers.counterfactual.dice_wrapper import CounterfactualExplainer
 from explainiverse.explainers.global_explainers.permutation_importance import PermutationImportanceExplainer
@@ -28,6 +30,7 @@ __all__ = [
     # Local explainers
     "LimeExplainer",
     "ShapExplainer",
+    "TreeShapExplainer",
     "AnchorsExplainer",
     "CounterfactualExplainer",
     # Global explainers

explainiverse/explainers/attribution/__init__.py

@@ -5,5 +5,6 @@ Attribution-based explainers - feature importance explanations.
 
 from explainiverse.explainers.attribution.lime_wrapper import LimeExplainer
 from explainiverse.explainers.attribution.shap_wrapper import ShapExplainer
+from explainiverse.explainers.attribution.treeshap_wrapper import TreeShapExplainer
 
-__all__ = ["LimeExplainer", "ShapExplainer"]
+__all__ = ["LimeExplainer", "ShapExplainer", "TreeShapExplainer"]

explainiverse/explainers/attribution/treeshap_wrapper.py

@@ -0,0 +1,434 @@
+# src/explainiverse/explainers/attribution/treeshap_wrapper.py
+"""
+TreeSHAP Explainer - Optimized SHAP for Tree-based Models.
+
+TreeSHAP computes exact SHAP values in polynomial time for tree-based models,
+making it significantly faster than KernelSHAP while providing exact (not
+approximate) Shapley values.
+
+Reference:
+    Lundberg, S.M., Erion, G.G., & Lee, S.I. (2018). Consistent Individualized
+    Feature Attribution for Tree Ensembles. arXiv:1802.03888.
+    
+Supported Models:
+    - scikit-learn: RandomForest, GradientBoosting, DecisionTree, ExtraTrees
+    - XGBoost: XGBClassifier, XGBRegressor
+    - LightGBM: LGBMClassifier, LGBMRegressor (if installed)
+    - CatBoost: CatBoostClassifier, CatBoostRegressor (if installed)
+"""
+
+import numpy as np
+import shap
+from typing import List, Optional, Union
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+# Tree-based model types that TreeSHAP supports
+SUPPORTED_TREE_MODELS = (
+    "RandomForestClassifier",
+    "RandomForestRegressor",
+    "GradientBoostingClassifier",
+    "GradientBoostingRegressor",
+    "DecisionTreeClassifier",
+    "DecisionTreeRegressor",
+    "ExtraTreesClassifier",
+    "ExtraTreesRegressor",
+    "XGBClassifier",
+    "XGBRegressor",
+    "XGBRFClassifier",
+    "XGBRFRegressor",
+    "LGBMClassifier",
+    "LGBMRegressor",
+    "CatBoostClassifier",
+    "CatBoostRegressor",
+    "HistGradientBoostingClassifier",
+    "HistGradientBoostingRegressor",
+)
+
+
+def _is_tree_model(model) -> bool:
+    """Check if a model is a supported tree-based model."""
+    model_name = type(model).__name__
+    return model_name in SUPPORTED_TREE_MODELS
+
+
+def _get_raw_model(model):
+    """
+    Extract the raw model from an adapter if necessary.
+    
+    TreeExplainer needs the actual sklearn/xgboost model, not an adapter.
+    """
+    # If it's an adapter, get the underlying model
+    if hasattr(model, 'model'):
+        return model.model
+    return model
+
+
+class TreeShapExplainer(BaseExplainer):
+    """
+    TreeSHAP explainer for tree-based models.
+    
+    Uses SHAP's TreeExplainer to compute exact SHAP values in polynomial time.
+    This is significantly faster than KernelSHAP for supported tree models
+    and provides exact Shapley values rather than approximations.
+    
+    Key advantages over KernelSHAP:
+    - Exact SHAP values (not approximations)
+    - O(TLD²) complexity vs O(TL2^M) for KernelSHAP
+    - Can compute interaction values
+    - No background data sampling needed
+    
+    Attributes:
+        model: The tree-based model (sklearn, XGBoost, LightGBM, or CatBoost)
+        feature_names: List of feature names
+        class_names: List of class names for classification
+        explainer: The underlying SHAP TreeExplainer
+        task: "classification" or "regression"
+    """
+    
+    def __init__(
+        self,
+        model,
+        feature_names: List[str],
+        class_names: Optional[List[str]] = None,
+        background_data: Optional[np.ndarray] = None,
+        task: str = "classification",
+        model_output: str = "auto",
+        feature_perturbation: str = "tree_path_dependent"
+    ):
+        """
+        Initialize the TreeSHAP explainer.
+        
+        Args:
+            model: A tree-based model or adapter containing one.
+                   Supported: RandomForest, GradientBoosting, XGBoost, 
+                   LightGBM, CatBoost, DecisionTree, ExtraTrees.
+            feature_names: List of feature names.
+            class_names: List of class names (for classification).
+            background_data: Optional background dataset for interventional
+                            feature perturbation. If None, uses tree_path_dependent.
+            task: "classification" or "regression".
+            model_output: How to transform model output. Options:
+                         - "auto": Automatically detect
+                         - "raw": Raw model output
+                         - "probability": Probability output (classification)
+                         - "log_loss": Log loss output
+            feature_perturbation: Method for handling feature perturbation:
+                                 - "tree_path_dependent": Fast, uses tree structure
+                                 - "interventional": Slower, requires background data
+        """
+        # Extract raw model if wrapped in adapter
+        raw_model = _get_raw_model(model)
+        
+        # Validate that it's a supported tree model
+        if not _is_tree_model(raw_model):
+            model_type = type(raw_model).__name__
+            raise ValueError(
+                f"TreeSHAP requires a tree-based model. Got {model_type}. "
+                f"Supported models: {', '.join(SUPPORTED_TREE_MODELS[:6])}..."
+            )
+        
+        super().__init__(model)
+        self.raw_model = raw_model
+        self.feature_names = list(feature_names)
+        self.class_names = list(class_names) if class_names else None
+        self.task = task
+        self.model_output = model_output
+        self.feature_perturbation = feature_perturbation
+        
+        # Create TreeExplainer
+        explainer_kwargs = {}
+        
+        if feature_perturbation == "interventional" and background_data is not None:
+            explainer_kwargs["data"] = background_data
+            explainer_kwargs["feature_perturbation"] = "interventional"
+        
+        if model_output != "auto":
+            explainer_kwargs["model_output"] = model_output
+        
+        self.explainer = shap.TreeExplainer(raw_model, **explainer_kwargs)
+        self.background_data = background_data
+    
+    def explain(
+        self,
+        instance: np.ndarray,
+        target_class: Optional[int] = None,
+        check_additivity: bool = False
+    ) -> Explanation:
+        """
+        Generate TreeSHAP explanation for a single instance.
+        
+        Args:
+            instance: 1D numpy array of input features.
+            target_class: For multi-class, which class to explain.
+                         If None, uses the predicted class.
+            check_additivity: Whether to verify SHAP values sum to 
+                             prediction - expected_value.
+        
+        Returns:
+            Explanation object with feature attributions.
+        """
+        instance = np.array(instance).flatten()
+        instance_2d = instance.reshape(1, -1)
+        
+        # Compute SHAP values
+        shap_values = self.explainer.shap_values(
+            instance_2d,
+            check_additivity=check_additivity
+        )
+        
+        # Handle different output formats
+        if isinstance(shap_values, list):
+            # Multi-class classification: list of arrays, one per class
+            n_classes = len(shap_values)
+            
+            if target_class is None:
+                # Use predicted class
+                if hasattr(self.raw_model, 'predict'):
+                    pred = self.raw_model.predict(instance_2d)[0]
+                    target_class = int(pred)
+                else:
+                    target_class = 0
+            
+            # Ensure target_class is valid
+            target_class = min(target_class, n_classes - 1)
+            class_shap = shap_values[target_class][0]
+            
+            # Get class name
+            if self.class_names and target_class < len(self.class_names):
+                label_name = self.class_names[target_class]
+            else:
+                label_name = f"class_{target_class}"
+            
+            # Store all class SHAP values for reference
+            all_class_shap = {
+                (self.class_names[i] if self.class_names and i < len(self.class_names) 
+                 else f"class_{i}"): shap_values[i][0].tolist()
+                for i in range(n_classes)
+            }
+        else:
+            # Binary classification or regression
+            class_shap = shap_values[0] if shap_values.ndim > 1 else shap_values.flatten()
+            label_name = self.class_names[1] if self.class_names and len(self.class_names) > 1 else "output"
+            all_class_shap = None
+        
+        # Build attributions dict
+        flat_shap = np.array(class_shap).flatten()
+        attributions = {
+            fname: float(flat_shap[i])
+            for i, fname in enumerate(self.feature_names)
+        }
+        
+        # Get expected value (base value)
+        expected_value = self.explainer.expected_value
+        if isinstance(expected_value, (list, np.ndarray)):
+            if target_class is not None and target_class < len(expected_value):
+                base_value = float(expected_value[target_class])
+            else:
+                base_value = float(expected_value[0])
+        else:
+            base_value = float(expected_value)
+        
+        explanation_data = {
+            "feature_attributions": attributions,
+            "base_value": base_value,
+            "shap_values_raw": flat_shap.tolist(),
+        }
+        
+        if all_class_shap is not None:
+            explanation_data["all_class_shap_values"] = all_class_shap
+        
+        return Explanation(
+            explainer_name="TreeSHAP",
+            target_class=label_name,
+            explanation_data=explanation_data
+        )
+    
+    def explain_batch(
+        self,
+        X: np.ndarray,
+        target_class: Optional[int] = None,
+        check_additivity: bool = False
+    ) -> List[Explanation]:
+        """
+        Generate TreeSHAP explanations for multiple instances efficiently.
+        
+        TreeSHAP can process batches more efficiently than individual calls.
+        
+        Args:
+            X: 2D numpy array of instances (n_samples, n_features).
+            target_class: For multi-class, which class to explain.
+            check_additivity: Whether to verify SHAP value additivity.
+        
+        Returns:
+            List of Explanation objects.
+        """
+        X = np.array(X)
+        if X.ndim == 1:
+            X = X.reshape(1, -1)
+        
+        # Compute SHAP values for all instances at once
+        shap_values = self.explainer.shap_values(X, check_additivity=check_additivity)
+        
+        explanations = []
+        for i in range(X.shape[0]):
+            if isinstance(shap_values, list):
+                # Multi-class
+                n_classes = len(shap_values)
+                tc = target_class if target_class is not None else 0
+                tc = min(tc, n_classes - 1)
+                class_shap = shap_values[tc][i]
+                
+                if self.class_names and tc < len(self.class_names):
+                    label_name = self.class_names[tc]
+                else:
+                    label_name = f"class_{tc}"
+            else:
+                class_shap = shap_values[i]
+                label_name = self.class_names[1] if self.class_names and len(self.class_names) > 1 else "output"
+            
+            flat_shap = np.array(class_shap).flatten()
+            attributions = {
+                fname: float(flat_shap[j])
+                for j, fname in enumerate(self.feature_names)
+            }
+            
+            expected_value = self.explainer.expected_value
+            if isinstance(expected_value, (list, np.ndarray)):
+                tc = target_class if target_class is not None else 0
+                base_value = float(expected_value[min(tc, len(expected_value) - 1)])
+            else:
+                base_value = float(expected_value)
+            
+            explanations.append(Explanation(
+                explainer_name="TreeSHAP",
+                target_class=label_name,
+                explanation_data={
+                    "feature_attributions": attributions,
+                    "base_value": base_value,
+                    "shap_values_raw": flat_shap.tolist(),
+                }
+            ))
+        
+        return explanations
+    
+    def explain_interactions(
+        self,
+        instance: np.ndarray,
+        target_class: Optional[int] = None
+    ) -> Explanation:
+        """
+        Compute SHAP interaction values for an instance.
+        
+        Interaction values show how pairs of features jointly contribute
+        to the prediction. The diagonal contains main effects.
+        
+        Args:
+            instance: 1D numpy array of input features.
+            target_class: For multi-class, which class to explain.
+        
+        Returns:
+            Explanation object with interaction matrix.
+        """
+        instance = np.array(instance).flatten()
+        instance_2d = instance.reshape(1, -1)
+        
+        # Compute interaction values
+        interaction_values = self.explainer.shap_interaction_values(instance_2d)
+        
+        # Determine target class for prediction
+        if target_class is None and hasattr(self.raw_model, 'predict'):
+            target_class = int(self.raw_model.predict(instance_2d)[0])
+        elif target_class is None:
+            target_class = 0
+        
+        # Handle different return formats from shap_interaction_values
+        if isinstance(interaction_values, list):
+            # Multi-class: list of arrays, one per class
+            n_classes = len(interaction_values)
+            tc = min(target_class, n_classes - 1)
+            interactions = np.array(interaction_values[tc][0])
+            
+            if self.class_names and tc < len(self.class_names):
+                label_name = self.class_names[tc]
+            else:
+                label_name = f"class_{tc}"
+        elif interaction_values.ndim == 4:
+            # Shape: (n_samples, n_features, n_features, n_classes)
+            n_classes = interaction_values.shape[3]
+            tc = min(target_class, n_classes - 1)
+            interactions = interaction_values[0, :, :, tc]
+            
+            if self.class_names and tc < len(self.class_names):
+                label_name = self.class_names[tc]
+            else:
+                label_name = f"class_{tc}"
+        else:
+            # Binary or regression: (n_samples, n_features, n_features)
+            interactions = interaction_values[0]
+            label_name = self.class_names[1] if self.class_names and len(self.class_names) > 1 else "output"
+        
+        # Ensure interactions is 2D (n_features x n_features)
+        interactions = np.array(interactions)
+        if interactions.ndim > 2:
+            # If still multi-dimensional, take first slice
+            interactions = interactions[:, :, 0] if interactions.ndim == 3 else interactions
+        
+        # Build interaction dict with feature name pairs
+        n_features = len(self.feature_names)
+        interaction_dict = {}
+        main_effects = {}
+        
+        for i in range(n_features):
+            fname_i = self.feature_names[i]
+            val = interactions[i, i]
+            main_effects[fname_i] = float(val) if np.isscalar(val) or val.size == 1 else float(val.flat[0])
+            
+            for j in range(i + 1, n_features):
+                fname_j = self.feature_names[j]
+                # Interaction values are symmetric, so we sum both directions
+                val_ij = interactions[i, j]
+                val_ji = interactions[j, i]
+                ij = float(val_ij) if np.isscalar(val_ij) or val_ij.size == 1 else float(val_ij.flat[0])
+                ji = float(val_ji) if np.isscalar(val_ji) or val_ji.size == 1 else float(val_ji.flat[0])
+                interaction_dict[f"{fname_i} x {fname_j}"] = ij + ji
+        
+        # Sort interactions by absolute value
+        sorted_interactions = dict(sorted(
+            interaction_dict.items(),
+            key=lambda x: abs(x[1]),
+            reverse=True
+        ))
+        
+        return Explanation(
+            explainer_name="TreeSHAP_Interactions",
+            target_class=label_name,
+            explanation_data={
+                "feature_attributions": main_effects,
+                "interactions": sorted_interactions,
+                "interaction_matrix": interactions.tolist(),
+                "feature_names": self.feature_names
+            }
+        )
+    
+    def get_expected_value(self, target_class: Optional[int] = None) -> float:
+        """
+        Get the expected (base) value of the model.
+        
+        This is the average model output over the background dataset.
+        
+        Args:
+            target_class: For multi-class, which class's expected value.
+        
+        Returns:
+            The expected value as a float.
+        """
+        expected_value = self.explainer.expected_value
+        
+        if isinstance(expected_value, (list, np.ndarray)):
+            tc = target_class if target_class is not None else 0
+            return float(expected_value[min(tc, len(expected_value) - 1)])
+        
+        return float(expected_value)

{explainiverse-0.2.0.dist-info → explainiverse-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.2.0
+Version: 0.2.2
 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 9 state-of-the-art XAI methods, evaluation metrics, and a plugin registry for easy extensibility.
 
 ---
 
@@ -40,6 +42,7 @@ 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))
 - **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 +65,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 +77,12 @@ From PyPI:
 pip install explainiverse
 ```
 
+With PyTorch support (for neural network explanations):
+
+```bash
+pip install explainiverse[torch]
+```
+
 For development:
 
 ```bash
@@ -100,7 +109,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', 'anchors', 'counterfactual', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
 
 # Create and use an explainer
 explainer = default_registry.create(
@@ -119,11 +128,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', '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 +142,64 @@ 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")
+```
+
 ### Using Specific Explainers
 
 ```python
@@ -233,12 +300,14 @@ poetry run pytest tests/test_new_explainers.py -v
 ## Roadmap
 
 - [x] LIME, SHAP (KernelSHAP)
+- [x] TreeSHAP (optimized for tree models) ✅ NEW
 - [x] Anchors, Counterfactuals
 - [x] Permutation Importance, PDP, ALE, SAGE
 - [x] Explainer Registry with filtering
-- [ ] TreeSHAP (optimized for tree models)
+- [x] PyTorch Adapter ✅ NEW
 - [ ] Integrated Gradients (gradient-based for neural nets)
-- [ ] PyTorch/TensorFlow adapters
+- [ ] GradCAM for CNNs
+- [ ] TensorFlow adapter
 - [ ] Interactive visualization dashboard
 
 ---

{explainiverse-0.2.0.dist-info → explainiverse-0.2.2.dist-info}/RECORD

@@ -1,19 +1,21 @@
-explainiverse/__init__.py,sha256=G8RreMDjukC0quXjsutBmEP_dtTdj_Q9CClA61xen0o,1207
-explainiverse/adapters/__init__.py,sha256=fNlWQ0VDjNqi4G4lwaJRTtL0wGVgvEE-4pZt6vOOjYU,322
+explainiverse/__init__.py,sha256=-4H6WbfGwpeoNpO9w0CEahKQBPsvIYe_lK5e10cZWD0,1612
+explainiverse/adapters/__init__.py,sha256=HcQGISyp-YQ4jEj2IYveX_c9X5otLcTNWRnVRRhzRik,781
 explainiverse/adapters/base_adapter.py,sha256=Nqt0GeDn_-PjTyJcZsE8dRTulavqFQsv8sMYWS_ps-M,603
+explainiverse/adapters/pytorch_adapter.py,sha256=GTilJAR1VF_OgWG88qZoqlqefHaSXB3i9iOwCJkyHTg,13318
 explainiverse/adapters/sklearn_adapter.py,sha256=pzIBtMuqrG-6ZbUqUCMt7rSk3Ow0FgrY268FSweFvw4,958
 explainiverse/core/__init__.py,sha256=P3jHMnH5coFqTTO1w-gT-rurkCM1-9r3pF-055pbXMg,474
 explainiverse/core/explainer.py,sha256=Z9on-9VblYDlQx9oBm1BHpmAf_NsQajZ3qr-u48Aejo,784
 explainiverse/core/explanation.py,sha256=6zxFh_TH8tFHc-r_H5-WHQ05Sp1Kp2TxLz3gyFek5jo,881
-explainiverse/core/registry.py,sha256=neI--cDC6j2VyZdUQbKkt1ERLGsaJdSyZSMvJ1b9RYs,19061
+explainiverse/core/registry.py,sha256=_BXWi1fJY3cGjYA1Xn1DwvY91jbpJrpX6_8EVzrRT20,19876
 explainiverse/engine/__init__.py,sha256=1sZO8nH1mmwK2e-KUavBQm7zYDWUe27nyWoFy9tgsiA,197
 explainiverse/engine/suite.py,sha256=sq8SK_6Pf0qRckTmVJ7Mdosu9bhkjAGPGN8ymLGFP9E,4914
 explainiverse/evaluation/__init__.py,sha256=Y50L_b4HKthg4epwcayPHXh0l4i4MUuzvaNlqPmUNZY,212
 explainiverse/evaluation/metrics.py,sha256=tSBXtyA_-0zOGCGjlPZU6LdGKRH_QpWfgKa78sdlovs,7453
-explainiverse/explainers/__init__.py,sha256=CYaDGsASoiNkwUUkeugLowR1-kupLNSvaCK8Fw_zdRI,1564
-explainiverse/explainers/attribution/__init__.py,sha256=ei8w6_4VL5aA5HSwIhcJx6gD_oVNAYFf_H1PRAi1SCA,326
+explainiverse/explainers/__init__.py,sha256=Op-Z_BTJ7BdqA_9gTnruomN2-rKtrkPCt1Zq1iCzxr0,1758
+explainiverse/explainers/attribution/__init__.py,sha256=YeVs9bS_IWDtqGbp6T37V6Zp5ZDWzLdAXHxxyFGpiQM,431
 explainiverse/explainers/attribution/lime_wrapper.py,sha256=OnXIV7t6yd-vt38sIi7XmHFbgzlZfCEbRlFyGGd5XiE,3245
 explainiverse/explainers/attribution/shap_wrapper.py,sha256=tKie5AvN7mb55PWOYdMvW0lUAYjfHPzYosEloEY2ZzI,3210
+explainiverse/explainers/attribution/treeshap_wrapper.py,sha256=LcBjHzQjmeyWCwLXALJ0WFQ9ol-N_8dod577EDxFDKY,16758
 explainiverse/explainers/counterfactual/__init__.py,sha256=gEV6P8h2fZ3-pv5rqp5sNDqrLErh5ntqpxIIBVCMFv4,247
 explainiverse/explainers/counterfactual/dice_wrapper.py,sha256=PyJYF-z1nyyy0mFROnkJqPtcuT2PwEBARwfh37mZ5ew,11373
 explainiverse/explainers/global_explainers/__init__.py,sha256=91xayho0r-fVeIxBLTxF-aBaBhRTRRXxGZ7oUHh7z64,713
@@ -23,7 +25,7 @@ explainiverse/explainers/global_explainers/permutation_importance.py,sha256=bcgK
 explainiverse/explainers/global_explainers/sage.py,sha256=57Xw1SK529x5JXWt0TVrcFYUUP3C65LfUwgoM-Z3gaw,5839
 explainiverse/explainers/rule_based/__init__.py,sha256=gKzlFCAzwurAMLJcuYgal4XhDj1thteBGcaHWmN7iWk,243
 explainiverse/explainers/rule_based/anchors_wrapper.py,sha256=ML7W6aam-eMGZHy5ilol8qupZvNBJpYAFatEEPnuMyo,13254
-explainiverse-0.2.0.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
-explainiverse-0.2.0.dist-info/METADATA,sha256=WqgN7AquEhUxeO6G3ZLhOXjKuNoVcOuVfXU8jQ1u1F0,7731
-explainiverse-0.2.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-explainiverse-0.2.0.dist-info/RECORD,,
+explainiverse-0.2.2.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
+explainiverse-0.2.2.dist-info/METADATA,sha256=kis3ejJCLRhBJWf5p13FzY2ZeSbnWfJxk6LS1hd7A1w,9497
+explainiverse-0.2.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+explainiverse-0.2.2.dist-info/RECORD,,