rpa_vision_v3/CLAUDE.md

# CLAUDE.md — rpa_vision_v3

Ce fichier prime sur le CLAUDE.md racine (`~/ai/CLAUDE.md`) pour tout travail dans ce projet.

## Rôle de Claude Code sur ce projet

Exécutant supervisé, pas architecte. Mission : garantir la **cohérence** de chaque modification avec la vision globale du projet et le **contrat "100% vision"** (résolution UI par la vue, pas par les sélecteurs DOM/API). Quand tu touches un fichier, vérifie que tu ne casses rien ailleurs.

Tu n'es pas en autonomie. Dom valide avant chaque étape. Tu proposes, il décide.

## Priorité absolue

**Le POC clinique Wallerstein doit tourner.** 5 postes Léa live ; les TIM travaillent sur leurs **vrais logiciels métier en mode web** (navigateur intégré au logiciel / navigateur du PC, instances **RDP** et **Citrix**), sur **2 écrans** → capture de la **fenêtre active**. Objectif produit : Léa **apprend** ces parcours et les **rejoue intelligemment** (pas du record-and-replay). Tout arbitrage technique se tranche par : « est-ce que ça rapproche ou éloigne du POC clinique qui tourne ? »

> Historique : `Urgence_aiva_demo` (22+ steps) sur la **maquette Easily Assure** (patiente fictive MOREL Catherine) était le banc de démo/test — **maquette abandonnée comme cible** (recadrage Dom 2026-06-25). Ne plus raisonner « Easily ».

## Méthode obligatoire — non négociable

- **Chirurgie itérative supervisée** : une modification, un test (≤ 2 min), validation explicite de Dom avant la suivante.
- **Pas de batch** : jamais plusieurs changements groupés sans validation intermédiaire.
- **Rustine interdite** : tu corriges la cause, pas le symptôme. Si tu ne comprends pas la cause, tu le dis et tu arrêtes.
- **Lire la doc avant d'agir** : code existant, `docs/`, specs. Pas de proposition basée sur des suppositions.
- **Un commit = une intention** : message explicite, daté.
- **Diff review systématique** sur tout code de production avant commit.

## Anti-patterns à proscrire

- Réponses longues. Si Dom dit "trop long" ou "déjà vu", tu raccourcis sans débattre.
- Propositions structurelles avant d'avoir compris l'intention de Dom.
- Re-proposer ce qui est déjà en place dans le code.
- Raisonner sur un composant trouvé via grep **sans vérifier qu'il est effectivement appelé au runtime**. Le projet contient beaucoup de code écrit mais non wired.
- Présenter la première solution qui marche. Toujours explorer 2-3 approches, présenter la meilleure avec justification.

## Architecture runtime réelle (à valider/raffiner avec Dom)

```
[VWB frontend React :3002]
        ↓ (HTTP)
[VWB backend Flask + SQLite]
        ↓ (envoi step par step)
[agent_v1 — Linux]
        ↓ (SSH vers Windows)
[Léa — chatbot exécutant — PC Windows]
        ↓
[Easily Assure — interface cible]
```

**Ollama** : sert le ou les modèles utilisés pour la résolution VLM, l'extraction texte, et la décision t2a. Sert aussi de **proxy vers cloud** pour certains appels.

**Cascade de résolution UI** (à confirmer composant par composant au runtime) :
1. OCR (docTR ou EasyOCR selon module)
2. cv2 template matching
3. YOLO v4 grounding
4. VLM grounding

**UI-DETR-1** : utilisé par VWB **au recording** pour overlays numérotés (équivalent OmniParser). `crop_hash` volontairement non persisté.

**Asymétrie connue, sujet ouvert post-démo** : VWB direct utilise UI-DETR-1 au runtime, le replay sur Léa ne l'utilise pas (cascade OCR/template/VLM seulement). Ne pas tenter de "fixer" cette asymétrie maintenant.

## ⚠️ Champs de mines — code orphelin

`core/` contient ~40 sous-modules. **Beaucoup ne sont pas wired au runtime actif.** Avant de raisonner sur un composant trouvé dans `core/` (coaching, healing, federation, learning, cognition, etc.) :

1. Vérifier qu'il est importé par un point d'entrée actif.
2. Vérifier qu'il est effectivement appelé en runtime (traces, logs).
3. Si doute, demander à Dom.

**Cas spécifique agent_v1** : suspicion de code orphelin à rebrancher. Si tu trouves un appel codé mais non exécuté en runtime (ex. appel Ollama de commentaire d'action présent dans le code mais jamais déclenché), c'est prioritaire à signaler.

## Debug — où regarder en premier

- `logs/` (racine projet) — logs runtime généraux
- `logs/audit/` — traces d'exécution
- `logs/healing/` — si concerne le healing
- `data/runner_captures/` — captures d'exécution
- `visual_workflow_builder/logs/` — logs VWB
- `server/logs/` — logs serveur

**Vérifier qu'un appel Ollama se déclenche vraiment au runtime** : ne pas se fier à la présence de l'appel dans le code. Tracer effectivement (log d'entrée de fonction, requête vue côté Ollama `:11434`).

## Inspirations externes

Voir `docs/INSPIRATION_FRAMEWORKS_2026-05-10.md` pour les patterns convergents (OpenAdapt, Skyvern, OmniParser : Policy/Grounding, Safety Gate, Abstraction Ladder, Planner-Actor-Validator). Le projet est techniquement plus mature que sa documentation ne le suggère — s'inspirer des bons patterns sans complexe.

## Recherche d'information

Ta connaissance interne est datée. Pour tout sujet technique évoluant vite (modèles VLM, frameworks RPA visuels, librairies de grounding, versions d'outils), **chercher sur internet d'abord**. Privilégier les sources de moins de 6 mois.

## Stack

- Python 3.10-3.12, venv `venv_v3/`
- Backend VWB : Flask + SQLite
- Frontend VWB : React (port 3002), dashboard :5001, API :8000
- LLM local : Ollama `:11434`
- GUI legacy : PyQt5
- Tests : pytest avec marqueurs (unit/integration/slow/smoke)
- Langue : français (code, commentaires, logs, GUI)

## Commandes utiles

```bash
cd ~/ai/rpa_vision_v3 && source venv_v3/bin/activate
./run.sh --full        # Écosystème complet
./run.sh --gui         # GUI PyQt5 seule
./run.sh --test        # Tests complets
make test-fast         # Tests rapides
make check             # Validation imports + tests rapides
```