rpa_vision_v3/docs/architecture/ARCHITECTURE_APPRENTISSAGE.md

🏗️ Architecture d'Apprentissage - RPA Vision V3

Date: 8 janvier 2026 - 00:45 Révélation clé : 3 systèmes d'apprentissage complémentaires

---

🎯 Vision Architecturale Complète

3 Niveaux d'Apprentissage

┌─────────────────────────────────────────────────────────────┐
│                    RPA VISION V3                            │
│                  Système d'Apprentissage                    │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   AGENT V0    │   │   SYSTÈME 2   │   │   SYSTÈME 3   │
│   (Léger)     │   │   (Complet)   │   │   (Complet)   │
└───────────────┘   └───────────────┘   └───────────────┘
│                   │                   │
│ • Capture        │ • Capture        │ • Capture
│   screenshots    │   screenshots    │   screenshots
│ • Events basiques│ • Events détaillés│ • Events détaillés
│ • SANS analyse   │ • AVEC analyse UI│ • AVEC analyse UI
│   locale         │   locale         │   locale
│ • Window title   │ • OCR            │ • OCR avancé
│   seulement      │ • UI elements    │ • UI elements
│                  │ • Text detection │ • Text detection
│                  │                  │ • Context métier
│                  │                  │
│ Workflows        │ Workflows        │ Workflows
│ SIMPLES          │ RICHES           │ TRÈS RICHES
└──────────────────┴──────────────────┴──────────────────

---

📊 Comparaison des Systèmes

Agent V0 (Actuel)

Objectif : Amorçage rapide sans impact utilisateur

Données capturées :

• ✅ Screenshots (PNG)
• ✅ Events (click, keyboard)
• ✅ Window title (basique)
• ✅ Timestamps
• ❌ Pas d'analyse UI locale
• ❌ Pas d'OCR
• ❌ Pas de détection éléments

Workflows générés :

• Embedding prototype (CLIP)
• Window title pattern (si disponible)
• Contraintes minimales

Avantages :

• Léger (pas d'analyse CPU)
• Déploiement rapide
• Pas d'impact utilisateur
• Phase d'amorçage

Limitations :

• Précision matching : ~85%
• Pas de contraintes UI/Text
• Workflows "génériques"

---

Systèmes 2 & 3 (Futurs/Existants)

Objectif : Apprentissage complet avec analyse riche

Données capturées :

• ✅ Tout de Agent V0
• ✅ OCR complet (textes détectés)
• ✅ UI elements (rôles, types, positions)
• ✅ Arbre d'accessibilité
• ✅ Context métier riche
• ✅ Business variables

Workflows générés :

• Embedding prototype (CLIP)
• Window constraints (title, process)
• Text constraints (required_texts, forbidden_texts)
• UI constraints (required_roles, min_element_count)
• Contraintes métier

Avantages :

• Précision matching : ~95%
• Workflows robustes
• Gestion variantes UI
• Production-ready

---

🎯 Stratégie Option B - Architecture Progressive

Principe Clé : Dégradation Gracieuse

L'implémentation doit :

1. ✅ Fonctionner avec données minimales (agent_v0)
2. ✅ S'enrichir automatiquement si plus de données disponibles
3. ✅ Pas échouer si contraintes non disponibles
4. ✅ Compatible avec futurs systèmes riches

Code Proposé

def _create_screen_template(
    self,
    states: List[ScreenState],
    prototype_embedding: np.ndarray,
    cluster_id: int
) -> ScreenTemplate:
    """
    Créer ScreenTemplate avec architecture progressive.

    S'adapte automatiquement au niveau de richesse des données :
    - Agent V0 : Embedding + window title
    - Systèmes 2/3 : Embedding + window + text + ui
    """
    # 1. Sauvegarder prototype (TOUJOURS)
    prototype_dir = Path(self.storage.base_path) / "prototypes"
    prototype_dir.mkdir(parents=True, exist_ok=True)
    prototype_path = prototype_dir / f"cluster_{cluster_id}.npy"
    np.save(prototype_path, prototype_embedding)

    # 2. Créer EmbeddingPrototype (TOUJOURS)
    embedding_proto = EmbeddingPrototype(
        provider="openclip_ViT-B-32",
        vector_id=str(prototype_path),
        min_cosine_similarity=0.85,
        sample_count=len(states)
    )

    # 3. Extraire WindowConstraint (PROGRESSIF)
    window = self._extract_window_constraint(states)

    # 4. Extraire TextConstraint (PROGRESSIF)
    text = self._extract_text_constraint(states)

    # 5. Extraire UIConstraint (PROGRESSIF)
    ui = self._extract_ui_constraint(states)

    # 6. Créer ScreenTemplate
    return ScreenTemplate(
        window=window,
        text=text,
        ui=ui,
        embedding=embedding_proto
    )


def _extract_window_constraint(self, states: List[ScreenState]) -> WindowConstraint:
    """
    Extraire contraintes de fenêtre depuis les états.

    AGENT V0 : Window title seulement
    SYSTÈMES 2/3 : Window title + process name + patterns
    """
    window_data = []

    for state in states:
        if hasattr(state, 'window') and state.window:
            if hasattr(state.window, 'window_title'):
                window_data.append({
                    'title': state.window.window_title,
                    'app': getattr(state.window, 'app_name', None)
                })

    if not window_data:
        # Pas de données window disponibles
        return WindowConstraint(
            title_pattern=".*",  # Accepte tout
            process_name=None
        )

    # Trouver pattern commun dans les titres
    titles = [w['title'] for w in window_data if w['title']]
    common_substring = self._find_common_substring(titles)

    # Trouver app commune
    apps = [w['app'] for w in window_data if w['app']]
    common_app = apps[0] if apps and all(a == apps[0] for a in apps) else None

    return WindowConstraint(
        title_contains=common_substring if common_substring else None,
        process_name=common_app
    )


def _extract_text_constraint(self, states: List[ScreenState]) -> TextConstraint:
    """
    Extraire contraintes de texte depuis les états.

    AGENT V0 : Vide (pas d'OCR)
    SYSTÈMES 2/3 : Textes requis/interdits
    """
    all_texts = []

    for state in states:
        if hasattr(state, 'perception') and state.perception:
            if hasattr(state.perception, 'detected_text'):
                detected = state.perception.detected_text
                if isinstance(detected, list):
                    all_texts.append(set(detected))

    if not all_texts:
        # Pas de textes détectés (agent_v0)
        return TextConstraint(
            required_texts=[],
            forbidden_texts=[]
        )

    # Trouver textes présents dans TOUS les états (requis)
    required = set.intersection(*all_texts) if all_texts else set()

    return TextConstraint(
        required_texts=list(required)[:5],  # Max 5 textes requis
        forbidden_texts=[]  # TODO: Analyser textes absents
    )


def _extract_ui_constraint(self, states: List[ScreenState]) -> UIConstraint:
    """
    Extraire contraintes UI depuis les états.

    AGENT V0 : Vide (pas d'analyse UI)
    SYSTÈMES 2/3 : Rôles/types requis
    """
    all_roles = []
    all_types = []
    element_counts = []

    for state in states:
        if hasattr(state, 'ui_elements') and state.ui_elements:
            roles = [el.role for el in state.ui_elements if hasattr(el, 'role')]
            types = [el.type for el in state.ui_elements if hasattr(el, 'type')]
            all_roles.append(set(roles))
            all_types.append(set(types))
            element_counts.append(len(state.ui_elements))

    if not all_roles:
        # Pas d'éléments UI détectés (agent_v0)
        return UIConstraint(
            required_roles=[],
            required_types=[],
            min_element_count=0
        )

    # Rôles présents dans TOUS les états
    common_roles = set.intersection(*all_roles) if all_roles else set()
    common_types = set.intersection(*all_types) if all_types else set()

    return UIConstraint(
        required_roles=list(common_roles)[:3],
        required_types=list(common_types)[:3],
        min_element_count=min(element_counts) if element_counts else 0
    )


def _find_common_substring(self, strings: List[str]) -> Optional[str]:
    """
    Trouver la plus longue sous-chaîne commune.

    Utilisé pour extraire patterns de window title.
    """
    if not strings or len(strings) < 2:
        return strings[0] if strings else None

    # Algorithme simple : trouver mots communs
    from collections import Counter

    all_words = []
    for s in strings:
        # Nettoyer et séparer en mots
        words = s.replace('-', ' ').replace('_', ' ').split()
        all_words.extend(words)

    # Compter occurrences
    word_counts = Counter(all_words)

    # Garder mots présents dans >50% des strings
    threshold = len(strings) / 2
    common_words = [word for word, count in word_counts.items() if count >= threshold]

    if common_words:
        # Retourner le mot le plus fréquent
        return max(common_words, key=lambda w: word_counts[w])

    return None

---

🎯 Avantages de cette Architecture

Pour Agent V0 (Maintenant)

• ✅ Fonctionne avec données minimales
• ✅ Workflows créés : embedding + window title
• ✅ Précision : ~85-90% (bon pour amorçage)
• ✅ Pas d'erreur si contraintes manquantes

Pour Systèmes 2/3 (Futur)

• ✅ S'enrichit automatiquement
• ✅ Workflows complets : embedding + window + text + ui
• ✅ Précision : ~95% (production)
• ✅ Même code, résultats plus riches

Évolutivité

• ✅ Pas de refactoring quand Systèmes 2/3 déployés
• ✅ Migration progressive des workflows
• ✅ Compatibilité ascendante/descendante
• ✅ Réutilisation des prototypes embeddings

---

📊 Exemple de Workflow Généré

Avec Agent V0

{
  "node_id": "node_001",
  "screen_template": {
    "window": {
      "title_contains": "Document",
      "process_name": "DesktopEditors"
    },
    "text": {
      "required_texts": [],
      "forbidden_texts": []
    },
    "ui": {
      "required_roles": [],
      "required_types": [],
      "min_element_count": 0
    },
    "embedding": {
      "provider": "openclip_ViT-B-32",
      "vector_id": "data/training/prototypes/cluster_1.npy",
      "min_cosine_similarity": 0.85,
      "sample_count": 12
    }
  }
}

Avec Système 2/3 (futur, données riches)

{
  "node_id": "node_001",
  "screen_template": {
    "window": {
      "title_contains": "Facturation T2A",
      "process_name": "chrome"
    },
    "text": {
      "required_texts": ["GHM", "Tarif", "Validation"],
      "forbidden_texts": ["Erreur"]
    },
    "ui": {
      "required_roles": ["button", "textbox"],
      "required_types": ["submit"],
      "min_element_count": 5
    },
    "embedding": {
      "provider": "openclip_ViT-B-32",
      "vector_id": "data/training/prototypes/cluster_1.npy",
      "min_cosine_similarity": 0.92,
      "sample_count": 45
    }
  }
}

---

🚀 Impact sur le Système

Court Terme (Agent V0)

• ✅ 8 workflows créés automatiquement
• ✅ Dashboard : 2 + 8 workflows visibles
• ✅ Précision matching : 85-90%
• ✅ Base pour apprentissage futur

Moyen Terme (Systèmes 2/3 déployés)

• ✅ Workflows s'enrichissent automatiquement
• ✅ Précision matching : 95%+
• ✅ Robustesse production
• ✅ Gestion variantes UI

Long Terme (Production)

• ✅ Fusion workflows agent_v0 + systèmes riches
• ✅ Migration progressive : workflows simples → riches
• ✅ Amélioration continue : chaque exécution enrichit
• ✅ Détection dégradation : si contraintes ne matchent plus

---

🎯 Recommandation Finale

OPTION B avec Architecture Progressive = PARFAIT pour ton cas !

Pourquoi :

1. ✅ Fonctionne maintenant avec agent_v0 (données minimales)
2. ✅ Prêt pour Systèmes 2/3 (auto-enrichissement)
3. ✅ Pas de refactoring futur nécessaire
4. ✅ Code production-ready et évolutif
5. ✅ Correspond exactement à ta vision architecturale

Prochaines étapes :

1. J'implémente _create_screen_template() avec extraction progressive
2. J'ajoute les 3 méthodes _extract_*_constraint()
3. Déploiement et test sur session agent_v0
4. Reprocessing des 8 sessions → 8 workflows créés
5. Validation : workflows simples mais fonctionnels

Temps estimé : 45 minutes (comme prévu) Résultat : Système évolutif prêt pour les 3 niveaux d'apprentissage

Puis-je continuer l'implémentation ? 🚀