# Orchestrateur - Boucle Cognitive RPA Vision V2

## Vue d'ensemble

L'orchestrateur est le composant central de RPA Vision V2 qui implémente la boucle cognitive principale suivant le paradigme **Observer → Réfléchir → Agir → Apprendre**.

## Architecture

```
┌─────────────────────────────────────────────────┐
│           BOUCLE COGNITIVE PRINCIPALE           │
│                                                 │
│  1. OBSERVER                                    │
│     ├─ Capturer l'écran (capture_screen)       │
│     └─ Détecter fenêtre active                 │
│                                                 │
│  2. RÉFLÉCHIR                                   │
│     ├─ Détecter éléments UI (VisionUtils)      │
│     └─ Raisonner sur l'action (LLMManager)     │
│                                                 │
│  3. AGIR                                        │
│     ├─ Mode Shadow: Observer uniquement        │
│     ├─ Mode Assisté: Suggérer + Valider        │
│     └─ Mode Autopilot: Exécuter                │
│                                                 │
│  4. APPRENDRE                                   │
│     └─ Mettre à jour LearningManager           │
└─────────────────────────────────────────────────┘
```

## Composants Intégrés

- **LearningManager**: Gestion de l'apprentissage et transitions de mode
- **VisionUtils**: Détection d'éléments UI avec OWL-v2/DINO/YOLO
- **LLMManager**: Raisonnement visuel avec Qwen 2.5-VL
- **Logger**: Journalisation chiffrée de toutes les actions
- **GUI**: Interface utilisateur (optionnel)

## Modes Opérationnels

### Mode Shadow (👀)
- Observe les actions utilisateur sans exécuter
- Enregistre les observations pour apprentissage
- Construit la mémoire visuelle

### Mode Assisté (🤝)
- Suggère des actions basées sur l'apprentissage
- Attend validation utilisateur (Entrée/Échap/Alt+C)
- Apprend des corrections

### Mode Autopilot (🤖)
- Exécute automatiquement les actions
- Vérifie la liste blanche avant exécution
- Rétrograde si confiance < 90%

## Sécurité

### Liste Blanche
- Vérifie que la fenêtre est autorisée avant toute action
- Bloque et journalise les violations
- Configurable dynamiquement

### Arrêt d'Urgence
- Ctrl+Pause (ou Ctrl+C) arrête immédiatement
- Journalise l'événement de sécurité
- Retour au mode Assisté

### Journalisation
- Toutes les actions sont loggées avec chiffrement AES-256
- Inclut: fenêtre, action, confiance, résultat
- Traçabilité complète pour audit

## Métriques de Performance

L'orchestrateur suit:
- **total_cycles**: Nombre de cycles de la boucle cognitive
- **avg_latency_ms**: Latence moyenne (cible: <400ms)
- **detections_count**: Nombre d'éléments détectés
- **actions_executed**: Actions exécutées en mode Autopilot
- **actions_suggested**: Actions suggérées en mode Assisté

## Utilisation

### Initialisation

```python
from geniusia2.core.orchestrator import Orchestrator
from geniusia2.core.learning_manager import LearningManager
from geniusia2.core.utils.vision_utils import VisionUtils
from geniusia2.core.llm_manager import LLMManager
from geniusia2.core.logger import Logger
from geniusia2.core.embeddings_manager import EmbeddingsManager
from geniusia2.core.config import get_config

# Initialiser les composants
config = get_config()
logger = Logger()
embeddings_manager = EmbeddingsManager()
learning_manager = LearningManager(embeddings_manager, logger, config)
vision_utils = VisionUtils(config)
llm_manager = LLMManager(logger=logger)

# Créer l'orchestrateur
orchestrator = Orchestrator(
    learning_manager=learning_manager,
    vision_utils=vision_utils,
    llm_manager=llm_manager,
    logger=logger,
    gui=None  # Ou votre instance GUI
)
```

### Démarrage

```python
# Configurer la liste blanche
orchestrator.add_to_whitelist("Dolibarr*")
orchestrator.add_to_whitelist("Firefox*")

# Définir l'intention actuelle
learning_manager.set_current_context({"intent": "cliquer sur valider"})

# Démarrer la boucle cognitive (dans un thread séparé)
import threading
cognitive_thread = threading.Thread(target=orchestrator.run)
cognitive_thread.start()

# Arrêter proprement
orchestrator.stop()
cognitive_thread.join()
```

### Gestion de la Liste Blanche

```python
# Ajouter une fenêtre
orchestrator.add_to_whitelist("MonApplication*")

# Retirer une fenêtre
orchestrator.remove_from_whitelist("MonApplication*")

# Obtenir la liste
whitelist = orchestrator.get_whitelist()

# Activer/désactiver l'application
orchestrator.set_whitelist_enforcement(True)
```

### Contrôle de la Boucle

```python
# Mettre en pause
orchestrator.pause()

# Reprendre
orchestrator.resume()

# Arrêter
orchestrator.stop()
```

### Consultation des Métriques

```python
# Obtenir les métriques
metrics = orchestrator.get_metrics()
print(f"Cycles: {metrics['total_cycles']}")
print(f"Latence moyenne: {metrics['avg_latency_ms']:.2f}ms")

# Obtenir le statut complet
status = orchestrator.get_status()
print(f"Mode: {status['mode']}")
print(f"Fenêtre actuelle: {status['current_window']}")
```

## Flux de Décision

```
Capture Contexte
      ↓
Détection UI (Vision)
      ↓
Raisonnement (LLM)
      ↓
Calcul Confiance
      ↓
┌─────────────────┐
│  Mode actuel?   │
└─────────────────┘
      ↓
   ┌──┴──┬──────┬──────┐
   │     │      │      │
Shadow Assist Auto  │
   │     │      │      │
   ↓     ↓      ↓      ↓
Observer Suggérer Vérifier Exécuter
         +        Liste
      Valider   Blanche
         ↓         ↓
    Apprendre  Apprendre
```

## Gestion des Erreurs

### Échec de Capture
- Log l'erreur
- Continue la boucle
- Réessaie au cycle suivant

### Échec de Détection
- Essaie les modèles de fallback (OWL-v2 → DINO → YOLO)
- Si tous échouent, log et continue

### Échec LLM
- Fallback vers sélection basée vision pure
- Continue avec confiance réduite

### Violation Liste Blanche
- Bloque l'action immédiatement
- Log événement de sécurité
- Notifie l'utilisateur

## Exigences Satisfaites

✓ 1.1, 1.2 - Capture d'écran et détection fenêtre  
✓ 2.1, 2.2, 2.3, 2.4, 2.5 - Modes et suggestions  
✓ 3.2, 3.3 - Exécution automatique et arrêt d'urgence  
✓ 5.3, 5.4 - Liste blanche et sécurité  
✓ 6.2, 6.3 - Notifications et alertes  

## Tests

Exécuter les tests basiques:
```bash
python3 test_orchestrator_simple.py
```

Pour tester avec tous les composants (nécessite PyTorch, etc.):
```bash
python3 -m geniusia2.core.orchestrator
```

## Notes d'Implémentation

- La boucle cognitive s'exécute dans un thread séparé
- Latence cible: <400ms par cycle
- Utilise des événements threading pour arrêt/pause propre
- Toutes les actions sont journalisées avec chiffrement
- Support multi-plateforme (Linux, Windows, macOS)

## Prochaines Étapes

1. Implémenter `input_utils.py` pour exécution réelle des actions
2. Implémenter `replay_async.py` pour rollback
3. Intégrer avec la GUI PyQt5
4. Ajouter le système de détection de changements UI
5. Implémenter les métriques avancées