docs: passe de cohérence documentaire (STT, Ghostfolio, embeddings, Qdrant) (#15)

Aligne la documentation sur l'état réel du cluster au 2026-06-18 :

- Qdrant : crash-loop résolu le 17/06 (statut « HS / EN COURS » corrigé dans
  CLAUDE.md, README, admin/ia/rag.md, admin/incidents.md, admin/ia/stt.md).
  Précision : collection funk-docs supprimée lors de la réparation → re-ingest
  RAG encore à faire (pas de surévaluation du statut).
- STT (assistant vocal « Jarvis ») : ajouté partout (était déployé mais non documenté).
- Ghostfolio : ajouté partout (était déployé mais non documenté).
- Embeddings dédiés nomic-embed-text :1238 : marqués opérationnels (roadmap
  README disait encore « TODO »).
- llama-server : ×3 → ×4 (instance embeddings) ; gap IaC précisé (embeddings géré
  par le rôle, seules les 2 instances CPU restent manuelles).
- Structure k8s/ corrigée dans CLAUDE.md : ajout stt/ + ghostfolio/, suppression
  des sous-dossiers traefik/ + metallb/ inexistants (installés via helm au bootstrap).
- Namespaces et liste des secrets Vault (vault_pg_ghostfolio_password) complétés.
- admin/README.md : index complété (~10 docs manquants : email, n8n, open-webui,
  ghostfolio, k9s, stt, rag, hermes-voice/souls/auto-improve, alertmanager-webhook).
- Funk/ (conception d'origine : LM Studio + agents Goose, obsolète) déplacé sous
  archive/ avec bandeau « obsolète » + archive/README.md (historique git préservé).


Claude-Session: https://claude.ai/code/session_017Qjq5jHiqNepnobJpHYpCa

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
ALI YESILKAYA 2026-06-18 11:16:34 +02:00 committed by GitHub
parent e1ec26d546
commit c023ab0e58
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 102 additions and 31 deletions

View file

@ -6,17 +6,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
**Funk** — homelab IA composé d'un cluster Kubernetes (Talos) pour les services applicatifs, d'un hôte d'inférence LLM dédié (gpu-01 / llama-server ROCm), et d'un agent autonome (Hermes Agent) sur storage-01. Stack IaC complète : Ansible + talhelper + ArgoCD.
**État actuel (2026-06-10)** :
**État actuel (2026-06-18)** :
- ✅ Hermes Agent opérationnel — multi-profils (funk-ai/system/monitor/brain)
- ⚠️ RAG **HS depuis 2026-06-05** — Qdrant en crash-loop (segment `funk-docs` corrompu, voir `admin/incidents.md`) ; `rag-ingest` / `rag-query` indisponibles
- ✅ Qdrant réparé (2026-06-17) — fin du crash-loop (segment `funk-docs` corrompu, voir `admin/incidents.md`). ⚠️ La collection RAG `funk-docs` a été supprimée lors de la réparation → **re-`rag-ingest` requis** pour réactiver `rag-query`
- ✅ Monitoring complet — Prometheus + Grafana + AlertManager → webhook Hermes + n8n
- ✅ storage-01 installé — `192.168.10.1` (LAN cluster), `192.168.1.200` (WAN)
- ✅ gpu-01 installé — llama-server GPU (:1234) + CPU (:1236/:1237) + embeddings nomic-embed-text (:1238, GPU) opérationnels, kernel 5.14.0-687.5.3
- ✅ gpu-01 installé — llama-server GPU (:1234) + CPU (:1236/:1237) + embeddings dédiés nomic-embed-text (:1238, GPU) opérationnels, kernel 5.14.0-687.5.3
- ✅ LiteLLM sur storage-01 — proxy multi-modèles + ask-agent (écoute `0.0.0.0:4000`)
- ✅ Cluster k8s Talos opérationnel (MetalLB + Traefik + wildcard DNS lab.local)
- ✅ postfix_relay — SMTP sortant via Gmail SMTP + App Password (aliyesilkaya93@gmail.com)
- ✅ Open WebUI opérationnel — `openwebui.lab.local`, namespace `ai`, backend LiteLLM
- ✅ n8n opérationnel — `n8n.lab.local`, namespace `ai`, 3 workflows actifs (alertes, rapport horaire, Hermes Doc Worker)
- ✅ STT (assistant vocal « Jarvis ») — STT-server in-cluster (`stt.lab.local`, namespace `ai`) + client `stt` (pipx) ; mémoire long-terme Qdrant `stt-memory` validée 2026-06-17 (voir `admin/ia/stt.md`)
- ✅ Ghostfolio opérationnel — `ghostfolio.lab.local`, namespace `ai`, suivi de portefeuille (PostgreSQL s01 + Redis in-cluster)
- ✅ hermes-auto-improve — analyse quotidienne de `admin/` par Hermes à 22h (n8n → trigger :9095), PR sur `hermes/daily-work`
- ⏳ WOL compute nodes non configuré (BIOS) — allumage manuel requis
@ -111,7 +113,7 @@ Variables globales (non-secrètes) dans `ansible/group_vars/all/vars.yml` : `adm
Variables chiffrées dans `ansible/group_vars/all/vault.yml` :
- `vault_anthropic_api_key` — clé Anthropic pour le profil brain
- `vault_pg_hermes_password`, `vault_pg_litellm_password`, `vault_pg_n8n_password`, `vault_pg_openwebui_password`
- `vault_pg_hermes_password`, `vault_pg_litellm_password`, `vault_pg_n8n_password`, `vault_pg_openwebui_password`, `vault_pg_ghostfolio_password`
- `vault_postfix_relay_password` — App Password Gmail (relay SMTP)
- `vault_n8n_api_key` — clé API n8n (label "claude") pour gérer les workflows via `/api/v1`
@ -153,17 +155,21 @@ k8s/
│ └── apps/ # Un fichier Application par workload — ArgoCD les crée automatiquement
│ ├── n8n.yaml
│ ├── open-webui.yaml
│ ├── stt.yaml
│ ├── ghostfolio.yaml
│ ├── monitoring.yaml
│ └── nfs-provisioner.yaml
├── apps/ # Manifests raw k8s par application
│ ├── n8n/ # namespace: ai
│ ├── open-webui/ # namespace: ai
│ ├── stt/ # namespace: ai — STT-server (assistant vocal, stt.lab.local)
│ ├── ghostfolio/ # namespace: ai — suivi de portefeuille (ghostfolio.lab.local)
│ └── {external-services}/ # ExternalName/Endpoints pointant vers storage-01 ou gpu-01
└── infra/ # Helm releases (HelmRelease + values.yaml)
├── monitoring/ # kube-prometheus-stack 85.0.2
── nfs-provisioner/
├── traefik/
└── metallb/
── nfs-provisioner/
# ⚠️ Traefik + MetalLB ne sont PAS dans k8s/infra/ : ils sont installés via `helm install`
# lors du bootstrap Talos (voir admin/k8s/talos.md), hors pattern App-of-Apps ArgoCD.
```
### Ajouter un nouveau workload k8s
@ -172,7 +178,7 @@ k8s/
2. Créer `k8s/apps-of-apps/apps/<nom>.yaml` (ArgoCD Application CRD) — copier `n8n.yaml` comme modèle
3. `git commit` + `git push` → ArgoCD prend en charge automatiquement
Namespaces actifs : `argocd`, `infra` (Traefik, MetalLB, NFS-provisioner), `monitoring` (Prometheus/Grafana), `ai` (n8n, open-webui).
Namespaces actifs : `argocd`, `infra` (Traefik, MetalLB, NFS-provisioner), `monitoring` (Prometheus/Grafana), `ai` (n8n, open-webui, stt, ghostfolio).
---
@ -213,9 +219,9 @@ ask-agent monitor "logs litellm : <résultat étape 1> — erreurs ?"
### RAG — Documentation Funk
> ⚠️ **HS depuis 2026-06-05** — Qdrant en crash-loop (segment `funk-docs` corrompu). Réparation : supprimer la collection corrompue puis relancer `rag-ingest` (reconstructible depuis `admin/`).
> ⚠️ **Qdrant réparé le 2026-06-17** (fin du crash-loop, segment `funk-docs` corrompu — voir `admin/incidents.md`). La réparation a **supprimé** la collection `funk-docs` sans la reconstruire → relancer `rag-ingest` pour réactiver `rag-query`. Le service Qdrant et la mémoire long-terme STT (`stt-memory`) sont opérationnels.
Qdrant collection `funk-docs` indexée depuis `admin/` (339 chunks, score min 0.60).
Qdrant collection `funk-docs` indexée depuis `admin/` (339 chunks avant suppression, score min 0.60 ; à re-ingérer).
```bash
rag-query "comment relancer dnsmasq ?"