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.

---

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.

Responsabilités de ConversationOrchestrator

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

États internes de l’orchestrateur

É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

Orchestrateur central du cycle conversationnel multimodal de Mirza.

Coordonne les evenements microphone, le VAD neuronal, la transcription ASR, le dialogue LLM, le filtrage temps reel bi-canal, la memoire RAG hybride, et la restitution vocale TTS non bloquante.

class mirza.pipeline.conversationOrchestrator.TurnModes(agentActive, thinking, reasoningBudget)

Bases : object

The execution modes that apply to a single conversational turn.

Agent mode and reflection mode are mutually exclusive by construction.

Paramètres:

• agentActive (bool)

• thinking (bool)

• reasoningBudget (int)

agentActive: bool

Whether the smolagents CodeAgent handles the turn.

thinking: bool

Whether the engine streams a chain of thought before answering.

reasoningBudget: int

Thought-token budget for this turn, always 0 outside reflection mode.

showsThinking()

Whether the HUD should display the THINKING state for this turn.

Type renvoyé:

bool

property streamsThoughtsUpFront: bool

Whether the stream starts inside a thought block, with no opening tag.

classmethod resolve(agentActive, thinkingEnabled, budget)

Build the modes for a turn from the raw engine flags.

Paramètres:

• agentActive (bool) – Whether agent mode is on.

• thinkingEnabled (bool) – The engine’s enableThinking flag.

• budget (int) – The engine’s reasoningBudget, in tokens.

Renvoie:

The resolved modes. Agent mode forces both other fields to 0.

Type renvoyé:

TurnModes

__init__(agentActive, thinking, reasoningBudget)

Paramètres:

• agentActive (bool)

• thinking (bool)

• reasoningBudget (int)

Type renvoyé:

None

class mirza.pipeline.conversationOrchestrator.TurnOutcome(agentText='', document=None, spoken='', ragContext=None)

Bases : object

What the agent branch produced during a turn.

Mutable by design: it is filled in progressively as the agent runs and the answer is arbitrated. An explicit holder keeps the surrounding code free of 'name' in locals() probing.

Paramètres:

• agentText (str)

• document (str | None)

• spoken (str)

• ragContext (str | None)

agentText: str = ''

The raw text returned by the agent, empty in direct (non-agent) mode.

document: str | None = None

The rich document diverted to the Docs panel, if any.

spoken: str = ''

The spoken synthesis, empty when the caller must fall back.

ragContext: str | None = None

The RAG memory context injected during this turn, if any.

__init__(agentText='', document=None, spoken='', ragContext=None)

Paramètres:

• agentText (str)

• document (str | None)

• spoken (str)

• ragContext (str | None)

Type renvoyé:

None

class mirza.pipeline.conversationOrchestrator.ConversationOrchestrator(config=None, sttEngine=None, llmEngine=None, ttsEngine=None, textOnly=False)

Bases : object

Orchestrateur backend principal du cycle conversationnel temps reel.

Gere l’ecoute vocale (VAD), la saisie textuelle directe, le streaming LLM et le TTS.

Paramètres:

• config (AppConfig | None)

• sttEngine (BaseStt | None)

• llmEngine (BaseLlm | None)

• ttsEngine (BaseTts | None)

• textOnly (bool)

__init__(config=None, sttEngine=None, llmEngine=None, ttsEngine=None, textOnly=False)

Initialise l’orchestrateur de conversation et ses sous-systemes.

Paramètres:

• config (AppConfig, optional) – Configuration globale, defaut: AppConfig().

• sttEngine (BaseStt, optional) – Moteur ASR injecte, sinon instancie via EngineFactory.

• llmEngine (BaseLlm, optional) – Moteur de langage injecte, sinon instancie via EngineFactory.

• ttsEngine (BaseTts, optional) – Moteur TTS injecte, sinon instancie via EngineFactory.

• textOnly (bool, optional) – Desactive STT et TTS pour un fonctionnement allonge en memoire, defaut: False.

currentState: str

sttEngine: BaseStt

activeProfileId: str

llmEngine: BaseLlm

ttsEngine: BaseTts

onStateChange: Callable[[str], None] | None

onAudioLevel: Callable[[float, float], None] | None

onTranscription: Callable[[str], None] | None

onTokenStream: Callable[[str], None] | None

onThoughtStream: Callable[[str], None] | None

onAssistantResponseComplete: Callable[[str], None] | None

onMetrics: Callable[[dict], None] | None

onSpeechAudioGenerated: Callable[[bytes, str | None], None] | None

onAgentDoc: Callable[[str], None] | None

onCodeGenerating: Callable[[bool], None] | None

onMemoryUpdated: Callable[[dict], None] | None

onActiveContextUpdated: Callable[[dict], None] | None

onLog: Callable[[str, str, str], None] | None

activeAssistantProfileId: str

thinkingFillerPhrases: tuple[str, ...]

agentManager: AgentManager | None

memoryStore: EpisodicMemoryStore | None

memoryRetrievalEnabled: bool

lastInjectedRagContext: str | None

sessionRagHistory: list[dict[str, Any]]

setMemoryRetrieval(enabled)

Active ou desactive le retrieval semantique RAG passif a chaque tour.

Paramètres:

enabled (bool) – True pour activer l’injection semantique automatique, False pour desactiver.

Renvoie:

Le statut de la memoire conversationnelle.

Type renvoyé:

dict

getMemoryStatus()

Renvoie le statut de la memoire conversationnelle RAG.

Renvoie:

L’etat d’activation, le nombre d’enregistrements et l’auto-archivage.

Type renvoyé:

dict

setAgentMode(enabled)

Active ou desactive le mode agentique CodeAgent.

Desactive aussi le mode reflexion (BrainBoost) des que l’agent est active.

Paramètres:

enabled (bool) – True pour activer l’agent smolagents, False pour le mode direct.

Renvoie:

Le statut actualise du gestionnaire d’agent.

Type renvoyé:

dict

toggleAgentTool(toolId, enabled=None)

Active ou desactive un outil specifique du mode agentique.

Paramètres:

• toolId (str) – Identifiant de l’outil cible.

• enabled (bool, optional) – Etat explicite souhaite ou None pour inverser.

Renvoie:

Le statut actualise du gestionnaire d’agent.

Type renvoyé:

dict

getAgentStatus()

Renvoie l’etat courant de l’agent et de ses outils.

Renvoie:

Statut detaille de l’agent et des outils.

Type renvoyé:

dict

setAudioDevices(micId=None, speakerId=None)

Modifie dynamiquement les peripheriques audio d’entree et de sortie.

Paramètres:

• micId (int, optional) – Identifiant du microphone souhaite.

• speakerId (int, optional) – Identifiant du haut-parleur souhaite.

Renvoie:

Peripheriques audio actuellement configures.

Type renvoyé:

dict

getAudioDevices()

Recupere la liste des peripheriques audio disponibles et les peripheriques actifs.

Renvoie:

Peripheriques audio disponibles et actifs.

Type renvoyé:

dict

loadModels()

Precharge les modeles en VRAM et effectue un warm-up initial.

Type renvoyé:

None

interrupt()

Interrompt immediatement la generation ou la lecture audio (barge-in).

Type renvoyé:

None

emergencyStop()

Arret d’urgence : tue le processus du modele.

L’interruption ordinaire arrete la consommation du flux, mais la generation continue cote serveur et la memoire reste occupee. Ici le processus est termine, ce qui coupe la generation la ou elle se fait et rend la memoire. Le moteur est marque decharge : la prochaine question le recharge normalement.

Renvoie:

L’etat obtenu, avec le nom du moteur arrete.

Type renvoyé:

dict

listModelProfiles()

Renvoie les profils de modele selectionnables.

Renvoie:

Un profil par entree du catalogue, marque actif pour celui en cours.

Type renvoyé:

list[dict]

getActiveModelProfileId()

Identifie le profil correspondant au modele actuellement charge.

Renvoie:

L’identifiant du profil, ou None si le modele charge n’est pas du catalogue.

Type renvoyé:

str | None

switchModel(profileId)

Bascule vers un autre profil de modele.

Pour les modeles locaux, la memoire est liberee avant de charger le nouveau modele afin de ne jamais conserver deux modeles lourds en VRAM. Pour le modele distant (OpenRouter), le modele local reste conserve en RAM pour permettre un basculement instantane sans rechargement.

Paramètres:

profileId (str) – Identifiant du profil cible.

Renvoie:

L’etat des moteurs apres bascule, avec "error" en cas d’echec. La bascule est refusee si une generation est en cours.

Type renvoyé:

dict

listAssistantProfiles()

Liste l’ensemble des profils d’assistant configurés.

Renvoie:

Description de chaque profil d’assistant.

Type renvoyé:

list[dict[str, Any]]

getActiveAssistantProfileId()

Retourne l’identifiant du profil d’assistant actuellement actif.

Renvoie:

Identifiant du profil (ex: « assistant », « medical »).

Type renvoyé:

str

switchAssistantProfile(profileId)

Bascule a chaud vers un autre profil d’assistant (ex: assistant, medical).

Met a jour le prompt systeme, les prompts et outils de l’agent, les phrases d’attente vocale et la base de donnees memoire.

Paramètres:

profileId (str) – Identifiant du profil cible.

Renvoie:

Resultat de la bascule.

Type renvoyé:

dict[str, Any]

getEngineStatus()

Renvoie l’etat de chargement de chaque moteur.

Renvoie:

Les cles llmLoaded, sttLoaded, ttsLoaded, allLoaded et anyLoading.

Type renvoyé:

dict

setEngineLoaded(loaded)

Decharge ou recharge l’integralite des modeles a la volee.

Toute requete est refusee pendant une generation : decharger les poids sous un flux de tokens en cours produirait une panne segfault.

Paramètres:

loaded (bool) – True pour recharger, False pour tout decharger.

Renvoie:

L’etat des moteurs apres l’operation, avec "error" en cas d’echec.

Type renvoyé:

dict

processClientAudio(audioBytes, clientTargetId=None)

Traite un flux audio envoye directement par un client distant.

Paramètres:

• audioBytes (bytes) – Octets binaires bruts de l’enregistrement audio au format WAV ou PCM.

• clientTargetId (str, optional) – Identifiant unique du client WebSocket demandeur.

Renvoie:

True si la transcription et la synthese vocale ont abouti, False sinon.

Type renvoyé:

bool

processTextInput(textInput, clientTargetId=None)

Traite directement une invite textuelle sans capture microphonique.

Paramètres:

• textInput (str) – Texte de la question ou commande soumise par l’utilisateur.

• clientTargetId (str, optional) – Identifiant du client WebSocket cible.

Renvoie:

True si la reponse a ete generee avec succes, False si l’entree est vide.

Type renvoyé:

bool

processSingleTurn()

Execute un tour conversationnel complet : VAD, STT, streaming LLM, TTS.

Renvoie:

True si le tour a abouti, False si aucun signal vocal n’a ete detecte.

Type renvoyé:

bool

startSession(maxTurns=10)

Demarre la boucle de conversation interactive.

Paramètres:

maxTurns (int, optional) – Nombre maximal de tours de conversation (defaut: 10).

Type renvoyé:

None

resetConversation()

Reinitialise l’historique, vide le cache KV et purge la memoire Metal.

Type renvoyé:

None

setThinkingMode(enabled)

Active ou desactive le mode reflexion au niveau du moteur LLM.

Paramètres:

enabled (bool) – True pour activer BrainBoost (CoT), False pour desactiver.

Type renvoyé:

None

setReasoningBudget(budget)

Definit a chaud le budget de tokens alloue a la reflexion.

Paramètres:

budget (int) – Nombre de tokens alloues au raisonnement interne (0 a 2048).

Type renvoyé:

None

getActiveContextInfo()

Extrait et synthetise l’etat du contexte actif charge en memoire vive (KV).

Renvoie:

Decompte des tokens par section, occupation du cache KV et historique.

Type renvoyé:

dict

listMemories(query=None, limit=50, offset=0)

Interroge la memoire episodique SQLite et retourne la liste des souvenirs.

Paramètres:

• query (str | None, optional) – Terme textuel a rechercher dans les souvenirs, defaut: None.

• limit (int, optional) – Nombre maximum d’elements retournes, defaut: 50.

• offset (int, optional) – Index de pagination, defaut: 0.

Renvoie:

Les dictionnaires de souvenirs trouves.

Type renvoyé:

list[dict]

deleteMemory(memoryId)

Supprime un souvenir de la base SQLite et retourne le statut.

Paramètres:

memoryId (int) – Identifiant numerique du souvenir a effacer.

Renvoie:

True si le souvenir a ete supprime, False sinon.

Type renvoyé:

bool

ingestConsultationNote(rawText)

Reformule une note brute ou une dictée de consultation médicale au format standardisé de la patientèle, puis l’injecte dans la base de données épisodique. N’utilise aucun TTS et n’émet aucun flux vocal.

Paramètres:

rawText (str) – Observations orales ou notes brutes saisies par le médecin.

Renvoie:

Détails de la consultation insérée (success, memoryId, formattedNote, docId, etc.).

Type renvoyé:

dict[str, Any]

shutdown()

Arrete l’orchestrateur et libere les ressources allouees.

Type renvoyé:

None