Effi/docs/ARCHITECTURE-LITELLM.md

# Architecture LLM multi-backends — LiteLLM + WOL

## État avant

```
open-webui (:3000)  ─► OLLAMA_BASE_URL=host.docker.internal:3011
                             │
                       wol-proxy (:3011, host network)
                             │
                             ▼  (WOL paquet + forward TCP)
                       PC gaming .11 (s'éteint la nuit)
                             └─ Ollama :11434
```

Problème : backend unique (Ollama), pas moyen d'utiliser Jean (Qwen3.6-27B + MTP sur ROCm) sans changer la config à la main.

## État après — LiteLLM + double proxy WOL

```
open-webui (:3000)  ─► OLLAMA_BASE_URL=host.docker.internal:4000   ← optional: à basculer manuellement
                             │
                       LiteLLM proxy (:4000, host network)       ← NOUVEAU
                             │  routing par nom de modèle
                             ├── "qwen3.6-27b" / "qwen3.6"  ─► jean-proxy (:3012)  ─► Jean (.11:8080)
                             └── "llama3.1-8b" / "llama3.1"  ─► wol-proxy  (:3011)  ─► Ollama (.11:11434)
                                                                    │
                                                                    └──  WOL paquet (MAC PC gaming) si cible DOWN
```

## Composants

### wol-proxy (`/wol-proxy/`) — EXISTANT, inchangé

Reverse-proxy Flask générique vers Ollama + déclenchement WoL.
- Écoute `:3011` sur le host (`network_mode: host`).
- Health-check : `GET /api/version` sur Ollama (`HEALTH_PATH` codé = `/api/version`).
- Si cible DOWN → envoi 3 paquets magic sur `BROADCAST_IP:9` avec `TARGET_MAC`, attente jusqu'à `WAKE_TIMEOUT` (60 s).
- Route ensuite toutes les requêtes vers `http://${OLLAMA_HOST}:11434`.

### jean-proxy (`/jean-proxy/`) — NOUVEAU, clone du wol-proxy

Même mécanique, adapté pour Jean (llama.cpp).
- Écoute `:3012` sur le host.
- Health-check : `GET /health` sur Jean (`HEALTH_PATH=/health` par défaut, *paramétrable via env*).
- Si cible DOWN → même WoL (même `TARGET_MAC`, même `BROADCAST_IP`).
- Bonus : **retry post-WoL** — Jean met ~30 s à charger le modèle 14 Go après le boot du PC. Si la connexion est refusée (Jean n'a pas encore ouvert son port), jean-proxy attend jusqu'à `WAKE_TIMEOUT` et retry toutes les `CHECK_INTERVAL` s.
- Route toutes les requêtes vers `http://${OLLAMA_HOST}:8080`.
- Voir `jean-proxy/app.py` : variables `TARGET_PORT=8080`, `HEALTH_PATH=/health`, `LISTEN_PORT=3012`.

### litellm (`/litellm/`) — NOUVEAU

Proxy OpenAI-compatible unique pour open-webui.
- Image officielle : `ghcr.io/berriai/litellm:main-stable`.
- Écoute `:4000` sur le host (`network_mode: host` pour joindre les proxies :301x).
- Routing par nom de modèle via `litellm/config.yaml` :

| Model name (visible open-webui) | Route vers | Backend réel |
|---|---|---|
| `qwen3.6-27b`, `qwen3.6` | `http://localhost:3012/v1` (jean-proxy) | Jean (`llama.cpp` OpenAI API) |
| `llama3.1-8b`, `llama3.1` | `http://localhost:3011` (wol-proxy) | Ollama (via `/api/chat` façon Ollama) |

- Master key : `sk-effi-litellm-master` (à mettre dans `.env` si on veut la surcharger — voir plus bas).
- `drop_params: true` : supprime les params non reconnus par le backend (évite les erreurs sur champs OpenAI exotiques).
- Pass-through du `chat_template_kwargs.enable_thinking` : LiteLLM le transmet tel quel à Jean — c'est ainsi qu'on peut désactiver le raisonnement Qwen3.6 par requête sans toucher au `config.env` de Jean.

## Fichiers

- `wol-proxy/app.py` — code existant (préalablement non versionné, désormais commit).
- `wol-proxy/Dockerfile` — idem.
- `jean-proxy/app.py` — clone du wol-proxy avec `HEALTH_PATH` paramétrable + retry post-WoL pour services lents à démarrer.
- `jean-proxy/Dockerfile` — idem que wol-proxy.
- `litellm/config.yaml` — routing des modèles, master key.
- `docker-compose.litellm.yml` — **override** : ajoute uniquement les services `jean-proxy` et `litellm`. Ne redéfinit **pas** les services existants, donc `docker compose up -d` ne redémarre ni `open-webui`, ni `hermes-webui`, ni `wol-proxy` (zero impact).

## Déploiement

### Pré-requis

Déjà validé sur la machine de prod :
- Serveur Effi `.27` accessible en SSH (`ssh effi-server`).
- Docker + compose installés.
- Repo Effi à `/home/effi/effi`.
- `.env` contient `OLLAMA_HOST`, `PC_GAMING_MAC`, `BROADCAST_IP`.

### Commandes (à lancer sur .27)

```bash
cd /home/effi/effi
# Démarre uniquement litellm + jean-proxy, n' touche pas au reste
docker compose -f docker-compose.yml -f docker-compose.litellm.yml up -d --build jean-proxy litellm

# Test 1 — Jean route
curl -s -H "Authorization: Bearer sk-effi-litellm-master" \
  http://localhost:4000/v1/models

# Test 2 — chat Qwen3.6 via Jean (reasoning off)
curl -s -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-effi-litellm-master" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.6-27b","messages":[{"role":"user","content":"Bonjour"}],
       "chat_template_kwargs":{"enable_thinking":false},"max_tokens":50}'

# Test 3 — chat llama3.1 via Ollama (provoque WoL si .11 éteint)
curl -s -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-effi-litellm-master" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.1","messages":[{"role":"user","content":"Bonjour"}],"max_tokens":30}'
```

### Commutation de open-webui vers LiteLLM (étape utilisateur)

Une fois les tests validés :

1. Éditer `/home/effi/effi/docker-compose.yml` (seulement cette ligne) :
   ```yaml
   OLLAMA_BASE_URL=http://host.docker.internal:4000   # LiteLLM au lieu de :3011
   ```
2. Ajouter la master key LiteLLM dans `/home/effi/effi/.env` :
   ```
   LITELLM_MASTER_KEY=sk-effi-litellm-master
   ```
3. Redémarrer open-webui uniquement :
   ```bash
   docker compose -f docker-compose.yml -f docker-compose.litellm.yml up -d open-webui
   ```
4. Dans open-webui : Admin → Settings → Connections → l'URL est déjà `http://host.docker.internal:4000`. Vérifier que les deux modèles apparaissent dans le dropdown.

ℹ️ Cette étape est volontairement laissée manuelle — c'est l'unique impact sur le service en prod (1 redémarrage open-webui). Hermes, wol-proxy, qdrant etc. ne sont pas touchés.

### En cas de rollback

Revenir à `OLLAMA_BASE_URL=http://host.docker.internal:3011` et redémarrer open-webui. LiteLLM et jean-proxy peuvent rester UP (en override, ils ne gênent rien) ou être arrêtés :
```bash
docker compose -f docker-compose.yml -f docker-compose.litellm.yml stop litellm jean-proxy
```

## Comportement WoL —要点

- Les deux proxies (`wol-proxy` et `jean-proxy`) partagent **la même adresse MAC cible** (`PC_GAMING_MAC`).
- Quel que soit le backend demandé, si le PC gaming est DOWN, un seul WoL est envoyé (par le proxy concerné).
- Pendant la phase de wake-up (`WAKE_TIMEOUT=60s`), le proxy bloque la requête HTTP jusqu'à ce que la cible réponde — l'utilisateur voit une latence plus longue mais pas d'erreur.
- Après WoL réussi :
  - Ollama répond en ~10-20 s (lancement container + warmup).
  - Jean répond en ~30-60 s (charger le modèle 14 Go en VRAM). `jean-proxy` a un retry supplémentaire pour couvrir ce cas.

## Limitations / à surveiller

- **`n_parallel=1` côté Jean** : une seule requête à la fois. Si open-webui + un script Effi appellent Jean en parallèle, la 2e attend. Pour la prod multi-tenant, mettre en place une queue ou ouvrir un 2e slot (mais VRAM saturée).
- **`drop_params: true`** : LiteLLM supprime tout paramètre non standard OpenAI. Si on veut passer `chat_template_kwargs` à Jean, vérifier que LiteLLM le transmet — testé OK, mais à revalider si on ajoute d'autres flags exotiques.
- **Pas de failover** dans la config actuelle : si jean-proxy retourne 502 (cible injoignable après WoL), LiteLLM renvoie l'erreur au client. On pourrait ajouter un `fallback` LiteLLM : qwen3.6 → llama3.1 si Jean down.
- **Master key en clair dans `config.yaml`** : acceptable en interne, mais pour un déploiement plus sclériser, déplacer la clé dans `.env` via `LITELLM_MASTER_KEY` et la référencer dans `config.yaml` via `${LITELLM_MASTER_KEY}` (LiteLLM supporte l'expansion env vars).

## Tests de non-régression

Après déploiement, vérifier que :
- `hermes-webui` est toujours `Up` et `healthy`.
- `open-webui` toujours `Up` et `healthy` (jusqu'à la commutation optionnelle).
- `wol-proxy` toujours `Up` (inchangé).
- `curl http://192.168.1.27:8787/` (Hermes UI) répond toujours.
- `curl http://192.168.1.27:3000/` (open-webui) répond toujours.
- `curl http://localhost:3011/api/version` (ollama via wol-proxy direct) répond toujours.