Module Serveur et Réseau (mirza.server)

Le module mirza.server expose la plateforme via un serveur HTTP/WebSocket sécurisé et gère la diffusion temps réel des événements vers les clients connectés.

---

Vue d’Ensemble du Serveur

Endpoints exposés par le serveur

Endpoint	Méthode	Description
/ws	WebSocket	Canal bidirectionnel principal — JSON + binaire ArrayBuffer
/	GET	Sert widget/dist/index.html (frontend React compilé)
/assets/*	GET	Fichiers statiques JS, CSS, icônes du widget

Modes de démarrage

Mode	Description
--server	HTTP sur le port 8000 (développement local)
--server --ssl	HTTPS/WSS avec TLS auto-signé sur le port 8443

---

Diffuseur d’Événements (EventBroadcaster)

Important

EventBroadcaster.broadcastEvent() est thread-safe : il peut être appelé depuis n’importe quel thread Python (LLM, TTS, orchestrateur) et utilise asyncio.run_coroutine_threadsafe() pour injecter les messages dans la boucle ASGI.

Module de diffusion et multiplexage temps reel des evenements WebSocket. Fournit une passerelle thread-safe pour envoyer des messages asynchrones depuis des threads de calcul MLX.

class mirza.server.eventBroadcaster.EventBroadcaster

Bases : object

Diffuseur d’evenements temps reel thread-safe pour les clients connectes en WebSocket.

Maintient le registre en memoire de toutes les connexions actives et offre des primitives permettant aux threads d’inference (LLM, STT, TTS) d’emettre des evenements JSON vers la boucle d’evenements asynchrone FastAPI sans risque de blocage.

activeConnections

Ensemble des instances WebSocket actives connectees au serveur.

Type:

set[Any]

eventLoop

Reference vers la boucle d’evenements asyncio principale.

Type:

asyncio.AbstractEventLoop or None

__init__()

Initialise le registre vide des connexions WebSocket.

Type renvoyé:

None

setEventLoop(loop)

Associe la boucle d’evenements asynchrone principale de FastAPI au diffuseur.

Paramètres:

loop (asyncio.AbstractEventLoop) – Boucle d’evenements asyncio en cours d’execution.

Type renvoyé:

None

registerConnection(websocket)

Enregistre une nouvelle connexion client WebSocket active dans le registre.

Paramètres:

websocket (Any) – Instance de la socket cliente connectee (FastAPI / Starlette WebSocket).

Type renvoyé:

None

unregisterConnection(websocket)

Supprime une connexion client deconnectee du registre.

Paramètres:

websocket (Any) – Instance de la socket cliente a retirer.

Type renvoyé:

None

broadcastEvent(eventName, payload)

Envoie un message JSON formate a tous les clients widgets et terminaux connectes.

Cette methode est thread-safe : si elle est appelee depuis un thread de travail (worker thread TTS ou thread d’inference MLX), elle planifie la coroutine d’envoi sur la boucle principale via asyncio.run_coroutine_threadsafe.

Paramètres:

• eventName (str) – Nom canonique de l’evenement (ex: “stateChange”, “thoughtChunk”, “telemetry”).

• payload (dict) – Donnees associees a l’evenement sous forme de dictionnaire serialisable.

Type renvoyé:

None

---

Serveur FastAPI et Passerelle WebSocket (WidgetServer)

Serveur ASGI FastAPI et passerelle WebSocket pour l’interface HUD React de Mirza.

Expose les routes REST pour les metriques, la memoire et le KV Cache, distribue les fichiers statiques du widget React compile, et maintient le canal WebSocket bidirectionnel pour le micro-streaming binaire et le routage multi-clients.

class mirza.server.widgetServer.WidgetServer(orchestrator, host='0.0.0.0', port=8765, enableSsl=False)

Bases : object

Serveur Web unifie distribuant le widget interactif React et l’API WebSocket.

Gere les liaisons full-duplex pour le streaming audio mobile, la telemetrie, et la gestion des certificats SSL/TLS sur reseau local et Tailscale.

Paramètres:

• orchestrator (ConversationOrchestrator) – Reference vers l’orchestrateur conversationnel de Mirza.

• host (str) – Adresse d’ecoute reseau (defaut: « 0.0.0.0 »).

• port (int) – Port d’ecoute TCP (defaut: 8765).

• enableSsl (bool) – Active HTTPS et WSS avec certificats auto-signes (defaut: False).

orchestrator

Orchestrateur de conversation utilise par l’application.

Type:

ConversationOrchestrator

broadcaster

Diffuseur d’evenements temps reel de l’application.

Type:

EventBroadcaster

app

Application ASGI exposee par le serveur.

Type:

FastAPI

__init__(orchestrator, host='0.0.0.0', port=8765, enableSsl=False)

Paramètres:

• orchestrator (ConversationOrchestrator)

• host (str)

• port (int)

• enableSsl (bool)

Type renvoyé:

None

run()

Demarre le serveur Uvicorn avec support HTTPS / WSS en mode bloquant.

Type renvoyé:

None

mirza.server.widgetServer.createWidgetApp(orchestrator, broadcaster)

Instancie et configure l’application FastAPI et les routes WebSocket de Mirza.

Paramètres:

• orchestrator (ConversationOrchestrator) – Orchestrateur central gerant VAD, ASR, LLM et TTS.

• broadcaster (EventBroadcaster) – Diffuseur d’evenements temps reel pour les clients connectes.

Renvoie:

Application ASGI configuree prete a etre servie par Uvicorn.

Type renvoyé:

FastAPI

mirza.server.widgetServer.getLocalIp()

Detecte l’adresse IP locale de la machine hote sur le reseau local (LAN/Wi-Fi).

Renvoie:

Adresse IPv4 locale (ex: « 192.168.1.42 »), ou « 127.0.0.1 » en cas d’echec.

Type renvoyé:

str

mirza.server.widgetServer.getTailscaleInfo()

Detecte l’adresse IP Tailscale IPv4 et le nom DNS de la machine.

Renvoie:

(adresse IPv4 Tailscale, nom DNS MagicDNS). None quand le service est inactif.

Type renvoyé:

tuple[str | None, str | None]

mirza.server.widgetServer.getTailscaleIp()

Detecte l’adresse IP Tailscale IPv4 de la machine.

Renvoie:

Adresse IPv4 Tailscale si le service est actif et connecte, None sinon.

Type renvoyé:

str | None

mirza.server.widgetServer.pcm16ToWavBytes(pcmData, sampleRate=16000)

Encapsule un flux audio brut PCM 16-bit mono dans un conteneur WAV standard RIFF.

Paramètres:

• pcmData (bytes) – Flux d’octets binaires representant les echantillons PCM 16-bit signes.

• sampleRate (int, optional) – Frequence d’echantillonnage en Hertz (defaut: 16000).

Renvoie:

Fichier WAV complet avec en-tete de 44 octets concatene aux donnees PCM.

Type renvoyé:

bytes

---

Gestionnaire de Certificats TLS (SslManager)

Note

SslManager génère un certificat auto-signé X.509 valable 1 an au premier démarrage et le réutilise lors des démarrages suivants. Il dépose les fichiers cert.pem et key.pem dans le répertoire courant de l’application.

Module de generation et gestion automatique des certificats SSL/TLS pour l’acces HTTPS sur reseau local. Permet a Safari iOS et Android Chrome d’autoriser l’acces au microphone du smartphone.

class mirza.server.sslManager.SslManager

Bases : object

Gestionnaire de certificats SSL auto-signes pour HTTPS/WSS sur reseau local.

static ensureCertificates(certsDir='certs', localIp='127.0.0.1', additionalIps=None)

Verifie l’existence des certificats SSL et les genere si necessaire.

Ajoute les extensions SAN (Subject Alternative Name) pour localhost, l’adresse IP locale du Mac et le reseau Tailscale.

Paramètres:

• certsDir (str) – Dossier de stockage des cles et certificats (defaut: « certs »).

• localIp (str) – Adresse IP locale de la machine sur le LAN (defaut: « 127.0.0.1 »).

• additionalIps (list[str] | None) – Adresses IP ou noms d’hotes additionnels (ex: IP Tailscale).

Renvoie:

Chemins des fichiers (certPath, keyPath).

Type renvoyé:

tuple[str, str]