# 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).