.. _api-pipeline:

Module Pipeline (``mirza.pipeline``)
======================================

Le module ``mirza.pipeline`` contient l'orchestrateur central de la plateforme :
``ConversationOrchestrator``, qui coordonne l'ensemble des sous-systèmes de capture,
transcription, génération et synthèse vocale.

.. contents:: Sommaire
   :local:
   :depth: 1

----

Rôle de l'Orchestrateur
------------------------

.. important::

   ``ConversationOrchestrator`` est le **chef d'orchestre** de Mirza.
   Il tourne dans le thread principal du processus Python et délègue les tâches
   intensives (inférence LLM, TTS) dans des threads ou coroutines séparés.

.. list-table:: Responsabilités de ConversationOrchestrator
   :widths: 40 60
   :header-rows: 1

   * - Responsabilité
     - Détail
   * - **Gestion du cycle conversationnel**
     - Maintient ``conversationHistory`` (jusqu'à ``historyMaxTurns`` tours)
   * - **Coordination VAD → ASR**
     - Collecte les chunks PCM validés par VAD et lance l'ASR
   * - **Routage de mode**
     - Décide direct / CoT / agent selon les paramètres ``enableThinking`` et ``agentEnabled``
   * - **Filtrage streaming temps réel**
     - Instancie et pilote ``StreamingTextFilter`` token par token
   * - **Gating acoustique**
     - Positionne ``isGenerating`` pour bloquer le micro pendant la synthèse
   * - **Métriques TTFT / tok/s**
     - Calcule et émet les métriques via ``EventBroadcaster.broadcastEvent``

----

Gestion de l'État de Conversation
-----------------------------------

.. list-table:: États internes de l'orchestrateur
   :widths: 20 80
   :header-rows: 1

   * - État
     - Description
   * - ``IDLE``
     - Aucune activité — le réacteur HUD est en veille
   * - ``LISTENING``
     - VAD détecte de la parole — capture PCM active
   * - ``PROCESSING``
     - ASR en cours ou LLM en génération
   * - ``SPEAKING``
     - TTS en streaming — microphone muté (gating)
   * - ``AGENT``
     - Mode agentique ReAct actif — cycle outil en cours

----

Référence API
--------------

.. automodule:: mirza.pipeline.conversationOrchestrator
   :members:
   :undoc-members:
   :show-inheritance: