rpa_vision_v3/docs/CARTOGRAPHY.md

Cartographie d'exécution — RPA Vision V3 (Léa)

Date : 26 avril 2026
Objectif : carte complète de ce qui est branché, ce qui ne l'est pas, et comment les données transitent.
Règle : LIRE CE DOCUMENT AVANT TOUTE MODIFICATION DE CODE.

---

1. Point d'entrée : deux chemins disjoints

POST /api/v3/execute/start  (execute.py:1528)
  ├── execution_mode = "verified"  → run_workflow_verified()  ← CHEMIN ORA
  └── execution_mode = "basic"|"intelligent"|"debug"  → execute_workflow_thread()  ← CHEMIN LEGACY

Il existe DEUX exécuteurs distincts qui dupliquent le chargement des ancres, la boucle d'étapes, le grounding, la gestion d'erreurs. Ils ne partagent que input_handler.py.

---

2. Chemin LEGACY (modes basic/intelligent/debug)

[API] POST /execute/start (mode=intelligent)
  → [execute.py:145] execute_workflow_thread()
    → [execute.py:160] Charge steps depuis DB
    → BOUCLE sur chaque step:
      │
      ├─ RÉFLEXE PRÉ-ÉTAPE (modes intelligent/debug)
      │   → [input_handler.py:79] check_screen_for_patterns()
      │       → UIPatternLibrary.find_pattern(ocr_text)               ← BRANCHÉ
      │   → [input_handler.py:129] handle_detected_pattern()
      │       → EasyOCR full screen + clic bouton                     ← BRANCHÉ
      │
      ├─ CHARGEMENT ANCRE [execute.py:222-256]
      │   params['visual_anchor'] = {
      │     screenshot: base64 du crop,
      │     bounding_box: {x, y, width, height},
      │     target_text: anchor.target_text,      ← PEUT ÊTRE VIDE ("")
      │     description: anchor.ocr_description   ← PEUT ÊTRE VIDE ("")
      │   }
      │
      ├─ execute_action(action_type, params) [execute.py:278]
      │   │
      │   ├─ ACTION = click_anchor [execute.py:862-1096]
      │   │  │
      │   │  ├─ MODE basic: coordonnées statiques (bbox centre)
      │   │  │
      │   │  └─ MODE intelligent/debug:
      │   │     ├─ target_text = anchor.target_text || step.label
      │   │     │   Si target_text == "click_anchor" et screenshot_base64:
      │   │     │     → _describe_anchor_image() (VLM qwen2.5vl:3b)  ← BRANCHÉ
      │   │     │
      │   │     ├─ MÉTHODE 1: Template matching (cv2)                ← BRANCHÉ
      │   │     ├─ MÉTHODE 2: CLIP matching (RF-DETR + CLIP)         ← BRANCHÉ
      │   │     ├─ MÉTHODE 3: OCR → UI-TARS → VLM                   ← BRANCHÉ
      │   │     └─ ÉCHEC: self-healing interactif                    ← BRANCHÉ
      │   │
      │   ├─ ACTION = type_text → safe_type_text()                   ← BRANCHÉ
      │   ├─ ACTION = wait → sleep + pattern check                   ← BRANCHÉ
      │   ├─ ACTION = keyboard_shortcut → pyautogui.hotkey()         ← BRANCHÉ
      │   ├─ ACTION = ai_analyze_text → Ollama                       ← BRANCHÉ
      │   ├─ ACTION = extract_text → docTR OCR                       ← BRANCHÉ
      │   └─ ACTION = hover/scroll/focus → coords statiques          ← PAS DE GROUNDING

---

3. Chemin ORA (mode "verified")

[API] POST /execute/start (mode=verified)
  → [execute.py:1349] run_workflow_verified()
    → [execute.py:1380-1428] Charge steps + ancres (MÊME logique que legacy)
    → [execute.py:1433] ORALoop(verify_level='none', max_retries=2)
    │                            ^^^^^^^^^^^^^^^^^^^
    │                   VÉRIFICATION DÉSACTIVÉE EN DUR
    │
    → [ORA:1478] ora.run_workflow(steps=ora_steps)
      │
      BOUCLE sur chaque step:
        │
        ├─ [ORA:1258] OBSERVE: capture écran + pHash + titre fenêtre
        │
        ├─ [ORA:1263] RÉFLEXE DIALOGUE (si pHash changé > 10)
        │   → DialogHandler.handle_if_dialog(screenshot)               ← BRANCHÉ
        │     → EasyOCR full screen → mots-clés dialogues connus
        │     → InfiGUI worker (/tmp/infigui_*)
        │     → Fallback OCR clic
        │
        ├─ [ORA:196] REASON: reason_workflow_step()
        │   target_text = anchor.target_text || anchor.description
        │   Si vide ou nom d'action → _describe_anchor_image()         ← CORRIGÉ 26/04
        │   Si encore vide → label (si pas un nom d'action)
        │
        ├─ [ORA:1306] ACT → _act_click()
        │   │
        │   ├─ RPA_USE_FAST_PIPELINE=1 (défaut)
        │   │   → FastSmartThinkPipeline
        │   │     → FastDetector (RF-DETR 120ms + EasyOCR 192ms)       ← BRANCHÉ
        │   │     → SmartMatcher (texte+type+position+voisins <1ms)    ← BRANCHÉ
        │   │     → SignatureStore.lookup() (apprentissage)             ← BRANCHÉ
        │   │     → Score ≥ 0.90 → action directe                     ← BRANCHÉ
        │   │     → Score 0.60-0.90 → ThinkArbiter
        │   │       → UITarsGrounder → InfiGUI worker (/tmp)           ← BRANCHÉ
        │   │     → Score < 0.60 → ThinkArbiter seul                  ← BRANCHÉ
        │   │     → ÉCHEC → _try_fallback()
        │   │       → GroundingPipeline                    ← NON BRANCHÉ (jamais connecté)
        │   │
        │   ├─ FALLBACK template matching (cv2, >0.75)                 ← BRANCHÉ
        │   ├─ FALLBACK OCR (_grounding_ocr)                           ← BRANCHÉ
        │   └─ DERNIER RECOURS: coords statiques                       ← BRANCHÉ
        │
        ├─ [ORA:1337] VÉRIFICATION TITRE (post-action)
        │   → TitleVerifier → EasyOCR crop 45px                       ← BRANCHÉ
        │   *** NE LIT RIEN EN VM (titre Windows dans le framebuffer) ← PROBLÈME
        │
        ├─ [ORA:1358] VERIFY: verify(pre, post, decision)
        │   *** DÉSACTIVÉ (verify_level='none') ***                    ← NON BRANCHÉ
        │
        └─ [ORA:1362] RECOVERY (5 stratégies)
            *** JAMAIS ATTEINT ***                                     ← NON BRANCHÉ
            - _recover_element_not_found (wait+scroll+UI-TARS)
            - _recover_overlay_blocking (pattern+Win+D)
            - _recover_wrong_screen (Alt+Tab)
            - _recover_no_effect (double-clic+décalage)
            - _classify_error (4 types)

---

4. Trace du champ target_text

CAPTURE (VWB CapturePanel → capture.py:201-263)
  → OCR sur crop élargi (docTR)
  → VLM qwen2.5vl:3b décrit le crop
  → Si les deux échouent → target_text = ""
  → Aucune erreur remontée au frontend

STOCKAGE (DB)
  → VisualAnchor.target_text (nullable) = "" si non renseigné

CHARGEMENT (execute.py:1400-1428)
  → SI anchor.target_text existe et non vide → injecté dans visual_anchor
  → SINON → la clé 'target_text' N'EXISTE PAS dans le dict

LEGACY (execute.py:893-907)
  → target_text = anchor.get('target_text', '')
  → SI vide ET c'est un nom d'action → _describe_anchor_image()       ← COMPENSE
  → SINON → fallback sur step_label

ORA (observe_reason_act.py:217) — CORRIGÉ LE 26 AVRIL
  → target_text = anchor.target_text || anchor.description
  → SI vide ou nom d'action → _describe_anchor_image()                ← AJOUTÉ
  → SINON → label (si pas un nom d'action)

---

5. Fonctions existantes NON BRANCHÉES

Fonction	Fichier	Raison
verify() + _classify_error() + 5 _recover_*()	observe_reason_act.py	verify_level='none' en dur
GroundingPipeline (ancien)	pipeline.py	set_fallback_pipeline() jamais appelé
TemplateMatcher (classe centralisée)	template_matcher.py	Utilisé seulement par GroundingPipeline mort
ShadowLearningHook	shadow_learning_hook.py	Jamais importé dans aucun flux
CognitiveContext	working_memory.py	Mode instruction seulement
VLM pre-check	observe_reason_act.py	if False: en dur
hover/focus grounding	execute.py	Coords statiques uniquement
grounding/server.py (FastAPI :8200)	server.py	Crash CUDA, remplacé par worker fichiers

---

6. Les 12 systèmes de grounding

#	Système	Fichier	Branché ?
1	Template matching inline (legacy)	execute.py:914	✅ Legacy
2	Template matching inline (ORA)	ORA:1475	✅ ORA fallback
3	CLIP matching (IntelligentExecutor)	intelligent_executor.py	✅ Legacy
4	OCR docTR (_grounding_ocr)	input_handler.py:430	✅ Legacy + ORA
5	UI-TARS Ollama (_grounding_ui_tars)	input_handler.py:513	✅ Legacy
6	VLM reasoning (_grounding_vlm)	input_handler.py:627	✅ Legacy seulement
7	FastDetector (RF-DETR + EasyOCR)	fast_detector.py	✅ ORA
8	SmartMatcher	smart_matcher.py	✅ ORA
9	ThinkArbiter → InfiGUI worker	think_arbiter.py + ui_tars_grounder.py	✅ ORA
10	DialogHandler → InfiGUI	dialog_handler.py	✅ ORA réflexe
11	GroundingPipeline (ancien)	pipeline.py	❌ Jamais connecté
12	TemplateMatcher classe	template_matcher.py	❌ Via GroundingPipeline mort

---

7. Gestion des dialogues (2 systèmes parallèles)

#	Système	Base de patterns	OCR	Clic	Utilisé par
1	UIPatternLibrary + handle_detected_pattern	28 patterns builtin	docTR/EasyOCR	OCR find bouton	Legacy
2	DialogHandler + KNOWN_DIALOGS	15 titres connus	EasyOCR full screen	InfiGUI	ORA

---

8. Budget VRAM (configuration actuelle)

Composant	VRAM	Process
InfiGUI-G1-3B (NF4)	2.41 GB	Worker indépendant (/tmp)
RF-DETR Medium	0.8 GB	Process Flask
EasyOCR	~1 GB (GPU)	Process Flask
Ollama qwen2.5vl:3b (si appelé)	~3.2 GB	Process Ollama
Chrome + système	~1.3 GB	—
Total max	~8.7 GB / 12 GB

---

9. Fichiers critiques par ordre d'importance

1. core/execution/observe_reason_act.py — boucle ORA, _act_click, reason, verify
2. visual_workflow_builder/backend/api_v3/execute.py — API, chargement ancres, legacy executor
3. core/grounding/fast_pipeline.py — pipeline FAST→SMART→THINK
4. core/grounding/ui_tars_grounder.py — client InfiGUI worker
5. core/grounding/infigui_worker.py — worker InfiGUI (process indépendant)
6. core/execution/input_handler.py — OCR, UI-TARS Ollama, safe_type_text, patterns
7. core/grounding/dialog_handler.py — gestion dialogues ORA
8. core/grounding/fast_detector.py — RF-DETR + EasyOCR
9. core/grounding/smart_matcher.py — matching contextuel
10. core/knowledge/ui_patterns.py — patterns réflexes

---

Dernière mise à jour : 26 avril 2026
Prochaine action : rebrancher verify + recovery, converger les 2 exécuteurs, nettoyer le code mort.