Files

T

Kantin-Petit c096fa9467 docs: conventions versioning + doc + paliers de risque (v0.2.0)

Pose les règles non négociables : SemVer + un-artefact-un-commit, pinning
des images, export JSON des workflows n8n ; gabarit de doc d'asset ;
paliers réversible/privilégié avec invariant anti-escalade ; schéma
d'architecture et invariants d'exposition. Ignore settings.local.json.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-23 00:59:25 +02:00

3.4 KiB

Raw Blame History

Architecture CHLOVA

Vue d'ensemble. Les règles non négociables font foi dans CLAUDE.md.

Principe

CHLOVA est une couche d'orchestration : un LLM en boucle tool-calling (comprendre → choisir un outil MCP → agir → observer → répondre) posée au-dessus d'un homelab Debian + Docker + Traefik existant.

Schéma logique

        mobile (client léger)
              │  Telegram (long-polling, zéro port ouvert)
              ▼
   ┌─────────────────────────┐        réseau Docker interne (chlova-internal)
   │   Backend CHLOVA        │   ─────────────────────────────────────────────
   │  (seule surface exposée)│        ┌───────────┐   ┌──────────────┐
   │   - boucle agent        │ ─────► │  Ollama   │ ─►│ ollama.com    │ (egress)
   │   - registry MCP        │        │ (proxy    │   │ modèles :cloud│
   │   - gatekeeper (P2+)    │        │  cloud)   │   └──────────────┘
   │   - audit log           │        └───────────┘
   └─────────────────────────┘
        │ MCP (stdio/http interne)
        ├───────────────► MCP n8n  ──► n8n API (interne)
        └───────────────► MCP Portainer ─► socket-proxy ─► Docker / Portainer

Invariants

Une seule surface exposée : le backend CHLOVA (auth + TLS). Tout le reste (Ollama, n8n, Portainer, serveurs MCP) n'écoute que sur chlova-internal.
Ollama sans auth native → jamais exposé ; il sort vers ollama.com pour les modèles :cloud (egress filtré, seul ollama.com autorisé).
Accès Docker via socket-proxy uniquement (pas de socket brut dans l'agent).
Secrets par référence : l'agent ne voit jamais les valeurs en clair.

Boucle agent (Phase 1, lecture seule)

Message texte (Telegram) → backend.
Backend appelle Ollama /api/chat avec la liste d'outils MCP read-only.
Le modèle choisit un outil → le backend l'exécute via le serveur MCP.
Observation renvoyée au modèle → réponse finale → utilisateur.
Toute exécution d'outil est audit-loggée.

En Phase 1, le readonly-filter garantit que seuls les outils readOnlyHint=true sont exposés : aucun risque d'écriture.

Évolutions (interfaces posées, non implémentées)

Gatekeeper + table assets : vérifie le statut avant chaque exécution (P2).
Cycle need-review : PROVISOIRE → APPROUVÉ/REFUSÉ/BLOQUÉ + cron horaire (P2).
Auto-extension : création d'outils/workflows en "need review" (P4).
Voix : STT + wake-word + TTS (P5), après un cerveau fiable.

Composants & contrats

Composant	Image / lib	Exposition	Palier
Backend CHLOVA	code maison (TS)	seule surface	—
Ollama (proxy cloud)	`ollama/ollama` épinglé	interne	—
MCP n8n	`czlonkowski/n8n-mcp` épinglé	interne	read-only (P1)
MCP Portainer	`portainer/portainer-mcp` épinglé	interne	read-only (P1)
socket-proxy	`tecnativa/docker-socket-proxy` épinglé	interne	scoping Docker

3.4 KiB Raw Blame History