Geniusia_v2/.kiro/specs/ui-element-detection/tasks.md

Plan d'Implémentation - Détection d'Éléments UI et Fusion Multi-Modale

Vue d'Ensemble

Ce plan implémente progressivement le système de détection d'éléments UI et de fusion multi-modale en 3 phases :

• Phase 1 (Light) : Structures de données et mode minimal
• Phase 2 (Enrichi) : Détection d'éléments basique
• Phase 3 (Complet) : Fusion multi-modale complète

Tâches

• 1. Phase 1 - Mode Light : Structures de Données de Base

  • Créer les structures de données UIElement et EnrichedScreenState
  • Ajouter les champs au JSON sans changer la logique existante
  • Permettre la compatibilité arrière complète
  • Exigences: 11.1, 11.2, 11.5, 12.1, 12.4, 15.1

• 1.1 Créer les dataclasses pour UIElement

  • Implémenter UIElement avec tous les champs (element_id, type, role, bbox, label, visual, text, properties, context, tags)
  • Implémenter les sous-structures (VisualData, TextData, ElementProperties, ElementContext)
  • Ajouter les méthodes de sérialisation/désérialisation JSON
  • Implémenter la génération d'element_id stable basée sur hash(app_name + center_bbox + label_normalized)
  • Exigences: 11.1, 11.2, 11.3, 11.4, 11.5

• * 1.2 Écrire les tests de propriété pour UIElement

  • Propriété 6: Stabilité des identifiants - Pour tout UIElement créé deux fois avec mêmes paramètres, l'element_id doit être identique
  • Propriété 32: Complétude de la structure UIElement - Tous les champs requis doivent être présents
  • Propriété 33: Round-trip de sérialisation UIElement - Sérialisation puis désérialisation doit préserver tous les champs
  • Valide: Exigences 11.1, 11.2, 11.5

• 1.3 Créer les dataclasses pour EnrichedScreenState

  • Implémenter EnrichedScreenState avec tous les champs (screen_state_id, timestamp, session_id, window, raw, perception, ui_elements, state_embedding, context)
  • Implémenter les sous-structures (WindowInfo, RawData, PerceptionData, StateEmbedding, EmbeddingComponents, ContextData)
  • Ajouter les méthodes de sérialisation/désérialisation JSON
  • Assurer la compatibilité avec l'ancien format ScreenState
  • Exigences: 12.1, 12.2, 12.3, 12.4

• * 1.4 Écrire les tests de propriété pour EnrichedScreenState

  • Propriété 34: Complétude de la structure ScreenState - Tous les champs requis doivent être présents
  • Propriété 36: Round-trip de sérialisation ScreenState - Les embeddings doivent être reconstruits correctement
  • Propriété 42: Compatibilité de lecture multi-mode - Lecture des anciens formats sans erreur
  • Valide: Exigences 12.1, 12.4, 12.5, 15.5

• 1.5 Intégrer les nouvelles structures dans le système existant

  • Modifier le code existant pour utiliser EnrichedScreenState au lieu de ScreenState
  • Initialiser ui_elements comme liste vide par défaut
  • Initialiser state_embedding avec image_embedding uniquement (mode light)
  • Assurer que tous les workflows existants continuent de fonctionner
  • Exigences: 9.1, 15.1

• * 1.6 Écrire les tests de compatibilité arrière

  • Propriété 25: Compatibilité arrière des workflows legacy - Les anciens workflows doivent continuer à fonctionner
  • Tester que les anciens fichiers JSON sont lisibles
  • Tester que les nouveaux fichiers sont écrits avec les nouveaux champs
  • Valide: Exigences 9.1, 9.2, 15.1

• 2. Checkpoint - Vérifier que le mode Light fonctionne

  • Assurer que tous les tests passent
  • Vérifier que les workflows existants fonctionnent toujours
  • Demander à l'utilisateur si des questions se posent

• 3. Phase 2 - Mode Enrichi : Détection d'Éléments Basique

  • Implémenter le pipeline de détection d'éléments
  • Détecter les éléments pour certains écrans configurés
  • Maintenir la compatibilité avec le mode light
  • Exigences: 1.1, 1.2, 1.3, 1.4, 1.5, 13.1, 13.2, 13.3, 13.4, 13.5, 15.2

• 3.1 Créer le composant RegionProposer

  • Implémenter la détection de zones de texte (méthode rapide)
  • Implémenter la détection de rectangles autour de texte (heuristique)
  • Implémenter la requête VLM conditionnelle pour zones cliquables (coûteux)
  • Implémenter la fusion et le nettoyage des régions (merge overlapping, filter invalid)
  • Implémenter la logique _should_use_vlm pour décider quand utiliser le VLM
  • Exigences: 13.2

• * 3.2 Écrire les tests pour RegionProposer

  • Tester la détection de zones de texte sur images synthétiques
  • Tester la fusion de régions qui se chevauchent
  • Tester le filtrage de régions invalides (trop petites, hors écran)
  • Valide: Exigences 13.2

• 3.3 Créer le composant ElementCharacterizer

  • Implémenter l'extraction de crop image pour chaque région
  • Implémenter la génération d'embedding image via CLIP
  • Implémenter l'extraction de texte dans/autour de la région via VLM
  • Implémenter la génération d'embedding texte
  • Implémenter l'extraction de position bbox
  • Exigences: 1.2, 1.3, 1.4, 13.3

• * 3.4 Écrire les tests de propriété pour ElementCharacterizer

  • Propriété 1: Complétude de détection d'éléments - Tous les champs requis doivent être extraits
  • Propriété 37: Complétude de la caractérisation - Crop, embeddings, texte, bbox doivent être présents
  • Valide: Exigences 1.2, 1.3, 1.4, 13.3

• 3.5 Créer le composant ElementClassifier

  • Implémenter la classification de type (button, text_input, checkbox, etc.)
  • Implémenter l'inférence de rôle sémantique (primary_action, dangerous_action, search_field, etc.)
  • Implémenter l'assignation de score de confiance
  • Utiliser les caractéristiques visuelles et l'analyse textuelle VLM
  • Exigences: 2.1, 2.3, 2.4, 13.4

• * 3.6 Écrire les tests de propriété pour ElementClassifier

  • Propriété 2: Validité des types d'éléments - Le type doit être l'un des types valides
  • Propriété 3: Présence du score de confiance - Score entre 0.0 et 1.0 doit être assigné
  • Propriété 38: Complétude de la classification - Type et rôle doivent être présents
  • Valide: Exigences 2.1, 2.3, 2.4, 13.4

• 3.7 Créer le composant UIElementDetector principal

  • Implémenter la méthode detect_elements qui orchestre le pipeline complet
  • Intégrer RegionProposer, ElementCharacterizer et ElementClassifier
  • Implémenter la gestion d'erreurs (continuer si un élément échoue)
  • Implémenter le logging détaillé de chaque étape
  • Exigences: 1.1, 13.1, 13.5

• * 3.8 Écrire les tests de propriété pour UIElementDetector

  • Propriété 1: Complétude de détection d'éléments - Tous les éléments interactifs doivent être détectés
  • Propriété 39: Robustesse du pipeline - Si 1 élément échoue, les N-1 autres doivent être produits
  • Valide: Exigences 1.1, 13.5

• 3.9 Intégrer UIElementDetector dans l'Orchestrator

  • Ajouter un appel à UIElementDetector.detect_elements lors de la capture d'écran
  • Stocker les UIElement détectés dans EnrichedScreenState.ui_elements
  • Ajouter une configuration pour activer/désactiver la détection (mode enrichi)
  • Implémenter la détection conditionnelle (seulement pour certains écrans configurés)
  • Exigences: 15.2

• * 3.10 Écrire les tests d'intégration pour la détection

  • Tester le pipeline complet : screenshot → UIElements
  • Tester avec différents types d'écrans (formulaires, tableaux, menus)
  • Tester la performance (< 2 secondes pour écran typique)
  • Valide: Exigences 1.1, 10.1

• 4. Checkpoint - Vérifier que le mode Enrichi fonctionne

  • Assurer que tous les tests passent
  • Vérifier que les éléments sont détectés correctement sur des écrans de test
  • Demander à l'utilisateur si des questions se posent

• 5. Phase 3 - Mode Complet : Fusion Multi-Modale

  • Implémenter le gestionnaire d'embeddings multi-modaux
  • Calculer le state_embedding fusionné avec toutes les modalités
  • Intégrer dans le workflow matcher
  • Exigences: 4.1, 4.2, 4.3, 4.4, 4.5, 5.1, 5.2, 5.3, 5.4, 14.1, 14.2, 14.3, 14.4, 14.5, 15.3

• 5.1 Créer le composant MultiModalEmbeddingManager

  • Implémenter la méthode create_state_embedding
  • Calculer image_embedding (screenshot entier via CLIP)
  • Calculer text_embedding (texte concaténé via CLIP text)
  • Calculer title_embedding (window_title via CLIP text)
  • Calculer ui_embedding (moyenne des embeddings d'éléments importants)
  • Calculer context_embedding (vecteur de contexte workflow)
  • Exigences: 4.1, 4.2, 4.3, 4.4, 14.1

• * 5.2 Écrire les tests de propriété pour les composantes individuelles

  • Propriété 7: Structure complète du state embedding - Toutes les composantes doivent être présentes
  • Propriété 8: Extraction de texte systématique - Le texte doit être extrait pour tout screenshot
  • Propriété 9: Présence du titre de fenêtre - window_title doit être présent
  • Propriété 10: Inclusion du contexte workflow - Le contexte doit être inclus si disponible
  • Valide: Exigences 4.1, 4.2, 4.3, 4.4, 14.1

• 5.3 Implémenter la normalisation des composantes

  • Normaliser chaque vecteur individuel (norme L2 = 1.0) avant fusion
  • Implémenter la méthode _normalize
  • Ajouter des assertions pour vérifier la normalisation
  • Exigences: 4.5, 14.2

• * 5.4 Écrire les tests de propriété pour la normalisation

  • Propriété 40: Normalisation des composantes - Chaque composante doit avoir norme L2 = 1.0 avant fusion
  • Tester avec différents vecteurs d'entrée
  • Valide: Exigences 14.2

• 5.5 Implémenter la fusion pondérée des composantes

  • Implémenter la combinaison pondérée avec poids configurables
  • Poids par défaut : w_img=0.5, w_text=0.3, w_title=0.1, w_ui=0.1, w_ctx=0.1
  • Normaliser le vecteur final (norme L2 = 1.0)
  • Stocker les composantes individuelles séparément pour debug
  • Exigences: 4.5, 14.3, 14.4, 14.5

• * 5.6 Écrire les tests de propriété pour la fusion

  • Propriété 11: Normalisation des embeddings - Le vecteur final doit avoir norme L2 = 1.0
  • Propriété 12: Dimension fixe des embeddings - La dimension doit être constante
  • Propriété 41: Stockage des composantes - Les composantes doivent être stockées séparément
  • Valide: Exigences 4.5, 5.1, 14.4, 14.5

• 5.7 Implémenter le calcul de ui_embedding

  • Filtrer les éléments importants (primary_action, is_clickable)
  • Calculer la moyenne des embeddings visuels
  • Gérer le cas où aucun élément n'est présent (retourner vecteur zéro)
  • Exigences: 14.1

• 5.8 Implémenter le calcul de context_embedding

  • Encoder les métadonnées de contexte (workflow_id, flags métier)
  • Projeter en vecteur de dimension appropriée
  • Gérer le cas où le contexte est manquant
  • Exigences: 4.4, 8.1, 8.4

• * 5.9 Écrire les tests de propriété pour le contexte

  • Propriété 22: Sensibilité au contexte - Contextes différents doivent produire embeddings différents
  • Propriété 23: Robustesse en absence de contexte - Un embedding valide doit être généré même sans contexte
  • Valide: Exigences 8.2, 8.4

• 5.10 Intégrer MultiModalEmbeddingManager dans l'Orchestrator

  • Appeler create_state_embedding lors de la capture d'écran
  • Stocker le state_embedding dans EnrichedScreenState
  • Ajouter une configuration pour activer/désactiver la fusion multi-modale (mode complet)
  • Exigences: 15.3

• * 5.11 Écrire les tests d'intégration pour la fusion multi-modale

  • Tester le pipeline complet : screenshot → state_embedding fusionné
  • Tester la performance (< 1 seconde pour génération d'embedding)
  • Valide: Exigences 10.2

• 6. Checkpoint - Vérifier que le mode Complet fonctionne

  • Assurer que tous les tests passent
  • Vérifier que les state_embeddings sont générés correctement
  • Demander à l'utilisateur si des questions se posent

• [-] 7. Améliorer le WorkflowMatcher pour utiliser les éléments

  • Créer EnhancedWorkflowMatcher qui supporte le matching au niveau élément
  • Maintenir le matcher legacy pour compatibilité
  • Implémenter le routage automatique (legacy vs enhanced)
  • Exigences: 6.1, 6.2, 6.3, 6.4, 6.5, 9.2, 9.3

• 7.1 Créer la classe EnhancedWorkflowMatcher

  • Implémenter match_workflow_step qui route vers matching élément ou legacy
  • Implémenter _has_element_descriptors pour détecter le type de workflow
  • Implémenter _match_by_elements pour matching basé sur éléments
  • Implémenter _match_legacy pour compatibilité arrière
  • Exigences: 6.1, 9.2, 9.3

• * 7.2 Écrire les tests de propriété pour le routage

  • Propriété 26: Routage correct des workflows - Workflows avec descripteurs → matcher amélioré, sans → legacy
  • Tester avec différents types de workflows
  • Valide: Exigences 9.2, 9.3

• 7.3 Implémenter la comparaison de state_embeddings

  • Calculer la similarité cosinus entre embeddings
  • Implémenter _compare_state_embeddings
  • Retourner un score entre 0.0 et 1.0
  • Exigences: 5.2, 6.2

• * 7.4 Écrire les tests de propriété pour la comparaison

  • Propriété 13: Robustesse aux variations visuelles légères - Similarité ≥ 0.85 pour variations légères
  • Propriété 14: Discrimination sémantique - Similarité ≤ 0.70 pour écrans différents
  • Tester la performance (< 100ms par comparaison)
  • Valide: Exigences 5.2, 5.3, 5.4, 10.3

• 7.5 Implémenter la comparaison d'éléments requis

  • Implémenter _compare_required_elements
  • Implémenter _elements_match pour vérifier correspondance type/rôle/sémantique/position
  • Calculer le score de correspondance (nombre d'éléments matchés / nombre requis)
  • Exigences: 6.1, 6.2, 6.3

• * 7.6 Écrire les tests de propriété pour la correspondance d'éléments

  • Propriété 16: Vérification des éléments requis - Score < 0.5 si éléments manquants
  • Propriété 17: Bonus des éléments optionnels - Score augmente avec éléments optionnels
  • Valide: Exigences 6.3, 6.4

• 7.7 Implémenter le feedback détaillé sur échec

  • Créer MatchResult avec liste de différences
  • Identifier les éléments manquants, types incorrects, positions incorrectes
  • Formater un message d'erreur lisible
  • Exigences: 6.5

• * 7.8 Écrire les tests de propriété pour le feedback

  • Propriété 18: Feedback détaillé sur échec - Liste non-vide de différences pour tout échec
  • Tester avec différents types d'échecs
  • Valide: Exigences 6.5

• 7.9 Intégrer EnhancedWorkflowMatcher dans l'Orchestrator

  • Remplacer l'ancien WorkflowMatcher par EnhancedWorkflowMatcher
  • Passer le legacy_matcher en paramètre pour compatibilité
  • Configurer les poids de matching (weight_state, weight_elements)
  • Exigences: 9.1, 9.2, 9.3

• 7.10 Écrire les tests d'intégration pour le matching

  • Tester le matching avec workflows legacy (compatibilité)
  • Tester le matching avec workflows enrichis (éléments)
  • Tester le routage automatique
  • Valide: Exigences 9.1, 9.2, 9.3

• 8. Checkpoint - Vérifier que le matching amélioré fonctionne

  • Assurer que tous les tests passent
  • Vérifier que les workflows legacy fonctionnent toujours
  • Vérifier que les nouveaux workflows utilisent le matching amélioré
  • Demander à l'utilisateur si des questions se posent

• 9. Optimisations et Performance

  • Implémenter le cache pour le VLM
  • Optimiser les requêtes d'éléments
  • Ajouter des métriques de monitoring
  • Exigences: 10.1, 10.2, 10.3, 10.4, 10.5

• 9.1 Implémenter le cache VLM

  • Créer un cache basé sur hash du screenshot
  • Implémenter une politique d'éviction LRU
  • Persister le cache entre sessions (optionnel)
  • Mesurer le taux de cache hit
  • Exigences: 10.4

• * 9.2 Écrire les tests de propriété pour le cache

  • Propriété 30: Efficacité du cache VLM - Deuxième traitement ≤ 10% du temps du premier
  • Tester avec différents screenshots
  • Valide: Exigences 10.4

• 9.3 Optimiser les requêtes d'éléments

  • Créer un index sur element_id pour recherche rapide
  • Implémenter une recherche par type et rôle
  • Mesurer les temps de requête
  • Exigences: 10.5

• * 9.4 Écrire les tests de propriété pour la scalabilité

  • Propriété 31: Scalabilité des requêtes - Temps ≤ 50ms pour base de 100k éléments
  • Tester avec différentes tailles de base de données
  • Valide: Exigences 10.5

• 9.5 Ajouter des métriques de monitoring

  • Nombre d'éléments détectés par screenshot
  • Temps de chaque étape du pipeline
  • Taux de cache hit pour le VLM
  • Distribution des types d'éléments
  • Scores de matching moyens
  • Exigences: 10.1, 10.2, 10.3

• * 9.6 Écrire les tests de performance

  • Propriété 27: Performance de détection - ≤ 2 secondes pour écran typique
  • Propriété 28: Performance de génération d'embedding - ≤ 1 seconde
  • Propriété 29: Performance de comparaison - ≤ 100ms
  • Valide: Exigences 10.1, 10.2, 10.3

• 10. Outils et Utilitaires

  • Créer un outil de migration de workflows
  • Créer un mode debug visuel
  • Créer un outil de configuration
  • Exigences: 9.4, 9.5, 15.4

• 10.1 Créer un outil de migration de workflows

  • Convertir les workflows plein écran en workflows au niveau élément
  • Détecter automatiquement les éléments dans les anciens screenshots
  • Générer les descripteurs d'éléments
  • Sauvegarder les workflows migrés
  • Exigences: 9.4

• 10.2 Créer un mode debug visuel

  • Sauvegarder des screenshots annotés avec bounding boxes
  • Afficher les types et rôles détectés
  • Afficher les scores de confiance
  • Afficher les embeddings (visualisation PCA/t-SNE)
  • Exigences: Design - Logging et Debug

• 10.3 Créer un outil de configuration

  • Permettre la configuration via fichier YAML ou variables d'environnement
  • Configurer les modes (light, enrichi, complet)
  • Configurer les poids de fusion
  • Configurer les seuils de matching
  • Configurer l'activation du VLM
  • Exigences: 15.4

• 11. Documentation et Tests Finaux

  • Documenter l'API des nouveaux composants
  • Créer des exemples d'utilisation
  • Vérifier la couverture de tests
  • Exigences: Toutes

• 11.1 Documenter l'API

  • Documenter UIElement, EnrichedScreenState
  • Documenter UIElementDetector, MultiModalEmbeddingManager, EnhancedWorkflowMatcher
  • Créer des docstrings complètes
  • Générer la documentation API (Sphinx)
  • Exigences: Toutes

• 11.2 Créer des exemples d'utilisation

  • Exemple de détection d'éléments sur un screenshot
  • Exemple de génération de state_embedding
  • Exemple de matching de workflow
  • Exemple de migration de workflow
  • Exigences: Toutes

• 11.3 Vérifier la couverture de tests

  • Vérifier que toutes les propriétés sont testées
  • Vérifier la couverture de code (> 80%)
  • Ajouter des tests manquants si nécessaire
  • Exigences: Toutes

• 12. Checkpoint Final - Validation Complète

  • Assurer que tous les tests passent
  • Vérifier que toutes les exigences sont satisfaites
  • Tester sur des workflows réels
  • Demander à l'utilisateur si des questions se posent