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 (Treiber-Pinning, Docker)	✅ (ungetestet gegen echten Cluster)
11	CI	–	Gitea Actions: Tests, Lint, Compose-Validierung	✅

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.

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