docs: Architekturplan, ADRs, Spezifikationen und Umsetzungsplan

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 14:00:36 +02:00
commit fef930d176
15 changed files with 854 additions and 0 deletions
@@ -0,0 +1,17 @@
+# ADR-0001: GPU-Nodes als VM, Infrastruktur als LXC
+
+- Status: angenommen
+- Datum: 2026-10-11
+
+## Kontext
+Im Cluster stecken GPUs aus drei Generationen: Maxwell (M4000), Pascal (P2000) und Ada (RTX 4000 Ada). Maxwell und Pascal werden von CUDA 13 nicht mehr unterstützt, vLLM verlangt Compute Capability ≥ 7.0. Ein LXC nutzt immer den Treiber des Hosts.
+
+## Entscheidung
+- Jede GPU-Rolle läuft in einer **VM mit PCI-Passthrough** und eigenem, fest gepinntem Treiber. Ada bekommt einen aktuellen Treiber, Maxwell und Pascal einen Treiber der Reihe CUDA 12.x.
+- GPUs werden über **Proxmox Resource Mappings** angesprochen (`gpu-ada-1`, `gpu-p2000-1`, …), nicht über PCI-Adressen.
+- CPU-Dienste (n8n, LiteLLM, Router, Postgres, Monitoring) laufen in **LXC** bzw. einer kleinen VM, jeweils mit Docker Compose.
+
+## Folgen
+- Der VM-RAM ist bei Passthrough vollständig reserviert. Er wird deshalb knapp bemessen: llama.cpp-VMs 6–8 GB, vLLM-VMs 24–32 GB.
+- Keine Live-Migration für GPU-VMs. Bei einem Ausfall springt der Router auf einen anderen Slot oder auf Stufe 0.
+- Treiber-Updates laufen pro VM, abgesichert durch einen Snapshot.
@@ -0,0 +1,18 @@
+# ADR-0002: ZFS lokal + Replikation statt Ceph
+
+- Status: angenommen
+- Datum: 2026-10-11
+
+## Kontext
+Die Nodes sind mit **1 GbE** verbunden. Jede physische Maschine hat 2–3 SSDs mit 128–256 GB. Ceph braucht für brauchbare Latenz und Rebuilds mindestens 10 GbE und genug Platz pro OSD.
+
+## Entscheidung
+- Pro Node ZFS: SSD 1 für das System, SSD 2+3 als Mirror `tank` (bei nur 2 SSDs: Einzel-SSD `tank`).
+- Proxmox-**ZFS-Replikation** alle 15 Min. für die Infra-VMs bzw. -LXCs auf einen Partner-Node, kombiniert mit Proxmox HA.
+- **Modelle lokal** auf der GPU-VM (eigenes Disk-Image, weder repliziert noch gesichert). Quelle: Hugging Face oder ein optionaler Modell-Mirror (HTTP, nur lesend).
+- **PBS** für Postgres, Konfiguration und Datensätze.
+
+## Folgen
+- Bei einem Node-Ausfall gehen höchstens 15 Min. Daten der Infra-VMs verloren. Postgres sichert sich zusätzlich über WAL-Archivierung bzw. PBS.
+- Modellwechsel verursachen Downloads (10 GB ≈ 90 s über 1 GbE). Das ist akzeptabel.
+- Die Speicherbudgets pro Rolle stehen in PLAN.md, Abschnitt 1.4.
@@ -0,0 +1,14 @@
+# ADR-0003: Slots statt Modellnamen, eine Lifecycle-Pipeline
+
+- Status: angenommen
+- Datum: 2026-10-11
+
+## Entscheidung
+- Clients (n8n, Hermes, Skills) sprechen **Slots** an (`tier1-general`, `verifier-small`, …). Was hinter einem Slot steht (Basismodell, Adapter, Engine, Node), legt nur die Registry fest.
+- Jede Änderung hinter einem Slot ist ein **Kandidat**, egal ob Basismodell, Adapter, Quantisierung, Embedding-Modell oder Engine. Jeder Kandidat durchläuft dieselbe Pipeline: Build → Eval → Shadow → Canary → Promote, mit Rollback.
+- Adapter sind über `(base_model, cluster, version)` adressiert. Ein Basiswechsel zieht das Neutraining der Adapter nach sich.
+- Trainingsdaten werden **modellneutral** gespeichert (Nachrichtenlisten ohne Chat-Template).
+
+## Folgen
+- Ein Modellwechsel ist eine Registry-Änderung und betrifft keinen Workflow.
+- Die Pipeline muss pro Kandidatentyp wissen, welche Golden Sets sie prüft.
@@ -0,0 +1,17 @@
+# ADR-0004: Halbautomatische Pflege über einen Pflege-Agenten (HITL)
+
+- Status: angenommen
+- Datum: 2026-10-11
+
+## Kontext
+Der Mensch soll Pflegeaufträge per Prompt erteilen können und regelmäßig durch eine Service-Routine geführt werden. Vollautomatik ist bei qualitäts- und kostenrelevanten Schritten nicht gewünscht.
+
+## Entscheidung
+- Der Pflege-Agent sammelt Befunde, erzeugt **Vorschläge** und führt nur Freigegebenes aus.
+- Aufträge des Menschen werden zu Vorschlägen und brauchen eine Bestätigung.
+- Die **Freigabe-Richtlinie** (`config/policy.yaml`) entscheidet pro Aktionstyp über `auto` oder `approve`. Grundsatz: Schritte in die sichere Richtung laufen automatisch, Schritte, die Qualität oder Kosten ändern, brauchen eine Freigabe.
+- Befehle werden zuerst über eine **feste Grammatik** verstanden. Ein LLM darf Freitext nur auf diese Befehle abbilden und löst niemals selbst eine Aktion aus.
+
+## Folgen
+- Jede Aktion ist nachvollziehbar (Vorschlag, Freigabe, Ausführung, Ergebnis).
+- Der Agent ist austauschbar: Der Kanal kann n8n Chat, Telegram oder Matrix sein, die Logik liegt im Router-Service.
@@ -0,0 +1,14 @@
+# ADR-0005: Deterministisches Autohealing, Kernlogik im Service statt in n8n
+
+- Status: angenommen
+- Datum: 2026-10-11
+
+## Entscheidung
+- Der Healer arbeitet eine **Regeltabelle** ab (`config/healer-rules.yaml`). Für jedes Alert-Muster gibt es eine Eskalationsleiter von Aktionen, jeweils mit Versuchsbudget und Cooldown. Sind alle Versuche erschöpft, wird ein Mensch benachrichtigt.
+- Alertmanager liefert **direkt** an den Router-Service, nicht über n8n. So funktioniert das Healing auch, wenn n8n ausfällt.
+- Die Schleife aus Routing, Ausführung, Verifikation und Eskalation steckt testbar im Service (`/v1/run`). n8n übernimmt Trigger, Authentifizierung, Antwort, Benachrichtigung und die HITL-Kanäle.
+- Alle Aktionen laufen standardmäßig im **Dry-Run**, bis sie pro Aktionstyp freigeschaltet werden.
+
+## Folgen
+- Weniger Logik in n8n, dafür Unit-Tests für die gesamte Entscheidungslogik.
+- Ein Ausfall von n8n betrifft nur die Eingangskanäle, nicht das Healing.