Update README.md

README.md

@@ -9,65 +9,80 @@ app_file: app.py
 pinned: false
 ---
 
-# Megumin ADK Agent
+# Megumin Chatbot Spec
 
-이 프로젝트는 `data/processed/*.json`의 Q/A 데이터를 로컬 RAG 방식으로 조회하고, 메구밍 페르소나로 답변하는 Gradio 앱입니다.
+## 개요
 
-## Hugging Face Spaces 배포 기준
+메구밍 페르소나로 대화하는 Gradio 기반 챗봇입니다.  
+Google ADK Agent를 사용하며, 답변 전에 RAG로 유사 사례를 찾아 말투와 설정을 참고합니다.
 
-이 저장소는 Hugging Face Spaces의 Gradio Space 형태로 배포할 수 있도록 정리되어 있습니다.
+## 핵심 구성
 
-필요한 것은 아래와 같습니다.
+- LLM: `gemini-3.1-flash-lite-preview`
+- Agent: Google ADK `LlmAgent`
+- UI: Gradio
+- 검색: Gemini Embedding + FAISS
+- 세션: `InMemorySessionService`
 
-- 루트 `app.py`
-- 루트 `requirements.txt`
-- Space Secret에 Gemini API 키 등록
+## 동작 방식
 
-## Spaces에서 필요한 Secret
+1. 사용자의 질문이 들어오면 Agent가 RAG tool을 호출합니다.
+2. 질문 임베딩을 기준으로 FAISS에서 유사 사례 top-3를 찾습니다.
+3. 검색된 답변 사례와 현재 질문을 함께 참고해 메구밍 페르소나로 응답합니다.
+4. 멀티턴 대화에서는 최근 6턴을 유지하고, 그 이전 내용은 짧은 요약으로 압축합니다.
 
-Hugging Face Spaces 설정 화면에서 아래 환경변수 중 하나를 Secret으로 등록하세요.
+## 데이터 구성
 
-- `GOOGLE_API_KEY`
-- 또는 `GEMINI_API_KEY`
+- `megumin_qa_dataset.json`: 원본 Q/A 데이터셋
+- `megumin_questions.faiss`: 질문 임베딩 인덱스
+- `megumin_questions_meta.json`: 인덱스와 원문 레코드 매핑 정보
 
-권장:
-
-```text
-GOOGLE_API_KEY=발급받은_실제_Gemini_API_키
-```
-
-## 로컬 실행
+## 실행
 
 ```bash
 python app_gradio.py
 ```
 
-또는 Spaces와 동일한 진입점 기준으로:
+Spaces 진입점:
 
 ```bash
 python app.py
 ```
 
-## 모델 변경
+## 필수 환경변수
 
-기본 모델은 `gemini-2.5-flash-lite` 입니다.
+- `GOOGLE_API_KEY`: Gemini API 키
+- `HF_TOKEN`: private dataset repo를 읽을 때 필요
 
-필요하면 환경변수로 바꿀 수 있습니다.
+권장:
 
-```bash
-set MEGUMIN_AGENT_MODEL=gemini-2.5-flash-lite
+```env
+GOOGLE_API_KEY=your_gemini_api_key
 ```
 
-## 데이터셋 변환
+## 인덱스 생성
 
-원본 raw txt를 processed JSON으로 변환하려면:
+원본 JSON에서 FAISS 인덱스를 만들려면:
 
 ```bash
-python scripts/convert_raw_to_processed.py
+python scripts/build_faiss_index.py
 ```
 
-생성 파일:
+## 나무위키 QA 변환
 
-```text
-data/processed/megumin_qa_dataset.json
+선별한 나무위키 문서를 QA JSON으로 변환하려면:
+
+```bash
+python scripts/crawl_namuwiki_to_qa.py --title 메구밍 --title 카즈마
 ```
+
+변환 규칙:
+
+- `question`: 질문형이 아니라 검색용 소제목 요약
+- `answer`: 약 200자 내외의 중립 요약
+- chunk overlap: 1~2문장
+- 표/이미지 제외
+
+## 배포 메모
+
+Hugging Face Spaces에서는 dataset repo에서 JSON, FAISS, metadata를 런타임에 내려받아 사용합니다.