.. _api-engine:

Module Moteurs et Inférence (``mirza.engine``)
===============================================

Le module ``mirza.engine`` regroupe toutes les abstractions et implémentations des moteurs
d'inférence IA : transcription (STT), génération de texte (LLM) et synthèse vocale (TTS),
ainsi que le module agentique complet.

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

----

Comparatif des Moteurs Disponibles
------------------------------------

.. list-table:: Moteurs STT
   :widths: 30 25 45
   :header-rows: 1

   * - Moteur
     - Type
     - Caractéristiques
   * - ``MlxNemotronStt``
     - STT Principal
     - Prioritaire — streaming temps réel, latence < 200 ms, optimisé ANE
   * - ``MlxWhisperStt``
     - STT Alternatif
     - Fallback — robustesse multilingue, transcription hors-ligne

.. list-table:: Moteurs LLM
   :widths: 30 25 45
   :header-rows: 1

   * - Moteur
     - Type
     - Caractéristiques
   * - ``MtplxLlm``
     - LLM Local Turbo
     - Runtime haute vitesse, Paged Attention GPU Metal, décodage spéculatif intégré (28–39 tok/s, TTFT ~115–450 ms)
   * - ``OpenRouterLlm``
     - LLM Distant
     - Routeur API distant haute capacité (switch instantané avec conservation du modèle local en mémoire)
   * - ``MlxQwenLlm``
     - LLM Local MLX
     - Inférence MLX locale avec décodage spéculatif + APC et pré-amorçage exact

.. list-table:: Moteurs TTS
   :widths: 30 25 45
   :header-rows: 1

   * - Moteur
     - Backend
     - Caractéristiques
   * - ``KokoroTts``
     - TTS Local
     - Moteur vocal par défaut — 100% local, souverain et hors-ligne
   * - ``EdgeTts``
     - TTS Distant
     - Repli cloud optionnel — haute fidélité vocale
   * - ``MeloTts``
     - TTS Alternatif
     - Synthèse locale alternative optimisée

----

Fabrique Centrale (``EngineFactory``)
--------------------------------------

.. automodule:: mirza.engine.factory
   :members:
   :undoc-members:
   :show-inheritance:

----

Interfaces Abstraites
----------------------

.. automodule:: mirza.engine.interfaces.baseStt
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: mirza.engine.interfaces.baseLlm
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: mirza.engine.interfaces.baseTts
   :members:
   :undoc-members:
   :show-inheritance:

----

Implémentations STT
--------------------

.. automodule:: mirza.engine.stt.mlxNemotronStt
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: mirza.engine.stt.mlxWhisperStt
   :members:
   :undoc-members:
   :show-inheritance:

----

Implémentations LLM
---------------------

.. automodule:: mirza.engine.llm.mtplxLlm
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: mirza.engine.llm.mlxQwenLlm
   :members:
   :undoc-members:
   :show-inheritance:

----

Implémentations TTS
--------------------

.. automodule:: mirza.engine.tts.edgeTts
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: mirza.engine.tts.kokoroTts
   :members:
   :undoc-members:
   :show-inheritance:

----

Module Agentique (``mirza.engine.agent``)
------------------------------------------

.. list-table:: Outils du registre agentique
   :widths: 20 20 60
   :header-rows: 1

   * - Identifiant
     - Nom UI
     - Description
   * - ``datetime_info``
     - Horloge & Calendrier
     - Date, heure, fuseau horaire avec 30+ correspondances intégrées
   * - ``system_metrics``
     - Télémétrie Matérielle
     - CPU %, RAM, VRAM Metal via psutil + MLX
   * - ``web_search``
     - Recherche Web
     - DuckDuckGo scraping HTML + fallback Instant Answer JSON
   * - ``visit_webpage``
     - Exploration Web
     - Extraction texte HTML (3000 chars max) sans exécution JS
   * - ``recall_memory``
     - Mémoire Épisodique & Passé
     - Recherche dans les souvenirs et faits passés de Mirza via RAG hybride SQLite-vec / FTS5
   * - ``save_memory``
     - Enregistrement Mémoire
     - Sauvegarde explicite d'un fait dans la base SQLite-vec

.. automodule:: mirza.engine.agent.agentManager
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: mirza.engine.agent.mirzaModelAdapter
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: mirza.engine.agent.tools
   :members:
   :undoc-members:
   :show-inheritance: