BatchTicket

BatchTicket (CLI: adt) ist ein deterministischer strukturierter Datentransducer für Agent-Workflows. Wie das kleine Ticket, das mit einer Produktions- oder Versandcharge reist, trägt jeder Lauf einen versionierten Plan und einen expliziten Bericht darüber, was die Ausführung verändert hat. Dieser Bericht behauptet nicht, dass die Zuordnung semantisch korrekt war.

Es ist keine weitere jq- oder SQL-Dialekt. DuckDB, JSON Schema, PyYAML und Standard-Parser besitzen etablierte Ausführungsarbeit. Dieses Projekt besitzt den Agent-Vertrag um sie herum.

Version 0.2.0 ist ein unveröffentlichter Quell-Release-Kandidat. Das Projekt ist unter der Apache License 2.0 lizenziert. Die stabilen technischen Bezeichner bleiben agent-data-transformer, data-transformer, adt und die vier data_* MCP-Tools.

Was implementiert ist

• JSON, JSONL, CSV, TSV, YAML und Parquet inspizieren, ohne vollständige Nutzlasten zurückzugeben.

• Begrenzte verschachtelte Recordsets in JSON/YAML-Envelopes entdecken und ihre logischen Felder profilieren.

• Eine Quell-Record-Form mit einem Ziel-JSON-Schema vergleichen, nur strukturelle Mapping-Kandidaten aufzeigen und einen ausführbaren Entwurfsplan nur nach expliziten kompatiblen Zuordnungen ausgeben.

• Sicherer Transformationsplan v1 ohne rohen Code, SQL, Shell, jq, Regex oder Template-Ausführung.

• Filtern, projizieren, verwerfen, umbenennen, sortieren, limitieren, deduplizieren, casten, ableiten, explodieren, joinen, gruppieren, pivotieren, unpivotieren, flatten, unflatten und Baum-Mutation.

• JSON Schema plus Nicht-Null-, Eindeutigkeits-, Zeilenanzahl-, Feld- und Typ-Assertions.

• Schema-bewusster Schlüssel- oder Schlüsselloser Diff.

• Dry-Run mit echter Ziel-Vorprüfung, gestaffelter atomarer Veröffentlichung und Überschreibschutz.

• Ganze Aufruf-Isolation mit kumulativen Quell-/Byte-/Zeilen-/Element-/Tiefen-/Zeit-/RSS-/Temp-Limits.

• Ein Byte-Limit über die vollständige serialisierte Antwort, einschließlich Stichproben, Formen, Ausführungseffekten, Diffs, Validierungsfehlern und Fehlern.

• Ein streng typisiertes Plan-v1-Modell generiert Laufzeitvalidierung, das veröffentlichte JSON Schema und das Live-MCP-Schema.

• Ein gemeinsamer Kern mit CLI und vier aufgabenbezogenen MCP-Tools.

Related MCP server: Trace MCP

Installieren und ausführen

Entwicklungs-Checkout:

git clone https://github.com/tetracoralla/BatchTicket.git
cd BatchTicket
uv sync --frozen --extra dev
uv run adt inspect examples/users.json --select 'data.users[*]'
uv run adt inspect examples/users.json --select 'data.users[*]' \
  --target-schema target.schema.json --mappings mappings.json
uv run adt transform examples/adults.plan.yaml
uv run adt transform examples/adults.plan.yaml --dry-run
uv run adt validate examples/users.json --select 'data.users[*]' \
  --assertions examples/users.assertions.json
ADT_WORKSPACE_ROOT=/absolute/granted/workspace uv run adt mcp

Ein plattformspezifisches Plugin bauen, das weder das Repository, uv, eine Python-Installation noch eine Netzwerkverbindung zur Laufzeit benötigt:

uv run python scripts/build_plugin.py
uv run python scripts/probe_plugin.py \
  dist/plugin/data-transformer-0.2.0-darwin-arm64
codex plugin marketplace add dist/plugin
codex plugin add data-transformer@data-transformer-local

Der Build erzeugt ein Plugin-Verzeichnis, ein .tar.gz-Archiv und eine SHA-256-Prüfsumme in dist/plugin/. Installieren oder kopieren Sie das vollständige generierte Verzeichnis; die .mcp.json im Repository-Stamm ist eine Entwicklungskonfiguration, während die .mcp.json des generierten Plugins sein gebündeltes ausführbares Programm direkt aufruft. Der generierte lokale Marktplatz verweist Codex auf dieses eigenständige Verzeichnis. Ein erneuter Build mit --replace verweigert symbolische Ausgabewurzeln oder generierte Ziele, bevor etwas gelöscht oder überschrieben wird.

Das generierte eigenständige Bündel ist derzeit ein lokales Validierungsartefakt, kein öffentliches Release-Asset. Es enthält eine Python-Laufzeit, Python-Pakete und native Bibliotheken, deren Lizenzmaterialien Dritter noch nicht im Archiv zusammengestellt sind. Laden Sie das Plugin-Verzeichnis, das Archiv oder die Prüfsumme nicht in ein GitHub-Release hoch. Dies schränkt die Veröffentlichung oder Nutzung des Apache-2.0-Quellrepositorys nicht ein; siehe die Release-Checkliste.

Die Beispieltransformation gibt zwei Records inline zurück und meldet über execution_effects, dass eine Eingabezeile entfernt wurde. Dateiausgabe ist über output.path optional; vorhandene Dateien werden nie ersetzt, außer output.overwrite ist explizit wahr.

CLI-Pfade sind explizite Benutzerpfade und können absolut sein. MCP-Dateipfade sind eine engere Fähigkeit: Der Server verwendet zuerst Arbeitsbereiche, die über das MCP-Roots-Protokoll gewährt werden. Eine einzelne Wurzel wird automatisch ausgewählt; wenn mehrere Wurzeln gewährt werden, übergeben Sie deren exakten Wurzel-name im optionalen workspace-Feld des Tools. Hosts ohne Roots-Unterstützung können eine explizite ADT_WORKSPACE_ROOT als Kompatibilitätsgewährung übergeben. Tool-Pfade bleiben relativ zur ausgewählten Wurzel, und absolute, übergeordnete, URI- und Symlink-Escapes werden abgelehnt. Inline-only-MCP-Aufrufe benötigen keine Arbeitsbereichsgewährung.

Codex CLI 0.148 übergibt derzeit keine MCP-Roots an lokale Plugin-Server. Für einen Kalt-CLI-Hosttest starten Sie Codex mit ADT_WORKSPACE_ROOT, das auf den exakten Testarbeitsbereich gesetzt ist. Schreibgeschützte Tools können unter approval=never ausgeführt werden; data_transform hat bedingte Dateiausgabefähigkeit und erfordert daher eine genehmigungsfähige Host-Richtlinie, selbst wenn ein bestimmter Aufruf Daten inline zurückgibt. Ein blockierter Aufruf ist ein Autorisierungsergebnis, keine Erlaubnis, auf Shell- oder modellseitige Datenumschreibung zurückzugreifen.

Deterministische Schema-Anpassung

data_inspect akzeptiert ein optionales target_schema- und mappings-Objekt. Es kann ein eindeutiges verschachteltes Recordset durch strukturelle Beweise auswählen, exakte oder normalisierte Namensübereinstimmungen vorschlagen und inkompatible, fehlende, duplizierte, ausgelassene oder verworfene Felder melden. Es verwendet keine Fuzzy-Synonyme, Casts oder Standardwerte. Der v1-Adapter mappt Top-Level-Record-Felder und unterstützt ein Objekt-Schema oder ein Array, dessen items ein Objekt-Schema ist. Zusammengesetzte/Referenz-Schemas und mehrdeutige Recordsets bleiben explizit unaufgelöst.

Wenn jedes erforderliche Feld eine explizite kompatible Zuordnung hat, ist adaptation.status ready und adaptation.draft_plan ist ein normaler Transformationsplan v1. Führen Sie diesen Plan über data_transform aus; der Adapter erstellt keinen separaten Ausführungspfad oder ein fünftes öffentliches Tool.

Bibliotheks-API

from data_transformer import DataTransformer

result = DataTransformer().transform(
    {
        "version": "1",
        "sources": {"rows": {"inline": [{"x": 2}, {"x": 4}]}},
        "steps": [
            {
                "op": "derive",
                "field": "doubled",
                "expr": {"multiply": [{"field": "x"}, {"value": 2}]},
            }
        ],
    }
)

Öffentliche Aufrufe geben status: ok, status: dry_run oder status: error mit einem stabilen error.code zurück. Erfolgreiche Transformationen legen zur Laufzeit beobachtete Änderungen unter execution_effects offen; sie leaken keine Stack-Traces oder DuckDB-Interna.

Siehe das Produktmodell, Transformationsplan v1 und den Review-Vertrag. Beiträge sind in CONTRIBUTING.md beschrieben, Sicherheitsmeldungen in SECURITY.md und bemerkenswerte Änderungen in CHANGELOG.md.