# Implémentation Capture d'Écran et Embedding Visuel - VWB

**Auteur : Dom, Alice, Kiro - 09 janvier 2026**

## Résumé

Cette documentation décrit l'implémentation des endpoints de capture d'écran et de création d'embeddings visuels pour le Visual Workflow Builder (VWB).

## Fonctionnalités Implémentées

### 1. Endpoint `/api/screen-capture` (POST)

Capture l'écran actuel et retourne l'image en base64.

**Request Body (optionnel):**
```json
{
  "format": "png",
  "quality": 90
}
```

**Response:**
```json
{
  "success": true,
  "screenshot": "base64_encoded_image...",
  "width": 1920,
  "height": 1080,
  "timestamp": "2026-01-09T13:41:18.123456"
}
```

### 2. Endpoint `/api/visual-embedding` (POST)

Crée un embedding visuel à partir d'une capture d'écran et d'une zone sélectionnée.

**Request Body:**
```json
{
  "screenshot": "base64_encoded_image...",
  "boundingBox": {
    "x": 100,
    "y": 200,
    "width": 150,
    "height": 50
  },
  "stepId": "step_123"
}
```

**Response:**
```json
{
  "success": true,
  "embedding": [0.1, 0.2, ...],
  "embedding_id": "emb_step_123_20260109_134118",
  "dimension": 512,
  "reference_image": "emb_step_123_..._ref.png",
  "bounding_box": {
    "x": 100,
    "y": 200,
    "width": 150,
    "height": 50
  }
}
```

### 3. Endpoint `/api/visual-embedding/<embedding_id>` (GET)

Récupère un embedding existant par son ID.

### 4. Endpoint `/api/visual-embedding/<embedding_id>/image` (GET)

Récupère l'image de référence d'un embedding.

## Architecture Technique

### Services Utilisés

1. **ScreenCapturer** (`core/capture/screen_capturer.py`)
   - Capture d'écran via `mss` ou `pyautogui`
   - Support multi-moniteur
   - Buffer circulaire pour historique

2. **CLIPEmbedder** (`core/embedding/clip_embedder.py`)
   - Modèle ViT-B/32 OpenAI
   - Embeddings de dimension 512
   - Exécution sur CPU pour économiser la mémoire GPU

### Stockage des Données

Les embeddings et images de référence sont stockés dans :
```
data/visual_embeddings/
├── emb_step_xxx_YYYYMMDD_HHMMSS.npy      # Embedding numpy
└── emb_step_xxx_YYYYMMDD_HHMMSS_ref.png  # Image de référence
```

## Intégration Frontend

Le composant `VisualSelector` (`visual_workflow_builder/frontend/src/components/VisualSelector/index.tsx`) utilise ces endpoints pour :

1. **Étape 1 - Capture** : Appel à `/api/screen-capture`
2. **Étape 2 - Sélection** : Interface canvas pour sélectionner une zone
3. **Étape 3 - Confirmation** : Appel à `/api/visual-embedding` pour créer l'embedding

## Tests

Les tests sont disponibles dans :
- `tests/integration/test_vwb_screen_capture_api.py`

### Exécution des Tests

```bash
python3 -c "
import sys
sys.path.insert(0, '.')
sys.path.insert(0, 'visual_workflow_builder/backend')
from app_lightweight import capture_screen_to_base64, create_visual_embedding

# Test capture
result = capture_screen_to_base64()
print(f'Capture: {result[\"success\"]}')

# Test embedding
if result['success']:
    bbox = {'x': 100, 'y': 100, 'width': 200, 'height': 100}
    emb = create_visual_embedding(result['screenshot'], bbox, 'test')
    print(f'Embedding: {emb[\"success\"]}')
"
```

## Résultats de Validation

- ✅ Capture d'écran fonctionnelle (1920x1080)
- ✅ Création d'embeddings CLIP (dimension 512)
- ✅ Sauvegarde des embeddings en fichiers .npy
- ✅ Sauvegarde des images de référence en PNG
- ✅ Intégration avec le frontend VisualSelector

## Prochaines Étapes

1. Tests d'intégration avec le frontend en conditions réelles
2. Optimisation du temps de chargement du modèle CLIP
3. Ajout de la recherche par similarité dans les embeddings existants