data-transformer

BatchTicket

Move structured-data work from model reasoning into the deterministic BatchTicket tools. Keep semantic mapping choices with the user when field meaning is ambiguous.

Route the task

• Call data_inspect when the source shape is genuinely unknown or the user asks what it contains.
• Call data_transform directly when the source shape and requested mapping are already known. Do not add a preliminary inspect call by habit.
• Call data_validate for JSON Schema, non-null, unique, type, field, or row-count checks.
• Call data_diff for schema and record comparison; provide stable key fields when records have a real unique identity.

An ordinary known task should take one tool call. One successful deterministic call is sufficient for its recorded observations: never repeat identical arguments for confirmation, and never rerun merely to change sample_rows, shorten presentation, or obtain a differently sized duplicate sample. If result.data is present, answer from it. Treat a stable validation failure or input error as the result; do not retry with guessed fields or generic code. None of these runtime observations independently proves semantic or business correctness.

Omit optional sampling controls for ordinary small results. If the user actually needs a bounded sample, use sample_rows: 5 unless they requested another value; the hard maximum is 100. Never substitute 100 or 1000 as a default merely because a schema advertises a maximum.

Use the public tool schema directly; do not search the installed plugin, runtime bundle, README, source tree, or memory to discover arguments. Common source forms are:

{"source":{"path":"users.json","select":"data.users[*]"},"sample_rows":2}

{"source":{"inline":[{"id":1},{"id":2}]},"sample_rows":2}

select belongs inside source. When an unselected JSON or YAML envelope contains nested record arrays, one data_inspect call reports them in shape.record_sets with their selector, row count, recursively profiled fields, and logical JSON types; the separate bounded tree sample retains examples at those paths. Those logical types are the public contract for user-facing field/type questions. Answer from that result; do not make a second selector call merely to replace logical JSON types with DuckDB storage types unless the user explicitly asks for engine-level types.