From 752ac537d4e44830432b0f11d49782730d1c1f18 Mon Sep 17 00:00:00 2001
From: Dom <dom@rpa-vision-v3.local>
Date: Thu, 15 Jan 2026 01:36:52 +0100
Subject: [PATCH] Docs: Vision agent conversationnel RPA
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Architecture et plan d'implémentation pour piloter
le système RPA par langage naturel.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 AGENT_CONVERSATIONNEL_VISION.md | 648 ++++++++++++++++++++++++++++++++
 1 file changed, 648 insertions(+)
 create mode 100644 AGENT_CONVERSATIONNEL_VISION.md

diff --git a/AGENT_CONVERSATIONNEL_VISION.md b/AGENT_CONVERSATIONNEL_VISION.md
new file mode 100644
index 000000000..a63dad087
--- /dev/null
+++ b/AGENT_CONVERSATIONNEL_VISION.md
@@ -0,0 +1,648 @@
+# AGENT CONVERSATIONNEL RPA VISION V3
+## Vision & Architecture
+
+**Date**: 14 janvier 2026
+**Statut**: Document de conception
+**Objectif**: Piloter le système RPA par langage naturel
+
+---
+
+## 1. CONCEPT
+
+Permettre aux utilisateurs de commander le système RPA en langage naturel :
+
+```
+👤 "Envoie les factures impayées de plus de 30 jours aux clients concernés"
+
+🤖 Agent → Comprend l'intention
+        → Trouve les workflows pertinents
+        → Extrait les paramètres (30 jours)
+        → Demande confirmation
+        → Exécute et rapporte le résultat
+```
+
+---
+
+## 2. CE QUI EXISTE DÉJÀ
+
+### 2.1 Interface de Commande
+
+| Composant | Fichier | Description |
+|-----------|---------|-------------|
+| **Command Interface** | `command_interface/app.py` | Interface web style Spotlight avec WebSocket |
+| **CLI** | `cli.py` | Ligne de commande (status, record, play, list) |
+| **Agent Tray** | `agent_v0/tray_ui.py` | Application système tray |
+
+### 2.2 Matching Sémantique (DÉJÀ IMPLÉMENTÉ)
+
+**Fichier**: `core/workflow/semantic_matcher.py`
+
+```python
+class SemanticMatcher:
+    def find_workflow(self, user_query: str) -> WorkflowMatch:
+        """
+        Trouve le workflow correspondant à une requête naturelle.
+
+        Retourne:
+        - workflow_id, workflow_name
+        - confidence score
+        - extracted_params (paramètres extraits de la phrase)
+        - match_reason
+        """
+```
+
+**Fonctionnalités**:
+- Matching par embeddings sémantiques
+- Matching par mots-clés et tags
+- Extraction automatique de paramètres
+- Support multi-langue (FR/EN)
+
+**Exemple**:
+```python
+matcher = SemanticMatcher("data/workflows")
+result = matcher.find_workflow("facturer le client Acme")
+# → workflow: "facturation_client"
+# → params: {client: "Acme"}
+# → confidence: 0.87
+```
+
+### 2.3 Intégration LLM/Ollama (DÉJÀ IMPLÉMENTÉ)
+
+**Fichier**: `core/gpu/ollama_manager.py`
+
+```python
+class OllamaManager:
+    def __init__(self, model="qwen3-vl:8b"):
+        self.endpoint = "http://localhost:11434"
+
+    def load_model(self) -> bool
+    def unload_model(self) -> bool
+    def is_available() -> bool
+```
+
+### 2.4 Exécution de Workflows (DÉJÀ IMPLÉMENTÉ)
+
+| Composant | Fichier | Rôle |
+|-----------|---------|------|
+| **ActionExecutor** | `core/execution/action_executor.py` | Exécute les actions individuelles |
+| **WorkflowChainer** | `core/workflow/workflow_chainer.py` | Chaîne plusieurs workflows |
+| **WorkflowPipeline** | `core/pipeline/workflow_pipeline.py` | Orchestration complète |
+
+### 2.5 Composition Avancée (DÉJÀ IMPLÉMENTÉ)
+
+**Fichier**: `core/workflow/composition_models.py`
+
+- `ChainConfig` : Chaînage de workflows
+- `LoopConfig` : Boucles paramétrées
+- `BranchConfig` : Branchements conditionnels
+- `TriggerConfig` : Déclencheurs programmés
+- `ExecutionContext` : Contexte d'exécution
+
+### 2.6 API REST (DÉJÀ IMPLÉMENTÉ)
+
+**Fichier**: `server/api_core.py`
+
+```
+POST /api/core/capture    → Capture d'écran
+POST /api/core/detect     → Détection UI
+POST /api/core/embed      → Génération embeddings
+POST /api/core/match      → Matching d'écran
+```
+
+---
+
+## 3. ARCHITECTURE CIBLE
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     INTERFACES UTILISATEUR                       │
+├─────────────┬─────────────┬─────────────┬─────────────┬─────────┤
+│  Chat Web   │    CLI      │   Vocal     │  API REST   │  Tray   │
+│  (React)    │  (existant) │  (Whisper)  │  (existant) │(existant│
+└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴────┬────┘
+       │             │             │             │           │
+       └─────────────┴─────────────┴─────────────┴───────────┘
+                                   │
+                                   ▼
+       ┌───────────────────────────────────────────────────────┐
+       │              AGENT CONVERSATIONNEL                     │
+       │                                                        │
+       │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
+       │  │   Intent     │  │   Workflow   │  │  Parameter   │ │
+       │  │   Parser     │  │   Matcher    │  │  Extractor   │ │
+       │  │   (LLM)      │  │  (existant)  │  │  (existant)  │ │
+       │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
+       │         │                 │                 │          │
+       │         └─────────────────┼─────────────────┘          │
+       │                           │                            │
+       │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
+       │  │ Confirmation │  │   Context    │  │   Response   │ │
+       │  │    Loop      │  │   Manager    │  │  Generator   │ │
+       │  │   (à faire)  │  │  (existant)  │  │    (LLM)     │ │
+       │  └──────────────┘  └──────────────┘  └──────────────┘ │
+       │                                                        │
+       └────────────────────────┬───────────────────────────────┘
+                                │
+                                ▼
+       ┌───────────────────────────────────────────────────────┐
+       │                 MOTEUR D'EXÉCUTION                     │
+       │                    (existant)                          │
+       │                                                        │
+       │  ActionExecutor ← WorkflowChainer ← WorkflowPipeline  │
+       │                                                        │
+       └───────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. COMPOSANTS À DÉVELOPPER
+
+### 4.1 Intent Parser (NOUVEAU)
+
+**Objectif**: Comprendre l'intention de l'utilisateur via LLM
+
+```python
+class IntentParser:
+    def __init__(self, ollama: OllamaManager):
+        self.ollama = ollama
+
+    def parse(self, user_input: str) -> Intent:
+        """
+        Analyse l'entrée utilisateur et retourne l'intention.
+
+        Intents possibles:
+        - EXECUTE_WORKFLOW: Exécuter un workflow existant
+        - LIST_WORKFLOWS: Lister les workflows disponibles
+        - GET_STATUS: Obtenir le statut d'une exécution
+        - SCHEDULE_WORKFLOW: Planifier une exécution
+        - CHAIN_WORKFLOWS: Enchaîner plusieurs workflows
+        - HELP: Demander de l'aide
+        - CANCEL: Annuler une action en cours
+        """
+
+        prompt = f"""
+        Analyse cette demande utilisateur et identifie l'intention.
+
+        Demande: "{user_input}"
+
+        Réponds en JSON:
+        {{
+            "intent": "EXECUTE_WORKFLOW|LIST_WORKFLOWS|...",
+            "confidence": 0.0-1.0,
+            "entities": {{...}}
+        }}
+        """
+
+        response = self.ollama.generate(prompt)
+        return Intent.from_json(response)
+```
+
+### 4.2 Confirmation Loop (NOUVEAU)
+
+**Objectif**: Demander confirmation avant actions critiques
+
+```python
+class ConfirmationLoop:
+    def __init__(self):
+        self.critical_actions = ["delete", "send", "execute", "modify"]
+
+    def needs_confirmation(self, workflow: Workflow, params: dict) -> bool:
+        """Détermine si une confirmation est nécessaire."""
+        # Actions critiques
+        if any(action in workflow.name.lower() for action in self.critical_actions):
+            return True
+        # Beaucoup d'éléments impactés
+        if params.get("count", 0) > 10:
+            return True
+        return False
+
+    def generate_confirmation_message(self, workflow: Workflow, params: dict) -> str:
+        """Génère le message de confirmation."""
+        return f"""
+        Je vais exécuter "{workflow.name}":
+        - Paramètres: {params}
+        - Éléments impactés: {params.get('count', 'inconnu')}
+
+        Confirmes-tu ? (oui/non)
+        """
+```
+
+### 4.3 Response Generator (NOUVEAU)
+
+**Objectif**: Générer des réponses naturelles
+
+```python
+class ResponseGenerator:
+    def __init__(self, ollama: OllamaManager):
+        self.ollama = ollama
+
+    def generate(self, execution_result: ExecutionResult, context: dict) -> str:
+        """Génère une réponse naturelle à partir du résultat."""
+
+        if execution_result.status == "SUCCESS":
+            return self._success_response(execution_result)
+        elif execution_result.status == "FAILED":
+            return self._error_response(execution_result)
+        else:
+            return self._pending_response(execution_result)
+
+    def _success_response(self, result: ExecutionResult) -> str:
+        # Utiliser le LLM pour générer une réponse naturelle
+        prompt = f"""
+        Génère une réponse courte et naturelle pour ce résultat:
+        - Action: {result.action}
+        - Statut: Succès
+        - Détails: {result.details}
+
+        Exemple: "C'est fait ! 23 factures ont été envoyées."
+        """
+        return self.ollama.generate(prompt)
+```
+
+### 4.4 Conversation Manager (NOUVEAU)
+
+**Objectif**: Gérer le contexte de conversation multi-tours
+
+```python
+class ConversationManager:
+    def __init__(self):
+        self.history: List[Message] = []
+        self.context: dict = {}
+        self.pending_confirmation: Optional[PendingAction] = None
+
+    def add_message(self, role: str, content: str):
+        self.history.append(Message(role=role, content=content, timestamp=now()))
+
+    def get_context_for_llm(self) -> str:
+        """Retourne le contexte pour le LLM."""
+        recent = self.history[-10:]  # 10 derniers messages
+        return "\n".join([f"{m.role}: {m.content}" for m in recent])
+
+    def set_pending_confirmation(self, action: PendingAction):
+        self.pending_confirmation = action
+
+    def handle_confirmation_response(self, response: str) -> Optional[PendingAction]:
+        if response.lower() in ["oui", "yes", "ok", "confirme"]:
+            action = self.pending_confirmation
+            self.pending_confirmation = None
+            return action
+        elif response.lower() in ["non", "no", "annule", "cancel"]:
+            self.pending_confirmation = None
+            return None
+```
+
+---
+
+## 5. FLUX DE CONVERSATION
+
+### 5.1 Flux Standard
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                 │
+│  USER INPUT                                                     │
+│      │                                                          │
+│      ▼                                                          │
+│  ┌─────────────────┐                                            │
+│  │  Intent Parser  │ ──── "Quelle est l'intention ?"            │
+│  └────────┬────────┘                                            │
+│           │                                                     │
+│           ▼                                                     │
+│  ┌─────────────────┐                                            │
+│  │ Workflow Matcher│ ──── "Quel workflow correspond ?"          │
+│  └────────┬────────┘                                            │
+│           │                                                     │
+│           ▼                                                     │
+│  ┌─────────────────┐                                            │
+│  │Param Extractor  │ ──── "Quels paramètres ?"                  │
+│  └────────┬────────┘                                            │
+│           │                                                     │
+│           ▼                                                     │
+│  ┌─────────────────┐      ┌─────────────────┐                   │
+│  │ Needs Confirm?  │──YES─▶│   Ask User     │                   │
+│  └────────┬────────┘      └────────┬────────┘                   │
+│           │ NO                     │                            │
+│           ▼                        ▼                            │
+│  ┌─────────────────┐      ┌─────────────────┐                   │
+│  │    Execute      │◀─────│  User Confirms  │                   │
+│  └────────┬────────┘      └─────────────────┘                   │
+│           │                                                     │
+│           ▼                                                     │
+│  ┌─────────────────┐                                            │
+│  │Response Generate│ ──── "Générer réponse naturelle"           │
+│  └────────┬────────┘                                            │
+│           │                                                     │
+│           ▼                                                     │
+│      USER OUTPUT                                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 Exemple de Conversation
+
+```
+👤 User: "Facture les clients du secteur santé"
+
+🤖 Agent:
+   [IntentParser] → Intent: EXECUTE_WORKFLOW
+   [WorkflowMatcher] → Match: "facturation_client" (confidence: 0.92)
+   [ParamExtractor] → Params: {secteur: "santé"}
+   [ConfirmationLoop] → Needs confirmation: YES (action critique)
+
+🤖 Agent: "J'ai trouvé le workflow 'Facturation Client'.
+          Je vais facturer tous les clients du secteur Santé.
+          3 clients concernés. Je lance ?"
+
+👤 User: "Oui vas-y"
+
+🤖 Agent:
+   [ConversationManager] → Confirmation reçue
+   [ActionExecutor] → Execute workflow
+   [ResponseGenerator] → Generate response
+
+🤖 Agent: "C'est fait ! 3 factures générées :
+          - Hôpital Saint-Louis : 12,450€
+          - Clinique du Parc : 8,200€
+          - Labo Médical Plus : 3,100€
+          Total : 23,750€"
+```
+
+---
+
+## 6. INTÉGRATION AVEC L'EXISTANT
+
+### 6.1 Points d'Intégration
+
+| Nouveau Composant | S'intègre avec | Comment |
+|-------------------|----------------|---------|
+| IntentParser | OllamaManager | Utilise le LLM pour parser |
+| ConversationManager | SemanticMatcher | Passe la query au matcher |
+| ConfirmationLoop | WorkflowChainer | Intercepte avant exécution |
+| ResponseGenerator | ExecutionResult | Transforme résultat en texte |
+
+### 6.2 Fichiers à Créer
+
+```
+core/
+└── agent/
+    ├── __init__.py
+    ├── intent_parser.py        # Nouveau
+    ├── confirmation_loop.py    # Nouveau
+    ├── response_generator.py   # Nouveau
+    ├── conversation_manager.py # Nouveau
+    └── conversational_agent.py # Nouveau (orchestrateur)
+```
+
+### 6.3 Classe Principale
+
+```python
+# core/agent/conversational_agent.py
+
+class ConversationalAgent:
+    """Agent conversationnel pour piloter RPA Vision."""
+
+    def __init__(self):
+        # Composants existants
+        self.ollama = OllamaManager()
+        self.matcher = SemanticMatcher("data/workflows")
+        self.executor = ActionExecutor()
+        self.chainer = WorkflowChainer()
+
+        # Nouveaux composants
+        self.intent_parser = IntentParser(self.ollama)
+        self.confirmation = ConfirmationLoop()
+        self.response_gen = ResponseGenerator(self.ollama)
+        self.conversation = ConversationManager()
+
+    async def process_message(self, user_input: str) -> str:
+        """Traite un message utilisateur et retourne la réponse."""
+
+        # 1. Ajouter au contexte
+        self.conversation.add_message("user", user_input)
+
+        # 2. Vérifier si c'est une réponse à une confirmation
+        if self.conversation.pending_confirmation:
+            return await self._handle_confirmation(user_input)
+
+        # 3. Parser l'intention
+        intent = self.intent_parser.parse(user_input)
+
+        # 4. Router selon l'intention
+        if intent.type == "EXECUTE_WORKFLOW":
+            return await self._handle_execute(intent)
+        elif intent.type == "LIST_WORKFLOWS":
+            return await self._handle_list()
+        elif intent.type == "HELP":
+            return self._handle_help()
+        else:
+            return "Je n'ai pas compris. Peux-tu reformuler ?"
+
+    async def _handle_execute(self, intent: Intent) -> str:
+        # Trouver le workflow
+        match = self.matcher.find_workflow(intent.query)
+
+        if match.confidence < 0.5:
+            return f"Je n'ai pas trouvé de workflow correspondant à '{intent.query}'"
+
+        # Vérifier si confirmation nécessaire
+        if self.confirmation.needs_confirmation(match.workflow, match.params):
+            self.conversation.set_pending_confirmation(
+                PendingAction(workflow=match.workflow, params=match.params)
+            )
+            return self.confirmation.generate_confirmation_message(
+                match.workflow, match.params
+            )
+
+        # Exécuter directement
+        result = await self.executor.execute(match.workflow, match.params)
+        return self.response_gen.generate(result)
+```
+
+---
+
+## 7. INTERFACES UTILISATEUR
+
+### 7.1 Chat Web (Extension de command_interface)
+
+```javascript
+// Extension de command_interface/static/app.js
+
+const ChatInterface = {
+    async sendMessage(text) {
+        const response = await fetch('/api/agent/chat', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({message: text})
+        });
+        return response.json();
+    },
+
+    displayMessage(role, content) {
+        const bubble = document.createElement('div');
+        bubble.className = `message ${role}`;
+        bubble.textContent = content;
+        chatContainer.appendChild(bubble);
+    }
+};
+```
+
+### 7.2 CLI Conversationnel
+
+```python
+# Extension de cli.py
+
+@click.command()
+def chat():
+    """Mode conversation avec l'agent."""
+    agent = ConversationalAgent()
+
+    print("🤖 Agent RPA Vision prêt. Tapez 'quit' pour quitter.")
+
+    while True:
+        user_input = input("\n👤 Vous: ")
+
+        if user_input.lower() in ['quit', 'exit', 'q']:
+            print("👋 Au revoir !")
+            break
+
+        response = asyncio.run(agent.process_message(user_input))
+        print(f"\n🤖 Agent: {response}")
+```
+
+### 7.3 API REST
+
+```python
+# Nouveaux endpoints dans server/api_core.py
+
+@app.route('/api/agent/chat', methods=['POST'])
+def agent_chat():
+    """Endpoint pour conversation avec l'agent."""
+    data = request.json
+    message = data.get('message', '')
+    session_id = data.get('session_id', 'default')
+
+    # Récupérer ou créer l'agent pour cette session
+    agent = get_or_create_agent(session_id)
+
+    # Traiter le message
+    response = asyncio.run(agent.process_message(message))
+
+    return jsonify({
+        'response': response,
+        'session_id': session_id
+    })
+```
+
+---
+
+## 8. FONCTIONNALITÉS AVANCÉES (FUTUR)
+
+### 8.1 Apprentissage des Habitudes
+
+```python
+class HabitLearner:
+    """Apprend les habitudes de l'utilisateur."""
+
+    def analyze_patterns(self) -> List[Suggestion]:
+        """Analyse l'historique et suggère des automatisations."""
+        # "Tous les lundis à 9h tu lances le rapport RH"
+        # → Suggérer de planifier automatiquement
+```
+
+### 8.2 Composition Intelligente
+
+```python
+class WorkflowComposer:
+    """Compose des workflows à partir d'objectifs."""
+
+    def compose_from_goal(self, goal: str) -> List[Workflow]:
+        """
+        Décompose un objectif en séquence de workflows.
+
+        Exemple:
+        "Assure-toi que tous les clients sont facturés"
+        → 1. Lister clients non facturés
+        → 2. Générer factures
+        → 3. Envoyer par email
+        → 4. Mettre à jour le CRM
+        """
+```
+
+### 8.3 Mode Vocal
+
+```python
+class VoiceInterface:
+    """Interface vocale avec Whisper."""
+
+    def listen(self) -> str:
+        """Écoute et transcrit."""
+        audio = self.record_audio()
+        return whisper.transcribe(audio)
+
+    def speak(self, text: str):
+        """Synthèse vocale."""
+        tts.speak(text)
+```
+
+---
+
+## 9. PLAN D'IMPLÉMENTATION
+
+### Phase 1 : MVP Conversationnel (1-2 semaines)
+
+- [ ] Créer `core/agent/` structure
+- [ ] Implémenter `IntentParser` basique
+- [ ] Implémenter `ConversationManager`
+- [ ] Connecter avec `SemanticMatcher` existant
+- [ ] Ajouter endpoint `/api/agent/chat`
+- [ ] Tester avec CLI
+
+### Phase 2 : Confirmation & Réponses (1 semaine)
+
+- [ ] Implémenter `ConfirmationLoop`
+- [ ] Implémenter `ResponseGenerator`
+- [ ] Intégrer avec `WorkflowChainer`
+- [ ] Tests end-to-end
+
+### Phase 3 : Interface Chat Web (1 semaine)
+
+- [ ] Étendre `command_interface` avec chat
+- [ ] UI React pour conversation
+- [ ] Historique des conversations
+- [ ] WebSocket pour temps réel
+
+### Phase 4 : Fonctionnalités Avancées (2-3 semaines)
+
+- [ ] Apprentissage des habitudes
+- [ ] Composition intelligente
+- [ ] Mode vocal (optionnel)
+- [ ] Multi-utilisateurs
+
+---
+
+## 10. MÉTRIQUES DE SUCCÈS
+
+| Métrique | Objectif | Mesure |
+|----------|----------|--------|
+| Taux de compréhension | >90% | Intents correctement parsés |
+| Taux de matching | >85% | Workflows correctement trouvés |
+| Temps de réponse | <2s | Latence moyenne |
+| Satisfaction utilisateur | >4/5 | Feedback utilisateurs |
+| Taux d'exécution réussie | >95% | Workflows exécutés sans erreur |
+
+---
+
+## CONCLUSION
+
+L'agent conversationnel est une extension naturelle du système RPA Vision V3. Grâce aux composants déjà implémentés (SemanticMatcher, OllamaManager, ActionExecutor), le développement peut se concentrer sur :
+
+1. **Intent Parser** : Comprendre les intentions
+2. **Confirmation Loop** : Sécuriser les actions critiques
+3. **Response Generator** : Réponses naturelles
+4. **Conversation Manager** : Contexte multi-tours
+
+**Estimation totale** : 4-6 semaines pour un MVP fonctionnel.
+
+---
+
+*Document de conception - À implémenter après les démos*