Evaluation LLM-basierter Transformationen strukturierter Daten

Dieses Repository enthält die Forschungssoftware, Datengrundlage, Versuchssteuerung und Auswertung einer Masterarbeit zur automatischen Transformation strukturierter Daten mit Large Language Models (LLMs).

Im Mittelpunkt steht die Frage, wie zuverlässig ein LLM JSON-Daten in eine vorgegebene Zielstruktur überführen kann und ob es vorteilhafter ist, das Ziel-JSON direkt oder eine wiederverwendbare Transformationsfunktion erzeugen zu lassen. Ein ergänzender Evaluationsstrang untersucht den Import von STAR-Dateien nach JSON.

Projektziel

Das Projekt vergleicht drei grundlegende Verfahren für JSON→JSON- Transformationen:

Verfahren	Eingabe für das LLM	Ausgabe des LLM	Wiederverwendung
Zero-shot	Source-JSON, Transformationsvertrag und Target-Schema	fertiges Target-JSON	neuer Request pro Eingabe
Mapping-Funktion	Source-JSON, Transformationsvertrag und Target-Schema	JavaScript-Funktion	im Hauptversuch neu pro Eingabe erzeugt
Schema→Schema	inferiertes Source-Schema, Transformationsvertrag und Target-Schema	JavaScript- oder JSONata-Funktion	eine Funktion kann auf mehreren verborgenen Source-JSONs ausgeführt werden

Bewertet werden nicht nur vollständig richtige Ergebnisse, sondern auch Teilqualität, technische Ausführbarkeit, Schema-Konformität, Tokenbedarf und die Wiederverwendbarkeit erzeugter Programme.

Untersuchungsbereiche

1. JSON→JSON-Hauptbenchmark

Der Hauptbenchmark basiert auf 38 deterministischen Transformationsrezepten aus 12 Datenprofilen von 11 öffentlichen APIs, unter anderem ClinicalTrials.gov, Crossref, The Met, NVD, OpenAlex, OpenFDA, Open Library, Open-Meteo, SEC und USGS.

Die kanonische Studie vergleicht Zero-shot, Mapping-Funktion und Schema→Schema auf kontrollierten, gepaarten Fällen. Zusätzliche Studien untersuchen:

• den Einfluss der Größe des Source-JSONs;
• Source-Schema-Anreicherungen durch Beispiele und erkannte Enum-Werte;
• JavaScript und JSONata als Sprache der generierten Mapping-Funktion;
• die Wiederverwendung einer Funktion über mehrere Source-JSONs.

Die maschinenlesbare Definition der kanonischen Studie ist evaluation/study.yaml. Weitere Studien besitzen eigene YAML-Spezifikationen unter evaluation/.

2. STAR→JSON-Importevaluation

Der zweite Evaluationsstrang untersucht, wie zuverlässig reale, zuvor kontrolliert in STAR serialisierte Datensätze wieder in ein vorgegebenes JSON-Zielschema überführt werden. Sechs Datenquellen werden jeweils durch einen eigenen STAR-Dialekt repräsentiert.

Verglichen werden vier Importverfahren:

• direkter STAR→JSON-Import durch das LLM;
• Erzeugung einer Mapping-Funktion aus dem STAR-Rohtext;
• eine Hybridvariante mit vollständiger Ausgabe des MetaConfigurator-Parsers;
• eine Hybridvariante mit einem aus der Parserausgabe inferierten Schema.

Details zu Dialekten, Parserintegration, Fallaufbau und Ergebnissen stehen in der STAR Import Evaluation.

Ablauf eines Experiments

flowchart LR
    A[Eingefrorene API-Daten] --> B[Adapter und deterministisches Sampling]
    B --> C[Source-Input]
    B --> D[Gold-Transformation]
    D --> E[Gold-JSON und Target-Schema]
    C --> F[Evaluations-Suite und Prompt]
    E --> F
    F --> G[LLM-Ausgabe]
    G --> H[Parsing bzw. lokale Programmausführung]
    H --> I[Metriken und technische Outcomes]
    I --> J[Audit, Tabellen, Plots und Berichte]

Loading

Die fachliche Referenz wird ausschließlich durch deterministische, handgeschriebene Transformationen erzeugt. Modellantworten beeinflussen weder Gold-Output noch Sampling oder Target-Schema.

Repository-Aufbau

Pfad	Verantwortung
tasks/	Datenquellen, Adapter, deterministisches Sampling, 38 Gold-Transformationen, Target-Schemas und fachliche Tests
tasks/config/	Definition der Source-Profile, Benchmarkfälle und Transformations-Testpfade
tasks/data/	eingefrorene API-Snapshots sowie daraus erzeugte Source- und Task-Bundles
evaluation/	Studienspezifikationen, Promptaufbau, Schema-Inferenz, LLM-Client, Programmausführung, Preflight, Runner und Audits
evaluation/core/	wiederverwendbare Kernlogik der Evaluation, beispielsweise Metriken, Quality Gates und Ausführungslogik
import_evaluation/	Erzeugung und Evaluation der STAR→JSON-Fälle einschließlich MetaConfigurator-Anbindung
analysis/	Aggregation, statistische Vergleiche, Failure-Analysen sowie Erzeugung von Tabellen und Grafiken
results/	vorbereitete Suites, Rohantworten, Run-Manifeste, Auditnachweise, Tabellen, Plots und Ergebnisberichte
docs/	Forschungsfragen, Methodik, Datenherkunft, Protokolländerungen und Runbook
pyproject.toml	Python-Paket, Abhängigkeiten und Kommandozeilen-Einstiegspunkte
package.json	lokale Node.js-Laufzeit für JSONata

Wichtige Komponenten

• tasks/json2json_bench/sources/ enthält quellenspezifische Adapter. Sie lesen und sampeln die jeweilige API-Struktur, ohne sie vorab auf ein gemeinsames Format zu reduzieren.
• tasks/json2json_bench/transformations/ enthält die deterministischen Referenztransformationen.
• evaluation/core/prompting.py baut die Prompts für die verschiedenen Versuchsarme.
• evaluation/core/executors.py führt generierten JavaScript- beziehungsweise JSONata-Code kontrolliert aus.
• evaluation/core/metrics.py berechnet die fachlichen und strukturellen Qualitätsmetriken.
• analysis/analyze.py erzeugt die kanonische Auswertung des Hauptbenchmarks.

Daten- und Ergebnisstruktur

Ein Evaluationsfall verbindet immer folgende Bestandteile:

1. einen eingefrorenen Source-Snapshot;
2. eine durch Größe und Seed festgelegte Stichprobe;
3. einen Transformationsvertrag;
4. ein unabhängig definiertes Target-Schema;
5. ein deterministisch berechnetes Gold-JSON;
6. den für einen Versuchsarm erzeugten Prompt;
7. die rohe Modellantwort und gegebenenfalls das extrahierte Programm;
8. technische Outcomes, Qualitätsmetriken und Provenienznachweise.

Die Ergebnisverzeichnisse sind absichtlich ausführlich. Neben aggregierten Berichten enthalten sie Rohdaten und Manifeste, damit ein Wert aus einer Tabelle bis zu Source-Input, Prompt, Modellantwort und Gold-Output zurückverfolgt werden kann. Historische oder abgebrochene Läufe werden nicht stillschweigend mit kanonischen Ergebnissen vermischt.

Zentrale Metriken

Metrik	Bedeutung
Leaf-Precision	Anteil der erzeugten JSON-Blattwerte, die korrekt sind
Leaf-Recall	Anteil der erwarteten JSON-Blattwerte, die korrekt erzeugt wurden
Leaf-F1	harmonisches Mittel aus Leaf-Precision und Leaf-Recall; primäre Inhaltsmetrik
Path-F1	Übereinstimmung der erzeugten und erwarteten JSON-Pfade
Exact Match	erzeugtes und erwartetes JSON stimmen vollständig überein
Schema-valid	der Output erfüllt das vollständige Target-JSON-Schema
Technischer Erfolg	Antwort konnte verarbeitet und gegebenenfalls kompiliert und ausgeführt werden

Technischer Erfolg und Schema-Validität sind notwendige Qualitätsindikatoren, aber kein Ersatz für die Prüfung der inhaltlichen Korrektheit.

Installation

Vorausgesetzt werden Python 3.12 und Node.js. Der kanonische Lauf wurde mit Python 3.12.3, Node.js 24.13.0 und npm 11.6.2 vorbereitet. Die exakten Python-Versionen stehen in requirements-evaluation.lock; die JavaScript-Abhängigkeit ist in package-lock.json fixiert.

Beispiel für PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements-evaluation.lock
python -m pip install -e . --no-deps
npm ci

Anschließend kann die lokale Umgebung geprüft werden:

python evaluation/verify_environment.py

Für die vollständige Source-Schema-Rekonstruktion und die hybriden STAR-Verfahren wird zusätzlich ein separater MetaConfigurator-Checkout benötigt. Dessen Pfad wird den entsprechenden Befehlen über --metaconfigurator-root übergeben; Commit und relevante Dateihashes werden in den Run-Artefakten protokolliert.

Lokale Prüfung

Alle automatisierten Tests laufen ohne einen kostenpflichtigen Modellrequest:

python -m pytest

Das eingefrorene Task-Bundle kann separat validiert werden:

python -m json2json_bench.cli validate-bundle `
  --bundle-dir tasks/data/n4/source_bundle

Weitere verfügbare Befehle:

python -m json2json_bench.cli --help
python -m evaluation.run --help
python -m analysis.analyze --help
python -m import_evaluation --help

Reproduzierbarkeit und Live-Ausführung

Die Evaluation trennt providerfreie Vorbereitung und kostenpflichtige LLM-Ausführung. Zu den Schutzmechanismen gehören:

• eingefrorene Quelldaten mit Größen- und Hashprüfungen;
• feste Seeds und deterministisches Sampling;
• unabhängig implementierte Gold-Transformationen und Target-Schemas;
• vorab definierte Studienpopulationen und Quality Gates;
• Token-, Kontext-, Request- und Kostenprüfungen vor Live-Läufen;
• gespeicherte Prompts, Rohantworten, Provider-Metadaten und Versuchshistorien;
• getrennte Berichterstattung technischer Coverage und fachlicher Qualität.

Ein Live-Lauf benötigt OPENAI_API_KEY, verursacht externe Requests und darf nur nach bestandenem Preflight und explizitem GO gestartet werden. Die verbindliche Befehlsfolge, Abbruchregeln und Retry-Regeln stehen im Runbook.

Empfohlener Lesepfad

Für einen schnellen fachlichen Überblick:

1. diese README für Ziel, Ablauf und Projektstruktur;
2. docs/RESEARCH_QUESTIONS.md für Forschungsfragen, Populationen und Interpretationsregeln;
3. tasks/README.md für Datenquellen, Sampling und Goldstandard;
4. evaluation/README.md für das Versuchsdesign des JSON→JSON-Hauptbenchmarks;
5. import_evaluation/README.md für die STAR→JSON-Importevaluation;
6. analysis/README.md für Metriken und Auswertung;
7. results/README.md für Ergebnisstatus und Artefaktstruktur.

Weitere Nachweisdokumente:

• docs/DATA_LINEAGE.md – Datenherkunft vom Source-Snapshot bis zum Ergebnisbericht;
• docs/PROTOCOL_CHANGELOG.md – dokumentierte Änderungen des Versuchsprotokolls;

Ausgewählte Ergebnisberichte

• Kanonische JSON→JSON-Auswertung
• Erweiterte Auswertung für n = 2, 4, 8, 16
• Source-Schema-Anreicherung bei n = 30
• JavaScript-/JSONata-Fehleranalyse
• STAR→JSON-Ergebnisse und Visualisierungen

Die Berichte sind jeweils nur innerhalb ihrer dokumentierten Population, Modellversion und Promptkonfiguration zu interpretieren. Der Benchmark belegt keine allgemeine Überlegenheit eines Verfahrens für sämtliche denkbaren JSON-Transformationen.

Lizenz und Zitierung

Der Quellcode steht unter der MIT-Lizenz. Angaben zur Zitierung befinden sich in CITATION.cff.