xplia 1.0.1__py3-none-any.whl

xplia/explainers/multimodal/foundation_model_explainer.py

@@ -0,0 +1,323 @@
+"""
+Explainer pour modèles de fondation (Foundation Models)
+====================================================
+
+Ce module implémente un explainer spécialisé pour les modèles de fondation comme
+GPT-5, Claude 3, Gemini Ultra 2.0 et autres grands modèles de langage et multimodaux.
+"""
+
+import time
+import logging
+import json
+from typing import Any, Dict, List, Optional, Tuple, Union, Set
+from dataclasses import dataclass, field
+import numpy as np
+
+from .base import (
+    MultimodalExplainerBase, DataModality, ModalityExplanation, 
+    MultimodalExplanationResult
+)
+from .registry import register_multimodal_explainer
+from ...core.base import ExplainabilityMethod, AudienceLevel, ExplanationQuality
+from ...core.optimizations import optimize, cached_call, parallel_map
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AttentionLayer:
+    """Représentation d'une couche d'attention dans un modèle de fondation."""
+    layer_name: str
+    attention_heads: Dict[str, np.ndarray]
+    aggregated_attention: np.ndarray
+
+
+@dataclass
+class FoundationModelInsight:
+    """Informations d'explicabilité extraites d'un modèle de fondation."""
+    attention_patterns: Dict[str, AttentionLayer] = field(default_factory=dict)
+    token_attributions: Dict[str, float] = field(default_factory=dict)
+    reasoning_path: List[Dict[str, Any]] = field(default_factory=list)
+    confidence_scores: Dict[str, float] = field(default_factory=dict)
+    counterfactual_examples: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@register_multimodal_explainer("foundation_model")
+class FoundationModelExplainer(MultimodalExplainerBase):
+    """
+    Explainer spécialisé pour les modèles de fondation (GPT-5, Claude 3, etc.).
+    
+    Cet explainer utilise des techniques avancées pour explorer et expliquer le
+    fonctionnement interne des grands modèles de langage et multimodaux, y compris
+    l'analyse des motifs d'attention, l'attribution de tokens, et la génération
+    de chemins de raisonnement explicites.
+    """
+    
+    supported_modalities = {
+        DataModality.TEXT, DataModality.IMAGE, 
+        DataModality.AUDIO, DataModality.VIDEO
+    }
+    
+    def __init__(self, 
+                 model: Any,
+                 model_family: str = "generic",
+                 api_key: Optional[str] = None,
+                 explanation_depth: str = "detailed",
+                 max_tokens_per_request: int = 8000,
+                 device: str = "cpu",
+                 explanation_method: ExplainabilityMethod = ExplainabilityMethod.MODEL_SPECIFIC,
+                 audience_level: AudienceLevel = AudienceLevel.TECHNICAL,
+                 **kwargs):
+        """
+        Initialise l'explainer pour modèles de fondation.
+        
+        Args:
+            model: Le modèle de fondation à expliquer
+            model_family: Famille du modèle ("gpt", "claude", "gemini", etc.)
+            api_key: Clé API pour les modèles accessibles via API
+            explanation_depth: Niveau de détail des explications ("high", "detailed", "comprehensive")
+            max_tokens_per_request: Limite de tokens par requête API
+            device: Appareil d'exécution
+            explanation_method: Méthode d'explicabilité
+            audience_level: Niveau d'audience ciblé
+            **kwargs: Paramètres additionnels
+        """
+        super().__init__(
+            model=model,
+            modalities=self.supported_modalities,
+            explanation_method=explanation_method,
+            audience_level=audience_level,
+            **kwargs
+        )
+        
+        self.model_family = model_family.lower()
+        self.api_key = api_key
+        self.explanation_depth = explanation_depth
+        self.max_tokens = max_tokens_per_request
+        self.device = device
+        
+        # Configuration spécifique selon la famille du modèle
+        self._configure_for_model_family()
+        
+    def initialize_modality_explainers(self):
+        """Initialise les explainers spécifiques pour chaque modalité."""
+        # Pour les modèles de fondation, nous utilisons principalement
+        # des techniques d'analyse spécifiques au modèle plutôt que
+        # des explainers génériques par modalité
+        pass
+    
+    def _configure_for_model_family(self):
+        """Configure l'explainer selon la famille spécifique du modèle."""
+        if self.model_family == "gpt":
+            self.extract_attention = self._extract_gpt_attention
+            self.analyze_reasoning = self._analyze_gpt_reasoning
+            self.generate_counterfactuals = self._generate_gpt_counterfactuals
+        elif self.model_family == "claude":
+            self.extract_attention = self._extract_claude_attention
+            self.analyze_reasoning = self._analyze_claude_reasoning
+            self.generate_counterfactuals = self._generate_claude_counterfactuals
+        elif self.model_family == "gemini":
+            self.extract_attention = self._extract_gemini_attention
+            self.analyze_reasoning = self._analyze_gemini_reasoning
+            self.generate_counterfactuals = self._generate_gemini_counterfactuals
+        else:
+            # Comportement par défaut pour les modèles génériques
+            self.extract_attention = self._extract_generic_attention
+            self.analyze_reasoning = self._analyze_generic_reasoning
+            self.generate_counterfactuals = self._generate_generic_counterfactuals
+    
+    def explain_modality(self, 
+                       modality: DataModality, 
+                       inputs: Any, 
+                       **kwargs) -> ModalityExplanation:
+        """
+        Génère une explication pour une modalité spécifique.
+        
+        Pour les modèles de fondation, cette méthode est moins pertinente
+        car nous analysons généralement le modèle dans son ensemble plutôt
+        que par modalité individuelle.
+        
+        Args:
+            modality: La modalité à expliquer
+            inputs: Les données d'entrée pour cette modalité
+            **kwargs: Paramètres additionnels
+            
+        Returns:
+            Une explication pour la modalité spécifiée
+        """
+        if modality == DataModality.TEXT:
+            explanation = self._explain_text_modality(inputs, **kwargs)
+            contribution = self._estimate_text_contribution(inputs, **kwargs)
+        elif modality == DataModality.IMAGE:
+            explanation = self._explain_image_modality(inputs, **kwargs)
+            contribution = self._estimate_image_contribution(inputs, **kwargs)
+        elif modality == DataModality.AUDIO:
+            explanation = self._explain_audio_modality(inputs, **kwargs)
+            contribution = self._estimate_audio_contribution(inputs, **kwargs)
+        elif modality == DataModality.VIDEO:
+            explanation = self._explain_video_modality(inputs, **kwargs)
+            contribution = self._estimate_video_contribution(inputs, **kwargs)
+        else:
+            raise ValueError(f"Modalité non supportée: {modality}")
+        
+        # Estimation de la confiance dans l'explication
+        confidence = self._estimate_explanation_confidence(modality, explanation)
+        
+        return ModalityExplanation(
+            modality=modality,
+            explanation=explanation,
+            confidence=confidence,
+            contribution=contribution
+        )
+    
+    def _analyze_cross_modal_interactions(self,
+                                         inputs: Dict[DataModality, Any],
+                                         explanations: List[ModalityExplanation]
+                                         ) -> Dict[Tuple[DataModality, DataModality], float]:
+        """
+        Analyse les interactions entre les différentes modalités.
+        
+        Pour les modèles de fondation, cette méthode est particulièrement importante
+        car elle permet de comprendre comment le modèle fusionne les informations
+        provenant de différentes modalités.
+        
+        Args:
+            inputs: Dictionnaire des entrées par modalité
+            explanations: Liste des explications par modalité
+            
+        Returns:
+            Dictionnaire des scores d'interaction entre modalités
+        """
+        interactions = {}
+        
+        # Analyser les interactions entre chaque paire de modalités
+        modalities = list(inputs.keys())
+        for i, mod1 in enumerate(modalities):
+            for j, mod2 in enumerate(modalities[i+1:], i+1):
+                interaction_score = self._compute_modality_interaction(
+                    mod1, inputs[mod1], mod2, inputs[mod2]
+                )
+                interactions[(mod1, mod2)] = interaction_score
+        
+        return interactions
+    
+    def _explain_fusion_mechanism(self,
+                                 inputs: Dict[DataModality, Any],
+                                 explanations: List[ModalityExplanation],
+                                 **kwargs) -> Dict[str, Any]:
+        """
+        Explique le mécanisme de fusion des modalités dans le modèle de fondation.
+        
+        Args:
+            inputs: Dictionnaire des entrées par modalité
+            explanations: Liste des explications par modalité
+            **kwargs: Paramètres additionnels
+            
+        Returns:
+            Dictionnaire décrivant le mécanisme de fusion
+        """
+        if self.model_family == "gpt":
+            return self._explain_gpt_fusion(inputs, explanations, **kwargs)
+        elif self.model_family == "claude":
+            return self._explain_claude_fusion(inputs, explanations, **kwargs)
+        elif self.model_family == "gemini":
+            return self._explain_gemini_fusion(inputs, explanations, **kwargs)
+        else:
+            return self._explain_generic_fusion(inputs, explanations, **kwargs)
+    
+    # Méthodes spécifiques à la famille GPT
+    
+    def _extract_gpt_attention(self, inputs, **kwargs):
+        """Extrait les motifs d'attention d'un modèle GPT."""
+        # Implémentation spécifique à GPT
+        pass
+    
+    def _analyze_gpt_reasoning(self, inputs, **kwargs):
+        """Analyse le processus de raisonnement d'un modèle GPT."""
+        # Implémentation spécifique à GPT
+        pass
+    
+    def _generate_gpt_counterfactuals(self, inputs, **kwargs):
+        """Génère des exemples contrefactuels pour un modèle GPT."""
+        # Implémentation spécifique à GPT
+        pass
+    
+    def _explain_gpt_fusion(self, inputs, explanations, **kwargs):
+        """Explique le mécanisme de fusion de modalités dans un modèle GPT."""
+        # Implémentation spécifique à GPT
+        return {
+            "mechanism": "transformer_fusion",
+            "description": "Fusion par attention multi-têtes cross-modales",
+            "architecture": "transformer_decoder_only",
+            "fusion_strategy": "late_fusion_with_attention_pooling"
+        }
+    
+    # Méthodes spécifiques à la famille Claude
+    
+    def _extract_claude_attention(self, inputs, **kwargs):
+        """Extrait les motifs d'attention d'un modèle Claude."""
+        # Implémentation spécifique à Claude
+        pass
+    
+    def _analyze_claude_reasoning(self, inputs, **kwargs):
+        """Analyse le processus de raisonnement d'un modèle Claude."""
+        # Implémentation spécifique à Claude
+        pass
+    
+    def _generate_claude_counterfactuals(self, inputs, **kwargs):
+        """Génère des exemples contrefactuels pour un modèle Claude."""
+        # Implémentation spécifique à Claude
+        pass
+    
+    def _explain_claude_fusion(self, inputs, explanations, **kwargs):
+        """Explique le mécanisme de fusion de modalités dans un modèle Claude."""
+        # Implémentation spécifique à Claude
+        return {
+            "mechanism": "constitutional_fusion",
+            "description": "Fusion contrainte par des principes constitutionnels",
+            "architecture": "constitutional_ai",
+            "fusion_strategy": "hierarchical_cross_attention"
+        }
+    
+    # Méthodes génériques
+    
+    def _extract_generic_attention(self, inputs, **kwargs):
+        """Méthode générique pour extraire l'attention."""
+        # Implémentation générique
+        pass
+    
+    def _analyze_generic_reasoning(self, inputs, **kwargs):
+        """Méthode générique pour analyser le raisonnement."""
+        # Implémentation générique
+        pass
+    
+    def _generate_generic_counterfactuals(self, inputs, **kwargs):
+        """Méthode générique pour générer des contrefactuels."""
+        # Implémentation générique
+        pass
+    
+    def _explain_generic_fusion(self, inputs, explanations, **kwargs):
+        """Explique un mécanisme de fusion générique."""
+        # Implémentation générique
+        return {
+            "mechanism": "unknown",
+            "description": "Mécanisme de fusion non spécifié",
+            "architecture": "foundation_model",
+            "fusion_strategy": "unknown"
+        }
+    
+    def _compute_modality_interaction(self, mod1, input1, mod2, input2):
+        """
+        Calcule le score d'interaction entre deux modalités.
+        
+        Args:
+            mod1: Première modalité
+            input1: Entrée pour la première modalité
+            mod2: Deuxième modalité
+            input2: Entrée pour la deuxième modalité
+            
+        Returns:
+            Score d'interaction entre 0 et 1
+        """
+        # Implémentation générique
+        return 0.5  # Valeur par défaut

xplia/explainers/multimodal/registry.py

@@ -0,0 +1,139 @@
+"""
+Registre des explainers multimodaux
+===================================
+
+Ce module fournit un mécanisme de registre pour découvrir et 
+enregistrer dynamiquement les explainers multimodaux.
+"""
+
+import inspect
+from typing import Any, Callable, Dict, List, Type, Set, Optional
+
+from .base import MultimodalExplainerBase, DataModality
+
+
+# Registre global des explainers multimodaux
+_MULTIMODAL_EXPLAINER_REGISTRY: Dict[str, Type[MultimodalExplainerBase]] = {}
+_MULTIMODAL_EXPLAINER_BY_MODALITY: Dict[DataModality, List[Type[MultimodalExplainerBase]]] = {
+    modality: [] for modality in DataModality
+}
+
+
+def register_multimodal_explainer(name: Optional[str] = None) -> Callable:
+    """
+    Décorateur pour enregistrer un explainer multimodal dans le registre global.
+    
+    Args:
+        name: Nom d'enregistrement optionnel (par défaut: nom de la classe)
+        
+    Returns:
+        Décorateur d'enregistrement
+    """
+    def decorator(cls: Type[MultimodalExplainerBase]) -> Type[MultimodalExplainerBase]:
+        # Vérifier que la classe hérite bien de MultimodalExplainerBase
+        if not inspect.isclass(cls) or not issubclass(cls, MultimodalExplainerBase):
+            raise TypeError(
+                f"Le décorateur register_multimodal_explainer ne peut être appliqué qu'à "
+                f"des classes dérivant de MultimodalExplainerBase, pas à {cls.__name__}"
+            )
+        
+        # Déterminer le nom d'enregistrement
+        registry_name = name or cls.__name__
+        
+        # Enregistrer l'explainer dans le registre global
+        if registry_name in _MULTIMODAL_EXPLAINER_REGISTRY:
+            raise ValueError(
+                f"Un explainer multimodal nommé '{registry_name}' existe déjà dans le registre"
+            )
+        
+        _MULTIMODAL_EXPLAINER_REGISTRY[registry_name] = cls
+        
+        # Enregistrer l'explainer par modalité
+        for modality in cls.supported_modalities:
+            _MULTIMODAL_EXPLAINER_BY_MODALITY[modality].append(cls)
+        
+        # Ajouter un attribut à la classe pour faciliter l'introspection
+        cls._registry_name = registry_name
+        
+        return cls
+    
+    return decorator
+
+
+def get_multimodal_explainer(name: str) -> Type[MultimodalExplainerBase]:
+    """
+    Récupère un explainer multimodal par son nom.
+    
+    Args:
+        name: Nom de l'explainer à récupérer
+        
+    Returns:
+        Classe d'explainer multimodal
+        
+    Raises:
+        KeyError: Si aucun explainer avec ce nom n'est enregistré
+    """
+    if name not in _MULTIMODAL_EXPLAINER_REGISTRY:
+        raise KeyError(f"Aucun explainer multimodal nommé '{name}' n'est enregistré")
+    
+    return _MULTIMODAL_EXPLAINER_REGISTRY[name]
+
+
+def list_multimodal_explainers() -> List[str]:
+    """
+    Liste tous les explainers multimodaux enregistrés.
+    
+    Returns:
+        Liste des noms d'explainers multimodaux enregistrés
+    """
+    return list(_MULTIMODAL_EXPLAINER_REGISTRY.keys())
+
+
+def find_explainers_for_modalities(modalities: Set[DataModality]) -> List[Type[MultimodalExplainerBase]]:
+    """
+    Trouve tous les explainers supportant un ensemble de modalités.
+    
+    Args:
+        modalities: Ensemble des modalités requises
+        
+    Returns:
+        Liste des classes d'explainers supportant toutes les modalités spécifiées
+    """
+    candidates = []
+    
+    for explainer_cls in _MULTIMODAL_EXPLAINER_REGISTRY.values():
+        if modalities.issubset(explainer_cls.supported_modalities):
+            candidates.append(explainer_cls)
+    
+    return candidates
+
+
+def create_multimodal_explainer(modalities: Set[DataModality], 
+                               model: Any, 
+                               **kwargs) -> MultimodalExplainerBase:
+    """
+    Crée automatiquement un explainer multimodal adapté aux modalités spécifiées.
+    
+    Args:
+        modalities: Ensemble des modalités à expliquer
+        model: Modèle à expliquer
+        **kwargs: Arguments additionnels à passer au constructeur de l'explainer
+        
+    Returns:
+        Instance d'explainer multimodal
+        
+    Raises:
+        ValueError: Si aucun explainer ne supporte les modalités spécifiées
+    """
+    candidates = find_explainers_for_modalities(modalities)
+    
+    if not candidates:
+        raise ValueError(
+            f"Aucun explainer multimodal ne supporte toutes les modalités: {modalities}"
+        )
+    
+    # Choisir le premier explainer compatible
+    # Note: Une logique plus sophistiquée pourrait être implémentée ici
+    explainer_cls = candidates[0]
+    
+    return explainer_cls(model=model, modalities=modalities, **kwargs)