/docs
Jev 사용하기
Jev는 타입이 지정된 질문에 따라 state를 평가하고, 코드에서 바로 분기할 수 있는 타입 값과 확률 분포로 이루어진 구조화된 답변을 반환합니다. 실행 방법을 안내합니다.
개요
Jev는 TypeSafe의 대표 모델이자 최초의 System One 모델이며, JevStation은 이를 중심으로 만든 워크스페이스입니다. 대규모 언어 모델은 사람이 읽을 텍스트를 만들도록 설계되어 있습니다. 그래서 코드가 소비할 판단을 요청하려면 텍스트 생성을 구조화된 출력에 억지로 맞추고 결과를 다시 파싱해야 합니다. Jev는 반대로 동작합니다. state와 타입이 지정된 질문을 보내면 타입이 지정된 답변을 바로 반환합니다. 텍스트 생성도, 파싱도, 해석할 문장도 없습니다.
빠른 시작
플레이그라운드에서 세 단계로 평가를 실행해 본 다음, 같은 모델을 직접 작성한 코드에서 호출해 보세요.
state 붙여 넣기
플레이그라운드를 열고 Jev가 판단할 내용을 붙여 넣으세요. 지원 티켓, 리뷰, 스펙, JSON 레코드 무엇이든 괜찮습니다. 플레이그라운드는 여러분의 코드가 호출할 것과 같은 규약을 호출합니다.
질문하기
판단마다 질문을 하나씩 추가하고, 한 번의 호출에서 Choice, Score, Noul을 섞어 쓸 수 있습니다. 모든 질문은 같은 state를 대상으로 평가됩니다.
답변 읽기
각 답변은 직접 정한 id 아래에 확률 분포와 함께 돌아오며, Choice와 Score에는 신뢰도 값이 추가됩니다.
코드에서 호출하기
플레이그라운드는 여러분의 코드가 호출할 것과 같은 규약입니다. 그곳에서 질문 세트를 설계한 뒤 자체 백엔드에서 호출하세요. 엔드포인트는 `POST /api/v1/systemone`이며, 설정에서 만든 API 키(`Authorization: Bearer sk_…`)로 인증하고, 플레이그라운드 실행과 같은 크레딧이 차감됩니다. JevStation의 사용량 집계 없이 모델과 직접 통신하고 싶다면 TypeSafe의 자체 API를 이용하시면 됩니다.
AI 에이전트에서 Jev 사용하기
AI 코딩 어시스턴트와 함께 작업 중이신가요? 엔드포인트, 인증, 요청과 답변 형태, 오류, 비용, 검증 방법까지 담은 통합 브리프를 통째로 복사해 Claude Code, Cursor 등 어떤 어시스턴트에든 붙여 넣으세요.
MCP 서버
같은 평가를 Streamable HTTP 기반 MCP 툴로도 사용할 수 있으며, API 키로 인증하고 HTTP API와 동일하게 과금됩니다. 툴: jev_decide, jev_run_question_set, jev_list_question_sets, jev_route_model, jev_guard_tool_call, jev_moderate, jev_get_credits. Claude Code의 경우:
claude mcp add --transport http jevstation https://jevstation.com/api/mcp \
--header "Authorization: Bearer $JEVSTATION_API_KEY"Agent Skills
세 가지 스킬이 에이전트에게 Jev를 호출하는 방법, 질문 세트를 설계하는 방법, Jev를 가드레일로 쓰는 방법을 알려 줍니다. 다음 명령으로 ~/.claude/skills에 설치하세요.
curl -fsSL https://jevstation.com/skills/install.sh | sh실행하기 전에 먼저 읽어 보고 싶으신가요? 이 스크립트는 /skills/jev-api/SKILL.md, /skills/jev-question-design/SKILL.md, /skills/jev-guardrails/SKILL.md만 다운로드합니다.
가이드: 오픈소스 프로젝트에서 쓰는 Jev
서로 독립된 GitHub 프로젝트 6개와, 각각에서 JevStation API 키를 만들어 Jev를 호출하는 단계별 가이드입니다. 이 프로젝트들은 JevStation과 관련이 없습니다.
질문 유형
TypeSafe는 세 가지 AI 프리미티브를 제공합니다. 각각 다른 종류의 질문을 받고 다른 종류의 답변을 반환합니다.
| 질문 유형 | 목적 | 반환값 |
|---|---|---|
| Choice | 직접 정의한 목록에서 옵션 하나 선택 | choice, probabilities, confidence |
| Score | 순서가 있는 루브릭으로 state를 평가 | score, probabilities, confidence |
| Noul | 이 진술은 참인가? | noul (0–1) |
원자적 질문, 코드에서 조합
System One 모델은 질문 하나가 구체적이고 범위가 명확한 한 가지만 물을 때 가장 잘 작동합니다. 아는 사람이 적절한 컨텍스트만 있으면 몇 초 안에 내릴 수 있는 판단이 그런 질문입니다. 질문에 긴 추론이 필요하거나 서로 독립적인 여러 요소를 함께 따져야 한다면 쪼개세요. 요소마다 따로 묻고 자체 공식으로 답변을 합치면, 나중에 우선순위를 바꿀 때 프롬프트를 고쳐 쓰는 대신 코드의 계수만 바꾸면 됩니다. 질문은 병렬로, 서로 격리된 채 평가되므로 질문을 늘려도 응답 시간은 거의 달라지지 않고 컨텍스트가 질문 사이에서 오염되지도 않습니다.
요청 파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| state | string | object | array | ✓ | 평가할 콘텐츠입니다. 텍스트는 일반 문자열로, 채팅 로그나 레코드, 애플리케이션의 현재 상태는 구조화된 데이터로 보냅니다. |
| model | string (optional) | ✓ | 선택 사항입니다. 답변할 의사결정 모델을 지정합니다. jev(기본값, TypeSafe), clef-flash 또는 clef(Cloudflare)를 쓸 수 있으며, Clef는 크레딧이 2배입니다. jev-latest 같은 다른 값은 Jev로 실행됩니다. |
| questions | map<string, Question> | ✓ | 타입이 지정된 질문의 맵입니다. 각 키는 직접 정하며, 일치하는 답변이 그 키 아래에 돌아옵니다. 키는 라벨일 뿐이며 모델에는 전달되지 않습니다. Choice에는 옵션이 최소 2개, Score에는 순서가 있는 단계가 최소 2개 필요합니다. |
| question_set_id | string (optional) | ✓ | 선택 사항이며 questions 대신 사용합니다. 플레이그라운드에서 저장한 질문 세트의 id이며, 본인의 세트만 사용할 수 있습니다. questions와 question_set_id 중 하나만 보내고 둘을 함께 보내지는 마세요. |
모든 질문 객체는 instructions(무엇을 판단하거나 평가할지)를 공통으로 가지며, 유형별 기준을 추가합니다. Choice는 옵션 맵, Score는 순서가 있는 단계 배열, Noul은 선택 사항인 true/false 설명입니다.
답변
질문마다 답변이 하나씩 있으며, 보낸 id를 키로 돌아옵니다. Choice와 Score 답변에는 확률 분포에서 도출한 신뢰도 값이 포함되고, Noul 답변은 확률만 반환합니다.
choice확률이 가장 높은 옵션, 각 옵션과 그 확률의 매핑, 그리고 신뢰도 값입니다.
score단계 전반에 걸친 확률 가중 값(단계 사이의 값이 나올 수 있음), 각 단계를 설명에 대응시키는 legend, 그리고 신뢰도입니다.
noul답이 예일 확률로, 0(아니요)에서 1(예) 사이입니다. Noul 답변에는 신뢰도가 없습니다.
모든 응답에는 요청의 토큰 사용량도 usage.input_tokens와 usage.output_tokens로 포함됩니다.
신뢰도
모델이 얼마나 확신하는지는 확률 분포의 모양이 알려 줍니다. 한 결과에 집중되어 있으면 확신이 높고, 여러 결과에 퍼져 있으면 확신이 낮습니다. 신뢰도 값은 그 모양을 0에서 1 사이의 숫자 하나로 요약하므로, 직접 계산하지 않고도 임계값을 정할 수 있습니다. 출발점으로 쓰기 좋은 패턴은 세 구간입니다.
자동으로 처리합니다. 모델이 명확하게 판단했으므로 사람이 개입하지 않고 진행해도 됩니다.
주의하며 진행합니다. 사용자에게 확인을 요청하거나, 검토 대상으로 표시하거나, 먼저 추가 정보를 수집하세요.
처리하지 않습니다. 사람에게 넘기거나, 추가 설명을 요청하거나, 다른 시스템으로 대체하세요.
경계를 어디에 둘지는 위험도에 따라 달라집니다. 되돌릴 수 없는 작업은 읽기 전용 작업보다 높은 임계값으로 막으세요.
전체 예시
호출 한 번, 질문 세 개, 응답 하나입니다. SDK는 필요 없습니다.
const res = await fetch("https://jevstation.com/api/v1/systemone", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.JEVSTATION_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
state: "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP.",
questions: {
department: {
type: "choice",
instructions: "Which team should handle this?",
criteria: {
billing: "Payments, invoicing, refunds",
technical: "Bugs, outages, integrations",
sales: "Pricing, upgrades, new accounts",
},
},
frustration: {
type: "score",
instructions: "How frustrated is the customer?",
criteria: ["Calm", "Frustrated", "Very angry"],
},
is_urgent: {
type: "noul",
instructions: "Does this convey urgency?",
},
},
}),
});
const { data } = await res.json();
data.answers.department.choice; // "billing"
data.answers.department.confidence; // 0.59
data.answers.frustration.score; // 1.04
data.answers.is_urgent.noul; // 0.99
data.credits.charged; // 1
data.credits.remaining; // 4,996curl -X POST https://jevstation.com/api/v1/systemone \
-H "Authorization: Bearer $JEVSTATION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Payouts have been failing for 3 days.",
"questions": {
"is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" }
}
}'참고 및 제한 사항
- 평가는 한 번의 왕복으로 끝납니다. Jev는 토큰 스트림이 아니라 답변을 반환하므로, 실행은 완전한 결과를 내거나 깔끔하게 실패합니다.
- 세트에 질문을 추가하면 입력 토큰은 더 쓰지만, 같은 state를 대상으로 병렬 평가되므로 지연 시간은 거의 늘지 않습니다.
- 실행할 때마다 크레딧이 차감됩니다. 표준 평가는 1크레딧이고, state가 8,000자를 넘거나 세트의 질문이 5개를 넘으면 3크레딧입니다. Clef는 둘 다 2배(2와 6)이며, Jev와 Clef-flash는 그렇지 않습니다. 잔액은 모델을 호출하기 전에 확인하고, 실패하거나 취소된 실행은 환불됩니다.
- 평가는 로그인한 사용자 범위로 한정되며, 한 계정이 다른 계정의 평가를 읽을 수는 없습니다.
- 프로바이더 자격 증명은 운영자가 관리자 설정에서 구성하며 브라우저에는 전달되지 않습니다.
- 429 또는 529가 나오면 지수 백오프로 재시도하세요. 클라이언트 SDK는 이미 이 처리를 해 줍니다.