adaptive-learner-content-test

Starter-Kit für eigene Adaptive Learner Lektionen. Forke dieses Repo und erstelle deine eigenen Inhalte.

Anleitung: docs/GETTING-STARTED.md

Was ist drin

• docs/: GETTING-STARTED.md und LESSON-FORMAT.md (lokale Zusammenfassung; die kanonische, testvalidierte Format-Referenz ist die learn-content-engine docs/lesson-format.md, gespiegelt in schema/).
• templates/: Vorlagen je Domäne (language / programming / knowledge) für das Single-JSON-Lektionsformat.
• Eine vollständige Beispiel-Lektion zum Nachlesen, den Inception-Effekt, führt das offizielle Repo. Als lauffähiges Set lebt sie inhaltsgleich als Lektion 106 des psych-intro-Sets in alc-psychology.
• sets/: lauffähige Test-Sets, im Wurzel-manifest.yaml registriert.
• books.yaml: Buchempfehlungen je Domäne.
• scripts/validate_content.py: lokaler Validator.
• scripts/generate_exercises.py: optionaler KI-Aufgaben-Generator (siehe unten).

Bewertungs-Pilot

Zwei Test-Sets prüfen, ob eine App den evaluation-Block eines Sets anwendet (Format-Referenz; erster Consumer: adaptive-learner#3736):

• evaluation-pilot-from-de („Hauptstädte Europas (Test mit Bestehensgrenze)“) erklärt evaluation: { scheme: pass_fail, pass_percent: 60, title: Hauptstadt-Prüfung }, im Wurzel- und im Set-Manifest identisch (eine Abweichung meldet die Engine als E-MANIFEST-ENTRY-MISMATCH).
• evaluation-pilot-control-from-de („Hauptstädte Europas (Test ohne Bestehensgrenze)“) enthält dieselbe Lektion ohne Block.

Jede der beiden Lektionen hat zehn gleichwertige Aufgaben, sieben richtige ergeben genau 70 Prozent. Testszenario in der App:

1. Dieses Repo als eigenes Content-Repo verbinden; es ist keine Standardquelle der App.
2. Einstellungen › Lernen › „In der Lektion“ › Lektionsmodus: den Standardmodus auf „Prüfen“ (der Prüfungsmodus, englisch „Exam“) und die Bestehens-Grenze auf 80 % setzen. Die Bewertung des Sets erscheint nur im Prüfungsmodus; im Modus „Üben“ zeigt die Zusammenfassung wie bisher Prozent und Sterne.
3. Pilot-Lektion mit 7 von 10 richtigen Antworten: Die Ergebniskarte heißt „Hauptstadt-Prüfung“ statt „Prüfungsergebnis“, zeigt „Bestanden“ und den Hinweis, dass nach den Vorgaben des Sets bewertet wurde (60 Prozent). „Nicht bestanden“ hieße, die App hat ihre eigene Grenze angewendet. Eine Note gibt es hier nicht: Das Set nutzt pass_fail, Noten zeigt nur scheme: grades.
4. Kontroll-Lektion mit 7 von 10 richtigen Antworten: erwartet wird „nicht bestanden“ gegen die eigene Schwelle von 80 Prozent.

Eigene Inhalte lokal prüfen

python3 scripts/validate_content.py

Exit-Code 0, wenn alle Sets bestehen; sonst 1 mit einem Bericht je Datei. Der Validator braucht Python 3 und die Pakete aus requirements.txt (pip install -r requirements.txt; make validate legt dafür ein eigenes venv an).

Vor dem Push zusätzlich das Engine-Gate lokal laufen lassen: dieselben semantischen Regeln (E-CARD-REF, Cloze-Marker, Multiple-Choice-Regeln) und Qualitäts-Mindestanforderungen, die sonst erst die CI meldet:

make lint

Der erste Lauf installiert die in schema/engine-version.txt gepinnte Engine lokal nach node_modules/ (gitignored; braucht Node.js und npm), danach laufen Selbsttest und der volle Engine-Lauf wie im CI-Workflow Engine conformance. Optional gibt make lint-warnings die Warnungen (W-*) des Engine-Gates über alle Lektionen aus.

Ein Set für KI-Review exportieren

scripts/export_set.py schreibt alle Lektionen EINES Sets in eine einzige YAML- (oder JSON-) Datei, damit ein KI-Assistent oder ein Mensch das ganze Set in einem Durchgang prüfen kann (Syntax, Korrektheit, Konsistenz über die Lektionen hinweg):

python3 scripts/export_set.py graded-quiz-demo
# -> exports/graded-quiz-demo-de-<timestamp>.yaml
python3 scripts/export_set.py graded-quiz-demo --format json --out /tmp/review.json

Der Slug ist die Set-Id aus dem Wurzel-manifest.yaml (graded-quiz-demo-from-de) oder der Ordnername des Set-Pfads (graded-quiz-demo); bei gleichnamigen Ordnern unter mehreren Quellsprachen entscheidet --lang (Default de). Umlaute bleiben echtes UTF-8. Ein unbekannter Slug bricht mit einer Liste der verfügbaren Sets ab.

Der Export ist selbsttragend: das erste Feld review_instructions enthält den kompletten Review-Prompt aus docs/ai-review-prompt-template.md (zur Laufzeit gelesen, nicht im Skript kopiert). Die Exportdatei kann also direkt und ohne manuell vorangestellten Prompt an eine Review-KI gegeben werden. Änderungen an der Review-Anweisung in der Template-Datei vornehmen und in den Geschwister-Content-Repos synchron halten.

Nur-Lese-Snapshot, KEIN Re-Import-Format: Der Export wird nirgends zurückgelesen. Änderungen fließen ausschließlich über die einzelnen schema-validierten Lektions-JSONs unter sets/ ein. Der Ordner exports/ ist gitignored.

Ausführliche Anleitung und Best Practices (u. a. Quellkapitel-Workflow): docs/export-set-usage.de.md (Deutsch) / docs/export-set-usage.md (English).

Aufgaben mit KI generieren (optional)

scripts/generate_exercises.py erzeugt aus einem Thema eine vollständige Lektion mit einem KI-Modell und lässt jeden Entwurf durch denselben Validator laufen, bevor er geschrieben wird. Das Prinzip ist erst Entwurf, dann validieren: Nichts landet direkt in sets/, sondern zuerst im Staging-Ordner generated/.

Setup (BYOK: dein Schlüssel, aus der Umgebung, nie im Repo):

pip install -r requirements.txt         # dieselben Deps wie der Validator
make lint                               # installiert einmalig die gepinnte Engine
export ANTHROPIC_API_KEY="sk-..."       # oder OPENAI_API_KEY / GEMINI_API_KEY

Aufruf:

python3 scripts/generate_exercises.py \
  --topic "Im Café bestellen" \
  --target-lang fr --source-lang de --level A1 \
  --set-id fr-a1 --count 6

Anbieter-agnostisch: --provider anthropic|openai|gemini (Default anthropic), Modell per --model überschreibbar. Der Ablauf ist ein Schleifen-Gate: Der Prompt gibt die exakte Lektions-JSON-Form vor, die Antwort wird geparst und geprüft, erst gegen das gespiegelte Schema, dann durch die gepinnte Engine (scripts/engine_check.mjs: semantische Regeln wie cloze ___-Marker == blanks, card_ids-Integrität, multiselect-Disjunktheit, dazu die Qualitäts-Mindestanforderungen). Schlägt die Prüfung fehl, gehen die Fehler zurück ins Modell und es versucht es erneut (begrenzt). Ein Entwurf, der nie besteht, wird verworfen, nicht geschrieben. Ohne installierte Engine bricht der Generator ab (make lint installiert sie).

Ein Gate bleibt nach der Generierung: das Muttersprachler-Review für Sprachen, die du nicht muttersprachlich sprichst. Kein Validator erkennt eine unnatürliche Formulierung oder eine falsche Umschrift. Maschinell erzeugt, dann menschlich geprüft: das ist die einzig verlässliche Reihenfolge für Sprachinhalte.

Hintergrund + Prompt-Rezepte: der Blogpost "Build Your Own Lessons for Adaptive Learner".