Module Cœur (mirza.core)

Le module mirza.core fournit les deux composants transversaux fondamentaux de la plateforme : la gestion de la mémoire unifiée Apple Silicon et le filtrage de texte en streaming temps réel.

---

Gestionnaire de Mémoire Unifiée (MemoryManager)

Important

MemoryManager utilise l’API C++ Metal exposée par MLX pour interroger directement la consommation en Unified Memory. Ces métriques sont propres à Apple Silicon et ne sont pas disponibles sur d’autres architectures.

Méthodes clés du MemoryManager

Méthode	Description
initializeEnvironment(vramLimitBytes, cacheLimit)	Configure les limites Metal et les préférences de cache MLX
getMemoryStats() → dict	Retourne ramMb, ramTotalMb, vramActiveMb, vramPeakMb
purge()	Libère les caches Metal et déclenche gc.collect()

Module de supervision et d’optimisation de la memoire unifiee Apple Silicon (UMA). Permet de controler les allocations Metal MLX et de surveiller l’empreinte RAM/VRAM.

mirza.core.memoryManager.PURGE_MIN_INTERVAL_SECONDS = 15.0

Intervalle minimal entre deux purges automatiques.

class mirza.core.memoryManager.MemoryManager

Bases : object

Gestionnaire centralise de la memoire unifiee (RAM CPU + VRAM Metal GPU) pour Apple Silicon.

Sur les SoC Apple (M1/M2/M3/M4), le CPU et le GPU partagent le meme espace physique de memoire vive unifiee. Module interroge les compteurs du framework MLX (Metal C++) et de psutil pour une telemetrie precise, et declenche la liberation proactive des allocations non utilisees.

mtplxPort: int = 0

Port du daemon MTPLX, renseigne a l’initialisation. 0 desactive l’appel.

static initializeEnvironment(vramLimitBytes=17179869184, cacheLimit=0, mtplxPort=0, purgeThresholdGb=0.0)

Configure les limites materielles Metal MLX pour empecher tout debordement de cache.

Paramètres:

• vramLimitBytes (int, optional) – Limite maximale d’allocation Metal en octets. Defaut : 16 Go (16 * 1024**3).

• cacheLimit (int, optional) – Limite de mise en cache Metal. Defaut : 0, ce qui evite la retention prolongee de tenseurs temporaires.

• mtplxPort (int, optional) – Port du daemon MTPLX. 0 desactive l’appel de vidage de cache.

• purgeThresholdGb (float, optional) – Seuil de RSS declenchant une purge automatique. Defaut : 80 % de la limite memoire unifiee.

Type renvoyé:

None

static getGpuUtilization()

Interroge l’IOAccelerator via ioreg pour la charge GPU Metal.

Renvoie:

Pourcentage d’utilisation, ou 0 si la lecture echoue.

Type renvoyé:

int

classmethod getMemorySnapshot()

Capture un instantane exhaustif de l’etat memoire UMA sur Apple Silicon.

Renvoie:

Dictionnaire contenant les metriques memoire cles.

Type renvoyé:

dict[str, float]

classmethod displayMemoryProfile(stepName='Actuelle')

Affiche dans le logger l’empreinte memoire formatee et lisible.

Paramètres:

stepName (str, optional) – Nom de l’etape de cycle de vie. Defaut : « Actuelle ».

Type renvoyé:

None

classmethod shouldPurge()

Indique si la memoire est sous une pression qui justifie une purge.

La purge n’est gratuite ni en temps ni en cache : mx.clear_cache() jette les tampons reutilises par Metal, ce qui oblige a les reconstruire au tour suivant. On ne purge donc que lorsqu’il y a vraiment lieu, et au plus une fois par intervalle.

Renvoie:

True s’il faut liberer maintenant.

Type renvoyé:

bool

classmethod purgeMemory(force=False)

Libere les caches Metal et execute le ramasse-miettes Python.

Paramètres:

force (bool, optional) – Si False (defaut), ne purge que sous pression memoire reelle. Si True, purge inconditionnellement, comme le demande un arret ou une action explicite de l’utilisateur.

Type renvoyé:

None

---

Filtre de Texte en Streaming (StreamingTextFilter)

Le StreamingTextFilter est le composant central de séparation des canaux. Il analyse le flux de tokens LLM au fur et à mesure de leur génération et dirige chaque fragment vers le bon canal de sortie.

Canaux de sortie gérés par StreamingTextFilter

Type de fragment	Balises détectées	Destination
Pensée CoT	<think>…</think> · <|channel>thought…<channel|> · <thought>…</thought>	onThought(chunk) → thoughtChunk WebSocket
Résultat agentique	<result>…</result>	onResultDoc(content) → agentResultDoc WebSocket
Voix épurée	Tout le reste	Retourné comme chaîne par processChunk()

Note

Le filtre est conçu pour être sans état inter-tours : il maintient un buffer interne minimaliste de 12 à 15 caractères pour gérer les balises coupées entre deux chunks consécutifs.

Module facade pour le nettoyage de texte, le filtrage de flux et les parseurs.

Re-exporte les composants scindes vers : - mirza.core.textNormalizer : normalisation phonetique et nettoyage TTS (TextCleaner) - mirza.core.streamParsers : parseurs de flux temps reel (StreamingTextFilter, FinalAnswerStreamParser)

class mirza.core.textCleaner.FinalAnswerStreamParser(on_speech_chunk, on_thought_chunk=None)

Bases : object

Parseur temps reel des tokens du LLM lors de l’etape de synthese agentique smolagents.

Paramètres:

• on_speech_chunk (Callable[[str], None])

• on_thought_chunk (Callable[[str], None] | None)

__init__(on_speech_chunk, on_thought_chunk=None)

Initialise le parseur de tokens agentiques.

Paramètres:

• on_speech_chunk (Callable[[str], None]) – Fonction appelee avec les morceaux de texte oral detectes.

• on_thought_chunk (Callable[[str], None] | None, optional) – Fonction appelee avec les morceaux de raisonnement ou appels d’outils.

Type renvoyé:

None

process_chunk(chunk)

Analyse un jeton du flux agentique pour detecter la reponse finale.

Paramètres:

chunk (str) – Jeton ou bloc textuel emis par le LLM lors de l’appel de final_answer.

Type renvoyé:

None

finalize()

Traite les residus si la generation s’est arretee avant la fermeture.

Type renvoyé:

None

hasStreamedSpeech()

Indique si des fragments de discours ont ete transmis a la synthese.

Renvoie:

True si au moins un fragment vocal a ete emis, False sinon.

Type renvoyé:

bool

class mirza.core.textCleaner.StreamingTextFilter(onThought=None, onResultDoc=None, onDocActive=None, maxThoughtTokens=0, initialThinkingActive=False)

Bases : object

Filtre en flux continu les balises XML/Markdown et les blocs de pensee.

Isole en temps reel les flux CoT, les documents riches et le texte parlable.

Paramètres:

• onThought (Callable[[str], None] | None)

• onResultDoc (Callable[[str], None] | None)

• onDocActive (Callable[[bool], None] | None)

• maxThoughtTokens (int)

• initialThinkingActive (bool)

__init__(onThought=None, onResultDoc=None, onDocActive=None, maxThoughtTokens=0, initialThinkingActive=False)

Initialise les tampons et callbacks du filtre de flux textuel.

Paramètres:

• onThought (Callable[[str], None] | None, optional) – Fonction appelee a chaque token de pensee CoT detecte.

• onResultDoc (Callable[[str], None] | None, optional) – Fonction appelee avec le contenu documentaire extrait des balises <result>, <code> ou <code_view>.

• onDocActive (Callable[[bool], None] | None, optional) – Fonction appelee avec un booleen signalant le debut/fin de generation d’un bloc de resultat/code.

• maxThoughtTokens (int, optional) – Nombre maximum de tokens de reflexion autorises. Defaut : 0.

• initialThinkingActive (bool, optional) – True si le LLM demarre directement en mode pensee, sans balise ouvrante explicite. Defaut : False.

Type renvoyé:

None

processChunk(chunk)

Traite un fragment de texte en continu et retourne le texte parlable filtre.

Paramètres:

chunk (str) – Fragment ou jeton textuel brut emis par le LLM.

Renvoie:

Texte epure des balises de pensee et de resultats, pret pour la voix ou l’affichage.

Type renvoyé:

str

finalize()

Vide les residus du buffer en fin de generation.

Renvoie:

Texte residuel nettoye pour la synthese vocale ou vide si aucun residu utile.

Type renvoyé:

str

class mirza.core.textCleaner.TextCleaner

Bases : object

Utilitaire de nettoyage et de normalisation textuelle pour STT, LLM et TTS.

noisePhrases: ClassVar[set[str]] = {'.', '..', '...', 'D.D.', 'DD', 'Euh', 'Merci.', 'Sous-titrage', 'Sous-titres', 'Sous-titres réalisés par', 'Transcrit par', 'd.d.', 'dd', 'euh'}

EMOJI_PATTERN = re.compile('[\\U00010000-\\U0010ffff\\u2600-\\u26ff\\u2700-\\u27bf\\ufe00-\\ufe0f\\u200d]+')

classmethod stripEmojis(text)

Supprime tous les emojis et pictogrammes d’une chaine de caracteres.

Paramètres:

text (str) – Chaine source potentiellement porteuse d’emojis.

Renvoie:

Chaine assainie depourvue d’emojis.

Type renvoyé:

str

classmethod cleanSttText(text)

Nettoie et assainit le texte transcrit par le moteur STT.

Deduplonne les begaiements acoustiques de l’ASR (ex: “de de”, “propos propos”) sans toucher aux formes pronominales (“nous nous”, “vous vous”), puis normalise espaces et ponctuations multiples.

Paramètres:

text (str) – Texte brut issu du moteur STT.

Renvoie:

Texte nettoye, sans begaiements ni artefacts de ponctuation.

Type renvoyé:

str

classmethod isNoiseTranscription(text)

Detecte si une transcription ne contient que des artefacts ou du bruit.

Paramètres:

text (str) – Texte issu du moteur STT.

Renvoie:

True si le texte est du bruit sans valeur semantique, False sinon.

Type renvoyé:

bool

classmethod cleanForTts(rawText)

Nettoie le texte genere pour l’optimiser pour la synthese vocale TTS.

Paramètres:

rawText (str) – Texte brut genere par le LLM.

Renvoie:

Texte nettoye, sans balises ni markdown, optimise pour la diction orale.

Type renvoyé:

str

---

Mémoire Épisodique & RAG (EpisodicMemoryStore)

Le EpisodicMemoryStore gère l’archivage vectoriel local persistant avec SQLite-vec, les embeddings locaux vectoriels et le reclassement par rang réciproque (RRF) combiné avec la recherche lexicale SQLite FTS5.

Memoire episodique et semantique de Mirza : RAG local, hybride, reranked RRF.

Combine SQLite (relationnel + vectoriel sqlite-vec), FastEmbed et la fusion de rangs reciproques (Reciprocal Rank Fusion) pour un enrichissement contextuel de moins de 4 ms d’overhead par tour.

class mirza.core.episodicMemory.EpisodicMemoryStore(dbPath='mirza/data/memory.db', embeddingModel='sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2', embeddingDim=384, similarityThreshold=0.1, maxContextTokens=600, topKRetrieval=8, topKRerank=2)

Bases : object

Gestionnaire de base de donnees vectorielle et relationnelle locale pour Mirza.

Indexe des souvenirs episodiques (tours de conversation, faits cles, resumes) et recupere les contextes les plus pertinents par reranking hybride (dense + BM25, fusion RRF).

Paramètres:

• dbPath (str, optional) – Chemin vers le fichier de base SQLite. Defaut : « mirza/data/memory.db ».

• embeddingModel (str, optional) – Identifiant HuggingFace du modele d’embedding. Defaut : « sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ».

• embeddingDim (int, optional) – Dimension des vecteurs d’embedding dense. Defaut : 384.

• similarityThreshold (float, optional) – Score cosinus minimum (1 - dist) pour juger un souvenir pertinent. Defaut : 0.35.

• maxContextTokens (int, optional) – Nombre maximal approximatif de tokens injectes dans le prompt. Defaut : 600.

• topKRetrieval (int, optional) – Nombre de candidats extraits par source (dense et sparse). Defaut : 8.

• topKRerank (int, optional) – Nombre final de souvenirs retenus apres fusion RRF. Defaut : 2.

__init__(dbPath='mirza/data/memory.db', embeddingModel='sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2', embeddingDim=384, similarityThreshold=0.1, maxContextTokens=600, topKRetrieval=8, topKRerank=2)

Paramètres:

• dbPath (str)

• embeddingModel (str)

• embeddingDim (int)

• similarityThreshold (float)

• maxContextTokens (int)

• topKRetrieval (int)

• topKRerank (int)

Type renvoyé:

None

warmUp()

Prechauffe le modele d’embedding ONNX pour eliminer tout surcout au premier tour.

Type renvoyé:

None

storeTurn(userInput, assistantResponse, summary=None, metadata=None)

Archive un tour de conversation complet dans la memoire a long terme.

Paramètres:

• userInput (str) – Texte de l’enonce soumis par l’utilisateur.

• assistantResponse (str) – Reponse textuelle generee par l’assistant.

• summary (str | None, optional) – Resume concis du tour. Defaut : None.

• metadata (str | None, optional) – Metadonnees contextuelles additionnelles. Defaut : None.

Renvoie:

Identifiant entier de la ligne inseree ou None en cas d’echec.

Type renvoyé:

int | None

retrieveRelevantContext(query, topK=None)

Recherche semantique hybride (Dense cosine distance sqlite-vec + Lexical BM25 FTS5).

Paramètres:

• query (str) – Requete ou invite textuelle pour la recherche semantique.

• topK (int | None, optional) – Nombre de candidats extraits par canal. Defaut : None, ce qui utilise topKRetrieval.

Renvoie:

Liste des souvenirs ordonnes par score RRF decroissant.

Type renvoyé:

list[dict[str, Any]]

reindexAll()

Recalcule tous les vecteurs pour realigner la memoire sur le modele d’embedding courant.

Renvoie:

Nombre de souvenirs reindexes.

Type renvoyé:

int

formatMemoryContext(query)

Recupere les contextes pertinents et les formate pour injection dans le prompt.

Paramètres:

query (str) – Entree utilisateur courante.

Renvoie:

Bloc formate sous [Memo context : …] ou chaine vide si aucun souvenir pertinent.

Type renvoyé:

str

count()

Retourne le nombre total de souvenirs archives.

Renvoie:

Nombre d’enregistrements en base.

Type renvoyé:

int

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

Liste les souvenirs stockes avec pagination.

Paramètres:

• query (str | None, optional) – Filtre de recherche plein texte. Defaut : None.

• limit (int, optional) – Nombre d’elements par page. Defaut : 50.

• offset (int, optional) – Indice de depart. Defaut : 0.

Renvoie:

Liste des souvenirs trouves.

Type renvoyé:

list[dict[str, Any]]

deleteMemory(memoryId)

Supprime un souvenir specifique par son identifiant.

Paramètres:

memoryId (int) – Identifiant du souvenir a supprimer.

Renvoie:

True si la suppression a reussi, False sinon.

Type renvoyé:

bool

mirza.core.episodicMemory.EpisodicMemory

alias de EpisodicMemoryStore