Training-Harness (ACO, Multi-Fidelity), Prüfstand-Benchmark, Agenten-README

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -1,4 +1,127 @@
-# Creator — Features
+# Creator
+
+KI-Lernguide-Generator: Aus einem Thema, Uni-Skript, Projektordner oder Web-Link entsteht
+ein vollständiger, belegter Lernguide mit Übungssystem. FastAPI-Backend (`backend/`),
+Vue-Frontend (`frontend/`), SQLite (`storage/creator.db`). MiniMax generiert über die
+OpenCode-CLI, Judge-Agenten prüfen jede Stufe.
+
+**Diese README ist das Onboarding für den nächsten KI-Agenten.** Endnutzer-Features stehen
+unten. Persistente Detail-Notizen liegen im Claude-Memory des Projekts; dieses Dokument
+trägt das Wesentliche.
+
+## Wofür das Projekt gebaut wird (die Gründe des Betreibers)
+
+- Lernen mit **Entscheidungsautomatik statt Wahlfreiheit**: Das System zerlegt, priorisiert
+  und prüft — der Lernende folgt dem Pfad, statt ihn zu bauen.
+- **100-%-Zerlegung** des Stoffs in Bausteine und Subbausteine, jede Aussage mit Beleg.
+- **MECE-Nordstern** (Kern des Projekts, wörtlich): „Man kann keinen Baustein entfernen,
+  ohne eine Lücke zu erzeugen, und keinen hinzufügen, ohne dass eine Dopplung entsteht."
+- Ideal: „Die Pipeline läuft durch, es ist eine 10/10, die Inhalte sind super —
+  nicht zu viel, nicht zu wenig, korrekt."
+
+## Entwicklungsphase: die vier Optimierungsziele
+
+Alle Arbeit optimiert, themenunabhängig:
+1. **Qualität** — Korrektheit maximieren.
+2. **Auswahl** — Lücken und Dopplungen minimieren (MECE).
+3. **Performance** — Gesamtlaufzeit minimieren.
+4. **Tokenverbrauch** — Generierung günstig halten.
+
+Fixes gehören in die **Pipeline** (Generierung). QA misst nur — Detektor-Konstanten und
+Notengewichte sind nie Teil einer Optimierung (Messinvarianz).
+
+## Architektur in einer Minute
+
+Drei Kanban-Boards (Engine: `kanban.py`, Karten in SQLite, resümierbar):
+1. **Inventar** (`board_inventory.py`): Research-Reader → Titel-Ingest → Cluster →
+   Konsens-Gate (+ Anker-Beleg gegen Kanon-Halluzination) → Naming (darf abstrahieren,
+   Anker-Pflicht) → Fragment-Filter → Dedup → Gruppierung → fertige Blöcke.
+   Danach QA-Gate (Note < 9.5 pausiert vor Board 2).
+2. **Artefakte** (`board_artefacts.py`): Subbausteine finden (Panel-Konsens) → Facts
+   (extract-once, Grounding für alles Spätere) → In-Block-Konsolidierung + Lücken-Nachfass
+   → Levels → Relevanz → Cross-Block-Dedup (Barriere, gechunkt) → Fragen → Flashcards/
+   Beispiele → Finalize (DB-Spiegel, Hygiene) → Outline.
+3. **Guide** (`guide_board.py`): Lernziele → Writer (Marker-Format, Längen-Budget) →
+   Fakten-Gate (CoVe; „falsch" fixt immer, „unbelegt" ab Schwelle) → Coverage → Lesbarkeit.
+
+Agenten-Rollen: `quick`/`fast` generieren, `judge` prüft (native MiniMax-Route — die
+kalt-Route stallte 20 % der Calls), `guide` schreibt. Große JSON-Antworten kommen als
+TEXT zurück (`_sink_or_file`) — Datei-schreibende Agenten verloren 40 Runden in
+JSON-Reparatur-Schleifen.
+
+## Arbeitsregeln (verbindlich, aus Erfahrung destilliert)
+
+- **Nie committen/pushen.** Der Betreiber committet selbst.
+- **Ändern nur auf Auftrag.** Beobachtungen berichten, nicht eigenmächtig fixen.
+  Ergebnisse nie nachträglich schönen.
+- **Kein Backend-Edit bei laufendem Flow**: vorher `curl -s localhost:8000/api/blocks/active`
+  == `[]` prüfen — `backend/*.py`-Edits triggern den uvicorn-Reload und killen Läufe.
+  `templates/` und `Makefile` sind gefahrlos.
+- **Generisch bleiben**: keine Domänen-Sonderregeln in Pipeline/Prompts. Quellen-Spezifika
+  löst der Import.
+- **Ursachen statt Symptome**: erst messen (Events, QA-Reports, OpenCode-Session-DB),
+  dann fixen. Kein Raten.
+- **Fragen zuerst beantworten**, dann handeln. Antworten knapp und auf Deutsch.
+- Keine Bewertungen fremder KI-Modelle/Provider (Geschwindigkeit, Qualität).
+- `.env` enthält echte API-Keys — nie exponieren.
+
+## Werkzeuge für Entwicklung und Diagnose
+
+| Kommando | Zweck |
+|---|---|
+| `make test` | ganze Suite (~240 Tests, ~20 s), inkl. Fake-E2E |
+| `make test-e2e` | nur Fake-E2E: kompletter Generierungspfad in Sekunden, ohne LLM |
+| `make qa TOPIC=… [LLM=1]` | Inventar-/Artefakt-QA read-only, Note 0–10 |
+| `make qa-guide TOPIC=… [LLM=1]` | Guide-QA |
+| `make train-init` | Frozen-Inventar-Vorlage für das Training bauen (einmalig) |
+| `make train [TRIALS] [STUNDEN] [AMEISEN]` | Ameisen-Optimierung der Parameter (anytime) |
+| `CREATOR_FAKE_AGENTS=1 make dev` | Server antwortet aus der Fake-Welt — UI-Smoke in Sekunden |
+| `CREATOR_PARAMS='{"X":1}'` | Parameter-Override pro Prozess (Registry: `backend/train_params.py`) |
+
+Diagnose-Quellen: `events`-Tabelle (Agent-Dauern/Tokens/Status je Lauf),
+`storage/qa/<topic>/*.json` (Report-Historie), `arbeit/lauf-summary.json`,
+OpenCode-Session-DB (`~/.local/share/opencode/opencode.db` — Turns/Tokens je Agent).
+
+## Training (`make train`)
+
+Ameisen-Algorithmus (ACO), anytime: Pheromon-Gewichte je Parameter-Stufe steuern die
+Kandidaten; je länger er läuft, desto gezielter die Tests. Drei Fidelity-Stufen:
+F0 Fake-E2E (0,5 s, Invarianten + Struktur-Proxy), F1 Frozen-Inventar (~5–8 min, Board 2
+auf kopiertem Inventar), F2 Volllauf mit Soll-Abgleich gegen
+`benchmarks/pruefstand/soll.json` (konstruiertes Thema mit bekannter Lösung und
+eingebauten Fallen). Übernahme nur nach Bestätigungslauf. Ergebnis:
+`storage/train/aco/{report.md, beste_params.json}`; Übernahme nach `config.py` ist
+manuell.
+
+## Entwicklungs-Meilensteine (was schon gelernt wurde)
+
+- MECE-Regelkreis: In-Block-Konsolidierung (2-Judge-Panel, Einstimmigkeit), Lücken-Nachfass
+  mit hartem Beleg-Gate, Cross-Block-Dedup mit Stichentscheid — Sub-Zahl 425→~213 bei
+  steigender Note.
+- Drei stabile QA-Noten (Inventar/Artefakte/Guide) mit Bestätiger-Pässen gegen
+  Judge-Rauschen; Repair arbeitet Befunde gezielt ab.
+- Resume-Dateien tragen einen Sub-Satz-Hash — Re-Runs übernehmen nie stale Ergebnisse;
+  Finalize löscht Alt-Reste (Lösch-Hygiene überall).
+- Facts-Nachfass: kein consensus-Sub ohne Grounding (sonst flutet das Fakten-Gate).
+- Judge-Stalls (20 % Timeouts) lagen an einer Provider-Route — Messen vor Raten.
+- Naming darf abstrahieren, aber nur korpus-verankert (Kanon-Halluzinations-Schutz).
+
+## Offene Ideen / nächste Schritte
+
+- Training auf dem Server laufen lassen (siehe unten), wirksame Parameter übernehmen.
+- Facts-Chunks parallelisieren; Live-Aktivität (Token-Zähler) an laufenden Karten zeigen.
+- Bekannte Cross-Dubletten knapp unter dem 0.75-Kandidaten-Floor.
+- Roadmap-Lernarchitektur: ein Guide + Stufen-Ansichten, ELO-Score mit wachsendem Cap.
+
+## Server-Betrieb mit 8 GB RAM
+
+- `.env`: `MAX_CONCURRENT_AGENTS=6`, `MAX_CONCURRENT_AGENTS_PER_TOPIC=6`.
+- Training: `make train AMEISEN=1` (jeder parallele Trial lädt das Embedding-Modell, ~1 GB).
+- Embedding + Readability halten zusammen ~1 GB im Backend-Prozess. 2–4 GB Swap anlegen.
+
+---
+
+# Features (Endnutzer-Sicht)
 
 ## Quellen
 - Freies Thema: die KI recherchiert den Stoff selbst im Web.