172 lines
8.5 KiB
Markdown
172 lines
8.5 KiB
Markdown
# 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.
|