Architecture Backend¶

Backend Python 3.12+ sur GPU Metal Apple Silicon. Coordination via coroutines asyncio et queues en mémoire, sans broker externe.

Vue d’Ensemble ¶

Caractéristique	Valeur
Matériel cible	Apple Silicon (mémoire unifiée UMA)
Langage	Python 3.12+ — convention `camelCase`
Runtime ML	MLX sur GPU Metal (zero-copy CPU↔GPU)
Débit LLM	28–39 tok/s, TTFT ~115–450 ms (décodage spéculatif MTP & APC exact)
Serveur HTTP / WS	FastAPI + Uvicorn (ASGI)
TLS	mkcert (recommandé) ou auto-signé généré à la volée

Arborescence des Modules ¶

mirza/
├── config.py                        Dataclasses de configuration (AppConfig, LlmConfig…)
├── entrypoint.py                    CLI argparse
├── audio/
│   ├── audioProcessor.py            Ring buffer, calcul RMS, pre-roll
│   ├── deviceManager.py             Détection micro/haut-parleur
│   └── vadDetector.py               VAD neural (CPU, <1 ms/chunk)
├── core/
│   ├── memoryManager.py             Télémétrie VRAM Metal, gc.collect()
│   ├── textCleaner.py               StreamingTextFilter, découpage de phrases
│   └── episodicMemory.py            RAG SQLite-vec + RRF
├── engine/
│   ├── factory.py                   Fabrique STT / LLM / TTS
│   ├── interfaces/                  ABC : BaseStt, BaseLlm, BaseTts
│   ├── stt/                         Moteurs STT streaming locaux
│   ├── llm/                         Moteurs LLM locaux (MTP / APC) et distants
│   ├── tts/                         Moteurs TTS locaux souverains et distants
│   └── agent/
│       ├── agentManager.py          CodeAgent smolagents
│       ├── mirzaModelAdapter.py     Bridge MLX↔smolagents
│       └── tools/                   6 outils : web, datetime, metrics, memory
├── pipeline/
│   └── conversationOrchestrator.py  Boucle asyncio, gating voix, métriques TTFT
└── server/
    ├── eventBroadcaster.py          Registre WebSocket thread-safe
    ├── sslManager.py                Génération X.509 auto-signé (fallback)
    └── widgetServer.py              FastAPI, /ws binaire, fichiers statiques

Gestion Mémoire (MemoryManager)¶

Méthode	Description
`initializeEnvironment(vramLimit, cacheLimit)`	Configure les limites Metal via `mlx.core.set_memory_limit()`
`getMemoryStats() → dict`	RAM active, RAM pic, VRAM active, VRAM pic (octets)
`purge()`	`gc.collect()` + `mlx.core.metal.clear_cache()`

Moteur LLM — Speculative Decoding MTP ¶

Métrique	Standard	MTP (MTPLX Turbo)
Débit	~12 tok/s	28–34 tok/s
TTFT	~700–800 ms	~300–450 ms
VRAM	~5.2 Go	~6.8 Go

Module Agentique (AgentManager)¶

Outil	Description
`datetime_info`	Date, heure, fuseau horaire (30+ villes)
`system_metrics`	CPU %, RAM, VRAM Metal
`web_search`	Recherche DuckDuckGo (scraping HTML + Instant Answer)
`visit_webpage`	Extraction texte HTML (3000 chars max, sans JS)
`recall_memory`	Recherche RAG hybride SQLite-vec / FTS5
`save_memory`	Sauvegarde dans SQLite-vec

WebSocket — Événements Sortants ¶

Événement	Payload
`stateChange`	`{ state: "IDLE"\|"LISTENING"\|"PROCESSING"\|"SPEAKING"\|"AGENT" }`
`transcription`	`{ text: "..." }`
`textChunk`	`{ text: "..." }`
`thoughtChunk`	`{ text: "..." }`
`agentDoc`	`{ text: "..." }`
`activeContext`	`{ systemPrompt, ragContext, conversationHistory, kvCacheTokens }`
`memoriesList`	`{ memories: [...], totalCount: N }`
`telemetry`	`{ ramMb, vramMb, tokSec, ttft, ... }`
`audioChunk` (binaire)	`ArrayBuffer` PCM ciblé par `clientTargetId`

Modèles Distants et Préservation VRAM ¶

Lors du passage vers un profil distant (ex: openrouter_nemotron via OpenRouter), le modèle local n’est pas déchargé de la VRAM. Le moteur local (daemon MTPLX ou modèle MLX) reste conservé en cache mémoire (_cachedLocalEngine). Cette conception offre des avantages majeurs :

Switch instantané vers le Cloud : aucun délai de libération, l’agent et le pipeline routent directement leurs requêtes vers l’API distante.
Retour instantané (0 ms) vers le local : réassignation immédiate du moteur local sans aucune phase de rechargement ni de compilation Metal.
Isolation stricte de la mémoire RAG : la mémoire épisodique locale est automatiquement désactivée sur les modèles distants afin de garantir la stricte confidentialité des données cliniques et personnelles.

Le plafond de tokens document agent est adaptatif selon les profils (512 à 2048 tokens).

Configuration des Modèles ¶

Via mirza/config.py ou le sélecteur de profil du HUD :

LLM : Choix du moteur d’inférence (local Turbo MTP, local Fast APC, distant)
STT : Moteur de transcription vocale locale streaming
TTS : Moteur de synthèse vocale locale ou distante
RAG : Modèles d’embedding et de reranking locaux