# rb8001: 웹검색 엔티티 확정·정확도 개선 설계/적용

**날짜**: 2025-10-23  
**작성자**: admin  
**관련 파일**: `app/router/message_router.py`, `app/router/slack_handler.py`, `app/services/workflows/web_search_workflow.py`, `app/brain/decision_engine.py`

---

## 문제 요약 (로그 근거 포함)
- “이 기업 …” 질의가 오래된 기억/파일명 상수(CODE_OF_CONDUCT 등)에 끌려가 잘못된 엔티티로 검색/요약됨.  
- LangGraph 경로 예외로 폴백(/search)로 자주 떨어져 대명사 해소·CQR·rerank 미실행, LLM 기본응답 반복.
- 대표/이름 질의가 엔티티 미확정 상태에서 실행되어 잘못된 대상에 대한 답변 반복.

## 해결 설계/적용
1) 그래프 파이프 강화  
   - resolve(코리퍼런스) → link(엔티티링크/신뢰도) → CQR(재작성) → search → rerank → summarize → format.  
   - AsyncSqliteSaver(체크포인터) + thread_id/checkpoint_ns 지정, 실패 시 폴백 로깅.

2) 폴백 경로 동등 정책  
   - /search 경로에서도 대명사 해소 스코어링(한글/기업접미사 가중, 파일·상수 패널티) 적용.  
   - 저신뢰(<2) 또는 미해결 시 즉시 재질문(clarify) 반환.

3) Clarify UX  
   - Slack 버튼으로 후보(최대 3) 제시 → 선택 즉시 재검색/응답.

4) 라우팅 보강  
   - “(기업|회사).*(이름|대표|대표이사)” 등도 웹검색 파이프로 라우팅.

5) 의도-회귀(곱씹기) 단계  
   - 실행 전 “요청-대상-행위” 삼단 체크리스트로 의도 재확인(예: [요청] 이 기업 대표? [대상] 지에프솔루션? [행위] 웹검색/대표확인).  
   - 엔티티 확정(clarify/CQR) 없이는 실행 금지. 질문이 모호하면 반드시 clarify 우선.

6) 시간 감쇠·윈도우 제한  
   - 메모리/최근 대화 검색은 최신 N개·최근 T분(예: 10~15분) 윈도우로 제한하고, 오래된 기억은 감쇠 가중(0.5× 이하) 적용.  
   - 파일명/전대문자 상수 토큰은 기본 제외 목록으로 처리.

## 정확도/표현
- 확신도 낮은 경우: “재질문/보류(출처 부족)”로 응답.  
- 요약/포맷: ‘출처:’ 블록에 상위 3개 제목+URL 표준 표기.

### 대답 정확도(자신감) 평가 로직
- 신뢰도 특징: (a) 근거 커버리지(출처 수·다양성) (b) 엔티티 일치도(질의 엔티티↔결과 타이틀/본문) (c) 최신성(KST 기준 타임스탬프) (d) NLI(출처→응답 정합).  
- 스코어 산출·캘리브레이션: 위 특징을 0–1로 정규화해 가중 합산→ECE/Brier로 보정; 임계 미만은 재질문/보류 라벨 부여.  
- 반성적 리라이트: 응답 말미에 “가정/근거/시간/확신도”를 메타로 요약하여 과장 금지, 불확실 영역은 분리 표기.

## 검증/모니터링
- 테스트(로컬): 엔티티 우선순위·clarify·그래프 경로 안정화 검증.  
- 로그: `[WebSearch] CAND entity`, `Pronoun resolved`, `Fallback /search`, Clarify 버튼 액션 로그.  
- 지표: 성공률·clarify 비율·폴백 비율·응답 확신도(ECE/Brier).

## 교훈
- 엔티티 미확정 상태의 실행 금지, 재질문→확정→실행으로 느린 경로라도 안정성 우선.  
- 오래된 기억/파일 토큰은 강한 패널티, 최신/한글 기업명·기업 접미사 가중으로 현실적 후보를 우선.

---