Architektur

LernWerkstatt folgt einer schichtweisen Architektur mit klar getrennten Verantwortungen: eine Wizard-Oberfläche, eine Auftragsverwaltung für serverseitig laufende Produktionen, eine Pipeline-Schicht mit DAG-Ausführung, spezialisierte Komponenten für Normalisierung, Validierung, Terminologie und Montage sowie eine dateibasierte Persistenz mit SQLite-Auftragsregister. Sprachmodelle, Embedder und Reranker laufen außerhalb der Anwendung und werden über OpenAI-kompatible HTTP-APIs angesprochen. Die Erzeugung ist als Generator-basierte Pipeline implementiert, die Fortschrittsereignisse an die Oberfläche streamt.

Auf einen Blick

• Schichten-Trennung: UI (Gradio 6) → Auftragslauf → Pipeline → Unit-Komponenten → Persistenz und externe Endpunkte
• Serverseitige Produktion in einem eigenen Task, entkoppelt von der Browsersitzung
• Kapitelweise Ausführung über einen gerichteten Graphen mit schichtweiser Parallelität
• Zwei Modellrollen mit getrennten Endpunkten, Zuordnung je Aufgabe statt global
• Deterministische Normalisierung und Validierung ohne Modellaufruf zwischen Erzeugung und Auslieferung
• Persistenz als JSON-Artefakte je Auftrag plus SQLite-Register
• Konfiguration ausschließlich über .env beziehungsweise Umgebungsvariablen
• Bereitstellung als Docker-Container hinter einem Reverse-Proxy

Schichten und Komponenten

UI-Schicht — Eine Gradio-6-Anwendung mit fünf aufeinander aufbauenden Schritten (Lernprofil, Planung, Freigabe, Produktion, Ergebnis). Der Sitzungszustand führt die Auftragsnummer und Verweise, nicht die Inhalte selbst. Ein Statustakt spiegelt den serverseitigen Lauf in die Oberfläche und ruht, solange keine Produktion aktiv ist.

Auftragsverwaltung — Ein Prozessregister hält laufende Produktionen als asyncio-Tasks mit Protokollpuffer und Statusdatei. Das Browserfenster kann geschlossen werden; über eine Auftragsliste mit Status und erreichter Phase hängt man sich später wieder an. Abbrüche wirken über ein Stop-Signal an der nächsten Kapitelgrenze.

Pipeline-Schicht — Die Phasensteuerung koordiniert acht Phasen: Lernprofil, Gap-Analyse, Konzeptgraph, Materialabdeckung, Feinplan, Skript, Blöcke und Konsolidierung. Je Kapitel werden zwei gerichtete Graphen geplant und schichtweise ausgeführt; die Schichten ergeben sich aus den Abhängigkeiten, innerhalb einer Schicht laufen Aufgaben parallel unter einer Semaphore. Kapitel werden zusätzlich verschränkt: Lauf A von Kapitel k+1 überlappt Lauf B von Kapitel k.

Unit-Komponenten — Spezialisierte Module für die Verarbeitungsschritte zwischen Modellausgabe und Auslieferung: Normalisierung (Formatreparatur), Validator (Schema, Blockverträge, Didaktikprüfungen), Terminologie (Begriffsregister und Kandidatenprüfung), Begriffsmarkierung (Glossar-Tooltips), Degradation (Herabstufung defekter Bausteine) und Assembler (Montage zur Einzeldatei).

Persistenz — Jeder Auftrag besitzt ein Verzeichnis mit Zustandsdatei, Unit-JSON, Checkpoint-Artefakten, Kapitelskripten, Terminologieregister und technischem Bericht. Ein SQLite-Register führt die Auftragsnummern. Die Wiederaufnahme ist feingranular: gesichert werden auch die Ausgaben einzelner Textabschnitte und jede fertige Lektion.

Externe Endpunkte — Zwei OpenAI-kompatible Sprachmodell-Endpunkte für die Modellrollen, optional ein Embedder- und ein Reranker-Endpunkt. Ohne Embedder entfällt die Inventarisierung des Materials, ohne Reranker liefert das Retrieval eine Rangfolge ohne Relevanzentscheidung — beides wird sauber weggelassen statt ersetzt.

Datenfluss

Der Nutzer interagiert ausschließlich mit der UI-Schicht. Schritt 1 liest hochgeladene Dateien, erzeugt über das schnelle Modell ein Lernprofil und legt den Volltext im Auftragsordner ab. Ist ein Embedder konfiguriert, wird das Material segmentiert und eingebettet.

Schritt 2 erzeugt über das starke Modell das Konzeptinventar mit Behandlungsklassen und den Kapitelplan, anschließend den Konzeptgraphen mit Einführungsorten und Voraussetzungen. Bei vorhandenem Index folgt die Abdeckungsanalyse, die jedem Konzept seine Belegstellen zuordnet.

Schritt 3 zeigt beides als editierbare Tabellen. Mit der Freigabe übergibt die Oberfläche an die Auftragsverwaltung, die einen serverseitigen Task startet.

In Schritt 4 durchläuft jedes Kapitel zwei Läufe. Lauf A erzeugt Fließtext: ein Querbezugs-Task sammelt die verbindliche Terminologie, dann schreibt je Konzept ein eigener Task, danach montiert ein Finalize-Task das Kapitelskript. Lauf B überführt den Text in Blöcke, je Lektion ein Task, gefolgt vom Anwendungsteil und der Kapitelzusammenfassung. Anschließend läuft je Lektion ein Anreicherungsdurchgang, der ausschließlich neue Bausteine mit Einfügeposition zurückgibt.

In der Konsolidierung laufen Abschlusstest und Critic parallel, danach Faktenprüfung und Redundanzpass. Schritt 5 führt Normalisierung, Validierung, Degradation und Montage aus und liefert die Einzeldatei.

Normalisierung, Validierung und Terminologiekontrolle greifen querschnittlich nach jeder erzeugenden Phase, ohne im Hauptdatenfluss zu liegen.

KI-Komponenten im Workflow

Drei Klassen von KI-Komponenten wirken zusammen, eingebettet in eine regelbasierte Orchestrierung:

Sprachmodelle in zwei Rollen — Ein starkes Modell übernimmt Planung, Konzeptgraph, Montage, die tragenden Konzepte, den Anwendungsteil und den Critic; ein schnelles Modell die formatnahe und mengenintensive Arbeit, insbesondere die Blockerzeugung. Die Zuordnung ist je Aufgabe im Ausführungsgraphen hinterlegt. Antworten mit JSON-Vertrag werden gegen ein Schema validiert; bei Fehlern folgt eine Reparaturschleife mit Befundrückmeldung.

Embedder und Reranker — Das Material wird modellgestützt in typisierte Einheiten segmentiert und eingebettet. Für die Zuordnung von Konzepten zu Belegstellen filtert eine Cosine-Vorauswahl breit vor, die Relevanzentscheidung trifft der Reranker gegen eine Schwelle. Sein Wert ist über Anfragen hinweg vergleichbar, weil Anfrage und Dokument gemeinsam bewertet werden; ein Ausfall meldet ausdrücklich „keine Aussage" statt einer Ersatzreihenfolge.

Deterministische Prüfschicht — Sie ist bewusst keine KI-Komponente. Schema, Blockverträge, Quizlogik, Datenkonsistenz, Interaktionsdichte und Formatdisziplin werden ohne Modellaufruf entschieden. Node-basierte Proben prüfen Simulator-Code, Mermaid-Syntax und LaTeX-Konvertierung gegen dieselben Bibliotheksversionen, die später in der Einheit stecken.

Nebenläufigkeit und Robustheit

Die Produktion läuft in einem serverseitigen Task, unabhängig von der Browsersitzung. Innerhalb eines Kapitels begrenzt eine Semaphore die parallel laufenden Aufgaben; Kapitel werden verschränkt ausgeführt.

Ausfälle werden abgestuft statt verabsolutiert: Abgeschnittene JSON-Antworten werden geschlossen und das unvollständige letzte Element verworfen. Ein misslungener Feinplan führt nach drei Versuchen zu einem Ersatzplan aus dem Konzeptinventar. Eine Lektion, die auch nach Wiederholung nicht lesbar ist, wird als Verlust im Final-Gate ausgewiesen statt stillschweigend zu fehlen. Ein nicht darstellbarer Baustein wird durch seine Beschreibung als Text ersetzt.

Eine Besonderheit betrifft die Modellansteuerung: Erzwingt response_format gültiges JSON, greift geführte Dekodierung. Ein Thinking-Modell kann seine Denk-Tokens dann nicht ausgeben und liefert bei ausgeschöpftem Budget nichts zurück. Der Client schaltet Thinking bei JSON-Modus deshalb standardmäßig ab und wiederholt eine leere Antwort genau einmal ohne Thinking.

Konfiguration und Deployment

Sämtliche Endpunkte, Modellnamen, Budgets, Parallelitäten und Grenzwerte werden über eine .env-Datei beziehungsweise Umgebungsvariablen gesetzt; es gibt keine Kommandozeilen-Argumente. Konfigurierbar sind unter anderem Basis-URL, Modell, Modellfamilie, Thinking-Verhalten, Token-Budget, Temperatur, Timeout und Parallelität je Modellrolle, die Budgets der Blockphase sowie Embedder- und Reranker-Endpunkte.

Die Anwendung startet als Docker-Container auf Basis von Python 3.12-Slim, der zusätzlich Node.js für die Prüfläufe enthält. Zur Bauzeit werden die Renderer-Bibliotheken in das Image geladen; schlägt das fehl, läuft die Anwendung weiter und meldet den Ausfall als Warnung. Ein Volume für das Arbeitsverzeichnis ist zwingend — es enthält das Auftragsregister und alle Auftragsordner, von denen die Wiederaufnahme abhängt. Vorgelagert ist ein nginx-Reverse-Proxy mit Pfadpräfix und großzügigen Timeouts, da einzelne Modellaufrufe lange laufen können.

Technologie-Übersicht

• UI: Gradio 6
• Laufzeit: Python 3.12, asyncio
• LLM-Zugriff: openai (async), OpenAI-kompatible Endpunkte
• HTTP-Client: httpx für Embedder und Reranker
• Schemaprüfung: jsonschema
• Dokumentenimport: pdfminer.six, python-docx, stdlib zipfile
• Dokumentenexport: python-docx
• Persistenz: SQLite, JSON-Dateien im Auftragsordner
• Prüfläufe: Node.js mit katex, mermaid, jsdom, dompurify (nur zur Bauzeit)
• Eingebettete Renderer: Chart.js 4, Mermaid 11, Vega/Vega-Lite/Vega-Embed
• Ausgabeformat: Single-File-HTML mit MathML und SVG
• Bereitstellung: Docker hinter nginx