rpa_vision_v3/docs/EXECUTION_LOOP_FLAGS.md

Flags d'exécution vision-aware (C1) — ExecutionLoop

Introduit dans la série de correctifs C1 (avril 2026). Référence code : core/execution/execution_loop.py (classe ExecutionLoop, constructeur lignes ~177-237).

Cette page décrit les quatre flags ajoutés à ExecutionLoop pour piloter finement la construction de ScreenState pendant le replay. Ils permettent de dégrader volontairement le pipeline de perception quand un composant est en panne ou quand on veut gagner de la latence.

Contexte

Depuis C1, chaque itération de la boucle d'exécution construit un ScreenState enrichi via ScreenAnalyzer (OCR + détection UI + embedding), avec un cache perceptuel pour éviter de recalculer deux fois sur le même screenshot.

Cela coûte cher (~200 ms – 2 s selon la machine). Les flags ci-dessous permettent de désactiver ou contraindre ces étapes.

Le StepResult expose désormais :

Champ	Type	Sens
ocr_ms	float	Temps OCR pour ce step
ui_ms	float	Temps détection UI pour ce step
analyze_ms	float	Temps total analyse ScreenState
total_ms	float	Temps total du step (alias duration_ms)
cache_hit	bool	True si le ScreenState vient du cache perceptuel
degraded	bool	True si on est retombé en mode dégradé

Ces champs remontent automatiquement dans le module analytics (table SQLite step_metrics, voir core/analytics/storage/timeseries_store.py).

Flags

enable_ui_detection: bool = True

Active/désactive la détection UI (YOLO + SomEngine + VLM de grounding).

Pourquoi le désactiver :

• Le serveur VLM (Ollama) est down ou surchargé
• On cible un workflow très simple où seul l'OCR suffit
• On debugge un problème de détection et on veut isoler la cause

Impact performance : gain ~100-1500 ms par step selon modèle VLM.

Exemple :

from core.execution.execution_loop import ExecutionLoop, ExecutionMode

loop = ExecutionLoop(
    pipeline=pipeline,
    enable_ui_detection=False,   # VLM down → on coupe la détection UI
)
loop.start(workflow_id="wf_notepad", mode=ExecutionMode.AUTOMATIC)

enable_ocr: bool = True

Active/désactive l'OCR (Tesseract/docTR).

Pourquoi le désactiver :

• Gains de performance sur un workflow piloté uniquement par templates/embeddings
• Environnement CPU-only où l'OCR est trop lent
• Les textes ne sont pas utilisés par la stratégie de matching

Impact performance : gain ~80-500 ms par step.

Exemple :

loop = ExecutionLoop(
    pipeline=pipeline,
    enable_ocr=False,
)

Note : si enable_ui_detection=False et enable_ocr=False, la boucle renvoie un ScreenState stub (sans texte ni éléments) et force degraded=True. Le matching retombera sur les embeddings CLIP seuls.

analyze_timeout_ms: int = 8000

Seuil soft en millisecondes au-delà duquel on considère que l'analyse a été trop lente et on bascule tous les steps suivants en mode dégradé (pas de recalcul OCR/UI, réutilisation du cache ou stub direct).

Pourquoi le modifier :

• Machines lentes (CPU, VM, Citrix) → augmenter à 15000 ou 20000
• Serveurs dédiés GPU → réduire à 3000 pour détecter plus tôt
• Tests / profiling → utiliser 999999 pour désactiver le basculement

Exemple :

loop = ExecutionLoop(
    pipeline=pipeline,
    analyze_timeout_ms=15000,    # environnement lent (RDP/Citrix)
)

Le mode dégradé est porté par ExecutionLoop._degraded_mode et affiché dans StepResult.degraded. Voir _build_screen_state (~ligne 920).

window_info_provider: Optional[Callable[[], Optional[Dict]]] = None

Callable renvoyant un dict décrivant la fenêtre active. Par défaut, la boucle appelle screen_capturer.get_active_window().

Pourquoi fournir un provider custom :

• Citrix / RDP : le client Windows local voit un seul process (le client Citrix). L'info de fenêtre utile vient de l'agent distant, on doit donc la passer explicitement.
• Environnements headless : pas de gestionnaire de fenêtres natif.
• Tests : injecter une fenêtre mockée sans toucher au capturer.

Format attendu du dict (au minimum) :

{
    "title": str,       # Titre de la fenêtre
    "app_name": str,    # Nom de l'application
    # champs optionnels utilisés par ScreenAnalyzer
    "x": int, "y": int, "width": int, "height": int,
}

Exemple Citrix :

def citrix_window_info():
    # L'agent dans la session Citrix distante publie ces infos
    # (par ex. via un fichier partagé ou une websocket)
    return remote_agent.get_current_window_info()

loop = ExecutionLoop(
    pipeline=pipeline,
    window_info_provider=citrix_window_info,
)

Combinaisons recommandées

Cas d'usage	Flags
Production standard (GPU local)	enable_ui_detection=True, enable_ocr=True, analyze_timeout_ms=8000 (défaut)
VLM down — mode fallback	enable_ui_detection=False, enable_ocr=True
Machine lente / VM	analyze_timeout_ms=15000
Citrix / RDP	window_info_provider=<custom> + valeurs par défaut
Benchmark CLIP-only	enable_ui_detection=False, enable_ocr=False

Remontée analytics

Les timings et flags dégradés persistent dans la table SQLite step_metrics (colonnes ocr_ms, ui_ms, analyze_ms, total_ms, cache_hit, degraded) via AnalyticsExecutionIntegration.on_step_result.

Exemple de requête d'analyse :

-- Steps avec OCR lent (>300 ms)
SELECT node_id, action_type, ocr_ms, analyze_ms
FROM step_metrics
WHERE ocr_ms > 300
ORDER BY ocr_ms DESC;

-- Taux de cache hit par workflow
SELECT workflow_id,
       SUM(cache_hit) * 1.0 / COUNT(*) AS cache_hit_ratio
FROM step_metrics
GROUP BY workflow_id;

-- Steps ayant basculé en mode dégradé
SELECT execution_id, node_id, analyze_ms
FROM step_metrics
WHERE degraded = 1
ORDER BY started_at DESC;

Voir aussi

• core/execution/execution_loop.py — implémentation
• core/pipeline/screen_analyzer.py — pipeline d'analyse
• core/pipeline/screen_state_cache.py — cache perceptuel
• tests/unit/test_execution_loop_vision_aware.py — tests C1
• tests/unit/test_analytics_vision_metrics.py — tests analytics C1
• docs/STATUS.md — état général du projet