rpa_vision_v3/README.md

# RPA Vision V3 — Automatisation basée sur la compréhension visuelle des interfaces

> ⚠️ **Projet en phase POC** — voir [`docs/STATUS.md`](docs/STATUS.md) pour l'état
> réel par module. Certaines briques sont opérationnelles bout en bout,
> d'autres sont en cours de stabilisation. Ce dépôt n'est pas production-ready.

*Dernière mise à jour : 14 avril 2026*

## Intention

Automatiser des workflows métier par **compréhension sémantique de l'écran**
plutôt que par coordonnées de clic fixes. Le système observe l'utilisateur,
reconstruit un graphe d'états de l'interface, et cherche à rejouer la
procédure en reconnaissant visuellement les éléments cibles — y compris
quand l'UI change légèrement.

Terrain cible principal : postes hospitaliers (Citrix, applications métier
web et desktop). Contrainte forte : **100 % local**, pas d'appel à un LLM
cloud dans le pipeline par défaut.

## Architecture en couches

```
RawSession (couche 0) — capture événements + screenshots
        ↓
ScreenState (couche 1) — états d'écran à plusieurs niveaux d'abstraction
        ↓
UIElement (couche 2) — détection sémantique (cascade OCR + templates + VLM)
        ↓
State Embedding (couche 3) — fusion multi-modale + index FAISS
        ↓
Workflow Graph (couche 4) — nœuds, transitions, résolution de cibles
```

## État des fonctionnalités (synthèse)

Le détail par module est dans [`docs/STATUS.md`](docs/STATUS.md).

**Opérationnel**
- Capture Windows (Agent V1) + streaming vers serveur Linux
- Stockage des sessions brutes (screenshots + événements)
- Streaming server FastAPI, sessions en mémoire
- Build du package Windows (`deploy/build_package.sh`)

**Alpha (fonctionnel sur un cas de référence, encore peu généralisé)**
- Détection UI par cascade VLM + OCR + templates
- Construction de workflow graph depuis une session
- Replay E2E supervisé — premier succès sur Notepad le 13 avril 2026
- Mode apprentissage : pause et demande d'aide humaine quand la résolution échoue
- Embeddings CLIP + index FAISS
- Module auth (Fernet + TOTP), federation (LearningPack)
- Web Dashboard, Agent Chat

**En cours**
- Visual Workflow Builder (VWB) — bugs DB runtime connus
- Self-healing / recovery global
- Analytics / reporting
- Worker de compilation sessions → ExecutionPlan
- Tests E2E multi-applications

## Limitations connues

- Le pipeline de replay est validé sur un nombre très restreint d'applications.
- `TargetMemoryStore` (apprentissage Phase 1) est câblé mais sa base reste
  vide tant qu'un replay complet n'a pas été cristallisé.
- Certaines asymétries entre chemins stricts et legacy dans le serveur de
  streaming peuvent provoquer des arrêts au lieu de pauses d'apprentissage.
- VWB n'est pas encore stable en écriture ; un outil dédié plus simple est
  envisagé.

## Démarrage

### Prérequis

- Python 3.10 à 3.12
- [Ollama](https://ollama.ai) installé et démarré localement
- Recommandé : GPU NVIDIA pour l'inférence VLM
- Windows 10/11 uniquement pour le client Agent V1

### Installation

```bash
# 1) Cloner puis créer le venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2) Démarrer Ollama et récupérer le modèle VLM par défaut
ollama serve &
ollama pull gemma4:latest        # défaut du projet
# Alternatives supportées :
# ollama pull qwen3-vl:8b
# ollama pull 0000/ui-tars-1.5-7b-q8_0:7b   # grounder visuel

# 3) Copier et ajuster la configuration
cp .env.example .env
# éditer .env pour vérifier RPA_VLM_MODEL, VLM_ENDPOINT, ports, etc.
```

### Lancer les services

Tous les services sont pilotés par `svc.sh` (source de vérité des ports :
`services.conf`).

```bash
./svc.sh status          # État de tous les services
./svc.sh start           # Tout démarrer
./svc.sh start streaming # Streaming server uniquement (port 5005)
./svc.sh restart api     # Redémarrer l'API (port 8000)
./svc.sh stop            # Tout arrêter
```

| Port | Service |
|---|---|
| 8000 | API Server (upload / traitement core) |
| 5001 | Web Dashboard |
| 5002 | VWB Backend (Flask) |
| 5003 | Monitoring |
| 5004 | Agent Chat |
| 5005 | Streaming Server (Agent V1 → pipeline core) |
| 5006 | Session Cleaner |
| 5099 | Worker de compilation (optionnel) |
| 3002 | VWB Frontend (Vite/React) |

### Client Windows (Agent V1)

Le client capture souris, clavier et écran sur le poste Windows et envoie
les données au streaming server Linux.

```bash
# Build du package Windows depuis le repo Linux
./deploy/build_package.sh
# produit deploy/Lea_v<version>.zip
```

Voir [`docs/DEV_SETUP.md`](docs/DEV_SETUP.md) pour la maintenance du dépôt
(worktrees, build, services).

## Arborescence du dépôt

```
rpa_vision_v3/
├── agent_v0/                # Agent V1 (client Windows) + serveur de streaming
│   ├── agent_v1/            # Source de l'agent (capture, UI tray, exécution)
│   └── server_v1/           # FastAPI streaming + processeurs
├── core/                    # Pipeline core
│   ├── detection/           # Cascade VLM + OCR + templates
│   ├── embedding/           # CLIP + FAISS
│   ├── graph/               # Construction / matching de workflow graphs
│   ├── execution/           # Résolution de cibles, actions LLM
│   ├── learning/            # TargetMemoryStore (apprentissage)
│   ├── auth/                # Vault Fernet + TOTP
│   └── federation/          # Export/import de LearningPacks
├── visual_workflow_builder/ # VWB (backend Flask + frontend React Vite)
├── web_dashboard/           # Dashboard Flask + SocketIO
├── agent_chat/              # Interface conversationnelle + planner
├── deploy/                  # Scripts de build et unités systemd
├── data/                    # Sessions, embeddings, index FAISS, apprentissage
├── docs/                    # Documentation technique
├── tests/                   # pytest (unit, integration, e2e)
├── services.conf            # Source de vérité des ports
├── svc.sh                   # Orchestrateur des services
└── run.sh                   # Démarrage tout-en-un (legacy, préférer svc.sh)
```

## Tests

```bash
source .venv/bin/activate

# Tests rapides (hors marqueur slow)
pytest -m "not slow" -q

# Tests d'intégration (streaming, pipeline)
pytest tests/integration/ -q

# Tests E2E
pytest tests/test_pipeline_e2e.py -q
```

Quelques tests legacy sont connus comme cassés — voir la mémoire projet et
`docs/` pour la liste.

## Documentation

- [`docs/STATUS.md`](docs/STATUS.md) — état réel par module
- [`docs/DEV_SETUP.md`](docs/DEV_SETUP.md) — tâches d'administration (worktrees, build)
- [`docs/EXECUTION_LOOP_FLAGS.md`](docs/EXECUTION_LOOP_FLAGS.md) — flags C1 vision-aware (`enable_ui_detection`, `enable_ocr`, `analyze_timeout_ms`, `window_info_provider`)
- [`docs/VISION_RPA_INTELLIGENT.md`](docs/VISION_RPA_INTELLIGENT.md) — cahier des charges
- [`docs/PLAN_ACTEUR_V1.md`](docs/PLAN_ACTEUR_V1.md) — architecture 3 niveaux (Macro / Méso / Micro)
- [`docs/CONFORMITE_AI_ACT.md`](docs/CONFORMITE_AI_ACT.md) — journalisation, floutage, rétention

## Concepts clés

- **RPA 100 % vision** : pas de coordonnées fixes ; l'agent localise un
  élément par ce qu'il voit (label + contexte visuel), pas par `x,y`.
- **Apprentissage progressif** : mode shadow → assisté → autonome, validé
  par supervision humaine sur les échecs.
- **LLM 100 % local** : Ollama sur la machine. Aucun appel cloud dans le
  pipeline par défaut (cf. feedback projet `feedback_local_only.md`).

## Licence

Propriétaire — tous droits réservés.