Module Moteurs et Inférence (mirza.engine)

Le module mirza.engine regroupe toutes les abstractions et implémentations des moteurs d’inférence IA : transcription (STT), génération de texte (LLM) et synthèse vocale (TTS), ainsi que le module agentique complet.

---

Comparatif des Moteurs Disponibles

Moteurs STT

Moteur	Type	Caractéristiques
MlxNemotronStt	STT Principal	Prioritaire — streaming temps réel, latence < 200 ms, optimisé ANE
MlxWhisperStt	STT Alternatif	Fallback — robustesse multilingue, transcription hors-ligne

Moteurs LLM

Moteur	Type	Caractéristiques
MtplxLlm	LLM Local Turbo	Runtime haute vitesse, Paged Attention GPU Metal, décodage spéculatif intégré (28–39 tok/s, TTFT ~115–450 ms)
OpenRouterLlm	LLM Distant	Routeur API distant haute capacité (switch instantané avec conservation du modèle local en mémoire)
MlxQwenLlm	LLM Local MLX	Inférence MLX locale avec décodage spéculatif + APC et pré-amorçage exact

Moteurs TTS

Moteur	Backend	Caractéristiques
KokoroTts	TTS Local	Moteur vocal par défaut — 100% local, souverain et hors-ligne
EdgeTts	TTS Distant	Repli cloud optionnel — haute fidélité vocale
MeloTts	TTS Alternatif	Synthèse locale alternative optimisée

---

Fabrique Centrale (EngineFactory)

Fabrique centrale d’instanciation des moteurs d’inference de Mirza.

Fournit une couche d’abstraction unifiee pour creer les moteurs STT, LLM et TTS.

class mirza.engine.factory.EngineFactory

Bases : object

Fabrique centrale des moteurs d’inference STT, LLM et TTS.

Centralise la selection des backends selon la configuration materielle et logicielle injectee.

static createSttEngine(provider='whisper', modelRepo='mlx-community/whisper-large-v3-turbo-q4')

Instancie le moteur de transcription vocale (STT / Speech-to-Text).

Supporte Whisper Turbo MLX et Nemotron 3.5 8-bit.

Paramètres:

• provider (str, optional) – Nom du fournisseur (“whisper”, “mlx”, “nemotron”). Defaut : « whisper ».

• modelRepo (str, optional) – Depot HuggingFace ou chemin local du modele quantifie. Defaut : « mlx-community/whisper-large-v3-turbo-q4 ».

Renvoie:

Instance du moteur de transcription conforme au contrat BaseStt.

Type renvoyé:

BaseStt

Lève:

ValueError – Si le fournisseur specifie n’est pas reconnu.

static createLlmEngine(modelConfig, provider='mlx')

Instancie le moteur de generation de langage (LLM / Large Language Model).

Charge Qwen 3.5 9B, Qwen 3.8 Distill MTPLX, ou une conversion OptiQ, avec acceleration Multi-Token Prediction et gestion de cache.

Paramètres:

• modelConfig (LlmConfig) – Configuration complete des hyperparametres LLM et Metal.

• provider (str, optional) – Nom du backend d’execution (“mlx”, “mtplx”, “mlxlm” ou “optiq”). Defaut : « mlx ».

Renvoie:

Instance du moteur de langage conforme au contrat BaseLlm.

Type renvoyé:

BaseLlm

Lève:

ValueError – Si le fournisseur specifie n’est pas reconnu.

static createTtsEngine(ttsConfig, provider='edge_tts')

Instancie le moteur de synthese vocale (TTS / Text-to-Speech).

Permet d’alterner entre Edge-TTS Neural (cloud) et Kokoro ONNX ou MeloTTS (synthese locale, autonome et hors-ligne).

Paramètres:

• ttsConfig (TtsConfig) – Configuration acoustique (voix, vitesse, hauteur, decoupe de clauses).

• provider (str, optional) – Fournisseur de synthese (“edge_tts”, “kokoro” ou “melo”). Defaut : « edge_tts ».

Renvoie:

Instance du moteur conforme au contrat BaseTts.

Type renvoyé:

BaseTts

Lève:

ValueError – Si le fournisseur TTS n’est pas reconnu.

---

Interfaces Abstraites

Contrat d’interface abstraite pour les moteurs de transcription vocale (STT / ASR).

class mirza.engine.interfaces.baseStt.BaseStt

Bases : ABC

Interface abstraite pour les moteurs STT (Speech-to-Text) locaux.

Definit les operations de pre-chauffage et de transcription des signaux audio.

abstractmethod warmUp()

Pre-chauffe le moteur STT pour eliminer la latence du premier appel.

Type renvoyé:

None

abstractmethod transcribe(audioArray, language='fr', initialPrompt='Bonjour Mirza.')

Transcrit un tableau d’echantillons audio 16kHz en texte.

Paramètres:

• audioArray (np.ndarray) – Echantillons audio monocanal a 16000 Hz au format float32.

• language (str, optional) – Code langue ISO (defaut: « fr »).

• initialPrompt (str, optional) – Prompt initial pour conditionner le contexte acoustique (defaut: « Bonjour Mirza. »).

Renvoie:

Texte transcrit nettoye.

Type renvoyé:

str

unload()

Libere le modele en memoire.

Par defaut sans effet : un moteur qui ne detient aucun poids local (synthese cloud) n’a rien a liberer.

Type renvoyé:

None

property isLoaded: bool

Indique si des poids resident actuellement en memoire.

Vrai par defaut : un moteur sans etat local (synthese cloud) n’a rien a charger.

Contrat d’interface abstraite pour les moteurs de generation de texte (LLM).

class mirza.engine.interfaces.baseLlm.BaseLlm

Bases : ABC

Interface abstraite pour les moteurs LLM locaux.

Fournit le chargement, le formatage de prompt, la generation en streaming et la gestion du cache.

Chaque moteur declare son propre reglage de reflexion, parce que les runtimes ne l’expriment pas de la meme facon : le daemon MTPLX prend un reasoning_effort a trois crans, le serveur OptiQ passe par chat_template_kwargs, et mlx-lm applique le drapeau au gabarit. Un budget unique partout ferait dire trois choses differentes au meme chiffre.

reasoningSteps: tuple[int, ...] = (0, 512, 1024, 2048)

Paliers de budget de reflexion, du plus sobre au plus bavard. Le premier element est toujours 0, qui signifie « pas de reflexion ».

defaultReasoningBudget: int = 1024

Budget applique quand l’utilisateur presse le bouton sans avoir choisi de niveau : le palier immediatement apres OFF.

reasoningParameter: str = 'chat_template_kwargs.enable_thinking'

Nom du parametre du runtime qui regle la reflexion. Purement documentaire : il dit comment ce moteur exprime le budget.

isRemote: bool = False

True quand le modele est servi ailleurs, sur du materiel qui n’est pas cette machine.

Tout ce que Mirza mesure sur un cache local n’a alors pas d’objet : il n’y a ni cache a quantifier, ni fenetre a borner, ni jetons a compter pour eviter de la deborder. La fenetre est celle du fournisseur, et elle ne se rogne pas ici. Le raisonnement non plus n’a pas a etre suivi : il ne se lit pas, il coute, et il ne revient pas dans l’historique.

Ce drapeau dit « ce moteur n’a pas de memoire chez nous ». Il ne dit pas que le contexte est sans importance : le prompt complet part quand meme, et c’est ce que le modele doit recevoir.

estimatedKvTokens: int = 0

currentKvTokens: int = 0

classmethod reasoningEffortFor(budget)

Traduit un budget en cran, a partir des paliers de ce moteur.

Paramètres:

budget (int) – Budget de reflexion demande.

Renvoie:

Le nom du palier : celui du budget, ou le dernier si le budget n’est pas exactement un palier.

Type renvoyé:

str

resolveMaxTokens(answerTokens, ceiling)

Calcule le budget total d’un tour : la reflexion plus la reponse.

Le total est borne par le plafond dur, mais jamais en dessous de ce qui reste pour la reponse : une reflexion qui consomme tout son budget laisserait la reponse a zero jeton.

Paramètres:

• answerTokens (int) – Jetons reserves a la reponse finale.

• ceiling (int) – Plafond dur sur le total.

Renvoie:

Le nombre de jetons a demander au runtime.

Type renvoyé:

int

abstractmethod loadModel(systemPrompt='')

Charge le modele et calibre le cache KV.

Paramètres:

systemPrompt (str, optional) – Prompt systeme initial pour calibrer le cache. Defaut : « « .

Type renvoyé:

None

abstractmethod formatPrompt(conversationHistory, currentUserInput, systemPrompt, maxTurns=4)

Formate la structure du prompt conversationnel selon le template du modele.

Paramètres:

• conversationHistory (list[dict]) – Historique conversationnel passe sous forme de messages avec roles.

• currentUserInput (str) – Entree textuelle de l’utilisateur.

• systemPrompt (str) – Prompt systeme encadrant la reponse.

• maxTurns (int, optional) – Nombre maximal de tours de parole a inclure. Defaut : 4.

Renvoie:

Prompt formate pret pour l’inference ou la tokenisation.

Type renvoyé:

str

abstractmethod streamResponse(formattedPrompt)

Genere le flux de tokens en streaming temps reel.

Paramètres:

formattedPrompt (str) – Prompt complet formate.

Yields:

str – Fragments de texte ou tokens generes en temps reel.

Type renvoyé:

Generator[str]

clearCache()

Purge les caches KV et la memoire transitoire du moteur LLM.

Type renvoyé:

None

setReasoningBudget(budget)

Ajuste le budget de reflexion alloue au modele.

Paramètres:

budget (int)

Type renvoyé:

None

setThinkingMode(enabled)

Active ou desactive le mode reflexion du modele.

Paramètres:

enabled (bool)

Type renvoyé:

None

abstractmethod unload()

Libere l’integralite des ressources GPU et memoire allouees.

Type renvoyé:

None

Contrat d’interface abstraite pour les moteurs de synthese vocale (TTS).

class mirza.engine.interfaces.baseTts.BaseTts

Bases : ABC

Interface abstraite pour tous les moteurs TTS (Text-to-Speech).

Permet d’interchanger un modele on-premise (Kokoro ONNX) et un service cloud (Edge-TTS).

abstractmethod async synthesizeAsync(text)

Synthese asynchrone non-bloquante.

Paramètres:

text (str) – Texte a synthetiser vocalement.

Renvoie:

Tuple contenant le tableau audio (float32) et le taux d’echantillonnage en Hz, ou (None, None) en cas d’erreur.

Type renvoyé:

tuple[np.ndarray | None, int | None]

abstractmethod synthesize(text)

Wrapper synchrone pour la synthese vocale.

Paramètres:

text (str) – Texte a synthetiser vocalement.

Renvoie:

Tuple contenant le tableau audio (float32) et le taux d’echantillonnage en Hz, ou (None, None) en cas d’erreur.

Type renvoyé:

tuple[np.ndarray | None, int | None]

warmUp()

Prechauffe le modele TTS si applicable.

Type renvoyé:

None

unload()

Libere le modele en memoire.

Par defaut sans effet : un moteur qui ne detient aucun poids local (synthese cloud) n’a rien a liberer.

Type renvoyé:

None

property isLoaded: bool

Indique si des poids resident actuellement en memoire.

Vrai par defaut : un moteur sans etat local (synthese cloud) n’a rien a charger.

---

Implémentations STT

Moteur de transcription vocale FastConformer Nemotron 3.5 8-bit via MLX Audio.

class mirza.engine.stt.mlxNemotronStt.MlxNemotronStt(modelRepo='mlx-community/nemotron-3.5-asr-streaming-0.6b-8bit')

Bases : BaseStt

FastConformer-RNNT Nemotron 3.5 ASR local sur Apple Silicon (MLX).

Modele streaming 600M quantifie en 8 bits, rapide et optimisé pour Apple Silicon.

Paramètres:

modelRepo (str)

__init__(modelRepo='mlx-community/nemotron-3.5-asr-streaming-0.6b-8bit')

Initialise le moteur Nemotron ASR.

Paramètres:

modelRepo (str, optional) – Depot HuggingFace du modele FastConformer quantifie. Defaut : « mlx-community/nemotron-3.5-asr-streaming-0.6b-8bit ».

warmUp()

Pre-charge integralement les poids Nemotron 8 bits et calibre le pipeline Metal.

Type renvoyé:

None

transcribe(audioArray, language='fr', initialPrompt='')

Transcrit le flux audio de maniere optimisee avec Nemotron FastConformer-RNNT.

Paramètres:

• audioArray (np.ndarray) – Echantillons audio 16 kHz mono au format float32.

• language (str, optional) – Code langue ISO (ex: “fr”). Defaut : « fr ».

• initialPrompt (str, optional) – Invite textuelle initiale, non utilisee par FastConformer. Defaut : « « .

Renvoie:

Chaine transcrite filtree du bruit ou vide si aucun signal intelligible.

Type renvoyé:

str

unload()

Libere le reseau de neurones et les tenseurs Metal associes.

Relaisable : transcribe recharge paresseusement au prochain appel.

Type renvoyé:

None

property isLoaded: bool

Indique si les poids resident en memoire.

Renvoie:

True une fois le modele charge.

Type renvoyé:

bool

Moteur de transcription vocale Whisper Turbo via mlx_whisper.

class mirza.engine.stt.mlxWhisperStt.MlxWhisperStt(modelRepo='mlx-community/whisper-large-v3-turbo-q4')

Bases : BaseStt

Whisper Turbo local sur puce Apple Silicon (MLX).

Modele quantifie en 4 bits, pour une empreinte VRAM d’environ 450 Mo.

Paramètres:

modelRepo (str)

__init__(modelRepo='mlx-community/whisper-large-v3-turbo-q4')

Initialise le moteur Whisper ASR.

Paramètres:

modelRepo (str, optional) – Depot HuggingFace du modele Whisper MLX. Defaut : « mlx-community/whisper-large-v3-turbo-q4 ».

warmUp()

Pre-charge integralement les poids et calibre le pipeline Metal.

Type renvoyé:

None

transcribe(audioArray, language='fr', initialPrompt='Bonjour Mirza.')

Transcrit le flux audio avec Whisper Turbo MLX via MLXs.

Paramètres:

• audioArray (np.ndarray) – Echantillons audio mono 16 kHz au format float32.

• language (str, optional) – Code langue ISO (ex: “fr”). Defaut : « fr ».

• initialPrompt (str, optional) – Prompt textuel de guidage contextuel. Defaut : « Bonjour Mirza. ».

Renvoie:

Texte transcrit filtre du bruit ou vide si inaudible.

Type renvoyé:

str

unload()

Libere le modele Whisper.

Sans effet sur ce moteur, qui ne charge ses poids qu’a la premiere transcription.

Type renvoyé:

None

---

Implémentations LLM

Implementation du moteur LLM Mirza basee sur MTPLX et Qwen 3.8-9B Distill MTPLX (Q6G64). Fournit une acceleration native MTP (Multi-Token Prediction) sur Apple Silicon M4 via le runtime MTPLX.

class mirza.engine.llm.mtplxLlm.MtplxLlm(modelConfig)

Bases : BaseLlm

Moteur de generation haute performance utilisant le runtime MTPLX.

Paramètres:

modelConfig (LlmConfig) – Configuration du moteur LLM.

reasoningSteps: tuple[int, ...] = (0, 512, 1024, 2048)

ses paliers sont traduits en effort par reasoningEffortFor.

Type:

Le daemon prend un effort a trois crans, pas un nombre de jetons

defaultReasoningBudget: int = 1024

Budget applique quand l’utilisateur presse le bouton sans avoir choisi de niveau : le palier immediatement apres OFF.

reasoningParameter: str = 'reasoning_effort'

Nom du parametre du runtime qui regle la reflexion. Purement documentaire : il dit comment ce moteur exprime le budget.

__init__(modelConfig)

Paramètres:

modelConfig (LlmConfig)

Type renvoyé:

None

loadModel(systemPrompt='')

Charge le modele en s’assurant que le daemon MTPLX est actif.

Paramètres:

systemPrompt (str, optional) – Instructions systeme d’initialisation. Defaut : « « .

Lève:

ConnectionError – Si le daemon est injoignable et le demarrage automatique desactive.

Type renvoyé:

None

prefill(systemPrompt='')

Pré-amorce le graphe de calcul Metal et le cache de session avec le prompt système.

Compile les shaders à l’avance et initialise les tables KV pour éliminer le délai TTFT à froid lors du premier échange utilisateur.

Paramètres:

systemPrompt (str, optional) – Le prompt système complet à pré-remplir.

Type renvoyé:

None

setThinkingMode(enabled)

Active ou desactive dynamiquement le mode reflexion (CoT).

Paramètres:

enabled (bool) – True pour le palier par defaut, False pour le couper.

Type renvoyé:

None

setReasoningBudget(budget)

Definit le budget de tokens alloue a la reflexion.

Paramètres:

budget (int) – Budget en tokens. 0 desactive le mode reflexion.

Type renvoyé:

None

clearCache()

Reinitialise les etats de session sur le serveur MTPLX.

Type renvoyé:

None

formatPrompt(conversationHistory=None, currentUserInput='', systemPrompt='', maxTurns=4, history=None, userPrefix='', assistantPrefix='')

Formate l’historique conversationnel en JSON valide pour l’API /chat/completions.

Paramètres:

• conversationHistory (list[dict[str, str]] | None, optional) – Tours precedents. Defaut : None.

• currentUserInput (str, optional) – La question courante. Defaut : « « .

• systemPrompt (str, optional) – Instructions systeme. Defaut : « « .

• maxTurns (int, optional) – Nombre de tours conserves. Defaut : 4.

• history (list[dict[str, str]] | None, optional) – Alias de conversationHistory, prioritaire. Defaut : None.

• userPrefix (str, optional) – Prefixe ajoute aux messages de role user. Defaut : « « .

• assistantPrefix (str, optional) – Prefixe ajoute aux messages de role assistant. Defaut : « « .

Renvoie:

La liste de messages serialisee en JSON.

Type renvoyé:

str

streamResponse(formattedPrompt)

Genere les tokens en streaming temps reel via SSE depuis MTPLX.

Paramètres:

formattedPrompt (str) – Prompt produit par formatPrompt().

Yields:

str – Fragments de texte. La reflexion est encadree par <think> et </think> pour que le filtre de flux la route vers le canal de reflexion et ne fasse entendre que la reponse finale.

Type renvoyé:

Generator[str]

unload()

Arrete le daemon MTPLX, qu’il ait ete lance ou adopte par cette instance.

Type renvoyé:

None

Moteur de generation de texte MLX avec decodage speculatif MTP pour Qwen 3.5.

mirza.engine.llm.mlxQwenLlm.REQUIRED_ROPE_KEYS = ('partial_rotary_factor', 'type', 'mrope_section', 'rope_theta')

Keys mlx_vlm’s qwen3_5 config insists on inside rope_parameters.

class mirza.engine.llm.mlxQwenLlm.MlxQwenLlm(modelConfig)

Bases : BaseLlm

Implementation MLX locale de Qwen 3.5 (9B 5-bit).

Supporte le decodage speculatif (MTP).

Paramètres:

modelConfig (LlmConfig) – Configuration contenant les parametres du modele MLX et les hyperparametres.

__init__(modelConfig)

Paramètres:

modelConfig (LlmConfig)

Type renvoyé:

None

model: Any

processor: Any

modelConfig: Any

apcManager: apc.APCManager | None

draftModel: Any

promptCache: Any

setThinkingMode(enabled)

Active ou desactive dynamiquement le mode reflexion (CoT).

Paramètres:

enabled (bool) – True pour demander un raisonnement, False pour l’eviter.

Type renvoyé:

None

setReasoningBudget(budget)

Definit a chaud le budget de tokens de reflexion.

Paramètres:

budget (int) – Budget en tokens. 0 desactive le mode reflexion.

Type renvoyé:

None

loadModel(systemPrompt='')

Charge le modele principal et le drafter MTP en memoire unifiee.

Paramètres:

systemPrompt (str, optional) – Prompt systeme utilise pour le prechauffage. Defaut : « « .

Type renvoyé:

None

formatPrompt(conversationHistory=None, currentUserInput='', systemPrompt='', maxTurns=4, history=None, userPrefix='', assistantPrefix='')

Convertit l’historique en prompt formate par le gabarit Qwen.

Paramètres:

• conversationHistory (list[dict[str, str]] | None, optional) – Tours precedents. Defaut : None.

• currentUserInput (str, optional) – La question courante. Defaut : « « .

• systemPrompt (str, optional) – Instructions systeme. Defaut : « « .

• maxTurns (int, optional) – Nombre de tours conserves. Defaut : 4.

• history (list[dict[str, str]] | None, optional) – Alias de conversationHistory, prioritaire. Defaut : None.

• userPrefix (str, optional) – Prefixe ajoute aux messages de role user. Defaut : « « .

• assistantPrefix (str, optional) – Prefixe ajoute aux messages de role assistant. Defaut : « « .

Renvoie:

Le prompt mis en forme, pret pour la generation.

Type renvoyé:

str

streamResponse(formattedPrompt)

Genere le flux en streaming, avec decodage speculatif et reflexion.

Paramètres:

formattedPrompt (str) – Prompt produit par formatPrompt().

Yields:

str – Fragments de texte au fur et a mesure.

Type renvoyé:

Generator[str]

clearCache()

Vide le pool de blocs de l’APC Manager.

Type renvoyé:

None

unload()

Decharge le modele neural, le processeur et vide la memoire Metal allouee.

Type renvoyé:

None

---

Implémentations TTS

Moteur de synthese vocale asynchrone Edge-TTS Neural (Microsoft Cloud).

class mirza.engine.tts.edgeTts.PersistentTCPConnector(*args, **kwargs)

Bases : TCPConnector

Connecteur TCP persistant, qui empeche la fermeture prematuree du socket.

Paramètres:

• args (Any)

• kwargs (Any)

Type renvoyé:

Any

async close()

Empeche la fermeture du socket TCP par session unitaire.

force_close()

Ferme definitivement la socket TCP sous-jacente.

Renvoie:

Ce que rend la fermeture de la classe parente.

Type renvoyé:

object

class mirza.engine.tts.edgeTts.EdgeTts(ttsConfig)

Bases : BaseTts

Service neural Edge-TTS, a tres faible latence.

Utilise une boucle evenementielle persistante et rogne les silences de bord.

Paramètres:

ttsConfig (TtsConfig) – Configuration contenant la voix, le debit et la hauteur de pitch.

config

Instance de configuration du moteur TTS.

Type:

TtsConfig

loop

Boucle evenementielle asynchrone dediee dans un thread d’arriere-plan.

Type:

asyncio.AbstractEventLoop

connector

Connecteur TCP persistant, reutilise d’un appel a l’autre.

Type:

PersistentTCPConnector | None

workerThread

Thread executant la boucle evenementielle asynchrone.

Type:

threading.Thread

__init__(ttsConfig)

Initialise le moteur et demarre la boucle d’evenements en arriere-plan.

Paramètres:

ttsConfig (TtsConfig) – Configuration acoustique (voix, debit, pitch).

async synthesizeAsync(text)

Synthetise un flux audio via Edge-TTS de maniere asynchrone.

Paramètres:

text (str) – Texte a synthetiser vocalement.

Renvoie:

Echantillons audio float32 et frequence d’echantillonnage en Hz, ou (None, None) en cas d’erreur.

Type renvoyé:

tuple[np.ndarray | None, int | None]

synthesize(text)

Synthetise un flux audio de maniere synchrone en interrogeant la boucle dediee.

Paramètres:

text (str) – Texte a synthetiser vocalement.

Renvoie:

Echantillons audio float32 et frequence d’echantillonnage en Hz, ou (None, None) en cas d’erreur.

Type renvoyé:

tuple[np.ndarray | None, int | None]

Moteur de synthese vocale locale hors-ligne Kokoro ONNX.

class mirza.engine.tts.kokoroTts.KokoroTts(ttsConfig, modelPath='mirza/data/models/kokoro-v1.0.onnx', voicesPath='mirza/data/models/voices-v1.0.bin')

Bases : BaseTts

Synthese vocale locale Kokoro ONNX (~80 Mo, 30 ms de latence).

Paramètres:

• ttsConfig (TtsConfig) – Configuration de la synthese vocale.

• modelPath (str, optional) – Chemin du fichier modele ONNX local. Defaut : « mirza/data/models/kokoro-v0_19.onnx ».

• voicesPath (str, optional) – Chemin du fichier de voix. Defaut : « mirza/data/models/voices-v1.0.bin ».

config

Configuration locale.

Type:

TtsConfig

modelPath

Emplacement du modele ONNX.

Type:

str

voicesPath

Emplacement du fichier de voix.

Type:

str

kokoro

Instance du moteur Kokoro chargee en memoire.

Type:

kokoro_onnx.Kokoro | None

__init__(ttsConfig, modelPath='mirza/data/models/kokoro-v1.0.onnx', voicesPath='mirza/data/models/voices-v1.0.bin')

Initialise le moteur Kokoro ONNX standard, non quantifie.

Paramètres:

• ttsConfig (TtsConfig) – Configuration acoustique (voix, vitesse).

• modelPath (str, optional) – Chemin local du modele ONNX non quantifie. Defaut : « mirza/data/models/kokoro-v1.0.onnx ».

• voicesPath (str, optional) – Chemin local du fichier de voix binaire. Defaut : « mirza/data/models/voices-v1.0.bin ».

warmUp()

Prechauffe le runtime ONNX par une courte synthese initiale, pour supprimer la latence du premier tour.

Type renvoyé:

None

async synthesizeAsync(text)

Synthetise un texte en audio de maniere asynchrone (delegue a synthesize).

Paramètres:

text (str) – Texte a synthetiser.

Renvoie:

Echantillons audio float32 et taux d’echantillonnage, ou (None, None).

Type renvoyé:

tuple[np.ndarray | None, int | None]

synthesize(text)

Genere l’audio phonetique via le runtime local Kokoro ONNX.

Paramètres:

text (str) – Texte a synthetiser.

Renvoie:

Echantillons audio float32 et frequence d’echantillonnage, ou (None, None).

Type renvoyé:

tuple[np.ndarray | None, int | None]

unload()

Libere la session ONNX Kokoro.

Relaisable : synthesize reconstruit la session au prochain appel.

Type renvoyé:

None

property isLoaded: bool

Indique si les poids resident en memoire.

Renvoie:

True une fois la session ONNX ouverte.

Type renvoyé:

bool

---

Module Agentique (mirza.engine.agent)

Outils du registre agentique

Identifiant	Nom UI	Description
datetime_info	Horloge & Calendrier	Date, heure, fuseau horaire avec 30+ correspondances intégrées
system_metrics	Télémétrie Matérielle	CPU %, RAM, VRAM Metal via psutil + MLX
web_search	Recherche Web	DuckDuckGo scraping HTML + fallback Instant Answer JSON
visit_webpage	Exploration Web	Extraction texte HTML (3000 chars max) sans exécution JS
recall_memory	Mémoire Épisodique & Passé	Recherche dans les souvenirs et faits passés de Mirza via RAG hybride SQLite-vec / FTS5
save_memory	Enregistrement Mémoire	Sauvegarde explicite d’un fait dans la base SQLite-vec

Gestionnaire central du mode agentique de Mirza, base sur smolagents (CodeAgent).

Gere l’activation et la desactivation a chaud du mode et des outils individuels.

class mirza.engine.agent.agentManager.AgentManager(llmEngine, broadcaster=None)

Bases : object

Gestionnaire central du mode agentique, base sur smolagents (CodeAgent).

Paramètres:

• llmEngine (BaseLlm) – Moteur d’inference LLM auquel l’agent est attache.

• broadcaster (EventBroadcaster, optional) – Diffuseur WebSocket notifiant le frontend des etats d’outils. Defaut : None.

__init__(llmEngine, broadcaster=None)

Paramètres:

• llmEngine (Any)

• broadcaster (Any)

Type renvoyé:

None

setAssistantProfilePrompts(systemPrompt=None, instructionsPrompt=None, finalAnswerPrompt=None, allowedTools=None)

Met a jour les gabarits de prompts et les restrictions d’outils de l’agent.

Paramètres:

• systemPrompt (str, optional) – Nouveau prompt systeme de l’agent.

• instructionsPrompt (str, optional) – Nouvelles instructions d’execution de l’agent.

• finalAnswerPrompt (dict, optional) – Nouveau gabarit final_answer.

• allowedTools (tuple[str, ] | None, optional) – Liste d’outils autorises ou None pour tout autoriser.

Type renvoyé:

None

setLlmEngine(llmEngine)

Rattache l’agent au moteur qui vient d’etre charge.

L’adaptateur avait capture le moteur du profil de demarrage : apres un changement de modele, il pointait sur un daemon arrete, et les outils echouaient alors que le dialogue normal fonctionnait.

Paramètres:

llmEngine (object) – Le moteur LLM nouvellement cree.

Type renvoyé:

None

isEnabled()

Indique si le mode agentique est actif.

Renvoie:

True si l’agent est active, False sinon.

Type renvoyé:

bool

setEnabled(enabled)

Active ou desactive le mode agentique.

Paramètres:

enabled (bool) – Nouvel etat du mode agentique.

Type renvoyé:

None

toggleTool(toolId, enabled=None)

Active ou desactive un outil specifique par son identifiant.

Paramètres:

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

• enabled (bool | None, optional) – Etat cible explicite ou None pour inverser l’etat courant.

Renvoie:

True si l’outil a ete trouve et modifie, False sinon.

Type renvoyé:

bool

getStatus()

Retourne l’etat complet de l’agent et la liste de ses outils.

Renvoie:

Dictionnaire decrivant le statut et les outils disponibles.

Type renvoyé:

dict[str, Any]

setAllowedTools(allowed)

Restreint les outils que l’agent a le droit d’appeler.

La restriction suit le profil actif, pas l’utilisateur : un modele distant peut n’avoir pas acces a tout, et ce choix se prend une fois. None laisse tous les outils, ce qui est le defaut tant qu’on n’a pas dit quels couper.

Un identifiant inconnu est ignore, pas refuse : la liste vient du profil, qui peut citer un outil enregistre plus tard sans casser le chargement.

Paramètres:

allowed (tuple[str, ] | None) – Identifiants autorises, ou None pour tous les autoriser.

Type renvoyé:

None

run(userPrompt, conversationHistory=None, onThoughtChunk=None, onTokenChunk=None)

Execute la requete utilisateur via smolagents CodeAgent.

Paramètres:

• userPrompt (str) – Instruction ou requete de l’utilisateur.

• conversationHistory (list[dict[str, str]] | None, optional) – Historique conversationnel recent.

• onThoughtChunk (Callable[[str], None] | None, optional) – Callback pour streamer les etapes de reflexion de l’agent.

• onTokenChunk (Callable[[str], None] | None, optional) – Callback pour streamer les fragments de reponse.

Renvoie:

Reponse finale textuelle de l’agent, balise result comprise pour les documents.

Type renvoyé:

str

Adaptateur smolagents reliant le moteur LLM MLX ou MTPLX a CodeAgent.

Partage les instances de modeles deja chargees, pour eviter tout rechargement de poids ou surcout de memoire unifiee.

class mirza.engine.agent.mirzaModelAdapter.MirzaModelAdapter(*args, **kwargs)

Bases : Model

Adaptateur smolagents reliant le moteur LLM MLX ou MTPLX a CodeAgent.

Paramètres:

• llmEngine (BaseLlm) – Instance du moteur LLM (MlxQwenLlm ou MtplxLlm).

• model_id (str, optional) – Identifiant du modele smolagents (defaut: « qwen-local-mlx »).

• max_tokens (int, optional) – Plafond de tokens generes par tour (defaut: 1024).

• temperature (float, optional) – Temperature d’echantillonnage (defaut: 0.6).

• top_p (float, optional) – Seuil de troncature nucleus (defaut: 0.95).

• **kwargs – Parametres supplementaires transmis a Model.

__init__(llmEngine, model_id='qwen-local-mlx', max_tokens=1024, temperature=0.6, top_p=0.95, **kwargs)

Paramètres:

• llmEngine (Any)

• model_id (str)

• max_tokens (int)

• temperature (float)

• top_p (float)

• kwargs (Any)

Type renvoyé:

None

generate(messages, stop_sequences=None, response_format=None, tools_to_call_from=None, **kwargs)

Genere une reponse compatible smolagents via MTPLX ou MLX.

Paramètres:

• messages (list[ChatMessage or dict]) – Historique conversationnel smolagents.

• stop_sequences (list[str], optional) – Chaines d’arret declenchant l’interruption de generation.

• response_format (dict[str, str], optional) – Format specifique demande pour la sortie.

• tools_to_call_from (list[Any], optional) – Outils smolagents mis a disposition du modele.

• **kwargs – Parametres d’inference additionnels.

Renvoie:

Message assistant contenant le texte genere et les statistiques de tokens.

Type renvoyé:

ChatMessage

Package des outils agentiques de Mirza.

Expose l’integralite des outils modulaires : - system : datetime_info, system_metrics - web : web_search, visit_webpage - memory : recall_memory, save_memory, setActiveMemoryStore

class mirza.engine.agent.tools.MemoryToolContext

Bases : object

Conteneur de contexte pour acceder au magasin de memoire.

Evite une variable globale brute pour le magasin actif.

activeStore: Any = None

classmethod setStore(store)

Associe le magasin de memoire episodique actif.

Paramètres:

store (Any) – Instance d’EpisodicMemoryStore.

Type renvoyé:

None

classmethod getStore()

Recupere le magasin de memoire actif ou en initialise un par defaut.

Renvoie:

Instance du gestionnaire de memoire episodique.

Type renvoyé:

Any

mirza.engine.agent.tools.clinical_records_stats(search_term='', query='', keyword='', patient_name='', min_count=1, start_date='', end_date='', group_by_patient=True)

Interroge et denombre les dossiers medicaux dans la base de donnees clinique SQLite de Mirza. Utilise cet outil lorsque l’utilisateur pose une question de comptage, de frequence ou d’exhaustivite (ex: “combien de patients…”, “qui a plus de 3 ordonnances de metformine”, “nombre de cas de grippe”, “liste tous les patients sous anticoagulant”).

Paramètres:

• search_term (str) – Mot-cle clinique, molecule, medicament ou pathologie recherchee (ex: “diabete”, “metformine”, “grippe”, “hypertension”, “PPC”, “insuline”).

• query (str) – Alias de search_term (ex: “diabete”, “hypertension”).

• keyword (str) – Alias de search_term (ex: “diabete”, “asthme”).

• patient_name (str) – Nom ou partie du nom du patient optionnel (ex: “Aubert”, “Colin”, “Leclerc”).

• min_count (int) – Nombre minimal d’occurrences ou d’ordonnances par patient (defaut: 1, mettre 4 pour “plus de 3”).

• start_date (str) – Date de debut minimale au format YYYY-MM-DD (ex: “2026-09-01” pour le mois de septembre).

• end_date (str) – Date de fin maximale au format YYYY-MM-DD (ex: “2026-10-31”).

• group_by_patient (bool) – Si True, regroupe et compte par patient (recommande pour les questions sur les patients et leurs ordonnances). Si False, donne le total global.

Type renvoyé:

str

mirza.engine.agent.tools.datetime_info(query_type='current', location='')

Fournit la date, l’heure courante, le fuseau horaire et le jour de la semaine, localement ou pour un pays/ville specifique dans le monde.

Paramètres:

• query_type (str) – Type d’information demandee (“current”, “date”, “time”, ou “iso”).

• location (str) – Ville ou pays optionnel (ex: “Ouganda”, “Tokyo”, “New York”, “Londres”, “Senegal”) pour obtenir l’heure dans ce fuseau horaire.

Type renvoyé:

str

mirza.engine.agent.tools.execute_clinical_sql(query)

Execute une requete SQL SELECT securisee en lecture seule sur la table “memories” de la base clinique. Utilise cet outil lorsque tu dois executer une requete analytique SQL specifique (GROUP BY, filtres temporels, calculs de moyenne/variance/statistiques, sous-requetes complexes).

Schema de la table “memories”: - id (INTEGER) - user_input (TEXT) : description du document et nom du patient - assistant_response (TEXT) : observations cliniques, prescriptions, actes medicaux - metadata (TEXT JSON) : contient “patient_id”, “patient_nom”, “age”, “sexe”, “date”, “type_document”, “doc_id”

Exemples SQL utiles:

SELECT AVG(json_extract(metadata, '$.age')), COUNT(DISTINCT json_extract(metadata, '$.patient_id')) FROM memories;
SELECT DISTINCT json_extract(metadata, '$.patient_nom'), json_extract(metadata, '$.age'), json_extract(metadata, '$.sexe') FROM memories;

Paramètres:

query (str) – Requete SQL SELECT valide (les instructions de modification INSERT, UPDATE, DELETE, DROP sont interdites).

Type renvoyé:

str

mirza.engine.agent.tools.recall_memory(query)

Recherche dans la memoire episodique et les conversations passees de Mirza. Utilise cet outil lorsque l’utilisateur demande de se rappeler d’un fait passe, d’un rendez-vous, d’un projet, d’un choix ou d’une recherche anterieure.

Paramètres:

query (str) – Mots-cles ou question resumant ce qu’il faut retrouver dans l’historique (ex: “rendez-vous dentiste”, “choix de framework”, “code python ecrit hier”).

Type renvoyé:

str

mirza.engine.agent.tools.save_memory(content, category='recherche')

Enregistre explicitement une information, un fait cle, une decouverte ou une note dans la memoire episodique / RAG de Mirza. Utilise cet outil pour memoriser les resultats de recherche importants, des faits precis sur un sujet, ou une information que l’utilisateur souhaite retenir pour de futures conversations.

Paramètres:

• content (str) – Le texte de l’information ou du fait a memoriser (doit etre clair, precis et factuel).

• category (str) – Theme ou categorie optionnelle (ex: “recherche”, “preference”, “technique”, “projet”).

Type renvoyé:

str

mirza.engine.agent.tools.setActiveMemoryStore(store)

Enregistre le magasin de memoire episodique actif pour l’outil recall_memory.

Paramètres:

store (Any) – Instance de gestion de la memoire vectorielle episodique.

Type renvoyé:

None

mirza.engine.agent.tools.system_metrics()

Mesure en temps reel l’utilisation des ressources du systeme macOS : charge processeur CPU, memoire vive RAM et VRAM Metal active allouee au GPU.

Type renvoyé:

str

mirza.engine.agent.tools.visit_webpage(url)

Telecharge et extrait le texte d’une page Web ou d’un document PDF (recommandations, publications, articles). Extrait egalement les liens et fichiers PDF pertinents trouves sur la page.

Paramètres:

url (str) – L’adresse URL absolue de la page ou du PDF a inspecter (doit commencer par http:// ou https://).

Type renvoyé:

str

mirza.engine.agent.tools.web_search(query, max_results=5)

Recherche des informations actualisees sur le Web a l’aide d’un moteur de recherche en ligne (DuckDuckGo).

Paramètres:

• query (str) – Les mots-cles ou la question a rechercher sur le web.

• max_results (int) – Nombre maximal de resultats a extraire (par defaut 5).

Type renvoyé:

str