# STT-server — orchestrateur AI (in-cluster)

API FastAPI déployée dans le cluster k8s (namespace `ai`). Reçoit les requêtes des clients
STT et route l'inférence vers LiteLLM (s01) → Qwen3 (g01) / Claude.

## API

| Méthode | Route | Corps | Réponse |
|---|---|---|---|
| `GET` | `/healthz` | — | `{status, version}` |
| `GET` | `/v1/models` | — | `{default, available[]}` |
| `POST` | `/v1/ask` | `{text, model?, session_id?}` | `{reply, model}` |
| `POST` | `/v1/reset` | `{session_id}` | `{status}` |

`model` (optionnel) = alias LiteLLM ; défaut serveur si absent ; rejeté (400) si absent
de `STT_ALLOWED_MODELS`. Le client choisit le modèle par requête (pas de switch global).

`session_id` (optionnel) active la **mémoire court-terme** : le serveur garde l'historique
de la conversation (en mémoire, borné + TTL) et l'injecte dans l'appel LLM. `/v1/reset`
l'efface. Sans `session_id`, chaque requête est sans état. (Deployment en 1 worker pour
la cohérence de la mémoire process. Mémoire long-terme Qdrant = phase 5b.)

## Configuration (variables d'env)

| Var | Défaut | Rôle |
|---|---|---|
| `STT_LITELLM_URL` | `http://192.168.10.1:4000/v1/chat/completions` | endpoint LiteLLM (IP directe s01, cf. open-webui) |
| `STT_LITELLM_KEY` | `lm-studio` | clé LiteLLM (valeur exacte attendue) |
| `STT_MODEL` | `hermes-default` | modèle par défaut |
| `STT_ALLOWED_MODELS` | `hermes-default,qwen3-8b,claude-sonnet-4-6,claude-opus-4-7` | alias autorisés (demandables par le client) |
| `STT_SYSTEM_PROMPT` | prompt vocal FR concis | persona |
| `STT_MAX_TOKENS` / `STT_TEMPERATURE` | `200` / `0.7` | génération |
| `STT_MEMORY_LONGTERM` | `true` | mémoire long-terme Qdrant (dégrade si injoignable) |
| `STT_QDRANT_URL` | `http://192.168.10.1:6333` | Qdrant (s01) |
| `STT_EMBED_URL` | `http://192.168.10.20:1234/v1/embeddings` | embeddings Qwen3 (gpu-01) |
| `STT_MEMORY_TOPK` | `3` | nombre de souvenirs injectés |

## Dev local

```bash
cd stt/server
pip install -e .
STT_LITELLM_URL=http://192.168.1.200:4000/v1/chat/completions stt-server   # :8000
curl -s localhost:8000/healthz
curl -s localhost:8000/v1/ask -H 'content-type: application/json' -d '{"text":"bonjour"}'
```

## Déploiement

- Image construite/poussée par `.github/workflows/build-stt-server.yml`, taguée `sha-<commit>` ;
  sur `main` la CI bumpe le manifest avec ce tag → ArgoCD redéploie tout seul (déterministe).
- Manifests : `k8s/apps/stt/` ; Application ArgoCD : `k8s/apps-of-apps/apps/stt.yaml` (depuis `main`).
- Accès LiteLLM (hors cluster) : IP directe `192.168.10.1:4000` (même pattern qu'open-webui).

## Mémoire

- **Court-terme** (`memory.py`) : historique par `session_id` (en mémoire, borné + TTL).
- **Long-terme** (`longterm.py`) : collection Qdrant `stt-memory` (vecteurs des tours user,
  embeddings Qwen3), souvenirs pertinents injectés au prompt. Dégrade si Qdrant/embeddings down.

## À venir

- Intégration des **outils Hermes** (« agir sur Funk ») via le gateway `:8080` — nécessite
  de spécifier son API. Aujourd'hui : inférence/chat seulement (via LiteLLM).
- Embedding dédié (`nomic-embed-text`) pour une recherche sémantique de meilleure qualité.
- Mémoire **distillée** versionnée (faits/préférences) dans `server/memory/`.