chore: GitHub-readiness 재검토 정리

코드 안전성:
- explore_data.py · test_api.py: 모듈 레벨 코드를 main() 함수로 감싸고
if __name__ == '__main__' 가드 추가. 이전엔 import만으로 .env 로드 +
API 호출 시도 + UnicodeEncodeError(cp949) 발생.
- 이모지 제거 (Windows 콘솔 인코딩 안전성 가이드라인 준수)
- 14개 모듈 모두 부작용 없이 import 됨 검증.

브랜드 정합성:
- src/ 12개 .py 모듈의 docstring 첫 줄 'K-Curator: ...' → '사이 (SAI): ...'

저장소 정돈:
- 루트 CLAUDE.md 삭제 (v0 stale, 옛 K-Curator 이름·e뮤지엄 한정 진행상황)
- src/CLAUDE.md 추적 해제 (어시스턴트 internal handoff. 정식 회고는
docs/07-development-journey.md 참고)
- .gitignore에 CLAUDE.md 패턴 명시

.gitignore

@@ -32,3 +32,8 @@ data/processed/chunks.jsonl
 .claude/
 .DS_Store
 Thumbs.db
+
+# AI 어시스턴트 internal handoff 문서 (CLAUDE.md)
+# — 일반 독자에겐 노이즈. 정식 인수인계 정보는 docs/07-development-journey.md에 정리됨.
+CLAUDE.md
+src/CLAUDE.md

CLAUDE.md

@@ -1,105 +0,0 @@
-# K-Curator 프로젝트 — 진행 상황 인수인계
-
-## 프로젝트 개요
-국립중앙박물관 소장품 기반 AI 도슨트 챗봇 (포트폴리오용 사이드 프로젝트).
-RAG + 멀티모달 + 사용자 적응형 톤 조절(어린이/성인/외국인)이 차별점.
-
-상세 기획은 `docs/K-Curator_프로젝트_정리.md` 참고.
-
-## 환경
-- OS: Windows 11
-- Python 3.13.12 (시스템 PATH 등록됨)
-- 가상환경: `C:\K-Curator\.venv`
-- 활성화 명령: `.\.venv\Scripts\Activate.ps1`
-- 설치된 라이브러리: requests, python-dotenv, beautifulsoup4, lxml
-- API 키: `.env` 파일의 `EMUSEUM_API_KEY` (36자, KCISA 발급)
-
-## 현재까지 진행한 것
-
-### 1. e뮤지엄 OpenAPI 발급 완료
-- 문화포털(KCISA)에서 발급
-- 일 1,000건 한도 (개발 계정)
-
-### 2. 첫 API 호출 성공 (`src/test_api.py`)
-- 엔드포인트: `https://api.kcisa.kr/openapi/service/rest/meta/MPKreli`
-- 파라미터: serviceKey, numOfRows, pageNo
-- 전체 데이터: 334,187개
-
-### 3. 데이터 품질 조사 완료 (`src/explore_data.py`)
-- description 채워진 비율: 페이지마다 60~100% 들쭉날쭉
-- subjectKeyword/subjectCategory: 거의 0% (사용 불가)
-- 발견: API의 description은 "보존상태 기록" 위주
-  → RAG 자료로는 부적합
-
-### 4. 큐레이터 추천 페이지 분석 완료
-- URL: https://www.museum.go.kr/MUSEUM/contents/M0501000000.do
-- 총 321건 (33페이지)
-- 6개 카테고리: 선사·고대, 중·근세, 조각·공예, 서화, 아시아, 보존과학
-- 작품 1개당 약 3,000자 깊이 있는 큐레이터 해설
-- 큐레이터 실명 명시
-- 라이선스: 공공누리 3유형 (출처표시+변경금지)
-- **이게 K-Curator의 진짜 RAG 자료원**
-
-## 데이터 소스 전략 (확정)
-
-### 메인 RAG 자료
-**큐레이터 추천 페이지 321건 (스크래핑)**
-- URL 패턴 (리스트): `?cp={페이지}&searchId=recommend&relicRecommendUse=Y`
-- URL 패턴 (상세): `?schM=view&relicRecommendId={ID}`
-- 이미지 패턴: `https://www.museum.go.kr/files/zin/curator_{번호}_{n}.jpg`
-
-### 메타데이터 보강
-**e뮤지엄 API**
-- 시대(temporal), 재질(medium) 등 안정적 메타데이터
-
-### Phase 1 목표
-**200점 → 321건 다 가져가도 무방**
-
-## 지금 작업 중인 것
-
-**파일: `src/scrape_one.py`**
-
-목표: 작품 1개(`<기영회도>` ID 2351292)를 자동 스크래핑해서 JSON으로 저장.
-
-추출 항목:
-1. 제목(메인+부제) + 큐레이터명
-2. 메타데이터 캡션 (작가, 시대, 재질, 크기, 소장번호, 등급)
-3. 본문 해설 (h5, p 태그 위주)
-4. 이미지 URL 5장
-5. 라이선스 정보
-
-저장 위치: `data/raw/relic_{ID}.json`
-
-테스트 작품 정보:
-- 제목: 〈기영회도〉- 세 가지 복을 누린 원로 관료들의 잔치
-- 큐레이터: 오다연
-- 시대: 조선 1584년
-- 재질: 비단에 색
-- 등급: 보물 제1328호
-
-## 다음 단계 (우선순위)
-
-1. ✅ `scrape_one.py` 완성 + 테스트 (1개 작품 자동 수집)
-2. ⏳ `scrape_list.py` (321개 작품 ID 리스트 수집)
-3. ⏳ `scrape_all.py` (321개 전체 자동 스크래핑 → `data/raw/`)
-4. ⏳ 텍스트 임베딩 + 벡터 DB 구축 (Chroma 또는 Qdrant)
-5. ⏳ RAG 파이프라인 (어린이/성인 모드 시스템 프롬프트)
-6. ⏳ Streamlit UI
-
-## 주의사항
-
-- 스크래핑 시 서버 부담 줄이기: 요청 간 1~2초 sleep 권장
-- 라이선스 표시 필수 (출처: 국립중앙박물관 / 공공누리 3유형)
-- API 키 / 서비스키는 절대 GitHub에 커밋 X (`.env`는 `.gitignore` 등록 완료)
-- 한국 정부 API/사이트는 가끔 한글 인코딩 이슈가 있을 수 있음
-- 이미지는 멀티모달용으로 저작권 주의 (Phase 2)
-
-## 코드 작성 가이드라인
-
-- Python 3.13 기준
-- 가상환경(.venv) 활성화 상태에서 작업
-- 한글 주석/메시지 OK
-- 함수는 짧고 명확하게
-- 에러 처리는 명시적으로
-- 출력 메시지에 이모지 자제 (Windows 콘솔 인코딩 이슈 방지)
-- 데이터 저장은 항상 `data/raw/` (raw) 또는 `data/processed/` (정제)

src/CLAUDE.md

@@ -1,155 +0,0 @@
-# K-Curator 프로젝트 — 진행 상황 인수인계
-
-## 프로젝트 개요
-국립중앙박물관 소장품 기반 AI 도슨트 챗봇 (포트폴리오용 사이드 프로젝트).
-RAG + 멀티모달 + 사용자 적응형 톤 조절(어린이/성인/외국인)이 차별점.
-
-상세 기획은 `docs/K-Curator_프로젝트_정리.md` 참고.
-
-## 환경
-- OS: Windows 11
-- Python 3.13.12 (시스템 PATH 등록됨)
-- 가상환경: `C:\K-Curator\.venv`
-- 활성화 명령: `.\.venv\Scripts\Activate.ps1`
-- 설치된 라이브러리: requests, python-dotenv, beautifulsoup4, lxml,
-  chromadb, sentence-transformers (torch CPU 포함), openai
-- API 키 (.env):
-    - `EMUSEUM_API_KEY` — 36자, KCISA 발급
-    - `OPENAI_API_KEY` — sk-proj-... 약 160자 (RAG LLM 생성용)
-- LLM: OpenAI gpt-4o-mini (Anthropic API 미사용, 사용자 결제 환경 고려)
-
-## 현재까지 진행한 것
-
-### 1. e뮤지엄 OpenAPI 발급 완료
-- 문화포털(KCISA)에서 발급
-- 일 1,000건 한도 (개발 계정)
-
-### 2. 첫 API 호출 성공 (`src/test_api.py`)
-- 엔드포인트: `https://api.kcisa.kr/openapi/service/rest/meta/MPKreli`
-- 파라미터: serviceKey, numOfRows, pageNo
-- 전체 데이터: 334,187개
-
-### 3. 데이터 품질 조사 완료 (`src/explore_data.py`)
-- description 채워진 비율: 페이지마다 60~100% 들쭉날쭉
-- subjectKeyword/subjectCategory: 거의 0% (사용 불가)
-- 발견: API의 description은 "보존상태 기록" 위주
-  → RAG 자료로는 부적합
-
-### 4. 큐레이터 추천 페이지 분석 완료
-- URL: https://www.museum.go.kr/MUSEUM/contents/M0501000000.do
-- 총 321건 (33페이지)
-- 6개 카테고리: 선사·고대, 중·근세, 조각·공예, 서화, 아시아, 보존과학
-- 작품 1개당 약 3,000자 깊이 있는 큐레이터 해설
-- 큐레이터 실명 명시
-- 라이선스: 공공누리 3유형 (출처표시+변경금지)
-- **이게 K-Curator의 진짜 RAG 자료원**
-
-## 데이터 소스 전략 (확정)
-
-### 메인 RAG 자료
-**큐레이터 추천 페이지 321건 (스크래핑)**
-- URL 패턴 (리스트): `?cp={페이지}&searchId=recommend&relicRecommendUse=Y`
-- URL 패턴 (상세): `?schM=view&relicRecommendId={ID}`
-- 이미지 패턴: `https://www.museum.go.kr/files/zin/curator_{번호}_{n}.jpg`
-
-### 메타데이터 보강
-**e뮤지엄 API**
-- 시대(temporal), 재질(medium) 등 안정적 메타데이터
-
-### Phase 1 목표
-**200점 → 321건 다 가져가도 무방**
-
-## 지금까지 만든 스크립트
-
-**`src/scrape_one.py`** — 작품 1건 스크래퍼. `scrape(relic_id)` / `save(data)` 함수 export.
-**`src/scrape_list.py`** — 321건 ID/제목/썸네일 리스트 수집. 단일 요청(pageSize=500).
-**`src/scrape_all.py`** — list 결과를 읽어 전수 수집. `--force` 옵션으로 재수집 가능.
-
-추출 항목:
-1. 제목 + 부제 + 큐레이터명 (`curator_NNN_tit.gif`의 alt 파싱; 콜론/대시 변형 처리)
-2. 메타데이터 (작가, 시대, 재질, 크기, 소장번호, 등급) + `raw_caption` 원본 보존
-3. 본문 (heading/paragraph/quote/caption 4종 블록, 순서 보존)
-4. 이미지 URL + alt 캡션
-5. 라이선스 텍스트
-
-## Phase 1 데이터 수집 완료 상태 (2026-04-29)
-
-전체 321건 → `data/raw/relic_{ID}.json` 저장 완료.
-
-| 지표 | 값 |
-|---|---|
-| 총 작품 수 | 321 |
-| 총 본문 글자 | 약 108만 자 |
-| 평균 본문 길이 | 3,366자 |
-| 총 본문 블록 | 4,497개 |
-| 총 이미지 | 1,423장 |
-| 큐레이터명 추출 성공 | 251/321 (78%) |
-
-남은 빈 필드는 대부분 캡션에 원래 없는 정보(선사 유물엔 등급 없음 등).
-필요 시 `raw_caption`에서 후처리 가능.
-
-## 임베딩 / 벡터 DB (2026-04-29 완료)
-
-**`src/build_index.py`** — 청킹 → 임베딩 → Chroma 인덱스 빌드
-**`src/search.py`** — top-k 검색 (RAG 검증/디버그용)
-
-- 청킹: heading 단위 섹션, 1500자 초과 시 paragraph 경계로 분할, 100자 미만 제거
-- 모델: `intfloat/multilingual-e5-small` (passage:/query: 프리픽스, normalize_embeddings)
-- 저장: `data/processed/chunks.jsonl` (사람용 덤프) + `data/chroma/` (kcurator_relics)
-
-| 지표 | 값 |
-|---|---|
-| 청크 수 | 1,171 |
-| 평균 길이 | 951자 (max 2,486 / min 110) |
-| 임베딩 차원 | 384 (cosine) |
-| Chroma 디스크 | ~24 MB |
-| 빌드 시간 | 약 4분 (CPU) |
-
-검색 스모크 테스트 결과 top-1 cosine 유사도 0.86~0.91 — 의미적 retrieval 작동 확인.
-재빌드: `python src/build_index.py` (기존 컬렉션 자동 삭제 후 재생성)
-
-## RAG 파이프라인 (2026-04-29 완료)
-
-**`src/rag.py`** — 검색 → 컨텍스트 구성 → OpenAI 호출 → 스트리밍 출력
-- 검색: build_index의 Chroma 컬렉션 재사용 (top-k 기본 5)
-- LLM: `gpt-4o-mini`, temperature=0.7, system 프롬프트로 톤 분리
-- 톤 모드 3종: `adult` (성인 존댓말) / `kid` (어린이 ~예요체) / `foreign` (영어, 한자 병기)
-- 출처 자동 표기: `— 참고: <작품명> (큐레이터: 이름)` 등 모드별 포맷
-- "자료에 없으면 모른다고 답하라" 가드레일 시스템 프롬프트에 포함
-
-사용 예:
-```
-python src/rag.py "기영회도가 뭐야?" --mode kid
-python src/rag.py "Tell me about the moon jar" --mode foreign
-python src/rag.py "..." --no-stream --k 5
-```
-
-알려진 자잘한 이슈:
-- foreign 모드에서 LLM이 출처를 가끔 `<자료 1>`로 카피해 적음 → 시스템 프롬프트 보강 필요
-
-## 다음 단계 (우선순위)
-
-1. ✅ `scrape_one.py` (1건 자동 수집)
-2. ✅ `scrape_list.py` (321개 ID 리스트)
-3. ✅ `scrape_all.py` (전체 수집 — 321/321 성공)
-4. ✅ `build_index.py` + `search.py` (청킹/임베딩/Chroma)
-5. ✅ `rag.py` (RAG, 어린이/성인/외국인 3-mode)
-6. ⏳ Streamlit UI (작품 이미지 카드 + 톤 토글 + 멀티턴)
-
-## 주의사항
-
-- 스크래핑 시 서버 부담 줄이기: 요청 간 1~2초 sleep 권장
-- 라이선스 표시 필수 (출처: 국립중앙박물관 / 공공누리 3유형)
-- API 키 / 서비스키는 절대 GitHub에 커밋 X (`.env`는 `.gitignore` 등록 완료)
-- 한국 정부 API/사이트는 가끔 한글 인코딩 이슈가 있을 수 있음
-- 이미지는 멀티모달용으로 저작권 주의 (Phase 2)
-
-## 코드 작성 가이드라인
-
-- Python 3.13 기준
-- 가상환경(.venv) 활성화 상태에서 작업
-- 한글 주석/메시지 OK
-- 함수는 짧고 명확하게
-- 에러 처리는 명시적으로
-- 출력 메시지에 이모지 자제 (Windows 콘솔 인코딩 이슈 방지)
-- 데이터 저장은 항상 `data/raw/` (raw) 또는 `data/processed/` (정제)

src/api.py

@@ -1,5 +1,5 @@
 """
-K-Curator: FastAPI 백엔드
+사이 (SAI): FastAPI 백엔드
 - POST /api/chat   — 검색 + LLM 스트리밍 (Server-Sent Events)
 - GET  /api/works/{id} — 작품 상세 JSON (출처 카드 클릭 시 사용)
 - GET  /api/health — 헬스체크

src/build_index.py

@@ -1,5 +1,5 @@
 """
-K-Curator: 본문 청킹 + 임베딩 + Chroma 인덱스 구축
+사이 (SAI): 본문 청킹 + 임베딩 + Chroma 인덱스 구축
 - 입력: data/raw/relic_*.json (321건)
 - 청킹: heading 단위 섹션. heading 등장 전의 도입부는 'intro' 섹션.
 - 임베딩: intfloat/multilingual-e5-small (passage: 프리픽스 사용)

src/daily_pick.py

@@ -1,5 +1,5 @@
 """
-K-Curator: '오늘의 큐레이션' 생성기
+사이 (SAI): '오늘의 큐레이션' 생성기
 - 날짜 기반 결정적 테마 (day-of-year) → 임베딩 검색으로 추천 작품 6점
 - 별도 cron 불필요 — 같은 날엔 같은 결과, 다음 날엔 자동 갱신
 

src/embed_images.py

@@ -1,5 +1,5 @@
 """
-K-Curator: 작품 이미지 CLIP 임베딩 → Chroma 인덱스
+사이 (SAI): 작품 이미지 CLIP 임베딩 → Chroma 인덱스
 - 입력: data/raw/relic_*.json 의 images[] 필드 (1,400+장)
 - 모델: sentence-transformers/clip-ViT-B-32-multilingual-v1 (한국어 텍스트도 같은 공간)
 - 출력: data/chroma/ 에 'kcurator_images' 컬렉션

src/explore_data.py

@@ -1,101 +1,103 @@
 """
-K-Curator: 데이터 품질 조사
-1페이지(오래된 데이터) vs 마지막 페이지(최신 데이터) 비교
+사이 (SAI): e뮤지엄 API 데이터 품질 조사 (v0 데이터 탐색 단계 산물).
+
+1페이지(오래된 데이터) vs 마지막 페이지(최신) 데이터 품질 비교.
+
+NOTE: v0 시절 의사결정의 근거가 된 스크립트 — e뮤지엄 API의 description이
+"보존상태 기록" 위주임을 확인하고 큐레이터 추천 페이지 스크래핑으로
+방향을 전환하게 만든 도구. 학습 여정의 흔적으로 보존됩니다.
 """
 
 import os
+import sys
+
 import requests
 from dotenv import load_dotenv
 
-load_dotenv()
-API_KEY = os.getenv("EMUSEUM_API_KEY")
 URL = "https://api.kcisa.kr/openapi/service/rest/meta/MPKreli"
 
 
-def fetch_page(page_no: int, num_rows: int = 10):
-    """특정 페이지의 데이터를 가져옴"""
-    params = {
-        "serviceKey": API_KEY,
-        "numOfRows": num_rows,
-        "pageNo": page_no,
-    }
+def fetch_page(api_key: str, page_no: int, num_rows: int = 10):
+    """특정 페이지의 데이터를 가져옴."""
+    params = {"serviceKey": api_key, "numOfRows": num_rows, "pageNo": page_no}
     response = requests.get(URL, params=params, headers={"Accept": "application/json"})
     data = response.json()
-    
     if data["response"]["header"]["resultCode"] != "0000":
         return None, 0
-    
     items = data["response"]["body"]["items"]["item"]
     total = int(data["response"]["body"]["totalCount"])
     return items, total
 
 
-def analyze_quality(items, label: str):
-    """데이터 품질 분석 + 출력"""
+def analyze_quality(items, label: str) -> None:
+    """데이터 품질 분석 + 출력."""
     print(f"\n{'='*60}")
-    print(f"  📊 {label}")
+    print(f"  [{label}]")
     print(f"{'='*60}")
-    
+
     if not items:
         print("  데이터 없음")
         return
-    
+
     total = len(items)
-    
-    # 필드별 채워진 개수 카운트
     fields_to_check = [
-        ('description', '해설'),
-        ('subjectKeyword', '키워드'),
-        ('subjectCategory', '분류'),
-        ('temporal', '시대'),
-        ('medium', '재질'),
+        ("description", "해설"),
+        ("subjectKeyword", "키워드"),
+        ("subjectCategory", "분류"),
+        ("temporal", "시대"),
+        ("medium", "재질"),
     ]
-    
-    print(f"\n  [필드 채워짐 비율] (총 {total}개 중)")
+
+    print(f"\n  필드 채워짐 비율 (총 {total}개 중)")
     for field, label_kr in fields_to_check:
         filled = sum(1 for item in items if item.get(field))
         pct = (filled / total) * 100
-        bar = '█' * int(pct / 10) + '░' * (10 - int(pct / 10))
+        bar = "#" * int(pct / 10) + "-" * (10 - int(pct / 10))
         print(f"    {label_kr:6s} [{bar}] {filled}/{total} ({pct:.0f}%)")
-    
-    # 작품 제목 샘플 5개
-    print(f"\n  [작품 제목 샘플]")
+
+    print("\n  작품 제목 샘플")
     for i, item in enumerate(items[:5], 1):
-        title = item.get('title') or '(제목없음)'
-        temporal = item.get('temporal') or '(시대불명)'
+        title = item.get("title") or "(제목없음)"
+        temporal = item.get("temporal") or "(시대불명)"
         print(f"    {i}. {title} ({temporal})")
-    
-    # 해설 있는 작품 1개 보여주기
-    items_with_desc = [item for item in items if item.get('description')]
+
+    items_with_desc = [item for item in items if item.get("description")]
     if items_with_desc:
         sample = items_with_desc[0]
-        desc = sample.get('description', '')[:200]
-        print(f"\n  [해설 있는 작품 예시]")
+        desc = sample.get("description", "")[:200]
+        print("\n  해설 있는 작품 예시")
         print(f"    제목: {sample.get('title') or '(없음)'}")
         print(f"    해설: {desc}...")
 
 
-# ===== 메인 실행 =====
-print("🔍 K-Curator 데이터 품질 조사 시작")
-print(f"   API 키 길이: {len(API_KEY)}자")
+def main() -> int:
+    load_dotenv()
+    api_key = os.getenv("EMUSEUM_API_KEY")
+    if not api_key:
+        print("EMUSEUM_API_KEY 가 .env 에 없습니다.", file=sys.stderr)
+        return 1
+
+    print("사이 — 데이터 품질 조사 시작")
+    print(f"  API 키 길이: {len(api_key)}자")
 
-# 1. 1페이지 조회
-items_first, total = fetch_page(1, 10)
-print(f"\n📦 전체 데이터 수: {total:,}개")
+    items_first, total = fetch_page(api_key, 1, 10)
+    print(f"\n  전체 데이터 수: {total:,}개")
+    analyze_quality(items_first, "1페이지 (가장 오래된 데이터 추정)")
 
-analyze_quality(items_first, "1페이지 (가장 오래된 데이터 추정)")
+    last_page = (total // 10) + (1 if total % 10 else 0)
+    items_last, _ = fetch_page(api_key, last_page, 10)
+    analyze_quality(items_last, f"마지막 페이지 #{last_page} (최신 데이터 추정)")
 
-# 2. 마지막 페이지 조회
-last_page = (total // 10) + (1 if total % 10 else 0)
-items_last, _ = fetch_page(last_page, 10)
-analyze_quality(items_last, f"마지막 페이지 #{last_page} (최신 데이터 추정)")
+    middle_page = last_page // 2
+    items_middle, _ = fetch_page(api_key, middle_page, 10)
+    analyze_quality(items_middle, f"중간 페이지 #{middle_page}")
+
+    print(f"\n{'='*60}")
+    print("  조사 완료")
+    print(f"{'='*60}")
+    print("\n  사용한 API 호출 수: 3회 / 일일 한도 1000회")
+    return 0
 
-# 3. 중간 페이지 조회
-middle_page = last_page // 2
-items_middle, _ = fetch_page(middle_page, 10)
-analyze_quality(items_middle, f"중간 페이지 #{middle_page}")
 
-print(f"\n{'='*60}")
-print("  ✅ 조사 완료!")
-print(f"{'='*60}")
-print("\n💰 사용한 API 호출 수: 3회 / 일일 한도 1000회")
+if __name__ == "__main__":
+    sys.exit(main())

src/match_locations.py

@@ -1,5 +1,5 @@
 """
-K-Curator: 추천 작품 ↔ 상설 작품 매칭
+사이 (SAI): 추천 작품 ↔ 상설 작품 매칭
 - 추천 321점의 작품 제목과 상설 643점의 작품명을 비교
 - 매칭되면 추천 작품에도 hall/floor/room_name 위치 메타를 부착
 - 출력: data/raw/relic_locations.json (relic_id → location 매핑)

src/rag.py

@@ -1,5 +1,5 @@
 """
-K-Curator: RAG 챗 파이프라인
+사이 (SAI): RAG 챗 파이프라인
 - 검색: Chroma + e5-small (build_index.py와 동일 모델)
 - 생성: OpenAI gpt-4o-mini
 - 톤 모드: adult(성인) / kid(어린이) / foreign(외국인용 영어)

src/scrape_all.py

@@ -1,5 +1,5 @@
 """
-K-Curator: 전체 큐레이터 추천 작품 자동 스크래핑
+사이 (SAI): 전체 큐레이터 추천 작품 자동 스크래핑
 - 입력: data/raw/relic_list.json (scrape_list.py 결과)
 - 동작: 각 ID마다 scrape_one.scrape() 호출 → data/raw/relic_{ID}.json 저장
 - 이미 저장된 파일은 스킵하므로 중간 재시작 가능

src/scrape_list.py

@@ -1,5 +1,5 @@
 """
-K-Curator: 큐레이터 추천 작품 ID 리스트 수집
+사이 (SAI): 큐레이터 추천 작품 ID 리스트 수집
 - 출처: https://www.museum.go.kr/MUSEUM/contents/M0501000000.do?searchId=recommend&relicRecommendUse=Y
 - pageSize=500 으로 한 번에 321건을 받아온다.
 - 출력: data/raw/relic_list.json

src/scrape_one.py

@@ -1,5 +1,5 @@
 """
-K-Curator: 큐레이터 추천 작품 1개 스크래핑
+사이 (SAI): 큐레이터 추천 작품 1개 스크래핑
 - 입력: relicRecommendId (예: 2351292 = 〈기영회도〉)
 - 출력: data/raw/relic_{ID}.json
 """

src/scrape_permanent.py

@@ -1,5 +1,5 @@
 """
-K-Curator: 국립중앙박물관 상설전시 스크래퍼
+사이 (SAI): 국립중앙박물관 상설전시 스크래퍼
 - 7관 39실을 순회하며 각 실의 소개 텍스트 + 현재 전시중인 작품 리스트 수집
 - 출력: data/raw/permanent.json (단일 파일)
 

src/scrape_special.py

@@ -1,5 +1,5 @@
 """
-K-Curator: 국립중앙박물관 특별전/테마전 스크래퍼
+사이 (SAI): 국립중앙박물관 특별전/테마전 스크래퍼
 - 현재 진행중인 특별·테마 전시 + 상세 페이지 본문 수집
 - 출력: data/raw/special.json
 """

src/search.py

@@ -1,5 +1,5 @@
 """
-K-Curator: Chroma 인덱스 검색 (RAG 검증용)
+사이 (SAI): Chroma 인덱스 검색 (RAG 검증용)
 사용법:
     python src/search.py "조선시대 잔치 그림"
     python src/search.py "조선시대 잔치 그림" --k 10

src/test_api.py

@@ -1,51 +1,61 @@
 """
-K-Curator: e뮤지엄 API 첫 호출 테스트
+사이 (SAI): e뮤지엄 API 첫 호출 테스트 (v0 데이터 탐색 단계 산물).
+
+NOTE: 이 스크립트는 v0 시절 데이터 품질 조사 도구입니다.
+사이의 본 운영(상세 작품 본문은 큐레이터 추천 페이지 스크래핑으로 확보)에는
+사용되지 않으며, 학습 여정의 흔적으로 보존됩니다.
 """
 
 import os
+import sys
+
 import requests
 from dotenv import load_dotenv
 
-load_dotenv()
-API_KEY = os.getenv("EMUSEUM_API_KEY")
-
-if not API_KEY:
-    raise ValueError(".env 파일에서 EMUSEUM_API_KEY를 못 찾았어요!")
-
-print(f"API 키 로딩 성공 (길이: {len(API_KEY)}자)")
-
-URL = "https://api.kcisa.kr/openapi/service/rest/meta/MPKreli"
-params = {
-    "serviceKey": API_KEY,
-    "numOfRows": 5,
-    "pageNo": 1,
-}
-
-print("API 호출 중...")
-response = requests.get(URL, params=params, headers={"Accept": "application/json"})
-print(f"응답 코드: {response.status_code}")
-
-data = response.json()
-result_code = data["response"]["header"]["resultCode"]
-result_msg = data["response"]["header"]["resultMsg"]
-print(f"결과: [{result_code}] {result_msg}")
-
-if result_code != "0000":
-    print("정상 응답이 아닙니다.")
-    exit()
-
-items = data["response"]["body"]["items"]["item"]
-total = data["response"]["body"]["totalCount"]
-print(f"전체 작품 수: {total}개")
-print(f"가져온 작품: {len(items)}개")
-print("")
-
-for idx, item in enumerate(items, 1):
-    print(f"--- [{idx}] ---")
-    print(f"제목: {item.get('title') or '(없음)'}")
-    print(f"시대: {item.get('temporal') or '(없음)'}")
-    print(f"재질: {item.get('medium') or '(없음)'}")
-    print(f"분류: {item.get('subjectCategory') or '(없음)'}")
-    desc = item.get('description') or '(없음)'
-    print(f"해설: {desc[:100]}")
-    print("")
+
+def main() -> int:
+    load_dotenv()
+    api_key = os.getenv("EMUSEUM_API_KEY")
+    if not api_key:
+        print(
+            ".env 파일에서 EMUSEUM_API_KEY를 못 찾았어요. "
+            "KCISA 발급 키를 .env에 추가하세요.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"API 키 로딩 성공 (길이: {len(api_key)}자)")
+
+    url = "https://api.kcisa.kr/openapi/service/rest/meta/MPKreli"
+    params = {"serviceKey": api_key, "numOfRows": 5, "pageNo": 1}
+
+    print("API 호출 중...")
+    response = requests.get(url, params=params, headers={"Accept": "application/json"})
+    print(f"응답 코드: {response.status_code}")
+
+    data = response.json()
+    result_code = data["response"]["header"]["resultCode"]
+    result_msg = data["response"]["header"]["resultMsg"]
+    print(f"결과: [{result_code}] {result_msg}")
+    if result_code != "0000":
+        print("정상 응답이 아닙니다.")
+        return 2
+
+    items = data["response"]["body"]["items"]["item"]
+    total = data["response"]["body"]["totalCount"]
+    print(f"전체 작품 수: {total}개  /  가져온 작품: {len(items)}개\n")
+
+    for idx, item in enumerate(items, 1):
+        print(f"--- [{idx}] ---")
+        print(f"제목: {item.get('title') or '(없음)'}")
+        print(f"시대: {item.get('temporal') or '(없음)'}")
+        print(f"재질: {item.get('medium') or '(없음)'}")
+        print(f"분류: {item.get('subjectCategory') or '(없음)'}")
+        desc = item.get("description") or "(없음)"
+        print(f"해설: {desc[:100]}\n")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())