xplia 1.0.1__py3-none-any.whl

xplia/explainers/calibration/audience_profiles.py

@@ -0,0 +1,372 @@
+"""
+Profils d'Audience et Gestion des Utilisateurs
+===========================================
+
+Ce module implémente la gestion des profils d'utilisateurs et d'audience
+pour permettre une adaptation personnalisée des explications.
+"""
+
+import logging
+from typing import Dict, List, Optional, Set, Any
+from enum import Enum, auto
+from dataclasses import dataclass, field
+import json
+import os
+import time
+
+from ...core.base import AudienceLevel
+
+
+class ExplanationPreference(Enum):
+    """Préférences d'explication des utilisateurs."""
+    VISUAL = auto()         # Préfère les explications visuelles
+    TEXTUAL = auto()        # Préfère les explications textuelles
+    TECHNICAL = auto()      # Préfère les détails techniques
+    SIMPLIFIED = auto()     # Préfère les explications simplifiées
+    COMPREHENSIVE = auto()  # Préfère les explications exhaustives
+    CONCISE = auto()        # Préfère les explications concises
+    INTERACTIVE = auto()    # Préfère les explications interactives
+    COMPARATIVE = auto()    # Préfère les comparaisons
+
+
+class DomainExpertise(Enum):
+    """Niveaux d'expertise dans différents domaines."""
+    NOVICE = 1
+    BASIC = 2
+    INTERMEDIATE = 3
+    ADVANCED = 4
+    EXPERT = 5
+
+
+@dataclass
+class UserProfile:
+    """
+    Profil d'un utilisateur avec ses préférences et son niveau d'expertise.
+    """
+    user_id: str
+    name: Optional[str] = None
+    audience_level: AudienceLevel = AudienceLevel.TECHNICAL
+    preferences: Set[ExplanationPreference] = field(default_factory=set)
+    domain_expertise: Dict[str, DomainExpertise] = field(default_factory=dict)
+    language: str = "fr"
+    interaction_history: List[Dict[str, Any]] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    
+    def update_preference(self, preference: ExplanationPreference, add: bool = True) -> None:
+        """
+        Ajoute ou supprime une préférence d'explication.
+        
+        Args:
+            preference: La préférence à modifier
+            add: Si True, ajoute la préférence; sinon la supprime
+        """
+        if add:
+            self.preferences.add(preference)
+        elif preference in self.preferences:
+            self.preferences.remove(preference)
+        
+        self.updated_at = time.time()
+    
+    def set_expertise(self, domain: str, level: DomainExpertise) -> None:
+        """
+        Définit le niveau d'expertise dans un domaine spécifique.
+        
+        Args:
+            domain: Le domaine concerné
+            level: Le niveau d'expertise
+        """
+        self.domain_expertise[domain] = level
+        self.updated_at = time.time()
+    
+    def record_interaction(self, 
+                          explanation_id: str, 
+                          feedback: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Enregistre une interaction avec une explication.
+        
+        Args:
+            explanation_id: Identifiant de l'explication
+            feedback: Retour d'information sur l'explication (optionnel)
+        """
+        self.interaction_history.append({
+            "explanation_id": explanation_id,
+            "timestamp": time.time(),
+            "feedback": feedback or {}
+        })
+        self.updated_at = time.time()
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convertit le profil en dictionnaire pour la sérialisation.
+        
+        Returns:
+            Dictionnaire représentant le profil
+        """
+        return {
+            "user_id": self.user_id,
+            "name": self.name,
+            "audience_level": self.audience_level.value,
+            "preferences": [pref.name for pref in self.preferences],
+            "domain_expertise": {domain: level.value for domain, level in self.domain_expertise.items()},
+            "language": self.language,
+            "interaction_history": self.interaction_history,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'UserProfile':
+        """
+        Crée un profil à partir d'un dictionnaire.
+        
+        Args:
+            data: Dictionnaire contenant les données du profil
+            
+        Returns:
+            Instance de UserProfile
+        """
+        preferences = set()
+        for pref_name in data.get("preferences", []):
+            try:
+                preferences.add(ExplanationPreference[pref_name])
+            except KeyError:
+                logging.warning(f"Préférence inconnue ignorée: {pref_name}")
+        
+        domain_expertise = {}
+        for domain, level_value in data.get("domain_expertise", {}).items():
+            try:
+                domain_expertise[domain] = DomainExpertise(level_value)
+            except ValueError:
+                logging.warning(f"Niveau d'expertise invalide ignoré pour {domain}: {level_value}")
+        
+        return cls(
+            user_id=data["user_id"],
+            name=data.get("name"),
+            audience_level=AudienceLevel(data.get("audience_level", AudienceLevel.TECHNICAL.value)),
+            preferences=preferences,
+            domain_expertise=domain_expertise,
+            language=data.get("language", "fr"),
+            interaction_history=data.get("interaction_history", []),
+            created_at=data.get("created_at", time.time()),
+            updated_at=data.get("updated_at", time.time())
+        )
+
+
+class AudienceProfileManager:
+    """
+    Gestionnaire de profils d'utilisateurs et d'audience.
+    """
+    
+    def __init__(self, storage_path: Optional[str] = None):
+        """
+        Initialise le gestionnaire de profils.
+        
+        Args:
+            storage_path: Chemin vers le stockage des profils (optionnel)
+        """
+        self.profiles: Dict[str, UserProfile] = {}
+        self.storage_path = storage_path
+        
+        # Charger les profils existants si un chemin de stockage est spécifié
+        if storage_path and os.path.exists(storage_path):
+            self._load_profiles()
+    
+    def get_profile(self, user_id: str) -> UserProfile:
+        """
+        Récupère le profil d'un utilisateur, ou en crée un nouveau si inexistant.
+        
+        Args:
+            user_id: Identifiant de l'utilisateur
+            
+        Returns:
+            Profil de l'utilisateur
+        """
+        if user_id not in self.profiles:
+            self.profiles[user_id] = UserProfile(user_id=user_id)
+        
+        return self.profiles[user_id]
+    
+    def update_profile(self, profile: UserProfile) -> None:
+        """
+        Met à jour un profil d'utilisateur.
+        
+        Args:
+            profile: Profil à mettre à jour
+        """
+        profile.updated_at = time.time()
+        self.profiles[profile.user_id] = profile
+        
+        # Sauvegarder les profils si un chemin de stockage est spécifié
+        if self.storage_path:
+            self._save_profiles()
+    
+    def delete_profile(self, user_id: str) -> bool:
+        """
+        Supprime un profil d'utilisateur.
+        
+        Args:
+            user_id: Identifiant de l'utilisateur
+            
+        Returns:
+            True si le profil a été supprimé, False sinon
+        """
+        if user_id in self.profiles:
+            del self.profiles[user_id]
+            
+            # Sauvegarder les profils si un chemin de stockage est spécifié
+            if self.storage_path:
+                self._save_profiles()
+            
+            return True
+        
+        return False
+    
+    def _load_profiles(self) -> None:
+        """Charge les profils depuis le stockage."""
+        try:
+            with open(self.storage_path, 'r', encoding='utf-8') as f:
+                profiles_data = json.load(f)
+                
+                for profile_data in profiles_data:
+                    try:
+                        profile = UserProfile.from_dict(profile_data)
+                        self.profiles[profile.user_id] = profile
+                    except Exception as e:
+                        logging.error(f"Erreur lors du chargement du profil: {str(e)}")
+                
+                logging.info(f"Chargement de {len(self.profiles)} profils utilisateur")
+        except Exception as e:
+            logging.error(f"Erreur lors du chargement des profils: {str(e)}")
+    
+    def _save_profiles(self) -> None:
+        """Sauvegarde les profils dans le stockage."""
+        try:
+            # Créer le répertoire parent si nécessaire
+            os.makedirs(os.path.dirname(self.storage_path), exist_ok=True)
+            
+            profiles_data = [profile.to_dict() for profile in self.profiles.values()]
+            
+            with open(self.storage_path, 'w', encoding='utf-8') as f:
+                json.dump(profiles_data, f, ensure_ascii=False, indent=2)
+                
+            logging.info(f"Sauvegarde de {len(self.profiles)} profils utilisateur")
+        except Exception as e:
+            logging.error(f"Erreur lors de la sauvegarde des profils: {str(e)}")
+    
+    def get_audience_segment(self, 
+                           criteria: Dict[str, Any]) -> List[UserProfile]:
+        """
+        Récupère un segment d'audience selon des critères spécifiques.
+        
+        Args:
+            criteria: Critères de segmentation
+            
+        Returns:
+            Liste des profils correspondant aux critères
+        """
+        matching_profiles = []
+        
+        for profile in self.profiles.values():
+            match = True
+            
+            # Vérifier chaque critère
+            for key, value in criteria.items():
+                if key == "audience_level" and hasattr(profile, key):
+                    if getattr(profile, key) != value:
+                        match = False
+                        break
+                elif key == "preferences" and hasattr(profile, key):
+                    if not all(pref in profile.preferences for pref in value):
+                        match = False
+                        break
+                elif key == "domain_expertise" and hasattr(profile, key):
+                    for domain, level in value.items():
+                        if domain not in profile.domain_expertise or profile.domain_expertise[domain] < level:
+                            match = False
+                            break
+                elif key == "language" and hasattr(profile, key):
+                    if getattr(profile, key) != value:
+                        match = False
+                        break
+            
+            if match:
+                matching_profiles.append(profile)
+        
+        return matching_profiles
+    
+    def analyze_audience_preferences(self) -> Dict[str, Any]:
+        """
+        Analyse les préférences globales de l'audience.
+        
+        Returns:
+            Statistiques sur les préférences de l'audience
+        """
+        if not self.profiles:
+            return {}
+        
+        # Compteurs pour les différentes préférences et niveaux
+        preference_counts = {pref: 0 for pref in ExplanationPreference}
+        audience_level_counts = {level: 0 for level in AudienceLevel}
+        domain_expertise = {}
+        languages = {}
+        
+        # Analyser tous les profils
+        for profile in self.profiles.values():
+            # Compter les préférences
+            for pref in profile.preferences:
+                preference_counts[pref] += 1
+            
+            # Compter les niveaux d'audience
+            audience_level_counts[profile.audience_level] += 1
+            
+            # Agréger l'expertise par domaine
+            for domain, level in profile.domain_expertise.items():
+                if domain not in domain_expertise:
+                    domain_expertise[domain] = {}
+                
+                if level not in domain_expertise[domain]:
+                    domain_expertise[domain][level] = 0
+                
+                domain_expertise[domain][level] += 1
+            
+            # Compter les langues
+            if profile.language not in languages:
+                languages[profile.language] = 0
+            
+            languages[profile.language] += 1
+        
+        # Calculer les pourcentages
+        total_profiles = len(self.profiles)
+        
+        preference_stats = {
+            pref.name: {
+                "count": count,
+                "percentage": (count / total_profiles) * 100
+            }
+            for pref, count in preference_counts.items() if count > 0
+        }
+        
+        audience_level_stats = {
+            level.name: {
+                "count": count,
+                "percentage": (count / total_profiles) * 100
+            }
+            for level, count in audience_level_counts.items() if count > 0
+        }
+        
+        language_stats = {
+            lang: {
+                "count": count,
+                "percentage": (count / total_profiles) * 100
+            }
+            for lang, count in languages.items()
+        }
+        
+        return {
+            "total_profiles": total_profiles,
+            "preferences": preference_stats,
+            "audience_levels": audience_level_stats,
+            "domain_expertise": domain_expertise,
+            "languages": language_stats
+        }

xplia/explainers/calibration/calibration_metrics.py

@@ -0,0 +1,299 @@
+"""
+Métriques de Calibration
+=====================
+
+Ce module implémente diverses métriques pour évaluer la qualité
+des explications et guider le processus d'auto-calibration.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple, Union
+import numpy as np
+from dataclasses import dataclass
+import time
+
+from ...core.base import ExplanationResult
+
+
+class CalibrationMetrics:
+    """
+    Métriques pour évaluer et optimiser la calibration des explications.
+    """
+    
+    def __init__(self):
+        """Initialise les métriques de calibration."""
+        pass
+    
+    def evaluate_explanation(self, 
+                           explanation: ExplanationResult,
+                           ground_truth: Optional[Any] = None,
+                           user_feedback: Optional[Dict[str, Any]] = None) -> Dict[str, float]:
+        """
+        Évalue une explication selon diverses métriques.
+        
+        Args:
+            explanation: L'explication à évaluer
+            ground_truth: Vérité terrain (optionnel)
+            user_feedback: Feedback utilisateur (optionnel)
+            
+        Returns:
+            Dictionnaire des scores de métriques
+        """
+        metrics = {}
+        
+        # Évaluer la complexité
+        metrics["complexity_score"] = self.measure_complexity(explanation)
+        
+        # Évaluer la concision
+        metrics["conciseness_score"] = self.measure_conciseness(explanation)
+        
+        # Évaluer la cohérence
+        metrics["coherence_score"] = self.measure_coherence(explanation)
+        
+        # Si une vérité terrain est disponible, évaluer la fidélité
+        if ground_truth is not None:
+            metrics["fidelity_score"] = self.measure_fidelity(explanation, ground_truth)
+        
+        # Si un feedback utilisateur est disponible, évaluer la satisfaction
+        if user_feedback is not None:
+            metrics["user_satisfaction"] = self.measure_user_satisfaction(user_feedback)
+        
+        # Calculer un score global
+        available_scores = [score for score in metrics.values() if isinstance(score, (int, float))]
+        if available_scores:
+            metrics["overall_score"] = sum(available_scores) / len(available_scores)
+        
+        return metrics
+    
+    def measure_complexity(self, explanation: ExplanationResult) -> float:
+        """
+        Mesure la complexité d'une explication.
+        
+        Args:
+            explanation: L'explication à évaluer
+            
+        Returns:
+            Score de complexité entre 0 et 1
+        """
+        # Dans une implémentation réelle, cette méthode pourrait:
+        # 1. Analyser la complexité linguistique du texte
+        # 2. Compter le nombre de termes techniques
+        # 3. Évaluer la complexité des visualisations
+        
+        # Pour l'exemple, nous retournons une valeur simulée
+        # basée sur des métadonnées d'explication
+        
+        complexity = 0.5  # Valeur par défaut
+        
+        # Si des métadonnées de complexité sont disponibles
+        if hasattr(explanation.metadata, "complexity_level"):
+            complexity = explanation.metadata.complexity_level
+        
+        # Normaliser entre 0 et 1
+        return min(1.0, max(0.0, complexity))
+    
+    def measure_conciseness(self, explanation: ExplanationResult) -> float:
+        """
+        Mesure la concision d'une explication.
+        
+        Args:
+            explanation: L'explication à évaluer
+            
+        Returns:
+            Score de concision entre 0 et 1
+        """
+        # Dans une implémentation réelle, cette méthode pourrait:
+        # 1. Évaluer la longueur du texte par rapport à l'information transmise
+        # 2. Détecter les redondances ou répétitions
+        # 3. Mesurer la densité d'information
+        
+        # Pour l'exemple, nous retournons une valeur simulée
+        conciseness = 0.5  # Valeur par défaut
+        
+        # Si des métadonnées de concision sont disponibles
+        if hasattr(explanation.metadata, "conciseness_level"):
+            conciseness = explanation.metadata.conciseness_level
+        
+        # Normaliser entre 0 et 1
+        return min(1.0, max(0.0, conciseness))
+    
+    def measure_coherence(self, explanation: ExplanationResult) -> float:
+        """
+        Mesure la cohérence d'une explication.
+        
+        Args:
+            explanation: L'explication à évaluer
+            
+        Returns:
+            Score de cohérence entre 0 et 1
+        """
+        # Dans une implémentation réelle, cette méthode pourrait:
+        # 1. Vérifier la cohérence interne de l'explication
+        # 2. Détecter les contradictions
+        # 3. Évaluer la structure logique
+        
+        # Pour l'exemple, nous retournons une valeur simulée
+        coherence = 0.7  # Valeur par défaut
+        
+        # Si des métadonnées de cohérence sont disponibles
+        if hasattr(explanation.metadata, "coherence_level"):
+            coherence = explanation.metadata.coherence_level
+        
+        # Normaliser entre 0 et 1
+        return min(1.0, max(0.0, coherence))
+    
+    def measure_fidelity(self, 
+                        explanation: ExplanationResult,
+                        ground_truth: Any) -> float:
+        """
+        Mesure la fidélité d'une explication par rapport à une vérité terrain.
+        
+        Args:
+            explanation: L'explication à évaluer
+            ground_truth: Vérité terrain
+            
+        Returns:
+            Score de fidélité entre 0 et 1
+        """
+        # Dans une implémentation réelle, cette méthode pourrait:
+        # 1. Comparer les attributions de features avec la vérité terrain
+        # 2. Vérifier la cohérence des prédictions du modèle et de l'explication
+        # 3. Évaluer la précision des contrefactuels
+        
+        # Pour l'exemple, nous retournons une valeur simulée
+        fidelity = 0.8  # Valeur par défaut
+        
+        # Si des métadonnées de fidélité sont disponibles
+        if hasattr(explanation.metadata, "fidelity_score"):
+            fidelity = explanation.metadata.fidelity_score
+        
+        # Normaliser entre 0 et 1
+        return min(1.0, max(0.0, fidelity))
+    
+    def measure_user_satisfaction(self, user_feedback: Dict[str, Any]) -> float:
+        """
+        Mesure la satisfaction de l'utilisateur à partir de son feedback.
+        
+        Args:
+            user_feedback: Feedback utilisateur
+            
+        Returns:
+            Score de satisfaction entre 0 et 1
+        """
+        # Exemple simple de calcul de score
+        satisfaction = 0.5  # Score neutre par défaut
+        
+        if "rating" in user_feedback:
+            # Normaliser une note sur 5 ou 10 à une échelle de 0 à 1
+            rating = user_feedback["rating"]
+            if isinstance(rating, (int, float)):
+                max_rating = 5.0  # Par défaut, supposer une échelle de 5
+                if rating > 5:
+                    max_rating = 10.0  # Ajuster pour une échelle de 10
+                
+                satisfaction = min(1.0, max(0.0, rating / max_rating))
+        
+        if "helpful" in user_feedback:
+            helpful = user_feedback["helpful"]
+            if isinstance(helpful, bool):
+                satisfaction = 0.8 if helpful else 0.2
+        
+        if "clarity" in user_feedback and "relevance" in user_feedback:
+            # Moyenne pondérée de la clarté et de la pertinence
+            clarity = min(1.0, max(0.0, user_feedback["clarity"]))
+            relevance = min(1.0, max(0.0, user_feedback["relevance"]))
+            satisfaction = 0.6 * clarity + 0.4 * relevance
+        
+        return satisfaction
+    
+    def compare_explanations(self, 
+                           explanations: List[ExplanationResult],
+                           ground_truth: Optional[Any] = None) -> Dict[str, List[float]]:
+        """
+        Compare plusieurs explications selon diverses métriques.
+        
+        Args:
+            explanations: Liste d'explications à comparer
+            ground_truth: Vérité terrain (optionnel)
+            
+        Returns:
+            Dictionnaire des scores de métriques pour chaque explication
+        """
+        comparison = {
+            "complexity_scores": [],
+            "conciseness_scores": [],
+            "coherence_scores": [],
+            "overall_scores": []
+        }
+        
+        if ground_truth is not None:
+            comparison["fidelity_scores"] = []
+        
+        # Évaluer chaque explication
+        for explanation in explanations:
+            metrics = self.evaluate_explanation(explanation, ground_truth)
+            
+            comparison["complexity_scores"].append(metrics.get("complexity_score", 0.0))
+            comparison["conciseness_scores"].append(metrics.get("conciseness_score", 0.0))
+            comparison["coherence_scores"].append(metrics.get("coherence_score", 0.0))
+            comparison["overall_scores"].append(metrics.get("overall_score", 0.0))
+            
+            if ground_truth is not None:
+                comparison["fidelity_scores"].append(metrics.get("fidelity_score", 0.0))
+        
+        return comparison
+    
+    def find_optimal_explanation(self, 
+                               explanations: List[ExplanationResult],
+                               ground_truth: Optional[Any] = None,
+                               criteria: Optional[Dict[str, float]] = None) -> Tuple[int, float]:
+        """
+        Trouve l'explication optimale selon des critères pondérés.
+        
+        Args:
+            explanations: Liste d'explications à comparer
+            ground_truth: Vérité terrain (optionnel)
+            criteria: Critères pondérés (optionnel)
+            
+        Returns:
+            Tuple (indice de la meilleure explication, score)
+        """
+        if not explanations:
+            return (-1, 0.0)
+        
+        # Critères par défaut
+        default_criteria = {
+            "complexity_score": 0.2,
+            "conciseness_score": 0.3,
+            "coherence_score": 0.3,
+            "fidelity_score": 0.2
+        }
+        
+        # Utiliser les critères fournis ou les critères par défaut
+        criteria = criteria or default_criteria
+        
+        # Comparer les explications
+        comparison = self.compare_explanations(explanations, ground_truth)
+        
+        # Calculer les scores pondérés
+        weighted_scores = []
+        for i in range(len(explanations)):
+            score = 0.0
+            total_weight = 0.0
+            
+            for metric, weight in criteria.items():
+                if metric in comparison and i < len(comparison[metric]):
+                    score += weight * comparison[metric][i]
+                    total_weight += weight
+            
+            if total_weight > 0:
+                weighted_scores.append(score / total_weight)
+            else:
+                weighted_scores.append(0.0)
+        
+        # Trouver l'indice de l'explication avec le meilleur score
+        if weighted_scores:
+            best_index = np.argmax(weighted_scores)
+            return (best_index, weighted_scores[best_index])
+        
+        return (0, 0.0)  # Par défaut, retourner la première explication