389 lines
19 KiB
Markdown
389 lines
19 KiB
Markdown
# 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
|