.. _quickstart:

Guide de Démarrage Rapide
=========================

Prérequis Matériel & Logiciel
------------------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Prérequis
     - Détail
   * - **Mac Apple Silicon**
     - M1, M2, M3 ou M4 recommandé — mémoire unifiée ≥ 16 Go
   * - **Python**
     - >= 3.12 (supporté jusqu'à Python 3.14 avec ``uv``)
   * - **uv** (gestionnaire de paquets)
     - ``curl -Ls https://astral.sh/uv/install.sh | sh``
   * - **Node.js + npm**
     - ≥ 18 LTS (pour le build du frontend React)
   * - **Navigateur**
     - Safari, Chrome ou Firefox (WebSocket + WebAudio requis)

Installation
-------------

.. code-block:: bash

   # 1. Cloner le dépôt
   git clone https://github.com/Petrichoeur/mirza.git
   cd mirza

   # 2. Créer l'environnement Python et installer les dépendances
   uv sync

   # 3. Builder le frontend React (widget HUD)
   cd widget && npm install && npm run build && cd ..

Lancement du Serveur
--------------------

.. code-block:: bash

   # Mode HTTP standard
   uv run python main.py --server

   # Mode HTTPS/WSS (TLS)
   uv run python main.py --server --ssl

   # Spécifier un port personnalisé
   uv run python main.py --server --ssl --port 9000

Options CLI Disponibles
-----------------------

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Option
     - Description
   * - ``--server``
     - Lance le serveur WebSocket FastAPI et sert le widget React
   * - ``--ssl``
     - Active TLS (utilise ``certs/cert.pem`` ou génère un auto-signé)
   * - ``--port PORT``
     - Port d'écoute (défaut : 8765)
   * - ``--text-only``
     - Désactive ASR et TTS (mode saisie texte uniquement)
   * - ``--benchmark``
     - Affiche l'empreinte mémoire UMA et quitte
   * - ``--purge``
     - Purge la mémoire VRAM Metal et quitte

Accès à l'Interface
-------------------

Une fois le serveur lancé :

* **Sur le Mac hôte** : ``https://127.0.0.1:8765``
* **Sur le réseau local (LAN)** : ``https://<IP_DU_MAC>:8765``
* **À distance (Tailscale)** : ``https://<IP_TAILSCALE>:8765`` (voir :ref:`acces-distant`)