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,45 @@
+# cluster-knaster
+
+Ein starkes LLM erarbeitet neue Aufgaben und destilliert sie zu **Skills**. Danach übernehmen kleinere, selbst gehostete Modelle diese Aufgaben. Embeddings erkennen wieder, routen und treffen einfache Entscheidungen. Betrieb auf einem Proxmox-Cluster mit gemischten GPUs, gesteuert über n8n, mit halbautomatischer Pflege (Human-in-the-Loop).
+
+```
+Anfrage → n8n → Router-Service ──▶ Stufe 3  Embedding-Classifier (CPU)
+                     │          ├─▶ Stufe 2  Programm (CPU)
+                     │          ├─▶ Stufe 1  schwaches LLM + Skill (+LoRA) über LiteLLM → vLLM
+                     │          └─▶ Stufe 0  starkes LLM über LiteLLM → OpenRouter
+                     └─ Verifier → bestanden: Antwort + Fall speichern
+                                   → nicht bestanden: Eskalation + Präferenzpaar
+```
+
+## Dokumentation
+
+| Dokument | Inhalt |
+|---|---|
+| [docs/PLAN.md](docs/PLAN.md) | Architektur und Betrieb: Proxmox, Pflege, Autohealing, Lifecycle, Finetuning, Problemerkennung, Portabilität |
+| [docs/adr/](docs/adr/) | Architekturentscheidungen |
+| [docs/spec/](docs/spec/) | Spezifikationen der Komponenten |
+| [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md) | Arbeitspakete, Teststrategie, Ablauf des Deployments |
+
+## Repo-Struktur
+
+```
+core/              Python-Paket `knaster` (Router-Service) + Tests
+config/            Policy, Healer-Regeln, Grenzwerte (portabel)
+catalog/           Modell- und Rollenkatalog mit Hardware-Anforderungen
+skills/            SKILL.md-Bibliothek
+deploy/            Docker Compose pro Rolle, LiteLLM, Prometheus, Alertmanager
+n8n/workflows/     importierbare n8n-Workflows
+platform/proxmox/  OpenTofu + Ansible
+sites/knaster/     standortspezifisch: Inventar, Registry
+```
+
+## Entwicklung
+
+```bash
+make dev      # venv + Abhängigkeiten
+make test     # Unit- und Integrationstests
+make lint     # ruff
+make validate # Compose-, Workflow- und Konfigurationsprüfung
+```
+
+Alle Aktionen gegen Infrastruktur laufen standardmäßig im **Dry-Run** (`KNASTER_DRY_RUN=true`).