# Architecture LLM — jean-router (routing dynamique + gestion VRAM)

## Vue d'ensemble

```
┌─────────────────────────────────────────────────────────────────┐
│                    OpenWebUI (:3000)                            │
│              http://192.168.1.27:3000                           │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    jean-router (:3014)                          │
│         Routing dynamique + Gestion VRAM automatique            │
│                                                                 │
│  • Interroge Jean /api/presets (découverte dynamique)          │
│  • Interroge Ollama /api/tags (modèles vision)                 │
│  • Switch automatique de preset Jean                           │
│  • Arrête Jean quand on passe sur Ollama (libère VRAM)         │
│  • Garde Ollama 5 min en mémoire avant déchargement            │
└────────┬──────────────────────────────────────┬────────────────┘
         │                                      │
         ▼                                      ▼
┌────────────────────────┐           ┌────────────────────────┐
│   jean-proxy (:3012)   │           │   wol-proxy (:3011)    │
│   + WOL si PC éteint   │           │   + WOL si PC éteint   │
└────────┬───────────────┘           └────────┬───────────────┘
         │                                      │
         ▼                                      ▼
┌────────────────────────┐           ┌────────────────────────┐
│   Jean (.11:8080)      │           │   Ollama (.11:11434)   │
│   llama.cpp server     │           │   Modèles vision       │
│   Presets dynamiques   │           │   mistral, qwen3.5     │
│   Ornith, Qwen3.6...   │           │                        │
└────────────────────────┘           └────────────────────────┘
```

## Composants

### jean-router (`/jean-router/`) — Proxy dynamique

**Rôle :** Router intelligemment entre Jean et Ollama avec gestion VRAM

**Fonctionnalités :**
1. **Découverte dynamique** : Interroge `/api/presets` (Jean) et `/api/tags` (Ollama)
2. **Routing intelligent** : Route vers Jean ou Ollama selon le modèle demandé
3. **Switch automatique** : Change de preset Jean si nécessaire
4. **Gestion VRAM** : Évite la contention mémoire entre Jean et Ollama

**Endpoints :**
- `GET /v1/models` : Liste tous les modèles (Jean + Ollama)
- `POST /v1/chat/completions` : Route vers le bon backend

**Configuration :**
```bash
JEAN_WEB_HOST=192.168.1.11        # Jean Web UI (API presets)
JEAN_WEB_PORT=8090
JEAN_PROXY_HOST=localhost          # jean-proxy (backend Jean)
JEAN_PROXY_PORT=3012
OLLAMA_PROXY_HOST=localhost        # wol-proxy (backend Ollama)
OLLAMA_PROXY_PORT=3011
OLLAMA_DIRECT_HOST=192.168.1.11    # Ollama direct (pour unload)
OLLAMA_DIRECT_PORT=11434
ENABLE_OLLAMA=true
ENABLE_VRAM_MANAGEMENT=true
OLLAMA_KEEP_ALIVE_MINUTES=5        # Ollama reste 5 min en mémoire
SWITCH_TIMEOUT=90                  # Timeout chargement Jean (s)
JEAN_STOP_TIMEOUT=30               # Timeout arrêt Jean (s)
LISTEN_PORT=3014
```

### jean-proxy (`/jean-proxy/`) — Reverse-proxy Jean + WOL

**Rôle :** Proxy vers Jean avec Wake-on-LAN si le PC gaming est éteint

**Fonctionnalités :**
- Écoute `:3012` sur le host (`network_mode: host`)
- Health-check : `GET /health` sur Jean
- Si cible DOWN → envoi paquets WOL vers `TARGET_MAC`
- Attente jusqu'à `WAKE_TIMEOUT` (60s)
- Route toutes les requêtes vers `http://${OLLAMA_HOST}:8080`

**Configuration :**
```bash
TARGET_HOST=192.168.1.11
TARGET_PORT=8080
TARGET_MAC=04:D9:F5:D1:EC:DF
LISTEN_PORT=3012
WAKE_TIMEOUT=60
CHECK_INTERVAL=5
BROADCAST_IP=192.168.1.255
HEALTH_PATH=/health
```

### wol-proxy (`/wol-proxy/`) — Reverse-proxy Ollama + WOL

**Rôle :** Proxy vers Ollama avec Wake-on-LAN

**Fonctionnalités :**
- Écoute `:3011` sur le host
- Health-check : `GET /api/version` sur Ollama
- Si cible DOWN → envoi paquets WOL
- Route toutes les requêtes vers `http://${OLLAMA_HOST}:11434`

**Configuration :**
```bash
TARGET_HOST=192.168.1.11
TARGET_PORT=11434
TARGET_MAC=04:D9:F5:D1:EC:DF
LISTEN_PORT=3011
WAKE_TIMEOUT=180
CHECK_INTERVAL=5
BROADCAST_IP=192.168.1.255
```

## Gestion VRAM

### Problème
Jean et Ollama partagent la même carte graphique (RX 7800 XT, 16GB VRAM). Charger les deux simultanément cause une contention mémoire.

| Backend | Modèle typique | VRAM utilisée |
|---------|---------------|---------------|
| Jean | Ornith 35B Q6_K | ~28.5GB (déborde en RAM) |
| Ollama | mistral 7B Q4_K_M | ~4GB |
| Ollama | qwen3.5:9b Q4_K_M | ~6GB |

### Solution : Switch automatique

**Switch Jean → Ollama :**
```
1. Arrêt de Jean via API web (/api/stop)
2. Attente confirmation (max 30s)
3. Route requête vers Ollama
```

**Switch Ollama → Jean :**
```
1. Programme déchargement Ollama dans 5 min (timer)
2. Démarrage de Jean via API web (/api/start)
3. Attente chargement modèle (max 90s)
4. Route requête vers Jean
```

**Timer Ollama :**
- Ollama reste en mémoire pendant **5 minutes** après le dernier usage
- Chaque requête vers Ollama annule le timer
- Si retour sur Ollama avant expiration → déchargement annulé
- Après 5 min d'inactivité → déchargement automatique

### Logs observés

**Switch Jean → Ollama :**
```
[VRAM] Switch Jean → Ollama
[VRAM] Arrêt de Jean pour libérer la VRAM...
[VRAM] Jean arrêté via API web
[VRAM] Jean confirmé arrêté
[Router] → Ollama (gemma4:e4b)
```

**Switch Ollama → Jean :**
```
[VRAM] Switch Ollama → Jean
[VRAM] Déchargement Ollama programmé dans 5 minutes
[VRAM] Démarrage de Jean...
[VRAM] Jean prêt après 45s
[Router] → Jean (ornith-35b-q6)
```

**Timer Ollama :**
```
[VRAM] Timer écoulé (5min), déchargement Ollama...
[VRAM] Ollama déchargé via API
```

## Modèles disponibles

### Jean (presets dynamiques)
Les presets sont découverts automatiquement via `/api/presets` :
- **ornith-35b-q6** (actif, Q6_K, reasoning)
- **qwen3.6-27b-mtp** (IQ4_XS, reasoning)
- **qwen3.6-35b-moe-compact**
- **qwen3.6-35b-moe-compact-reason** (reasoning)
- **qwen3.6-35b-moe-nano**

**Note :** Nouveaux presets Jean apparaissent automatiquement dans OpenWebUI sans configuration.

### Ollama (modèles vision)
- **mistral** (7.2B, Q4_K_M, tools)
- **qwen3.5:9b** (9.7B, Q4_K_M, vision, thinking)

**Note :** Ollama sert principalement pour les modèles avec vision que Jean ne supporte pas.

## Déploiement

### Commandes (sur effi-server .27)

```bash
cd /home/effi/effi
git pull

# Build et démarrage jean-router
docker compose -f docker-compose.yml -f docker-compose.litellm.yml up -d --build jean-router

# Recréer open-webui avec nouvelle config
docker compose -f docker-compose.yml -f docker-compose.litellm.yml up -d --force-recreate open-webui

# Vérifier
docker logs jean-router --tail 20
curl -s http://localhost:3014/v1/models | jq
```

### Tests

**1. Liste des modèles :**
```bash
curl -s http://localhost:3014/v1/models | python3 -m json.tool
```

**2. Requête Jean :**
```bash
curl -X POST http://localhost:3014/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ornith-35b-q6",
    "messages": [{"role": "user", "content": "Bonjour"}],
    "max_tokens": 50
  }'
```

**3. Requête Ollama :**
```bash
curl -X POST http://localhost:3014/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 30
  }'
```

**4. Vérifier logs VRAM :**
```bash
docker logs jean-router -f | grep -E "VRAM|Router"
```

## Avantages vs LiteLLM

| Aspect | LiteLLM | jean-router |
|--------|---------|-------------|
| Configuration | Statique (config.yaml) | Dynamique (API Jean) |
| Nouveaux presets | Modifier config + restart | Automatique |
| Pass-through /v1/models | Non | Oui |
| Gestion VRAM | Aucune | Automatique |
| Couches | 2 (LiteLLM + jean-proxy) | 1 (jean-router) |
| Complexité | Élevée | Faible |

## Limitations

### 1. Latence de switch
- Jean → Ollama : ~3s (arrêt Jean)
- Ollama → Jean : ~45-90s (démarrage + chargement modèle)
- **Impact** : Première requête après switch plus lente

### 2. Timer Ollama non-persistant
- Si jean-router redémarre, le timer est perdu
- Ollama restera en mémoire indéfiniment (jusqu'à son propre timeout)
- **Acceptable** : Ollama gère son propre `keep_alive`

### 3. Pas de failover
- Si Jean échoue (timeout, erreur), pas de fallback automatique vers Ollama
- **À considérer** : Ajouter un fallback dans jean-router si besoin

### 4. Jean n'a pas d'auto-unload natif
- Ollama décharge automatiquement après `OLLAMA_KEEP_ALIVE` (défaut 5min)
- Jean garde son modèle chargé tant que le service tourne
- **Solution actuelle** : Arrêt complet de Jean via API web

## Évolution possible

### Court terme
- **Monitorer** : Vérifier que la gestion VRAM fonctionne bien en production
- **Ajuster** : Modifier `OLLAMA_KEEP_ALIVE_MINUTES` selon l'usage réel
- **Tester** : Valider que les nouveaux presets Jean apparaissent bien automatiquement

### Moyen terme
- **VRAM monitoring** : jean-router pourrait vérifier la VRAM disponible avant de router
- **Fallback automatique** : Si Jean échoue, router vers Ollama
- **Metrics** : Exposer des statistiques (temps de switch, VRAM utilisée, etc.)

### Long terme
- **JeanOrchestrator** : Jean pourrait gérer lui-même le switch entre presets
- **Multi-GPU** : Si plusieurs GPU, router vers celui avec le plus de VRAM libre
- **Load balancing** : Si plusieurs instances Jean/Ollama, répartir la charge

## Historique

**2026-06-27** : Architecture initiale avec LiteLLM
- Routing statique par nom de modèle
- Configuration codée en dur dans `litellm/config.yaml`

**2026-07-20** : Migration vers jean-router
- Routing dynamique basé sur les presets Jean
- Gestion automatique de la VRAM
- Suppression de LiteLLM (une couche de moins)
- Nouveaux modèles automatiquement disponibles

## Références

- **Code jean-router** : `/jean-router/app.py`
- **Docker compose** : `/docker-compose.litellm.yml`
- **Journal de session** : `/docs/05-journal/SESSION-2026-07-20-JEAN-ROUTER.md`
- **Repo Gitea** : https://gitea.folzocorp.fr/Folzo/Effi