rpa_vision_v3/docs/archive/misc/agent/AGENT_V0_ANALYSIS.md

Agent V0 - Analyse et Validation ✅

Date: 24 novembre 2025
Status: Architecture Validée - Recommandations Fournies

📋 Vue d'Ensemble

L'agent V0 est un enregistreur d'interface cross-plateforme léger qui capture les interactions utilisateur et les envoie au serveur RPA Vision V3 pour apprentissage.

Objectif

Permettre aux formateurs (Windows/macOS/Linux) d'enregistrer leurs workflows sans avoir besoin du système complet RPA Vision V3.

Architecture

Agent V0 (Poste Formateur)
    ↓ Capture
    ├─ Clics souris
    ├─ Combos clavier  
    ├─ Scroll molette
    ├─ Hover (immobilité)
    └─ Screenshots (full/crop)
    ↓ Package
    RawSession JSON + Screenshots ZIP
    ↓ Upload
Serveur RPA Vision V3 (Linux)

✅ Points Forts

1. Compatibilité Parfaite avec RPA Vision V3

• ✅ Utilise le format rawsession_v1 identique à core/models/raw_session.py
• ✅ Structure Event/Screenshot/WindowContext compatible
• ✅ Timestamps relatifs (t en secondes depuis début session)
• ✅ Métadonnées complètes (environment, user, context)

2. Architecture Modulaire et Propre

agent_v0/
├── main.py              # Point d'entrée
├── tray_ui.py           # Interface utilisateur (icône tray)
├── raw_session.py       # Modèle de données
├── event_captor.py      # Capture souris (clics, scroll, hover)
├── key_captor.py        # Capture clavier (combos)
├── screen_capturer.py   # Screenshots (mss)
├── window_info.py       # Info fenêtre active (xdotool)
├── storage.py           # Création ZIP
├── uploader.py          # Upload serveur
├── user_config.py       # Configuration JSON
├── config.py            # Constantes
└── logger_conf.py       # Logging rotatif

3. Fonctionnalités Avancées

• ✅ Hover detection - Capture l'immobilité souris (infobulles)
• ✅ Screenshot modes - Full screen ou crop autour du curseur
• ✅ Key combos - Détection CTRL+C, ALT+F4, etc.
• ✅ Scroll tracking - Molette souris avec delta
• ✅ Network save - Copie automatique vers chemin réseau
• ✅ ZIP packaging - Session complète en un fichier
• ✅ Logging rotatif - Fichiers logs avec rotation 5MB

4. UX Excellente

• ✅ Icône tray (zone de notification)
• ✅ Menu simple: Start/Stop/Open/Quit
• ✅ Indicateur visuel (vert=actif, gris=inactif)
• ✅ Configuration JSON éditable
• ✅ Ouverture dossiers sessions/logs depuis le menu

⚠️ Points d'Attention

1. Compatibilité Cross-Plateforme Limitée

Problème: window_info.py utilise xdotool (Linux uniquement)

# window_info.py - LINUX ONLY
def get_active_window_info():
    title = _run_cmd(["xdotool", "getactivewindow", "getwindowname"])
    pid_str = _run_cmd(["xdotool", "getactivewindow", "getwindowpid"])

Impact: Ne fonctionnera pas sur Windows/macOS

Solution: Implémenter des backends spécifiques par OS:

# window_info.py - CROSS-PLATFORM
import sys
import platform

def get_active_window_info() -> Dict[str, str]:
    system = platform.system()
    
    if system == "Linux":
        return _get_window_info_linux()
    elif system == "Windows":
        return _get_window_info_windows()
    elif system == "Darwin":  # macOS
        return _get_window_info_macos()
    else:
        return {"title": "unknown_window", "app_name": "unknown_app"}

def _get_window_info_linux():
    # Code actuel avec xdotool
    ...

def _get_window_info_windows():
    # Windows: pywin32 ou ctypes
    import win32gui
    import win32process
    import psutil
    
    hwnd = win32gui.GetForegroundWindow()
    title = win32gui.GetWindowText(hwnd)
    _, pid = win32process.GetWindowThreadProcessId(hwnd)
    app_name = psutil.Process(pid).name()
    
    return {"title": title, "app_name": app_name}

def _get_window_info_macos():
    # macOS: pyobjc ou AppleScript
    from AppKit import NSWorkspace
    
    active_app = NSWorkspace.sharedWorkspace().activeApplication()
    app_name = active_app['NSApplicationName']
    # Pour le titre, utiliser AppleScript ou Accessibility API
    
    return {"title": "...", "app_name": app_name}

Dépendances à ajouter:

# requirements.txt
pywin32>=306 ; sys_platform == 'win32'
pyobjc-framework-Cocoa>=10.0 ; sys_platform == 'darwin'
psutil>=5.9.0  # Pour Windows process info

2. Sécurité et Permissions

Problème: Capture d'écran et monitoring clavier nécessitent des permissions

Windows:

• Pas de permissions spéciales nécessaires
• Antivirus peut bloquer (ajouter exception)

macOS:

• ⚠️ Nécessite "Accessibility" permissions
• ⚠️ Nécessite "Screen Recording" permissions
• Demander à l'utilisateur d'activer dans System Preferences

Linux:

• Nécessite X11 (pas Wayland par défaut)
• xdotool doit être installé

Recommandation: Ajouter un check au démarrage:

# permissions_check.py
def check_permissions():
    system = platform.system()
    
    if system == "Darwin":
        # Vérifier Accessibility
        from AppKit import NSWorkspace
        # Tester si on peut lire la fenêtre active
        try:
            NSWorkspace.sharedWorkspace().activeApplication()
        except:
            show_macos_permissions_dialog()
            return False
    
    elif system == "Linux":
        # Vérifier xdotool
        if not shutil.which("xdotool"):
            show_linux_install_dialog()
            return False
    
    return True

3. Gestion des Données Sensibles

Problème: Les screenshots peuvent contenir des données sensibles

Recommandations:

1. Chiffrement du ZIP avant upload
2. Anonymisation optionnelle des screenshots
3. Politique de rétention claire (supprimer après X jours)
4. RGPD compliance - Consentement utilisateur

# storage.py - Ajout chiffrement
import zipfile
import pyminizip  # ou cryptography

def create_session_zip_encrypted(session, password):
    zip_path = create_session_zip(session)
    encrypted_path = zip_path.replace('.zip', '_encrypted.zip')
    
    # Chiffrer avec AES-256
    pyminizip.compress(
        zip_path, 
        None, 
        encrypted_path, 
        password, 
        5  # compression level
    )
    
    os.remove(zip_path)  # Supprimer non-chiffré
    return encrypted_path

4. Performance et Optimisation

Problème: Screenshots en PNG peuvent être volumineux

Recommandations:

1. Compression JPEG pour screenshots (qualité 85%)
2. Resize automatique si > 1920x1080
3. Throttling - Max 1 screenshot/seconde

# screen_capturer.py - Optimisations
from PIL import Image

def capture_optimized(self, focus_pos):
    # Capture existante
    screenshot_id, relative_path = self.capture(focus_pos)
    
    # Optimiser l'image
    img_path = os.path.join(self._get_session_shots_dir(), f"{screenshot_id}.png")
    
    with Image.open(img_path) as img:
        # Resize si trop grand
        if img.width > 1920 or img.height > 1080:
            img.thumbnail((1920, 1080), Image.Resampling.LANCZOS)
        
        # Convertir en JPEG (plus léger)
        jpg_path = img_path.replace('.png', '.jpg')
        img.convert('RGB').save(jpg_path, 'JPEG', quality=85, optimize=True)
        
        # Supprimer PNG
        os.remove(img_path)
        
        # Mettre à jour relative_path
        relative_path = relative_path.replace('.png', '.jpg')
    
    return screenshot_id, relative_path

5. Packaging et Distribution

Problème: Distribution aux formateurs

Solution: Utiliser PyInstaller (déjà configuré avec .spec)

# build.sh
#!/bin/bash
pyinstaller agent_v0_tray.spec

# Résultat:
# dist/agent_v0_tray  (Linux)
# dist/agent_v0_tray.exe  (Windows)
# dist/agent_v0_tray.app  (macOS)

Recommandations:

1. Créer des installeurs - NSIS (Windows), DMG (macOS), DEB/RPM (Linux)
2. Auto-update - Vérifier version au démarrage
3. Signature de code - Éviter les warnings antivirus

🔧 Intégration avec RPA Vision V3

Côté Serveur (À Implémenter)

# server/api/upload_handler.py
from fastapi import FastAPI, UploadFile, File
from core.persistence import StorageManager
from core.models import RawSession

app = FastAPI()
storage = StorageManager(base_path="data/training")

@app.post("/api/traces/upload")
async def upload_session(
    file: UploadFile = File(...),
    session_id: str = Form(...)
):
    # Sauvegarder ZIP
    zip_path = f"data/training/uploads/{session_id}.zip"
    with open(zip_path, "wb") as f:
        f.write(await file.read())
    
    # Extraire et valider
    extract_dir = f"data/training/sessions/{session_id}"
    with zipfile.ZipFile(zip_path, 'r') as zf:
        zf.extractall(extract_dir)
    
    # Charger RawSession
    json_path = f"{extract_dir}/{session_id}/{session_id}.json"
    session = RawSession.load_from_file(Path(json_path))
    
    # Valider format
    assert session.schema_version == "rawsession_v1"
    
    # Stocker avec StorageManager
    storage.save_raw_session(session)
    
    return {"status": "success", "session_id": session_id}

Pipeline de Training

# training/process_agent_sessions.py
from core.models import RawSession, ScreenState
from core.embedding import StateEmbeddingBuilder
from core.graph import GraphBuilder

def process_agent_session(session_id: str):
    # 1. Charger RawSession
    session = storage.load_raw_session(session_id)
    
    # 2. Construire ScreenStates
    screen_states = []
    for event in session.events:
        if event.screenshot_id:
            # Créer ScreenState à partir de screenshot
            state = build_screen_state_from_event(event, session)
            screen_states.append(state)
    
    # 3. Générer embeddings
    builder = StateEmbeddingBuilder()
    for state in screen_states:
        embedding = builder.build_embedding(state)
        storage.save_embedding(embedding.vector, state.screen_state_id)
    
    # 4. Construire workflow
    graph_builder = GraphBuilder()
    workflow = graph_builder.build_from_session(session)
    storage.save_workflow(workflow)
    
    return workflow

📊 Comparaison avec RPA Vision V3

Aspect	Agent V0	RPA Vision V3
Plateforme	Windows/macOS/Linux	Linux (serveur)
Rôle	Capture données	Analyse + Exécution
Dépendances	Légères (mss, pynput)	Lourdes (CLIP, FAISS, Ollama)
UI	Tray icon	GUI complète
Stockage	Local + Upload	Base de données
Processing	Aucun	Embeddings + Matching
Taille	~50 MB (packagé)	~2 GB (avec modèles)

🎯 Recommandations Prioritaires

Priorité 1 - Critique

1. ✅ Implémenter window_info cross-plateforme (Windows/macOS)
2. ✅ Ajouter check permissions au démarrage
3. ✅ Chiffrer les ZIPs avant upload

Priorité 2 - Important

4. ✅ Optimiser screenshots (JPEG, resize)
5. ✅ Créer API serveur pour recevoir uploads
6. ✅ Tester sur Windows/macOS réels

Priorité 3 - Nice to Have

7. ✅ Auto-update mécanisme
8. ✅ Anonymisation optionnelle screenshots
9. ✅ Statistiques session (durée, nb events)
10. ✅ Preview session avant upload

📝 Checklist de Déploiement

Avant Distribution

• Tester sur Windows 10/11
• Tester sur macOS 12+
• Tester sur Ubuntu 22.04+
• Vérifier permissions (Accessibility, Screen Recording)
• Créer installeurs (NSIS, DMG, DEB)
• Signer le code (éviter warnings antivirus)
• Documenter installation (README_AGENT.md)
• Créer guide utilisateur (PDF)

Côté Serveur

• Implémenter API /api/traces/upload
• Configurer stockage (data/training/)
• Implémenter pipeline de processing
• Ajouter monitoring (Prometheus/Grafana)
• Configurer backup automatique
• Tester charge (100+ formateurs simultanés)

🎉 Conclusion

L'agent V0 est une excellente base! L'architecture est propre, modulaire et bien pensée. Les principaux points à adresser sont:

1. Compatibilité cross-plateforme (window_info)
2. Sécurité (chiffrement, permissions)
3. Optimisation (compression screenshots)

Avec ces améliorations, l'agent sera prêt pour déploiement production chez les formateurs.

---

Prochaines étapes suggérées:

1. Implémenter window_info pour Windows/macOS
2. Créer l'API serveur d'upload
3. Tester sur les 3 OS
4. Créer les installeurs
5. Déployer en beta chez 2-3 formateurs pilotes

Besoin d'aide pour implémenter ces améliorations? Je peux t'aider à coder les parties manquantes! 🚀