rpa_vision_v3/docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md

Investigation — Mémoire visuelle orpheline

Date : 2026-05-09 Branche : feature/qw-suite-mai Périmètre : modules de cache d'embeddings, validation visuelle continue, et apprentissage par observation, identifiés en code mais non instanciés en runtime.

Hors scope de docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (audit borné à agent_v0/server_v1/ + core/* importés par le serveur). Ces modules ne sont pas importés par le serveur.

1. Modules concernés

Module	Lignes	Commit d'origine	Dernier commit touchant le code	Sites d'instanciation runtime
core/visual/visual_embedding_manager.py	651	a27b74cf2 (2026-01-29, v1.0 stable)	36737cfe9 (2026-04-14, refactor sécurité serializer)	0
core/visual/screenshot_validation_manager.py	571	a27b74cf2 (2026-01-29, v1.0 stable)	a27b74cf2 (idem)	0
core/grounding/shadow_learning_hook.py	156	73cea2385 (2026-04-25, "Phase 6 — Shadow Learning Hook")	idem	0 (seul match = exemple docstring du fichier)

Vérifications effectuées :

• grep -rn "VisualEmbeddingManager(" --include="*.py" hors module et hors tests/ : 0 hit.
• grep -rn "ScreenshotValidationManager(" idem : 0 hit.
• grep -rn "ShadowLearningHook(" idem : 0 hit.
• core/visual/__init__.py re-exporte les deux managers, mais aucun consommateur n'importe from core.visual import ….

2. Rôle déduit du code

VisualEmbeddingManager (core/visual/visual_embedding_manager.py)

Cache d'embeddings CLIP indexés par signature, métriques de similarité multiples (cosine, euclidean, normalized correlation, score combiné), API MatchResult. S'interface avec core.embedding.fusion_engine.FusionEngine et utilise core.security.signed_serializer pour persister le cache (HMAC signé).

Vise à fournir une recherche de correspondances rapide pour le grounding visuel (intro module : « système RPA 100% visuel », exigences 3.3, 3.4 — référencement non retrouvé dans le repo).

ScreenshotValidationManager (core/visual/screenshot_validation_manager.py)

Validation périodique automatique d'éléments visuels enregistrés. Statuts VALID/WARNING/ERROR/UNKNOWN/VALIDATING, ValidationReport avec ValidationIssue et RecoveryAction proposées (auto-fixable ou non). Dépend de VisualEmbeddingManager + ScreenCapturer + UIDetector.

Vise à alimenter une UI de monitoring de santé des targets visuels (intro : « indicateurs vert/orange/rouge »).

ShadowLearningHook (core/grounding/shadow_learning_hook.py)

Pont entre observation Shadow (l'humain clique) et SignatureStore (base de signatures d'éléments UI). À chaque clic observé : détection de l'élément sous le clic via FastDetector, enrichissement de la base. Présenté comme « hook optionnel (callback) » à brancher dans ShadowObserver ou l'API de capture.

3. Pourquoi non-câblés (analyse historique)

Sous-système core/visual/ (VEM + SVM)

Introduits le 2026-01-29 dans le commit a27b74cf2 (« v1.0 - Version stable »), antérieur de plusieurs mois aux refontes grounding d'avril 2026 (commits 9da589c8c pipeline centralisé, 77faa03ec UI-TARS→InfiGUI, phases 1-6 FAST→SMART→THINK). Le pipeline grounding actuel passe par core/grounding/* (fast_pipeline.py, infigui_server.py, think_arbiter.py) qui implémente sa propre logique de signature (SignatureStore dans element_signature.py) — fonctionnellement redondant avec VEM côté cache d'embeddings, et orthogonal à SVM côté validation continue.

Le screenshot_validation_manager.py n'a connu aucun commit depuis sa création (mtime 2026-01-07). Pas de trace de point d'appel envisagé dans les commits ultérieurs.

ShadowLearningHook

Introduit le 2026-04-25 (73cea2385) au sein du pipeline FAST→SMART→THINK (phase 6 sur 6 documentée du commit b30d4b665). Le hook attend d'être appelé sur événement clic — mais le ShadowObserver (core/workflow/shadow_observer.py) ne configure aucun callback de ce type, et api_stream.py instancie ShadowValidator (validation post-action côté workflow) sans déclencher d'enrichissement de SignatureStore.

Le commit suivant (e2046837c 2026-04-25, « Phase 5 intégration FAST→SMART→THINK dans ORA ») câble les phases 1-5 dans observe_reason_act.py mais ne mentionne pas la phase 6. Probable fin de batch d'implémentation sans pas de câblage côté capture clic.

4. Recommandation préliminaire (à statuer en revue +14j, soit 2026-05-23)

Module	Recommandation	Justification
VisualEmbeddingManager	ACCEPTED + archivage _archive/ sauf cas d'usage prod identifié	Redondant avec SignatureStore + cache d'embeddings côté fusion_engine.py. Maintien sans utilisateur = bruit.
ScreenshotValidationManager	ACCEPTED + archivage	Pas d'UI de monitoring associée dans web_dashboard/ ni visual_workflow_builder/. Composant prévu pour une fonctionnalité non aboutie.
ShadowLearningHook	CÂBLER post-démo Kerella	Fonctionnalité cohérente avec la vision aiva-vision (apprentissage progressif). Coût faible : un callback on_click dans ShadowObserver ou côté API capture. Bénéfice élevé si apprentissage devient prio post-démo.

L'archivage VEM/SVM ne tranche pas la question plus large d'une unification du cache d'embeddings (VEM + fusion_engine.py + embedding_cache.py). Cette unification, si pertinente, fait l'objet d'une dette dédiée à instruire séparément, hors scope de cette investigation.

5. Tests dépendants à traiter en même temps que l'archivage

Si la revue +14j retient l'archivage de VEM/SVM, les tests suivants doivent être archivés ou réécrits dans le même commit (sinon CI casse ou faux positif vert) :

• tests/property/test_visual_embedding_manager_properties.py — dédié VEM (à archiver avec).
• tests/integration/test_visual_rpa_checkpoint.py — couvre VEM + SVM en intégration.
• tests/property/test_visual_capture_properties.py — couvre VEM + SVM.
• tests/property/test_interactive_preview_area_properties.py — référence VEM ; à examiner avant archivage car peut couvrir d'autres composants encore vivants.
• tests/property/test_realtime_validation_properties.py — importe core.visual (à examiner : peut viser VisualTargetManager qui, lui, est instancié côté VWB et ne doit pas être archivé).

ShadowLearningHook n'a aucun test associé.

6. Dette identifiée hors scope de cette investigation

L'investigation actuelle s'est limitée au sous-système mémoire visuelle. Le constat que des modules orphelins existent au-delà du périmètre de l'AUDIT serveur du 2026-05-08 (cf. modules identifiés en sections 1-2) suggère fortement que d'autres orphelins existent ailleurs dans le repo (VWB, agent_chat, demo/, deploy/, autres).

Un audit exhaustif des modules orphelins du repo constitue une dette identifiée à instruire post-démo Kerella. Numéro de dette non réservé à ce stade (instruction préalable nécessaire pour cadrer le périmètre).