# UIChangeDetector - Détecteur de Changements UI

## Vue d'ensemble

Le `UIChangeDetector` est un composant essentiel du système RPA Vision V2 qui surveille les changements d'interface utilisateur et déclenche le ré-entraînement lorsque nécessaire. Il détecte deux types de dérives :

1. **Dérive visuelle** : Changements dans l'apparence des éléments UI (détectés via similarité d'embeddings)
2. **Dérive de position** : Déplacements des éléments UI (détectés via delta de bounding box)

## Fonctionnalités principales

### 1. Détection de changements visuels

```python
change_detected, similarity = detector.detect_ui_change(
    current_embedding,
    stored_embeddings,
    task_id
)
```

Compare l'embedding visuel actuel avec les embeddings stockés pour détecter si l'UI a changé. Un changement est détecté si la similarité maximale est inférieure au seuil (70% par défaut).

### 2. Calcul de delta de position

```python
deltas = detector.calculate_delta(
    predicted_bbox=(100, 200, 50, 30),
    actual_bbox=(105, 203, 50, 30)
)
```

Calcule les différences en pixels entre la position prédite et la position réelle d'un élément UI. Retourne :
- `delta_x` : Différence en X
- `delta_y` : Différence en Y
- `delta_width` : Différence en largeur
- `delta_height` : Différence en hauteur
- `delta_center` : Distance euclidienne entre les centres
- `max_delta` : Delta maximum (position)

### 3. Décision de ré-entraînement

```python
should_retrain = detector.should_trigger_retraining(deltas, similarity)
```

Détermine si le ré-entraînement doit être déclenché en fonction de :
- Delta de position > seuil (10 pixels par défaut)
- OU similarité visuelle < seuil (70% par défaut)

### 4. Déclenchement de ré-entraînement

```python
detector.trigger_retraining(
    task_id="ouvrir_facture",
    reason="position_drift",
    metadata={"delta": 25.0}
)
```

Enregistre un événement de ré-entraînement dans les logs et l'historique.

### 5. Vérification complète

```python
result = detector.check_and_trigger_retraining(
    task_id="ouvrir_facture",
    current_embedding=current_emb,
    stored_embeddings=stored_embs,
    predicted_bbox=(100, 200, 50, 30),
    actual_bbox=(150, 230, 50, 30)
)
```

Effectue une vérification complète et déclenche automatiquement le ré-entraînement si nécessaire. Retourne un dictionnaire avec :
- `ui_change_detected` : Changement visuel détecté
- `position_drift_detected` : Dérive de position détectée
- `retraining_triggered` : Ré-entraînement déclenché
- `similarity` : Similarité maximale trouvée
- `deltas` : Dictionnaire des deltas de position

## Configuration

Les seuils sont configurables via le fichier `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 avec LearningManager

Le `UIChangeDetector` est intégré dans le `LearningManager` pour une surveillance continue :

```python
# Dans LearningManager
result = self.check_ui_changes(
    task_id="ouvrir_facture",
    current_embedding=current_emb,
    predicted_bbox=predicted_bbox,
    actual_bbox=actual_bbox
)

if result.get("retraining_triggered"):
    # Le système ajoute automatiquement le nouvel embedding
    # et met à jour l'index FAISS
    pass
```

### Surveillance de la dérive d'exécution

```python
# Surveiller la différence entre prédiction et réalité
drift_detected = learning_manager.monitor_execution_drift(
    task_id="ouvrir_facture",
    predicted_action=predicted_action,
    actual_action=actual_action
)
```

## Historique et statistiques

### Consulter l'historique

```python
# Tous les changements
history = detector.get_change_history()

# Changements pour une tâche spécifique
history = detector.get_change_history(task_id="ouvrir_facture", limit=20)
```

### Obtenir les statistiques

```python
stats = detector.get_stats()
# Retourne:
# {
#     "total_changes_detected": 15,
#     "retraining_triggered_count": 8,
#     "changes_by_task": {
#         "ouvrir_facture": 5,
#         "valider_commande": 3
#     },
#     "ui_change_threshold": 0.70,
#     "bbox_delta_threshold": 10
# }
```

## Cas d'usage

### 1. Détection de mise à jour d'interface

Lorsqu'une application est mise à jour et que l'interface change :

```python
# L'embedding actuel sera différent des embeddings stockés
change_detected, similarity = detector.detect_ui_change(
    current_embedding,
    stored_embeddings,
    "ouvrir_facture"
)

if change_detected:
    print(f"Mise à jour UI détectée (similarité: {similarity:.2%})")
    # Le système demandera à l'utilisateur de ré-observer la tâche
```

### 2. Détection de déplacement d'éléments

Lorsque des éléments UI se déplacent (ex: fenêtre redimensionnée) :

```python
deltas = detector.calculate_delta(
    predicted_bbox=(100, 200, 50, 30),
    actual_bbox=(150, 230, 50, 30)
)

if deltas['max_delta'] > 10:
    print(f"Élément déplacé de {deltas['max_delta']:.0f} pixels")
    # Le système ajustera automatiquement ses prédictions
```

### 3. Surveillance continue en mode Autopilot

En mode Autopilot, le système surveille automatiquement chaque exécution :

```python
# Après chaque action automatisée
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']:
    # Rétrograder au mode Assisté pour validation
    learning_manager.rollback_if_low_confidence(current_task_id)
```

## Exigences satisfaites

Ce module satisfait les exigences suivantes du document de requirements :

- **Exigence 4.1** : Calcul du delta entre emplacement prédit et réel
- **Exigence 4.2** : Déclenchement du ré-entraînement si delta > 10 pixels
- **Exigence 6.5** : Détection de changements UI (similarité < 70%)

## Tests

Un test complet est disponible dans `test_ui_change_detector_simple.py` :

```bash
python3 test_ui_change_detector_simple.py
```

Le test vérifie :
- Détection de changements visuels
- Calcul de deltas de position
- Décisions de ré-entraînement
- Déclenchement de ré-entraînement
- Vérification complète
- Statistiques et historique

## Architecture

```
UIChangeDetector
├── detect_ui_change()           # Détection visuelle
├── calculate_delta()            # Calcul delta position
├── should_trigger_retraining()  # Décision
├── trigger_retraining()         # Déclenchement
├── check_and_trigger_retraining() # Vérification complète
├── get_change_history()         # Historique
├── get_stats()                  # Statistiques
└── clear_history()              # Nettoyage

Intégration LearningManager
├── check_ui_changes()           # Vérification avec mise à jour
├── monitor_execution_drift()    # Surveillance continue
└── get_ui_change_stats()        # Statistiques globales
```

## Journalisation

Tous les événements sont enregistrés dans le logger chiffré :

- `ui_change_detected` : Changement UI détecté
- `ui_stable` : UI stable (pas de changement)
- `bbox_delta_calculated` : Delta de position calculé
- `retraining_decision` : Décision de ré-entraînement
- `retraining_triggered` : Ré-entraînement déclenché
- `ui_change_retraining` : Ré-entraînement suite à changement UI

## Bonnes pratiques

1. **Seuils adaptatifs** : Ajuster les seuils en fonction du type d'application
2. **Historique limité** : Utiliser `limit` pour éviter de surcharger la mémoire
3. **Nettoyage périodique** : Effacer l'historique ancien avec `clear_history()`
4. **Surveillance continue** : Intégrer dans la boucle cognitive de l'orchestrateur
5. **Feedback utilisateur** : Notifier l'utilisateur lors de changements détectés

## Limitations

- La détection visuelle dépend de la qualité des embeddings OpenCLIP
- Les vecteurs aléatoires en haute dimension ont naturellement une similarité modérée (~0.5-0.9)
- Le seuil de 70% peut nécessiter un ajustement selon les cas d'usage
- La détection de position nécessite des bounding boxes précises

## Évolutions futures

- Seuils adaptatifs par tâche
- Détection de patterns de changements récurrents
- Prédiction proactive de changements UI
- Apprentissage des zones stables vs zones volatiles
- Intégration avec un système de versioning d'UI
