# VWB Vision RPA - Document de Référence
## Session du 24 Janvier 2026

---

## 1. RÉSUMÉ DU PROBLÈME INITIAL

Le workflow "Onlyoffice" (12 étapes) cliquait au mauvais endroit :
- **Symptôme** : Gedit s'ouvrait au lieu de OnlyOffice
- **Cause** : Les seuils de matching étaient trop permissifs (acceptait des matches à 200+ pixels de distance)
- **Impact** : Le workflow continuait même après un clic erroné

---

## 2. ARCHITECTURE DU SYSTÈME DE VISION

```
┌─────────────────────────────────────────────────────────────┐
│                    PIPELINE DE MATCHING                      │
├─────────────────────────────────────────────────────────────┤
│  1. UI-DETR-1 (rfdetr)                                      │
│     → Détecte tous les éléments UI à l'écran                │
│     → Retourne des bounding boxes                           │
│                                                              │
│  2. CLIP (OpenCLIP)                                         │
│     → Compare l'ancre avec chaque élément détecté           │
│     → Score de similarité sémantique (0-1)                  │
│     → Pondéré par la distance à la position originale       │
│                                                              │
│  3. Template Matching (OpenCV)                              │
│     → Fallback si CLIP échoue                               │
│     → Comparaison pixel à pixel                             │
│     → Zoned (100-200px) puis Global                         │
│                                                              │
│  4. Static Fallback                                         │
│     → Dernier recours : coordonnées originales              │
└─────────────────────────────────────────────────────────────┘
```

---

## 3. SEUILS CRITIQUES (VALEURS ACTUELLES)

### Dans `intelligent_executor.py` - Méthode CLIP

```python
# === SEUILS ÉQUILIBRÉS ===
MAX_DISTANCE_PX = 120      # Rejeter tout élément > 120px de la position originale
MIN_CLIP_SCORE = 0.55      # Score CLIP minimum requis
MIN_COMBINED_SCORE = 0.5   # Score combiné minimum pour accepter un match
```

### Dans `intelligent_executor.py` - Template Matching Zoné

```python
MAX_TEMPLATE_DISTANCE = 150  # Dans zoned_template_match()
```

### Dans `intelligent_executor.py` - Template Matching Global

```python
MAX_GLOBAL_DISTANCE = 150    # Dans find_and_click()
```

---

## 4. FICHIERS MODIFIÉS

| Fichier | Modifications |
|---------|---------------|
| `services/intelligent_executor.py` | Seuils CLIP, limites de distance, logs détaillés |
| `api_v3/execute.py` | Logique d'exécution avec modes basic/intelligent/debug |
| `services/ui_detection_service.py` | Backend UI-DETR-1 |
| `frontend_v4/src/App.tsx` | Overlay debug désactivé |
| `frontend_v4/src/components/ExecutionOverlay.tsx` | URLs API corrigées |
| `catalog_routes_v2_vlm.py` | Intégration VLM Ollama |

---

## 5. MODES D'EXÉCUTION

| Mode | Comportement | Vitesse | Utilisation |
|------|--------------|---------|-------------|
| **basic** | Coordonnées statiques uniquement | Rapide | Écran identique à l'enregistrement |
| **intelligent** | Vision (CLIP + Template) | Lent | Interface peut changer |
| **debug** | Vision + logs détaillés | Lent | Débogage |

---

## 6. ORDRE DES STRATÉGIES DE MATCHING

```
1. CLIP (UI-DETR-1 + embeddings CLIP)
   ├── Si trouvé avec confiance ≥ 0.5 et distance ≤ 120px → UTILISER
   └── Sinon → Fallback

2. Template Matching Zoné (100px)
   ├── Si trouvé avec confiance ≥ 0.7 et distance ≤ 150px → UTILISER
   └── Sinon → Élargir

3. Template Matching Zoné Élargi (200px)
   ├── Si trouvé avec confiance ≥ 0.6 et distance ≤ 150px → UTILISER
   └── Sinon → Global

4. Template Matching Global
   ├── Si trouvé avec confiance ≥ 0.75 et distance ≤ 150px → UTILISER
   └── Sinon → Static Fallback

5. Static Fallback
   └── Utiliser les coordonnées originales de l'enregistrement
```

---

## 7. PROBLÈMES COURANTS ET SOLUTIONS

### Problème : "Aucun candidat valide (tous rejetés par seuils stricts)"
**Cause** : Les seuils CLIP sont trop stricts ou UI-DETR-1 ne détecte pas l'élément
**Solution** :
- Baisser `MIN_CLIP_SCORE` (ex: 0.50)
- Augmenter `MAX_DISTANCE_PX` (ex: 150)

### Problème : Clic au mauvais endroit
**Cause** : Template matching trouve un faux positif loin de la cible
**Solution** :
- Réduire `MAX_TEMPLATE_DISTANCE` et `MAX_GLOBAL_DISTANCE`
- Vérifier que l'ancre est bien distinctive

### Problème : Workflow très lent
**Cause** :
- Modèles rechargés à chaque étape
- Ollama sur CPU
- Multiples fallbacks
**Solutions** :
- Utiliser mode `basic` pour workflows stables
- Configurer Ollama pour GPU
- Implémenter un cache des modèles

### Problème : Ollama sur CPU au lieu de GPU
**Vérification** : `ollama ps`
**Solution** :
```bash
# Vérifier CUDA
nvidia-smi
# Relancer Ollama avec GPU
CUDA_VISIBLE_DEVICES=0 ollama serve
```

---

## 8. MODÈLES UTILISÉS

| Modèle | Utilisation | Emplacement |
|--------|-------------|-------------|
| UI-DETR-1 (rfdetr) | Détection éléments UI | `/home/dom/ai/rpa_vision_v3/models/ui-detr-1/model.pth` |
| CLIP (ViT-B-32) | Similarité sémantique | OpenCLIP (téléchargé automatiquement) |
| qwen2.5vl:3b | Analyse IA (vision) | Ollama |

### Modèles Ollama recommandés pour meilleure qualité :
- `qwen2.5vl:7b` - Meilleur que 3b
- `llama3.2-vision:11b` - Encore meilleur
- `mistral:7b` - Pour texte pur (pas de vision)

---

## 9. COMMANDES UTILES

```bash
# Démarrer le backend VWB
cd /home/dom/ai/rpa_vision_v3/visual_workflow_builder/backend
./venv/bin/python app.py

# Vérifier le port 5001
lsof -i :5001

# Voir les logs d'exécution
tail -f /tmp/vwb_backend.log | grep -E "(Execute|Vision|CLIP)"

# Vérifier le status d'une exécution
curl -s http://localhost:5001/api/v3/execute/status | python3 -m json.tool

# Lister les modèles Ollama
ollama list

# Voir si Ollama utilise le GPU
ollama ps
```

---

## 10. RÉSULTAT FINAL

Le workflow "Onlyoffice" (12 étapes) fonctionne maintenant :

| Étape | Action | Méthode | Status |
|-------|--------|---------|--------|
| 1 | Clic menu | CLIP 99.8% | ✅ |
| 2 | Saisie "onlyoffice" | - | ✅ |
| 3 | Clic OnlyOffice | static_fallback | ✅ |
| 4 | Clic docx | CLIP 99.2% | ✅ |
| 5 | Attente 5s | - | ✅ |
| 6 | Saisie texte | - | ✅ |
| 7 | Analyse IA | qwen2.5vl:3b | ✅ |
| 8 | Clic menu | CLIP 98.9% | ✅ |
| 9 | Saisie "gedit" | - | ✅ |
| 10 | Clic gedit | static_fallback | ✅ |
| 11 | Attente 10s | - | ✅ |
| 12 | Coller résultat IA | - | ✅ |

---

## 11. PROCHAINES AMÉLIORATIONS SUGGÉRÉES

1. **Cache des modèles** : Charger UI-DETR-1 et CLIP une seule fois au démarrage
2. **Ollama GPU** : Configurer pour utiliser le GPU
3. **Seuils adaptatifs** : Ajuster automatiquement selon le contexte
4. **Vérification post-action** : Confirmer que l'action a eu l'effet attendu
5. **Mode hybride** : Basic par défaut, vision uniquement si échec

---

## 12. CONTACT / HISTORIQUE

- **Date de résolution** : 24 Janvier 2026
- **Durée de débogage** : ~2 heures
- **Fichiers sauvegardés** : `/home/dom/ai/rpa_vision_v3/backups_24janv.2026_vision_fix/`

---

*Document généré automatiquement - Ne pas modifier manuellement*