Funk-lab/admin/ia/stt.md

STT — Assistant vocal "Jarvis" du homelab Funk

STT est l'interface vocale et graphique de Funk : un assistant type Jarvis / Iron Man qui écoute, parle, affiche un HUD animé, et agit sur le homelab via Hermes Agent. Il s'installe sur le poste perso comme une commande unique (stt) et démarre au boot.

Nom de code : STT. À l'origine « Speech-To-Text », mais le projet couvre toute la chaîne voix → cerveau → voix + interface + mémoire. Renommable plus tard sans impact technique (FRIDAY, etc.) — c'est juste un identifiant de répertoire/commande.

⚠️ Conception validée (2026-06-17) — squelette en place, implémentation par phases (voir Roadmap). Aucun composant n'est encore déployé sur le poste.

---

Principe directeur : réutiliser, ne pas réinventer

~70 % du backend existe déjà dans Funk. STT n'ajoute que le visage (HUD), la personnalisation, la mémoire multi-tiers et le packaging en commande.

Besoin Jarvis	Brique Funk réutilisée	État
Modèle local ou Claude	LiteLLM :4000 + hermes-default + hermes-switch qwen|claude	✅ opérationnel
Agir sur le homelab	Hermes Agent (:8080, profils funk-ai/system/monitor/brain)	✅ opérationnel
Voix (STT + TTS + wake word)	tools/hermes-voice/ — faster-whisper + Piper + webrtcvad	✅ existe (CLI only)
Démarrage auto au boot	pattern systemd --user (tools/hermes-voice/install-service.sh)	✅ éprouvé
Mémoire sémantique	Qdrant :6333 + RAG (rag-query/rag-ingest) sur s01	⚠️ HS depuis 05/06

Maillon réellement manquant : l'interface graphique HUD + le packaging + la mémoire perso.

---

Décisions d'architecture (verrouillées 2026-06-17)

Décision	Choix retenu
Interface	HUD web sur-mesure (canvas/WebGL) + backend Python local
STT / TTS	Local sur le poste (faster-whisper CPU + Piper)
Packaging	Commande stt via pipx (pipx install git+…#subdirectory=stt)
Cerveau	3 modes + auto-détection LAN (voir ci-dessous)
Mémoire	3 tiers : local (SQLite) + s01 (Qdrant) + GitHub (distillée, versionnée)

---

Architecture

┌─ POSTE PERSO — commande `stt` (systemd --user, démarrage auto) ─────┐
│                                                                      │
│   ┌──────────────┐   websocket    ┌───────────────────────────┐    │
│   │  HUD web      │ ◀────────────▶ │  backend `stt` (Python)    │    │
│   │  (kiosk)      │   états +      │  • micro + VAD + wake word │    │
│   │  • visualiseur│   transcript   │  • faster-whisper (STT)    │    │
│   │  • avatar     │   + réponses   │  • Piper (TTS)             │    │
│   │  • thème      │                │  • routeur cerveau (3 modes)│   │
│   │  • réglages   │                │  • gestionnaire mémoire     │   │
│   └──────────────┘                └───┬─────────────┬──────────┘    │
│                                        │             │               │
│                            mémoire     │             │ cerveau       │
│                   ┌────────────────────┘             │               │
│                   ▼                                   ▼               │
│            SQLite local + cache              (selon mode + LAN)       │
│            git pull/push GitHub                                       │
└───────────────────────────────────────────────────┼─────────────────┘
                                                      │ LAN (192.168.1.200)
                  ┌───────────────────────────────────┼──────────────────┐
                  ▼                    ▼                ▼                  ▼
           Hermes :8080          LiteLLM :4000     Qdrant :6333      API Anthropic
           (mode hermes)        (mode local-direct) (mémoire s01)   (mode claude-direct,
            agit sur Funk        chat g01/Claude     sémantique       hors-LAN, chat seul)

Le cerveau — 3 modes + auto-détection

Au démarrage (et périodiquement), stt ping s01 (192.168.1.200) :

Mode	Déclenché quand	Chemin	Agit sur Funk ?	Coût
hermes	LAN OK (défaut maison)	PC → Hermes :8080 (route Qwen3 g01 ou Claude via hermes-switch)	✅ oui	gratuit/local sauf si switch claude
local-direct	LAN OK, chat pur voulu	PC → LiteLLM :4000 (Qwen3 g01)	❌ chat seul	gratuit
claude-direct	hors-LAN (nomade)	PC → API Anthropic (clé locale)	❌ (Funk injoignable)	facturé

Clé de lecture : « agir sur Funk » vit dans Hermes (sur s01). À la maison, même pour l'intelligence de Claude, on passe par Hermes (hermes-switch claude) → pouvoirs Funk conservés. Le mode claude-direct est le fallback nomade (Funk inatteignable de toute façon). Auto-détection par défaut, override manuel dans les réglages.

La mémoire — 3 tiers

Tier	Support	Contenu	Disponibilité
Local	SQLite + cache (stt/memory/ local, gitignoré)	Historique brut récent, working memory	Toujours (offline)
s01	Qdrant :6333, collection dédiée STT	Mémoire sémantique long-terme, partagée avec le RAG Funk	Sur LAN
GitHub	stt/memory/distilled/ (versionné)	Mémoire distillée : faits, préférences, résumés — source de vérité portable	Via git pull/push

Flux de synchro :

1. Démarrage → git pull la mémoire distillée GitHub → charge en local.
2. Pendant l'usage → écriture immédiate en SQLite local.
3. Périodiquement / à l'arrêt → distillation (résumé via le cerveau) → git commit GitHub + (si LAN) embedding dans Qdrant s01.
4. Sur nouveau poste / réinstall → GitHub re-seed local + Qdrant.

⚠️ Vie privée : seule la mémoire distillée est committée (faits/préférences). Les transcripts bruts restent locaux et gitignorés. Repo privé impératif.

---

Composants

Composant	Emplacement	Description
Commande stt	stt/pyproject.toml → entrypoint	stt (lance), stt --setup (install Whisper/Piper/voix), stt --stop, stt --mode <hermes|local|claude>
Backend	stt/stt/ (package Python)	Extension de tools/hermes-voice.py : wake word, STT, TTS, routeur cerveau, mémoire, serveur websocket
HUD web	stt/hud/	Front statique (HTML/JS/canvas) : visualiseur animé, conversation, écran de réglages. Servi localement, ouvert en kiosk
Config	stt/config/	stt.example.toml + thèmes, avatars, voix Piper
Mémoire	stt/memory/	distilled/ versionné + raw local gitignoré
Auto-start	stt/install-service.sh	systemd --user : backend + ouverture HUD au login
(opt.) cluster	k8s/apps/stt/	Phase 6 : STT/TTS déportés en Wyoming sur gpu-01

---

Personnalisation (« l'image, le design, la voix »)

Pilotable depuis stt/config/ + l'écran de réglages du HUD, sans recompiler :

• Avatar / image : asset swappable (config/avatars/).
• Thème / design : couleurs, fond, style du visualiseur (config/themes/).
• Voix : modèle Piper .onnx interchangeable (config/voices/), fr_FR par défaut.
• Wake word : configurable (défaut « Ok Hermès »).
• Cerveau : mode par défaut + override, clé API Anthropic locale (pour claude-direct).

---

Prérequis / dépendances

• Poste : micro, Python 3.11+, pipx, navigateur (kiosk). stt --setup gère Whisper/Piper/voix.
• LAN : accès 192.168.1.200 (s01) pour modes hermes/local-direct + Qdrant.
• Qdrant réparé requis pour la mémoire tier s01 (crash-loop depuis 05/06, voir admin/incidents.md). Non bloquant : MVP fonctionne avec mémoire locale + GitHub seules.
• Clé Anthropic locale (poste) pour le mode claude-direct nomade.

---

Roadmap

Phase	Objectif	Livrable	État
0 — Cadrage	Conception validée	doc + squelette stt/	✅ fait
1 — Commande + backend	stt/stt --setup lancent le moteur vocal + websocket	pyproject.toml, stt/ (cli, config, voice, server)	✅ fait
2 — Routeur cerveau	3 modes + auto-détection LAN	module brain (hermes/local/claude)	✅ fait
3 — HUD	Visualiseur + conversation	stt/hud/index.html (MVP) → visualiseur avancé	🟡 MVP fait
4 — Mémoire 3 tiers	local ✅ + GitHub + Qdrant	memory : SQLite ✅ ; distillation/sync git + Qdrant	🟡 local fait
5 — Personnalisation	Thèmes / avatar / voix / wake word	écran réglages + stt/config/	⏳
6 — Auto-start	Démarre au boot du poste	install-service.sh + kiosk	⏳
7 — Cluster (opt.)	STT/TTS sur GPU	Wyoming sur gpu-01 + k8s/apps/stt/	⏳

État phase 1-2 (testé hors-LAN)

py_compile OK sur tout le package ; stt --help, chargement config, routeur cerveau (auto-détection → claude hors-LAN) et mémoire SQLite locale vérifiés. Le test bout-en-bout audio (Whisper/Piper/micro) se fait sur le poste après pipx install + stt --setup.

---

Projets de référence (inspiration, non forkés)

Aucun ne se branche proprement sur LiteLLM + Hermes (ils embarquent leur propre LLM/agent), mais bons pour le design et le code à piocher :

• AlexandreSajus/JARVIS — Voice→LLM→Speech, interface web (proche du front visé).
• InterGenJLU/jarvis — AMD ROCm (comme la RX 6700XT), HUD santé, streaming TTS.
• novik133/jarvis — whisper.cpp + Piper (même TTS) + monitoring système.
• rhasspy/wyoming-addons — faster-whisper / Piper conteneurisés (option phase 7).