rpa_vision_v3/docs/PLAN_ACTION_MARS_2026.md

# Plan d'action RPA Vision V3 — Mars 2026

**Date** : 10 mars 2026
**Auteur** : Dom + Claude
**Statut** : En cours de validation

---

## Diagnostic du projet

### Objectif du projet

Système RPA **100% basé sur la vision** (pas de sélecteurs DOM/accessibility) capable d'**apprendre par observation** des workflows utilisateur et de les rejouer de manière autonome.

**Philosophie** : "Observer → Comprendre → Apprendre → Agir"

**Cas d'usage cible** : milieu médical (facturation T2A, logiciels hospitaliers type HIS) — applications legacy sans API.

**Progression d'apprentissage** : OBSERVATION → COACHING → AUTO_CANDIDATE → AUTO_CONFIRMED

### Architecture 5 couches

```
Couche 0: RawSession       — Capturer clics/clavier/screenshots
Couche 1: ScreenState      — Analyser l'écran (image + texte + UI + contexte métier)
Couche 2: UIElement         — Détecter boutons/champs/tableaux sémantiquement
Couche 3: StateEmbedding    — Créer un "fingerprint" fusionné de l'état d'écran
Couche 4: WorkflowGraph     — Modéliser en graphe (nodes = écrans, edges = actions)
```

### Etat réel du code vs la vision documentée

| Composant | Statut | Notes |
|---|---|---|
| Modèles de données (5 couches) | **Complet** | Dataclasses/Pydantic bien structurées |
| Pipeline de détection UI (OWL-v2 + OpenCV + VLM) | **Fonctionnel** | |
| Embedding multi-modal (CLIP + FAISS) | **Fonctionnel** | BUG: composant texte toujours None |
| Learning States (4 niveaux + transitions) | **Implémenté** | |
| ActionExecutor + TargetResolver | **Très complet** | ~2800 lignes, multi-stratégie |
| ExecutionLoop multi-modes | **Implémenté** | |
| Self-healing (4 stratégies) | **Implémenté** | |
| GraphBuilder (RawSession → Workflow) | **Partiel** | Clustering OK, templates incomplets |
| Capture d'événements (clavier/souris) | **Absent du core** | Délégué à agent_v0 (séparé) |
| Construction auto des 4 niveaux ScreenState | **Absent** | OCR jamais peuplé |
| Visual Workflow Builder (éditeur web) | **Fonctionnel** | React + Flask, 20+ composants |

### Enrichissements documentés (8 concepts)

| # | Concept | Statut code |
|---|---|---|
| 1 | Grammaire du temps (épisodes) | Partiel — boost temporel, pas de patterns |
| 2 | Marquage du bruit | Manquant — implicite dans DBSCAN, non persisté |
| 3 | Layout signature | Implémenté — `screen_signature.py` |
| 4 | Identité stable | Partiel — target_memory, pas de StableIdentity formelle |
| 5 | Actionnabilité (scores) | Partiel — `is_interactable` bool, pas de score numérique |
| 6 | Versioning des espaces | Implémenté — PrototypeVersion |
| 7 | Variables métier | Partiel — champ présent, intégration non automatisée |
| 8 | Noeuds d'erreur | Manquant — pas de ErrorNode dans le graphe |

### Problèmes identifiés

#### Bug critique silencieux
`core/embedding/state_embedding_builder.py` accède à `detected_texts` (avec 's') alors que le champ réel s'appelle `detected_text`. Le composant texte de l'embedding (30% du poids) est **toujours None**. La qualité du matching est silencieusement dégradée.

#### Pipeline end-to-end non bouclé
La chaîne complète "observer un utilisateur → construire un workflow → le rejouer" n'est pas opérationnelle. La capture d'événements est dans agent_v0 (séparé), le GraphBuilder laisse des TODOs dans les templates, l'OCR ne peuple jamais le ScreenState.

#### Dette technique massive
- ~660K lignes Python, ~25 000 fichiers
- Centaines de scripts one-shot (classés dans `_a_trier/`)
- 3 frontends VWB abandonnés (classés dans `_a_trier/`)
- agent_v0 de 7.9 Go
- Ratio signal/bruit faible

#### Dispersion de l'effort
Beaucoup de modules sophistiqués (coaching, analytics, monitoring, sécurité, i18n, training, précision) développés en parallèle, mais la boucle fondamentale n'est pas fiable.

---

## Programme d'action

### Phase 0 — Stabiliser les fondations (1-2 semaines)

**Objectif : un pipeline minimal qui tourne de A à Z**

- [x] **P0-1** Corriger le bug `detected_texts` → `detected_text` dans `state_embedding_builder.py`
- [x] **P0-2** Intégrer la capture d'événements dans le core (`core/capture/event_listener.py` — pynput)
- [x] **P0-3** Implémenter le Screen Analyzer (`core/pipeline/screen_analyzer.py` — ScreenState complet 4 niveaux)
- [x] **P0-4** Compléter le GraphBuilder — `_create_screen_template()` + alignement modèles + fix import circulaire
- [x] **P0-5** Test E2E (`tests/test_pipeline_e2e.py` — 20 tests, pipeline validé avec embeddings mock)

**Critère de succès** : une démo qui enregistre un workflow simple et le rejoue correctement.

### Phase 1 — Valider sur un cas réel (2-3 semaines)

**Objectif : prouver que ça fonctionne sur un vrai logiciel**

**Prérequis (complétés) :**
- [x] SessionRecorder (`core/capture/session_recorder.py`) — orchestre EventListener + ScreenCapturer
- [x] Script CLI (`scripts/record_and_build.py`) — record / build / full / list
- [x] Fix `_extract_node_vector` dans WorkflowPipeline (support metadata prototypes)
- [x] Nettoyage code mort dans `execute_workflow_step`
- [x] Validation pipeline sur session réelle (66 screenshots → 1 node "Calculatrice")

**Tâches :**
- [ ] **P1-1** Choisir un workflow simple sur une application réelle (ex : 3 boutons + 1 saisie)
- [ ] **P1-2** Enregistrer 5 sessions de ce workflow (`python scripts/record_and_build.py record`)
- [ ] **P1-3** Vérifier que le GraphBuilder crée un workflow cohérent (`python scripts/record_and_build.py build`)
- [ ] **P1-4** Passer en COACHING → valider les suggestions
- [ ] **P1-5** Passer en AUTO_CANDIDATE → vérifier l'exécution supervisée
- [ ] **P1-6** Mesurer : précision matching, taux succès, temps exécution

**Critère de succès** : taux de succès > 80% en mode AUTO_CANDIDATE sur le workflow choisi.

### Phase 2 — Consolider le core (3-4 semaines)

**Objectif : fiabilité et robustesse**

- [ ] **P2-1** Implémenter les enrichissements manquants prioritaires : noeuds d'erreur, identité stable formelle, score d'actionnabilité
- [ ] **P2-2** Tests d'intégration sur le pipeline complet
- [ ] **P2-3** Nettoyage `_a_trier/` — décider quoi garder/supprimer/archiver
- [ ] **P2-4** Documentation code core (modules clés uniquement)

**Critère de succès** : couverture de tests > 60% sur le pipeline core, zéro bug silencieux connu.

### Phase 3 — Produit utilisable (4-6 semaines)

**Objectif : le VWB comme outil complet**

- [ ] **P3-1** Intégrer le pipeline core dans le VWB (aligner les services VWB sur core/)
- [ ] **P3-2** Supprimer l'ancien frontend VWB (garder uniquement frontend_v4)
- [ ] **P3-3** Workflow complet dans le VWB : enregistrer → éditer → tester → déployer
- [ ] **P3-4** Mode démo pour présentation (prospects/investisseurs)

**Critère de succès** : un utilisateur non technique peut enregistrer et rejouer un workflow via le VWB.

### Ce qu'on ne fait PAS maintenant

- Ajouter de nouvelles fonctionnalités (analytics avancé, coaching amélioré, multi-écran)
- Refactorer la structure des 28 sous-modules
- Migrer vers un autre framework web
- Développer agent_v1 tant que le pipeline core n'est pas bouclé

---

## Métriques de suivi

| Métrique | Cible Phase 0 | Cible Phase 1 | Cible Phase 3 |
|---|---|---|---|
| Pipeline end-to-end fonctionnel | Oui (cas simple) | Oui (cas réel) | Oui (multi-cas) |
| Taux de succès AUTO_CANDIDATE | N/A | > 80% | > 90% |
| Temps enregistrement → workflow | < 5 min | < 5 min | < 2 min |
| Bugs silencieux connus | 0 | 0 | 0 |
| Couverture tests pipeline | Smoke test | > 40% | > 60% |

---

## Fichiers clés à connaître

### Core — Modèles
- `core/models/raw_session.py` — RawSession, Event, Screenshot
- `core/models/screen_state.py` — ScreenState (4 niveaux)
- `core/models/ui_element.py` — UIElement, BBox, VisualFeatures
- `core/models/state_embedding.py` — StateEmbedding, EmbeddingComponent
- `core/models/workflow_graph.py` — Workflow, WorkflowNode, WorkflowEdge, LearningState

### Core — Pipeline
- `core/capture/screen_capturer.py` — Capture screenshots (mss)
- `core/detection/ui_detector.py` — Pipeline OWL-v2 + OpenCV + VLM
- `core/embedding/state_embedding_builder.py` — Construction StateEmbedding (**BUG ligne ~216**)
- `core/embedding/clip_embedder.py` — OpenCLIP ViT-B-32
- `core/embedding/faiss_manager.py` — Index FAISS
- `core/graph/graph_builder.py` — RawSession → Workflow (DBSCAN, **TODOs templates**)

### Core — Exécution
- `core/execution/action_executor.py` — Exécution des actions
- `core/execution/target_resolver.py` — Résolution multi-stratégie (~2800 lignes)
- `core/execution/execution_loop.py` — Orchestration des modes
- `core/healing/healing_engine.py` — Self-healing (4 stratégies)
- `core/learning/learning_manager.py` — Machine à états d'apprentissage

### Points d'entrée
- `run.sh` — Chef d'orchestre (--full, --gui, --server, etc.)
- `Makefile` — Tests (make test, make test-fast, make check)
- `visual_workflow_builder/run_v4.sh` — VWB frontend_v4

### Documentation de référence
- `docs/reference/ARCHITECTURE_VISION_COMPLETE.md` — Architecture 5 couches
- `docs/reference/ARCHITECTURE_ENRICHISSEMENTS.md` — 8 enrichissements
- `docs/PLAN_ACTION_MARS_2026.md` — Ce fichier

---

**Priorité absolue : Phase 0 — Boucler le pipeline end-to-end.**