# GPT 판례 판단 연동

## 동작 구조

`POST /v1/plagiarism/detect`는 다음 순서로 법적 검토 보조 신호를 만든다.

1. 등록 코퍼스에서 유사 문서와 증거 구간을 찾는다.
2. `LegalRiskEngine`이 저작물 유형과 법적 태그로 등록 판례 Top 5를 고른다.
3. GPT Judge가 탐지 증거와 Top 5 판례만 비교한다.
4. 서버가 Structured Outputs 스키마와 판례 ID를 검증하고, 사람 검토가 해제되지 않도록 `review_required=true`를 강제한다.
5. 호출 실패·형식 오류·미등록 판례 ID가 있으면 규칙 기반 결과로 복귀한다.

GPT는 전체 판례 545건을 한 번에 받지 않으며 법률상 침해를 확정하지 않는다.

## 설정

기본값은 비활성이다. 원고의 증거 구간이 외부 API로 전송되는 것을 승인한 환경에서만
다음 값을 설정한다.

```dotenv
OPENAI_API_KEY=...
USE_LLM_LEGAL_JUDGE=true
OPENAI_JUDGE_MODEL=gpt-4o-mini
LLM_JUDGE_TIMEOUT_SECONDS=20
LLM_JUDGE_MAX_EVIDENCE_CHARS=4000
```

OpenAI 응답 저장은 `store=false`로 요청한다. 전송되는 원고 인용문의 총 길이는
`LLM_JUDGE_MAX_EVIDENCE_CHARS`로 제한된다. API 키가 없으면 판례 Judge는 활성화되지 않는다.

## 응답 필드

```json
{
  "legal_risk": {
    "status": "review_required",
    "judgment_method": "llm",
    "llm_verdict": "likely",
    "llm_confidence": 0.82,
    "llm_review_required": true,
    "precedent_ids": ["2012다73493"],
    "llm_matched_precedent_ids": ["2012다73493"],
    "supporting_reasons": ["..."],
    "counter_reasons": ["..."],
    "missing_factors": ["..."],
    "judge_model": "gpt-4o-mini",
    "judge_prompt_version": "legal-judge-v2",
    "judgment_summary": "2012다73493 판례의 판단 기준과 탐지 증거를 비교한 결과, 표현 일치 범위가 크다는 사유로 저작권 침해가 의심되어 추가 검토가 필요합니다."
  }
}
```

- `judgment_method=llm`: GPT 판단과 서버 검증이 완료됨
- `judgment_method=rule_based`: 기능이 비활성 또는 판단할 매칭·판례가 없음
- `judgment_method=rule_fallback`: GPT 호출 또는 검증 실패로 규칙 결과 사용
- `precedent_ids`: 규칙 엔진이 검색한 판례 Top 5
- `llm_matched_precedent_ids`: GPT가 실제 근거로 선택한 판례. Top 5 밖의 ID는 거부됨
- `llm_verdict`: `likely`, `unlikely`, `insufficient_evidence` 중 하나
- `judgment_summary`: 검증된 사건번호와 핵심 사유를 결합한 사용자 표시용 판례 의견

사용자 화면에는 모델명이나 `judgment_method`를 주 문구로 표시하지 않는다. 먼저
`judgment_summary`를 보여주고 관련 사건번호, 지지·반대 근거, 추가 확인사항을 함께 표시한다.

`llm_confidence`는 GPT 응답의 자기평가 값이며 법적 침해 확률이나 통계적으로 보정된
확률이 아니다. 운영 감사 시에는 모델명, 프롬프트 버전, 입력 판례 ID와 결과를 함께
보관해야 한다.

## 검증

```bash
python3 -m pytest tests/test_legal_risk.py -q
```

실제 OpenAI 호출은 테스트에서 수행하지 않는다. 운영 전 별도 검증 세트에서 모델별
일치율, `insufficient_evidence` 비율, 사람 검토자와의 불일치를 측정한다.