cluster-knaster/docs/IMPLEMENTATION.md

Umsetzungsplan

Vorgehen pro Baustein: Spec → Implementierung → Tests → Commit. Bis zum gemeinsamen Deployment wird nichts auf Produktivsysteme ausgerollt. Alle externen Aufrufe (LLMs, Proxmox, Portainer, n8n) sind hinter Schnittstellen gekapselt und in Tests durch Fakes ersetzt.

Arbeitspakete

#	Paket	Spec	Inhalt	Status
1	Grundlagen	SPEC-core §1–2	Settings, Registry, Skill-Parser, Store (SQLAlchemy, SQLite/Postgres)	✅
2	Routing	SPEC-core §3–4	Embedding-Client, Skill-Index, Reranker, Token-Budget, Router, Eskalation	✅
3	Ausführung	SPEC-core §5–7	LLM-Client, Executor (Stufe 0–3), Signale, Verifier, Fälle/Präferenzpaare, Kalibrierung	✅
4	Pflege	SPEC-maintenance	Policy, Vorschläge, Service-Routine, Befehlsgrammatik, Intent-Mapper	✅
5	Healing	SPEC-healer	Regel-Engine, Treiber (Portainer, Proxmox, Notify), Dry-Run	✅
6	Lifecycle	SPEC-lifecycle	Kandidaten-Zustandsmaschine, Promote/Rollback, Graduierung	✅
7	Portabilität	SPEC-inventory	Inventar-Parser, Katalog, Placement, CLI	✅
8	API	SPEC-core §8	FastAPI-App, Auth, Metriken	✅
9	Deployment-Artefakte	PLAN §1, §3	Compose pro Rolle, LiteLLM, Prometheus-Regeln, Alertmanager, n8n-Workflows	✅
10	Plattform	ADR-0001/0002	OpenTofu (bpg/proxmox), Ansible-Rollen (IOMMU/VFIO, ZFS-Replikation, Treiber-Pinning, Xid-Exporter)	✅ geschrieben, nicht gegen echten Cluster/tofu validate geprüft
11	CI	–	Gitea Actions: Tests, Lint, Konfig-Validierung (Runner gitrunner-knaster)	✅
12	TTS + Legacy-GPUs	ADR-0006	Engine-Grenzen im Katalog, deaktivierte GPUs, geteilte GPU-Rollen, TTS-Slots, Piper-Dienst, TTS-Canary, knaster bench tts	✅

Teststrategie

• Unit-Tests pro Modul (core/tests), deterministisch und ohne Netz. Für Embeddings kommt ein HashingEmbedder zum Einsatz (Bag-of-Words, normalisiert). Er liefert reproduzierbare Ähnlichkeiten.
• Integrationstests der API mit FastAPI-TestClient, Fake-LLM und SQLite im Speicher. Sie decken die komplette /v1/run-Schleife inkl. Eskalation und Präferenzpaar ab.
• Artefakt-Tests: Compose-Dateien, Prometheus-Regeln, LiteLLM-Konfiguration und n8n-Workflows werden strukturell geprüft (YAML/JSON gültig, referenzierte Knoten vorhanden, Slots konsistent zur Registry).
• Nicht getestet bis zum gemeinsamen Deployment: echte Modelle, Proxmox-API, Portainer-Aktionen, OpenTofu-Apply.

Stand der Verifikation

Was	Wie geprüft
Kernlogik (Router, Eskalation, Verifier, Pflege-Agent, Healer, Lifecycle, Placement)	136 Unit- und Integrationstests (make test)
Konfiguration (Registry ↔ Skills ↔ LiteLLM ↔ Healer ↔ Policy ↔ Katalog)	knaster validate
Compose-Dateien	docker compose config (make compose-check)
Prometheus/Alertmanager/n8n-JSON	Strukturtests (core/tests/test_artifacts.py)
n8n, Portainer	nur lesender Erreichbarkeitstest, nichts deployt
OpenTofu, Ansible	nur YAML/Syntax. tofu validate und ansible-lint stehen noch aus

Offene Punkte vor dem Deployment

• Image-Tags pinnen: LiteLLM (main-stable) und pve-exporter (latest). vLLM-, llama.cpp- und Treiber-Versionen gegen den aktuellen Stand prüfen.
• LiteLLM-Wildcard-Routen (tier1-general/*) gegen die eingesetzte Version testen.
• Den n8n Chat-Trigger nach dem Import prüfen (Parameter der Knotenversion).
• sites/knaster/*: Hosts, VM-IDs, IPs und PCI-Adressen sind Annahmen und werden durch den Inventarlauf ersetzt.
• Classifier ticket-kategorie.json entsteht erst aus gelabelten Fällen (Warnung von knaster validate).
• Qwen3-TTS-Server für tts-de-hq auswählen (OpenAI-kompatibler Wrapper um faster-qwen3-tts) und Image setzen.
• Benchmark-Tag: llama-bench auf P2000 (und M4000), knaster bench tts für beide TTS-Slots, dazu Strom messen. Ergebnisse in Katalog und Registry übernehmen.

Gemeinsames Deployment (später)

1. Inventarlauf auf allen Nodes → sites/knaster/inventory.yaml ergänzen → knaster placement plan
2. Proxmox: ZFS-Pools, Resource Mappings, Templates (platform/proxmox)
3. Infra-LXC: deploy/compose/infra mit KNASTER_DRY_RUN=true
4. GPU-VMs nacheinander, nach jeder Rolle Canary-Checks
5. n8n-Workflows importieren (zuerst inaktiv), Credentials setzen
6. Dry-Run eine Woche beobachten, dann Aktionen einzeln freischalten