docs/data-collection-spec.md

# Data Collection Spec

## 개요

이 프로젝트는 메구밍 챗봇의 RAG 자원을 두 계층으로 관리한다.

- 스타일/페르소나용 데이터
  - 예: `megumin_qa_dataset.json`
- 사실/설정용 데이터
  - 예: `namuwiki_qa.json`

사실/설정용 데이터는 나무위키 문서를 선별 수집해 QA JSON으로 변환하고, 이후 FAISS 인덱스로 검색한다.

## 수집 대상

나무위키 문서는 별칭으로 입력할 수 있으며, 실제 검색 시에는 정식 문서명으로 변환한다.

예:

- `카즈마` -> `사토 카즈마`
- `아쿠아` -> `아쿠아(이 멋진 세계에 축복을!)`
- `다크니스` -> `다크니스(이 멋진 세계에 축복을!)`
- `세계관` -> `이 멋진 세계에 축복을!/설정`
- `지역` -> `이 멋진 세계에 축복을!/지역`

저장 시 `source.title`은 짧은 표시명으로 정규화한다.

예:

- `사토 카즈마` -> `카즈마`
- `아쿠아(이 멋진 세계에 축복을!)` -> `아쿠아`
- `이 멋진 세계에 축복을!/설정` -> `세계관`
- `이 멋진 세계에 축복을!/지역` -> `세계관`

## 변환 규칙

- 출력 포맷은 QA JSON 유지
- `question`은 사용자 질문형이 아니라 검색용 소제목 요약
- `answer`는 중립 요약형 본문
- 표, 이미지, 불필요한 장식 요소는 제외
- chunk 길이는 약 200자 내외
- chunk overlap은 1~2문장

## 저장 파일

- `data/processed/namuwiki_qa.json`
  - 나무위키 기반 통합 QA 데이터
- `data/processed/megumin_qa_dataset.json`
  - 기존 메구밍 스타일/페르소나 QA 데이터
- `data/processed/megumin_questions.faiss`
  - 스타일 데이터 question 인덱스
- `data/processed/megumin_question_answer.faiss`
  - 스타일 데이터 question+answer 인덱스
- `data/processed/megumin_questions_meta.json`
  - 스타일 데이터 인덱스와 원문 레코드 매핑
- `data/processed/namuwiki_questions.faiss`
  - 나무위키 데이터 question 인덱스
- `data/processed/namuwiki_question_answer.faiss`
  - 나무위키 데이터 question+answer 인덱스
- `data/processed/namuwiki_questions_meta.json`
  - 나무위키 데이터 인덱스와 원문 레코드 매핑

## 병합 저장 규칙

`crawl_namuwiki_to_qa.py`는 출력 파일이 이미 존재하면 기존 `items`와 새 결과를 병합한다.

- 우선 중복 기준: `chunk_id`
- 보조 기준: `source.url + chunk_index + question`

병합 후 식별자는 다음 규칙으로 정규화한다.

- `chunk_id`
  - title별 연속 번호 유지
  - 예: `메구밍_0000`, `카즈마_0185`
- `chunk_index`
  - 전체 파일 기준 연속 번호
  - 예: `0`, `135`, `320`

## 관련 스크립트

- `scripts/crawl_namuwiki_to_qa.py`
  - 나무위키 문서를 QA JSON으로 변환
- `scripts/build_faiss_index.py`
  - 스타일/나무위키 데이터 각각에 대해 question 인덱스와 question+answer 인덱스를 생성
- `scripts/expand_persona_from_namuwiki.py`
  - 사실/설정 QA를 메구밍 스타일 QA 초안으로 확장

## 운영 메모

- 나무위키 기반 데이터는 사실/설정 보강용이다.
- 기존 `megumin_qa_dataset.json`은 메구밍 말투와 감정선 유지에 더 중요하다.
- 최종 Agent는 두 데이터원을 함께 검색해 사용한다.