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

Requirements Document - Correction Système d'Apprentissage FAISS

Introduction

Le système RPA Vision V2 présente des défaillances critiques dans son système d'apprentissage. Après 3 jours de tests répétitifs (calculatrice, OnlyOffice), aucune suggestion n'est générée malgré la présence de 19+ tâches sauvegardées. L'index FAISS reste vide, les processus zombies consomment 3GB+ RAM, et le système ne peut pas être arrêté proprement.

Glossaire

• FAISS: Facebook AI Similarity Search - Bibliothèque pour la recherche de similarité vectorielle
• Index FAISS: Structure de données contenant les embeddings pour la recherche rapide
• Embedding: Représentation vectorielle d'une capture d'écran ou action
• Tâche: Séquence d'actions utilisateur sauvegardée avec ses signatures
• Signature: Représentation unique d'une action (screenshot + embedding + métadonnées)
• LearningManager: Composant responsable de la détection et sauvegarde des patterns
• EmbeddingsManager: Composant responsable de la gestion de l'index FAISS
• Processus zombie: Processus qui continue de s'exécuter après l'arrêt demandé
• Circuit breaker: Mécanisme de protection contre les boucles infinies

Requirements

Requirement 1

User Story: En tant qu'utilisateur, je veux que le système construise automatiquement l'index FAISS à partir des tâches sauvegardées, afin que les suggestions fonctionnent après mes tests répétitifs.

Acceptance Criteria

1. WHEN le système démarre THEN le système SHALL charger toutes les tâches existantes dans l'index FAISS
2. WHEN une nouvelle tâche est sauvegardée THEN le système SHALL ajouter immédiatement ses embeddings à l'index FAISS
3. WHEN l'index FAISS est modifié THEN le système SHALL persister l'index sur disque immédiatement
4. WHEN le système détecte des tâches sans embeddings dans l'index THEN le système SHALL reconstruire l'index complet
5. WHEN l'index FAISS contient des embeddings THEN le système SHALL retourner des suggestions pour des actions similaires

Requirement 2

User Story: En tant qu'utilisateur, je veux que l'application s'arrête proprement sans laisser de processus zombies, afin de ne pas avoir à tuer manuellement des processus consommant 3GB+ RAM.

Acceptance Criteria

1. WHEN l'utilisateur appuie sur Ctrl+C THEN le système SHALL arrêter tous les threads en moins de 5 secondes
2. WHEN l'application s'arrête THEN le système SHALL libérer toute la mémoire allouée
3. WHEN des threads de capture sont actifs THEN le système SHALL les arrêter de manière synchrone avant de quitter
4. WHEN pynput listeners sont actifs THEN le système SHALL appeler explicitement leur méthode stop()
5. WHEN l'orchestrateur tourne en arrière-plan THEN le système SHALL utiliser des threads daemon ou un mécanisme d'arrêt garanti

Requirement 3

User Story: En tant qu'utilisateur, je veux voir des suggestions après avoir effectué des actions répétitives, afin que le système apprenne réellement de mes comportements.

Acceptance Criteria

1. WHEN l'utilisateur effectue la même action 3 fois THEN le système SHALL détecter le pattern répétitif
2. WHEN un pattern est détecté THEN le système SHALL créer une tâche avec ses signatures
3. WHEN une tâche est créée THEN le système SHALL générer et indexer les embeddings multimodaux
4. WHEN l'utilisateur effectue une action similaire à une tâche existante THEN le système SHALL proposer une suggestion avec confiance > 0.7
5. WHEN une suggestion est affichée THEN le système SHALL inclure le nom de la tâche et les actions à effectuer

Requirement 4

User Story: En tant qu'utilisateur, je veux que le système ne consomme pas plus de 2GB de RAM en fonctionnement normal, afin d'éviter les fuites mémoire.

Acceptance Criteria

1. WHEN le système fonctionne en mode shadow THEN la consommation mémoire SHALL rester sous 1GB
2. WHEN le système fonctionne en mode assist THEN la consommation mémoire SHALL rester sous 2GB
3. WHEN des embeddings sont générés THEN le système SHALL libérer les tensors GPU après utilisation
4. WHEN des screenshots sont capturés THEN le système SHALL limiter la taille du buffer à 10 images maximum
5. WHEN la mémoire dépasse 2GB THEN le système SHALL logger un avertissement et nettoyer les caches

Requirement 5

User Story: En tant qu'utilisateur, je veux un diagnostic complet du système d'apprentissage, afin de comprendre pourquoi aucune suggestion n'apparaît après 3 jours de tests.

Acceptance Criteria

1. WHEN l'utilisateur lance le diagnostic THEN le système SHALL vérifier l'existence et la taille de l'index FAISS
2. WHEN le diagnostic s'exécute THEN le système SHALL compter le nombre de tâches sauvegardées
3. WHEN le diagnostic s'exécute THEN le système SHALL vérifier la cohérence entre tâches et embeddings indexés
4. WHEN des incohérences sont détectées THEN le système SHALL proposer une reconstruction automatique
5. WHEN le diagnostic se termine THEN le système SHALL générer un rapport JSON avec toutes les métriques

Requirement 6

User Story: En tant qu'utilisateur, je veux une commande de reconstruction de l'index FAISS, afin de réparer le système sans perdre mes 3 jours de tests.

Acceptance Criteria

1. WHEN l'utilisateur lance la reconstruction THEN le système SHALL scanner tous les dossiers de tâches
2. WHEN une tâche est trouvée THEN le système SHALL charger ses signatures et générer les embeddings manquants
3. WHEN tous les embeddings sont générés THEN le système SHALL construire un nouvel index FAISS optimisé
4. WHEN la reconstruction est terminée THEN le système SHALL sauvegarder l'index et les métadonnées
5. WHEN la reconstruction échoue THEN le système SHALL logger l'erreur et continuer avec les tâches suivantes

Requirement 7

User Story: En tant qu'utilisateur, je veux que le système valide la qualité des embeddings générés, afin de garantir que les suggestions seront pertinentes.

Acceptance Criteria

1. WHEN un embedding est généré THEN le système SHALL vérifier que sa norme est non-nulle
2. WHEN un embedding est généré THEN le système SHALL vérifier qu'il ne contient pas de NaN ou Inf
3. WHEN deux screenshots identiques sont traités THEN leurs embeddings SHALL avoir une similarité > 0.95
4. WHEN deux screenshots différents sont traités THEN leurs embeddings SHALL avoir une similarité < 0.8
5. WHEN un embedding invalide est détecté THEN le système SHALL logger l'erreur et régénérer l'embedding

Requirement 8

User Story: En tant qu'utilisateur, je veux que le système détecte et corrige automatiquement les boucles infinies, afin d'éviter les fuites mémoire de 3GB+.

Acceptance Criteria

1. WHEN une fonction est appelée plus de 100 fois par seconde THEN le système SHALL activer un circuit breaker
2. WHEN un circuit breaker est activé THEN le système SHALL logger l'événement avec la stack trace
3. WHEN un circuit breaker est activé THEN le système SHALL arrêter temporairement la fonction pendant 60 secondes
4. WHEN le circuit breaker se réinitialise THEN le système SHALL reprendre progressivement avec un rate limit
5. WHEN 3 circuit breakers sont activés simultanément THEN le système SHALL passer en mode dégradé et alerter l'utilisateur