Mirza • Guide Utilisateur Officiel & Architecture

Architecture Système Multi-Niveaux

L'architecture est structurée en trois couches : le client d'interface (HUD React / Tauri v2), la passerelle de transport réseau (WebSocket binaire et TLS) et le nœud d'inférence local hébergé sur le Mac hôte Apple Silicon.

COUCHE 1 : CLIENT HUD (NOMADE / DESKTOP) TAURI V2 / REACT 18

              Capture Audio PCM
              Microphone 16 kHz mono linéaire, buffers audio cycliques et normalisation logicielle.
            

              Rendu Réacteur 60 FPS
              Canvas Web Worker OffscreenCanvas, ondes spectrales et animations des 3 satellites.
            

              HUD & Télémétrie
              Affichage direct des métriques de latence, sélection des profils et console de logs.
            

▼ TRANSPORT CHIFFRÉ : WEBSOCKET BINAIRE / TLS (PORT 8765) / TAILSCALE WIREGUARD ▼

COUCHE 2 : MOTEUR D'ORCHESTRATION BACKEND (MAC APPLE SILICON) FASTAPI / ASYNCIO / PYTHON

              Audio Pipeline VAD + ASR
              Silero VAD v5 filtrant les silences, streaming direct vers FastConformer RNN-T 8-bit.
            

              Gestionnaire de Dialogue
              Bascule de profil à chaud (profiles.yaml), prompt engineering et formatage dual-channel.
            

              Boucle Agentique CodeAgent
              smolagents ReAct avec exécution Python sécurisée et 6 outils modulaires.
            

▼ ACCÈS DIRECT ZÉRO-COPIE : MÉMOIRE UNIFIÉE APPLE SILICON (UMA METAL) ▼

COUCHE 3 : MOTEURS D'INFÉRENCE & MATÉRIEL LOCAL MLX / METAL / HARDWARE

              Démon MTPLX (Port 8766)
              LLM local Qwen 3.5 9B distillé quantifié Q6G64 avec Paged Attention Metal (30+ tok/s).
            

              Synthèse Vocale TTS
              Kokoro-TTS ONNX 100% local et souverain par défaut, ou Edge-TTS en repli cloud optionnel.
            

              Contrôle Thermique M4
              Module Fan Control actif régulant le ventilateur selon les sondes thermiques GPU/SoC.
            

CONFIDENTIALITÉ ET EXÉCUTION LOCALE

L'ensemble des données vocales, des notes contextuelles et de l'historique de conversation réside sur la machine hôte. Aucun paquet audio ni prompt textuel n'est transmis à un service tiers en mode nominal.

MÉMOIRE UNIFIÉE ZERO-COPY (UMA)

Sur Apple Silicon, le processeur central (CPU), le moteur neuronal (NPU) et le processeur graphique (GPU Metal) partagent la même bande passante mémoire (jusqu'à 150 Go/s). Les tenseurs de poids et le cache KV n'ont jamais besoin d'être copiés sur un bus PCI express.

Vue générale de l'interface mobile Mirza HUD

Figure 1 : Interface HUD Nomade de Mirza — Réacteur réactif OffscreenCanvas, constellation de satellites (BrainBoost, Agent, Contexte), jauges de télémétrie matérielle et console de dialogue.

Moteurs d'Inférence Pris en Charge

Mirza intègre plusieurs moteurs interchangeables configurables au lancement ou en temps réel :

Type	Moteur / Modèle	Propriétés & Rôle
ASR (STT)	MlxNemotronStt (FastConformer 8-bit)	Moteur principal. Streaming temps réel RNN-T à latence inférieure à 200 ms.
ASR (Fallback)	MlxWhisperStt (Whisper Turbo)	Moteur de secours pour transcription multilingue hors-ligne.
LLM Principal	MtplxLlm (Qwen 3.5 9B distillé MTPLX Q6G64)	Moteur local haute performance avec Paged Attention GPU Metal (28–34 tok/s).
LLM Cloud	OpenRouterLlm (openrouter/free)	Bascule instantanée vers le cloud gratuit avec conservation du modèle local en RAM.
TTS (Voix Souveraine)	KokoroTts (Kokoro ONNX)	Synthèse vocale neuronale 100% locale, souveraine et hors-ligne (moteur par défaut).
TTS Fallback (Optionnel)	Edge-TTS (fr-FR-EloiseNeural) / MeloTTS	Repli cloud optionnel haute fidélité (connexion Internet requise) ou moteur local alternatif.

Relevé télémétrique en direct sur Apple Silicon

Figure 2 : Relevé Télémétrique en Temps Réel — Débit stable de 22.9 tok/s avec Speculative Decoding MTP x2, empreinte UMA réelle de 11.20 Go (47%), latence STT nulle et liaison chiffrée WSS.

Pipeline Audio Streaming & Transcription

La chaîne de traitement audio est dimensionnée pour descendre sous les 200 ms de latence perçue entre la fin d'élocution et le premier son émis.

1

Capture du Microphone Client & Échantillonnage 16 kHz

Le client mobile ou navigateur capture les échantillons audio en mono 16 bits non compressé à 16 000 Hz. Les paquets de 40 millisecondes (640 échantillons) sont encapsulés sous forme binaire et expédiés par le canal WebSocket sécurisé vers l'endpoint /ws/audio.

2

Détection d'Activité Vocale (Silero VAD v5)

À la réception côté serveur, le flux traverse une instance locale de Silero VAD. Ce réseau de neurones compact évalue la probabilité de présence de voix humaine toutes les 32 millisecondes. Les bruits de fond continus, respirations et silences sont filtrés en amont, évitant de réveiller inutilement le moteur ASR.

3

Inférence ASR Streaming (FastConformer RNN-T)

Dès que la parole est confirmée, les frames audio sont injectées dans le modèle FastConformer quantifié 8-bit MLX. Grâce à l'architecture RNN-Transducer, les hypothèses lexicales sont émises au fur et à mesure sans attendre la fin de la phrase. Dès que l'utilisateur s'arrête de parler, la transcription finale est validée en moins de 180 millisecondes.

Figure 3 : Réacteur en Écoute Active (MIC ACTIVE) — Visualisation en temps réel de l'onde vocale entrante modulée par la détection d'activité vocale (Silero VAD).

Moteur de Raisonnement MTPLX & Dual Output

Une fois le texte transcrit, la requête est transmise au gestionnaire de dialogue, orchestré par le démon d'inférence MTPLX et la boucle agentique.

DÉROULEMENT DU DOUBLE CANAL DE RESTITUTION (DUAL OUTPUT) ARCHITECTURE HYBRIDE ORALE / ÉCRITE

Canal Oral (TTS) Synthèse vocale concise (1 à 2 phrases). Ton posé, direct et informatif, évitant d'énumérer de longs blocs textuels à l'oreille.

Canal Visuel (<result>) Rapport Markdown complet injecté dans le tiroir documentaire du HUD. Contient les tableaux de données, blocs de code, listes et analyses approfondies.

PAGED ATTENTION GPU METAL

Le démon MTPLX tire parti de l'implémentation Paged Attention native sur GPU Metal. Cela permet d'allouer la mémoire du cache KV sous forme de pages non contiguës de 16 tokens, éliminant la fragmentation de la RAM unifiée et permettant de maintenir un débit constant de 28 à 34 tokens par seconde sur puce M4, même lors de contextes volumineux (jusqu'à 16 384 tokens).

Mode BrainBoost actif avec réflexion approfondie

Figure 4 : Mode BrainBoost Actif — Faisceau d'énergie et aura violette signalant une réflexion approfondie en chaîne de pensée (CoT).

Tiroir de restitution documentaire et résultats

Figure 5 : Tiroir DOCS & RÉSULTATS — Restitution des données structurées, calculs et extraits documentaires hors du flux oral.

Système Modulaire de Profils (Personas)

Mirza n'est pas limité à un rôle prédéfini : son architecture repose sur un gestionnaire de profils entièrement déclaratif dans config/profiles.yaml. Ce mécanisme découple le moteur d'exécution de la personnalité de l'agent, permettant à chaque utilisateur de configurer ses propres personas selon ses besoins (assistance générale, ingénierie logicielle, analyse de données, écriture, ou profils métiers spécifiques).

PROFIL PAR DÉFAUT : ASSISTANT GÉNÉRAL

Rôle : Compagnon polyvalent pour le développement, l'automatisation, la recherche web et la productivité quotidienne.
Mémoire : Mémoire épisodique active avec base vectorielle locale SQLite-vec.
Ambiance Visuelle : Cyber Crimson (rouge néon carmin, lueurs ambrées).

PROFILS PERSONNALISÉS & EXTENSIONS MÉTIER

Flexibilité : Possibilité de définir librement n'importe quel profil vertical dans le fichier YAML (consignes système, température, outils autorisés et thème graphique dédié).
Démonstrateur de test : Un profil spécialisé clinique a été configuré comme exemple pratique pour valider l'injection d'outils dédiés et la bascule visuelle.

Bascule à Chaud et Chargement Intelligent

Pour garantir des performances optimales et éviter des lectures disques répétitives à chaque interaction, la configuration des profils est parsée une seule fois au démarrage et conservée dans un cache mémoire thread-safe.

L'utilisateur peut basculer d'un profil à l'autre au démarrage ou en cours d'utilisation :

# Au lancement du serveur : spécification par argument CLI uv run python main.py --server --ssl --profile <nom_du_profil> # Ou directement à chaud depuis l'interface HUD : # Cliquez sur le sélecteur de profil situé à gauche de l'indicateur ONLINE dans l'en-tête.

Lors du basculement vers un profil disposant d'une direction artistique distincte (par exemple le profil de test cyan), l'interface adapte immédiatement son habillage visuel (réticule de l'orbe, anneaux des satellites, bordures et accents lumineux).

Sélecteur dynamique de profils d'assistant dans l'interface

Figure 6 : Sélecteur de Profils à Chaud — Menu contextuel sur mobile permettant de basculer instantanément entre l'Assistant Généraliste et un profil métier personnalisé, avec réinitialisation du contexte et adaptation de la DA.

Exemple Illustratif de Test : Démonstrateur de Profil Spécialisé

Pour valider concrètement l'extensibilité du système de profils sans altérer le cœur de Mirza, un profil métier spécialisé (ici orienté sur une consultation clinique de test) sert d'exemple pratique. Ce cas d'usage illustre comment un profil utilisateur peut enrichir Mirza avec un prompt structuré (méthode SOAP), des outils de calcul locaux et une direction artistique dédiée.

CAS DE TEST DÉMONSTRATEUR : SIMULATION CLINIQUE

Patient Laurent D., 58 ans • Bilan Biologique Rénal & Adaptation Posologique

Antécédents : Diabète de type 2 évoluant depuis 9 ans, hypertension artérielle essentielle.
Traitements actuels : Metformine 1 000 mg (1 comprimé matin et soir, soit 2 000 mg/j), Ramipril 5 mg (1 comprimé le matin).
Biologie reçue : Créatininémie à 132 µmol/L (Clairance estimée CKD-EPI : 48 mL/min/1.73m²), HbA1c à 8.4%, Kaliémie à 4.6 mmol/L, Microalbuminurie à 180 mg/g de créatinine.

REQUÊTE VOCALE DU PRATICIEN :

« Mirza, analyse le bilan de Laurent D. Est-ce que le dosage de metformine doit être adapté compte tenu de sa créatininémie, et quelle stratégie thérapeutique proposer ? »

RAISONNEMENT INTERNE DU MODÈLE (CHAIN-OF-THOUGHT CLINIQUE EBM) :

1. Identification patient : Laurent D., 58 ans, DT2 + HTA. 2. Paramètre clé : Créatininémie 132 µmol/L -> DFG CKD-EPI = 48 mL/min/1.73m² (Insuffisance rénale chronique Stade 3a). 3. Règle EBM / ANSM sur la Metformine : - DFG entre 30 et 59 mL/min : posologie maximale autorisée = 1000 mg/jour en 2 prises. - Posologie actuelle de 2000 mg/jour expose à un risque d'accumulation et d'acidose lactique. 4. Contrôle glycémique : HbA1c 8.4% (objectif < 7.0%). Réduire la metformine risque de dégrader l'équilibre. 5. Recommandations KDIGO 2023 / SFD : - Présence d'IRC Stade 3a avec microalbuminurie (180 mg/g). - Indication formelle de néphroprotection et cardioprotection par inhibiteur du SGLT2 (Dapagliflozine 10 mg ou Empagliflozine 10 mg). - Ramipril bien toléré (kaliémie normale à 4.6), à poursuivre.

CANAL VOCAL PARLÉ (TTS) [AUDIO EN DIRECT]

Prononcé à voix haute calmement pour ne pas perturber l'échange avec le patient :

« Le DFG de Laurent D. est à 48 millilitres par minute, ce qui correspond à une insuffisance rénale modérée de stade 3a. La metformine doit être réduite à 1 000 milligrammes par jour. Pour maintenir l'équilibre glycémique et protéger sa fonction rénale, l'adjonction d'un inhibiteur de SGLT2 est recommandée selon les critères KDIGO. »

CANAL VISUEL HUD (<RESULT>) [RAPPORT CHAT]

Archivé dans le volet inférieur sous forme de rapport médical structuré :

### ÉVALUATION CLINIQUE & THÉRAPEUTIQUE **1. Fonction Rénale & Métabolique :** • DFG estimé (CKD-EPI) : **48 mL/min/1.73m²** (Stade 3a) • HbA1c : **8.4%** (cible < 7.0%) • Rapport Albuminurie/Créatininurie : **180 mg/g** (A2) **2. Ajustement Posologique Immédiat :** • **Metformine :** Réduire de 2000 mg/j à **1000 mg/j** (500 mg matin et soir). *Justification : seuil de clairance 30-59 mL/min (prévention acidose lactique).* **3. Optimisation Recommandée (KDIGO 2023) :** • **Introduction iSGLT2 :** Dapagliflozine 10 mg 1 cp/j. *Double bénéfice : néphroprotection et baisse HbA1c sans risque d'hypoglycémie.* • **Maintien IEC :** Ramipril 5 mg/j (kaliémie à 4.6 mmol/L conforme). **4. Plan de Surveillance (M3) :** • Ionogramme sanguin + créatininémie à S4 et M3. • Contrôle HbA1c à 3 mois.

L'Orbe Centrale (Mirza)

L'orbe centrale est rendue sur canvas dédié par un Web Worker (OffscreenCanvas) à 60/120 FPS. Elle réagit en direct aux interactions audio :

VEILLE (MUTED / IDLE)

Halo discret et rotation lente des arcs extérieurs. Aucun calcul d'inférence en cours.

ÉCOUTE (RECORDING)

Le halo passe en lueur ambrée. Des rubans d'ondes horizontaux oscillent selon l'amplitude réelle de votre voix (RMS micro).

PAROLE (SPEAKING)

Couronne de 8 brins dorés et écarlates ondulant activement pendant la restitution audio. Lors de l'activation d'un profil doté d'une DA personnalisée (comme le profil de test), les brins s'adaptent instantanément (ex: cyan et vert émeraude).

RÉFLEXION (THINKING)

Noyau virant au violet néon lorsque le budget de réflexion (Chain-of-Thought) est activé.

Les 3 Satellites Interactifs

Au-dessus de l'orbe centrale, trois réacteurs satellites miniatures reliés par des conduits d'énergie permettent de piloter l'assistant en direct :

1

Satellite Gauche : BrainBoost (Raisonnement CoT)

Règle le palier de réflexion (Chain-of-Thought) alloué au modèle : 0 (réponse directe rapide), 512, 1024 ou 2048 tokens. Cliquez dessus pour changer de palier. Le faisceau s'illumine en ambre.

2

Satellite Central : Agent Cube (Mode Agentique)

Cliquez pour activer ou désactiver le mode Agent (smolagents CodeAgent ReAct). Le conduit devient bleu néon vif. Un appui long ouvre la liste des outils disponibles pour les activer individuellement.

3

Satellite Droit : KV-Cache (Mémoire de Contexte)

Affiche le taux d'occupation de la fenêtre d'attention (jusqu'à 16 384 tokens). Maintenez le clic enfoncé (Hold to Flush) pour réinitialiser le cache de contexte à zéro. Un clic simple ou double-tap ouvre l'inspecteur de contexte actif.

Pilule et Panneau de Télémétrie

Sous la barre supérieure, une pilule compacte résume les métriques clés en continu (ex: 31.2 tok/s • 12% CONTEXTE • Metal UMA).

En cliquant sur cette pilule, le panneau supérieur déroulant affiche :

JAUGES CIRCULAIRES RAM & VRAM

Jauge 1 : Utilisation globale de la RAM système du Mac (ex: 18.4 Go / 24.0 Go).
Jauge 2 : Empreinte mémoire exacte du processus Mirza (VRAM Metal active).

MÉTRIQUES DE LATENCE & DÉBIT

Affiche en temps réel : Latence ASR (durée de transcription), Time-To-First-Token (TTFT en ms), Durée de génération LLM et Latence totale d'aller-retour (Roundtrip).

Démarrage du Serveur Backend (Mac)

Le serveur se lance sur le Mac hôte à la racine du dépôt avec uv :

1

Lancement avec chiffrement SSL (Recommandé pour smartphones)

uv run python main.py --server --ssl

Le flag --ssl génère ou utilise les certificats TLS nécessaires pour autoriser l'accès au microphone sur les appareils distants.

2

Lancement avec un profil spécifique

uv run python main.py --server --ssl --profile <nom_du_profil>

Active d'emblée un profil personnalisé (ex: --profile medical pour charger le démonstrateur de test) et sa direction artistique associée.

3

Choix du fournisseur vocal (TTS)

uv run python main.py --server --ssl --tts kokoro

Permet de forcer le moteur TTS au démarrage : kokoro (défaut local souverain), edge_tts (repli cloud optionnel) ou melo.

Client Mobile Android (Tauri v2)

L'application Android permet d'utiliser Mirza sur smartphone avec l'interface complète :

A

Téléchargement

Téléchargez l'APK depuis le portail d'accueil (section Application APK protégée par mot de passe).

B

Installation

Ouvrez le fichier téléchargé. Si Android demande confirmation, autorisez l'installation d'applications inconnues pour votre navigateur.

C

Configuration IP au premier lancement

Appuyez sur la pilule de télémétrie en haut, renseignez l'adresse IP de votre Mac hôte dans le champ passerelle et appuyez sur OK.

Connexion Réseau & Utilisation Distante

Deux méthodes pour connecter votre smartphone au Mac :

MÊME RÉSEAU WI-FI (LOCAL)

Identifiez l'adresse IP locale de votre Mac (affichée dans le terminal au démarrage de Mirza, ex: 192.168.1.50:8765). Saisissez-la dans la passerelle de l'application mobile.

DÉPLACEMENT SÉCURISÉ (TAILSCALE)

Installez Tailscale sur votre Mac et sur votre smartphone avec le même compte. Utilisez l'adresse IP 100.x.y.z:8765 attribuée au Mac. La liaison est chiffrée en WireGuard et fonctionne en 4G/5G.

Les 6 Outils du Mode Agent

Lorsque le satellite Agent Cube est activé, l'assistant peut invoquer les 6 outils modulaires enregistrés dans mirza.engine.agent.tools :

Outil	Module	Description & Rôle
datetime_info	`system`	Fournit la date, l'heure courante, le jour de la semaine et le fuseau horaire précis.
system_metrics	`system`	Retourne la charge CPU, l'occupation de la RAM, de la VRAM Metal et l'état de la batterie.
web_search	`web`	Effectue une recherche sur le web et renvoie les titres, extraits et liens pertinents.
visit_webpage	`web`	Extrait et nettoie le contenu textuel complet d'une page web donnée.
save_memory	`memory`	Enregistre une information clé dans la base de données mémoire SQLite / Vectorielle.
recall_memory	`memory`	Recherche et extrait des souvenirs passés pertinents par similarité sémantique.

Figure 7 : Mode Agent Actif (Agent ON) — Satellites et réticules d'acquisition cyan signalant l'autorisation d'exécution de code et d'outils autonomes.

Panneau de configuration des outils smolagents CodeAgent

Figure 8 : Configuration smolagents CodeAgent — Sélection granulaire des outils autorisés (recherche web, télémétrie, inspection de page, mémoire locale).

Contrôle Thermique Actif (Mac Mini M4)

L'inférence continue de modèles 9B à 32 tokens par seconde sollicite intensément les cœurs GPU Metal et la mémoire unifiée. Mirza intègre un module de régulation thermique active (Fan Control) pour prévenir l'échauffement sans usure prématurée.

Relevé Réel de Test sous Profil Balanced (Charge LLM Continue)

Mesure effectuée sur Mac Mini M4 lors d'une génération soutenue de 45 secondes en mode d'inférence MTPLX :

Temps	Vitesse Ventilateur	Mode Contrôle	Température GPU	Température Max SoC
00s	1 000 RPM	auto	39.2°C	51.5°C
05s	1 000 RPM	manual	57.9°C	63.2°C
15s	1 641 RPM	manual	64.4°C	70.4°C
25s	2 765 RPM	manual	67.8°C	71.3°C
35s	2 939 RPM	manual	69.4°C	71.3°C
40s	2 939 RPM	manual	70.0°C	72.5°C

Analyse d'Ingénierie sur l'Usure Mécanique FDB

Une question fréquente concerne l'impact d'une ventilation active continue sur la longévité mécanique du ventilateur Apple.

ROULEMENTS HYDRODYNAMIQUES (FDB)

Les ventilateurs d'Apple reposent sur des roulements à palier fluide (Fluid Dynamic Bearing - FDB) et des moteurs brushless sans balais. Contrairement aux paliers lisses classiques, il n'y a aucun contact métal contre métal : l'axe flotte sur un film d'huile sous pression. Leur durée de vie opérationnelle dépasse 50 000 à 70 000 heures de rotation continue à vitesse modérée (1 500 – 3 000 RPM).

CHOCS THERMIQUES VS VITESSE STABLE

Ce qui dégrade réellement un ordinateur moderne, ce ne sont pas les rotations du ventilateur, mais les chocs thermiques brutaux répétitifs (passages brusques de 40°C à 95°C lors des rafales de calcul). Ces variations cycliques fatiguent les micro-billes de soudure BGA reliant la puce M4 à la carte mère.

Conclusion de Conception

Le profil Balanced de Mirza régule la montée en régime de manière linéaire (de 1 000 à 2 939 RPM en 35 secondes), ce qui stabilise la puce sous le seuil de 72.5°C. À cette vitesse, le niveau sonore reste sous les 25 dBA tout en garantissant une évacuation thermique constante qui protège le matériel sans surmener le roulement du ventilateur.

Questions Fréquentes & Dépannage

L'application mobile affiche "Déconnecté" (Disque rouge) ?

Vérifiez que le serveur tourne bien sur votre Mac (--server --ssl). Contrôlez l'adresse renseignée dans le volet télémétrie : sur Wi-Fi local, l'IP du Mac change parfois lors d'une reconnexion de box.

Comment couper l'assistant quand il parle ?

Cliquez simplement sur l'orbe centrale ou appuyez sur la touche Échap (Escape) sur ordinateur. L'assistant interrompt immédiatement la synthèse vocale et réinitialise son écoute.

Comment vider le contexte si la mémoire est pleine ?

Maintenez le clic enfoncé sur le satellite de droite (KV-Cache) jusqu'à ce que la jauge circulaire se remplisse pour déclencher le Hold to Flush.

Manuel Système Mirza Neural Assistant