# 🤖 Effi - Assistant IA Personnel Self-Hosted

Effi est un assistant IA personnel **100% auto-hébergé**, avec mémoire persistante, discussion vocale, génération d'images/audio, et surveillance système.

---

## 🏗️ Architecture

### Infrastructure Multi-Machines

| Machine | IP | Rôle | Services |
|---------|-----|------|----------|
| **effi-server** | `192.168.1.27` | Serveur Docker principal | OpenWebUI, Qdrant, n8n, jean-router |
| **folzo-Corp** | `192.168.1.11` | LLM + STT + TTS + Gen | Jean, Ollama, ComfyUI, effi-stt, openedai-speech, kreuzberg |
| **NAS Synology** | `192.168.1.25` | Monitoring | Beszel Hub |

### Schéma Global

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         NAS SYNOLOGY (192.168.1.25)                         │
│                            Beszel Hub :8090                                │
└─────────────────────────────────────────────────────────────────────────────┘
         │                              │                              │
         │ Monitoring                   │ Monitoring                    │ Monitoring
         ▼                              ▼                              ▼
┌─────────────────────────────────┐  ┌─────────────────────────────────────────┐
│       EFFI SERVER (192.168.1.27) │  │         FOLZO-CORP (192.168.1.11)       │
│                                 │  │                                          │
│  ┌──────────────┐  ┌──────────┐ │  │  ┌──────────────┐  ┌──────────────┐   │
│  │ Open WebUI   │  │ Qdrant   │ │  │  │ Jean         │  │ Ollama       │   │
│  │ Port 3000    │  │ Port 6333│ │  │  │ Port 8080    │  │ Port 11434   │   │
│  └──────────────┘  └──────────┘ │  │  │ llama.cpp    │  │ Vision       │   │
│                                 │  │  │ Ornith 35B   │  │ mistral,     │   │
│  ┌──────────────┐  ┌──────────┐ │  │  │ Qwen3.6...   │  │ qwen3.5:9b   │   │
│  │ n8n          │  │jean-router│ │  │  └──────────────┘  └──────────────┘   │
│  │ Port 5678    │  │ Port 3014│ │  │                                          │
│  └──────────────┘  └──────────┘ │  │  ┌──────────────┐  ┌──────────────┐   │
│                                 │  │  │ ComfyUI      │  │ effi-stt     │   │
│  ┌──────────────┐  ┌──────────┐ │  │  │ Port 8188    │  │ Port 8200    │   │
│  │ Beszel Agent │  │ Watchtower│ │  │  │ Image/Audio  │  │ Whisper STT  │   │
│  └──────────────┘  └──────────┘ │  │  └──────────────┘  └──────────────┘   │
└─────────────────────────────────┘  │                                          │
                                      │  ┌──────────────┐  ┌──────────────┐   │
                                      │  │ openedai     │  │ kreuzberg    │   │
                                      │  │ Port 8100    │  │ Port 8300    │   │
                                      │  │ TTS          │  │ Doc Extract  │   │
                                      │  └──────────────┘  └──────────────┘   │
                                      │         RX 7800 XT (VRAM 16GB)        │
                                      └─────────────────────────────────────────┘
```

**Note :** jean-router gère le routing dynamique entre Jean et Ollama avec gestion automatique de la VRAM partagée. Voir [ARCHITECTURE-JEAN-ROUTER.md](docs/ARCHITECTURE-JEAN-ROUTER.md) pour les détails.

---

## 📦 Services

### FolzoCorp (192.168.1.11)

| Service | Port | Image | Rôle | RAM/VRAM | Auto-unload |
|---------|------|-------|------|----------|-------------|
| **Jean** | 8080 | Native | LLM inference (llama.cpp, presets dynamiques) | ~28GB | Arrêt via API |
| **Ollama** | 11434 | Native | LLM vision (mistral, qwen3.5:9b) | ~4-6GB | 5min après dernier usage |
| **ComfyUI** | 8188 | `yanwk/comfyui-boot:rocm` | Image + Audio generation | 18GB shm | ✅ après 10min idle |
| **effi-stt** | 8200 | Build local | Whisper STT | ~20MB | ✅ après 5min idle |
| **openedai-speech** | 8100 | `ghcr.io/matatonic/openedai-speech` | TTS | ~15MB | Non (GPU) |
| **kreuzberg** | 8300 | `ghcr.io/kreuzberg-dev/kreuzberg:latest` | Document extraction | ~5MB | ✅ après 10min idle |
| **beszel-agent** | - | `henrygd/beszel-agent:latest` | Monitoring | ~5MB | Auto-start |

**Note :** Jean et Ollama partagent la VRAM (RX 7800 XT, 16GB). jean-router gère automatiquement le switch pour éviter la contention mémoire.

### EffiServer (192.168.1.27)

| Service | Port | Image | Rôle |
|---------|------|-------|------|
| **Open WebUI** | 3000 | `ghcr.io/open-webui/open-webui:main` | Interface IA |
| **Qdrant** | 6333 | `qdrant/qdrant:latest` | Vector DB (RAG) |
| **n8n** | 5678 | `docker.n8n.io/n8nio/n8n:latest` | Automatisation |
| **jean-router** | 3014 | Build local | Routing dynamique Jean/Ollama + gestion VRAM |
| **jean-proxy** | 3012 | Build local | Wake-on-LAN + Jean proxy |
| **wol-proxy** | 3011 | Build local | Wake-on-LAN + Ollama proxy |
| **beszel-agent** | - | `henrygd/beszel-agent:latest` | Monitoring |

### NAS Synology (192.168.1.25)

| Service | Port | Image | Rôle |
|---------|------|-------|------|
| **Beszel Hub** | 8090 | `henrygd/beszel:latest` | Monitoring central |

---

## 🎯 Fonctionnalités

### 💬 Chat IA
- **Interface**: Open WebUI
- **LLM principal**: Jean (llama.cpp) avec presets dynamiques
  - **ornith-35b-q6** (35B, Q6_K, reasoning) — modèle principal
  - **qwen3.6-27b-mtp** (27B, IQ4_XS, reasoning, MTP)
  - **qwen3.6-35b-moe-compact** (35B MoE, compact)
  - **qwen3.6-35b-moe-compact-reason** (35B MoE, reasoning)
  - **qwen3.6-35b-moe-nano** (35B MoE, nano)
- **LLM vision**: Ollama (mistral, qwen3.5:9b) pour les tâches avec images
- **Routing automatique**: jean-router détecte le modèle demandé et route vers Jean ou Ollama
- **Gestion VRAM**: Switch automatique entre Jean et Ollama pour éviter la contention mémoire

**Note :** Nouveaux presets Jean apparaissent automatiquement dans OpenWebUI sans configuration. Voir [ARCHITECTURE-JEAN-ROUTER.md](docs/ARCHITECTURE-JEAN-ROUTER.md) pour les détails.

### 🚀 jean-router — Routing dynamique LLM
- **Découverte automatique**: Interroge Jean et Ollama pour lister les modèles disponibles
- **Routing intelligent**: Route vers Jean (presets) ou Ollama (vision) selon le modèle demandé
- **Switch automatique**: Change de preset Jean si nécessaire (via API web)
- **Gestion VRAM**: 
  - Arrête Jean quand on passe sur Ollama (libère VRAM)
  - Garde Ollama en mémoire 5 min avant déchargement automatique
  - Évite la contention mémoire entre les deux backends
- **API OpenAI-compatible**: `/v1/models` et `/v1/chat/completions`

### 🎤 Pipeline Vocal
- **STT**: Whisper large-v3 via effi-stt (CPU, déchargement auto)
- **TTS**: XTTS v2 via openedai-speech (GPU ROCm)

### 🖼️ Génération Images/Audio
- **ComfyUI**: Workflows pour image et audio
- **Modèle audio**: ACE-Step ( génération musicale)
- **Modèles image**: Multiples checkpoints disponibles

### 📄 Extraction Documents
- **Kreuzberg**: Extraction 90+ formats (PDF, DOCX, images, etc.)
- Intégré à OpenWebUI via CONTENT_EXTRACTION_ENGINE=docling

### 🧠 Mémoire
- **Type**: Mémoire manuelle via OpenWebUI (snippets)
- **RAG**: Qdrant pour embeddings sémantiques

### 📊 Monitoring

- **URL Beszel**: http://192.168.1.25:8090
- **Agents actifs**:
  - FolzoCorp (192.168.1.11) - GPU AMD RX 7800 XT
  - EffiServer (192.168.1.27) - Intel J5040

### 🛠️ Tool OpenWebUI - Beszel

Outil custom pour interroger Beszel depuis OpenWebUI via Effi.

**Fonctionnalités actuelles**:
- `get_system_stats` → retourne CPU, RAM, GPU (%)
- Données temps réel depuis `info` (cpu, mp=gpu, g=gpu, dt=timestamp)

**Améliorations futures** (pas encore implémentées):
- Support historique: données des N dernières minutes
- Filtres par période
- Graphiques/Métriques avancés
- Alertes automatisées via le tool

**Documentation**: [Tool Beszel OpenWebUI](./docs/TOOL-BESZEL-OPENWEBUI.md)

### Scripts Memory

| Script | Condition | Action |
|--------|-----------|--------|
| comfyui-memory-manager.py | 10min idle + VRAM<1% + RAM>5GB | Restart container |
| kreuzberg-memory-manager.py | 10min idle + RAM>2GB | Restart container |
| effi-stt | 5min idle | Déchargement modèle Whisper |

### Commandes Utiles

| Script | Condition | Action |
|--------|-----------|--------|
| comfyui-memory-manager.py | 10min idle + VRAM<1% + RAM>5GB | Restart container |
| kreuzberg-memory-manager.py | 10min idle + RAM>2GB | Restart container |
| effi-stt | 5min idle | Déchargement modèle Whisper |

### Commandes Utiles

```bash
# Statut services
sudo systemctl status comfyui-memory-manager kreuzberg-memory-manager
docker ps

# Logs
journalctl -u comfyui-memory-manager -f
docker logs -f comfyui

# Métriques Beszel
python3 scripts/beszel_client.py --system folzocorp --check stats
```

---

## 📚 Documentation

- [Architecture jean-router](./docs/ARCHITECTURE-JEAN-ROUTER.md) — Routing dynamique LLM + gestion VRAM
- [Session 2026-07-20](./docs/05-journal/SESSION-2026-07-20-JEAN-ROUTER.md) — Création de jean-router
- [Installation Beszel](./docs/BESZEL-INSTALLATION.md)
- [Gestion Mémoire](./docs/MEMOIRE-GESTION.md)
- [Session 2026-04-12](./docs/SESSION-2026-04-12-RAM-BESZEL.md)
- [Guide ACE-Step](./docs/guide-ace-step.md)
- [Guide ComfyUI](./comfyui/README.md)

---

## 🔗 Technologies

| Domaine | Technologies |
|---------|-------------|
| **LLM** | Jean (llama.cpp), Ollama (vision) |
| **Routing** | jean-router (Flask, routing dynamique + gestion VRAM) |
| **Interface** | Open WebUI |
| **STT** | Faster Whisper (CPU) |
| **TTS** | XTTS v2 (ROCm GPU) |
| **Image/Audio** | ComfyUI + ACE-Step |
| **Vector DB** | Qdrant |
| **Document** | Kreuzberg (docling) |
| **Automatisation** | n8n |
| **GPU** | AMD RX 7800 XT (ROCm) |
| **Monitoring** | Beszel |

---

## 📁 Structure du Projet

```
effi/
├── beszel/                    # Configuration Beszel
│   ├── docker-compose-hub.yml          # Hub (Synology)
│   ├── docker-compose-agent-folzocorp.yml  # Agent FolzoCorp
│   └── docker-compose-agent-effiserver.yml # Agent EffiServer
│
├── comfyui/                  # ComfyUI (Image/Audio)
│   ├── docker-compose.yml
│   ├── custom_nodes/          # Nodes personnalisés
│   ├── models/               # Modèles checkpoints, VAE, LoRA
│   └── workflows/            # Workflows JSON
│
├── effi-stt/                 # STT Whisper
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── main.py               # API avec timeout auto-unload
│
├── effi-kreuzberg/           # Documentation Kreuzberg
│   ├── README.md
│   └── MIGRATION.md
│
├── scripts/                  # Scripts utilitaires
│   ├── beszel_client.py      # Client API Beszel
│   ├── comfyui-memory-manager.py    # Restart ComfyUI après idle
│   ├── kreuzberg-memory-manager.py   # Restart Kreuzberg si >2GB
│   └── start-memory-monitors.sh
│
├── systemd/                  # Services systemd
│   ├── comfyui-memory-manager.service
│   ├── kreuzberg-memory-manager.service
│   ├── beszel-agent-wake.service
│   └── ollama.service              # Ollama LLM (folzo-Corp)
│
├── docs/                     # Documentation
│   ├── SESSION-2026-04-12-RAM-BESZEL.md
│   ├── BESZEL-INSTALLATION.md
│   ├── MEMOIRE-GESTION.md
│   └── TOOL-BESZEL-OPENWEBUI.md
│
└── docker-compose*.yml       # Divers compose files (legacy/backup)
```

---

## 📝 Historique

**Juillet 2026** - jean-router : routing dynamique LLM + gestion VRAM

### jean-router ✅
- Création de jean-router (Flask) pour routing dynamique entre Jean et Ollama
- Découverte automatique des presets Jean via `/api/presets`
- Découverte automatique des modèles Ollama via `/api/tags`
- Nouveaux presets Jean automatiquement visibles dans OpenWebUI
- Gestion VRAM : arrêt Jean quand on passe sur Ollama, timer 5min pour Ollama
- Suppression de LiteLLM (une couche de moins, config statique obsolète)
- OpenWebUI pointe directement vers jean-router:3014

### Jean (llama.cpp) ✅
- Migration vers Jean comme backend LLM principal
- Presets dynamiques : ornith-35b-q6, qwen3.6-27b-mtp, qwen3.6-35b-moe-compact...
- Service systemd avec démarrage au boot (sans login)
- API web pour gestion (start/stop/switch presets)

**Avril 2026** - Optimisation RAM + Monitoring + Tool OpenWebUI

### RAM Management ✅
- Scripts déchargement mémoire avec restart container (ComfyUI, Kreuzberg)
- Timeout inactivité 300s pour effi-stt avec déchargement Whisper
- Services systemd pour gestion automatique

### Beszel Monitoring ✅
- Hub sur NAS Synology (http://192.168.1.25:8090)
- Agents sur FolzoCorp + EffiServer + NAS Synology
- Service restart après veille (beszel-agent-wake.service)

### Tool OpenWebUI Beszel ✅
- Outil custom pour interrogation Beszel depuis OpenWebUI
- Endpoint PocketBase: `/api/collections/users/auth-with-password`
- Données extraites du champ `info` (cpu, mp, g, dt, la, etc.)
- Pattern Valves Pydantic pour configuration

### LLM Optimization (gemma4:e4b) ✅
- Installation gemma4:e4b (9.6GB, 128K context, MMLU 82.6%)
- Service systemd Ollama propre (User=folzo, auto-start)
- Variables: OLLAMA_FLASH_ATTENTION=1, OLLAMA_KV_CACHE_TYPE=q8_0, OLLAMA_CONTEXT_LENGTH=32768
- Note: gemma4:26b (18GB) ne tient pas dans 17GB VRAM RX 7800 XT

### RAG Optimization ✅
- effi-server: RAG_SYSTEM_CONTEXT=True (meilleur KV cache pour RAG)
- effi-server: ENABLE_RAG_HYBRID_SEARCH=True

**Améliorations futures**:
- Support historique (données des N dernières minutes)
- Filtres par période
- Graphiques et alertes automatisées

**Mars 2026** - Génération Audio
- Intégration ACE-Step pour génération musicale
- ComfyUI avec ROCm

**Février 2026** - Stack Vocale
- effi-stt avec Whisper large-v3
- openedai-speech avec XTTS v2
- Kreuzberg pour extraction documents

---

## 🙋 Auteur

**Folzo** - [gitea.folzocorp.fr/Folzo](https://gitea.folzocorp.fr/Folzo)

---

*Dernière mise à jour : Avril 2026*