README.md

---
title: IntentFinder API
emoji: 🔎
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

> **HuggingFace Space 배포 메모**
> - SDK: Docker (위 메타). 진입점 `api:app`, 포트 7860.
> - **Space Settings → Secrets 에 입력**(코드/레포엔 두지 않음):
>   `NAVER_CLIENT_ID`, `NAVER_CLIENT_SECRET`, `NAVER_API_KEY`, `NAVER_SECRET_KEY`, `NAVER_CUSTOMER_ID`,
>   `ANTHROPIC_API_KEY`, `SUPABASE_URL`, `SUPABASE_SERVICE_KEY`
> - **배포 보호 시크릿**(권장): `ALLOWED_ORIGINS`(대시보드 도메인), `DT_API_KEY`(대시보드와 공유), `RATE_MAX_PER_MIN`
> - 헬스체크: `GET /health` · 분석: `GET /analyze?keyword=...` (`DT_API_KEY` 설정 시 `X-DT-Key` 헤더 필요)

# IntentFinder — 검색 인텐트 분석 대시보드

키워드를 입력하면 네이버 실시간 검색 데이터 + AI 클러스터링으로 검색 의도·타깃·연관 경로를 분석하는 SMB용 대시보드.

## 구성

```
[dashboard.html]  React 단일 파일 프론트 (빌드 불필요)
      │  fetch /analyze?keyword=
      ▼
[api.py]  FastAPI 백엔드 (포트 8000)
      ├─ naver_collector.py   네이버 검색광고 키워드도구 (검색량·경쟁)
      ├─ clusterer.py         관련성 필터 + S-BERT→UMAP→HDBSCAN 클러스터링
      ├─ analyzer.py          Overview 카드 집계
      ├─ intent_classifier.py Claude Haiku 의도분류·테마명·마케팅 제안
      ├─ autocomplete.py      네이버 자동완성 기반 검색 경로
      ├─ search_path.py       임베딩 기반 검색 경로(폴백)
      ├─ datalab.py           데이터랩 성별×연령 추정 비중
      ├─ cache.py             SQLite 빠른 재조회 캐시
      └─ supabase_store.py    Supabase 적재(통합 BI 저장소)
```

## 설치 및 실행

```bash
# 1. 의존성 설치 (torch 포함, 수백 MB)
pip install -r requirements.txt

# 2. 자격증명 설정: .env.example을 .env로 복사 후 값 채우기
#    - 네이버 검색광고 (searchad.naver.com > 도구 > API)
#    - ANTHROPIC_API_KEY (platform.claude.com)
#    - 네이버 데이터랩 (developers.naver.com)
#    - SUPABASE_URL / SUPABASE_SERVICE_KEY (Supabase > Settings > API)

# 3. Supabase 테이블 생성: supabase_schema.sql을 SQL Editor에 붙여 Run

# 4. 실행
python -m uvicorn api:app --port 8000      # 백엔드
python -m http.server 5500                 # 프론트
#  → http://127.0.0.1:5500/dashboard.html
```

## 자격증명 키 (.env)

| 변수 | 발급처 | 용도 |
|---|---|---|
| `NAVER_API_KEY` / `NAVER_SECRET_KEY` / `NAVER_CUSTOMER_ID` | searchad.naver.com | 검색량·경쟁 |
| `ANTHROPIC_API_KEY` | platform.claude.com | 의도분류·마케팅 제안 |
| `NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET` | developers.naver.com | 인구통계 |
| `SUPABASE_URL` / `SUPABASE_SERVICE_KEY` | Supabase | 통합 저장소 적재 |

키가 없는 기능은 자동으로 비활성(placeholder)되고 나머지는 정상 동작한다.

## 주의

- `.env`(실제 키)는 **절대 공유·커밋 금지**. 공유는 `.env.example`만.
- `service_role` 키는 RLS 우회 키 → 서버에서만 사용, 프론트 노출 금지.
- 네이버 자동완성·데이터랩은 비공식/상대지수 기반 → "추정" 라벨 유지.
- CDN(Babel·Tailwind)은 데모용 → 실서비스는 Vite 빌드 권장.

## 진행 기록

- `checklist.md` — 단계별 완료 현황
- `context-notes.md` — 설계 결정과 근거
- `data-requirements.md` — 데이터 소스·한계 분석