xplia 1.0.1__py3-none-any.whl

xplia/core/base.py

@@ -0,0 +1,391 @@
+"""
+Classes de base et abstraites pour l'architecture de XPLIA
+=============================================================
+
+Ce module fournit les interfaces et classes abstraites qui servent
+de fondation à l'ensemble du framework d'explicabilité.
+"""
+
+import abc
+import datetime
+import json
+import uuid
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Type, Union
+
+import numpy as np
+import pandas as pd
+
+from .config import ConfigManager
+
+
+class ExplainabilityMethod(str, Enum):
+    """Méthodes d'explicabilité supportées."""
+    SHAP = "shap"
+    LIME = "lime"
+    ANCHORS = "anchors"
+    COUNTERFACTUAL = "counterfactual"
+    PDP = "partial_dependence"
+    ICE = "ice"
+    FEATURE_IMPORTANCE = "feature_importance"
+    ATTENTION = "attention"
+    GRADIENT = "gradient"
+    INTEGRATED_GRADIENTS = "integrated_gradients"
+    UNIFIED = "unified"
+
+
+class AudienceLevel(str, Enum):
+    """Niveaux d'audience pour l'explicabilité."""
+    NOVICE = "novice"          # Grand public, aucune connaissance technique
+    BASIC = "basic"            # Décideurs, managers, stakeholders business
+    INTERMEDIATE = "intermediate"  # Analystes, data analysts
+    ADVANCED = "advanced"      # Data scientists, ML engineers
+    EXPERT = "expert"          # ML researchers, experts académiques
+    # Aliases pour compatibilité
+    PUBLIC = "novice"
+    BUSINESS = "basic"
+    TECHNICAL = "advanced"
+
+
+class ModelType(str, Enum):
+    """Types de modèles pris en charge."""
+    CLASSIFICATION = "classification"
+    REGRESSION = "regression"
+    CLUSTERING = "clustering"
+    RECOMMENDER = "recommender"
+    TIME_SERIES = "time_series"
+    NLP = "nlp"
+    COMPUTER_VISION = "computer_vision"
+    REINFORCEMENT_LEARNING = "reinforcement_learning"
+    GENERATIVE = "generative"
+
+
+class ConfigurableMixin:
+    """Mixin qui ajoute des fonctionnalités de configuration."""
+    
+    def __init__(self, **kwargs):
+        """
+        Initialise l'objet configurable avec des paramètres.
+        
+        Args:
+            **kwargs: Paramètres de configuration arbitraires
+        """
+        self._config = {}
+        self._config.update(ConfigManager().get_default_config())
+        self._config.update(kwargs)
+    
+    def configure(self, **kwargs):
+        """
+        Met à jour la configuration.
+        
+        Args:
+            **kwargs: Paramètres de configuration à mettre à jour
+            
+        Returns:
+            self: Pour permettre le chaînage
+        """
+        self._config.update(kwargs)
+        return self
+    
+    def get_config(self):
+        """
+        Récupère la configuration actuelle.
+        
+        Returns:
+            dict: Configuration actuelle
+        """
+        return self._config.copy()
+
+
+class AuditableMixin:
+    """Mixin qui ajoute des fonctionnalités d'audit et de traçabilité."""
+    
+    def __init__(self):
+        """Initialise l'objet avec des capacités d'audit."""
+        self._audit_trail = []
+        self._creation_timestamp = datetime.datetime.now().isoformat()
+        self._uuid = str(uuid.uuid4())
+        
+    def add_audit_record(self, action: str, details: Dict[str, Any]) -> None:
+        """
+        Ajoute un enregistrement d'audit.
+        
+        Args:
+            action: Type d'action réalisée
+            details: Détails sur l'action
+        """
+        record = {
+            "timestamp": datetime.datetime.now().isoformat(),
+            "action": action,
+            "details": details
+        }
+        self._audit_trail.append(record)
+    
+    def get_audit_trail(self) -> List[Dict[str, Any]]:
+        """
+        Récupère tout l'historique d'audit.
+        
+        Returns:
+            list: Liste des enregistrements d'audit
+        """
+        return self._audit_trail.copy()
+    
+    def export_audit_trail(self, format: str = "json") -> Union[str, Dict]:
+        """
+        Exporte l'historique d'audit dans le format spécifié.
+        
+        Args:
+            format: Format d'export ("json" ou "dict")
+            
+        Returns:
+            Union[str, dict]: Historique d'audit au format demandé
+        """
+        if format.lower() == "json":
+            return json.dumps({
+                "uuid": self._uuid,
+                "creation_timestamp": self._creation_timestamp,
+                "audit_trail": self._audit_trail
+            }, indent=2)
+        return {
+            "uuid": self._uuid,
+            "creation_timestamp": self._creation_timestamp,
+            "audit_trail": self._audit_trail
+        }
+
+
+@dataclass
+class FeatureImportance:
+    """Classe pour stocker les importances des caractéristiques."""
+    feature_name: str
+    importance_value: float
+    importance_rank: int = 0
+    direction: str = "positive"
+    confidence_interval: Optional[Tuple[float, float]] = None
+    std_dev: Optional[float] = None
+    p_value: Optional[float] = None
+    
+    # Alias pour compatibilité
+    @property
+    def importance(self):
+        return self.importance_value
+    
+    def to_dict(self):
+        """Convertit en dictionnaire."""
+        return asdict(self)
+
+
+@dataclass
+class ExplanationQuality:
+    """Métriques de qualité d'une explication."""
+    fidelity: Optional[float] = None  # Fidélité au modèle (0-1)
+    stability: Optional[float] = None  # Stabilité des explications (0-1)
+    sparsity: Optional[float] = None  # Sparsité (proportion de features importantes)
+    consistency: Optional[float] = None  # Cohérence entre instances similaires (0-1)
+    
+    def to_dict(self):
+        """Convertit en dictionnaire."""
+        return asdict(self)
+    
+    def overall_score(self) -> float:
+        """Calcule un score global de qualité."""
+        scores = [s for s in [self.fidelity, self.stability, self.sparsity, self.consistency] if s is not None]
+        return sum(scores) / len(scores) if scores else 0.0
+
+
+class ExplanationFormat(str, Enum):
+    """Formats d'export des explications."""
+    JSON = "json"
+    HTML = "html"
+    PDF = "pdf"
+    TEXT = "text"
+    MARKDOWN = "markdown"
+    INTERACTIVE = "interactive"
+
+
+@dataclass
+class ModelMetadata:
+    """Métadonnées associées à un modèle."""
+    model_type: str
+    framework: str
+    input_shape: Tuple
+    output_shape: Tuple
+    feature_names: List[str]
+    target_names: Optional[List[str]] = None
+    model_params: Dict[str, Any] = field(default_factory=dict)
+    training_date: Optional[str] = None
+    training_dataset_hash: Optional[str] = None
+    model_version: str = "1.0.0"
+    author: Optional[str] = None
+    
+    def to_dict(self):
+        """Convertit en dictionnaire."""
+        return asdict(self)
+
+
+@dataclass
+class ExplanationResult:
+    """
+    Classe qui encapsule les résultats d'une explication.
+    
+    Cette classe standardisée permet de manipuler uniformément
+    les résultats de différentes méthodes d'explicabilité.
+    """
+    method: ExplainabilityMethod
+    model_metadata: ModelMetadata
+    feature_importances: List[FeatureImportance]
+    explanation_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    creation_timestamp: str = field(default_factory=lambda: datetime.datetime.now().isoformat())
+    raw_explanation: Any = None
+    audience_level: AudienceLevel = AudienceLevel.TECHNICAL
+    explanation_quality: float = 1.0
+    explanation_fidelity: Optional[float] = None
+    additional_metrics: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self):
+        """Convertit en dictionnaire."""
+        result = asdict(self)
+        # Convertir les sous-objets complexes
+        result["feature_importances"] = [fi.to_dict() for fi in self.feature_importances]
+        result["model_metadata"] = self.model_metadata.to_dict()
+        return result
+    
+    def to_json(self):
+        """Convertit en JSON."""
+        return json.dumps(self.to_dict())
+    
+    def save(self, path: Union[str, Path]):
+        """
+        Sauvegarde l'explication dans un fichier.
+        
+        Args:
+            path: Chemin où sauvegarder l'explication
+        """
+        path = Path(path)
+        with open(path, 'w') as f:
+            json.dump(self.to_dict(), f, indent=2)
+    
+    @classmethod
+    def load(cls, path: Union[str, Path]) -> "ExplanationResult":
+        """
+        Charge une explication depuis un fichier.
+        
+        Args:
+            path: Chemin du fichier d'explication
+            
+        Returns:
+            ExplanationResult: Instance chargée
+        """
+        path = Path(path)
+        with open(path, 'r') as f:
+            data = json.load(f)
+        
+        # Reconstruction des objets complexes
+        feature_importances = [FeatureImportance(**fi) for fi in data.pop("feature_importances")]
+        model_metadata = ModelMetadata(**data.pop("model_metadata"))
+        
+        return cls(
+            feature_importances=feature_importances,
+            model_metadata=model_metadata,
+            **data
+        )
+
+
+class ExplainerBase(abc.ABC, ConfigurableMixin, AuditableMixin):
+    """
+    Classe de base abstraite pour tous les explainers.
+    
+    Cette classe définit l'interface commune que tous les explainers
+    doivent implémenter, assurant ainsi une API uniforme.
+    """
+    
+    def __init__(self, model, **kwargs):
+        """
+        Initialise un explainer.
+        
+        Args:
+            model: Modèle à expliquer
+            **kwargs: Paramètres additionnels spécifiques à l'explainer
+        """
+        ConfigurableMixin.__init__(self, **kwargs)
+        AuditableMixin.__init__(self)
+        self._model = model
+        self._method = None
+        self._supported_model_types = []
+        self._metadata = None
+        
+        self.add_audit_record("initialization", {
+            "explainer_type": self.__class__.__name__,
+            "model_type": str(type(model)),
+            "config": self._config
+        })
+    
+    @property
+    def model(self):
+        """Récupère le modèle associé."""
+        return self._model
+    
+    @property
+    def method(self) -> ExplainabilityMethod:
+        """Récupère la méthode d'explicabilité."""
+        return self._method
+    
+    @abc.abstractmethod
+    def explain(self, X, y=None, **kwargs) -> ExplanationResult:
+        """
+        Génère des explications pour les entrées données.
+        
+        Args:
+            X: Données d'entrée à expliquer
+            y: Sorties/labels réels (optionnel)
+            **kwargs: Paramètres additionnels
+            
+        Returns:
+            ExplanationResult: Résultat standardisé de l'explication
+        """
+        pass
+    
+    @abc.abstractmethod
+    def explain_instance(self, instance, **kwargs) -> ExplanationResult:
+        """
+        Explique une instance spécifique.
+        
+        Args:
+            instance: Instance à expliquer
+            **kwargs: Paramètres additionnels
+            
+        Returns:
+            ExplanationResult: Résultat standardisé de l'explication
+        """
+        pass
+    
+    def supports_model(self, model) -> bool:
+        """
+        Vérifie si l'explainer supporte le type de modèle donné.
+        
+        Args:
+            model: Modèle à vérifier
+            
+        Returns:
+            bool: True si le modèle est supporté, False sinon
+        """
+        return type(model).__name__ in self._supported_model_types
+    
+    def get_metadata(self) -> ModelMetadata:
+        """
+        Récupère les métadonnées du modèle.
+        
+        Returns:
+            ModelMetadata: Métadonnées du modèle
+        """
+        if self._metadata is None:
+            self._extract_metadata()
+        return self._metadata
+    
+    def _extract_metadata(self) -> None:
+        """
+        Extrait les métadonnées du modèle.
+        Cette méthode doit être implémentée par les classes dérivées.
+        """
+        pass

xplia/core/config.py

@@ -0,0 +1,297 @@
+"""
+Système de configuration pour XPLIA
+=======================================
+
+Ce module fournit un système centralisé de gestion des configurations,
+permettant une personnalisation fine et cohérente de tous les composants
+de la librairie.
+"""
+
+import copy
+import json
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+
+class ConfigScope(str, Enum):
+    """Portées des configurations."""
+    GLOBAL = "global"
+    MODULE = "module"
+    INSTANCE = "instance"
+    SESSION = "session"
+
+
+class ConfigManager:
+    """
+    Gestionnaire centralisé de configuration.
+    
+    Cette classe implémente le pattern Singleton pour assurer
+    qu'une seule instance gère la configuration globale.
+    """
+    
+    _instance = None
+    _default_config = {
+        "visualization": {
+            "theme": "light",
+            "color_palette": "viridis",
+            "font_size": 12,
+            "interactive": True,
+            "export_format": "png",
+            "dpi": 300,
+        },
+        "explanation": {
+            "default_method": "unified",
+            "n_samples": 1000,
+            "include_baseline": True,
+            "randomize_seed": 42,
+            "confidence_level": 0.95,
+        },
+        "performance": {
+            "parallel_jobs": -1,
+            "cache_results": True,
+            "cache_dir": "./xplia_cache",
+            "use_gpu": "auto",
+        },
+        "logging": {
+            "level": "INFO",
+            "file": None,
+            "verbose": False,
+        },
+        "compliance": {
+            "generate_reports": True,
+            "regulations": ["gdpr", "ai_act"],
+            "documentation_level": "standard",
+            "audit_trail": True,
+        },
+        "ui": {
+            "default_audience": "technical",
+            "language": "en",
+            "show_advanced_options": True,
+            "dashboard_layout": "standard",
+        },
+    }
+    
+    def __new__(cls):
+        """Implémentation du Singleton."""
+        if cls._instance is None:
+            cls._instance = super(ConfigManager, cls).__new__(cls)
+            cls._instance._initialize()
+        return cls._instance
+    
+    def _initialize(self):
+        """Initialise l'instance avec les configurations par défaut."""
+        self._config = copy.deepcopy(self._default_config)
+        self._load_user_config()
+    
+    def _load_user_config(self):
+        """
+        Charge la configuration de l'utilisateur depuis:
+        1. Fichier de configuration global (~/.xplia/config.json)
+        2. Variables d'environnement (XPLIA_*)
+        3. Fichier de projet local (./.xplia_config.json)
+        """
+        # Fichier de configuration global
+        global_config_path = Path.home() / ".xplia" / "config.json"
+        if global_config_path.exists():
+            try:
+                with open(global_config_path, 'r') as f:
+                    global_config = json.load(f)
+                self._update_recursive(self._config, global_config)
+            except Exception as e:
+                # Utiliser un logger ici
+                print(f"Erreur lors du chargement de la configuration globale: {e}")
+        
+        # Variables d'environnement
+        env_prefix = "XPLIA_"
+        for env_var, value in os.environ.items():
+            if env_var.startswith(env_prefix):
+                # Format attendu: XPLIA_SECTION_KEY=value
+                # Exemple: XPLIA_VISUALIZATION_THEME=dark
+                parts = env_var[len(env_prefix):].lower().split('_', 1)
+                if len(parts) == 2:
+                    section, key = parts
+                    if section in self._config and key in self._config[section]:
+                        # Conversion de type basique (str vers int, float, bool)
+                        orig_type = type(self._config[section][key])
+                        if orig_type == bool:
+                            self._config[section][key] = value.lower() in ('true', 'yes', '1')
+                        elif orig_type == int:
+                            self._config[section][key] = int(value)
+                        elif orig_type == float:
+                            self._config[section][key] = float(value)
+                        else:
+                            self._config[section][key] = value
+        
+        # Fichier de projet local
+        local_config_path = Path.cwd() / ".xplia_config.json"
+        if local_config_path.exists():
+            try:
+                with open(local_config_path, 'r') as f:
+                    local_config = json.load(f)
+                self._update_recursive(self._config, local_config)
+            except Exception as e:
+                # Utiliser un logger ici
+                print(f"Erreur lors du chargement de la configuration locale: {e}")
+    
+    def _update_recursive(self, target: Dict, source: Dict):
+        """
+        Met à jour récursivement un dictionnaire cible avec les valeurs d'un dictionnaire source.
+        
+        Args:
+            target: Dictionnaire à mettre à jour
+            source: Dictionnaire contenant les nouvelles valeurs
+        """
+        for key, value in source.items():
+            if key in target and isinstance(target[key], dict) and isinstance(value, dict):
+                self._update_recursive(target[key], value)
+            else:
+                target[key] = value
+    
+    def get_config(self, section: Optional[str] = None, key: Optional[str] = None) -> Any:
+        """
+        Récupère une valeur de configuration.
+        
+        Args:
+            section: Section de configuration (optionnel)
+            key: Clé de configuration dans la section (optionnel)
+            
+        Returns:
+            Any: Valeur de configuration ou sous-dictionnaire
+            
+        Raises:
+            KeyError: Si la section ou la clé n'existe pas
+        """
+        if section is None:
+            return copy.deepcopy(self._config)
+        
+        if section not in self._config:
+            raise KeyError(f"Section de configuration non trouvée: {section}")
+        
+        if key is None:
+            return copy.deepcopy(self._config[section])
+        
+        if key not in self._config[section]:
+            raise KeyError(f"Clé de configuration non trouvée: {key} dans la section {section}")
+        
+        return copy.deepcopy(self._config[section][key])
+    
+    def set_config(self, section: str, key: str, value: Any) -> None:
+        """
+        Définit une valeur de configuration.
+        
+        Args:
+            section: Section de configuration
+            key: Clé de configuration dans la section
+            value: Nouvelle valeur
+            
+        Raises:
+            KeyError: Si la section n'existe pas
+        """
+        if section not in self._config:
+            raise KeyError(f"Section de configuration non trouvée: {section}")
+        
+        self._config[section][key] = value
+    
+    def update_section(self, section: str, values: Dict[str, Any]) -> None:
+        """
+        Met à jour une section entière de la configuration.
+        
+        Args:
+            section: Section à mettre à jour
+            values: Nouvelles valeurs
+            
+        Raises:
+            KeyError: Si la section n'existe pas
+        """
+        if section not in self._config:
+            raise KeyError(f"Section de configuration non trouvée: {section}")
+        
+        self._config[section].update(values)
+    
+    def reset(self, section: Optional[str] = None, key: Optional[str] = None) -> None:
+        """
+        Réinitialise la configuration aux valeurs par défaut.
+        
+        Args:
+            section: Section à réinitialiser (optionnel)
+            key: Clé à réinitialiser dans la section (optionnel)
+        """
+        if section is None:
+            self._config = copy.deepcopy(self._default_config)
+            return
+        
+        if section not in self._default_config:
+            return
+        
+        if key is None:
+            self._config[section] = copy.deepcopy(self._default_config[section])
+            return
+        
+        if key not in self._default_config[section]:
+            return
+        
+        self._config[section][key] = copy.deepcopy(self._default_config[section][key])
+    
+    def save_user_config(self, path: Optional[Union[str, Path]] = None,
+                        scope: ConfigScope = ConfigScope.GLOBAL) -> None:
+        """
+        Sauvegarde la configuration actuelle.
+        
+        Args:
+            path: Chemin du fichier de configuration (optionnel)
+            scope: Portée de la configuration (détermine le chemin par défaut)
+        """
+        if path is None:
+            if scope == ConfigScope.GLOBAL:
+                path = Path.home() / ".xplia" / "config.json"
+            elif scope == ConfigScope.SESSION:
+                path = Path.cwd() / ".xplia_config.json"
+            else:
+                # Pour d'autres portées, utiliser le répertoire courant
+                path = Path.cwd() / ".xplia_config.json"
+        
+        path = Path(path)
+        
+        # S'assurer que le répertoire parent existe
+        path.parent.mkdir(parents=True, exist_ok=True)
+        
+        with open(path, 'w') as f:
+            json.dump(self._config, f, indent=2)
+    
+    def get_default_config(self) -> Dict[str, Any]:
+        """
+        Récupère la configuration par défaut.
+        
+        Returns:
+            Dict[str, Any]: Configuration par défaut
+        """
+        return copy.deepcopy(self._default_config)
+
+
+# Fonctions utilitaires pour accéder au gestionnaire de configuration
+def get_config(section: Optional[str] = None, key: Optional[str] = None) -> Any:
+    """
+    Récupère une valeur de configuration.
+    
+    Args:
+        section: Section de configuration (optionnel)
+        key: Clé de configuration dans la section (optionnel)
+        
+    Returns:
+        Any: Valeur de configuration
+    """
+    return ConfigManager().get_config(section, key)
+
+
+def set_config(section: str, key: str, value: Any) -> None:
+    """
+    Définit une valeur de configuration.
+    
+    Args:
+        section: Section de configuration
+        key: Clé de configuration dans la section
+        value: Nouvelle valeur
+    """
+    ConfigManager().set_config(section, key, value)