BatchTicket

BatchTicket（CLI: adt）は、Agentワークフローのための決定的な構造化データ変換器です。生産バッチや出荷バッチに付随する小さなチケットのように、各実行はバージョン管理されたプランと、実行によって何が変更されたかの明示的な記録を保持します。その記録は、マッピングが意味的に正しかったことを主張するものではありません。

これは、また別のjqやSQL方言ではありません。DuckDB、JSON Schema、PyYAML、および標準パーサーが確立された実行処理を担っています。このプロジェクトは、それらの周辺のAgent契約を担います。

バージョン0.2.0は未リリースのソースリリース候補です。このプロジェクトはApache License 2.0の下でライセンスされています。安定した技術識別子は、agent-data-transformer、data-transformer、adt、および4つのdata_* MCPツールのままです。

実装されている機能

• JSON、JSONL、CSV、TSV、YAML、Parquetを完全なペイロードを返さずに検査します。

• JSON/YAMLエンベロープ内の境界付きネストレコードセットを発見し、その論理フィールドをプロファイリングします。

• ソースレコードの形状をターゲットJSON Schemaと比較し、構造的なマッピング候補のみを提示し、明示的な互換マッピングの後にのみ実行可能なドラフトプランを出力します。

• 生のコード、SQL、シェル、jq、正規表現、テンプレート実行のない安全なTransformation Plan v1。

• フィルタ、プロジェクト、ドロップ、リネーム、ソート、リミット、重複排除、キャスト、導出、エクスプロード、ジョイン、グループ、ピボット、アンピボット、フラット化、アンフラット化、ツリー変異。

• JSON Schemaに加えて、非null、一意、行数、フィールド、型のアサーション。

• スキーマ対応のキー付きまたはキーなし差分。

• 実際の宛先プリフライト、ステージングされたアトミック公開、上書き保護を備えたドライラン。

• 累積的なソース/バイト/行/アイテム/深さ/時間/RSS/temp制限を備えた呼び出し全体のワーカー分離。

• サンプル、形状、実行効果、差分、検証失敗、エラーを含む、完全なシリアライズ済みレスポンスに対するバイト上限。

• 1つの厳密な型付きPlan v1モデルが、ランタイム検証、公開されたJSON Schema、ライブMCPスキーマを生成します。

• CLIと4つのタスクレベルMCPツールを備えた1つの共有コア。

Related MCP server: Trace MCP

インストールと実行

開発チェックアウト：

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

リポジトリ、uv、Pythonインストール、または実行時のネットワーク接続を必要としないプラットフォーム固有のプラグインをビルドします：

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

ビルドは、dist/plugin/にプラグインディレクトリ、.tar.gzアーカイブ、SHA-256チェックサムを生成します。生成された完全なディレクトリをインストールまたはコピーします。リポジトリルートの.mcp.jsonは開発用設定であり、生成されたプラグインの.mcp.jsonはバンドルされた実行可能ファイルを直接呼び出します。生成されたローカルマーケットプレイスは、Codexをその自己完結型ディレクトリに向けます。--replaceでの再ビルドは、何かを削除または上書きする前に、シンボリックリンクされた出力ルートまたは生成されたターゲットを拒否します。

生成された自己完結型バンドルは現在、ローカル検証アーティファクトであり、公開リリースアセットではありません。これは、Pythonランタイム、Pythonパッケージ、およびサードパーティのライセンス資料がまだアーカイブに組み込まれていないネイティブライブラリを含みます。プラグインディレクトリ、アーカイブ、またはチェックサムをGitHub Releaseにアップロードしないでください。これはApache-2.0ソースリポジトリの公開または使用を制限するものではありません。リリースチェックリストを参照してください。

サンプル変換は2つのレコードをインラインで返し、execution_effectsを通じて1つの入力行が削除されたことを報告します。ファイル出力はoutput.pathを通じてオプトインです。既存ファイルは、output.overwriteが明示的にtrueでない限り置き換えられることはありません。

CLIパスは明示的なユーザーパスであり、絶対パスにすることができます。MCPファイルパスはより狭い機能です。サーバーはまずMCP rootsプロトコルを通じて付与されたワークスペースを使用します。単一のルートが自動的に選択されます。複数のルートが付与されている場合は、ツールのオプションのworkspaceフィールドに正確なルートnameを渡します。rootsサポートのないホストは、互換性付与として明示的なADT_WORKSPACE_ROOTを渡すことができます。ツールパスは選択されたルートに対して相対的なままです。絶対パス、親ディレクトリ、URI、シンボリックリンクによるエスケープは拒否されます。インラインのみのMCP呼び出しはワークスペース付与を必要としません。

Codex CLI 0.148は現在、MCP rootsをローカルプラグインサーバーに渡しません。コールドCLIホストテストの場合は、ADT_WORKSPACE_ROOTを正確なテストワークスペースに設定してCodexを起動します。読み取り専用ツールはapproval=neverで実行できます。data_transformは条件付きファイル出力機能を持つため、特定の呼び出しがデータをインラインで返す場合でも、承認対応ホストポリシーが必要です。ブロックされた呼び出しは認可の結果であり、シェルやモデル側のデータ書き換えにフォールバックする許可ではありません。

決定的スキーマ適応

data_inspectはオプションのtarget_schemaとmappingsオブジェクトを受け入れます。構造的証拠によって一意のネストレコードセットを選択し、完全一致または正規化された名前の一致を提案し、互換性のない、欠落した、重複した、省略された、またはドロップされたフィールドを報告できます。ファジー同義語、キャスト、デフォルトは使用しません。v1アダプターはトップレベルのレコードフィールドをマッピングし、オブジェクトスキーマまたはitemsが1つのオブジェクトスキーマである配列をサポートします。合成/参照スキーマと曖昧なレコードセットは、明示的に未解決のままです。

すべての必須フィールドに明示的な互換マッピングがある場合、adaptation.statusはreadyになり、adaptation.draft_planは通常のTransformation Plan v1になります。そのプランをdata_transformで実行します。アダプターは別の実行パスや5番目の公開ツールを作成しません。

ライブラリ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}]},
            }
        ],
    }
)

公開呼び出しは、安定したerror.codeとともにstatus: ok、status: dry_run、またはstatus: errorを返します。成功した変換は、execution_effectsの下でランタイムで観測された変更を公開します。スタックトレースやDuckDB内部を漏洩することはありません。

プロダクトモデル、Transformation Plan v1、レビュー契約を参照してください。貢献はCONTRIBUTING.md、セキュリティ報告はSECURITY.md、注目すべき変更はCHANGELOG.mdに記載されています。