Jev 는 TypeSafe 가 2026년 9월에 공개한 판단 전용 모델입니다. 글을 생성하지 않고, 우리가 준 보기 안에서 타입이 정해진 답과 확률만 돌려줍니다. 이 저장소는 샘플 쇼핑몰 '테디마켓'의 고객지원 에이전트를 예제로, 판단은 Jev 가 하고 문장은 LLM 이 쓰는 구조를 처음부터 끝까지 따라가 봅니다.

패스트캠퍼스 비법노트 주주총회 세미나 자료입니다. (테디노트)

• 도구 선택: Jev 가 choice 질문으로 도구 후보를 좁히고, LLM 은 남은 도구의 인자만 작성합니다.
• 가드레일: 인젝션, 욕설, 비방, 개인정보를 Jev 호출 한 번으로 판정합니다. 도구 결과에 숨은 지시문도 검사합니다.
• 위험 작업 게이트: 주문 취소와 환불은 실행 전에 "사용자가 직접 요청했는가"를 묻고, 애매하면 사람에게 넘깁니다.
• 오픈소스 패턴 4종: 메모리 압축, 도구 게이트와 출력 판정, 검색·모델 라우팅, 브라우저 액션 선택을 같은 방식으로 구현했습니다.
• 눈으로 보는 판단: 샘플 앱이 Jev 의 판단마다 확률 막대를 보여 줍니다.

준비물은 Python 3.12, uv, Node.js 20 이상, 그리고 OpenRouter API 키입니다. Jev 는 선불 크레딧이 있는 계정에서만 호출됩니다.

GitHub 저장소를 clone 받아 그 폴더에서 시작합니다. 아래 명령은 저장소를 내려받고, 파이썬 패키지를 설치하고, 환경 변수 파일을 만듭니다.

git clone https://github.com/teddylee777/fastcampus-jev.git
cd fastcampus-jev
uv sync
cp .env.example .env

.env 를 열어 OPENROUTER_API_KEY 에 발급받은 키를 넣습니다.

Git 이 없으면 저장소 페이지의 Code → Download ZIP 으로 받아 압축을 풀고, 그 폴더에서 uv sync 부터 이어 갑니다. 이미 clone 받은 저장소를 최신으로 맞추려면 git pull 뒤에 uv sync 를 다시 실행합니다.

터미널 두 개를 엽니다. 둘 다 저장소 루트에서 시작합니다.

터미널 1 은 백엔드(LangGraph 서버, http://localhost:2024)입니다.

uv run langgraph dev --no-browser

터미널 2 는 프론트엔드(React, http://localhost:5173)입니다.

cd frontend
npm install
npm run dev

브라우저에서 http://localhost:5173 을 엽니다. 왼쪽 메뉴에 탭 여섯 개가 보이면 준비가 끝난 것입니다. 고객지원 에이전트 탭 첫 화면의 예시 카드 "배송 조회"를 누르면 Jev 가 track_shipping 도구를 고르는 확률과 답변이 함께 나옵니다.

노트북으로 시작하려면 다음 명령을 씁니다. VS Code 에서는 .venv 커널을 선택합니다.

uv run python -m jupyterlab notebooks

값은 .env 에 두고 커밋하지 않습니다. .env 는 .gitignore 에 들어 있습니다.

왼쪽 메뉴에서 탭을 고릅니다.

패턴 탭은 예시를 고르고 글자를 고친 뒤 "Jev 에 묻기"를 누르면 됩니다. Jev 호출은 서버에서만 일어나고 API 키는 브라우저로 나가지 않습니다.

고객지원 에이전트 탭의 예시 카드로 일곱 가지 상황을 바로 확인할 수 있습니다.

주문 데이터는 서버 메모리에 있습니다. 환불 예시를 실행한 뒤 처음 상태로 되돌리려면 백엔드 서버를 다시 시작합니다.

고객지원 에이전트(support 그래프)는 jev_agent/agent.py 에서 Jev 미들웨어 세 개를 Deep Agent 에 붙여 만듭니다.

flowchart TD
    U["사용자 입력"] --> G1["JevGuardrailMiddleware<br/>Noul 4개를 호출 1회로 판정"]
    G1 -->|"인젝션, 비방·위협"| B1["차단하고 종료"]
    G1 -->|"욕설은 표시만, 개인정보는 가리고 계속"| S["JevToolSelectorMiddleware<br/>Choice: 어떤 도구인가"]
    S -->|"확신이 높으면 상위 2개 도구만, 낮으면 전체 도구를 노출"| L["LLM<br/>도구 인자 작성, 답변 생성"]
    L -->|"cancel_order, request_refund"| R["JevRiskGateMiddleware<br/>Noul: 사용자가 직접 요청했는가"]
    L -->|"그 밖의 도구"| T["도구 실행"]
    R -->|"probability 0.93 이상"| T
    R -->|"probability 0.15 이하"| B2["실행하지 않고 거절"]
    R -->|"그 사이"| H["interrupt: 사람이 승인 또는 거절"]
    H -->|"승인"| T
    H -->|"거절"| B2
    T --> G2["JevGuardrailMiddleware<br/>Noul: 결과에 지시문이 섞였는가"]
    G2 --> L

각 판단은 그래프 state 의 jev_decisions 에 쌓이고, 프론트엔드가 이 값을 읽어 확률 막대로 보여 줍니다.

가드레일의 범주별 기준과 조치는 jev_agent/guardrails.py 의 THRESHOLDS, ACTIONS 에 있습니다.

알아 둘 한계가 있습니다. 주소와 이름은 가리지 않습니다. Jev 는 개인정보가 "있다"까지만 답하고 위치를 알려 주지 못해, 실제로 가리는 일은 정규식이 맡기 때문입니다. 도구 결과의 개인정보와 스트리밍으로 나가는 최종 답변도 검사하지 않습니다. 가린 글은 LLM 에 전달되는 대화 기록에 적용되고, 가리기 전 원문은 그 시점의 체크포인트에 남습니다. 자세한 실험은 11번 노트북에 있습니다.

원리편: 시작하기 전에

기본편: 고객지원 에이전트에 Jev 붙이기

오픈소스편: 다른 프로젝트들은 Jev 를 어디에 쓰는가

블로그 글 Jev 활용 프로젝트 정리에 소개된 프로젝트의 방식을 참고해 이 저장소에 새로 작성했습니다.

NanoJev, open-alternative-jev, Reticle 은 10번 끝에서 소개만 합니다. 앞의 둘은 로컬 모델 가중치가 필요하고, Reticle 은 Jev 연동이 아직 계획 단계입니다.

노트북은 scripts/build_notebooks.py 에서 생성합니다. 내용을 고칠 때는 이 파일을 수정한 뒤 다시 생성하고 실행합니다.

uv run python scripts/build_notebooks.py   # 노트북 재생성 (출력은 지워짐)
uv run python scripts/run_notebooks.py     # 실제 API 로 전부 실행하고 출력 저장
uv run python scripts/run_notebooks.py 11  # 이름에 '11' 이 들어간 노트북만 실행
uv run python scripts/sync_notebook_markdown.py 11  # 설명 글만 고쳤을 때: 출력은 두고 마크다운만 반영

notebooks/        노트북 12개 (아래 목차)
jev_agent/        노트북과 서버가 함께 쓰는 공용 모듈
  jev.py            Jev Decisions API 클라이언트
  tools.py          샘플 쇼핑몰 '테디마켓' 도구 10개
  middleware.py     Jev 미들웨어 (도구 선택, 위험 게이트)와 판단 기록 도구
  guardrails.py     Jev 가드레일 미들웨어: 인젝션, 욕설, 비방, 개인정보를 호출 한 번으로 판정
  guardrail_compare.py  같은 글을 Jev 와 LLM 에 판정시켜 confidence 와 시간을 비교
  guardrail_evalset.py  가드레일 평가용 라벨 데이터 40건
  agent.py          Deep Agent 조립, LangGraph 서버 진입점
  evalset.py        도구 선택 평가용 라벨 데이터 30건
  patterns/         오픈소스에서 가져온 패턴 4종 (압축, 게이트, 라우팅, 브라우저 액션)
  pattern_graphs.py 패턴을 LangGraph 그래프로 감싸 앱 탭에 제공
frontend/         React(Vite) 앱: 채팅 탭 + 가드레일 비교 탭 + 패턴 탭 4개
  scripts/          화면 캡처와 구간별 시간 측정 스크립트 (Playwright)
langgraph.json    LangGraph 서버 설정 (그래프 6개)
scripts/          노트북 생성과 실행 스크립트
tests/            가짜 Jev, 가짜 LLM 으로 도는 단위 테스트
LICENSE           MIT

# 백엔드: 네트워크 없이 가짜 Jev 와 가짜 LLM 으로 분기 검증
uv run pytest tests/test_jev_agent.py tests/test_patterns.py -q --timeout=10

# 프론트엔드: 도구 호출 묶기, 마크다운 표시, 탭 전환
cd frontend
npx vitest run src/chat/timeline.test.ts src/App.test.tsx

두 서버를 띄운 상태에서는 헤드리스 브라우저로 각 탭을 열어 화면을 캡처하고 시간을 잴 수 있습니다. frontend 디렉터리에서 실행합니다.

npx playwright install chromium
node scripts/screenshots.mjs ./screenshots
node scripts/guardrail-shots.mjs ./screenshots   # 가드레일 비교 탭과 가드레일 채팅 예시
node scripts/timing.mjs                         # 채팅 한 턴의 구간별 시간 측정

• Jev 문서 (OpenRouter)
• Jev 튜토리얼 (OpenRouter)
• What Is Jev? (OpenRouter 블로그)
• Jev 활용 프로젝트 정리 (블로그)
• LangChain agent-chat-ui (채팅 화면 방식)
• LangChain guardrails 문서
• TypeSafe 공식 문서 · confidence 공식 · System One 개념
• Introducing System One Models & Jev (TypeSafe 블로그)
• TypeSafe SDK 안내
• Pydantic AI 의 TypeSafe 모델 문서 (제약 사항 정리)

MIT License. 전문은 LICENSE 에 있습니다.