# 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