# task-1575.1 완료 보고서

## SCQA

**S**: `kakao_knowledge` v2 파이프라인의 LLM 호출부가 `anthropic` Python SDK + API 키 방식으로 구현되어 있으며, 내부 환경에서는 API 키 없이 `claude` CLI를 사용해야 한다.

**C**: API 키가 미설정이므로 `--use-llm` 옵션을 지정해도 항상 규칙 기반 폴백으로 동작하여, LLM 기반 고품질 인사이트 추출이 불가능했다.

**Q**: `anthropic` SDK 호출을 내부 Claude CLI로 전환하여 LLM 경로를 정상 동작시킬 수 있는가?

**A**: `subprocess.run` 기반 `_call_claude()` 헬퍼를 도입하여 3곳의 `client.messages.create()` 호출을 모두 전환했다. 소량 샘플 테스트에서 LLM 경로가 fallback 없이 정상 동작하며, Stage 2(Sonnet) 추출 품질이 규칙 기반 대비 현저히 우수하다. pytest 34건 전체 통과, pyright 0 에러.

## Phase 1: 코드 변경 내역

### 핵심 변경
1. `_call_claude(prompt, model, timeout)` 헬퍼 추가 — `/home/jay/.local/bin/claude -p` 서브프로세스 호출
2. `_llm_refine_thread_splits()` — `client.messages.create()` -> `_call_claude(model="haiku", timeout=120)`
3. `_stage1_single()` — `client.messages.create()` -> `_call_claude(model="haiku", timeout=120)`
4. `_stage2_single()` — `client.messages.create()` -> `_call_claude(model="sonnet", timeout=300)`
5. `extract_knowledge_v2()` — `api_key` 파라미터 및 `anthropic` SDK 초기화 블록 제거
6. `_parse_json_response()` — CLI 출력에서 JSON 객체를 견고하게 추출하는 2차 파싱 로직 추가

### 삭제된 코드
- `import anthropic` (런타임 import)
- `ANTHROPIC_API_KEY` 환경변수 체크 및 fallback 분기 (30줄)
- `--api-key` CLI 인자 (extract-v2, pipeline-v2 서브커맨드)
- 함수 시그니처에서 `client: object`, `llm_client`, `api_key` 파라미터

## Phase 2: 파이프라인 실행

### 소량 테스트 (100줄 샘플)
- 추출 건수: 1건
- LLM 경로 정상 동작: Stage 1(Haiku) + Stage 2(Sonnet) 모두 성공
- fallback 없음 (로그에 "규칙 기반으로 fallback" 미발생)
- 추출 품질: 제목/요약/핵심포인트/질문/답변 모두 정확하고 상세

### 전체 실행 (32,946줄)
- 백그라운드 실행 중 (PID: 534681)
- 예상 소요: 수 시간 (스레드당 Haiku+Sonnet 2회 CLI 호출)
- 중간 결과: `scripts/kakao_knowledge/output_v2_intermediate/` 에 배치별 저장
- 완료 후 후속 작업: wiki_entries_v2.json -> wiki_entries.json 복사, wiki.db import, 대시보드 재시작

### LLM vs 규칙 기반 품질 비교 (소량 샘플 기준)

- 규칙 기반: title="질문자/인카/서울 #궁금증 ..." (원문 그대로)
- LLM 기반: title="레이저 광응고술, 약관 개정으로 수술 해당 및 고지의무 대상 확정" (의미 추출)
- LLM 기반이 카테고리 분류, 전문가 식별, 핵심 포인트 추출에서 현저히 우수

## 발견 이슈 및 해결

### 자체 해결 (2건)
1. **Claude CLI 출력 JSON 파싱 실패** — `_parse_json_response`에 2차 JSON 객체 추출 로직(`{}` 브레이스 매칭) 추가
   - 상세: CLI 출력에 JSON 외 텍스트(설명, 코드블록 등)가 포함되어 `json.loads()` 실패. 1차 시도 실패 시 첫 번째 `{...}` 블록을 깊이 추적하여 추출
2. **pyright 타입 에러 — `_side_effect(*args)` 인덱싱** — `*args` 대신 명시적 `cmd: list[str]` 파라미터로 변경
   - 상세: `test_knowledge_extractor_v2.py`의 mock side_effect에서 `args[0]` 접근 시 pyright `reportGeneralTypeIssues`

### 범위 외 미해결 (1건)
1. **전체 파이프라인 실행 완료 대기** — 범위 외 사유: 32,946줄 처리에 수 시간 소요, 백그라운드 실행 중. 완료 후 wiki_entries.json 복사/import는 별도 확인 필요

## 산출물

- `/home/jay/projects/insuwiki/.worktrees/task-1575.1-dev1/scripts/kakao_knowledge/knowledge_extractor_v2.py`
- `/home/jay/projects/insuwiki/.worktrees/task-1575.1-dev1/scripts/kakao_knowledge/__main__.py`
- `/home/jay/projects/insuwiki/.worktrees/task-1575.1-dev1/scripts/kakao_knowledge/tests/test_knowledge_extractor_v2.py`

## 테스트 결과

- pytest: 34 passed in 0.23s (규칙 기반 10건, 카테고리 4건, 인사이트 유형 4건, 스레드 분리 3건, 배치 3건, LLM mock 3건, 구조 검증 7건)
- pyright: 0 errors, 0 warnings
- black/isort: 포맷팅 적용 완료

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-1575.1-dev1
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-1575.1-dev1
- **머지 의견**: Phase 1 코드 전환 완료, 테스트 34건 전체 통과, pyright 0 에러. 전체 파이프라인 실행은 백그라운드 진행 중이며 결과 확인 후 wiki_entries.json 교체 권장.

## 모델 사용 기록

- 팀원: 불칸 / 작업 내용: knowledge_extractor_v2.py + __main__.py LLM 호출부 전환 / 사용 모델: sonnet / 정당성: -
- 팀원: 아르고스 / 작업 내용: test_knowledge_extractor_v2.py mock 수정 / 사용 모델: sonnet / 정당성: -

## QC 자동 검증 결과

```json
{
  "task_id": "task-1575.1",
  "overall": "재검증 예정",
  "checks": {
    "test_runner": "PASS (34 passed in 0.23s)",
    "pyright_check": "PASS (0 errors, 0 warnings)",
    "style_check": "PASS (black + isort 적용 완료)",
    "data_integrity": "PASS",
    "file_check": "보고서 작성 후 재검증"
  }
}
```