운영에서는 타임아웃·응답 스키마 검증·비밀 제거 로깅을 추가한다. SDK를 쓴다면 Python typesafe-sdk 또는 JS @typesafe-ai/sdk를 사용하며 버전과 lockfile을 고정한다. 담당 팀 분류가 환불 실행 승인으로 이어져서는 안 된다.
05 / POLICY FLOWCHART
판정에서 행동으로: fail-closed 정책
그림 2. 모델 출력 이후의 정책 분기 · 하드 관문 실패는 모델 호출/자동 행동 전에 중단한다.
# 설명용 의사코드: 임계값은 평가셋에서 결정한 설정값
if not authorized or not input_valid:
return DENY
result = decision_provider.evaluate(state, questions)
if result.error or result.refused or not schema_valid(result):
return HOLD
if evidence_missing(result) or not scope_supported(result):
return ASK_FOR_MORE_EVIDENCE
if high_impact_action or needs_review(result, calibrated_policy):
return HUMAN_REVIEW
return ROUTE_TO_INTERNAL_QUEUE # 금전·권한 변경 없음
unknown / missing / error / refusal을 false 또는 0점으로 바꾸지 않는다.
자동 처리율을 높이려고 API 실패를 “통과”로 대체하지 않는다.
금전·계정 권한·채용 결과는 별도 승인·감사·되돌리기 경로를 둔다.
정책 결정 이유는 적용된 규칙 ID와 근거 참조로 설명한다. Jev의 내적 사고를 만들어내지 않는다.
06 / RETRIEVAL-AUGMENTED GENERATION
RAG: 검색과 생성 사이의 검토층
검색기는 후보를 찾고 Jev는 후보의 의미적 유용성을 판단한다. Jev는 검색 후보 밖의 문서를 발견하지 못한다. 문단 관련성과 “답할 만큼 충분한가”는 별도 기준이다.
그림 3. RAG evidence gate · 원문의 RAG 설명을 기반으로 한 권장 구조. [원문 관찰, S1]
단계
검증할 것
검색
Top-K recall, 테넌트/사용자 접근권한, 최신성, 중복 제거
문단 판정
질문과의 직접 관련성, 필요한 사실 포함, 잘린 문맥 여부
충분성
여러 질문 요소에 대한 coverage, 상충 근거, 날짜·단위 일치
생성 후
인용 문단이 실제 주장을 지지하는지, 추가된 무근거 주장 여부
07 / EVALUATION AND OBSERVABILITY
에이전트 평가: JevEval과 Opik
그림 4. 규칙 검사 → 의미 판정 → 회귀 · 규칙 검사에서 판별 가능한 사실을 모델에 재판정시키지 않는다. [S8]
JevEval은 Jev 답변을 코드로 결합하는 DeepEval의 지표다. Opik은 trace·데이터셋·실험 결과를 저장·비교하는 관측 플랫폼이다. 둘을 함께 쓸 수 있지만 둘 다 Jev 모델 자체는 아니다.
JevEval 동작
정확한 의미
일반 모드
Noul은 P(true), Score는 기대 레벨을 0~1로 정규화, Choice는 적용되는 선택지의 credit 가중 확률. 그 뒤 질문별 가중 평균.
N/A Choice
credit=None인 선택지 확률 합이 0.5 이상이면 해당 질문은 지표에서 제외. 누락된 테스트 근거를 임의로 N/A로 처리하면 안 됨.
strict 모드
Noul ≥0.5, Score 최빈 레벨이 최고 레벨, Choice 최빈 적용 옵션의 credit=1.0일 때 개별 통과. 적용 질문이 모두 통과해야 최종 1.
reason
답변을 바탕으로 코드가 만드는 설명. 생성형 rationale이나 모델 사고 과정이 아님.
trace 기반 평가에서 evaluation_params를 생략한 JevEval은 span tree를 사용하며 토큰·비용·프롬프트를 제외한다고 문서가 설명한다. 그런 필드를 보지 못하는 질문으로 비용 적정성을 평가하지 않는다.
08 / ADJACENT SYSTEMS
SQL 검토와 에이전트 메모리
그림 5. 데이터 분석 에이전트의 이중 검토 · 화살표는 처리 순서. 도식은 권장 설계이며 설치·배포된 시스템의 실측도가 아니다.
Beacon·JevGrep은 어디에 놓이는가?
도구
역할
Jev와의 연결
Beacon
harness 실행 기록·세션 간 지식 재사용
공식 opt-in memory 평가가 Jev를 호출한다. 일반 capture/hooks는 호출하지 않는다. [S12]
JevGrep
자연어 동작 설명에서 관련 코드·경로·발췌 탐색
검색 결과는 원본 파일을 읽을 출발점. 코드 변경·테스트 성공을 보장하지 않음.
Jev 판정 추가
기억의 재사용성·근거 충실도·검색 관련성 검토
커밋 SHA·원문 위치·유효기간을 함께 기록. 낡은 기억은 갱신·폐기.
Beacon은 beacon memory evaluations run --dry-run으로 전송 전 범위를 확인하도록 문서화한다. 실제 평가 명령은 제한·가림 처리한 trace를 외부로 보낼 수 있다. Jev는 교훈 문장을 생성하지 않고, 사람이 원본 trace를 검토해 승인한다. Beacon Cloud는 별도이며 현재 문서는 evaluator가 없다고 설명한다. [S12] 외부 사례의 실행 환경·영상 전체 재현은 이 가이드의 검증 범위에 포함하지 않는다.
09 / MULTIMODAL BOUNDARIES
이미지·PDF·영상: 입력 경로를 분리한다
그림 6. 추출 경로와 이미지 직접 경로 · 텍스트 변환과 이미지 자체 판정은 동등한 검증이 아니다.
Box는 부재에도 항상 좌표를 반환한다. not-found 결과가 없으므로 존재 여부 Noul을 같은 요청에 넣고 존재 확률이 낮으면 Box를 무시한다. Box에는 criteria가 없다. 좌표·confidence 주의는 p20 참고.
PDF는 파싱/OCR, 영상은 전사·프레임 추출 경로를 구분한다. OCR 텍스트 검증은 이미지 전체 검증이 아니다. OpenRouter 형식도 TypeSafe와 다르다. 기존 오프라인 starter는 텍스트 전용이며 assets·Box를 지원하지 않는다. 별도 연구 모델과 입력 검증은 36–43쪽에서 구분한다.
10 / HIGH-IMPACT REVIEW
채용·포트폴리오 검토
그림 7. 채용 포트폴리오 검토 지원 · 화살표는 처리 순서. 도식은 권장 설계이며 설치·배포된 시스템의 실측도가 아니다.
다음 도식은 특정 제품의 실측 사례가 아닌 권장 설계다. 권장 통합의 결과물은 자동 합격/탈락이 아니라 검토자가 확인할 evidence packet이다.
질문·기록
권장 내용
직무 기준
“이 제출물에 SQL 성능 분석의 근거가 있는가?”처럼 직무 관련 관찰로 한정.
저자 기여
팀 성과와 개인 역할을 구분. 저자 확인 상태를 unknown으로 남길 수 있음.
자료 누락
비공개 링크·깨진 URL·OCR 실패는 역량 없음이 아니라 missing evidence.
공정성
보호 특성·대리 변수에 의한 평가를 피하고 일관된 rubric과 사람 재검토를 제공.
데이터 권리
제출·동의 범위, 목적 제한, 최소 수집, 접근통제·보관·삭제·이의 제기 절차.
11 / REPOSITORY MAP
생태계: 모델·도구·관측을 구분한다
프로젝트
위치와 역할
도입 시 확인
AnyJev [R1]
공개 causal LLM으로 제한된 결정을 읽는 연구·라이브러리. training-free 및 Tacit 경로.
TypeSafe 공식 구현 아님. 모델 weights·라이선스·서빙·보정 별도. BANKING77-20 수치는 저자 실험.
DeepEval / JevEval [S8,R2]
평가 지표·테스트·trajectory 프레임워크.
질문 state·가중치·N/A·strict 의미 고정. Jev 호출 비용 별도.
jev-as-judge [R3]
합성 trace 10건에 Noul 3개+Score 1개를 묶어 평가하는 Opik custom adapter 예제.
demo 확률은 수작업이며 저자도 실제 인증 API/업로드 미실행을 명시. 환불·자동 escalation 기능 없음.
Opik [R4]
trace·데이터셋·실험·평가 관측 플랫폼.
평가 모델이 아님. trace에 비밀·개인정보가 저장되지 않도록 필터.
dzhng/jevgrep [R5]
자연어 기반 코드 탐색 CLI.
8/10은 검색 정확도가 아니라 SWE-bench 과제 해결 수. 소스 외부 전송 주의. 동명 저장소와 구별.
agent-beacon [R6]
에이전트 세션 기록·메모리·검토된 지식 재사용 계층.
Jev 모델은 아니지만 명시적 memory 평가 명령에 Jev 통합이 있다. dry-run→평가→사람 승인. [S12]
evals-with-deepeval-tute [R7]
구조적 검사·답변 비교·Jev judge를 다루는 튜토리얼.
예제 학습용. 제품 수준 접근권한·운영 게이트는 별도.
Unsloth 가이드 [R8]
LoRA 기반 자체 결정 모델 훈련·보정 실험.
상용 Jev 자체를 미세조정하는 경로 아님. 학습·holdout·서빙을 직접 관리.
저장소 설명은 저자 주장과 독립 검증을 구분한다. upstream 설치·실행·전체 보안 감사·벤치마크 재현은 수행하지 않았다. VideoJev·MJev-Spatial·Jeva의 논문·실제 코드 대조와 분석은 36–43쪽에 추가했다.
12 / PROVIDER ABSTRACTION
공급자 교체는 adapter와 재평가로
그림 8. 권장 DecisionProvider 경계 · 공통 타입은 유지하되 공급자별 semantics와 capability를 지우지 않는다.
항목
TypeSafe Jev
OpenAI Decisions
입력 / 질문
state + ID별 questions 맵
input + name이 있는 questions 배열
타입
noul / choice / score
predicate / choice / score
응답
ID별 answers 맵
name을 포함한 answers 배열, refusal 처리
모델 예
jev-1.14.0 (직접 API)
gpt-6-luna
입력 단가
입력 $0.042 / 1M tokens
입력 $0.10 / 1M tokens
미디어
기본 Text + 별도 이미지 경로
텍스트·이미지 문서화
가격은 조회 시점의 공개 기본 단가이며 계약·지역 처리·장문·중개 비용은 별도다. OpenAI 문서는 Decisions를 public beta로 표시한다. [S3, S11]
13 / EVALUATION PLAN
평가·확률 보정·비용
정확도 하나로 운영을 결정하지 않는다. 실제 업무 표본·한국어·애매한 사례·정보 누락·공격 입력을 포함한 독립 평가셋이 필요하다. 동일 state·동일 라벨·동일 작업 목적에서만 공급자를 비교한다.
축
기록할 지표
판정에 쓰는 방법
품질
정확도, macro-F1, 클래스별 precision/recall, 오탐·미탐
비용이 큰 오류 유형별로 허용 한도 설정
보정
Brier score, ECE, reliability curve
출력 확률과 실제 빈도가 맞는지 확인. 빈 크기·표본 불확실성 명시.
선택적 자동화
자동 처리 coverage, 자동 구간 오류율, 검토량
불확실 사례를 보류해도 전체 오류를 숨기지 않음.
실행 성능
p50/p95 지연, timeout/429/오류율, retry 포함 비용
네트워크·동시성·컨텍스트 길이를 함께 기록
분포 변화
언어·입력 길이·카테고리·모델 버전별 품질
질문/선택지/버전 변경 시 동일 회귀셋 재실행
데이터를 세 구간으로 분리한다
개발셋으로 질문을 다듬고, 검증·보정셋으로 임계값을 선택하며, 고정 테스트셋으로 최종 판정한다. 동일 문서의 중복·파생 사례가 분리 구간을 넘지 않게 하고, 실제 빈도와 어려운 사례의 평가를 각각 보고한다.
설명용 입력 비용 계산 — 성능 측정값 아님
가정: 10,000건 × 요청당 실제 과금 입력 1,000 tokens
총 입력 = 10,000,000 tokens
TypeSafe 기본 단가: 10 × $0.042 = $0.42
OpenAI 기본 단가: 10 × $0.10 = $1.00
OCR·검색·이미지 토큰·질문 길이·재시도·후속 LLM·인간 검토·관측 저장 비용을 제외한 산술 예다. 실제 비용은 각 공급자의 usage와 청구 데이터를 사용한다. 질문 배치는 state 반복을 줄일 수 있지만 추가 질문은 무료가 아니다.
14 / RELEASE AND OPERATIONS
운영: shadow부터 시작한다
그림 9. 도입과 운영의 단계별 관문 · 화살표는 처리 순서. 도식은 권장 설계이며 설치·배포된 시스템의 실측도가 아니다.
영역
권장 기본값
오류·재시도
400/401 등 설정·인증 오류는 무한 재시도 금지. 429/5xx/timeout은 제한된 backoff+jitter, Retry-After 존중. 실패는 검토/보류.
이중 실행
추론 retry와 후속 액션을 분리. 액션에 idempotency key·중복 방지·감사 ID 적용.
버전 관리
provider/model, questions/rubric, threshold/policy, parser/schema를 함께 버전 관리.
감사 로그
근거 참조/해시·질문 ID/버전·모델 버전·원본 판정·정책 결과·검토자/행동. 원문은 제한된 저장소에 보관.
캐시
tenant/권한 범위·state hash·질문·모델 버전으로 분리. 원본 판정과 정책 결과를 분리해 threshold 변경 시 재해석 가능하게.
롤백
평가된 모델·질문·정책 버전을 묶어 되돌리고 자동 처리를 끌 수 있는 kill switch 확보.
DEEP DIVE / S1 · S2 · S7
TypeSafe: HTTP와 SDK의 계약을 구분한다
공식 API 리디렉션과 OpenAPI를 대조했다. SDK 예제에서 model을 생략할 수 있어도 raw HTTP의 필수 필드는 model·state·questions다. 질문은 공유 state를 독립적으로 평가하며, 앞 질문의 답이 필요한 후행 질문은 별도 요청으로 만든다.
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <server-side secret>
Content-Type: application/json
model: exact model ID
state: string | object | array
questions: {question_id: {type, instructions?, criteria?}}
항목
공식 계약 / 실무 정책
State
최상위 null·number·boolean은 요청 state 타입이 아니다. 개인정보를 최소화한 string/object/array를 전달한다.
Choice
criteria는 옵션→설명 map. OpenAPI는 1~255개를 허용하지만 분류/로컬 confidence 계산에는 2개 이상을 요구한다.
Score
criteria는 낮은→높은 배열. OpenAPI는 1~10개지만 의미 있는 척도·정규화에는 2~10개를 요구한다.
Instructions
스키마상 선택이며 문자열 외 구조화 값도 가능하다. 스킬/스타터는 의미가 명확한 문자열을 요구하는 더 좁은 정책이다.
Response
model·answers·usage를 검증한다. Score 확률 키는 HTTP에서 문자열, Python SDK에서는 정수 변환 가능.
input_image.image_url. 공개 HTTP(S) 허용 여부가 가이드와 API reference 사이에 달라 공통 예제는 data URL로 제한.
2026-10-21 한정 갱신 · S13 Images · S14 Box · S3 Models. 이미지·Box·별칭만 확인했으며 전체 보고서를 재검증한 것은 아니다. 실제 API 호출은 하지 않았다.
TypeSafe 버전
이미지 / Box
jev-1.13.0
이미지 지원 / Box 미지원
jev-1.14.0
이미지·Box 지원
과거 OpenAPI의 nullable confidence를 현행 보장으로 옮기지 않는다. 향후 parser는 고정한 계약에서 누락·null을 별도 검증한다. 공급자별 크기·형식·잘림 조건은 도입 직전 재확인한다.
내부 adapter가 보존할 것
이유
REFUSED / ERROR / NO_APPLICABLE
false·0점·정상 N/A로 뭉개면 잘못된 승격이 발생한다.
Reported vs estimated cost
OpenRouter usage.cost와 OpenAI token usage는 다르다. USD 누락을 0원으로 만들지 않는다.
Raw vs derived confidence
OpenAI와 TypeSafe가 같은 confidence 공식을 쓴다는 근거는 확인하지 못했다.
Truncation / modality
특정 중개 모델의 무오류 절단이나 다른 모델의 audio/video 지원을 Jev 기능으로 일반화하지 않는다.
DEEP DIVE / S8 · R2 · R4
DeepEval·Opik: 점수 1도 실패할 수 있다
JevEval은 애매한 의미를 Jev로 평가하고 점수 조합은 일반 코드에서 계산한다. DeepEval 자체의 pass와 애플리케이션의 배포 허용은 별개다.
동작
검증/구현 규칙
N/A mass
credit=None인 Choice 확률 합이 0.5 이상이면 제외. 미만이면 적용 옵션 확률을 재정규화.
전부 N/A
일반·strict 모두 score=1이다. applicable_count=0이면 별도 NO_APPLICABLE/PENDING으로 보내고 승격하지 않는다.
Strict
Noul≥0.5, Score 최빈 레벨=최상위, Choice 최빈 적용 옵션 credit=1. 원확률 100%가 아니다.
Reason / confidence
reason은 코드가 만든 표시문이며 사고과정이 아니다. metric confidence의 최솟값에는 N/A 항목도 포함된다.
관찰 범위
evaluation_params 밖의 사실은 알 수 없다. trajectory에서 제거한 비용·토큰·prompt를 평가할 수 없다.
Opik에는 TypeSafe SDK용 track_typesafe 통합이 있다. 직접 HTTP는 별도 span 연결이 필요하다. OpenAI Decisions wrapper는 고정 공개 소스·mock 테스트에서 확인했으며 배포 release 지원은 별도로 확인해야 한다. 단순 provider label 변경은 schema 변환이 아니다.
DEEP DIVE / S12 · R6 · R7
Beacon·평가 튜토리얼: 기록에서 검토된 지식으로
Beacon 단계
실제 의미
Capture / dry-run
일반 hook과 dry-run은 evaluator를 호출하지 않는다. 기록 수집과 Jev 평가는 별도.
Explicit evaluation
beacon memory evaluations run이 TypeSafe를 호출한다. 기본 latest alias는 고정 버전이 아니다.
Candidate
task_success≥0.50 및 세 확률 평균≥0.60은 후보 생성 기준이다. 교훈의 진실성·채택 승인이 아니다.
Approval
점수에서 교훈이 자동 생성되지 않는다. 원trace를 읽어 작성하고 사람 승인·skill 설치 승인으로 분리한다.
Local vs Cloud
로컬 memory.db/read-only MCP는 프로젝트 범위. Cloud에는 evaluator가 없고 local과 자동 복제되지 않는다. wizard 선택값을 확인한다.
DeepEval 튜토리얼은 구조 검사→문구 coverage→Jev 의미 판정을 순차 실행한다. 동일 응답/공유 judge 요청을 재사용하지만 각각의 필수 질문은 독립적인 AND 관문으로 평가한다.
튜토리얼 도입 함정
바로 적용할 규칙
문서 태그 없음
tutorial-01~09를 요구하지만 공개 demo tags가 비어 있다. 검토한 최종 main SHA와 제한을 명시한다.
Private 내부 API
_system_one_outcomes에 의존한다. DeepEval 업그레이드 전에 contract fixture를 재검증한다.
검사 비용과 전체 비용
구조/fuzzy metric이 무료여도 live agent가 먼저 호출되면 비용이 든다. mock agent여도 Jev judge는 호출될 수 있다.
Fail-fast 순서
query별 순차 실행 전제. xdist/random ordering을 추가하기 전에 계층 상태 전이를 재설계한다.
DEEP DIVE / R1 · R3 · R5
AnyJev·JevGrep·Opik 예제: 채택할 부분만
프로젝트
이번 심층 조회로 확인한 사항
AnyJev 0.3.0
raw/L0와 Tacit 경로. L1/L2는 제거되어 이전 버전 안내와 다르다. L0는 옵션 회전·prior 보정이지 정답 라벨 기반 calibration이 아니다.
Tacit adaptive
추가 추론 cap은 예산 제한이다. cap에 닿으면 저확신 답을 사람에게 보내는 것이 아니라 기존 one-forward 답을 유지한다.
AnyJev benchmark
BANKING77 20-way 300건 raw→L0 accuracy 0.747→0.803, ECE 0.240→0.184. 저자 보고이며 업무 위험 보장이 아니다.
jev-as-judge
합성 trace 10건·Noul 3+Score 1. demo, live judge, Opik experiment는 비용/외부쓰기 경로가 다르다.
JevGrep
eligible source를 외부 provider로 전송한다. ignore/secret heuristic은 완전한 제거 보장이 아니다. doctor도 synthetic live 요청이다.
재사용 가치: state allowlist, strict response validation, 오류와 품질 실패 구분, rubric version, audit. 별도 구현 필요: 사람 검토 큐, 승인 저장소, 운영 권한, 전송 정책, 실제 품질 보정. jev-as-judge는 명시 라이선스를 확인하지 못했으므로 무조건 코드를 복사 배포하지 않는다.
DEEP DIVE / R8 · NOTEBOOK
Unsloth·Colab: 자체 모델 학습의 재현 조건
이 경로는 TypeSafe Jev 가중치를 로컬에서 학습하는 것이 아니라, 별도 causal model에 decision head/LoRA를 적용하는 경로다. 모델 확보·GPU·학습·서빙 비용과 데이터 권리는 직접 관리한다.
한국어·모순·경계·누락·out-of-scope의 실제 라벨 데이터는 parser unit test와 별도 평가.
Brier = mean((p−y)²). ECE는 binning과 기준(positive-event probability 또는 predicted-label confidence)을 명시해야 비교 가능하다. 순서형 Score는 평균점수만 보지 말고 분포와 업무상 오류 비용을 함께 본다.
승격 단계
증거가 없으면 다음 단계로 가지 않는다
Offline
합성 fixture의 parser/policy 테스트 통과. 실제 provider 호환·모델 품질을 의미하지 않는다.
Live evaluation
전송 데이터·권리·보관·provider·요청/지출 cap에 별도 승인.
Shadow
사용자 행동을 바꾸지 않고 검토량·오탐/미탐·지연·비용 실측.
Limited rollout
독립 QA/기존 리뷰 승인, 제한 범위·kill switch·버전 번들 rollback 확보.
DEEP DIVE / REUSABLE SKILL
스킬로 사용하기: 설계부터 오프라인 구현까지
공개 jev-decisions 스킬을 설치해 자신의 프로젝트에 적용한다. 기존 프로젝트의 명령·설정·승인 절차는 유지한다. 스킬 자체는 API를 호출하는 서비스가 아니라 작업할 때 읽는 실행 절차와 재사용 파일이다.
jev-decisions로 고객 문의 라우팅을 설계해. API 호출 없이.
jev-decisions로 RAG 판정 adapter와 테스트를 구현해.
jev-decisions로 에이전트 trace 평가 질문과 회귀 테스트를 만들어.
구성
어떻게 사용하는가
설계 템플릿
목적·위험·권한·evidence·provider·버전·지출·리뷰 관문을 먼저 채운다.
Question registry
Noul·Choice·Score의 예제를 업무 기준으로 교체한다. 예제 회사명/threshold를 제품에 고정하지 않는다.
오프라인 starter
표준 라이브러리만 사용. 질문 정의 검증·내부 정규화 응답 검증·정책 추천을 로컬에서 테스트한다.
문서 references
TypeSafe 계약, provider 통합, 구현 플레이북, 오프라인 starter 설명을 필요할 때만 읽는다.
평가 기록
미측정 값은 null/미측정으로 유지한다. 합성 결과를 실험 결과로 채우지 않는다.
APPENDIX A / PUBLIC EDITION
공개판 범위와 안전한 재사용
이 배포판은 공개 기술 문서를 바탕으로 작성한 독립 커뮤니티 가이드다. TypeSafe 및 언급된 공급자의 공식 제품·인증 플러그인이 아니다.
포함한 것
타입이 있는 질문 설계, 확률 해석, 실패 처리, 평가와 단계적 도입 절차.
공개 문서·저장소 링크와 근거의 한계.
합성 예제로만 실행하는 오프라인 도구·테스트와 재사용 템플릿.
이 HTML 원본, PDF 생성 도구 및 직접 만든 SVG 도식.
포함하지 않은 것
개인 대화, 내부 프로젝트·고객·업무 데이터, 비공개 저장소 이력.
계정 설정, API 키, 토큰, 인증 쿠키, 자동 설치 hooks.
타사 모델 가중치, 자동 유료 호출(동봉 client는 --live 명시 때만 호출), 자동 외부 전송이나 실제 실행 권한.
워크플로에 적용하는 순서
스킬을 설치하고 낮은 위험의 의사결정 하나를 고른다.
도메인·권한·증거·질문·정책을 템플릿으로 정의한다.
오프라인 테스트로 잘못된 입력과 보류 경로를 검증한다.
별도 승인된 데이터와 예산으로 live adapter를 구현·평가한다.
사람 검토를 유지한 shadow 단계부터 점진적으로 도입한다.
APPENDIX B / ANNOTATED REFERENCES
링크별 독해 기록 1
아래는 공개 자료별 핵심 내용과 한계다. 공개 출처 목록은 sources.json에 제공한다. 문서 검토는 모델 실행·미디어 검증을 뜻하지 않는다.
공개 출처를 바탕으로 정리한 기술 가이드다. 출처와 내용은 작성 시점 기준이며, 공급자의 현재 계약·모델·가격·한도는 도입 직전에 재확인해야 한다. 실제 API 호출·성능 벤치마크·영상 전체 재현 결과를 제공하지 않는다.
확인한 것
확인하지 않은 것
문서·bounded source·OpenAPI 독해
유료 Jev/OpenAI 추론, 실제 계정 API 호환
소셜 본문·Colab 코드 셀
소셜 미디어 전체 재생, notebook/GPU 학습
오프라인 starter parser/policy 테스트
실제 데이터 정확도·확률 보정·운영 threshold
리포트 HTML/PDF 렌더링과 레이아웃 QA
서비스 배포·실제 티켓 라우팅·결제·채용 판정
첫 적용은 정답 공간이 작고 근거가 명확하며 되돌릴 수 있는 내부 라우팅이다. 설계 템플릿을 채우고 질문·adapter·실패 테스트를 만든 뒤, 승인된 실제 라벨 데이터로 provider별 threshold를 평가한다. Shadow 단계에서는 실제 행동을 바꾸지 않는다.
RESEARCH EXTENSION / OVERVIEW
영상·공간·null-aware 판정으로 확장하기
이 장은 VideoJev, MJev-Spatial, Jeva의 논문 본문·부록과 공개 구현을 대조한 요약·분석이다. 세 프로젝트는 TypeSafe 서비스의 추가 모델 ID가 아니다. 공통점은 자유로운 답변 생성보다 주어진 후보 공간에서 판정하는 구조에 있고, 입력·학습·추론·출력 계약은 서로 다르다.
43쪽의 원문·코드 링크와 오프라인 도구로 이어진다. 세 모델을 조합할 수도 있지만 이 패키지는 통합된 멀티모달 실행 backend를 제공하지 않는다.
VIDEOJEV / ARCHITECTURE
VideoJev: 생성 대신 시간·선택지 판정
한 줄 요약: 영상과 질문을 처리한 뒤, 시간 후보 또는 제시된 답변 후보를 공유 cosine head로 점수화한다. 영상 이해 연구지만 임의의 대화 답변 생성·오디오 이해·도구 조작까지 자동 제공하는 것은 아니다.
고정 소스에서 추적한 개념 흐름. 모델을 실행해 관찰한 결과가 아니다. [R9]
논문 아이디어
두 프레임으로 이루어진 temporal group을 시간 셀로 보고, 질문의 사건과 관련된 셀을 판정한다. 추론은 threshold-adjusted logits에 maximum-sum decoding을 적용해 비어 있지 않은 연속 구간을 고른다. 선택형 QA는 사용자가 준 옵션 안에서 답을 고른다.
공개 구현에서 확인한 계약
predict_video는 영상 준비·vision encode 후 predict_features로 이어진다.
질문은 id/task/query, 선택형이면 options를 사용한다. 우리 검증기는 질문 목록만 검사하며 영상 파일을 받거나 열지 않는다.
Joint 묶음의 뒤 질문은 앞 질문 텍스트를 볼 수 있다. 질문 독립성이 필요한 평가에서는 이 조건을 통제한다.
근거: 논문 §2·관련 부록, 공개 HF processing/modeling/temporal 경로. 상세 파일·함수·행 번호는 VideoJev reference.
VIDEOJEV / CRITICAL ANALYSIS
VideoJev: 캐시를 구분해야 도입을 판단한다
항목
논문·설명과 실제 코드의 관계
영상 특징 재사용
공개 HF API에서 vision features를 재사용한다. 매 질문 묶음의 언어 forward까지 생략하는 뜻은 아니다.
Prefix cache
공개 HF forward는 use_cache=False. 별도 연구 코드에는 실제 prefix-cache 경로가 있다. 두 경로를 같은 기능으로 설명하지 않는다.
공개 custom 4B 설정의 192K/ZeRO-3와 논문 경로의 144K/ZeRO-2가 다르다. 설정 차이는 곧 결과 오류라는 뜻은 아니지만 동일 재현의 증거도 아니다.
어디에 유용한가 — 권장 활용 설계
긴 영상에서 사람이 검토할 사건 후보 구간을 좁히거나, 동일 영상에 대한 정해진 질문 묶음을 평가하는 보조 도구가 후보가 된다. 예를 들어 “물체가 프레임에 들어오는 구간”을 찾고, 실제 존재 여부와 최종 구간을 사람이 확인하는 방식이다.
실행 전 평가할 것
사건 없음·짧은 사건·작은 물체·반복 사건·모호한 선택지를 포함한다.
Temporal IoU와 선택형 정확도뿐 아니라 false positive·검토율을 기록한다.
프레임 sampling·decode·vision encode·언어 forward·후처리의 지연을 구분한다.
옵션 순서·질문 순서·Joint와 단독 호출·실제 cache 경로를 따로 비교한다.
읽은 범위: 본문 §§1–6, 표·참고문헌, Appendix A/B. 시각 확인 범위와 미재현 지표는 상세 reference에 별도 표시. [R9]
MJEV-SPATIAL / ARCHITECTURE
MJev-Spatial: 공간 판단을 후보 선택으로
한 줄 요약: 이미지·질문에서 공간 관계, 수치 또는 위치를 판단한다. 기존 attention의 Q/K 표현으로 후보를 점수화하고, 수치·좌표는 coarse-to-fine 단계로 좁혀 간다.
단계마다 후보를 좁히는 개념도. 한 단계의 forward와 전체 요청의 forward 수는 다르다. [R10]
작업
입력·출력의 해석
Choice
공간 관계 등 주어진 옵션을 비교한다. 안정적인 option ID와 텍스트를 구분한다.
Scalar
m·count·deg를 구분한다. 단위가 다른 MAE를 하나의 수치로 합치지 않는다.
Point
공개 기본 경로는 단일 normalized_xy point. 원본 이미지의 정규화 좌표이며 화면·실세계 좌표와 자동 호환되지 않는다.
코드에서 확인한 흐름
CLI의 입력 정규화 → image processor → native Q/K scoring → scalar codebook 또는 point refinement → decode. 학습의 teacher-forced 단계와 추론에서 예측한 단계는 구분해야 한다. 앞 단계 오류가 후속 crop·후보 선택으로 전달될 수 있다.
본문 §§1–5·Appendix A–H와 실제 입력·Q/K·decode·학습 경로를 대조했다. 상세 reference.
MJEV-SPATIAL / RELEASE GATES
MJev-Spatial: 설계 채택과 실행 승격은 별개
확인한 문제
정확한 범위·해석
Dependency 충돌
선언된 inference/train extras의 transformers==5.17.0는 Hub >=1.5,<2를 요구하지만 저장소는 Hub <1을 요구한다. 모든 설치 방법이 실패한다고 일반화하지 않는다.
Checkpoint 저장
documented train 경로가 output directory를 만들고 save 함수가 같은 경로를 다시 exist_ok=False로 생성한다.
공개 API export
top-level JevSpatial export가 존재하지 않는 inference 모듈을 참조한다. 다른 직접 진입점과는 구분한다.
Checkpoint 대응
공개 metadata와 논문 최종 학습 설정의 대응이 불명확하다. metadata만으로 가중치 오염이나 논문 결과의 부정을 단정할 수 없다.
평가 범위
공개 기본 evaluator의 accuracy·MAE·point distance는 논문의 mask·multi-point·macro benchmark 전체 harness가 아니다.
도입 순서 — 권장 설계
고정 revision에서 의존성·진입점·저장 lifecycle을 별도 scope로 수정·검증한다.
체크포인트의 학습·평가 데이터 계보와 코드·논문 대응을 확인한다.
라이선스·backbone 조건·환경·메모리를 기록하고 작은 실제 추론 smoke를 실행한다.
독립 holdout으로 단위별 수치 오차, point 위치 오차, 대상 부재·가림·복잡한 장면을 평가한다.
활용 후보는 이미지의 위치·관계를 사람이 재검토하는 보조 분석이다. 실시간 조작·정밀 측정·자동 클릭 등은 별도 교정과 권한 검증 없이 연결하지 않는다. [R10]
JEVA / DECISION ARCHITECTURE
Jeva: 후보 경쟁과 후보 부재를 분리한다
한 줄 요약: 요청과 옵션을 따로 인코딩하고, 고정된 option memory를 읽어 요청 상태를 갱신한다. “후보 중 무엇이 좋은가”와 “이 후보 집합에 답이 있는가”를 서로 다른 양으로 표현한다.
옵션 재사용이 가능한 구조와 결과 해석의 분리. 캐시 효율·품질을 로컬에서 재현한 것은 아니다. [R11]
양
의미
조건부 확률 q
제시된 후보 안에서의 경쟁 분포. 공개 candidate_probabilities·conditional_probabilities는 이 값을 가리킨다.
Joint mass p
p_i = (1 - p_null) × q_i. 후보 coverage를 반영한 질량이다. 조건부 q와 섞지 않는다.
Null
적절한 답이 후보 집합에 없다는 결과. 일반적인 불확실성·정답률·검토 승인과 같지 않다.
Typed value
Noul은 positive option의 조건부 질량, Score는 명시한 values와 조건부 q로 계산한다. 보편적인 고정 점수 척도가 아니다.
실제 API 경계
우리 검증기는 raw predict의 state/question/decision_type/options/allow_null 형태를 제한적으로 검사한다. Score는 values, Noul은 positive_index를 명시한다. TypeSafe 요청 JSON이나 평가 label 파일을 그대로 받는 API가 아니다.
JEVA / CRITICAL ANALYSIS
Jeva: 아키텍처의 장점과 재현의 빈틈
왜 이 구조가 의미 있는가
옵션 표현을 요청과 분리하면 반복되는 후보 집합을 재사용할 수 있고, 후보 순서 변화에 대한 평가도 명시적으로 설계할 수 있다. coverage를 따로 두면 후보가 모두 부적절한 상황을 단순한 “가장 덜 나쁜 답”과 구분할 여지가 생긴다. 다만 이는 구조적 설계 의도이며 운영 품질·보정·캐시 이득의 실측 보장은 아니다.
대조 항목
발견한 차이와 적용 규칙
후보 수
raw 및 typed Choice/Score의 공통 inference validator는 singleton을 허용한다. 논문·evaluator의 최소 두 후보 조건과 구분하고 우리 검사에서는 두 개 이상을 요구한다.
Permutation 평가
문서의 any-flip/all-order/TV와 공개 summary의 changed-variant agreement·maximum drift는 같은 지표가 아니다. 필요한 지표를 별도 계산한다.
학습
공개 trainer는 논문의 auxiliary loss·단계별 curriculum·별도 optimizer parameter groups를 모두 재현하지 않는다.
Cache 표본
본문·그림의 50과 부록의 46이 다르다. 원인이나 정답 denominator를 추정하지 않고 불일치를 기록한다.
배포 라이선스
코드·가중치·backbone 조건을 각각 확인한다. 기본 download/export 경로만으로 모든 LICENSE·NOTICE가 보존된다고 가정하지 않는다.
권장 평가 시나리오
정답 후보 있음·없음, 비슷한 오답 추가, 후보 순서 변경을 분리한다.
안정적 option ID로 정렬한 뒤 확률 변화를 비교한다. 텍스트 중복을 임의 제거하지 않는다.
같은 모델·tokenizer·옵션·설정에서 cache/no-cache 품질과 실제 지연을 비교한다.
null false accept/reject와 review 정책을 평가한다. null을 곧바로 승인·거절 명령으로 쓰지 않는다.
전체 본문·Appendix A.1–C.7과 typed/raw API·평가·학습 경로를 대조. 상세 reference. [R11]
RESEARCH EXTENSION / ADOPTION & SOURCES
사용 순서, 출처, 남겨 둔 검증
스킬에서 적용하기
공개 플러그인은 /jev:jev-decisions에 작업을 자연어로 요청한다. 이 reference가 연결된 로컬 /jev에서도 같은 설계·검증 흐름을 사용할 수 있다. 명령 이름만으로 모델이 설치되거나 실행되는 것은 아니다.
/jev:jev-decisions VideoJev로 사건 구간 평가를 설계하고 합성 질문을 검증해. 추론은 하지 마.
/jev:jev-decisions MJev-Spatial의 단일 point 계약과 실행 차단 사항을 확인해.
/jev:jev-decisions Jeva의 null·조건부 확률을 분리한 평가를 설계해.
저장소 루트에서 stdlib 도구와 합성 데모를 실행한다.
python3 plugins/jev/skills/jev-decisions/scripts/research_kit.py plan --task video-grounding
python3 examples/research_demo.py