Initial commit
This commit is contained in:
Dom
275
docs/implementation/UI_CHANGE_DETECTOR_IMPLEMENTATION_SUMMARY.md
Normal file
275
docs/implementation/UI_CHANGE_DETECTOR_IMPLEMENTATION_SUMMARY.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# Résumé d'Implémentation - UIChangeDetector
|
||||
|
||||
## Tâche Complétée
|
||||
|
||||
**Tâche 15.1** : Créer module de détection de dérive
|
||||
|
||||
## Fichiers Créés
|
||||
|
||||
### 1. `geniusia2/core/ui_change_detector.py`
|
||||
Module principal implémentant la classe `UIChangeDetector` avec les fonctionnalités suivantes :
|
||||
|
||||
#### Méthodes Principales
|
||||
|
||||
- **`detect_ui_change(current_embedding, stored_embeddings, task_id)`**
|
||||
- Détecte les changements visuels en comparant les embeddings
|
||||
- Seuil de similarité : 70% (configurable)
|
||||
- Retourne : (changement_détecté, similarité_max)
|
||||
|
||||
- **`calculate_delta(predicted_bbox, actual_bbox)`**
|
||||
- Calcule les deltas en pixels entre bbox prédite et réelle
|
||||
- Retourne : delta_x, delta_y, delta_width, delta_height, delta_center, max_delta
|
||||
|
||||
- **`should_trigger_retraining(deltas, similarity)`**
|
||||
- Décide si le ré-entraînement est nécessaire
|
||||
- Critères : delta > 10 pixels OU similarité < 70%
|
||||
|
||||
- **`trigger_retraining(task_id, reason, metadata)`**
|
||||
- Déclenche le ré-entraînement et enregistre l'événement
|
||||
- Journalise dans le logger chiffré
|
||||
|
||||
- **`check_and_trigger_retraining(...)`**
|
||||
- Vérification complète combinant détection visuelle et position
|
||||
- Déclenche automatiquement le ré-entraînement si nécessaire
|
||||
|
||||
- **`get_change_history(task_id, limit)`**
|
||||
- Retourne l'historique des changements détectés
|
||||
- Filtrage par tâche optionnel
|
||||
|
||||
- **`get_stats()`**
|
||||
- Statistiques globales sur les changements détectés
|
||||
|
||||
### 2. `geniusia2/core/learning_manager.py` (Modifications)
|
||||
|
||||
Intégration du UIChangeDetector dans le LearningManager :
|
||||
|
||||
#### Nouvelles Méthodes
|
||||
|
||||
- **`check_ui_changes(task_id, current_embedding, predicted_bbox, actual_bbox)`**
|
||||
- Vérifie les changements UI pour une tâche
|
||||
- Met à jour automatiquement les embeddings si ré-entraînement déclenché
|
||||
- Sauvegarde le profil mis à jour
|
||||
|
||||
- **`monitor_execution_drift(task_id, predicted_action, actual_action)`**
|
||||
- Surveille la dérive entre action prédite et action réelle
|
||||
- Retourne True si ré-entraînement déclenché
|
||||
|
||||
- **`get_ui_change_stats()`**
|
||||
- Retourne les statistiques du détecteur de changements
|
||||
|
||||
#### Modifications d'Initialisation
|
||||
|
||||
- Ajout de `self.ui_change_detector` dans `__init__`
|
||||
- Import de `UIChangeDetector` avec TYPE_CHECKING pour éviter les dépendances circulaires
|
||||
|
||||
### 3. `test_ui_change_detector_simple.py`
|
||||
|
||||
Test complet et autonome vérifiant :
|
||||
- Détection de changements visuels (UI stable vs changée)
|
||||
- Calcul de deltas de position (petite vs grande différence)
|
||||
- Décisions de ré-entraînement (3 scénarios)
|
||||
- Déclenchement de ré-entraînement
|
||||
- Vérification complète avec déclenchement automatique
|
||||
- Statistiques et historique
|
||||
- Filtrage de l'historique
|
||||
- Effacement de l'historique
|
||||
|
||||
**Résultat** : ✓ Tous les 14 tests réussis
|
||||
|
||||
### 4. `geniusia2/core/UI_CHANGE_DETECTOR_README.md`
|
||||
|
||||
Documentation complète incluant :
|
||||
- Vue d'ensemble et fonctionnalités
|
||||
- Exemples d'utilisation
|
||||
- Configuration des seuils
|
||||
- Intégration avec LearningManager
|
||||
- Cas d'usage pratiques
|
||||
- Architecture et journalisation
|
||||
- Bonnes pratiques et limitations
|
||||
|
||||
## Exigences Satisfaites
|
||||
|
||||
### Exigence 4.1
|
||||
✓ Calcul du delta entre emplacement prédit et réel d'un élément UI
|
||||
|
||||
### Exigence 4.2
|
||||
✓ Déclenchement du ré-entraînement si delta > 10 pixels
|
||||
|
||||
### Exigence 6.5
|
||||
✓ Détection de changements UI (similarité d'embedding < 70%)
|
||||
|
||||
## Configuration
|
||||
|
||||
Les seuils sont configurables via `core/config.py` :
|
||||
|
||||
```python
|
||||
CONFIG = {
|
||||
"thresholds": {
|
||||
"ui_change_similarity": 0.70, # Seuil de similarité (70%)
|
||||
"bbox_delta_pixels": 10 # Seuil de delta position (10 pixels)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Intégration dans le Workflow
|
||||
|
||||
### 1. Mode Shadow
|
||||
Le détecteur n'est pas actif (pas de prédictions à comparer)
|
||||
|
||||
### 2. Mode Assisté
|
||||
- Après chaque validation/correction utilisateur
|
||||
- Compare la prédiction avec l'action réelle
|
||||
- Déclenche le ré-entraînement si dérive détectée
|
||||
|
||||
### 3. Mode Autopilot
|
||||
- Surveillance continue après chaque action automatisée
|
||||
- Détection proactive des changements UI
|
||||
- Rétrogradation automatique au mode Assisté si dérive importante
|
||||
|
||||
## Flux de Détection
|
||||
|
||||
```
|
||||
Action Prédite
|
||||
↓
|
||||
Action Réelle (validée/détectée)
|
||||
↓
|
||||
UIChangeDetector.check_and_trigger_retraining()
|
||||
↓
|
||||
├─→ Détection Visuelle (embeddings)
|
||||
│ └─→ Similarité < 70% ? → Changement UI
|
||||
│
|
||||
├─→ Détection Position (bbox)
|
||||
│ └─→ Delta > 10px ? → Dérive Position
|
||||
│
|
||||
└─→ Décision Ré-entraînement
|
||||
├─→ OUI → trigger_retraining()
|
||||
│ ├─→ Logger l'événement
|
||||
│ ├─→ Ajouter nouvel embedding
|
||||
│ ├─→ Mettre à jour FAISS
|
||||
│ └─→ Sauvegarder profil
|
||||
│
|
||||
└─→ NON → Continuer normalement
|
||||
```
|
||||
|
||||
## Journalisation
|
||||
|
||||
Tous les événements sont enregistrés dans le logger chiffré :
|
||||
|
||||
- `ui_change_detector_initialized` : Initialisation
|
||||
- `ui_change_detected` : Changement UI détecté
|
||||
- `ui_stable` : UI stable
|
||||
- `bbox_delta_calculated` : Delta calculé
|
||||
- `retraining_decision` : Décision prise
|
||||
- `retraining_triggered` : Ré-entraînement déclenché
|
||||
- `ui_change_retraining` : Mise à jour suite à changement
|
||||
|
||||
## Tests et Validation
|
||||
|
||||
### Test Unitaire
|
||||
```bash
|
||||
python3 test_ui_change_detector_simple.py
|
||||
```
|
||||
|
||||
**Résultats** :
|
||||
- 14 tests exécutés
|
||||
- 14 tests réussis ✓
|
||||
- 0 échecs
|
||||
|
||||
### Diagnostics
|
||||
```bash
|
||||
# Aucune erreur de syntaxe, type ou lint
|
||||
✓ geniusia2/core/ui_change_detector.py
|
||||
✓ geniusia2/core/learning_manager.py
|
||||
```
|
||||
|
||||
## Utilisation Pratique
|
||||
|
||||
### Exemple 1 : Vérification Manuelle
|
||||
|
||||
```python
|
||||
from core.ui_change_detector import UIChangeDetector
|
||||
from core.embeddings_manager import EmbeddingsManager
|
||||
from core.logger import Logger
|
||||
from core.config import CONFIG
|
||||
|
||||
# Initialiser
|
||||
logger = Logger(log_dir="data/logs")
|
||||
embeddings_mgr = EmbeddingsManager(logger=logger)
|
||||
detector = UIChangeDetector(embeddings_mgr, logger, CONFIG)
|
||||
|
||||
# Vérifier un changement
|
||||
result = detector.check_and_trigger_retraining(
|
||||
task_id="ouvrir_facture",
|
||||
current_embedding=current_emb,
|
||||
stored_embeddings=task.embeddings,
|
||||
predicted_bbox=(100, 200, 50, 30),
|
||||
actual_bbox=(105, 203, 50, 30)
|
||||
)
|
||||
|
||||
if result['retraining_triggered']:
|
||||
print("Ré-entraînement nécessaire!")
|
||||
```
|
||||
|
||||
### Exemple 2 : Intégration LearningManager
|
||||
|
||||
```python
|
||||
# Dans l'orchestrateur, après une action
|
||||
result = learning_manager.check_ui_changes(
|
||||
task_id=current_task_id,
|
||||
current_embedding=detected_element.embedding,
|
||||
predicted_bbox=predicted_bbox,
|
||||
actual_bbox=detected_bbox
|
||||
)
|
||||
|
||||
if result['retraining_triggered']:
|
||||
# Notifier l'utilisateur
|
||||
gui.show_notification(
|
||||
"Changement UI détecté - Ré-entraînement en cours",
|
||||
type="warning"
|
||||
)
|
||||
```
|
||||
|
||||
## Points Techniques Importants
|
||||
|
||||
### 1. TYPE_CHECKING pour Imports
|
||||
Utilisation de `TYPE_CHECKING` pour éviter les imports circulaires :
|
||||
```python
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from .embeddings_manager import EmbeddingsManager
|
||||
from .logger import Logger
|
||||
```
|
||||
|
||||
### 2. Similarité Cosinus
|
||||
Conversion de la similarité cosinus de [-1, 1] vers [0, 1] :
|
||||
```python
|
||||
similarity = (cosine_similarity + 1.0) / 2.0
|
||||
```
|
||||
|
||||
### 3. Vecteurs Aléatoires
|
||||
Les vecteurs aléatoires en haute dimension (512-d) ont naturellement une similarité modérée (~0.5-0.9). Pour les tests, utiliser des vecteurs construits spécifiquement.
|
||||
|
||||
### 4. Historique Limité
|
||||
L'historique est stocké en mémoire. Utiliser `limit` et `clear_history()` pour gérer la mémoire.
|
||||
|
||||
## Prochaines Étapes
|
||||
|
||||
Le module est maintenant prêt pour :
|
||||
1. Intégration dans l'orchestrateur (tâche 8)
|
||||
2. Tests d'intégration avec le système complet
|
||||
3. Ajustement des seuils selon les cas d'usage réels
|
||||
4. Ajout de métriques de performance
|
||||
|
||||
## Statut Final
|
||||
|
||||
✅ **Tâche 15.1 : COMPLÉTÉE**
|
||||
✅ **Tâche 15 : COMPLÉTÉE**
|
||||
|
||||
Tous les critères d'acceptation sont satisfaits :
|
||||
- ✓ Classe UIChangeDetector implémentée dans core/
|
||||
- ✓ Méthode detect_ui_change() avec seuil 70%
|
||||
- ✓ Méthode calculate_delta() pour delta pixels
|
||||
- ✓ Méthode trigger_retraining() si delta > 10 pixels
|
||||
- ✓ Intégration dans learning_manager pour surveillance continue
|
||||
- ✓ Exigences 4.1, 4.2, 6.5 satisfaites
|
||||
Reference in New Issue
Block a user