xplia 1.0.1__py3-none-any.whl

xplia/integrations/wandb_integration.py

@@ -0,0 +1,375 @@
+"""
+Weights & Biases integration for XPLIA.
+
+Log explanations, compliance reports, and trust metrics to W&B.
+
+Author: XPLIA Team
+License: MIT
+"""
+
+from typing import Any, Dict, Optional, List
+import tempfile
+from pathlib import Path
+
+try:
+    import wandb
+except ImportError:
+    raise ImportError(
+        "Weights & Biases not installed. Install with: pip install xplia[mlops]"
+    )
+
+from xplia.core.base import ExplanationResult
+
+
+class XPLIAWandBLogger:
+    """
+    Logger for XPLIA explanations and metrics to Weights & Biases.
+
+    Examples
+    --------
+    >>> logger = XPLIAWandBLogger(project="my-ml-project")
+    >>> logger.log_explanation(explanation)
+    """
+
+    def __init__(
+        self,
+        project: Optional[str] = None,
+        entity: Optional[str] = None,
+        config: Optional[Dict] = None
+    ):
+        """
+        Initialize W&B logger.
+
+        Parameters
+        ----------
+        project : str, optional
+            W&B project name.
+
+        entity : str, optional
+            W&B entity (username or team).
+
+        config : dict, optional
+            Configuration to log.
+        """
+        self.project = project
+        self.entity = entity
+        self.config = config or {}
+
+    def init_run(
+        self,
+        name: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        notes: Optional[str] = None
+    ):
+        """
+        Initialize W&B run.
+
+        Parameters
+        ----------
+        name : str, optional
+            Run name.
+
+        tags : list of str, optional
+            Tags for the run.
+
+        notes : str, optional
+            Notes for the run.
+        """
+        default_tags = tags or []
+        default_tags.extend(["xplia", "explainability"])
+
+        wandb.init(
+            project=self.project,
+            entity=self.entity,
+            name=name,
+            tags=default_tags,
+            notes=notes,
+            config=self.config
+        )
+
+    def log_explanation(
+        self,
+        explanation: ExplanationResult,
+        step: Optional[int] = None
+    ):
+        """
+        Log explanation to W&B.
+
+        Parameters
+        ----------
+        explanation : ExplanationResult
+            Explanation to log.
+
+        step : int, optional
+            Step number for logging.
+        """
+        log_dict = {
+            "explanation/method": explanation.method
+        }
+
+        # Log quality metrics
+        if hasattr(explanation, 'quality_metrics') and explanation.quality_metrics:
+            for metric_name, metric_value in explanation.quality_metrics.items():
+                if isinstance(metric_value, (int, float)):
+                    log_dict[f"explanation/quality/{metric_name}"] = metric_value
+
+        # Log feature importance
+        if 'feature_importance' in explanation.explanation_data:
+            import numpy as np
+
+            importance = explanation.explanation_data['feature_importance']
+            feature_names = explanation.explanation_data.get('feature_names', [])
+
+            if isinstance(importance, np.ndarray):
+                importance = importance.tolist()
+
+            # Create bar chart
+            if feature_names:
+                importance_table = wandb.Table(
+                    columns=["feature", "importance"],
+                    data=[[name, imp] for name, imp in zip(feature_names, importance)]
+                )
+                log_dict["explanation/feature_importance"] = wandb.plot.bar(
+                    importance_table,
+                    "feature",
+                    "importance",
+                    title="Feature Importance"
+                )
+
+                # Also log top features
+                top_indices = np.argsort(np.abs(importance))[-5:][::-1]
+                for idx in top_indices:
+                    log_dict[f"explanation/top_features/{feature_names[idx]}"] = importance[idx]
+
+        wandb.log(log_dict, step=step)
+
+    def log_compliance_report(
+        self,
+        compliance_result: Any,
+        regulation: str,
+        step: Optional[int] = None
+    ):
+        """
+        Log compliance report to W&B.
+
+        Parameters
+        ----------
+        compliance_result : ComplianceResult
+            Compliance check result.
+
+        regulation : str
+            Regulation name.
+
+        step : int, optional
+            Step number.
+        """
+        log_dict = {
+            f"compliance/{regulation}/score": compliance_result.score,
+            f"compliance/{regulation}/compliant": compliance_result.compliant
+        }
+
+        # Log requirements
+        if hasattr(compliance_result, 'requirements'):
+            met_requirements = sum(1 for req in compliance_result.requirements if req.get('met', False))
+            total_requirements = len(compliance_result.requirements)
+            log_dict[f"compliance/{regulation}/requirements_met"] = met_requirements
+            log_dict[f"compliance/{regulation}/requirements_total"] = total_requirements
+
+        # Save full report as artifact
+        with tempfile.TemporaryDirectory() as tmpdir:
+            report_path = Path(tmpdir) / f"{regulation}_compliance_report.pdf"
+            compliance_result.export(str(report_path), format='pdf')
+
+            artifact = wandb.Artifact(
+                name=f"{regulation}_compliance_report",
+                type="compliance_report",
+                description=f"Compliance report for {regulation}"
+            )
+            artifact.add_file(str(report_path))
+            wandb.log_artifact(artifact)
+
+        wandb.log(log_dict, step=step)
+
+    def log_trust_metrics(
+        self,
+        trust_metrics: Dict[str, float],
+        step: Optional[int] = None
+    ):
+        """
+        Log trust evaluation metrics to W&B.
+
+        Parameters
+        ----------
+        trust_metrics : dict
+            Trust metrics.
+
+        step : int, optional
+            Step number.
+        """
+        log_dict = {}
+        for metric_name, metric_value in trust_metrics.items():
+            if isinstance(metric_value, (int, float)):
+                log_dict[f"trust/{metric_name}"] = metric_value
+
+        wandb.log(log_dict, step=step)
+
+    def log_fairwashing_detection(
+        self,
+        fairwashing_result: Any,
+        step: Optional[int] = None
+    ):
+        """
+        Log fairwashing detection results.
+
+        Parameters
+        ----------
+        fairwashing_result : FairwashingResult
+            Detection result.
+
+        step : int, optional
+            Step number.
+        """
+        log_dict = {
+            "fairwashing/detected": fairwashing_result.detected
+        }
+
+        if fairwashing_result.detected:
+            log_dict["fairwashing/severity"] = fairwashing_result.severity
+            log_dict["fairwashing/types_count"] = len(fairwashing_result.fairwashing_types)
+
+            # Create alert
+            wandb.alert(
+                title="Fairwashing Detected",
+                text=f"Severity: {fairwashing_result.severity}, Types: {', '.join(fairwashing_result.fairwashing_types)}",
+                level=wandb.AlertLevel.WARN
+            )
+
+        wandb.log(log_dict, step=step)
+
+    def log_uncertainty_metrics(
+        self,
+        uncertainty_result: Any,
+        step: Optional[int] = None
+    ):
+        """
+        Log uncertainty quantification results.
+
+        Parameters
+        ----------
+        uncertainty_result : UncertaintyResult
+            Uncertainty metrics.
+
+        step : int, optional
+            Step number.
+        """
+        log_dict = {
+            "uncertainty/global": uncertainty_result.global_uncertainty,
+            "uncertainty/aleatoric": uncertainty_result.aleatoric_uncertainty,
+            "uncertainty/epistemic": uncertainty_result.epistemic_uncertainty
+        }
+
+        if hasattr(uncertainty_result, 'structural_uncertainty'):
+            log_dict["uncertainty/structural"] = uncertainty_result.structural_uncertainty
+
+        wandb.log(log_dict, step=step)
+
+    def log_model_with_explainability(
+        self,
+        model: Any,
+        explainer: Any,
+        model_name: str,
+        sample_input: Optional[Any] = None
+    ):
+        """
+        Log model with explainability artifacts.
+
+        Parameters
+        ----------
+        model : object
+            ML model.
+
+        explainer : Explainer
+            XPLIA explainer.
+
+        model_name : str
+            Model name.
+
+        sample_input : array-like, optional
+            Sample input for demonstration.
+        """
+        # Save model as artifact
+        with tempfile.TemporaryDirectory() as tmpdir:
+            model_path = Path(tmpdir) / "model.pkl"
+
+            import joblib
+            joblib.dump(model, model_path)
+
+            artifact = wandb.Artifact(
+                name=model_name,
+                type="model",
+                description=f"Model with XPLIA explainability"
+            )
+            artifact.add_file(str(model_path))
+
+            # Add explainer metadata
+            artifact.metadata = {
+                "explainer_method": explainer.method if hasattr(explainer, 'method') else 'unknown',
+                "xplia_version": "1.0.0"
+            }
+
+            wandb.log_artifact(artifact)
+
+        # Log sample explanation if provided
+        if sample_input is not None:
+            explanation = explainer.explain(sample_input)
+            self.log_explanation(explanation)
+
+    def finish(self):
+        """Finish W&B run."""
+        wandb.finish()
+
+
+# Context manager
+class XPLIAWandBContext:
+    """
+    Context manager for XPLIA + W&B integration.
+
+    Examples
+    --------
+    >>> with XPLIAWandBContext(project="my-project", name="experiment-1") as logger:
+    ...     # Train model
+    ...     model.fit(X, y)
+    ...
+    ...     # Create and log explanations
+    ...     explainer = create_explainer(model, method='shap')
+    ...     explanation = explainer.explain(X_test)
+    ...     logger.log_explanation(explanation)
+    """
+
+    def __init__(
+        self,
+        project: Optional[str] = None,
+        entity: Optional[str] = None,
+        name: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        config: Optional[Dict] = None
+    ):
+        self.project = project
+        self.entity = entity
+        self.name = name
+        self.tags = tags
+        self.config = config
+        self.logger = None
+
+    def __enter__(self):
+        self.logger = XPLIAWandBLogger(
+            project=self.project,
+            entity=self.entity,
+            config=self.config
+        )
+        self.logger.init_run(name=self.name, tags=self.tags)
+        return self.logger
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.logger:
+            self.logger.finish()

xplia/plugins/__init__.py

@@ -0,0 +1,36 @@
+"""
+Système de plugins XPLIA
+========================
+
+Permet l’extension dynamique de la librairie par des modules externes (explainers, visualizers, compliance, etc.).
+"""
+
+import importlib
+import pkgutil
+
+class PluginRegistry:
+    """
+    Registre global des plugins XPLIA.
+    """
+    _registry = {}
+
+    @classmethod
+    def register(cls, name, plugin):
+        cls._registry[name] = plugin
+    @classmethod
+    def get(cls, name):
+        return cls._registry.get(name)
+    @classmethod
+    def all(cls):
+        return dict(cls._registry)
+
+    @classmethod
+    def auto_discover(cls, package='xplia.plugins'):
+        """
+        Découvre et enregistre automatiquement tous les plugins du package.
+        """
+        for loader, modname, ispkg in pkgutil.iter_modules(__import__(package).__path__):
+            if modname != '__init__':
+                module = importlib.import_module(f"{package}.{modname}")
+                if hasattr(module, 'register_plugin'):
+                    module.register_plugin(cls)

xplia/plugins/example_visualizer.py

@@ -0,0 +1,11 @@
+"""
+Exemple de plugin Visualizer pour XPLIA
+"""
+from . import PluginRegistry
+
+def register_plugin(registry):
+    registry.register('example_visualizer', ExampleVisualizer)
+
+class ExampleVisualizer:
+    def render(self, explanation_result):
+        return f"Visualisation custom : {explanation_result}"

xplia/utils/__init__.py

@@ -0,0 +1,18 @@
+"""
+Utilitaires pour XPLIA
+======================
+
+Ce module fournit des fonctions et classes utilitaires pour XPLIA.
+"""
+
+from .performance import Timer, MemoryTracker, measure_performance
+from .validation import validate_input, validate_model, validate_feature_names
+
+__all__ = [
+    'Timer',
+    'MemoryTracker',
+    'measure_performance',
+    'validate_input',
+    'validate_model',
+    'validate_feature_names',
+]

xplia/utils/performance.py

@@ -0,0 +1,119 @@
+"""
+Outils de mesure de performance
+================================
+
+Utilitaires pour mesurer le temps d'exécution et l'utilisation mémoire.
+"""
+
+import time
+import psutil
+import os
+from contextlib import contextmanager
+from typing import Optional, Dict, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class Timer:
+    """Gestionnaire de contexte pour mesurer le temps d'exécution."""
+    
+    def __init__(self, name: str = "Operation", verbose: bool = True):
+        """
+        Initialise le timer.
+        
+        Args:
+            name: Nom de l'opération à mesurer
+            verbose: Si True, affiche le temps écoulé
+        """
+        self.name = name
+        self.verbose = verbose
+        self.start_time = None
+        self.end_time = None
+        self.elapsed = None
+    
+    def __enter__(self):
+        """Démarre le timer."""
+        self.start_time = time.time()
+        return self
+    
+    def __exit__(self, *args):
+        """Arrête le timer et affiche le résultat."""
+        self.end_time = time.time()
+        self.elapsed = self.end_time - self.start_time
+        if self.verbose:
+            logger.info(f"{self.name} took {self.elapsed:.4f} seconds")
+    
+    def get_elapsed(self) -> Optional[float]:
+        """Retourne le temps écoulé en secondes."""
+        return self.elapsed
+
+
+class MemoryTracker:
+    """Gestionnaire de contexte pour suivre l'utilisation mémoire."""
+    
+    def __init__(self, name: str = "Operation", verbose: bool = True):
+        """
+        Initialise le tracker mémoire.
+        
+        Args:
+            name: Nom de l'opération à suivre
+            verbose: Si True, affiche l'utilisation mémoire
+        """
+        self.name = name
+        self.verbose = verbose
+        self.process = psutil.Process(os.getpid())
+        self.start_memory = None
+        self.end_memory = None
+        self.memory_used = None
+    
+    def __enter__(self):
+        """Démarre le suivi mémoire."""
+        self.start_memory = self.process.memory_info().rss / 1024 / 1024  # MB
+        return self
+    
+    def __exit__(self, *args):
+        """Arrête le suivi et affiche le résultat."""
+        self.end_memory = self.process.memory_info().rss / 1024 / 1024  # MB
+        self.memory_used = self.end_memory - self.start_memory
+        if self.verbose:
+            logger.info(f"{self.name} used {self.memory_used:.2f} MB of memory")
+    
+    def get_memory_used(self) -> Optional[float]:
+        """Retourne la mémoire utilisée en MB."""
+        return self.memory_used
+
+
+@contextmanager
+def measure_performance(name: str = "Operation", track_memory: bool = True):
+    """
+    Gestionnaire de contexte combiné pour mesurer temps et mémoire.
+    
+    Args:
+        name: Nom de l'opération
+        track_memory: Si True, suit aussi l'utilisation mémoire
+        
+    Yields:
+        Dict contenant les métriques de performance
+    """
+    metrics = {}
+    
+    timer = Timer(name, verbose=False)
+    timer.__enter__()
+    
+    if track_memory:
+        mem_tracker = MemoryTracker(name, verbose=False)
+        mem_tracker.__enter__()
+    
+    try:
+        yield metrics
+    finally:
+        timer.__exit__()
+        metrics['elapsed_time'] = timer.elapsed
+        
+        if track_memory:
+            mem_tracker.__exit__()
+            metrics['memory_used'] = mem_tracker.memory_used
+        
+        logger.info(f"{name} - Time: {metrics.get('elapsed_time', 0):.4f}s, "
+                   f"Memory: {metrics.get('memory_used', 0):.2f}MB")

xplia/utils/validation.py

@@ -0,0 +1,109 @@
+"""
+Fonctions de validation
+========================
+
+Utilitaires pour valider les entrées et modèles.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Any, Union, List, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def validate_input(X: Any, expected_shape: Optional[tuple] = None, 
+                   allow_1d: bool = False) -> np.ndarray:
+    """
+    Valide et convertit les données d'entrée en format numpy.
+    
+    Args:
+        X: Données d'entrée
+        expected_shape: Forme attendue (optionnel)
+        allow_1d: Si True, autorise les tableaux 1D
+        
+    Returns:
+        np.ndarray: Données validées
+        
+    Raises:
+        ValueError: Si les données ne sont pas valides
+    """
+    # Conversion en numpy array
+    if isinstance(X, pd.DataFrame):
+        X = X.values
+    elif isinstance(X, list):
+        X = np.array(X)
+    elif not isinstance(X, np.ndarray):
+        raise ValueError(f"Type de données non supporté: {type(X)}")
+    
+    # Validation de la forme
+    if not allow_1d and X.ndim == 1:
+        X = X.reshape(1, -1)
+    
+    if expected_shape is not None:
+        if X.shape != expected_shape:
+            logger.warning(f"Forme des données ({X.shape}) différente de la forme attendue ({expected_shape})")
+    
+    # Vérification des valeurs manquantes
+    if np.any(np.isnan(X)):
+        logger.warning("Données contenant des valeurs manquantes (NaN)")
+    
+    return X
+
+
+def validate_model(model: Any, required_methods: Optional[List[str]] = None) -> bool:
+    """
+    Valide qu'un modèle possède les méthodes requises.
+    
+    Args:
+        model: Modèle à valider
+        required_methods: Liste des méthodes requises
+        
+    Returns:
+        bool: True si le modèle est valide
+        
+    Raises:
+        ValueError: Si le modèle ne possède pas les méthodes requises
+    """
+    if required_methods is None:
+        required_methods = ['predict']
+    
+    missing_methods = []
+    for method in required_methods:
+        if not hasattr(model, method):
+            missing_methods.append(method)
+    
+    if missing_methods:
+        raise ValueError(
+            f"Le modèle ne possède pas les méthodes requises: {', '.join(missing_methods)}"
+        )
+    
+    return True
+
+
+def validate_feature_names(feature_names: Union[List[str], np.ndarray], 
+                           n_features: int) -> List[str]:
+    """
+    Valide et normalise les noms de features.
+    
+    Args:
+        feature_names: Noms des features
+        n_features: Nombre de features attendu
+        
+    Returns:
+        List[str]: Noms de features validés
+        
+    Raises:
+        ValueError: Si le nombre de noms ne correspond pas
+    """
+    if feature_names is None:
+        return [f"feature_{i}" for i in range(n_features)]
+    
+    if len(feature_names) != n_features:
+        raise ValueError(
+            f"Nombre de noms de features ({len(feature_names)}) "
+            f"différent du nombre de features ({n_features})"
+        )
+    
+    return list(feature_names)

xplia/visualizations/__init__.py

@@ -0,0 +1,31 @@
+"""
+Module de visualisations pour XPLIA
+==================================
+
+Ce module fournit des composants de visualisation adaptés à chaque type d'explication
+générée par les explainers de XPLIA, avec support pour différents niveaux d'audience.
+"""
+
+from .base import VisualizerBase
+from .registry import register_visualizer
+from .feature_importance_viz import FeatureImportanceVisualizer
+from .attention_viz import AttentionVisualizer
+from .gradient_viz import GradientVisualizer
+from .shap_viz import ShapVisualizer
+from .lime_viz import LimeVisualizer
+from .pdp_viz import PDPVisualizer
+from .counterfactual_viz import CounterfactualVisualizer
+from .anchor_viz import AnchorVisualizer
+
+__all__ = [
+    "VisualizerBase",
+    "register_visualizer",
+    "FeatureImportanceVisualizer",
+    "AttentionVisualizer",
+    "GradientVisualizer",
+    "ShapVisualizer",
+    "LimeVisualizer",
+    "PDPVisualizer",
+    "CounterfactualVisualizer",
+    "AnchorVisualizer",
+]