LLM-gestützte Entwicklung eines Diagramm-Generators: Erkenntnisse zur Code-Validierung#

1. Einführung und Projektkontext#

1.1 Motivation und Lernziele#

Der KI-Diagramm-Generator entstand als exploratives Lernprojekt mit dem primären Ziel, Multi-Agenten-Architekturen in der LLM-gestützten Softwareentwicklung zu erproben. Die zentrale Forschungsfrage lautete: Wie lässt sich die Zuverlässigkeit LLM-generierter Syntax von initial etwa 70% auf nahezu 100% steigern?

Die Motivation speiste sich aus zwei Quellen: Zum einen aus dem Interesse an den Möglichkeiten und Grenzen von LLM-gestütztem Coding bei komplexen, syntax-sensitiven Aufgaben. Zum anderen ein praktischer Bedarf an verlässlich generierten Diagrammen in verschiedenen Formaten. Das Tool war von Anfang an als Lernvehikel konzipiert, wobei die Möglichkeit einer späteren produktiven Nutzung offengehalten wurde.

Das Projekt baute auf Erkenntnissen aus einem Vorprojekt (“ppt-helper”) auf, bei dem sich gezeigt hatte, dass modulare Multi-Komponenten-Architekturen gut mit LLMs entwickelt werden können. Der KI-Diagramm-Generator sollte diesen Ansatz erweitern und um spezifische Validierungs- und Qualitätssicherungsmechanismen ergänzen.

1.2 Was das Tool macht#

Der KI-Diagramm-Generator ist eine Gradio-basierte Webanwendung, die aus natürlichsprachlichen Beschreibungen oder strukturierten Daten automatisch Diagramme in verschiedenen Formaten generiert. Nutzer können über ein Chat-Interface ihre Anforderungen beschreiben, strukturierte Daten (CSV, JSON, eingerückte Listen) eingeben oder aus über 40 vorgefertigten Templates wählen.

Das Tool unterstützt 12 Diagrammtypen:

Flowcharts (Prozessablaufdiagramme)
Mindmaps (hierarchische Ideenstrukturen)
Organigramme (Organisationsstrukturen)
Gantt-Charts (Zeitpläne)
Sequenzdiagramme (System-Interaktionen)
State-Diagramme (Zustandsübergänge)
ER-Diagramme (Datenbankstrukturen)
Netzwerk-Graphen
Pie-Charts
User-Journey-Diagramme
Swimlane-Diagramme (prozesse mit Verantwortlichkeiten)
Kanban-Boards

Der generierte Code wird in Echtzeit validiert und kann im integrierten Code-Editor mit Undo-Funktion manuell nachbearbeitet werden. Diagramme lassen sich als SVG, PNG oder Quellcode exportieren.

2. Technische Architektur#

2.1 Multi-Agenten-System#

Die Architektur basiert auf drei spezialisierten Agenten mit klar definierten Verantwortlichkeiten:

ChatAgent (Intent-Analyse und Koordination):

Analysiert natürlichsprachliche Nutzeranfragen
Identifiziert, ob neue Diagramme erstellt oder bestehende modifiziert werden sollen
Koordiniert die Interaktion zwischen Nutzer und Generierungs-Pipeline
Gibt keine Code-Ausgaben direkt an den Nutzer, sondern nur Erklärungen

DiagramAgent (Code-Generierung):

Generiert Mermaid-Code basierend auf strukturierten Daten oder Chat-Kontext
Unterstützt zwei Generierungsmodi: Direct Generation und JSON-Intermediate
Implementiert diagrammtyp-spezifische Generatoren mit strukturierten Fallbacks
Nutzt vollständige Syntax-Referenzen für Template-basierte Generierung

ValidationAgent (Qualitätssicherung):

Führt Pre-Validierung und automatische Syntax-Korrekturen durch
Testet Code durch tatsächliches Rendering mit Mermaid CLI
Korrigiert fehlerhafte Syntax durch iterative LLM-gestützte Reparatur (max. 3 Versuche)
Fällt auf vordefinierte Templates zurück bei nicht-reparierbarem Code

Diese Struktur ergab sich organisch während der Entwicklung und wurde nicht von Anfang an vollständig geplant. Die klare Modularisierung erwies sich als förderlich für die LLM-Zusammenarbeit, da jeder Agent eine überschaubare, klar definierte Aufgabe hat.

2.2 UI-Architektur und Komponenten#

Die Gradio-basierte Benutzeroberfläche gliedert sich in vier Hauptbereiche:

Chat-Interface: Natürlichsprachliche Interaktion für Diagramm-Anforderungen
Daten-Panel: Eingabe strukturierter Daten mit Smart-Convert-Funktion, Template-Auswahl und Datei-Upload
Code-Editor: Split-View mit Eingabedaten links und editierbarem, generiertem Code rechts; Undo-Stack für iterative Anpassungen; manueller Render-Button statt Auto-Rendering
Diagramm-Galerie: Anzeige generierter Varianten mit Auswahlmöglichkeit und Export-Funktionen

Die Entscheidung für Gradio war pragmatisch begründet – es ermöglicht schnelle Prototypen-Entwicklung. Die Modularisierung in separate UI-Bereiche war von Anfang an im Konzept, da sie notwendig erschien, um verschiedene Interaktionsmodi (Chat vs. strukturierte Eingabe vs. manuelle Code-Bearbeitung) sauber zu trennen.

2.3 Validierungs-Pipeline#

Die Validierungs-Pipeline ist das technische Herzstück des Projekts und durchläuft mehrere Stufen:

Stufe 1 - Pre-Validation:

Erkennung und Entfernung mehrfacher Diagramm-Deklarationen
Diagrammtyp-spezifische Syntax-Korrekturen
Sanitization von Node-IDs und Labels (Sonderzeichen, ungültige Keywords)
Mindmap-spezifische Einrückungs-Normalisierung (2 Spaces pro Ebene)

Stufe 2 - Rendering-Test:

Tatsächliches Rendering mit Mermaid CLI
Erfolg → Code ist valide
Fehler → Weiter zu Stufe 3

Stufe 3 - LLM-gestützte Korrektur:

Prompt enthält: Fehlerhaften Code + Fehlermeldung + vollständige Mermaid-Syntax-Referenz
Bei wiederholten Fehlschlägen: Anpassung der Temperature (0.0 → 0.05 → 0.1 → 0.15)
Extraktion und erneuter Test des korrigierten Codes
Maximum 3 Korrektur-Versuche

Stufe 4 - Template-Fallback:

Bei Fehlschlag aller Korrektur-Versuche: Rückgriff auf vordefinierte, validierte Templates
Template wird ebenfalls noch einmal validiert (sollte immer funktionieren)
Letzter Fallback: Simpelstes Flowchart-Beispiel

Diese Pipeline erhöhte die Erfolgsrate von initial etwa 70% auf 95% nach der finalen Iteration.

2.4 JSON-Intermediate-Layer#

Für strukturierte Diagrammtypen (Flowchart, Mindmap, Org-Chart) wurde ein zweistufiger Generierungsprozess implementiert:

Stage 1 - LLM → JSON:

LLM generiert strukturierte JSON-Repräsentation des Diagramms
Definierte Schemas mit klaren Constraints (z.B. Node-ID-Konventionen)
Validierung der JSON-Struktur vor Konvertierung
Retry-Loop bei ungültigem JSON (max. 2 Versuche)

Stage 2 - JSON → Mermaid (deterministisch):

JSONToMermaidConverter übersetzt strukturiertes JSON in syntaktisch korrekten Mermaid-Code
Deterministisch, keine LLM-Variabilität
Garantiert valide Syntax bei validem Input-JSON

Dieser Ansatz war ein Versuch, die Code-Qualität zu verbessern. Die Trennung zwischen “Was soll dargestellt werden” (JSON) und “Wie wird es syntaktisch korrekt codiert” (Converter) reduziert die Fehlerquellen.

3. Entwicklungsprozess#

3.1 Fünf-Phasen-Entwicklung#

Die Entwicklung erfolgte in fünf klar strukturierten Phasen über einen Zeitraum von zwei Wochen:

Phase 1 - Spezifikation (90 Minuten):

Intensive Architekturdiskussion mit dem LLM
Evaluation möglicher Patterns und Architekturen
Bewusste Auswahl entlang KISS-Prinzipien
Ergebnis: Detaillierte technische Spezifikation mit Multi-Agenten-Ansatz

Phase 2 - Basis-Implementierung (30 Minuten):

Umsetzung der Kern-Komponenten
Grundlegende UI mit Chat und Daten-Panel
Erste Diagramm-Generierung ohne Validierung
Ergebnis: Funktionsfähiger Prototyp mit ~70% Erfolgsrate

Phase 3 - ValidationAgent-Integration (30-45 Minuten):

Hinzufügen automatischer Code-Validierung durch Rendering-Tests
Erste LLM-gestützte Korrektur-Versuche
Ergebnis: Verbesserte Erfolgsrate, aber noch instabil

Phase 4 - Pattern-Integration (30-45 Minuten):

Erweiterte Fehlerkorrektur-Patterns
Diagrammtyp-spezifische Validierungs-Regeln
Pre-Validation mit automatischen Fixes
Ergebnis: Stabilere Generierung, weniger Korrektur-Iterationen nötig

Phase 5 - Mermaid-Syntax-Referenz (30-45 Minuten):

Integration vollständiger Syntax-Spezifikation (>500 Zeilen) in System-Prompts
Dokumentation aller Mermaid-Diagrammtypen mit Beispielen
Explizite Fehler-Pattern-Kataloge mit Korrekturen
Ergebnis: 95% Erfolgsrate

Gesamtaufwand: Etwa 6 Stunden, verteilt auf kurze Sessions von 10-15 Minuten zwischendurch.

3.2 Arbeitsweise mit dem LLM#

Die Entwicklung erfolgte mit lokal verfügbaren LLMs in einem strukturierten Prozess:

Vorab-Diskussion: Intensive Exploration möglicher Architekturen und Patterns mit dem LLM vor jeder Implementierungsphase
Präzise Spezifikation: Ergebnis der Diskussion wurde in klare technische Anforderungen übersetzt
Implementierung in einer Runde: Jede Phase wurde in einem Durchgang umgesetzt, nicht iterativ innerhalb der Phase
Evaluation und Planung: Nach jeder Phase Evaluation der Ergebnisse und Planung der nächsten Verbesserung

Die Erkenntnis aus dem Vorprojekt – dass klare Patterns und Architekturen vor der Implementierung diskutiert werden sollten – bewährte sich. Das LLM diente sowohl als Implementierungs-Partner als auch als Architektur-Diskussionspartner.

3.3 KISS-Prinzip in der Praxis#

Over-Engineering wurde durch mehrere Mechanismen verhindert:

Explizite KISS-Vorgaben in Architektur-Diskussionen
Pragmatische Tool-Wahl: Gradio statt Custom-Framework, Mermaid statt Custom-Rendering
Fokus auf Kern-Funktionalität: Keine unnötigen Features wie User-Management, Datenbank-Persistierung (außer Session-Storage)
Schrittweise Komplexitäts-Steigerung: Erst Basis, dann Validierung, dann Patterns, dann Syntax-Referenz

Die Modularität entstand organisch, wurde aber nicht overengineered. Die 27 Python-Dateien haben klare Verantwortlichkeiten ohne überflüssige Abstraktionsebenen.

4. Methodische Erkenntnisse#

4.1 Bewährte Ansätze#

Multi-Agenten-Architekturen scheinen förderlich: Die Aufteilung in spezialisierte Agenten (Chat, Generierung, Validierung) erwies sich als strukturierender Rahmen für die LLM-Zusammenarbeit. Jeder Agent hat eine überschaubare, klar definierte Aufgabe, was sowohl die Spezifikation als auch die Implementierung vereinfacht. Allerdings sollte dies nicht als generelle Regel verstanden werden – die Stichprobe ist zu klein.

Syntax-Referenzen im Prompt sind wirkungsvoll: Die Integration der vollständigen Mermaid-Syntax-Referenz (>500 Zeilen) in den ValidationAgent-System-Prompt führte zum größten Qualitätssprung. Das LLM konnte damit präzise “nachschlagen”, was korrekte Syntax ist, statt aus dem “Gedächtnis” zu generieren. Dies scheint besonders bei domain-spezifischen Syntax-Anforderungen relevant zu sein.

Validierungs-Loops mit LLM-Korrektur können wirksam sein: Die iterative Korrektur fehlerhaften Codes durch das LLM selbst (mit Fehlermeldung + Syntax-Referenz als Input) funktionierte überraschend gut. Von 100 fehlerhaften Diagrammen konnten etwa 80-85 durch den Korrektur-Loop repariert werden. Dies ist eine signifikante Verbesserung, löst das Problem aber nicht vollständig.

Strukturierte Vorab-Diskussion reduziert Iterationen: Die intensive Architektur-Diskussion in Phase 1 (90 Minuten) zahlte sich aus. Die nachfolgenden Implementierungsphasen verliefen jeweils in einer einzigen großen Iteration ohne viele Nachbesserungen. Dies deutet darauf hin, dass LLMs gut darin sein können, verschiedene Architektur-Optionen zu diskutieren, bevor Code generiert wird.

JSON als Intermediate-Format kann helfen: Die Trennung zwischen “Was darstellen” (JSON) und “Wie syntaktisch codieren” (deterministischer Converter) reduzierte Fehlerquellen bei strukturierten Diagrammen. Allerdings war der Aufwand höher und der Qualitätsgewinn moderat – nicht für alle Diagrammtypen lohnenswert.

4.2 Verbleibende Herausforderungen#

Nachträgliche Code-Korrektur bleibt schwierig: Dies ist die zentrale Erkenntnis des Projekts. Auch mit vollständiger Syntax-Referenz und mehreren Korrektur-Versuchen gelingt die Reparatur nicht-validen Codes nur in etwa 80-85% der Fälle. Bei etwa 15-20% der Fehler führt auch iterative LLM-Korrektur nicht zum Erfolg. Die Gründe sind vielfältig:

LLM wiederholt gleiche Fehler trotz Fehlermeldung
LLM führt neue Fehler ein beim Versuch, alte zu korrigieren
Manche Syntax-Konstrukte scheinen schwer zu “debuggen” für LLMs

Intent-Erkennung funktioniert nicht zuverlässig genug: Die Identifikation, welcher Diagrammtyp für eine natürlichsprachliche Anfrage optimal ist, bleibt unzuverlässig. Der ChatAgent trifft die Typ-Auswahl nur in etwa 60-70% der Fälle korrekt beim ersten Versuch. Nutzer müssen oft explizit den gewünschten Typ angeben. Dieses Problem wurde in einem Nachfolgeprojekt (“Chart-Tool”) angegangen.

Grundlegende LLM-Zuverlässigkeit ist limitierend: Trotz aller Validierungs- und Korrektur-Mechanismen bleibt die Basis-Qualität der initialen Code-Generierung abhängig von der Zuverlässigkeit des verwendeten LLMs. Bei schwächeren Modellen sinkt die Erfolgsrate auch mit Validierung deutlich. Die erreichten 95% gelten für die verwendeten lokalen Modelle – andere Modelle zeigen andere Erfolgsraten.

Mermaid deckt nicht alle Anforderungen: Während das Tool für Mermaid-kompatible Diagramme gut funktioniert, gibt es viele Visualisierungs-Anforderungen, die Mermaid nicht abdeckt (komplexe wissenschaftliche Plots, hochgradig angepasste Grafiken, interaktive Visualisierungen). Das Tool ist daher nur für eine Teilmenge von Diagramm-Anforderungen geeignet.

4.3 Workflow-Veränderungen#

Durch das Projekt haben sich folgende Arbeitspraktiken etabliert:

Pattern- und Syntax-Integration als Standard: Bei zukünftigen Projekten mit domain-spezifischer Syntax wird die Integration vollständiger Referenzen von Anfang an eingeplant, nicht erst nachträglich. Der Aufwand (1-2 Stunden für Aufbereitung der Referenz) lohnt sich durch deutlich höhere Code-Qualität.

Validierung als integraler Bestandteil: Statt LLM-generierten Code direkt zu verwenden, wird standardmäßig ein Validierungs-Schritt eingeplant. Dies kann Test-Ausführung, Rendering oder andere Forms der Verifikation sein, abhängig vom Projekt-Typ.

5. Validierung und praktische Nutzung#

5.1 Funktionale Erprobung#

Das Tool wird derzeit aktiv getestet mit folgenden Beobachtungen:

Erfolgsraten nach Diagrammtyp:

Flowcharts, Mindmaps, Org-Charts: ~95% valide beim ersten Versuch
Gantt, Sequence, State: ~90% valide
Komplexere Typen (ER, Swimlane, Kanban): ~85% valide
Durchschnitt über alle Typen: ~95%

Manuelle Nacharbeit: Bei den 5% nicht-validen Diagrammen ermöglicht der Code-Editor in den meisten Fällen schnelle manuelle Korrektur (1-2 Minuten). Nur in seltenen Fällen (<1%) ist komplettes Neuerstellen nötig.

Qualität der Visualisierungen: Die generierten Diagramme sind in der Regel semantisch korrekt und optisch ansprechend. Die größte Schwäche liegt in der Intent-Erkennung (falscher Diagrammtyp gewählt), nicht in der Umsetzung eines korrekt identifizierten Typs.

5.2 Produktive Nutzung#

Das Tool wird gelegentlich produktiv eingesetzt, bleibt aber primär ein Experiment. Typische Nutzungsszenarien:

Schnelle Prototypen: Für Präsentationen oder Dokumentationen, wo Geschwindigkeit wichtiger ist als Perfektion
Template-Basis: Als Ausgangspunkt, der dann in spezialisierten Tools weiterbearbeitet wird
Exploration: Zum Ausprobieren verschiedener Visualisierungs-Optionen für einen Datensatz

Nicht geeignet für:

Produktions-Dokumentation mit hohen Qualitätsanforderungen (noch zu hohe Fehlerrate)
Komplexe, hochgradig angepasste Diagramme (Mermaid-Limitierungen)
Batch-Verarbeitung großer Datenmengen (Performance-Gründe)

5.3 Erkenntnisse aus der Nutzung#

Die praktische Erprobung bestätigte die theoretischen Erkenntnisse:

Das “letzte Prozent” ist schwer: Von 95% auf 99%+ Zuverlässigkeit zu kommen, würde vermutlich exponentiell mehr Aufwand erfordern. Für ein Lernprojekt ist 95% ein guter Punkt, für Produktions-Software noch nicht ausreichend.

Human-in-the-Loop ist wertvoll: Die Kombination aus automatischer Generierung und manuellem Editor funktioniert besser als reine Automation. Nutzer können schnell nachbessern, wo die Automation fehlt.

Intent-Erkennung bleibt der Flaschenhals: Selbst perfekte Code-Generierung hilft nicht, wenn der falsche Diagrammtyp gewählt wird. Hier wurde in Nachfolgeprojekten weitergearbeitet.

6. Metriken und Vergleichbarkeit#

Umfang:

13.000 Zeilen Code gesamt
12.400 Zeilen Python
27 Python-Dateien
12 unterstützte Diagrammtypen
40+ Templates in der Library

Entwicklungszeit:

Spezifikation: ~3,5 Stunden (initial 90 Min + 4x 30 Min Verfeinerung)
Implementierung: ~2,5 Stunden (4 Phasen à 30-45 Min)
Gesamtaufwand: ~6 Stunden über 2 Wochen
Arbeitsweise: Kurze Sessions (10-15 Min) zwischendurch

Qualitäts-Entwicklung:

Initial: ~70% valider Code
Nach ValidationAgent: ~80%
Nach Pattern-Integration: ~88%
Nach Syntax-Referenz: ~95%

Performance:

Durchschnittliche Generierungszeit: 2-5 Sekunden (abhängig vom LLM)
Validierung mit Korrektur: 5-15 Sekunden
Template-Fallback: <1 Sekunde

7. Schlussfolgerungen#

Der KI-Diagramm-Generator demonstriert, dass systematische Validierung und Syntax-Integration die Zuverlässigkeit LLM-generierter Syntax erheblich steigern können – von initial etwa 70% auf 95% in diesem Projekt. Die Multi-Agenten-Architektur erwies sich als strukturierender Rahmen für die LLM-Zusammenarbeit, wobei unklar bleibt, ob dies generalisierbar ist.

Die zentrale verbleibende Herausforderung ist die nachträgliche Korrektur fehlerhaften Codes durch LLMs selbst. Auch mit vollständiger Syntax-Referenz und mehreren Iterationen gelingt dies nur in 80-85% der Fälle. Dies deutet auf fundamentale Limitierungen der aktuellen LLM-Generationen bei komplexen Syntax-Debugging-Aufgaben hin.

Für zukünftige Projekte haben sich folgende Praktiken als wertvoll erwiesen:

Integration vollständiger Syntax-Referenzen von Anfang an
Validierung als integraler Bestandteil, nicht nachträgliches Add-on
Schrittweise Qualitäts-Iteration statt Big-Bang-Perfektion
Human-in-the-Loop für die “letzten Prozent”

Wichtige Einschränkung: Alle Erkenntnisse stammen aus einem einzelnen Projekt und sollten nicht als allgemeingültig verstanden werden. Sie repräsentieren Beobachtungen unter spezifischen Bedingungen (bestimmte LLMs, bestimmte Domain, bestimmter Entwickler) und bedürfen weiterer Validierung.

Das Tool selbst hat noch nicht Produktionsreife erreicht, funktioniert aber als Lernvehikel und gelegentliches Hilfsmittel. Die methodischen Erkenntnisse – insbesondere zur Validierungs-Pipeline und Pattern-Integration – flossen bereits in Nachfolgeprojekte ein und werden dort weiterentwickelt.