diff --git a/README.md b/README.md index 99436d8..ff0db42 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,10 @@ Anfrage → n8n → Router-Service ──▶ Stufe 3 Embedding-Classifier (CPU) | [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 | +| [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md) | Arbeitspakete, Teststrategie, Stand der Verifikation, Ablauf des Deployments | +| [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 @@ -39,7 +42,8 @@ sites/knaster/ standortspezifisch: Inventar, Registry make dev # venv + Abhängigkeiten make test # Unit- und Integrationstests make lint # ruff -make validate # Compose-, Workflow- und Konfigurationsprüfung +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`). diff --git a/docs/BETRIEB.md b/docs/BETRIEB.md new file mode 100644 index 0000000..2ae9f7d --- /dev/null +++ b/docs/BETRIEB.md @@ -0,0 +1,73 @@ +# Betrieb: Skill-Lebenszyklus, Hermes, Pflege, Freischaltung + +## 1. Lebenszyklus eines Skills + +``` + Hermes schreibt SKILL.md + │ + draft ──(Mensch/Agent: aktivieren)──▶ active, Stufe 0 + │ läuft auf dem starken Modell mit Skill-Text, + │ sammelt verifizierte Fälle + Service-Routine: stabil ≥ 95 % ────┤ + ▼ + request_graduation (Freigabe) + │ Hermes erzeugt Varianten → + │ POST /v1/skills/{name}/graduate + ▼ + promote_skill (Freigabe) ──▶ active, Stufe 1 (schwaches Modell) + │ + Drift (Pass-Rate < 80 %) ──▶ demote_skill (automatisch) ──▶ demoted (Stufe 0) + │ + ≥ 300 Trainingsfälle, Stufe-1-Rate < 90 % ─▶ train_adapter (Freigabe) ──▶ Lifecycle-Pipeline +``` + +Stufe 2 (Programm) und Stufe 3 (Classifier) gibt es, wenn der Skill `execution: program|classifier` deklariert und die passende Stufe freigegeben ist. Programme liegen in `knaster/programs.py` und gehen wie normaler Code durch ein Review. Classifier entstehen aus gelabelten Fällen (`EmbeddingClassifier.train`) und liegen unter `config/classifiers/.json`. + +## 2. Rolle von Hermes + +Hermes läuft als Skill-Autor mit dem starken Modell. Er zeigt auf LiteLLM, Alias `tier0-strong`. Hermes steht **nicht** im Pfad jeder Anfrage. + +| Auslöser | Hermes tut | Schnittstelle | +|---|---|---| +| Job `graduate_skill` (über n8n `knaster-jobs`) | 10–30 realistische Varianten erzeugen, Graduierung aufrufen. Schlägt sie fehl, den Skill anhand von `failures` überarbeiten | `POST /v1/skills/{name}/graduate` | +| Job `merge_skills` | zwei Skills zu einem zusammenführen, alten Skill auf `retired` setzen | Git-Commit in `skills/`, dann `POST /v1/skills/reload` | +| Neue Aufgabenklasse (häufige `no_skill`-Fälle) | neuen `SKILL.md`-Entwurf schreiben (`status: draft`) | Git-Commit + Reload | + +Skills sind Dateien im Repo. Jede Änderung ist dadurch ein nachvollziehbarer Commit und lässt sich zurückdrehen. + +## 3. Pflege per Prompt (Beispiele) + +``` +> routine +Service-Routine +Befunde: +- Drift: zusammenfassung Pass-Rate 72% (n=40) +Automatisch erledigt: +- P-12: Skill zusammenfassung auf Stufe 0 zurückstufen → Skill zusammenfassung auf Stufe 0 zurückgestuft +Offene Vorschläge (genehmige P-x / lehne P-x ab): +- P-13 [low] LoRA-Adapter für rechnungen trainieren – 412 verifizierte Fälle, Stufe-1-Rate 86% + +> genehmige P-13 +P-13 executed: Kandidat 7f3e… (adapter) angelegt und Build gestartet + +> wechsle tier1-general auf qwen3-32b-awq +Vorschlag P-14 [medium] Basismodell von tier1-general auf qwen3-32b-awq wechseln … +Bestätige mit „genehmige P-14“. +``` + +Freitext, der keinem Befehl entspricht, bildet ein kleines Modell auf einen Befehl ab. Der Agent fragt dann mit „Meinst du …?“ zurück. + +## 4. Dry-Run aufheben (schrittweise) + +1. Eine Woche mit `KNASTER_DRY_RUN=true` laufen lassen. Die Healer-Ergebnisse stehen als `[dry-run] …` in den Antworten bzw. Logs. +2. `KNASTER_DRY_RUN=false` setzen. Interne Aktionen (Slot-Status, Skill-Stufen, Kandidaten) liefen schon vorher. Jetzt werden auch Jobs per Webhook verschickt. +3. Infrastruktur-Aktionen einzeln freischalten, über `config/healer-rules.yaml` → `enabled_actions: [restart_container]`, später `restart_vm`. `reboot_host` bleibt freigabepflichtig (Policy) und läuft nur im Wartungsfenster. + +## 5. Rollback-Wege + +| Was | Wie | +|---|---| +| Adapter/Basismodell | Prompt `rollback ` → Freigabe | +| Skill-Stufe | Prompt `stufe zurück` bzw. Git-Revert der SKILL.md | +| Treiber/Engine | Proxmox-Snapshot der GPU-VM (vor jedem Update anlegen) | +| Konfiguration | Git-Revert und Neustart des Router-Containers |