# 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 |
|---|---|---|
| **0 — Cadrage** | Conception validée | ✅ ce doc + squelette `stt/` |
| **1 — Commande + backend** | `stt`/`stt --setup` lancent le moteur vocal + websocket | `stt/pyproject.toml`, `stt/stt/` (hermes-voice + ws + états) |
| **2 — Routeur cerveau** | 3 modes + auto-détection LAN | module `brain` (hermes/local-direct/claude-direct) |
| **3 — HUD MVP** | Visualiseur + conversation à l'écran | `stt/hud/` relié au websocket |
| **4 — Mémoire 3 tiers** | local + GitHub (+ Qdrant si dispo) | module `memory` + sync git + distillation |
| **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/` |

---

## 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](https://github.com/AlexandreSajus/JARVIS) — Voice→LLM→Speech, interface web (proche du front visé).
- [InterGenJLU/jarvis](https://github.com/InterGenJLU/jarvis) — AMD ROCm (comme la RX 6700XT), HUD santé, streaming TTS.
- [novik133/jarvis](https://github.com/novik133/jarvis) — whisper.cpp + Piper (même TTS) + monitoring système.
- [rhasspy/wyoming-addons](https://github.com/rhasspy/wyoming-addons) — faster-whisper / Piper conteneurisés (option phase 7).