Geniusia_v2/.kiro/specs/faiss-learning-fix/design.md

Design Document - Correction Système d'Apprentissage FAISS

Overview

Ce document décrit l'architecture de correction pour résoudre les problèmes critiques du système d'apprentissage RPA Vision V2. Après 3 jours de tests, le système ne génère aucune suggestion car l'index FAISS n'est jamais construit à partir des tâches sauvegardées. De plus, des processus zombies consomment 3GB+ RAM et l'application ne s'arrête pas proprement.

Problèmes Identifiés

1. Index FAISS vide : L'index n'est jamais chargé au démarrage ni reconstruit à partir des tâches existantes
2. Pas de chargement des tâches : Les 19+ tâches sauvegardées ne sont jamais chargées dans l'index
3. Processus zombies : Les listeners pynput ne sont pas arrêtés proprement
4. Fuite mémoire : Boucles infinies et tensors GPU non libérés
5. Pas de diagnostic : Aucun outil pour comprendre l'état du système

Solution Proposée

1. Chargement automatique au démarrage : Scanner et indexer toutes les tâches existantes
2. Reconstruction d'index : Commande pour reconstruire l'index à partir des tâches
3. Arrêt propre : Gestion correcte des threads et listeners
4. Gestion mémoire : Libération des ressources et circuit breakers
5. Diagnostic complet : Outil d'analyse de l'état du système

Architecture

Composants Modifiés

1. EmbeddingsManager : Ajout de méthodes de reconstruction et chargement
2. LearningManager : Chargement automatique des tâches au démarrage
3. Orchestrator : Arrêt propre des threads et listeners
4. main.py : Initialisation avec chargement des tâches existantes

Nouveaux Composants

1. FAISSIndexBuilder : Construction et reconstruction de l'index
2. SystemDiagnostic : Diagnostic complet du système d'apprentissage
3. MemoryMonitor : Surveillance et gestion de la mémoire
4. CircuitBreaker : Protection contre les boucles infinies

Components and Interfaces

FAISSIndexBuilder

class FAISSIndexBuilder:
    """Construit et reconstruit l'index FAISS à partir des tâches."""
    
    def __init__(self, embeddings_manager, learning_manager, logger):
        pass
    
    def scan_tasks(self) -> List[TaskProfile]:
        """Scanne tous les dossiers de tâches."""
        pass
    
    def load_task_embeddings(self, task: TaskProfile) -> List[np.ndarray]:
        """Charge les embeddings d'une tâche."""
        pass
    
    def rebuild_index(self) -> Dict[str, Any]:
        """Reconstruit l'index complet."""
        pass
    
    def verify_index_integrity(self) -> bool:
        """Vérifie la cohérence de l'index."""
        pass

SystemDiagnostic

class SystemDiagnostic:
    """Diagnostic complet du système d'apprentissage."""
    
    def check_faiss_index(self) -> Dict[str, Any]:
        """Vérifie l'état de l'index FAISS."""
        pass
    
    def count_tasks(self) -> int:
        """Compte les tâches sauvegardées."""
        pass
    
    def check_consistency(self) -> Dict[str, Any]:
        """Vérifie la cohérence tâches/embeddings."""
        pass
    
    def generate_report(self) -> Dict[str, Any]:
        """Génère un rapport JSON complet."""
        pass

MemoryMonitor

class MemoryMonitor:
    """Surveille et gère la consommation mémoire."""
    
    def get_current_memory(self) -> float:
        """Retourne la mémoire utilisée en GB."""
        pass
    
    def check_threshold(self, max_memory_gb: float) -> bool:
        """Vérifie si le seuil est dépassé."""
        pass
    
    def cleanup_caches(self):
        """Nettoie les caches pour libérer de la mémoire."""
        pass
    
    def free_gpu_memory(self):
        """Libère la mémoire GPU."""
        pass

CircuitBreaker

class CircuitBreaker:
    """Protection contre les boucles infinies."""
    
    def __init__(self, threshold: int = 100, window: float = 1.0):
        pass
    
    def record_call(self, function_name: str):
        """Enregistre un appel de fonction."""
        pass
    
    def should_break(self, function_name: str) -> bool:
        """Vérifie si le circuit doit s'ouvrir."""
        pass
    
    def reset(self, function_name: str):
        """Réinitialise le circuit breaker."""
        pass

Data Models

TaskEmbedding

@dataclass
class TaskEmbedding:
    """Représente un embedding de tâche."""
    task_id: str
    embedding: np.ndarray
    metadata: Dict[str, Any]
    timestamp: datetime

DiagnosticReport

@dataclass
class DiagnosticReport:
    """Rapport de diagnostic du système."""
    timestamp: datetime
    faiss_index_exists: bool
    faiss_index_size: int
    tasks_count: int
    embeddings_count: int
    consistency_ok: bool
    inconsistencies: List[str]
    memory_usage_gb: float
    recommendations: List[str]

MemoryStats

@dataclass
class MemoryStats:
    """Statistiques mémoire."""
    total_mb: float
    used_mb: float
    available_mb: float
    percent: float
    gpu_used_mb: Optional[float]

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: Index chargé au démarrage

For any système qui démarre avec des tâches existantes, l'index FAISS doit contenir tous les embeddings de ces tâches après l'initialisation.

Validates: Requirements 1.1

Property 2: Ajout immédiat à l'index

For any nouvelle tâche sauvegardée, ses embeddings doivent être immédiatement présents dans l'index FAISS.

Validates: Requirements 1.2

Property 3: Persistance immédiate

For any modification de l'index FAISS, les fichiers sur disque doivent être mis à jour dans les 5 secondes.

Validates: Requirements 1.3

Property 4: Reconstruction automatique

For any système qui détecte des tâches sans embeddings dans l'index, la reconstruction doit être déclenchée automatiquement.

Validates: Requirements 1.4

Property 5: Suggestions avec index non-vide

For any action similaire à une tâche existante, si l'index contient des embeddings, une suggestion doit être retournée.

Validates: Requirements 1.5

Property 6: Arrêt rapide

For any signal d'arrêt (Ctrl+C), tous les threads doivent être arrêtés en moins de 5 secondes.

Validates: Requirements 2.1

Property 7: Libération mémoire

For any arrêt de l'application, la consommation mémoire du processus doit diminuer de plus de 90% dans les 10 secondes.

Validates: Requirements 2.2

Property 8: Arrêt synchrone des threads

For any arrêt demandé, aucun thread de capture ne doit rester actif après la fin de la méthode shutdown().

Validates: Requirements 2.3

Property 9: Stop explicite des listeners

For any listener pynput actif, sa méthode stop() doit être appelée avant la fin du programme.

Validates: Requirements 2.4

Property 10: Threads daemon ou arrêt garanti

For any thread d'orchestrateur, il doit être soit daemon, soit avoir un mécanisme d'arrêt vérifié.

Validates: Requirements 2.5

Property 11: Détection de patterns répétitifs

For any séquence de 3 actions identiques, un pattern doit être détecté et enregistré.

Validates: Requirements 3.1

Property 12: Création de tâche après pattern

For any pattern détecté, une tâche avec signatures doit être créée dans les 2 secondes.

Validates: Requirements 3.2

Property 13: Indexation des embeddings

For any tâche créée, ses embeddings multimodaux doivent être présents dans l'index FAISS.

Validates: Requirements 3.3

Property 14: Suggestions avec confiance élevée

For any action similaire (similarité > 0.8) à une tâche existante, une suggestion avec confiance > 0.7 doit être proposée.

Validates: Requirements 3.4

Property 15: Contenu des suggestions

For any suggestion affichée, elle doit contenir le nom de la tâche et la liste des actions à effectuer.

Validates: Requirements 3.5

Property 16: Limite mémoire mode shadow

For any exécution en mode shadow pendant plus de 5 minutes, la consommation mémoire doit rester sous 1GB.

Validates: Requirements 4.1

Property 17: Limite mémoire mode assist

For any exécution en mode assist pendant plus de 5 minutes, la consommation mémoire doit rester sous 2GB.

Validates: Requirements 4.2

Property 18: Libération GPU

For any génération d'embedding, la mémoire GPU utilisée doit être libérée dans les 2 secondes.

Validates: Requirements 4.3

Property 19: Buffer limité

For any moment de l'exécution, le buffer de screenshots ne doit jamais contenir plus de 10 images.

Validates: Requirements 4.4

Property 20: Alerte mémoire

For any dépassement du seuil de 2GB, un avertissement doit être loggé et les caches nettoyés.

Validates: Requirements 4.5

Property 21: Comptage des tâches

For any exécution du diagnostic, le nombre de tâches retourné doit correspondre au nombre de dossiers dans user_profiles.

Validates: Requirements 5.2

Property 22: Vérification de cohérence

For any exécution du diagnostic, toutes les tâches avec embeddings doivent avoir leurs embeddings dans l'index.

Validates: Requirements 5.3

Property 23: Proposition de reconstruction

For any incohérence détectée (tâche sans embedding dans l'index), le diagnostic doit proposer une reconstruction.

Validates: Requirements 5.4

Property 24: Rapport JSON complet

For any diagnostic terminé, un fichier JSON doit être généré avec toutes les métriques requises.

Validates: Requirements 5.5

Property 25: Scan complet des tâches

For any reconstruction lancée, tous les dossiers de tâches existants doivent être scannés.

Validates: Requirements 6.1

Property 26: Génération d'embeddings manquants

For any tâche trouvée sans embeddings dans l'index, les embeddings doivent être générés et ajoutés.

Validates: Requirements 6.2

Property 27: Construction d'index optimisé

For any reconstruction terminée, un nouvel index FAISS doit être créé avec tous les embeddings.

Validates: Requirements 6.3

Property 28: Sauvegarde après reconstruction

For any reconstruction réussie, les fichiers d'index et métadonnées doivent être sauvegardés sur disque.

Validates: Requirements 6.4

Property 29: Résilience aux erreurs

For any erreur lors du traitement d'une tâche, la reconstruction doit continuer avec les tâches suivantes.

Validates: Requirements 6.5

Property 30: Validation norme non-nulle

For any embedding généré, sa norme L2 doit être strictement positive.

Validates: Requirements 7.1

Property 31: Validation NaN/Inf

For any embedding généré, il ne doit contenir ni NaN ni Inf.

Validates: Requirements 7.2

Property 32: Cohérence embeddings identiques

For any paire de screenshots identiques, leurs embeddings doivent avoir une similarité cosinus > 0.95.

Validates: Requirements 7.3

Property 33: Discrimination embeddings différents

For any paire de screenshots visuellement différents, leurs embeddings doivent avoir une similarité cosinus < 0.8.

Validates: Requirements 7.4

Property 34: Régénération sur invalide

For any embedding invalide détecté, une erreur doit être loggée et l'embedding régénéré.

Validates: Requirements 7.5

Property 35: Activation circuit breaker

For any fonction appelée plus de 100 fois en 1 seconde, le circuit breaker doit s'activer.

Validates: Requirements 8.1

Property 36: Log circuit breaker

For any activation de circuit breaker, un log avec stack trace doit être créé.

Validates: Requirements 8.2

Property 37: Blocage temporaire

For any circuit breaker activé, la fonction doit être bloquée pendant 60 secondes.

Validates: Requirements 8.3

Property 38: Reprise progressive

For any réinitialisation de circuit breaker, un rate limit doit être appliqué à la reprise.

Validates: Requirements 8.4

Property 39: Mode dégradé

For any situation avec 3 circuit breakers actifs simultanément, le système doit passer en mode dégradé.

Validates: Requirements 8.5

Error Handling

Stratégie Générale

1. Erreurs de chargement : Logger et continuer avec les tâches suivantes
2. Erreurs d'embedding : Régénérer jusqu'à 3 tentatives
3. Erreurs FAISS : Reconstruire l'index si corrompu
4. Erreurs mémoire : Nettoyer les caches et alerter
5. Erreurs de thread : Forcer l'arrêt après timeout

Gestion des Erreurs Critiques

try:
    # Opération critique
    pass
except MemoryError:
    memory_monitor.cleanup_caches()
    logger.log_critical("memory_exhausted")
except FAISSError:
    index_builder.rebuild_index()
    logger.log_critical("faiss_corrupted")
except ThreadError:
    force_shutdown_threads()
    logger.log_critical("thread_deadlock")

Testing Strategy

Unit Tests

• Test de chargement des tâches individuelles
• Test de génération d'embeddings
• Test d'ajout à l'index FAISS
• Test de recherche de similarité
• Test d'arrêt des threads
• Test de libération mémoire

Property-Based Tests

Nous utiliserons Hypothesis pour Python comme bibliothèque de property-based testing. Chaque test sera configuré pour exécuter au minimum 100 itérations.

Chaque property-based test doit être tagué avec un commentaire référençant explicitement la correctness property du design document au format : **Feature: faiss-learning-fix, Property {number}: {property_text}**

Les tests doivent couvrir :

• Génération aléatoire de tâches et vérification de l'indexation
• Génération aléatoire d'embeddings et validation
• Simulation d'arrêts à différents moments
• Simulation de charges mémoire variables
• Simulation d'appels répétitifs pour circuit breakers

Integration Tests

• Test du flux complet : création tâche → indexation → suggestion
• Test de reconstruction d'index avec tâches existantes
• Test d'arrêt propre avec tous les composants actifs
• Test de diagnostic sur système réel
• Test de gestion mémoire sous charge

Implementation Notes

Ordre d'Implémentation

1. FAISSIndexBuilder : Fondation pour tout le reste
2. Chargement au démarrage : Correction immédiate du problème principal
3. Arrêt propre : Correction des processus zombies
4. MemoryMonitor : Protection contre les fuites
5. CircuitBreaker : Protection contre les boucles
6. SystemDiagnostic : Outil de débogage

Points d'Attention

1. Compatibilité : Ne pas casser le code existant
2. Performance : Chargement rapide au démarrage (<10s)
3. Robustesse : Gérer les tâches corrompues
4. Logs : Tracer toutes les opérations critiques
5. Tests : Valider chaque property avant de continuer