BatchTicket

BatchTicket(CLI: adt)은 Agent 워크플로우를 위한 결정적(deterministic) 구조화 데이터 트랜스듀서입니다. 생산 또는 배송 배치와 함께 이동하는 작은 티켓처럼, 각 실행은 버전이 지정된 계획과 실행이 무엇을 변경했는지에 대한 명시적 기록을 담고 있습니다. 이 기록은 매핑이 의미적으로 정확했다고 주장하지 않습니다.

이것은 jq나 SQL의 또 다른 방언이 아닙니다. DuckDB, JSON Schema, PyYAML 및 표준 파서들은 이미 확립된 실행 작업을 담당합니다. 이 프로젝트는 그들에 대한 Agent 계약을 담당합니다.

버전 0.2.0은 아직 출시되지 않은 소스 릴리스 후보입니다. 이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여됩니다. 안정적인 기술 식별자는 agent-data-transformer, data-transformer, adt, 그리고 네 가지 data_* MCP 도구로 유지됩니다.

구현된 기능

• 전체 페이로드를 반환하지 않고 JSON, JSONL, CSV, TSV, YAML 및 Parquet을 검사합니다.

• JSON/YAML 봉투(envelope)에서 경계가 지정된 중첩 레코드 집합을 발견하고 해당 논리 필드를 프로파일링합니다.

• 소스 레코드 형태를 대상 JSON Schema와 비교하고, 구조적 매핑 후보만 표면화하며, 명시적으로 호환되는 매핑이 있어야만 실행 가능한 초안 계획을 생성합니다.

• 원시 코드, SQL, 셸, jq, 정규식 또는 템플릿 실행이 없는 안전한 변환 계획(Transformation Plan) v1.

• 필터(filter), 프로젝트(project), 드롭(drop), 이름 변경(rename), 정렬(sort), 제한(limit), 중복 제거(deduplicate), 형변환(cast), 파생(derive), 폭발(explode), 조인(join), 그룹(group), 피벗(pivot), 언피벗(unpivot), 평탄화(flatten), 비평탄화(unflatten) 및 트리 변이(tree mutation).

• JSON Schema와 비-null, 고유(unique), 행 수(row-count), 필드 및 유형 검증(assertion).

• 스키마를 인식하는 키(keyed) 또는 무키(unkeyed) diff.

• 실제 대상 사전 점검(preflight), 단계적 원자 게시, 덮어쓰기 보호가 있는 예행 실행(dry-run).

• 누적 소스/바이트/행/항목/깊이/시간/RSS/임시 제한이 있는 전체 호출 워커 격리.

• 샘플, 형태, 실행 결과, diff, 검증 실패 및 오류를 포함한 완전한 직렬화 응답 전체에 대한 바이트 상한(byte ceiling).

• 하나의 엄격한 타입의 Plan v1 모델이 런타임 검증, 게시된 JSON Schema 및 실행 중인 MCP 스키마를 생성합니다.

• CLI와 네 가지 작업 수준(task-level) 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

빌드는 dist/plugin/에 플러그인 디렉토리, .tar.gz 아카이브 및 SHA-256 체크섬을 생성합니다. 생성된 전체 디렉토리를 설치하거나 복사하십시오. 저장소 루트의 .mcp.json은 개발 구성이며, 생성된 플러그인의 .mcp.json은 번들된 실행으 직접 호출합니다. 생성된 로컬 마켓플레이스는 Codex가 해당 자체 포함 디렉토리를 가리키도록 합니다. --replace로 재빌드할 때는 삭제하거나 덮어쓰기 전에 심볼릭 링크된 출력 루트 또는 기존 생성 대상을 거부합니다.

생성된 자체 포함(self-contained) 번들은 현재 **로컬 검증 아티팩트(artifact)**이며, 공개 릴리스 자산이 아닙니다. 이 번들은 Python 런타임, Python 패키지 및 네이티브 라이브러리를 포함하며, 해당 서드 파티 라이선스 자료는 아직 아카이브에 포함되지 않았습니다. 플러그인 디렉토리, 아카이브 또는 체크섬을 GitHub Release에 업로드하지 마십시오. 이것은 Apache-2.0 소스 저장소를 게시하거나 사용하는 것을 제한하지 않습니다. 릴리스 체크리스트를 참조하십시오.

예제 변환은 두 레코드를 인라인으로 반환하며 execution_effects를 통해 입력 행 하나가 제거되었음을 보고합니다. 파일 출력은 output.path를 통해 선택적(opt-in)으로 제공되며, 기존 파일은 output.overwrite가 명시적으로 true일 때만 교체됩니다.

CLI 경로는 명시적인 사용자 경로이며 절대 경로일 수 있습니다. MCP 파일 경로는 더 좁은 기능입니다. 서버는 먼저 MCP 루트 프로토콜로 부여된 워크스페이스를 사용합니다. 단일 루트가 자동으로 선택되며 여러 루트가 부여된 경우, 도구의 선택적 workspace 필드에 해당 루트의 정확한 name을 전달하십시오. 루트를 지원하지 않는 호스트는 호환 부여로 명시적 ADT_WORKSPACE_ROOT를 전달할 수 있습니다. 도구 경로는 선택된 루트를 기준으로 유지되며 절대 경로, 상위 디렉터리, URI 및 심볼릭 링크 이탈은 거부됩니다. 인라인 전용 MCP 호출은 워크스페이스 부여 없이 가능합니다.

Codex CLI 0.148은 현재 MCP 루트를 로컬 플러그인 서버에 전달하지 않습니다. 콜드(cold) CLI 호스트 테스트를 위해 정확한 테스트 워크스페이스로 ADT_WORKSPACE_ROOT를 설정하고 Codex를 실행하십시오. 읽기 전용 도구는 approval=never로 실행할 수 있습니다. data_transform은 조건부 파일 출력 기능이 있으므로 특정 호출이 인라인으로 데이터를 반환하더라도 승인 가능한 호스트 정책이 필요합니다. 차단된 호출은 인가 결과일 뿐이며, 셸이나 모델 측 데이터 재작성으로 대체할 수 있는 권한이 아닙니다.

결정적 스키마 적응

data_inspect는 선택적 target_schema와 mappings 객체를 받습니다. 구조적으로 증거를 기반으로 고유한 중첩 레코드 집합을 선택하고, 정확한 이름 또는 정규화된 이름 일치를 제안하며, 호환되지 않는, 누락된, 중복된, 생략된 또는 삭제된 필드를 보고할 수 있습니다. 퍼지 동의어, 캐스트 또는 기본값을 사용하지 않습니다. v1 어댑터는 최상위 레코드 필드를 매핑하며 객체 스키마 또는 items가 하나의 객체 스키마인 배열을 지원합니다. 구성/참조 스키마 및 모호한 레코드 집합은 명시적으로 해결되지 않은 상태로 남습니다.

모든 필수 필드에 명시적이고 호환 가능한 매핑이 있으면 adaptation.status는 ready가 되고 adaptation.draft_plan은 일상적인 Transformation 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}]},
            }
        ],
    }
)

공개 호출은 안정적인 error.code와 함께 status: ok, status: dry_run 또는 status: error를 반환합니다. 성공한 변환은 execution_effects 아래에서 런타임 관측 변경 사항을 노출합니다. 스택 트레이스 또는 DuckDB 내부를 누출하지 않습니다.

제품 모델, Transformation Plan v1 및 검토 계약을 참조하십시오. 기여는 CONTRIBUTING.md, 보안 보고서는 SECURITY.md 및 주요 변경 사항은 CHANGELOG.md에 설명되어 있습니다.