TL;DR

  • jevq는 JSON Lines(JSONL) 입력의 각 값에 Jev TypeSafe System One 모델로 예·아니요 질문을 하고, 기준을 통과한 값을 전달하는 jq용 사이드카임.
  • QUESTION은 검색어가 아니라 현재 값에 대한 예·아니요 주장이며, 기본 임계값은 0.5임.
  • --fields는 모델에 보낼 키만 제한하지만 출력은 전체 값이며, --score는 점수와 원본 값을 출력하고 --pass는 API 호출 없이 모든 값을 그대로 전달함.
  • API 키는 TYPESAFE_API_KEY로 설정하며, 기본 모델은 jev-1.13.0이고 환경 변수보다 명령행 플래그가 우선함.
  • 티켓·로그·이슈 필터링에 활용할 수 있으며, v1에서는 --path, jev() 내장 기능, 동시성, 캐싱을 지원하지 않음.

jevq

  • 파이프라인은 jq | jevq | jq 형태로 구성되며, jq가 구조를 처리하고 jevq가 표준 입력에서 한 줄에 하나씩 JSON 값을 읽어 각각 Jev에 질문한 뒤, 긍정 응답을 받은 값을 전달함.
  • QUESTION은 검색 질의가 아니라 현재 값이 참인지 묻는 예·아니요 주장임.

설치

  • uv tool install --editable .로 설치함.
  • TYPESAFE_API_KEY 환경 변수에 API 키를 설정함.
  • scripts/reinstall-cli.sh는 강제 재빌드를 수행하며, --dry-run, --no-editable, --skip-smoke 옵션을 제공함.

옵션

  • 사용 형식은 jevq [options] QUESTION이며, --pass를 지정하지 않는 한 QUESTION이 필수임. JSONL을 표준 입력에서 읽음.
  • QUESTION: 각 값에 대한 예·아니요 주장. 기본값 없음.
  • -t N, --threshold N: 점수가 N 이상인 값을 유지함. 기본값은 0.5이며 JEV_THRESHOLD로 설정 가능함.
  • -f a,b, --fields a,b: 지정한 키만 모델에 전달함. 기본값은 전체 값이며, 출력에는 전체 값이 유지됨.
  • --score: 기본값은 꺼짐이며, 각 값을 score와 원본 value를 담은 객체로 출력함.
  • --pass: 기본값은 꺼짐이며, API 호출이나 API 키 없이 모든 값을 변경 없이 출력함.
  • --model NAME: 질문에 사용할 모델을 지정함. 기본값은 jev-1.13.0이며 JEV_MODEL로 설정 가능함.
  • -v, --verbose: 기본값은 꺼짐이며, 처리 개수와 응답 모델을 표준 오류(stderr)에 출력함.
  • -h, --help: 도움말을 표시하고 종료함.
  • --score와 --pass는 함께 사용할 수 없으며, 플래그는 해당 환경 변수보다 우선함.

환경 변수

  • TYPESAFE_API_KEY: 기본값 없음. --pass를 사용하지 않을 때 필요한 API 키임.
  • JEV_MODEL: 기본값은 jev-1.13.0임.
  • JEV_BASE_URL: 기본값은 https://api.typesafe.ai/v1/systemone임.
  • JEV_THRESHOLD: 기본값은 0.5임.

사용 사례

  • jq -c '.[] | select(.status == "open")' samples/tickets.json | jevq "the customer is asking for a refund" | jq -c '{id, subject}'는 환불을 요청하는 열린 티켓을 {id, subject} 형태로 출력함.
  • jq -c 'select(.level == "error")' samples/app.ndjson | jevq "this error is caused by a network timeout, not a bug in our code"는 코드 결함이 아니라 네트워크 시간 초과로 보이는 오류 로그 행을 필터링함.
  • gh api 'repos/itchyny/gojq/issues?state=open&per_page=100' | jq -c '.[] | select(.pull_request | not) | {number, title, body}' | jevq --score "reports a crash or wrong output, not a feature request" | jq -rs 'sort_by(-.score) | .[:5][] | .value | "\(.number)\t\(.title)"'는 기능 요청이 아닌 충돌 또는 잘못된 출력을 보고하는 열린 이슈 가운데 버그 가능성이 높은 다섯 건을 번호와 제목으로 출력함.
  • 추가 예제는 docs/examples.md에 있으며, 출력 규칙·종료 코드·HTTP·재시도 관련 전체 계약은 docs/jevq.md에 있음.

테스트

  • uv run pytest -q로 테스트를 실행함.
  • bash tests/samples/run.sh로 샘플 파이프라인을 실행함.
  • JEVQ_LIVE=1 TYPESAFE_API_KEY=... bash tests/samples/run.sh는 샘플 파이프라인을 실제로 실행함.

v1에서 지원하지 않는 기능

  • --path, jev() 내장 기능, 동시성, 캐싱은 v1에서 지원하지 않음.