.. _api-core:

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.

.. contents:: Sommaire
   :local:
   :depth: 1

----

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.

.. list-table:: Méthodes clés du MemoryManager
   :widths: 45 55
   :header-rows: 1

   * - 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()``

.. automodule:: mirza.core.memoryManager
   :members:
   :undoc-members:
   :show-inheritance:

----

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.

.. list-table:: Canaux de sortie gérés par StreamingTextFilter
   :widths: 35 35 30
   :header-rows: 1

   * - 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.

.. automodule:: mirza.core.textCleaner
   :members:
   :undoc-members:
   :show-inheritance:

----

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.

.. automodule:: mirza.core.episodicMemory
   :members:
   :undoc-members:
   :show-inheritance: