가이드
Jev Python 가이드
공식 TypeSafe Python SDK는 이 사이트에서 그대로 동작합니다. typesafe-sdk를 설치하고 base URL을 jev-api.org로 지정한 뒤 jev-api.org 키로 system_one을 호출하면 됩니다. 설치, 설정, 세 가지 질문 타입, 답 읽기, 비동기 클라이언트를 다룹니다.
업데이트
설치
PyPI 패키지명은 typesafe-sdk이며 Python 3.10 이상이 필요합니다. 소스는 github.com/typesafe-ai/typesafe-sdk-python에 있습니다.
pip install typesafe-sdk
# or: uv add typesafe-sdk
# requires Python 3.10+키와 base URL 설정
SDK는 두 개의 환경 변수를 읽습니다. TYPESAFE_API_KEY에는 jev-api.org 대시보드의 키를 넣으세요. TypeSafe 콘솔 키는 여기서 동작하지 않습니다. TYPESAFE_BASE_URL을 https://jev-api.org로 지정하면 api.typesafe.ai 대신 TypeSafe 호환 /v1/systemone 엔드포인트로 요청이 갑니다.
# .env — a key from your jev-api.org dashboard
TYPESAFE_API_KEY=jeva_...
TYPESAFE_BASE_URL=https://jev-api.orgTypeSafeClient(api_key=..., base_url="https://jev-api.org")처럼 직접 전달해도 됩니다. 기본 모델은 jev-latest이며 TYPESAFE_DEFAULT_MODEL이나 model 인자로 바꿀 수 있습니다. 기본 타임아웃은 10초입니다.
첫 호출: Noul, Choice, Score
client.system_one은 state(문자열·객체·배열)와 Noul, Choice, Score 클래스로 만든 questions 맵을 받습니다. 아래 호출은 모델 공표 지연 범위인 70~500ms 안에 돌아오며 이 사이트에서 크레딧 1을 사용합니다.
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
with TypeSafeClient() as client: # reads TYPESAFE_API_KEY and TYPESAFE_BASE_URL
response = client.system_one(
state={"document": "I was charged twice. Please fix this ASAP."},
questions={
"billing": Noul(instructions="Is this ticket about billing?"),
"tone": Choice(
instructions="What is the customer's tone?",
criteria={"calm": None, "frustrated": None, "angry": None},
),
"urgency": Score(
instructions="How urgent is this ticket?",
criteria=["can wait", "this week", "today"],
),
},
)
print(response.nouls["billing"].noul) # 0.0 .. 1.0
print(response.choices["tone"].choice) # winning option
print(response.scores["urgency"].score) # fractional level답 읽기
응답 객체는 타입화된 뷰를 제공합니다. response.nouls, response.choices, response.scores를 질문 id로 조회하세요. Noul 답은 .noul(예의 확률 0~1), Choice 답은 .choice, .probabilities, .confidence, Score 답은 단계 사이에 놓일 수 있는 .score와 .legend, .probabilities, .confidence를 가집니다.
confidence를 인계 신호로 쓰세요. 낮거나 두 옵션이 가까우면 임계값을 내리는 대신 사람에게 넘기거나 더 좁은 후속 질문을 던지세요. response.answers["id"]로 원시 질문 객체도 읽을 수 있습니다.
비동기 클라이언트
AsyncTypeSafeClient는 같은 인터페이스를 await 가능하게 제공합니다. FastAPI 엔드포인트나 여러 state를 동시에 처리하는 워커에서 유용합니다.
from typesafe_sdk import AsyncTypeSafeClient, Noul
async with AsyncTypeSafeClient() as client:
response = await client.system_one(
state="I was charged twice for my subscription.",
questions={"refund": Noul(instructions="Is the customer asking for money back?")},
)
print(response.answers["refund"])SDK 없이: requests만 사용
의존성을 원하지 않으면 JSON 본문을 직접 POST하면 됩니다. 이 사이트의 간단한 엔드포인트 /api/v1/decisions은 같은 state+questions 형태를 받고 모델 id는 jev-1.13이며 제한이 조금 더 엄격합니다(질문 1~6개, Choice 옵션 2~8개).
import os
import requests
res = requests.post(
"https://jev-api.org/api/v1/decisions",
headers={"Authorization": f"Bearer {os.environ['JEV_API_KEY']}"},
json={
"model": "jev-1.13",
"state": "I was charged twice for my subscription.",
"questions": {
"refund": {"type": "noul", "instructions": "Is the customer asking for money back?"}
},
},
timeout=30,
)
print(res.json()["answers"]["refund"])오류와 타임아웃
jev-api.org는 detail 필드가 있는 JSON 오류를 반환합니다. 보게 될 코드는 다음과 같습니다.
- 401 — API 키가 없거나 거부됨. Authorization: Bearer 헤더와 키가 이 사이트 발급인지 확인하세요.
- 402 — 키는 유효하지만 잔액이 부족합니다. 가격 페이지에서 크레딧을 추가하세요.
- 422 — 본문이 검증에 실패했거나 모델이 거부했습니다(예: 64k/32k 토큰 제한 초과). 메시지가 필드를 지목합니다.
- 429 — 속도 제한. 잠시 후 재시도하세요.
- 502 — 결정 서비스가 답을 반환하지 않았습니다. 크레딧은 사용되지 않습니다.
자주 묻는 질문
TypeSafe 콘솔 키를 이 사이트에서 쓸 수 있나요?
안 됩니다. 키는 상호 교환되지 않습니다. TypeSafe 키는 api.typesafe.ai용이고 jev-api.org 대시보드 키는 이 사이트용입니다. TYPESAFE_API_KEY를 jev-api.org 키로, TYPESAFE_BASE_URL을 https://jev-api.org로 설정하세요.
SDK가 이 사이트에서 호출하는 엔드포인트는?
base_url을 https://jev-api.org로 지정하면 SDK는 TypeSafe 호환 엔드포인트 /v1/systemone에 POST합니다. 전체 질문 세트(최대 256 질문, 255 Choice 옵션, 구조화 instructions)를 받고 성공 호출당 크레딧 1입니다.
SDK가 자동으로 재시도하나요?
TypeSafe SDK는 429 같은 일시적 오류에 대한 기본 재시도 정책을 갖고 있으며, 클라이언트의 retry 옵션으로 덮어쓸 수 있습니다. 422 검증 오류는 재시도가 아니라 본문을 고쳐야 합니다.
필요한 Python 버전은?
Python 3.10 이상입니다. typesafe-sdk 패키지에 동기(TypeSafeClient)와 비동기(AsyncTypeSafeClient) 클라이언트가 모두 있습니다.
어떤 모델 버전이 답했는지 어떻게 아나요?
응답의 model 필드는 항상 실제로 응답한 버전 id(현재 jev-1.13.0)를 보고합니다. jev-latest 같은 별칭을내도 마찬가지입니다.
첫 결정 보내기
키를 만들고 두 환경 변수를 설정한 뒤 위 스니펫을 실행하세요.