cluster-knaster/docs/spec/SPEC-lifecycle.md

SPEC-lifecycle: Kandidaten, Graduierung, Training

Pakete: knaster.lifecycle, knaster.graduation.

1. Kandidat

id, kind: base_model | adapter | quantization | embedding_model | engine
slot: str                     # betroffener Slot (bei adapter: Slot, dessen Basis passt)
target: {...}                 # z. B. {base_model: "qwen3-14b-awq"} oder {cluster: "rechnungen"}
baseline: {pass_rate?}        # Messwert der aktuellen Version
state, metrics{}, history[{ts, from, to, note}]

2. Zustände

proposed ──(Freigabe)──▶ building ──report(build_ok)──▶ evaluating
evaluating ──report(eval: pass_rate ≥ baseline − tolerance)──▶ shadow   (sonst ▶ rejected)
shadow ──report(shadow: agreement ≥ min_agreement, n ≥ min_n)──▶ canary   (sonst ▶ rejected)
canary ──report(canary: pass_rate ≥ baseline − tolerance, n ≥ min_n)──▶ awaiting_promotion (sonst ▶ rejected)
awaiting_promotion ──(Freigabe)──▶ promoted
promoted ──rollback──▶ rolled_back
jeder Zustand ──report(error)──▶ failed

Grenzwerte stehen in config/lifecycle.yaml: tolerance 0,02, min_agreement 0,85, min_n 50, canary_share 0,1.

Die Freigaben laufen über die Policy (create_candidate, promote_candidate). Promote schreibt in den Registry-Laufzeitzustand bzw. in die Adapterliste:

• base_model: Slot base_model wird umgestellt, alle Adapter der alten Basis werden retired, und für jeden Cluster mit Adapter entsteht ein Kandidat adapter (Neutraining).
• adapter: Der neue Adapter wird active, der bisher aktive für denselben Cluster und dieselbe Basis wird retired (bleibt als Rollback-Ziel erhalten).
• Rollback stellt den Zustand vor dem Promote wieder her (gespeichert in history).

Die Jobs selbst (Download, Quantisierung, Training, Eval) laufen extern, als Job-Runner auf gpu-flex. Sie melden ihr Ergebnis per POST /v1/lifecycle/candidates/{id}/report. Der JobRunner im Service stößt den Job an: Im Dry-Run wird nur protokolliert, sonst geht ein Webhook an n8n bzw. den Runner.

3. Graduierung (knaster.graduation)

graduate(skill, variants[], run_fn, verify_fn, threshold=0.9, min_variants=10) -> GraduationReport

• Jede Variante wird mit stage = 1 auf dem Skill-Slot ausgeführt (run_fn) und geprüft (verify_fn).
• passed = pass_rate ≥ threshold und n ≥ min_variants.
• Bei Erfolg entsteht ein Vorschlag promote_skill{skill, stage: 1} (Policy: approve), bei Misserfolg ein Bericht mit den fehlgeschlagenen Varianten. Diese gehen an das starke Modell, das den Skill überarbeitet.
• Die Varianten erzeugt das starke Modell (Hermes) und schickt sie an POST /v1/skills/{name}/graduate.

4. Adapter-Training (extern, Vertrag)

Eingang für den Trainingsjob: Export cases (split = train, passed = true, skill.cluster = X) plus optional preference_pairs. Ausgang: Adapter-Verzeichnis und report(build_ok, adapter_name). Die Eval nutzt die Fälle mit split = eval desselben Clusters.