rpa_vision_v3/.kiro/specs/rpa-vision-excellence/design.md

# Document de Conception : RPA Vision Excellence

## Vue d'ensemble

Cette conception transforme RPA Vision V3 en un système RPA 100% Vision de niveau production en ajoutant quatre composants majeurs :

1. **Validateur de Qualité d'Entraînement** - Validation et métriques de qualité d'entraînement
2. **Matcher Hiérarchique** - Matching multi-niveau robuste
3. **Apprenant Continu** - Apprentissage continu et adaptation
4. **Gestionnaire de Variantes** - Gestion des variantes et états dynamiques

L'architecture s'intègre aux composants existants (GraphBuilder, WorkflowPipeline, ExecutionLoop) sans les remplacer.

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                        RPA Vision Excellence                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────────┐    ┌──────────────────┐    ┌────────────────┐ │
│  │ Training Quality │    │   Hierarchical   │    │   Continuous   │ │
│  │    Validator     │    │     Matcher      │    │    Learner     │ │
│  └────────┬─────────┘    └────────┬─────────┘    └───────┬────────┘ │
│           │                       │                       │         │
│           ▼                       ▼                       ▼         │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                      Variant Manager                         │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │   │
│  │  │   Variant   │  │    State    │  │   Drift Detector    │   │   │
│  │  │   Cluster   │  │   Tracker   │  │                     │   │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘   │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                     Existing Components                             │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐     | 
│  │   Graph    │  │  Workflow  │  │  Execution │  │    FAISS   │     │   
│  │  Builder   │  │  Pipeline  │  │    Loop    │  │   Manager  │     │  
│  └────────────┘  └────────────┘  └────────────┘  └────────────┘     │
└─────────────────────────────────────────────────────────────────────┘
```

## Composants et Interfaces

### 1. Validateur de Qualité d'Entraînement

```python
class TrainingQualityValidator:
    """Valide la qualité des workflows entraînés"""
    
    def validate_workflow(self, workflow: Workflow, 
                         observations: List[ScreenState]) -> QualityReport
    
    def compute_cluster_metrics(self, embeddings: np.ndarray, 
                                labels: np.ndarray) -> ClusterMetrics
    
    def detect_outliers(self, embeddings: np.ndarray) -> List[int]
    
    def cross_validate(self, workflow: Workflow, 
                      observations: List[ScreenState],
                      holdout_ratio: float = 0.2) -> ValidationResult

@dataclass
class QualityReport:
    overall_score: float  # 0.0 - 1.0
    cluster_metrics: Dict[str, ClusterMetrics]
    outlier_indices: List[int]
    validation_accuracy: float
    recommendations: List[str]
    is_production_ready: bool

@dataclass
class ClusterMetrics:
    silhouette_score: float  # Score de silhouette
    cohesion: float          # Cohésion intra-cluster
    separation: float        # Séparation inter-cluster
    sample_count: int        # Nombre d'échantillons
    is_sufficient: bool      # Données suffisantes
```

### 2. Matcher Hiérarchique

```python
class HierarchicalMatcher:
    """Système de matching multi-niveau"""
    
    def match(self, screenshot: Image, 
              workflow: Workflow,
              temporal_context: Optional[TemporalContext] = None) -> MatchResult
    
    def match_window_level(self, window_info: WindowContext,
                          node: WorkflowNode) -> float
    
    def match_region_level(self, regions: List[UIRegion],
                          template_regions: List[UIRegion]) -> float
    
    def match_element_level(self, elements: List[UIElement],
                           template_elements: List[UIElement]) -> float

@dataclass
class MatchResult:
    node_id: str
    confidence: float              # Confiance globale
    window_confidence: float       # Confiance niveau fenêtre
    region_confidence: float       # Confiance niveau région
    element_confidence: float      # Confiance niveau élément
    temporal_boost: float          # Bonus temporel
    matched_variant: Optional[str] # Variante matchée
    alternatives: List[AlternativeMatch]

@dataclass
class TemporalContext:
    previous_nodes: List[str]       # N derniers nodes matchés
    previous_confidences: List[float]
    time_since_last_match: float    # Temps depuis dernier match
```

### 3. Apprenant Continu

```python
class ContinuousLearner:
    """Apprentissage continu et adaptation"""
    
    def update_prototype(self, node_id: str, 
                        new_embedding: np.ndarray,
                        execution_success: bool) -> None
    
    def detect_drift(self, node_id: str,
                    recent_confidences: List[float]) -> DriftStatus
    
    def create_variant(self, node_id: str,
                      variant_embedding: np.ndarray) -> str
    
    def consolidate_variants(self, node_id: str) -> None
    
    def rollback_prototype(self, node_id: str, version: int) -> None

@dataclass
class DriftStatus:
    is_drifting: bool                # Dérive détectée
    drift_severity: float            # Sévérité 0.0 - 1.0
    consecutive_low_confidence: int  # Matchs faibles consécutifs
    recommended_action: str          # "monitor", "create_variant", "retrain"

class PrototypeVersionManager:
    """Gère l'historique des versions de prototypes"""
    
    def save_version(self, node_id: str, embedding: np.ndarray) -> int
    def get_version(self, node_id: str, version: int) -> np.ndarray
    def list_versions(self, node_id: str) -> List[VersionInfo]
```

### 4. Gestionnaire de Variantes

```python
class VariantManager:
    """Gère les variantes d'écran et états UI"""
    
    def detect_variants(self, embeddings: List[np.ndarray],
                       similarity_threshold: float = 0.7) -> List[VariantCluster]
    
    def match_with_variants(self, query_embedding: np.ndarray,
                           node_id: str) -> VariantMatchResult
    
    def add_variant(self, node_id: str, 
                   variant_embedding: np.ndarray,
                   metadata: Dict) -> str
    
    def detect_ui_states(self, elements: List[UIElement]) -> Dict[str, UIState]
    
    def detect_overlay(self, screenshot: Image,
                      baseline: Image) -> Optional[OverlayInfo]

@dataclass
class VariantCluster:
    variant_id: str
    prototype: np.ndarray
    member_count: int                # Nombre de membres
    similarity_to_primary: float     # Similarité avec prototype principal

@dataclass
class UIState(Enum):
    ENABLED = "enabled"      # Activé
    DISABLED = "disabled"    # Désactivé
    CHECKED = "checked"      # Coché
    UNCHECKED = "unchecked"  # Non coché
    LOADING = "loading"      # Chargement
    ERROR = "error"          # Erreur
    FOCUSED = "focused"      # Focus

@dataclass
class OverlayInfo:
    overlay_type: str  # "modal", "popup", "tooltip", "dropdown"
    bounds: Tuple[int, int, int, int]  # Coordonnées
    blocking: bool     # Bloquant
```

## Modèles de Données

### WorkflowNode Amélioré

```python
@dataclass
class EnhancedWorkflowNode(WorkflowNode):
    # Champs existants hérités
    
    # Nouveaux champs pour variantes
    variants: List[NodeVariant] = field(default_factory=list)
    primary_variant_id: str = "primary"
    
    # Métriques de qualité
    quality_score: float = 0.0
    observation_count: int = 0
    
    # Versioning des prototypes
    prototype_version: int = 1
    prototype_history: List[str] = field(default_factory=list)

@dataclass
class NodeVariant:
    variant_id: str
    embedding_path: str
    similarity_to_primary: float  # Similarité avec prototype principal
    observation_count: int        # Nombre d'observations
    created_at: datetime
    metadata: Dict[str, Any]
```

### Relations Spatiales

```python
@dataclass
class SpatialRelation:
    source_element_id: str
    target_element_id: str
    relation_type: str  # "above", "below", "left_of", "right_of", "inside"
    distance: float     # Distance en pixels
    confidence: float   # Confiance de la relation

@dataclass
class SemanticContainer:
    container_id: str
    container_type: str  # "form", "menu", "toolbar", "dialog", "list"
    element_ids: List[str]  # IDs des éléments contenus
    bounds: Tuple[int, int, int, int]  # Coordonnées du conteneur
```

## Propriétés de Correction

*Une propriété est une caractéristique ou un comportement qui doit être vrai pour toutes les exécutions valides d'un système - essentiellement, une déclaration formelle de ce que le système doit faire. Les propriétés servent de pont entre les spécifications lisibles par l'humain et les garanties de correction vérifiables par machine.*

### Propriété 1 : Cohérence de la Qualité des Clusters
*Pour tout* ensemble d'embeddings assignés à un cluster, le score de silhouette calculé par Training_Quality_Validator DOIT être cohérent avec la fonction silhouette_score de sklearn avec une tolérance de 0.01
**Valide : Exigences 1.1**

### Propriété 2 : Correction de la Détection d'Outliers
*Pour tout* ensemble d'embeddings, les outliers détectés par la méthode IQR DOIVENT avoir une distance au centroïde du cluster supérieure à Q3 + 1.5*IQR
**Valide : Exigences 1.3**

### Propriété 3 : Précision de la Validation Croisée
*Pour tout* workflow avec N observations, la validation croisée avec 20% de holdout DOIT correctement matcher au moins 80% des observations retenues vers leurs nodes originaux
**Valide : Exigences 1.5**

### Propriété 4 : Bornes de Confiance Hiérarchique
*Pour tout* résultat de match du Hierarchical_Matcher, la confiance finale DOIT être égale à 0.2*fenêtre + 0.3*région + 0.5*élément avec une tolérance de 0.001
**Valide : Exigences 2.4**

### Propriété 5 : Correction du Boost Temporel
*Pour tout* match où le node matché est un successeur valide du node précédent, la confiance DOIT être augmentée de exactement 0.1 (plafonnée à 1.0)
**Valide : Exigences 2.5**

### Propriété 6 : Mise à Jour du Prototype par EMA
*Pour toute* mise à jour de prototype, le nouveau prototype DOIT être égal à (1-alpha)*ancien_prototype + alpha*nouvel_embedding où alpha=0.1
**Valide : Exigences 3.1**

### Propriété 7 : Seuil de Détection de Dérive
*Pour toute* séquence de 3 exécutions consécutives avec une confiance inférieure à 0.85, le Drift_Detector DOIT signaler une dérive potentielle
**Valide : Exigences 3.2**

### Propriété 8 : Seuil de Similarité des Variantes
*Pour toute* variante créée, sa similarité avec le prototype principal DOIT être inférieure à 0.7 (différence > 0.3)
**Valide : Exigences 4.2**

### Propriété 9 : Sélection de la Meilleure Variante
*Pour tout* match contre un node avec variantes, le match retourné DOIT avoir la plus haute similarité parmi toutes les variantes
**Valide : Exigences 4.3**

### Propriété 10 : Symétrie des Relations Spatiales
*Pour toute* relation spatiale "A à_gauche_de B", il DOIT exister une relation correspondante "B à_droite_de A"
**Valide : Exigences 5.1**

### Propriété 11 : Backoff Exponentiel des Retries
*Pour toute* action échouée avec retries, les temps d'attente DOIVENT suivre le pattern : temps_base * 2^(tentative-1) pour les tentatives 1, 2, 3
**Valide : Exigences 7.1**

## Gestion des Erreurs

### Erreurs d'Entraînement
- **InsufficientDataError** : Levée quand un cluster a moins de 3 observations
- **LowQualityClusterError** : Levée quand le score de silhouette < 0.5
- **OutlierDominanceError** : Levée quand les outliers dépassent 30% des observations

### Erreurs de Matching
- **NoMatchFoundError** : Levée quand aucun node ne matche au-dessus du seuil
- **AmbiguousMatchError** : Levée quand plusieurs nodes matchent avec confiance similaire
- **TemporalInconsistencyError** : Levée quand le node matché n'est pas atteignable depuis le précédent

### Erreurs d'Apprentissage
- **DriftConfirmedError** : Levée quand la dérive est confirmée et nécessite action utilisateur
- **VariantLimitExceededError** : Levée quand un node dépasse 5 variantes
- **PrototypeCorruptionError** : Levée quand la mise à jour du prototype produit un embedding invalide

## Stratégie de Tests

### Tests Unitaires
- Tester chaque composant isolément avec dépendances mockées
- Tester les cas limites : entrées vides, observation unique, variantes maximum
- Tester les conditions d'erreur et la gestion des exceptions

### Tests Basés sur les Propriétés
- Utiliser la bibliothèque Hypothesis pour les tests property-based en Python
- Chaque propriété de correction DOIT avoir un test property correspondant
- Configurer minimum 100 itérations par test property
- Taguer chaque test avec : `**Feature: rpa-vision-excellence, Property {N}: {description}**`

### Tests d'Intégration
- Tester le pipeline complet : entraînement → validation → matching → exécution
- Tester le cycle d'apprentissage continu avec changements UI simulés
- Tester les workflows de création et consolidation de variantes

### Tests de Performance
- Latence de matching : < 100ms pour un screenshot
- Validation d'entraînement : < 5s pour un workflow avec 100 observations
- Mise à jour de prototype : < 10ms par mise à jour