rpa_vision_v3/AGENT_CONVERSATIONNEL_VISION.md

# 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*