# 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.