docs(audit): README honnête + STATUS + DEV_SETUP + cleanup build

- README.md : bandeau POC, date 14 avril 2026, retrait claims "production-ready 77%" (alignement code/doc post-audit) - docs/STATUS.md : état réel par module (opérationnel/alpha/en cours) - docs/DEV_SETUP.md : gestion worktrees Claude - QUICK_START.md : gemma4:latest au lieu de qwen3-vl:8b - deploy/build_package.sh : +9 fichiers dans REQUIRED_FILES (system_dialog_guard.py, persistent_buffer.py, grounding.py, etc.) - agent_v0/deploy_windows.py : marqué OBSOLÈTE (legacy) - .gitignore : ajout data/, .hypothesis, .deps_installed, buffer/, instance/*.db, caches SQLite Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-14 16:49:29 +02:00
parent 36737cfe9d
commit 42f571d496
7 changed files with 438 additions and 172 deletions
--- a/docs/DEV_SETUP.md
+++ b/docs/DEV_SETUP.md
@@ -0,0 +1,107 @@
+# DEV_SETUP — Guide développeur
+
+Ce document recense les tâches d'administration du dépôt qui ne sont pas couvertes
+par `README.md` (destiné aux utilisateurs) mais nécessaires au quotidien.
+
+## Sommaire
+
+- [Environnement Python](#environnement-python)
+- [Services locaux](#services-locaux)
+- [Worktrees Claude Code](#worktrees-claude-code)
+- [Build du package Windows](#build-du-package-windows)
+
+---
+
+## Environnement Python
+
+- Venv du projet : `.venv/` (à la racine du repo)
+- Python supporté : 3.10 à 3.12
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Services locaux
+
+Utiliser `./svc.sh` pour piloter tous les services. La carte des ports est
+dans `services.conf`.
+
+```bash
+./svc.sh status          # État de tous les services
+./svc.sh start streaming # Démarrer le serveur Agent V1 (port 5005)
+./svc.sh restart api     # Redémarrer l'API (port 8000)
+./svc.sh stop            # Tout arrêter
+```
+
+## Worktrees Claude Code
+
+La CLI Claude Code peut créer des worktrees git dans `.claude/worktrees/` pour
+exécuter des agents parallèles sur des branches isolées. Ces dossiers peuvent
+occuper plusieurs centaines de Mo chacun et polluer les grep.
+
+### Vérifier l'état des worktrees
+
+```bash
+# Worktrees actifs vs branches git
+git worktree list
+git branch | grep worktree
+
+# Espace disque consommé
+du -sh .claude/worktrees/* 2>/dev/null
+```
+
+### Supprimer un worktree proprement
+
+```bash
+# 1) Retirer l'entrée git (libère le lock dans .git/worktrees/)
+git worktree remove .claude/worktrees/agent-<hash>
+
+# 2) Si le dossier persiste (worktree orphelin), forcer le retrait
+git worktree remove --force .claude/worktrees/agent-<hash>
+
+# 3) Supprimer les branches worktree abandonnées
+git branch -D worktree-agent-<hash>
+```
+
+### Nettoyage global
+
+```bash
+# Supprimer TOUS les worktrees et leurs branches associées
+for wt in .claude/worktrees/*/; do
+    hash=$(basename "$wt")
+    git worktree remove --force "$wt" 2>/dev/null
+done
+git branch | grep worktree-agent- | xargs -r git branch -D
+git worktree prune -v
+
+# Nettoyer les branches orphelines (worktree supprimé mais branche subsiste)
+git branch | grep worktree-agent- | xargs -r git branch -D
+```
+
+Le dossier `.claude/` est gitignoré — il ne sera jamais committé.
+
+## Build du package Windows
+
+Le package de déploiement pour le PC Windows des utilisateurs est généré par
+`deploy/build_package.sh`. Il embarque `agent_v0/agent_v1/` directement (pas
+de staging intermédiaire).
+
+```bash
+./deploy/build_package.sh          # Build standard
+./deploy/build_package.sh --clean  # Nettoyer avant de builder
+```
+
+Le script vérifie la présence de tous les fichiers Python requis via la liste
+`REQUIRED_FILES`. Si vous ajoutez un nouveau module Python critique côté agent
+(ex: dans `agent_v1/core/` ou `agent_v1/network/`), **ajoutez-le à
+`REQUIRED_FILES`** pour qu'un fichier manquant fasse échouer le build plutôt
+que de produire un zip incomplet.
+
+### Note historique : `agent_v0/deploy/windows_client/`
+
+Ce dossier a été créé par `agent_v0/deploy_windows.py` comme staging de build
+et s'est désynchronisé. Il a été supprimé en avril 2026 — le build officiel
+passe désormais par `deploy/build_package.sh` qui lit directement
+`agent_v0/agent_v1/`.
--- a/docs/STATUS.md
+++ b/docs/STATUS.md
@@ -0,0 +1,112 @@
+# STATUS — État réel du projet RPA Vision V3
+
+> Dernière mise à jour : 14 avril 2026
+>
+> Ce document remplace les affirmations marketing du README historique.
+> Il décrit l'état réel des modules, sans embellissement.
+
+## Positionnement
+
+**POC avancé** — certaines briques sont fonctionnelles de bout en bout
+(capture, streaming, premier replay E2E sur Notepad), d'autres sont en cours
+de stabilisation ou à l'état d'ébauche. Le projet n'est pas « production-ready ».
+
+Les fonctionnalités ci-dessous sont documentées sans minimiser les limites.
+
+## Légende
+
+- **opérationnel** : testé, utilisé régulièrement, pas de régression récente connue
+- **alpha** : branché et fonctionnel sur un cas d'usage de référence, manque
+  de recul sur la généralisation
+- **en cours** : en développement actif, comportement instable
+- **non démarré** : planifié, pas encore de code significatif
+
+## Vue d'ensemble par module
+
+| Module / fonctionnalité | État | Commentaire |
+|---|---|---|
+| Capture d'écran + événements (Agent V1 Windows) | opérationnel | `agent_v0/agent_v1/` — systray, streaming vers serveur |
+| Streaming server (`agent_v0/server_v1/`) | opérationnel | FastAPI port 5005, sessions en mémoire |
+| Stockage sessions (`RawSession`) | opérationnel | JSON + screenshots, rotation manuelle |
+| Détection UI (`core/detection/`) | alpha | Cascade VLM + OCR + templates, sensible au modèle choisi |
+| Embedding & FAISS (`core/embedding/`) | alpha | CLIP ViT-B/32 + index Flat, pas testé à grande échelle |
+| Workflow Graph (`core/graph/`) | alpha | Construction depuis sessions, matching heuristique |
+| Replay E2E (`agent_v0/server_v1/api_stream.py`) | alpha | Premier succès le 13 avril 2026 sur Notepad, asymétries strict/legacy connues |
+| Mode apprentissage supervisé | alpha | Pause sur échec répété, demande d'intervention humaine |
+| TargetMemoryStore (Phase 1 apprentissage) | alpha | Schéma SQLite en place, DB vide jusqu'au premier replay complet |
+| Grounding visuel (UI-TARS, gemma4, qwen3-vl) | alpha | Switch de modèle via `.env` (`RPA_VLM_MODEL`) |
+| SomEngine (YOLO + docTR + VLM) | alpha | Intégré, dormant dans la cascade par défaut |
+| Web Dashboard (port 5001) | alpha | Flask + SocketIO, fonctionnel mais non durci |
+| Visual Workflow Builder (VWB, ports 5002 + 3002) | en cours | Catalogue d'actions, UI React. Bugs DB runtime connus |
+| Agent Chat (port 5004) | alpha | Planner autonome, basé LLM local |
+| Module auth (`core/auth/`) | alpha | Vault Fernet + TOTP, CLI seul, pas d'intégration UI |
+| Federation (`core/federation/`) | alpha | Export/import de LearningPacks, pas de test terrain |
+| GPU Resource Manager (`core/gpu/`) | alpha | Gestion Ollama + warmup modèles, code utilisé mais peu testé |
+| Self-healing / recovery | en cours | Heuristiques présentes, comportement global non stabilisé |
+| Analytics / reporting | en cours | Prototype, pas de frontend finalisé |
+| Tests end-to-end | en cours | 1 replay E2E réussi, 56 tests d'intégration verts hors cas connus |
+| Deploy Windows (`deploy/build_package.sh`) | opérationnel | Produit `Lea_v<version>.zip`, vérification des fichiers requis |
+| Conformité AI Act (journalisation, floutage, rétention logs) | alpha | Mécanismes en place, audit formel non fait |
+
+## Limites connues (non exploitables comme failles)
+
+- Plusieurs copies parallèles du code agent ont existé (source, staging
+  Windows, worktrees) avec risque de divergence. Le staging Windows obsolète
+  a été supprimé ; le build officiel passe par `deploy/build_package.sh`.
+- La base `data/learning/target_memory.db` reste vide tant qu'un replay
+  complet n'a pas été cristallisé — l'apprentissage est câblé mais pas
+  encore éprouvé.
+- Certaines asymétries entre chemins « strict » et « legacy » dans
+  `api_stream.py` peuvent faire retomber une erreur en mode strict vers
+  le retry+stop legacy au lieu de la pause d'apprentissage.
+- Le worker de compilation sessions → `ExecutionPlan` (port 5099) n'est pas
+  lancé par défaut — les sessions enregistrées ne sont pas compilées
+  automatiquement.
+- Le VWB présente des bugs en écriture DB identifiés et documentés.
+- La détection VLM est sensible au choix de modèle ; le défaut est
+  `gemma4:latest` (cf. `.env.example`).
+
+## Modèles utilisés
+
+Définis dans `.env` (voir `.env.example`) :
+
+| Variable | Valeur par défaut | Rôle |
+|---|---|---|
+| `RPA_VLM_MODEL` | `gemma4:latest` | Modèle VLM principal (Ollama) |
+| `VLM_MODEL` | `gemma4:latest` | Alias de compatibilité |
+| `CLIP_MODEL` | `ViT-B-32` | Embeddings visuels |
+| `CLIP_PRETRAINED` | `openai` | Poids pré-entraînés |
+| `VLM_ENDPOINT` | `http://localhost:11434` | Ollama local |
+
+Modèles alternatifs testés : `qwen3-vl:8b`, `ui-tars` (grounding direct).
+Aucun appel cloud par défaut — tout passe par Ollama local.
+
+## Infrastructure
+
+- **OS cible serveur** : Linux (Ubuntu 24.04 testé)
+- **GPU recommandé** : NVIDIA (ex. RTX 5070) pour l'inférence VLM locale
+- **OS cible client** : Windows 10/11 (Agent V1)
+- **Python** : 3.10 à 3.12
+- **Ollama** : service local obligatoire
+
+## Ports utilisés (source : `services.conf`)
+
+| Port | Service |
+|---|---|
+| 8000 | API Server (core upload) |
+| 5001 | Web Dashboard |
+| 5002 | VWB Backend (Flask) |
+| 5003 | Monitoring |
+| 5004 | Agent Chat |
+| 5005 | Streaming Server (Agent V1) |
+| 5006 | Session Cleaner |
+| 5099 | Worker de compilation (optionnel) |
+| 3002 | VWB Frontend (Vite/React) |
+
+## Prochaines étapes prioritaires
+
+1. Stabiliser le replay E2E sur 3 applications métier différentes
+2. Alimenter `TargetMemoryStore` via des replays réussis réels
+3. Harmoniser les branches `strict` / `legacy` dans `api_stream.py`
+4. Durcir VWB ou pivoter vers un outil dédié plus simple
+5. Activer le worker de compilation sessions → ExecutionPlan