From 5dc20cc85bb58367e3c9eb66e12e6b0c2d6b8cc0 Mon Sep 17 00:00:00 2001 From: Dom Date: Sat, 9 May 2026 11:23:45 +0200 Subject: [PATCH] =?UTF-8?q?docs(dette):=20rectif=20mapping=20DETTE-005=20+?= =?UTF-8?q?=20DETTE-008/009=20+=20investigation=20m=C3=A9moire=20visuelle?= =?UTF-8?q?=20orpheline?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/DETTE_TECHNIQUE.md | 4 +- ...N_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md | 76 +++++++++++++++++++ 2 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md diff --git a/docs/DETTE_TECHNIQUE.md b/docs/DETTE_TECHNIQUE.md index c26e9cd56..c2e809643 100644 --- a/docs/DETTE_TECHNIQUE.md +++ b/docs/DETTE_TECHNIQUE.md @@ -20,9 +20,11 @@ P0 / P1 / P2 / P3 (alignées sur convention handoffs) | DETTE-002 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Exemption drift > 0.20 si template_matching ≥ 0.95 ou hybrid_text_direct ≥ 0.80 (resolve_engine.py:2367-2390) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F2.2.1) | | DETTE-003 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Self-healing Win+D au retry 1 retiré (revert 22c0a2ba6, replay_engine.py) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F2.2.3) | | DETTE-004 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Cascade OmniParser/YOLO neutralisée — `_resolve_by_yolo` défini, importé, jamais appelé (resolve_engine.py:293) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F2.4.1) | -| DETTE-005 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Pre-check VLM par-clic désactivé via `if False:` (observe_reason_act.py:1704-1713) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F6.1.1) | +| DETTE-005 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Sous-système mémoire visuelle orphelin — `VisualEmbeddingManager` + `ScreenshotValidationManager` (core/visual/*) définis mais jamais instanciés en runtime | docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md | | DETTE-006 | 2026-05-08 | 2026-05-23 | P0 | IN_PROGRESS | Bug échelle pixel grounding Ollama smart_resize non-déterministe | docs/MIGRATION_VLM_PLAN_2026-05-09.md | | DETTE-007 | 2026-05-09 | 2026-05-23 | P3 | OPEN | Trois implémentations smart_resize coexistent (server.py, infigui_worker.py, nouveau module officiel). Unification post-démo Kerella. | commit feat(grounding): module smart_resize officiel | +| DETTE-008 | 2026-05-09 | 2026-05-23 | P2 | OPEN | Pre-check VLM par-clic désactivé via `if False:` (observe_reason_act.py:1704-1713) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F6.1.1) | +| DETTE-009 | 2026-05-09 | 2026-05-23 | P3 | OPEN | `ShadowLearningHook` (core/grounding/shadow_learning_hook.py) défini mais jamais instancié — Phase 6 du pipeline FAST→SMART→THINK non câblée à l'observation Shadow | docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md | ## Convention de référencement diff --git a/docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md b/docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md new file mode 100644 index 000000000..fea53e3c2 --- /dev/null +++ b/docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md @@ -0,0 +1,76 @@ +# 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).