Dom/rpa_vision_v3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e679804cfda586aeb031b749ac5f4da98a376778
rpa_vision_v3/docs/POC/SPECS_PHASE_25_SEMANTIQUE_2026-06-01.md

8.7 KiB
Raw Blame History

SPECS Phase 2.5 Sémantique — POC RPA Vision v3

DRAFT specs pour implémentation — pas encore appliqué — alignement avec arbitrage Plato 2026-06-01 18:18

Date : 2026-06-01 Auteur : Claude (agent Plan), arbitrage Plato/Codex Statut : DRAFT — à valider par Dom avant implémentation Référence arbitrage : docs/coordination/inbox_claude/2026-06-01_1818_codex-to-claude_ADDENDUM-agent-plato-archi-semantique.md Référence addendum initial Claude : 17:45 (OmniParser systématique dans hot path replay) — révoqué par Plato

Principes d'arbitrage retenus

  1. Garder replay/click/OCR existant comme chemin principal (hot path inchangé)
  2. Phase 2.5 = post-apprentissage uniquement, jamais en hot path replay
  3. Demander à l'humain seulement les ambiguïtés utiles
  4. Sémantique = contexte, pas prérequis de chaque clic
  5. ExternalDecisionClient autour de t2a_decision, puis adaptation AIVA
  6. OCR critique renforcé par régions annotées + escalade humaine

Sommaire

  1. Périmètre Phase 2.5 MVP
  2. Endpoint à créer
  3. Identification des écrans distincts
  4. Stockage des annotations sémantiques
  5. Réutilisation au replay (autopilote / autonome)
  6. Compatibilité compétences existantes
  7. Garde-fous anti-fragilité OmniParser
  8. Coûts perf attendus
  9. Tests à prévoir
  10. Estimation effort implémentation
  11. Hors scope MVP Phase 2.5

1. Périmètre Phase 2.5 MVP

  • Quand : déclenchement à la fin de la phase d'observation, après POST /api/v1/shadow/stop, avant restitution Option C à l'humain.
  • Sur quoi : screenshots clés capturés (1 par écran distinct détecté), pas tous les frames.
  • Avec quoi : OmniParser réutilisé (déjà présent, adaptateur fragile mais isolé), encapsulé derrière garde-fou anti-fragilité §7.
  • Pour quoi : produire un payload structuré {tables[], forms[], buttons[], text_blocks[]} par écran clé, stocké dans un YAML sémantique séparé du YAML compétence principal.
  • Non-objectif : Phase 2.5 ne touche pas le chemin replay. Elle enrichit uniquement la compétence apprise.

2. Endpoint à créer

POST /api/v1/lea/screen/analyze côté streaming server (port 5005).

  • Entrée : {session_id: str, screenshot_indexes: int[]} — index des frames capturées en mode léger pendant l'observation.
  • Sortie : {screens: [{index, hash, structure: {tables, forms, buttons, text_blocks}}]}.
  • Idempotence : cache disque sous data/cache/omniparser/<session>/<index>.json.
  • Timeout : 30s par screenshot. Dépassement → fallback OCR-seul (docTR text_blocks seuls), flag degraded: true.
  • Erreur OmniParser (exception, modèle KO) : fallback OCR-seul + log logs/omniparser_errors.log. L'endpoint ne renvoie jamais 500 — toujours 200 avec flag dégradé.

3. Identification des écrans distincts

Heuristique de regroupement, exécutée avant l'appel /api/v1/lea/screen/analyze :

  • Calcul imagehash.phash pour chaque frame capturée.
  • Grouping par similarité : Hamming distance ≤ 8 ⇒ même écran logique.
  • Sélection d'un frame représentatif par groupe (premier dans l'ordre temporel, ou celui avec le plus de détections OCR).
  • Limite POC : maximum 10 écrans distincts par session. Au-delà, session marquée too_complex et l'humain est invité à scinder la compétence en sous-compétences (message explicite dans restitution Option C).

4. Stockage des annotations sémantiques

Fichier séparé du YAML compétence principal, suffixe .semantic.yaml.

Chemin : data/competences/candidate/<slug>.semantic.yaml

Structure :

competence_id: facturation_urgence_simple
semantic_version: 1
generated_at: 2026-06-01T18:30:00Z
omniparser_version: <hash adaptateur>
degraded: false
screens:
  - screen_id: screen_001
    phash: "abc123..."
    representative_frame_index: 42
    annotations:
      - region_id: region_3
        bbox: [120, 80, 400, 150]
        semantic_label: motif_arrivee
        confidence: human_verified
    structure:
      tables: [...]
      forms: [...]
      buttons: [...]
      text_blocks: [...]
  • Séparation stricte : YAML compétence principal reste lisible et minimal. .semantic.yaml est optionnel.
  • YAML compétence référence le fichier sémantique par clé semantic_ref: <slug>.semantic.yaml si présent.

5. Réutilisation au replay (autopilote / autonome)

OmniParser au replay uniquement si la compétence référence un .semantic.yaml (présence de semantic_ref).

Algorithme :

  1. Au démarrage du replay d'un écran, calcul phash du screen courant.
  2. Si Hamming distance ≤ 8 avec un screen_id connu OU même nombre de tables/buttons/forms structurellement → match, application des annotations.
  3. Sinon → divergence :
    • Autopilote : escalade humaine via Option C runtime (« écran inattendu, valider ou annoter »).
    • Autonome : log incident logs/replay_incidents.log, stop avec code semantic_mismatch.

Compétences sans semantic_ref → on saute totalement cette étape (rétrocompat §6).

6. Compatibilité compétences existantes

  • Compétences sans .semantic.yaml ⇒ pas de Phase 2.5 au replay, pas d'OmniParser, chemin OCR + template + click inchangé.
  • Phase 2.5 = opt-in par compétence : seule une compétence apprise après l'activation de Phase 2.5 possédera le fichier sémantique.
  • Aucune migration auto des compétences anciennes. Rétrocompat garantie par l'absence de semantic_ref.
  • Pas de breaking change sur le format YAML compétence principal — seulement une clé optionnelle.

7. Garde-fous anti-fragilité OmniParser

Adaptateur OmniParser fragile (chemin absolu, dépendances lourdes). Mesures :

  • Wrapper try/except global autour de chaque appel OmniParser, fallback OCR-seul (docTR) systématique en cas d'exception.
  • Log dédié : toute erreur → logs/omniparser_errors.log avec stack trace, session_id, frame_index.
  • Healthcheck au démarrage Phase 2.5 : appel test sur image bidon. Si échec → bascule auto en mode dégradé OCR-seul, log warning, restitution degraded: true.
  • Test unitaire obligatoire : mock OmniParser qui lève exception, vérifier que la chaîne aboutit à un .semantic.yaml dégradé valide.
  • Isolation chemin absolu : config OmniParser (chemin modèle, version) centralisée dans config/omniparser.yaml, jamais en dur.

8. Coûts perf attendus

  • Dev (RTX 5070, OmniParser CPU) : 2 à 5s par screen. Acceptable (principe 5 Dom, hors hot path).
  • DGX Spark (cible prod) : < 500ms par screen.
  • Coût session typique : 10 screens × 2-5s = 20-50s ajoutés à la fin d'une session d'apprentissage sur dev. Tolérable, asynchrone vis-à-vis humain (restitution Option C peut afficher spinner).
  • Pas d'impact sur replay (hot path) tant que pas de semantic_ref. Avec semantic_ref, surcoût = phash (négligeable) + OmniParser uniquement en cas de mismatch structure.

9. Tests à prévoir

Unitaires :

  • Hash perceptuel + grouping : frames similaires/différentes, vérif Hamming threshold.
  • Fallback OCR-seul si OmniParser KO (mock exception, timeout, healthcheck KO).
  • Génération .semantic.yaml : structure valide, degraded correctement positionné.
  • Cap 10 écrans : session avec 15 → marquage too_complex propre.

Intégration :

  • Flux complet : session shadow → stop → identification écrans → analyse → .semantic.yaml écrit → Option C.
  • Replay compétence avec .semantic.yaml : match nominal, mismatch déclenche escalade autopilote / stop autonome.
  • Replay compétence sans .semantic.yaml : chemin legacy intact, aucun appel OmniParser.

Sécurité :

  • Injection chemins relatifs/absolus dans session_id ou slug refusée (regex strict ^[a-z0-9_]+$).
  • Pas d'écriture hors data/competences/candidate/ et data/cache/omniparser/.

10. Estimation effort implémentation

  • ~200-300 lignes Python (endpoint, grouping phash, wrapper OmniParser, écriture YAML, lecture replay).
  • ~150 lignes tests.
  • Effort moyen, étalable sur 1-2 jours.
  • Risque régression faible : ne touche pas hot path replay, opt-in par compétence, rétrocompat totale.

11. Hors scope MVP Phase 2.5

  • Détection visuelle de changements d'écran en temps réel pendant le replay (= hot path, révoqué par Plato).
  • Annotations sémantiques automatiques par VLM (prérequis trop ambitieux POC).
  • Versioning sémantique multi-versions Easily (post-POC).
  • Recalcul auto annotations si interface change (post-POC, lié mode rééducation).
  • Annotations multi-langues (POC français uniquement).
  • Synchronisation .semantic.yaml entre agents distribués (post-POC).

Fin DRAFT — à valider par Dom avant implémentation. Aucune modification de fichier de prod. Aucun commit.

Reference in New Issue View Git Blame Copy Permalink