# 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 |
|---|---|
| [AGENTS.md](AGENTS.md) | **Einstieg für Agenten und neue Admins**: Arbeitsweise, Regeln, Muster |
| [project-map.md](project-map.md) | Was wo läuft: Rechner, Adressen, Dienste, Ports, Namespaces, Repo, Orte der Geheimnisse |
| [known-issues.md](known-issues.md) | Bekannte Probleme und Fallen |
| [docs/NOTFALL-ADMIN-UEBERGABE.md](docs/NOTFALL-ADMIN-UEBERGABE.md) | Notfall: Verwaltung an eine andere Person übergeben (für die Geschäftsführung) |
| [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/superpowers/plans/2026-10-12-aufbau-cluster-knaster.md](docs/superpowers/plans/2026-10-12-aufbau-cluster-knaster.md) | **Aufbauplan auf echter Hardware**: Phasen, Entscheidungen D1–D5, Zuordnung zu Planner Epic 7 |
| [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md) | Arbeitspakete, Teststrategie, Stand der Verifikation |
| [docs/BETRIEB.md](docs/BETRIEB.md) | Skill-Lebenszyklus, Rolle von Hermes, Pflege per Prompt, Dry-Run aufheben, Rollback |
| [n8n/README.md](n8n/README.md) | Workflows und Import |
| [platform/proxmox/README.md](platform/proxmox/README.md) | Proxmox-Ablauf (OpenTofu + Ansible) |

## 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 # Konsistenz Registry/Skills/LiteLLM/Healer/Policy/Katalog + Placement
make compose-check  # docker compose config für alle Rollen
```

Alle Aktionen gegen Infrastruktur laufen standardmäßig im **Dry-Run** (`KNASTER_DRY_RUN=true`).