BatchTicket

BatchTicket (CLI: adt) — детерминированный структурированный преобразователь данных для агентских рабочих процессов. Как маленький талон, который сопровождает производственную или отгрузочную партию, каждый запуск несет версионированный план и явный отчет о том, что изменило исполнение. Этот отчет не утверждает, что сопоставление было семантически корректным.

Это не очередной диалект jq или SQL. DuckDB, JSON Schema, PyYAML и стандартные парсеры владеют устоявшейся работой по исполнению. Этот проект владеет контрактом для агентов вокруг них.

Версия 0.2.0 — невыпущенный кандидат на исходный релиз. Проект лицензирован в соответствии с Apache License 2.0. Стабильными техническими идентификаторами остаются agent-data-transformer, data-transformer, adt и четыре MCP-инструмента data_*.

Что реализовано

• Просмотр JSON, JSONL, CSV, TSV, YAML и Parquet без возврата полных полезных нагрузок.

• Обнаружение ограниченных вложенных наборов записей в JSON/YAML-конвертах и профилирование их логических полей.

• Сравнение формы исходной записи с целевой JSON Schema, выявление только структурных кандидатов на сопоставление и создание исполняемого чернового плана только после явных совместимых сопоставлений.

• Безопасный план трансформации v1 без необработанного кода, SQL, shell, jq, regex или выполнения шаблонов.

• Фильтрация, проекция, удаление, переименование, сортировка, ограничение, дедупликация, приведение типов, наследование, разворачивание, соединение, группировка, сводные таблицы, обратные сводные таблицы, уплощение, разуплощение и мутация дерева.

• JSON Schema плюс проверки на непустоту, уникальность, количество строк, поля и типы.

• Схемно-зависимый дифф с ключом или без ключа.

• Пробный прогон с реальной предварительной проверкой назначения, поэтапной атомарной публикацией и защитой от перезаписи.

• Изоляция воркера на весь вызов с совокупными лимитами источника/байт/строк/элементов/глубины/времени/RSS/временных файлов.

• Потолок байтов для полного сериализованного ответа, включая образцы, формы, эффекты выполнения, различия, ошибки проверки и ошибки.

• Одна строгая типизированная модель плана v1 генерирует проверку во время выполнения, опубликованную JSON Schema и живую MCP-схему.

• Одно общее ядро с CLI и четырьмя MCP-инструментами уровня задач.

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

Сборка создает каталог плагина, архив .tar.gz и контрольную сумму SHA-256 в dist/plugin/. Установите или скопируйте полный сгенерированный каталог; .mcp.json в корне репозитория является конфигурацией для разработки, тогда как .mcp.json сгенерированного плагина вызывает свой встроенный исполняемый файл напрямую. Сгенерированный локальный маркетплейс указывает Codex на этот автономный каталог. Пересборка с --replace отказывается от символических ссылок в корневых каталогах вывода или сгенерированных целях перед удалением или перезаписью чего-либо.

Сгенерированный автономный пакет в настоящее время является локальным артефактом проверки, а не публичным релизным ресурсом. Он включает среду выполнения Python, пакеты Python и нативные библиотеки, чьи материалы сторонних лицензий еще не собраны в архив. Не загружайте каталог плагина, архив или контрольную сумму в GitHub Release. Это не ограничивает публикацию или использование репозитория исходного кода Apache-2.0; см. контрольный список релиза.

Пример трансформации возвращает две записи инлайн и сообщает через execution_effects, что одна входная строка была удалена. Вывод в файл осуществляется через output.path; существующие файлы никогда не заменяются, если output.overwrite явно не установлен в true.

Пути CLI являются явными пользовательскими путями и могут быть абсолютными. Пути к файлам MCP — это более узкая возможность: сервер сначала использует рабочие области, предоставленные через протокол корней MCP. Один корень выбирается автоматически; когда предоставлено несколько корней, передайте точное имя корня в необязательном поле workspace инструмента. Хосты без поддержки корней могут передать явный ADT_WORKSPACE_ROOT в качестве совместимого разрешения. Пути инструментов остаются относительными к выбранному корню, а абсолютные, родительские, URI и символические ссылки отклоняются. Только встроенные вызовы MCP не требуют разрешения рабочей области.

Codex CLI 0.148 в настоящее время не передает корни MCP локальным серверам плагинов. Для холодного теста хоста CLI запустите Codex с ADT_WORKSPACE_ROOT, установленным в точную тестовую рабочую область. Инструменты только для чтения могут работать с approval=never; data_transform имеет условную возможность вывода в файл и поэтому требует политику хоста с поддержкой одобрения, даже если конкретный вызов возвращает данные инлайн. Заблокированный вызов — это результат авторизации, а не разрешение на возврат к оболочке или перезаписи данных на стороне модели.

Детерминированная адаптация схемы

data_inspect принимает необязательные target_schema и объект mappings. Он может выбрать уникальный вложенный набор записей по структурным признакам, предложить точные или нормализованные совпадения имен и сообщить о несовместимых, отсутствующих, дублированных, пропущенных или удаленных полях. Он не использует нечеткие синонимы, приведения или значения по умолчанию. Адаптер v1 сопоставляет поля записей верхнего уровня и поддерживает объектную схему или массив, чьи items являются одной объектной схемой. Составные/ссылочные схемы и неоднозначные наборы записей остаются явно неразрешенными.

Когда каждое обязательное поле имеет явное совместимое сопоставление, adaptation.status равен ready, а adaptation.draft_plan — это обычный план трансформации v1. Запустите этот план через data_transform; адаптер не создает отдельного пути выполнения или пятого публичного инструмента.

Библиотечный 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}]},
            }
        ],
    }
)

Публичные вызовы возвращают status: ok, status: dry_run или status: error со стабильным error.code. Успешные трансформации раскрывают наблюдаемые во время выполнения изменения в execution_effects; они не раскрывают трассировки стека или внутренности DuckDB.

См. модель продукта, план трансформации v1 и контракт на проверку. Вклад описан в CONTRIBUTING.md, отчеты о безопасности — в SECURITY.md, а важные изменения — в CHANGELOG.md.