Enhance README.md with comprehensive documentation

- Add system architecture Mermaid diagram showing 4-step RAG process
- Include detailed data structure breakdown (166,721 respondents)
- Add complete API documentation with curl examples
- Provide response examples for Actual and Synthetic modes
- Add 6 research application categories
- Include performance metrics and technical stack details
- Add professional badges and enhanced formatting

Based on NBS_System_Guide.md technical documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

README.md

@@ -5,63 +5,366 @@ colorFrom: blue
 colorTo: purple
 sdk: docker
 pinned: false
+license: apache-2.0
+tags:
+  - computational-social-science
+  - survey-simulation
+  - rag
+  - persona
+  - korean
 ---
 
-# NBS 페르소나 설문조사 시스템
+# 🎭 NBS 페르소나 설문조사 시스템
 
-전국지표조사(NBS) 데이터 기반 페르소나 아바타 설문 시뮬레이션 API
+[![Hugging Face](https://img.shields.io/badge/🤗%20Hugging%20Face-Space-blue)](https://huggingface.co/spaces/jonghhhh/persona_survey)
+[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.128.0-009688.svg)](https://fastapi.tiangolo.com/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## 기능
+전국지표조사(NBS) 데이터 기반 **페르소나 아바타 설문 시뮬레이션** API입니다. 과거 여론조사에 참여했던 실제 사람들을 디지털 아바타로 재현하여, 새로운 사회적 이슈에 대한 반응을 예측합니다.
 
-- **실제 응답자 모드**: 16만 건의 실제 응답자 데이터 기반 시뮬레이션
-- **통계 기반 모드**: 특정 그룹의 통계적 경향성을 반영한 시뮬레이션
-- **RAG 기반 응답 생성**: 과거 응답 이력을 참조하여 일관성 있는 답변 생성
+## 🌟 주요 특징
 
-## 데이터
+- **📊 대규모 실증 데이터**: 166,721명의 실제 응답자, 163회 설문조사, 1,219개 고유 질문
+- **🤖 RAG 기반 시뮬레이션**: 과거 응답 이력을 검색하여 LLM 컨텍스트로 활용
+- **🎯 정밀 타겟팅**: 성별, 연령, 지역, 직업별 세분화된 시뮬레이션
+- **⚡ 경량 시스템**: 13MB Parquet 파일로 16만+ 응답 데이터 압축
+- **🔄 두 가지 모드**: 개별 응답자(Actual) vs 통계 집계(Synthetic)
 
-- 총 응답자: 166,721명
-- 설문 회차: 163회 (2020년~현재)
-- 고유 질문: 1,219개
+---
+
+## 📚 목차
+
+- [작동 원리](#-작동-원리)
+- [데이터 구조](#-데이터-구조)
+- [API 사용법](#-api-사용법)
+- [응답 예시](#-응답-예시)
+- [기술 스택](#-기술-스택)
+- [연구 활용](#-연구-활용)
+- [라이선스](#-라이선스)
+
+---
+
+## 🧠 작동 원리
+
+### 1. 시스템 아키텍처
+
+```mermaid
+graph TB
+    A[사용자 질문 + 조건] --> B{1. 인구통계 필터링}
+    B --> C[조건 맞는 응답자 추출<br/>166,721명 중]
+
+    A --> D{2. 의미 검색}
+    D --> E[유사 질문 Top-5<br/>1,219개 중]
+
+    C --> F{3. 컨텍스트 구성}
+    E --> F
+    F --> G[응답자의 과거 답변<br/>+ 가치관 프로필]
+
+    G --> H[4. LLM 생성]
+    H --> I[시뮬레이션 답변]
+```
+
+### 2. 핵심 데이터 파일
+
+| 파일 | 크기 | 역할 | 구조 |
+|------|------|------|------|
+| `nbs_questions_index.parquet` | 6.2MB | 질문 검색 인덱스 | 1,219개 질문 × 768차원 벡터 |
+| `consolidated_nbs_data.parquet` | 6.7MB | 응답자 데이터베이스 | 166,721명 × 1,219개 질문 (희소 행렬) |
+
+**작동 흐름:**
+1. **질문 검색**: `nbs_questions_index.parquet`에서 KR-SBERT 임베딩으로 유사 질문 검색
+2. **응답자 필터링**: `consolidated_nbs_data.parquet`에서 조건 맞는 사람 추출
+3. **컨텍스트 생성**: 선택된 응답자의 과거 답변 + 정치성향/가치관 데이터
+4. **LLM 시뮬레이션**: Gemini 2.5 Flash로 일관성 있는 답변 생성
+
+### 3. RAG (Retrieval-Augmented Generation)
+
+LLM 환각을 방지하기 위해 **실제 데이터를 근거로 답변을 생성**합니다:
+
+```python
+# 예시: "정년연장" 질문에 대한 시뮬레이션
+1. 유사 질문 검색 → "고령자 고용 정책", "정년퇴직 연령", "노후 소득 보장"
+2. 서울 40대 남성 자영업자 응답자 5명 추출
+3. 각 응답자의 과거 답변:
+   - 응답자 A: "복지 정책 확대 → 반대 (세금 부담)", "정치 성향 → 보수"
+   - 응답자 B: "복지 정책 확대 → 찬성 (서민 보호)", "정치 성향 → 진보"
+4. LLM이 위 정보를 바탕으로 각자의 입장에서 정년연장 답변 생성
+```
+
+---
+
+## 📂 데이터 구조
+
+### 인구통계 분포
+
+```
+총 응답자: 166,721명 (2020~2025년)
+설문 회차: 163회
+고유 질문: 1,219개
+
+성별:
+  남자: 50.1% (83,561명)
+  여자: 49.9% (83,160명)
+
+연령:
+  평균: 50.0세 (표준편차 17.4세)
+  범위: 18세 ~ 99세
 
-## API 사용법
+지역 (Top 5):
+  경기: 25.5% (42,513명)
+  서울: 18.5% (30,843명)
+  부산:  6.9% (11,504명)
+  경남:  6.5% (10,837명)
+  인천:  5.7%  (9,503명)
+
+직업 (Top 4):
+  사무/기술직: 25.2% (42,013명)
+  주부:         18.2% (30,343명)
+  자영업:       15.7% (26,175명)
+  무직/퇴직:    14.7% (24,508명)
+```
+
+### Sparse Matrix 구조
+
+각 응답자는 전체 1,219개 질문 중 **평균 20~30개만 답변**했으며, Parquet의 효율적 압축으로 13MB에 모든 데이터를 저장합니다.
+
+```
+응답자 #12345:
+  - survey_round: 142
+  - gender: 남자
+  - age: 45
+  - region: 서울
+  - job: 자영업
+  - 대통령_국정운영_평가: "긍정"      ✅ 답변 있음
+  - 정년연장_찬반: "찬성"             ✅ 답변 있음
+  - 기본소득제_찬반: NaN              ❌ 미참여
+  - ... (1,217개 질문)
+```
+
+---
+
+## 🚀 API 사용법
 
 ### Health Check
+
 ```bash
-GET /health
+curl https://jonghhhh-persona-survey.hf.space/health
 ```
 
-### 실제 응답자 시뮬레이션
-```bash
-POST /simulate/actual
+**응답:**
+```json
 {
-  "question": "정년연장에 대해 어떻게 생각하십니까?",
-  "gender": "남자",
-  "age": "31~40",
-  "region": "서울",
-  "job": "사무/기술직",
-  "sample": 5
+  "status": "healthy",
+  "total_records": 166721
 }
 ```
 
-### 통계 기반 시뮬레이션
+---
+
+### 실제 응답자 시뮬레이션 (Actual Mode)
+
+**개별 응답자**의 구체적인 과거 답변을 기반으로 시뮬레이션합니다.
+
 ```bash
-POST /simulate/synthetic
-{
-  "question": "기본소득제 도입에 대한 의견은?",
-  "gender": "여자",
-  "age": "20~29",
-  "region": "경기",
-  "sample": 3
-}
+curl -X POST "https://jonghhhh-persona-survey.hf.space/simulate/actual" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_GEMINI_API_KEY" \
+  -d '{
+    "question": "정년연장에 대해 어떻게 생각하십니까?",
+    "gender": "남자",
+    "age": "40",
+    "region": "서울",
+    "job": "사무/기술직",
+    "sample": 3
+  }'
 ```
 
-## 기술 스택
+**파라미터:**
+- `question` (필수): 시뮬레이션할 질문
+- `gender` (선택): 성별 - "남자" 또는 "여자"
+- `age` (선택): 연령 - "40" 또는 "30~40" 형식
+- `region` (선택): 지역 - 서울, 경기, 부산, 대구, 광주, 대전, 울산, 세종, 강원, 충북, 충남, 전북, 전남, 경북, 경남, 제주
+- `job` (선택): 직업 - 학생, 사무/기술직, 자영업, 주부, 경영/관리/전문직, 생산/기능/노무직, 농/림/수산업, 무직/퇴직/기타
+- `sample` (필수): 생성할 아바타 수 (권장: 3~10개)
+
+**헤더:**
+- `X-API-Key`: Gemini API 키 (필수)
+
+---
+
+### 통계 기반 시뮬레이션 (Synthetic Mode)
+
+**그룹 전체**의 통계적 경향성을 반영한 시뮬레이션입니다.
+
+```bash
+curl -X POST "https://jonghhhh-persona-survey.hf.space/simulate/synthetic" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_GEMINI_API_KEY" \
+  -d '{
+    "question": "기본소득제 도입에 대한 의견은?",
+    "gender": "여자",
+    "age": "20~29",
+    "region": "경기",
+    "sample": 3
+  }'
+```
+
+**차이점:**
+- **Actual**: 각 응답자의 개별 이력 → 다양한 답변
+- **Synthetic**: 그룹의 답변 분포 통계 → 대표성 있는 답변
+
+---
+
+## 📋 응답 예시
+
+### Actual Mode 응답
+
+```json
+[
+  {
+    "respondent_id": "12345",
+    "survey_round": 142,
+    "demographics": {
+      "gender": "남자",
+      "region": "서울",
+      "age": 45,
+      "job": "사무/기술직"
+    },
+    "referenced_context": [
+      "복지 정책 확대 → 반대 (세금 부담 우려)",
+      "정치 성향 → 보수",
+      "경제 성장 우선 → 찬성"
+    ],
+    "response": "정년연장에 대해서는 신중한 접근이 필요하다고 생각합니다. 기업의 인건비 부담이 늘어나면 청년 일자리가 줄어들 수 있고, 결국 세금으로 보전해야 할 가능성이 높기 때문입니다. 개인의 노후 준비를 지원하는 방향이 더 바람직하다고 봅니다."
+  }
+]
+```
+
+### Synthetic Mode 응답
+
+```json
+[
+  {
+    "avatar_id": "syn_0",
+    "demographics": {
+      "gender": "여자",
+      "age": "20~29",
+      "region": "경기",
+      "job": null
+    },
+    "referenced_stat_context": [
+      "복지 정책 확대 → 찬성 75%, 반대 15%, 모름 10%",
+      "기본소득제 관련 질문 → 긍정적 반응 62%",
+      "정치 성향 분포 → 진보 45%, 중도 38%, 보수 17%"
+    ],
+    "response": "20대 여성으로서 기본소득제는 청년 세대의 불안정한 고용 상황을 고려할 때 긍정적으로 검토할 필요가 있다고 생각합니다. 다만 재원 마련 방안과 함께 논의되어야 실효성이 있을 것 같습니다."
+  }
+]
+```
+
+---
+
+## 🛠️ 기술 스택
+
+### Backend
+- **FastAPI** - 고성능 비동기 API 프레임워크
+- **Uvicorn** - ASGI 서버
+
+### Data Processing
+- **Pandas** - 데이터 조작 및 필터링
+- **PyArrow** - Parquet 파일 처리
+- **NumPy** - 벡터 연산 및 Cosine Similarity
+
+### AI/ML
+- **Sentence Transformers** - KR-SBERT 임베딩 모델 (`snunlp/KR-SBERT-V40K-klueNLI-augSTS`)
+- **Google Gemini 2.5 Flash** - LLM 텍스트 생성
+- **scikit-learn** - Cosine Similarity 계산
+
+### Infrastructure
+- **Docker** - 컨테이너화 배포
+- **Hugging Face Spaces** - 무료 호스팅
+
+---
+
+## 🔬 연구 활용
+
+### 1. 컴퓨테이셔널 사회과학
+- **합성 인구(Synthetic Population)** ��성
+- 대규모 설문 데이터 × LLM 결합 방법론
+- 저비용 여론 사전 탐색 도구
+
+### 2. 정책 시뮬레이션
+- 특정 정책안에 대한 세대별/지역별 반응 예측
+- A/B 테스트 전 빠른 프로토타이핑
+- 타겟 집단 최적화
+
+### 3. 시계열 분석
+- 동일 인구집단의 가치관 변화 추적 (2020~2025)
+- 사회적 이슈에 대한 여론 변동 패턴 분석
+
+### 4. 비교문화 연구
+- 한국 설문 데이터 + 타국 데이터 결합
+- 국가 간 페르소나 비교 연구
+
+### 5. 마케팅 & UX
+- 타겟 고객층의 선호도 예측
+- 제품/서비스 반응 시뮬레이션
+- 사용자 페르소나 생성 자동화
+
+### 6. 교육
+- 다양한 관점 체험 시뮬레이션
+- 사회적 다양성 이해 도구
+
+---
+
+## 📊 시스템 성능
+
+- **응답 속도**: 3~5초 (임베딩 로드 시간 제외)
+- **동시 처리**: FastAPI 비동기 처리
+- **데이터 크기**: 13MB (Parquet 압축)
+- **메모리 사용**: 약 500MB (모델 로드 포함)
+
+---
+
+## 🔒 API 키 설정
+
+Gemini API 키는 요청 시 헤더로 전달합니다:
+
+```bash
+-H "X-API-Key: YOUR_GEMINI_API_KEY"
+```
+
+API 키 발급: [Google AI Studio](https://makersuite.google.com/app/apikey)
+
+---
+
+## 📄 라이선스
+
+- **코드**: Apache 2.0
+- **데이터**: 전국지표조사(NBS) 원본 데이터 기반
+- **모델**: KR-SBERT (CC-BY-SA-4.0)
+
+---
+
+## 📞 문의 및 기여
+
+- **GitHub**: [Repository Link]
+- **Hugging Face**: [jonghhhh/persona_survey](https://huggingface.co/spaces/jonghhhh/persona_survey)
+- **이메일**: jonghhhh@khu.ac.kr
+
+---
+
+## 🙏 Acknowledgments
+
+- **전국지표조사(NBS)**: 원본 데이터 제공
+- **KR-SBERT**: 한국어 문장 임베딩 모델
+- **Hugging Face**: 무료 호스팅 플랫폼
+
+---
 
-- FastAPI
-- Sentence Transformers (KR-SBERT)
-- Google Gemini 2.5 Flash
-- Pandas + PyArrow (Parquet)
+<div align="center">
 
-## 라이선스
+**Built with ❤️ for Computational Social Science Research**
 
-데이터는 전국지표조사(NBS) 원본 데이터를 기반으로 합니다.
+</div>