Jev 기반 내담자 감정 상태와 응답 일관성 개선

docs/guides/local-development.md

@@ -192,6 +192,13 @@ npm install
 | `ENGINE_MODE` | `claude_cli` | `claude_cli` / `claude_api` / `codex_cli` / `agy_cli` 공급자 라우팅. 실제 운영 변경은 관리자 드롭다운이 DB에 저장 |
 | `ENGINE_GATEWAY_SHARED_SECRET` | 빈 값 | 선택 인증. NAS/원격 preview에서는 API와 gateway에 동일한 32자 이상 비-placeholder 값을 설정. 빈 값은 기존 로컬 9099 호환 |
 | `VIGNETTE_LIVE_CLIENT_PROVIDER` | `claude_cli` | 실시간 내담자 AI 전용 lane. 관리자에서 선택한 evaluator/review 공급자와 분리해 회기별 Claude 상주 세션을 재사용 |
+| `VIGNETTE_CLIENT_AFFECT_PROVIDER` | `legacy` | 내담자 감정 판단 경로. 기본 `legacy`는 기존 운영 동작을 유지하며, `jev`는 아래 Jev transport 설정을 사용한다 |
+| `VIGNETTE_JEV_PROVIDER` | `openrouter` | Jev transport. 기본 `openrouter`는 Alpha Decisions endpoint를 쓰며, 직접 TypeSafe는 `typesafe`를 명시했을 때만 지원한다. 두 경로는 서로 fallback하지 않는다 |
+| `OPENROUTER_API_KEY` | 설정된 비밀값 | 기본 OpenRouter Jev credential. 원문을 명령·로그·문서에 넣지 않는다 |
+| `TYPESAFE_API_KEY` | 설정된 비밀값 | `VIGNETTE_JEV_PROVIDER=typesafe`일 때만 쓰는 직접 TypeSafe credential. 원문을 명령·로그·문서에 넣지 않는다 |
+| `VIGNETTE_JEV_MODEL` | `~typesafe/jev-latest` | 기본 OpenRouter Jev 판단 모델 |
+| `VIGNETTE_JEV_TIMEOUT_SECONDS` | `1.2` | Jev 판단 전체 deadline(초). 재시도하지 않는다 |
+| `VIGNETTE_JEV_MIN_CONFIDENCE` | `0.65` | 설정값(기본 `0.65`) 이상은 기존 감정 전이, confidence 누락은 `None` hold. 그 high threshold 미만에서만 `>=0.35`와 정규화 인접 2구간 mass `>=0.80`이면 tentative 전이(alpha `0.15`, cap `0.075`) |
 | `AUTH_DEV_LOGIN_ENABLED` | `true` | dev-login 엔드포인트 활성화 |
 | `AUTH_ALLOWED_EMAIL_DOMAINS` | `["hs.ac.kr","twentyoz.kr"]` | dev-login·SAML 조직 정책용 도메인 목록. Google OIDC는 이 목록을 적용하지 않고 provider-verified 이메일을 모두 허용 |
 | `AUTH_SUPER_ADMIN_EMAILS` | `["yunchan@twentyoz.kr","hoonjungkoo@hs.ac.kr"]` | 학습자·교수자·관리자 공간 접근과 승인 상태를 부여할 슈퍼 관리자 이메일 |
@@ -220,6 +227,24 @@ npm install
 
 > 참고: 프로세스 환경변수(`$env:KEY`)는 `.env`보다 우선한다. 일회성 오버라이드에 쓸 수 있다.
 
+Jev는 기존 내담자 생성 모델을 바꾸지 않는다. `VIGNETTE_CLIENT_AFFECT_PROVIDER=jev`일 때만 직전 감정 판단을 추가한 뒤 기존 생성 경로로 넘긴다. 기본 transport는 `VIGNETTE_JEV_PROVIDER=openrouter`, 모델은 `VIGNETTE_JEV_MODEL=~typesafe/jev-latest`, endpoint는 `https://openrouter.ai/api/alpha/decisions`다. [OpenRouter Alpha Decisions 공식 API](https://openrouter.ai/docs/api/api-reference/alphadecisions/submit-a-decisions-questions-and-answers-request)의 요청 계약을 따른다. `typesafe`는 직접 TypeSafe를 명시한 경우에만 사용하며 어느 경로도 다른 쪽으로 fallback하지 않는다.
+
+이미 해당 provider의 키가 설정된 로컬 환경에서는 아래 runner로 실제 판단 메타데이터를 수집할 수 있다.
+
+```powershell
+py -3.11 -X utf8 scripts/evaluate-jev-client.py --output outputs/jev-client-evaluation.json
+```
+
+원 probabilities는 보존하고 판단 질문은 압축하며, 질적 감정은 최대 4개로 제한해 고정 사실을 바꾸지 않도록 지시한다. 최종 반복 probe는 구현을 수용했지만 이번 비교에서 기존 경로가 더 빨랐고, 작은 표본·시점·응답 차이 때문에 일반 성능 우위와 품질 승격은 보류한다. 이 로컬 활성화는 코드 기본값 `legacy`나 운영 배포 상태를 바꾸지 않으며, 상세 결과·한계·다음 게이트는 [Jev 결정문](../decisions/jev-client-affect.md)을 따른다.
+
+반복 비교에는 `probe-jev-dialogue.py`를 쓴다.
+
+```powershell
+py -3.11 -X utf8 scripts/probe-jev-dialogue.py --output outputs/jev-dialogue-probe.json --repeats 2 --phases legacy,jev --label local-comparison
+```
+
+`--repeats`, `--phases`, `--label`은 각각 phase 묶음 반복, 비교 대상, 보고서 식별자다. 첫 turn과 이후 turn을 분리해 요약하고, 짝수 반복은 phase 순서를 뒤집어 고정 순서 편향을 줄인다. 이는 provider cache 상태 측정이나 품질·성능 우위 판정이 아니다.
+
 ### 2.2 실행
 
 ```powershell