Funk-lab/docs/stt-presentation.md

Asa — l'assistant vocal de Funk (STT client‑serveur)

Asa est l'interface vocale et graphique du homelab Funk : un assistant type Jarvis qui écoute, parle, affiche un HUD animé, et — surtout — agit comme une véritable agente sur le homelab. Elle sait (doc + état live), cherche (web) et agit (avec confirmation).

Architecture client‑serveur : un client stt (pipx) tourne sur le poste (voix + HUD) ; le « cerveau » est un STT‑server déployé dans le cluster (namespace ai, exposé stt.lab.local).

Code	client stt/client/ · serveur stt/server/
Déploiement	client : pipx + service systemd --user · serveur : image GHCR → ArgoCD
Modèle	100 % local — Qwen3‑8B via LiteLLM (function calling natif)
Doc de référence	admin/ia/stt.md

---

Le HUD en images

Conversation (Asa agentique)	Veille / réveil vocal
Asa sonde l'état live (« gpu‑01 tourne bien ? » → CPU/RAM/disque/GPU) puis fait une recherche web — chaque réponse taguée asa. État RÉPONSE : anneau arc‑reactor actif.	« Asa, stop » → état SOMMEIL : portrait désaturé, Asa n'écoute plus que le mot de réveil. Dire « Asa » la rallume.

Le portrait affiche le repli « あ » (Asa en hiragana) tant qu'aucun jeu d'avatars n'est déposé dans stt/client/stt/hud/avatars/ (cf. son README). Thème arc‑reactor, réglable dans le HUD.

---

Architecture — la chaîne de bout en bout

flowchart LR
    subgraph POSTE["Poste perso — client stt (pipx)"]
        MIC["Micro"] --> VAD["VAD + wake word<br/>« Asa » / « Asa stop »"]
        VAD --> ASR["ASR local<br/>whisper / Parakeet (onnx)"]
        ASR --> API["api.py → ServerClient"]
        REPLY["Réponse"] --> TTS["TTS Piper"]
        REPLY --> HUD["HUD web<br/>bulles, portrait, portail"]
    end

    subgraph CLUSTER["Cluster k8s — namespace ai"]
        SRV["STT-server (FastAPI)<br/>stt.lab.local"]
        SRV --> LOOP["brain.ask_with_tools<br/>function calling (contexte asa)"]
        LOOP --> TOOLS["tools.py"]
    end

    API -->|"POST /v1/ask"| SRV
    SRV -->|"reply + trace"| REPLY

    LOOP -->|"inférence + tool_calls"| LITELLM["LiteLLM :4000<br/>storage-01"]
    LITELLM --> QWEN["Qwen3-8B<br/>gpu-01 :1234"]

    TOOLS -->|"host_health / cluster_status / prometheus_query"| PROM["Prometheus<br/>in-cluster"]
    TOOLS -->|"search_docs"| QDRANT["Qdrant RAG<br/>funk-docs (s01)"]
    TOOLS -->|"web_search"| SEARX["SearXNG<br/>in-cluster, privé"]
    TOOLS -->|"admin_action ⇒ confirmation"| HEXEC["hermes-exec :9096<br/>hermes -z --yolo (s01)"]

    classDef poste fill:#fde,stroke:#c69;
    classDef cluster fill:#def,stroke:#69c;
    class POSTE poste
    class CLUSTER cluster

Principe : le poste ne fait que la voix (STT/TTS) et l'affichage. Toute l'intelligence est côté serveur, qui orchestre LiteLLM et choisit ses outils. Aucune dépendance cloud : modèle, recherche web et données sont tous self‑host.

---

Le tour d'une question vocale (séquence)

sequenceDiagram
    actor U as Utilisateur
    participant C as Client stt (poste)
    participant S as STT-server (cluster)
    participant L as LiteLLM puis Qwen3-8B
    participant T as Outils (Prom/SearXNG/RAG)

    U->>C: « Asa, est-ce que gpu-01 tourne bien ? »
    Note over C: wake word détecté puis ASR (texte)
    C->>S: POST /v1/ask {text, context:"asa"}
    Note over S: recall mémoire (Qdrant) + assemblage prompt
    S->>L: chat + tools (function calling)
    L-->>S: tool_call host_health(gpu-01)
    S->>T: PromQL (up, CPU, RAM, disque, GPU)
    T-->>S: « en ligne, GPU 61 °C, 99 % »
    S->>L: résultat de l'outil réinjecté
    L-->>S: réponse finale en français
    S-->>C: reply + trace des outils
    C->>U: TTS Piper + bulle dans le HUD

Si Asa veut agir (admin_action), la boucle s'arrête et elle propose ; l'exécution (hermes‑exec) n'a lieu qu'au tour suivant, après un « confirme » vocal.

---

Ce qu'Asa sait faire

🗣️ Liste complète des demandes possibles (exemples de phrases) : asa-commandes.md.

Capacité	Comment	Outils / sources
🔎 Savoir	Doc Funk + état live du homelab, l'outil est choisi par le modèle	search_docs (RAG), host_health, cluster_status, prometheus_query
🌐 Chercher	Recherche Internet privée (méta‑moteur self‑host)	web_search → SearXNG
🤖 Agir	Actions d'admin avec confirmation vocale + jeton	admin_action → hermes‑exec
🧠 Se souvenir	Mémoire court terme (session) + long terme (Qdrant)	stt-memory
🗣️ Veille/réveil	« Asa » réveille · « Asa stop » endort	machine à états côté client
🧩 Contextes	Profils présélectionnables (funk, ghostfolio, grafana, alerting, cluster)	contexts.py

---

Où vivent les choses

stt/
├── client/                 # commande `stt` (pipx) — poste perso
│   └── stt/
│       ├── voice/engine.py # micro, VAD, wake word, ASR, TTS
│       ├── api.py          # client HTTP vers le STT‑server
│       └── hud/index.html  # le HUD (portrait, bulles, portail, visualiseur)
└── server/                 # image conteneur — déployée par ArgoCD (ns ai)
    └── stt_server/
        ├── app.py          # API FastAPI (/v1/ask, /v1/contexts…)
        ├── brain.py        # appel LiteLLM + boucle de function‑calling
        ├── tools.py        # outils : doc, état live, web, action
        ├── contexts.py     # profils (dont « asa » = boucle d'outils)
        ├── sources.py      # sondes Prometheus / Alertmanager / Ghostfolio
        ├── knowledge.py    # RAG funk‑docs (Qdrant)
        └── longterm.py     # mémoire long terme (Qdrant)

Manifests k8s : k8s/apps/stt/ (STT‑server) et k8s/apps/searxng/ (recherche web). Détails et pièges : admin/ia/stt.md.

Capturer ses propres écrans du HUD : déposer un jeu d'avatars dans stt/client/stt/hud/avatars/, lancer le client, et capturer les états (idle, écoute, réponse, portail, visualiseur). Les deux images ci‑dessus ont été rendues depuis le HUD réel.