# 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

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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_

- [x] 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