CLI 사용 가이드 — KPubData Builder

이 문서는 kpubdata-builder 명령줄 도구(CLI)의 실제 사용법을 다룹니다. 각 명령의 출력은 실제 실행 결과를 그대로 수록했습니다. 라이브 API 키가 필요한 preview 및 build 명령의 출력은 테스트 픽스처 기반 예시임을 명시합니다.

---

설치 확인

설치가 완료되면 kpubdata-builder 실행 파일이 PATH에 등록됩니다. 버전을 확인하려면 --version 옵션을 사용합니다.

$ kpubdata-builder --version
kpubdata-builder 0.1.0

---

전체 도움말

$ kpubdata-builder --help
usage: kpubdata-builder [-h] [--version] command ...

KPubData Builder command-line interface.

positional arguments:
  command
    validate  Validate a BuildSpec YAML file.
    preview   Preview a BuildSpec: schema and sample rows without writing
              artifacts.
    build     Execute a BuildSpec through the Medallion pipeline.
    publish   Publish build artifacts to a local or remote destination.

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

---

하위 명령 (Subcommands)

validate — 빌드 명세 검증

validate 명령은 BuildSpec YAML 파일의 구조와 필드 유효성을 검사합니다. 실제 데이터 소스(data.go.kr 등)에는 접근하지 않으므로 API 키 없이 오프라인에서 실행할 수 있습니다.

$ kpubdata-builder validate --help
usage: kpubdata-builder validate [-h] spec

positional arguments:
  spec        Path to the BuildSpec YAML file.

options:
  -h, --help  show this help message and exit

검증 성공 예시

다음은 유효한 BuildSpec YAML 파일 apt_trade_spec.yaml 예시입니다.

# apt_trade_spec.yaml
dataset_id: dataset.seoul_apt_trade
title: 서울 아파트 실거래가
description: |
  data.go.kr 국토교통부 아파트매매 실거래가 데이터를 수집해
  JSONL 형식으로 내보내는 BuildSpec 예제입니다.
sources:
  - provider: datago
    dataset: apt_trade
    alias: gangnam_202401
    params:
      LAWD_CD: "11680"
      DEAL_YMD: "202401"
exports:
  - kind: jsonl
    output_path: out/apt_trade.jsonl

$ kpubdata-builder validate apt_trade_spec.yaml
spec is valid: dataset.seoul_apt_trade

성공 시 종료 코드는 0이며, 표준 출력에 spec is valid: <dataset_id>가 출력됩니다.

검증 실패 예시 1 — 로드 오류

sources 목록이 비어 있는 YAML은 로드(파싱) 단계에서 오류가 발생합니다.

# broken_empty_sources.yaml
dataset_id: dataset.broken
title: Broken Spec
description: sources 목록이 비어 있어 검증에 실패하는 예제입니다.
sources: []
exports:
  - kind: jsonl
    output_path: out/data.jsonl

$ kpubdata-builder validate broken_empty_sources.yaml
error: failed to load spec: Failed to parse build spec: sources must not be empty

종료 코드는 1입니다. 오류 메시지는 표준 오류(stderr)로 출력됩니다.

검증 실패 예시 2 — 스펙 유효성 오류

지원하지 않는 export.kind 값은 파싱은 성공하지만 유효성 검사(validation) 단계에서 실패합니다.

# broken_export_kind.yaml
dataset_id: dataset.broken_export
title: 잘못된 Export Kind 예제
description: 지원하지 않는 export kind가 포함된 스펙으로 검증 실패를 보여줍니다.
sources:
  - provider: datago
    dataset: apt_trade
exports:
  - kind: unsupported_format
    output_path: out/data.unsupported

$ kpubdata-builder validate broken_export_kind.yaml
error: spec validation failed:
  - exports[0].kind 'unsupported_format' is not supported; supported kinds: ['csv', 'huggingface', 'jsonl', 'kaggle', 'markdown', 'parquet']

지원되는 export kind는 csv, huggingface, jsonl, kaggle, markdown, parquet입니다.

---

preview — 스키마·샘플 미리 보기

preview 명령은 BuildSpec을 검증한 뒤 각 소스(source)의 스키마(컬럼 목록)와 샘플 행을 가져옵니다. 아티팩트(artifact) 파일은 생성하지 않습니다.

$ kpubdata-builder preview --help
usage: kpubdata-builder preview [-h] [--limit LIMIT] spec

positional arguments:
  spec           Path to the BuildSpec YAML file.

options:
  -h, --help     show this help message and exit
  --limit LIMIT  Maximum sample rows per source (default: 5).

[예시 — 픽스처 기반 출력] preview 명령은 실제 data.go.kr API에 접근하므로 아래 출력은 라이브 실행이 아닌 테스트 픽스처를 바탕으로 재구성한 대표 예시입니다. 실제 실행을 위해서는 KPUBDATA_DATAGO_API_KEY 환경 변수에 유효한 API 키가 필요합니다.

$ export KPUBDATA_DATAGO_API_KEY="<your-data-go-kr-api-key>"
$ kpubdata-builder preview apt_trade_spec.yaml --limit 3
preview: dataset.seoul_apt_trade
  - gangnam_202401: sggCd (Utf8), umdNm (Utf8), aptNm (Utf8), excluUseAr (Float64), floor (Int64), buildYear (Int64), dealYear (Int64), dealMonth (Int64), dealDay (Int64), dealAmount (Utf8)
    sample (3 of 142 rows):
      {'sggCd': '11680', 'umdNm': '개포동', 'aptNm': '개포주공1단지', 'excluUseAr': 41.96, 'floor': 3, 'buildYear': 1982, 'dealYear': 2024, 'dealMonth': 1, 'dealDay': 6, 'dealAmount': '82,500'}
      {'sggCd': '11680', 'umdNm': '개포동', 'aptNm': '개포주공2단지', 'excluUseAr': 36.0, 'floor': 9, 'buildYear': 1983, 'dealYear': 2024, 'dealMonth': 1, 'dealDay': 8, 'dealAmount': '53,500'}
      {'sggCd': '11680', 'umdNm': '역삼동', 'aptNm': '역삼래미안', 'excluUseAr': 59.97, 'floor': 12, 'buildYear': 2003, 'dealYear': 2024, 'dealMonth': 1, 'dealDay': 11, 'dealAmount': '120,000'}

소스 fetch에 실패하면 표준 오류(stderr)에 오류 메시지가 출력되고 종료 코드 1이 반환됩니다.

---

build — 파이프라인 전체 실행

build 명령은 BuildSpec의 Medallion 파이프라인(Bronze → Silver → Gold)을 전체 실행하고 아티팩트(artifact)와 매니페스트(manifest)를 생성합니다.

$ kpubdata-builder build --help
usage: kpubdata-builder build [-h] [--output-dir OUTPUT_DIR] [--run-id RUN_ID]
                              spec

positional arguments:
  spec                  Path to the BuildSpec YAML file.

options:
  -h, --help            show this help message and exit
  --output-dir OUTPUT_DIR
                        Run workspace root directory (default: build).
  --run-id RUN_ID       Run identifier (default: generated timestamp).

[예시 — 픽스처 기반 출력] build 명령은 실제 data.go.kr API에 접근하므로 아래 출력은 테스트 픽스처를 바탕으로 재구성한 대표 예시입니다. 실제 실행을 위해서는 KPUBDATA_DATAGO_API_KEY 환경 변수에 유효한 API 키가 필요합니다.

$ export KPUBDATA_DATAGO_API_KEY="<your-data-go-kr-api-key>"
$ kpubdata-builder build apt_trade_spec.yaml --output-dir ./build --run-id run-20240601
build: dataset.seoul_apt_trade (run run-20240601)
  - gangnam_202401: ok [bronze, silver, gold]
manifest: <path>/build/run-20240601/manifest.json

--run-id를 생략하면 타임스탬프 기반 식별자가 자동 생성됩니다.

빌드가 실패하면 실패한 소스 키와 오류 내용이 표준 오류(stderr)에 출력되고 종료 코드 1이 반환됩니다.

$ kpubdata-builder build apt_trade_spec.yaml
build: dataset.seoul_apt_trade (run 20240601-153022)
  - gangnam_202401: failed [-]
error: build failed for one or more sources
  - gangnam_202401: ConfigError: KPUBDATA_DATAGO_API_KEY not set

---

publish — 아티팩트 게시

publish 명령은 이미 생성된 아티팩트를 로컬 디렉터리, Hugging Face, 또는 Kaggle에 게시합니다.

$ kpubdata-builder publish --help
usage: kpubdata-builder publish [-h] [--target {huggingface,kaggle,local}]
                                --destination DESTINATION --artifacts-dir
                                ARTIFACTS_DIR [--public]
                                spec

positional arguments:
  spec                  Path to the BuildSpec YAML file.

options:
  -h, --help            show this help message and exit
  --target {huggingface,kaggle,local}
                        Publish target (default: local).
  --destination DESTINATION
                        Local directory path (local) or HF repo id
                        (huggingface).
  --artifacts-dir ARTIFACTS_DIR
                        Directory whose files will be published.
  --public              Create new datasets as public (kaggle only; default:
                        private).

로컬 디렉터리로 복사하는 예시입니다.

$ kpubdata-builder publish apt_trade_spec.yaml \
    --target local \
    --destination ./dist/apt_trade \
    --artifacts-dir ./build/run-20240601
publish: dataset.seoul_apt_trade -> local
  target: <path>/dist/apt_trade
  artifacts: 2

---

서비스 모드 (HTTP API)

kpubdata-builder 패키지는 HTTP 서비스로 실행할 수도 있습니다. 서비스는 stdlib http.server 어댑터 기반이며 추가 의존성 없이 실행됩니다.

서비스 기동

별도 CLI serve 명령은 없습니다. BuilderService와 serve()를 직접 임포트해 실행합니다.

# serve_dev.py  —  개발·로컬 테스트용 기동 스크립트 예시
from pathlib import Path
from kpubdata_builder.service import BuilderService, serve
from kpubdata_builder.stages.bronze.build import SourceClient

def _client_factory() -> SourceClient:
    from kpubdata import Client
    return Client.from_env()  # type: ignore[return-value]

service = BuilderService(
    output_root=Path("build"),
    client_factory=_client_factory,
)
serve(service, host="127.0.0.1", port=8000)

$ python serve_dev.py
# 서버가 127.0.0.1:8000에서 요청을 대기합니다 (Ctrl-C로 종료).

/validate와 /version은 API 키 없이 오프라인으로 사용할 수 있습니다. /preview와 /build는 KPUBDATA_DATAGO_API_KEY 환경 변수가 필요합니다.

GET /version

서비스가 노출하는 API 계약 버전을 확인합니다.

$ curl -s http://127.0.0.1:8000/version

{
  "service": "kpubdata-builder",
  "api_version": "1.0.0"
}

POST /validate

BuildSpec YAML 문자열을 JSON body의 spec 필드로 전달합니다.

검증 성공:

$ curl -s -X POST http://127.0.0.1:8000/validate \
    -H "Content-Type: application/json" \
    -d '{
      "spec": "dataset_id: dataset.sample\ntitle: Sample\ndescription: test\nsources:\n  - provider: datago\n    dataset: apt_trade\nexports:\n  - kind: jsonl\n    output_path: out/data.jsonl\n"
    }'

{
  "status": "valid",
  "dataset_id": "dataset.sample",
  "api_version": "1.0.0"
}

검증 실패 (지원하지 않는 export kind):

{
  "status": "invalid",
  "problems": [
    "exports[0].kind 'unsupported_format' is not supported; supported kinds: ['csv', 'huggingface', 'jsonl', 'kaggle', 'markdown', 'parquet']"
  ]
}

POST /build

[예시 — 대표 응답] POST /build는 실제 data.go.kr API에 접근하므로 아래 응답은 테스트 픽스처를 바탕으로 재구성한 대표 예시입니다. 실제 실행을 위해서는 KPUBDATA_DATAGO_API_KEY 환경 변수에 유효한 API 키가 필요합니다.

BuildSpec YAML 문자열을 JSON body의 spec 필드로 전달합니다. 선택적으로 run_id를 지정할 수 있습니다.

빌드 성공 (HTTP 200):

$ curl -s -X POST http://127.0.0.1:8000/build \
    -H "Content-Type: application/json" \
    -d '{"spec": "<spec-yaml-string>", "run_id": "run-20240601"}'

{
  "status": "ok",
  "run_id": "run-20240601",
  "outcomes": [
    {
      "source_key": "gangnam_202401",
      "status": "ok",
      "stages_completed": ["bronze", "silver", "gold"],
      "error": null
    }
  ],
  "manifest": "build/run-20240601/manifest.json",
  "api_version": "1.0.0"
}

빌드 실패 (HTTP 502 — 업스트림 소스 fetch 실패):

{
  "status": "failed",
  "run_id": "run-20240601",
  "outcomes": [
    {
      "source_key": "gangnam_202401",
      "status": "failed",
      "stages_completed": [],
      "error": "ConfigError: KPUBDATA_DATAGO_API_KEY not set"
    }
  ],
  "manifest": "build/run-20240601/manifest.json",
  "api_version": "1.0.0"
}

GET /artifacts/{run_id}

지정한 실행 워크스페이스의 산출물 파일 목록을 반환합니다.

$ curl -s http://127.0.0.1:8000/artifacts/run-20240601

{
  "run_id": "run-20240601",
  "files": [
    "gangnam_202401/apt_trade.jsonl",
    "manifest.json"
  ]
}

실행 ID가 존재하지 않으면 HTTP 404가 반환됩니다.

---

구현된 엔드포인트는 GET /version, POST /validate, POST /preview, POST /build, GET /artifacts/{run_id}이며, 이것이 실제 동작의 기준입니다. 공식 API 계약(스키마·버전 협상 포함)은 PR #231에서 실제 구현과 동기화된 contract/builder-api.yaml을 참고하세요.

---

환경 변수

변수	설명
KPUBDATA_DATAGO_API_KEY	data.go.kr 공공데이터 API 인증 키. preview 및 build 명령 실행 시 필요합니다.

API 키는 data.go.kr에서 회원가입 후 발급받을 수 있습니다.

---

관련 문서

문서	설명
에러 처리	에러 계층 및 단계별 에러 처리 정책
예제: 서울 아파트 실거래가	종단 간 데이터 수집·게시 예제
API 규약	서비스 HTTP API 상세 규약