# Document d'Exigences

## Introduction

Cette spécification définit les exigences pour transformer GeniusIA v2 d'un système de comparaison plein écran en une plateforme RPA robuste capable de détecter et d'interagir avec des éléments d'interface individuels via une analyse vision multi-modale. Le système combinera les embeddings visuels (CLIP, Pix2Struct), l'extraction de texte VLM (Qwen3-VL), le contexte de fenêtre et les métadonnées de workflow dans une "empreinte d'état" unifiée permettant une automatisation d'interface précise et fiable.

## Glossaire

- **Élément d'UI**: Un composant interactif à l'écran tel qu'un bouton, champ de texte, liste déroulante, onglet, case à cocher ou lien
- **Capture Locale**: Une capture d'écran recadrée focalisée sur un élément d'UI spécifique plutôt que sur l'écran complet
- **VLM (Vision Language Model)**: Un modèle comme Qwen3-VL capable d'extraire du texte et de décrire du contenu visuel
- **Embedding d'État**: Une représentation vectorielle multi-modale combinant informations visuelles, textuelles et contextuelles sur un état d'écran
- **Élément Interactif**: Un composant d'UI pouvant recevoir une entrée utilisateur ou déclencher des actions
- **Descripteur d'Élément**: Une représentation structurée contenant (capture locale + embedding + description VLM + position)
- **Empreinte d'État Unifiée**: Un embedding complet combinant screenshot, texte détecté, titre de fenêtre et contexte workflow
- **Système GeniusIA**: Le système d'automatisation RPA en cours d'amélioration
- **Gestionnaire d'Embeddings**: Le composant responsable de la génération et gestion des embeddings
- **Orchestrateur**: Le composant central qui coordonne la boucle cognitive et la prise de décision

## Exigences

### Exigence 1: Détection d'Éléments d'UI

**User Story:** En tant que développeur RPA, je veux que le système détecte et identifie les éléments d'UI individuels à l'écran, afin de pouvoir interagir avec des boutons, champs et contrôles spécifiques plutôt que de me fier à une correspondance plein écran.

#### Critères d'Acceptation

1. QUAND le système capture une capture d'écran, ALORS le Système GeniusIA DOIT identifier tous les éléments d'UI interactifs présents à l'écran
2. QUAND un élément interactif est détecté, ALORS le Système GeniusIA DOIT extraire une capture locale (région recadrée) de cet élément
3. QUAND un élément d'UI est traité, ALORS le Système GeniusIA DOIT générer un embedding à partir de la capture locale
4. QUAND un élément d'UI est analysé, ALORS le Système GeniusIA DOIT utiliser le VLM pour générer une description textuelle de l'élément
5. QUAND les informations d'élément sont stockées, ALORS le Système GeniusIA DOIT créer un Descripteur d'Élément contenant (capture locale, embedding, description VLM, position écran)

### Exigence 2: Classification d'Éléments

**User Story:** En tant que développeur RPA, je veux que le système classifie les éléments d'UI par type, afin de pouvoir appliquer des stratégies d'interaction appropriées pour les boutons, champs, listes et autres contrôles.

#### Critères d'Acceptation

1. QUAND un élément d'UI est détecté, ALORS le Système GeniusIA DOIT le classifier dans l'un des types suivants : bouton, champ de texte, liste déroulante, onglet, case à cocher, bouton radio, lien, ou élément interactif générique
2. QUAND un élément est classifié, ALORS le Système GeniusIA DOIT utiliser à la fois les caractéristiques visuelles et l'analyse textuelle VLM
3. QUAND le type d'élément est ambigu, ALORS le Système GeniusIA DOIT assigner un score de confiance à la classification
4. QUAND les données d'élément sont stockées, ALORS le Système GeniusIA DOIT inclure le type d'élément et le score de confiance dans le Descripteur d'Élément

### Exigence 3: Compréhension Sémantique des Éléments

**User Story:** En tant que développeur RPA, je veux que le système comprenne ce que fait chaque élément d'UI, afin que les workflows puissent référencer les éléments par leur signification sémantique plutôt que par des coordonnées de pixels.

#### Critères d'Acceptation

1. QUAND un élément d'UI est analysé, ALORS le VLM DOIT générer une description sémantique telle que "Bouton 'Valider la facture' en bas à droite"
2. QUAND la sémantique d'élément est extraite, ALORS le Système GeniusIA DOIT identifier le label ou le contenu textuel de l'élément
3. QUAND le but de l'élément est déterminé, ALORS le Système GeniusIA DOIT inférer l'action ou la fonction à partir d'indices visuels et textuels
4. QUAND la localisation de l'élément est décrite, ALORS le Système GeniusIA DOIT fournir des informations de position relative (haut/bas, gauche/droite, près d'autres éléments)
5. QUAND plusieurs éléments similaires existent, ALORS le Système GeniusIA DOIT les différencier en utilisant des informations spatiales et contextuelles

### Exigence 4: Embedding d'État Multi-Modal

**User Story:** En tant que développeur RPA, je veux que le système crée un embedding unifié combinant toutes les informations disponibles sur l'état de l'écran, afin que la correspondance de workflow soit robuste face aux variations visuelles.

#### Critères d'Acceptation

1. QUAND un embedding d'état est généré, ALORS le Gestionnaire d'Embeddings DOIT combiner l'embedding visuel du screenshot, le texte extrait par VLM, le titre de fenêtre et le contexte workflow en un seul vecteur unifié
2. QUAND un screenshot est traité, ALORS le Système GeniusIA DOIT extraire le contenu textuel en utilisant le VLM
3. QUAND l'état d'écran est capturé, ALORS le Système GeniusIA DOIT inclure le titre de la fenêtre active
4. OÙ le contexte workflow est disponible, ALORS le Système GeniusIA DOIT inclure les métadonnées contextuelles (ID patient, numéro de facture, type de document, etc.)
5. QUAND l'embedding unifié est créé, ALORS le Gestionnaire d'Embeddings DOIT normaliser et pondérer chaque modalité de manière appropriée

### Exigence 5: Génération d'Empreinte d'État

**User Story:** En tant que développeur RPA, je veux que chaque état d'écran ait une empreinte unique et robuste, afin que le système puisse reconnaître de manière fiable les états même lorsque l'apparence visuelle varie légèrement.

#### Critères d'Acceptation

1. QUAND une empreinte d'état est générée, ALORS le Gestionnaire d'Embeddings DOIT produire une représentation vectorielle de dimension fixe
2. QUAND des empreintes d'état sont comparées, ALORS le Système GeniusIA DOIT utiliser la similarité cosinus ou une métrique de distance équivalente
3. QUAND les éléments visuels changent légèrement (couleur, taille, position), ALORS l'empreinte d'état DOIT rester suffisamment similaire pour la correspondance
4. QUAND le contenu sémantique change significativement, ALORS l'empreinte d'état DOIT différer suffisamment pour éviter les fausses correspondances
5. QUAND les empreintes d'état sont stockées, ALORS le Système GeniusIA DOIT les associer aux étapes de workflow et aux descripteurs d'éléments

### Exigence 6: Correspondance de Workflow au Niveau Élément

**User Story:** En tant que développeur RPA, je veux que les workflows correspondent en fonction de la présence et de l'état d'éléments d'UI spécifiques, afin que l'automatisation soit plus fiable que la comparaison d'images plein écran.

#### Critères d'Acceptation

1. QUAND une étape de workflow est mise en correspondance, ALORS le Système GeniusIA DOIT comparer les éléments d'UI détectés aux éléments attendus pour cette étape
2. QUAND une correspondance est évaluée, ALORS le Système GeniusIA DOIT considérer le type d'élément, la description sémantique et la position
3. QUAND plusieurs éléments sont requis, ALORS le Système GeniusIA DOIT vérifier que tous les éléments requis sont présents
4. QUAND des éléments optionnels existent, ALORS le Système GeniusIA DOIT augmenter la confiance de correspondance s'ils sont présents
5. QUAND des éléments sont manquants ou ne correspondent pas, ALORS le Système GeniusIA DOIT fournir un retour détaillé sur ce qui diffère

### Exigence 7: Intégration VLM pour l'Extraction de Texte

**User Story:** En tant que développeur RPA, je veux que le système extraie tout le texte visible des screenshots en utilisant le VLM, afin que le contenu textuel puisse être utilisé pour la correspondance et la prise de décision.

#### Critères d'Acceptation

1. QUAND un screenshot est traité, ALORS le Système GeniusIA DOIT utiliser Qwen3-VL pour extraire tout le texte visible
2. QUAND du texte est détecté, ALORS le Système GeniusIA DOIT préserver les informations spatiales sur l'emplacement du texte
3. QUAND du texte est extrait d'éléments d'UI, ALORS le Système GeniusIA DOIT associer le texte à l'élément correspondant
4. QUAND l'extraction de texte échoue ou est ambiguë, ALORS le Système GeniusIA DOIT enregistrer le problème et continuer le traitement
5. QUAND le texte extrait est stocké, ALORS le Système GeniusIA DOIT l'inclure à la fois dans les descripteurs d'éléments et les embeddings d'état

### Exigence 8: Représentation d'État Contextuelle

**User Story:** En tant que développeur RPA, je veux que le système inclue le contexte workflow dans les représentations d'état, afin que le même écran visuel puisse être interprété différemment selon la tâche en cours.

#### Critères d'Acceptation

1. OÙ le contexte workflow est disponible (ID patient, numéro de facture, type de document), ALORS le Système GeniusIA DOIT l'inclure dans l'embedding d'état
2. QUAND le contexte change, ALORS l'empreinte d'état DOIT refléter la différence contextuelle
3. QUAND des états sont comparés, ALORS le Système GeniusIA DOIT pondérer la similarité contextuelle de manière appropriée
4. QUAND le contexte est manquant, ALORS le Système GeniusIA DOIT quand même générer un embedding d'état valide en utilisant les informations disponibles
5. QUAND les étapes de workflow sont stockées, ALORS le Système GeniusIA DOIT capturer le contexte qui était présent pendant l'enregistrement

### Exigence 9: Compatibilité Arrière

**User Story:** En tant que mainteneur système, je veux que la nouvelle détection au niveau élément coexiste avec la correspondance plein écran existante, afin de pouvoir migrer progressivement sans casser les workflows existants.

#### Critères d'Acceptation

1. QUAND le système de détection d'éléments est activé, ALORS le Système GeniusIA DOIT continuer à supporter les workflows de correspondance plein écran existants
2. QUAND un workflow utilise des captures plein écran de l'ancien style, ALORS le Système GeniusIA DOIT les traiter en utilisant le système de correspondance legacy
3. QUAND un workflow utilise de nouveaux descripteurs au niveau élément, ALORS le Système GeniusIA DOIT utiliser le système de correspondance amélioré
4. QUAND des workflows sont migrés, ALORS le Système GeniusIA DOIT fournir des outils pour convertir les workflows plein écran en workflows au niveau élément
5. QUAND les deux systèmes sont actifs, ALORS le Système GeniusIA DOIT permettre la configuration pour préférer une approche plutôt que l'autre

### Exigence 10: Performance et Scalabilité

**User Story:** En tant qu'administrateur système, je veux que la détection d'éléments et l'embedding multi-modal soient performants, afin que le système RPA reste réactif pendant l'automatisation.

#### Critères d'Acceptation

1. QUAND des éléments d'UI sont détectés, ALORS le Système GeniusIA DOIT compléter le traitement en moins de 2 secondes pour un écran typique
2. QUAND des embeddings d'état sont générés, ALORS le Gestionnaire d'Embeddings DOIT compléter le traitement en moins de 1 seconde
3. QUAND des empreintes d'état sont comparées, ALORS le Système GeniusIA DOIT effectuer la recherche de similarité en moins de 100ms
4. QUAND l'extraction de texte VLM est traitée, ALORS le Système GeniusIA DOIT mettre en cache les résultats pour éviter un traitement redondant
5. QUAND la base de données d'éléments devient volumineuse, ALORS le Système GeniusIA DOIT maintenir la performance des requêtes via une indexation appropriée

### Exigence 11: Structure de Données UIElement

**User Story:** En tant que développeur système, je veux une structure de données standardisée pour les éléments d'UI, afin de pouvoir stocker, rechercher et manipuler les éléments de manière cohérente.

#### Critères d'Acceptation

1. QUAND un UIElement est créé, ALORS le Système GeniusIA DOIT lui assigner un identifiant stable basé sur (app_name + centre_bbox + label_normalized)
2. QUAND un UIElement est stocké, ALORS le Système GeniusIA DOIT inclure les champs suivants : element_id, type, role, bbox, label, visual (screenshot_path + embedding), text (raw + normalized + embedding), properties (is_clickable, is_focusable, is_dangerous), context (app_name, window_title, workflow_hint), et tags
3. QUAND un embedding visuel d'élément est généré, ALORS le Système GeniusIA DOIT stocker le provider (ex: openclip_ViT-B-32) et le vector_id (chemin vers le fichier .npy)
4. QUAND un embedding textuel d'élément est généré, ALORS le Système GeniusIA DOIT stocker le texte brut, le texte normalisé, le provider et le vector_id
5. QUAND un UIElement est sérialisé, ALORS le Système GeniusIA DOIT utiliser le format JSON avec tous les champs requis

### Exigence 12: Structure de Données ScreenState Enrichi

**User Story:** En tant que développeur système, je veux que le ScreenState contienne à la fois les éléments d'UI détectés et l'embedding d'état unifié, afin d'avoir une représentation complète de l'écran.

#### Critères d'Acceptation

1. QUAND un ScreenState est créé, ALORS le Système GeniusIA DOIT inclure les champs suivants : screen_state_id, timestamp, session_id, window (app_name, window_title, screen_resolution), raw (screenshot_path), perception (detected_text), ui_elements (liste), state_embedding (provider, vector_id, components), et context
2. QUAND des éléments d'UI sont détectés, ALORS le Système GeniusIA DOIT les stocker dans le champ ui_elements du ScreenState
3. QUAND un state_embedding est généré, ALORS le Système GeniusIA DOIT stocker le vecteur final ainsi que ses composantes (image_embedding, text_embedding, title_embedding, ui_embedding, context_embedding)
4. QUAND un ScreenState est sérialisé, ALORS le Système GeniusIA DOIT utiliser le format JSON avec tous les champs requis
5. QUAND un ScreenState est chargé, ALORS le Système GeniusIA DOIT pouvoir reconstruire tous les embeddings à partir des vector_id stockés

### Exigence 13: Pipeline de Détection d'Éléments

**User Story:** En tant que développeur système, je veux un pipeline clair pour transformer un screenshot en liste d'UIElement, afin de pouvoir maintenir et améliorer le processus de détection.

#### Critères d'Acceptation

1. QUAND un screenshot est capturé, ALORS le Système GeniusIA DOIT exécuter les étapes suivantes dans l'ordre : (1) proposer des régions d'intérêt, (2) caractériser chaque élément, (3) classifier type et rôle
2. QUAND des régions d'intérêt sont proposées, ALORS le Système GeniusIA DOIT utiliser au moins une des méthodes suivantes : détection de zones de texte, repérage de rectangles autour de texte, ou requête VLM pour zones cliquables
3. QUAND un élément est caractérisé, ALORS le Système GeniusIA DOIT extraire : crop image de la zone, embedding image, texte dans/autour de la zone, embedding texte, et position bbox
4. QUAND un élément est classifié, ALORS le Système GeniusIA DOIT déterminer le type (button, text_input, checkbox, etc.) et le rôle sémantique (primary_action, dangerous_action, search_field, etc.)
5. QUAND le pipeline échoue sur un élément, ALORS le Système GeniusIA DOIT enregistrer l'erreur et continuer avec les autres éléments

### Exigence 14: Pipeline de Fusion Multi-Modale

**User Story:** En tant que développeur système, je veux un pipeline clair pour créer un state_embedding à partir de multiples modalités, afin de pouvoir ajuster les pondérations et améliorer la robustesse.

#### Critères d'Acceptation

1. QUAND un state_embedding est généré, ALORS le Système GeniusIA DOIT calculer les composantes suivantes : image_embedding (screenshot entier), text_embedding (texte concaténé détecté), title_embedding (window_title), ui_embedding (moyenne des embeddings d'éléments importants), et context_embedding (vecteur de contexte workflow)
2. QUAND les composantes sont fusionnées, ALORS le Gestionnaire d'Embeddings DOIT normaliser chaque vecteur avant fusion
3. QUAND la fusion est effectuée, ALORS le Gestionnaire d'Embeddings DOIT utiliser une combinaison pondérée avec les poids configurables suivants par défaut : w_img=0.5, w_text=0.3, w_title=0.1, w_ui=0.1, w_ctx=0.1
4. QUAND le vecteur final est produit, ALORS le Gestionnaire d'Embeddings DOIT le normaliser pour avoir une norme unitaire
5. QUAND les composantes individuelles sont calculées, ALORS le Système GeniusIA DOIT les stocker séparément pour permettre le debug et l'analyse

### Exigence 15: Implémentation Progressive

**User Story:** En tant que mainteneur système, je veux pouvoir activer les nouvelles fonctionnalités progressivement, afin de minimiser les risques et de valider chaque étape.

#### Critères d'Acceptation

1. QUAND le système est en mode "light", ALORS le Système GeniusIA DOIT ajouter les champs ui_elements (vide) et state_embedding (image uniquement) au JSON sans changer la logique existante
2. QUAND le système est en mode "enrichi", ALORS le Système GeniusIA DOIT détecter les UIElement pour certains écrans configurés tout en maintenant la compatibilité avec le mode light
3. QUAND le système est en mode "complet", ALORS le Système GeniusIA DOIT calculer le state_embedding fusionné avec toutes les modalités
4. QUAND un mode est activé, ALORS le Système GeniusIA DOIT permettre la configuration via un fichier de configuration ou des variables d'environnement
5. QUAND un mode change, ALORS le Système GeniusIA DOIT continuer à lire les anciens formats de données tout en écrivant dans le nouveau format
