creator/README.md

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.
• Uni-Skript: lädt ein Skript und liest es abschnittsweise.
• Projektordner: nutzt eigene Dateien als Quelle.
• Web-Link: crawlt eine Seite und filtert relevante Inhalte.

Inhalt erstellen

• Zerlegt den Stoff in einzelne Lern-Konzepte (Bausteine).
• Führt doppelt genannte Konzepte automatisch zusammen.
• Entfernt Bruchstücke, die keine eigenen Themen sind.
• Gliedert jeden Baustein in Teilpunkte.
• Belegt jeden Teilpunkt mit Fakten aus der Quelle.
• Stuft Teilpunkte nach Schwierigkeit ein (Anfänger/Fortgeschritten/Experte).
• Trennt Randthemen vom Kern.
• Ordnet Bausteine in Kapitel mit Voraussetzungs-Reihenfolge.
• Schreibt daraus einen lesbaren Guide.
• Drei Guide-Varianten: fokussiert, komplett, nur Randthemen.
• Erzeugt Karteikarten und durchgerechnete Beispiele.

Guide-Ansicht

• Zeigt Mathe-Formeln korrekt gerendert.
• Umschalten zwischen kurzer und ausführlicher Darstellung.
• Filtert den Guide nach Lernstufe.
• Prüft schwer lesbare Sätze und vereinfacht sie.
• Einzelne Abschnitte auf Knopfdruck neu prüfen.

Lernen & Prüfen

• Übungsfragen je Baustein generieren.
• Vier Frageformen: Quiz, Lückentext, Freitext, Erklären.
• KI bewertet Freitext-Antworten mit Begründung.
• Punkte-System mit Stufen und Streak je Baustein.
• Themenweite Gesamt-Prüfung über alle Bausteine.
• Chat-Nachfrage zu jedem Baustein.
• Fokus-Modus: Guide und Prüfung nebeneinander.

Eigene Elemente

• Eigene Lern-Notizen per Stichwort erstellen lassen.
• Notizen im Chat anpassen; KI prüft Lücken und Stil.

Steuerung

• KI-Anbieter wählen: Claude, MiniMax, lokal.
• Generierung ab jedem Schritt neu starten.
• Ab jedem Schritt löschen, ohne neu zu generieren.
• Laufende Generierung abbrechen oder fortsetzen.
• Live-Fortschritt sehen.
• Dark Mode.