BatchTicket

BatchTicket (CLI: adt) es un transductor determinista de datos estructurados para flujos de trabajo de agentes. Como el pequeño ticket que viaja con un lote de producción o de envío, cada ejecución lleva un plan versionado y un registro explícito de lo que la ejecución cambió. Ese registro no afirma que el mapeo fuera semánticamente correcto.

No es otro dialecto de jq o SQL. DuckDB, JSON Schema, PyYAML y los analizadores estándar se encargan del trabajo de ejecución establecido. Este proyecto es el responsable del contrato de agente en torno a ellos.

La versión 0.2.0 es un candidato a lanzamiento de código fuente aún no publicado. El proyecto está licenciado bajo la Apache License 2.0. Los identificadores técnicos estables siguen siendo agent-data-transformer, data-transformer, adt y las cuatro herramientas MCP data_*.

Qué está implementado

• Inspecciona JSON, JSONL, CSV, TSV, YAML y Parquet sin devolver las cargas útiles completas.

• Descubre conjuntos de registros anidados acotados en envolturas JSON/YAML y perfila sus campos lógicos.

• Compara la forma de un registro fuente con un JSON Schema de destino, muestra solo los candidatos de mapeo estructural y emite un borrador de plan ejecutable solo después de mapeos compatibles explícitos.

• Transformation Plan v1 seguro, sin ejecución de código crudo, SQL, shell, jq, regex ni plantillas.

• Filtrado, proyección, eliminación, renombrado, ordenación, limitación, deduplicación, conversión de tipos, derivación, explosión, unión, agrupación, pivote, despivote, aplanado, desaplanado y mutación de árbol.

• JSON Schema más aserciones de no nulo, unicidad, recuento de filas, campo y tipo.

• Diff con o sin clave que tiene en cuenta el esquema.

• Ejecución en seco con verificación previa del destino real, publicación atómica por etapas y protección contra sobrescritura.

• Aislamiento del worker durante toda la llamada con límites acumulativos de fuente/byte/fila/ítem/profundidad/tiempo/RSS/temp.

• Un límite máximo de bytes sobre la respuesta serializada completa, incluyendo muestras, formas, efectos de ejecución, diffs, fallos de validación y errores.

• Un único modelo de Plan v1 estricto y tipado genera la validación en tiempo de ejecución, el JSON Schema publicado y el esquema MCP en vivo.

• Un único núcleo compartido con CLI y cuatro herramientas MCP a nivel de tarea.

Related MCP server: Trace MCP

Instalación y ejecución

Clonado para desarrollo:

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

Construye un plugin específico de plataforma que no necesita el repositorio, uv, una instalación de Python ni una conexión de red en tiempo de ejecución:

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

La compilación produce un directorio de plugin, un archivo .tar.gz y una suma de verificación SHA-256 en dist/plugin/. Instala o copia el directorio generado completo; el .mcp.json de la raíz del repositorio es configuración de desarrollo, mientras que el .mcp.json del plugin generado invoca directamente su ejecutable empaquetado. El marketplace local generado apunta Codex a ese directorio autocontenido. Reconstruir con --replace rechaza raíces de salida con enlaces simbólicos o destinos generados antes de eliminar o sobrescribir cualquier cosa.

El paquete autocontenido generado es actualmente un artefacto de validación local, no un activo de lanzamiento público. Incorpora un runtime de Python, paquetes de Python y bibliotecas nativas cuyos materiales de licencia de terceros aún no están ensamblados en el archivo. No subas el directorio del plugin, el archivo ni la suma de verificación a un GitHub Release. Esto no restringe la publicación ni el uso del repositorio de código fuente Apache-2.0; consulta la lista de verificación de lanzamiento.

La transformación de ejemplo devuelve dos registros en línea e informa a través de execution_effects de que se eliminó una fila de entrada. La salida a archivo es opt-in mediante output.path; los archivos existentes nunca se reemplazan a menos que output.overwrite sea explícitamente verdadero.

Las rutas de la CLI son rutas de usuario explícitas y pueden ser absolutas. Las rutas de archivos MCP son una capacidad más restringida: el servidor utiliza primero los espacios de trabajo concedidos mediante el protocolo de raíces MCP. Se selecciona automáticamente una única raíz; cuando se conceden varias raíces, pasa el name exacto de cada raíz en el campo opcional workspace de la herramienta. Los hosts sin soporte de raíces pueden pasar un ADT_WORKSPACE_ROOT explícito como concesión de compatibilidad. Las rutas de las herramientas permanecen relativas a la raíz seleccionada, y se rechazan los escapes absolutos, de directorio padre, URI y de enlaces simbólicos. Las llamadas MCP exclusivamente en línea no requieren concesión de espacio de trabajo.

Codex CLI 0.148 no pasa actualmente raíces MCP a los servidores de plugins locales. Para una prueba en frío del host CLI, ejecuta Codex con ADT_WORKSPACE_ROOT establecido en el espacio de trabajo de prueba exacto. Las herramientas de solo lectura pueden ejecutarse con approval=never; data_transform tiene capacidad condicional de salida a archivo y, por lo tanto, requiere una política de host con capacidad de aprobación incluso cuando una llamada concreta devuelve datos en línea. Una llamada bloqueada es un resultado de autorización, no un permiso para recurrir a la shell ni a la reescritura de datos en el lado del modelo.

Adaptación determinista del esquema

data_inspect acepta un target_schema opcional y un objeto mappings. Puede seleccionar un conjunto único de registros anidados basándose en evidencia estructural, sugerir coincidencias exactas o de nombre normalizado, e informar sobre campos incompatibles, faltantes, duplicados, omitidos o eliminados. No utiliza sinónimos difusos, conversiones de tipo ni valores predeterminados. El adaptador v1 mapea los campos de registro de nivel superior y admite un esquema de objeto o un array cuyo items es un esquema de objeto. Los esquemas compuestos/de referencia y los conjuntos de registros ambiguos permanecen explícitamente sin resolver.

Cuando cada campo obligatorio tiene un mapeo compatible explícito, adaptation.status es ready y adaptation.draft_plan es un Transformation Plan v1 normal. Ejecuta ese plan mediante data_transform; el adaptador no crea una ruta de ejecución separada ni una quinta herramienta pública.

API de librería

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}]},
            }
        ],
    }
)

Las llamadas públicas devuelven status: ok, status: dry_run o status: error con un error.code estable. Las transformaciones exitosas exponen los cambios observados en tiempo de ejecución en execution_effects; no filtran trazas de pila ni detalles internos de DuckDB.

Consulta el modelo de producto, Transformation Plan v1 y el contrato de revisión. Las contribuciones se describen en CONTRIBUTING.md, los informes de seguridad en SECURITY.md y los cambios notables en CHANGELOG.md.