Cleanup: dead code, route deletion (/info, /chat, /api/*), comment polish, auth mode docs, URL rename

.dockerignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.coverage
+*.gguf
+.git/
+.github/
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+docs/
+tests/
+.claude/
+
+# 모델 가중치는 컨테이너 안에서 첫 실행 시 받음
+models/
+.cache/

.gitattributes

@@ -1,38 +1,9 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
-data/cases.sqlite filter=lfs diff=lfs merge=lfs -text
-data/guides.sqlite filter=lfs diff=lfs merge=lfs -text
-data/embeddings.sqlite filter=lfs diff=lfs merge=lfs -text
+* text=auto eol=lf
+
+*.sqlite binary
+*.gguf binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary

.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+
+.venv/
+venv/
+.env
+
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+.cache/
+.kpaa-cache/
+*.gguf
+models/
+.run/
+.webui_secret_key
+
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

Dockerfile

@@ -0,0 +1,50 @@
+# 멀티아키 backend 이미지 — llama-cpp-python 임베드 단일 프로세스.
+# 외부 추론 데몬·서비스 의존 없음.
+#
+# 빌드:
+#     docker buildx build --platform linux/amd64,linux/arm64 -t kpaa-backend .
+# 또는 docker-compose가 알아서 (build: .)
+
+FROM python:3.11-slim AS base
+
+# Build deps for native wheels (lxml, llama-cpp-python sdist fallback).
+# llama-cpp-python은 보통 manylinux wheel을 받지만, arm64에서 빌드가 필요할 수 있어
+# build-essential + cmake 포함.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        cmake \
+        ca-certificates \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONUTF8=1 \
+    KPAA_HOST=0.0.0.0 \
+    KPAA_PORT=8000
+# GPU offload 는 컨테이너 *런타임* 의 llama-cpp 빌드에 따라 자동 결정.
+# CPU 빌드 컨테이너: 자동 0. GPU 빌드 컨테이너: 자동 -1.
+# 강제 override 가 필요하면 docker-compose 의 environment 에 KPAA_N_GPU_LAYERS=... 추가.
+
+WORKDIR /app
+
+# 의존성 먼저 설치 (캐시 효율)
+COPY pyproject.toml README.md LICENSE NOTICE ./
+COPY src/ ./src/
+RUN pip install --upgrade pip \
+ && pip install '.[llm]'
+
+# 데이터 자산 (상담사례 스냅샷 동봉)
+COPY data/ ./data/
+
+# 모델·법제처 캐시는 named volume으로 마운트 (도커가 처리)
+VOLUME ["/root/.cache/kpaa"]
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -fsS http://127.0.0.1:8000/healthz || exit 1
+
+CMD ["python", "-m", "kpaa", "serve", "--host", "0.0.0.0", "--port", "8000"]

Dockerfile.ui

@@ -0,0 +1,41 @@
+# KPAA UI Space — Open WebUI pointing to KPAA Backend Space.
+#
+# Open WebUI 공식 이미지를 그대로 쓰되 HF Spaces 정책(UID 1000 + writable /app)에
+# 맞추기 위해 chown + 필수 env 추가.
+
+FROM ghcr.io/open-webui/open-webui:main
+
+# ─── Backend wiring ──────────────────────────────────────────────────────
+ENV OPENAI_API_BASE_URLS="https://scvcoder-kpaa.hf.space/v1"
+ENV OPENAI_API_KEYS="hf-spaces-internal"
+ENV ENABLE_OLLAMA_API=false
+ENV WEBUI_NAME="KPAA — 개인정보보호법 상담"
+# 백엔드의 default preset (`gemma-4-e2b-q4`) 과 동일해야 Open WebUI 자동 선택.
+# 사용자가 dropdown 에서 다른 프리셋을 고르면 백엔드의 ModelManager 가 자동 전환.
+ENV DEFAULT_MODELS="개인정보 상담 AI(gemma-4-e2b-q4)"
+ENV WEBUI_AUTH=false
+
+# ─── HF Spaces / UID 1000 권한 정리 ───────────────────────────────────────
+USER root
+RUN chown -R 1000:1000 /app && \
+    mkdir -p /tmp/openwebui-data && \
+    chown -R 1000:1000 /tmp/openwebui-data
+ENV DATA_DIR=/tmp/openwebui-data
+
+# ─── Inject route-change postMessage script into Open WebUI HTML ─────────
+# Cross-origin iframe 정책상 부모 창은 자식의 URL 변경을 감지할 수 없다.
+# Open WebUI HTML 에 작은 polling 스크립트를 주입해서 location.pathname
+# 변경 시 부모 창에 postMessage 로 알린다. 백엔드 Space 의 split HTML 이
+# 이 메시지를 받으면 우측 참고자료를 자동 초기화.
+RUN sh -c "for f in /app/build/index.html /app/backend/open_webui/static/index.html; do \
+    if [ -f \"\$f\" ]; then \
+        sed -i 's|</body>|<script>console.log(\"[kpaa] injected script loaded\");(function(){var _kp;function emit(){var p=location.pathname;if(p!==_kp){_kp=p;console.log(\"[kpaa] route change:\",p);try{window.parent.postMessage({type:\"kpaa-route\",path:p},\"*\");}catch(e){console.log(\"[kpaa] postMessage failed\",e);}}}var _origPush=history.pushState,_origRep=history.replaceState;history.pushState=function(){_origPush.apply(this,arguments);emit();};history.replaceState=function(){_origRep.apply(this,arguments);emit();};window.addEventListener(\"popstate\",emit);setInterval(emit,500);emit();})();</script></body>|' \"\$f\"; \
+        echo \"injected into: \$f\"; \
+    fi; \
+done"
+
+USER 1000
+
+# Open WebUI listens on 8080 by default.
+ENV PORT=8080
+EXPOSE 8080

README.md

@@ -1,56 +1,266 @@
 ---
-title: Korean Privacy AI Assistant 백앤드 API
-emoji: 🧠
-colorFrom: green
-colorTo: blue
+title: 개인정보보호법 미니 상담 (KPAA)
+emoji: ⚖️
+colorFrom: blue
+colorTo: green
 sdk: gradio
 sdk_version: "5.20.0"
 app_file: app.py
 pinned: false
-short_description: 경량 AI 모델 사용
+short_description: 한국 개인정보보호법 RAG 상담 챗봇 (Gemma 4 E2B + 법제처 OPEN API)
 hardware: zero-a10g
 license: mit
 ---
 
-# KPAA Backend
+# 개인정보보호법 미니 상담 챗봇 (KPAA)
 
-한국 개인정보보호법 RAG 백엔드. **OpenAI 호환 API**를 노출합니다.
+> 개인 · 소상공인 · 작은 병원을 위한 한국 개인정보보호법 안내 챗봇.
+> 법제처 OPEN API + 개인정보보호위원회 상담사례 1,745건을 근거로
+> 작은 모델(Gemma 4 E2B)이 한국어 평문으로 답합니다.
 
-이 Space는 **추론 백엔드 전용**입니다. UI는 별도 Space([scvcoder/korean-privacy-ai-assistant](https://huggingface.co/spaces/scvcoder/korean-privacy-ai-assistant))에서 Open WebUI로 제공됩니다.
+- **법제처 OPEN API**(MCP 레이어 없이 Python으로 직접 호출, 15개 카테고리 SDK)
+- **개인정보보호위원회 상담사례** 1,745건 로컬 SQLite FTS5 인덱스
+- **RAG 사전조회** — 룰 라우터로 법조문/사례/PIPC결정/해석례 병렬 fan-out → Gemma는 그 컨텍스트만 보고 답변
+- **모든 답변에 인용 + 면책 자동 부착**
 
-## 아키텍처
+---
+
+## 두 가지 사용 경로
+
+### 🤗 한 번 클릭으로 체험 — Hugging Face Spaces 데모
+
+배포된 Space 링크에 접속해서 바로 채팅. 별도 설치·키 발급 불필요.
+ZeroGPU(A100) 가속으로 빠른 응답.
+
+> Space 가 잠시 휴면(sleep) 상태일 수 있습니다 — 첫 방문 시 wake-up 5–10초 대기.
+
+### 💻 노트북에서 직접 돌리기 (권장 — SMB·장기 사용자)
+
+GitHub clone → `pip install` → 자기 데이터/키로 운영. 외부 의존 없음 (법제처
+OPEN API 호출 외 모든 것이 로컬). 아래 "사전 조건" 부터 따라가세요.
+
+---
+
+## 사전 조건
+
+- Python **3.11 이상** (Win/Mac/Linux 공통) — 또는 Docker Desktop
+- 8GB 이상 여유 RAM (Gemma 4 E2B Q4_K_M ~3.2GB + KV cache + 백엔드)
+- **법제처 OPEN API 키 (LAW_OC) 무료 발급** — https://open.law.go.kr 가입 후 마이페이지에서 ID(이메일 @ 앞부분) 확인
+
+---
+
+## 빠른 시작
+
+`.env`에 OC 키부터 입력:
+
+```bash
+git clone https://github.com/sz1-kca/korean-privacy-ai-assistant
+cd korean-privacy-ai-assistant
+
+# Mac/Linux
+cp .env.example .env
+# Windows PowerShell
+copy .env.example .env
+
+# 편집기로 .env 열어 LAW_OC=<발급받은_id> 입력
+```
+
+이후 두 가지 경로 중 하나.
+
+### 경로 A — 네이티브 (권장, Docker 불필요)
+
+```bash
+# 의존성 + 패키지 설치
+pip install -e ".[dev,llm]"
+
+# (1) 백엔드 — RAG + LLM (FastAPI :8000)
+python -m kpaa serve
+
+# (2) 새 터미널에서 Open WebUI (한 번만 설치)
+pip install open-webui
+open-webui serve     # http://localhost:8080
+```
+
+Open WebUI에서 Settings → Connections → **OpenAI API** → `+ Add Connection`:
+- URL: `http://localhost:8000/v1`
+- Key: `local`
+- 모델 드롭다운에서 **`kpaa-privacy-ko`** 선택
+
+첫 `kpaa serve` 실행 시 Gemma 4 E2B GGUF (~3.2GB)을 자동 다운로드합니다 (~5–15분, 한 번만).
+
+### 경로 B — Docker Compose
+
+```bash
+docker compose up -d
+# → http://localhost:3000 (Open WebUI 자동 연결)
+# 첫 가동 시 backend가 모델 다운로드, 5–15분 소요
+docker compose logs -f backend   # 진행 확인
+```
+
+`docker-compose.yml`이 Open WebUI에 OpenAI 커넥션을 미리 주입하므로 UI에서 별도 설정 없이 즉시 `kpaa-privacy-ko` 모델로 채팅 가능합니다.
+
+---
+
+## 🔐 인증 모드 (개인용 vs 다중 사용자)
+
+**기본값 — 즉시 사용 모드 (`WEBUI_AUTH=false`).** `manage.sh` / `Dockerfile.ui` / `docker-compose.yml` 모두 이 값을 주입하므로 첫 부팅 시 `admin@localhost`/`admin` 관리자 계정이 자동 생성되어 가입·로그인 화면 없이 바로 채팅 화면이 뜹니다. **개인 PC 로컬 (`127.0.0.1`) 단독 사용 가정**.
+
+⚠️ **공용/원격 노출 시 위험**: 이 모드에서는 호스트:포트에 접근 가능한 누구나 admin 권한으로 들어옵니다. LAN/공용 서버로 노출(0.0.0.0 바인딩, 포워딩, 리버스 프록시) 시 반드시 아래 인증 모드로 전환하세요.
 
+**인증 모드 — 본인 이메일/비밀번호 사용.** 환경변수만 바꾸고 재시작:
+
+```bash
+# 네이티브 (manage.sh):
+export KPAA_OPENWEBUI_WEBUI_AUTH=true
+./manage.sh restart
 ```
-사용자 브라우저
-    ↓ (UI 접속)
-[Open WebUI Space]
-    ↓ (OpenAI API 호출)
-[이 Space — KPAA Backend]
-    ↓ (RAG 검색 + Gemma 4 추론)
-법제처 OPEN API + 상담사례 SQLite + ZeroGPU
+
+Docker 사용자는 [`Dockerfile.ui:16`](Dockerfile.ui#L16) / [`docker-compose.yml`](docker-compose.yml) 의 `WEBUI_AUTH` 를 `true` 로 바꿔 재빌드.
+
+전환 후 첫 부팅에서 가입 화면이 뜨고, 본인 이메일/비밀번호로 admin 등록 → 이후 매 세션 로그인 + 비밀번호 자유 변경 가능. **즉시 사용 모드의 `admin@localhost`/`admin` 계정에서 비밀번호를 바꾸려고 시도하면 자동 로그인이 깨져 잠기므로** 본인 비밀번호 운영을 원하면 처음부터 인증 모드로 시작하세요.
+
+| 모드 | 화면 마찰 | 비밀번호 자유도 | 권장 환경 |
+|---|---|---|---|
+| `WEBUI_AUTH=false` (기본) | 0 (즉시 채팅) | 고정 `admin/admin` | 개인 PC 로컬 |
+| `WEBUI_AUTH=true` | 매 세션 로그인 | 자유 | LAN/공용 서버 |
+
+---
+
+## 사용 예 (CLI)
+
+```bash
+# 법제처 SDK 단독 호출 (LLM 없음)
+python -m kpaa law search "개인정보보호법"
+python -m kpaa law text 270351 --jo "24의2"
+python -m kpaa pipc search "동의 철회"
+python -m kpaa expc search "개인정보 수집"
+
+# 상담사례 검색 (로컬 SQLite, ms 단위)
+python -m kpaa cases search "병원 환자 동의"
+
+# RAG 컨텍스트만 빌드 (LLM 호출 없음, 빠름)
+python -m kpaa retrieve "매장 CCTV 안내문구 어떻게 써요?"
+
+# RAG + LLM 종단
+python -m kpaa smoke "매장 CCTV 안내문구 어떻게 써요?"
+
+# 상담사례 갱신 (privacy.go.kr 재스크래이프 ~2분)
+python -m kpaa refresh-cases
+python -m kpaa refresh-cases --since 2025-01-01    # 증분
 ```
 
-## Endpoints
+---
+
+## OS별 주의사항
+
+KPAA 는 *장비별 자동 선택* 으로 GPU 가속 여부를 결정합니다.
+사용자가 `KPAA_N_GPU_LAYERS` 를 명시하지 않으면 다음 규칙:
 
-| Method | Path | 설명 |
+| 플랫폼 | llama-cpp 빌드 | 자동 결과 |
 |---|---|---|
-| POST | `/v1/chat/completions` | OpenAI 호환 chat (`stream=true` 지원) |
-| GET | `/v1/models` | 사용 가능 모델 (`kpaa-privacy-ko`) |
-| GET | `/healthz` | liveness check |
-| GET | `/info` | 상세 정보 + Swagger UI |
-| GET | `/gradio` | Gradio 상태 페이지 |
+| Windows / Linux | GPU 빌드 (CUDA·ROCm·Vulkan 등) | `-1` (모든 레이어 GPU) |
+| Windows / Linux | CPU 빌드 (기본 `pip install`) | `0` (CPU) |
+| macOS (Apple Silicon / Intel) | Metal 빌드 / 일반 | `0` (CPU, opt-in) |
+
+### Windows
+- PowerShell 한글 깨짐 방지: `chcp 65001` + `PYTHONUTF8=1` (CLI 진입 시 자동 UTF-8 reconfigure 적용)
+- NVIDIA GPU 사용 시 (CUDA Toolkit 설치 후):
+  ```powershell
+  $env:CMAKE_ARGS = "-DGGML_CUDA=on"
+  pip install --force-reinstall --no-cache-dir llama-cpp-python
+  ```
+  재설치 후엔 자동으로 GPU 모드로 동작 (`KPAA_N_GPU_LAYERS` 명시 불필요).
 
-## Open WebUI 연결 (UI Space에서 자동 설정)
+### macOS (Apple Silicon / Intel)
+- **기본 CPU 추론** — Gemma 4 E2B Q4_K_M + Metal 조합 segfault 회귀 회피
+  (라이브 검증 2026-05-01: `n_gpu_layers=-1` 시 모델 로드 직후 프로세스
+  silently die, `n_gpu_layers=12` 시 응답 hang. 안정성 미확정).
+- 노트북 *팬 소음* 이 거슬리면 스레드 수를 더 줄이세요:
+  ```bash
+  KPAA_N_THREADS=4 python -m kpaa serve   # 16코어 M3 Max → 4 만 사용
+  ```
+  반대로 빠른 추론을 원하면 늘리거나 (속도 ↑ 발열·소음 ↑):
+  ```bash
+  KPAA_N_THREADS=12 python -m kpaa serve
+  ```
+- Apple Silicon Metal GPU 가속 *opt-in* (segfault 우려, 자기 책임):
+  ```bash
+  KPAA_N_GPU_LAYERS=-1 python -m kpaa serve
+  ```
+  segfault 등 호환성 이슈가 보이면 변수 제거 (자동 CPU 환원).
+- 정부 사이트 SSL 인증서: `truststore` 가 시스템 신뢰 저장소 자동 사용 (별도 설정 불필요).
 
+### Linux
+- NVIDIA GPU 사용 시:
+  ```bash
+  CMAKE_ARGS="-DGGML_CUDA=on" pip install --force-reinstall --no-cache-dir llama-cpp-python
+  ```
+  재설치 후 자동 감지. `KPAA_N_GPU_LAYERS` 명시 불필요.
+- ROCm: `CMAKE_ARGS="-DGGML_HIPBLAS=on"`, Vulkan: `CMAKE_ARGS="-DGGML_VULKAN=on"` — 동일 패턴.
+
+---
+
+## 환경변수 (`.env`)
+
+| 변수 | 기본 | 설명 |
+|---|---|---|
+| `LAW_OC` | (필수) | 법제처 OPEN API 인증 ID (이메일 @ 앞부분) |
+| `KPAA_N_GPU_LAYERS` | (자동) | GPU offload 레이어 수 — 미지정 시 *플랫폼·빌드 자동 감지* (위 표). 강제 override: `-1`=모두 / `0`=CPU / 정수=일부 |
+| `KPAA_N_THREADS` | (자동) | CPU 추론 스레드 수 — *플랫폼별 자동*: macOS=`cpu/3` (4~6 cap, 노트북 발열·소음 절제), Linux/Win=`cpu/2` (4~8 cap). 빠른 추론 원하면 늘리고 더 조용히 원하면 줄임 |
+| `KPAA_MODEL_DIR` | (자동) | GGUF 캐시 경로 — 미지정 시 `platformdirs.user_cache_dir/kpaa/models` |
+| `KPAA_HOST` / `KPAA_PORT` | `127.0.0.1` / `8000` | FastAPI 바인딩 |
+| `KPAA_LLM_BACKEND` | (자동) | LLM 백엔드 선택 — `llama_cpp`(로컬 GGUF) 또는 `zerogpu`(HF Spaces transformers). 미지정 시 `SPACE_ID` 환경변수로 자동 분기 |
+| `KPAA_HF_MODEL_REPO` | `google/gemma-4-E2B-it` | ZeroGPU 백엔드용 transformers repo |
+| `KPAA_HF_GPU_DURATION` | `120` | `@spaces.GPU` ���수당 GPU 점유 한도(초) |
+| `KPAA_OPENWEBUI_WEBUI_AUTH` | `false` | `true` 로 두면 OpenWebUI 가입/로그인 화면 활성화 (본인 이메일·비밀번호). 자세히는 위 "🔐 인증 모드" |
+
+---
+
+## 🤗 Hugging Face Spaces 직접 배포하기
+
+본 리포는 **HF Spaces 의 Gradio + ZeroGPU 환경에서 그대로 동작**한다.
+저장소를 fork 하거나 자체 Space 에 클론해 자기 도메인으로 운영 가능.
+
+### 절차
+1. https://huggingface.co/new-space — Space 생성. SDK = **Gradio**, Hardware = **ZeroGPU** (Pro 무료) 또는 CPU upgrade.
+2. **Persistent Storage** 활성화 (Pro: 20GB 무료) — transformers 모델이 한 번만 받아짐.
+3. **Settings → Variables and secrets**:
+   - Secret: `LAW_OC` = 본인 법제처 OPEN API ID
+   - Variable: `HF_HOME=/data/.huggingface` (persistent storage 위에 모델 캐시)
+4. 본 리포를 Space 에 push (`git remote add hf https://huggingface.co/spaces/<user>/<space>` → `git push hf main`).
+5. 첫 빌드 10–15분 (torch + transformers + 모델 다운로드). 이후 재시작 즉시 부팅.
+6. 채팅 테스트.
+
+### 로컬에서 Gradio UI 미리보기
 ```bash
-OPENAI_API_BASE_URL=https://scvcoder-kpaa-backend.hf.space/v1
-OPENAI_API_KEY=any-value
-DEFAULT_MODELS=kpaa-privacy-ko
+pip install -e ".[dev,llm,hf]"
+KPAA_LLM_BACKEND=llama_cpp python app.py     # 로컬 GGUF + Gradio UI
+# → http://127.0.0.1:7860
 ```
 
-## Secrets / Hardware
-- **Secret** `LAW_OC` — 법제처 OPEN API ID (필수)
-- **Hardware** ZeroGPU (zero-a10g) — Pro 무료
+### 듀얼 모드 정리
+
+| 환경 | 진입점 | LLM 백엔드 | UI |
+|---|---|---|---|
+| 로컬 노트북 (장기 사용·SMB) | `python -m kpaa serve` | `llama_cpp` (GGUF, CPU/Metal/CUDA) | FastAPI `/chat` (자체 SSE) 또는 Open WebUI |
+| HF Spaces 데모 (대중 체험) | `python app.py` (자동) | `zerogpu` (transformers + `@spaces.GPU`) | Gradio Blocks |
+| 로컬 Gradio 미리보기 | `KPAA_LLM_BACKEND=llama_cpp python app.py` | `llama_cpp` (강제) | Gradio Blocks |
+
+같은 RAG 파이프라인(법제처 호출, 라우팅, 인용·면책 부착) 을 양쪽이 공유.
+
+---
+
+## 데이터 출처 / 라이선스
+
+- **법제처 OPEN API** (https://open.law.go.kr) — 1인 1키 무료. 응답 데이터는 공공누리 표시 후 사용 가능.
+- **개인정보 상담사례** (https://www.privacy.go.kr) — 약 1,745건, 공공누리 제1유형 추정. 본 리포의 [`data/cases.sqlite`](data/cases.sqlite)는 시점 스냅샷이며 갱신은 `kpaa refresh-cases` 또는 월 1회 GitHub Actions 자동 PR.
+- **Gemma 4** — [Gemma Terms of Use](https://ai.google.dev/gemma/terms) + Apache 2.0. GGUF (로컬용): [`bartowski/google_gemma-4-E2B-it-GGUF`](https://huggingface.co/bartowski/google_gemma-4-E2B-it-GGUF). transformers (HF Spaces 용, 같은 가중치): [`google/gemma-4-E2B-it`](https://huggingface.co/google/gemma-4-E2B-it).
+- 본 프로젝트 코드: **MIT** ([LICENSE](LICENSE), [NOTICE](NOTICE))
+
+로컬 사용자: 채팅 기록은 Open WebUI 로컬 SQLite 또는 자체 `/chat` UI 의 브라우저 메모리에만. HF Spaces 데모: Gradio 세션 종료 시 휘발. 외부 텔레메트리 없음.
+
+---
+
+## 면책
 
-## 라이선스
-MIT (코드) · 답변 데이터는 PIPC/privacy.go.kr 출처표시
+본 챗봇 답변은 **일반적 정보 제공**이며 법률 자문이 아닙니다. 구체적 사안은 개인정보보호위원회(privacy.go.kr) 또는 변호사 상담을 권합니다. 신고: KISA 개인정보침해신고센터 국번없이 **118**.

README_backend.md

@@ -0,0 +1,56 @@
+---
+title: KPAA Backend - 개인정보보호법 RAG 추론 API
+emoji: 🧠
+colorFrom: green
+colorTo: blue
+sdk: gradio
+sdk_version: "5.20.0"
+app_file: app.py
+pinned: false
+short_description: KPAA RAG 추론 백엔드 (OpenAI 호환 API)
+hardware: zero-a10g
+license: mit
+---
+
+# KPAA Backend
+
+한국 개인정보보호법 RAG 백엔드. **OpenAI 호환 API**를 노출합니다.
+
+이 Space는 **추론 백엔드 전용**입니다. UI는 별도 Space([scvcoder/korean-privacy-ai-assistant](https://huggingface.co/spaces/scvcoder/korean-privacy-ai-assistant))에서 Open WebUI로 제공됩니다.
+
+## 아키텍처
+
+```
+사용자 브라우저
+    ↓ (UI 접속)
+[Open WebUI Space]
+    ↓ (OpenAI API 호출)
+[이 Space — KPAA Backend]
+    ↓ (RAG 검색 + Gemma 4 추론)
+법제처 OPEN API + 상담사례 SQLite + ZeroGPU
+```
+
+## Endpoints
+
+| Method | Path | 설명 |
+|---|---|---|
+| POST | `/v1/chat/completions` | OpenAI 호환 chat (`stream=true` 지원) |
+| GET | `/v1/models` | 사용 가능 모델 (`kpaa-privacy-ko`) |
+| GET | `/healthz` | liveness check |
+| GET | `/info` | 상세 정보 + Swagger UI |
+| GET | `/gradio` | Gradio 상태 페이지 |
+
+## Open WebUI 연결 (UI Space에서 자동 설정)
+
+```bash
+OPENAI_API_BASE_URL=https://scvcoder-kpaa.hf.space/v1
+OPENAI_API_KEY=any-value
+DEFAULT_MODELS=kpaa-privacy-ko
+```
+
+## Secrets / Hardware
+- **Secret** `LAW_OC` — 법제처 OPEN API ID (필수)
+- **Hardware** ZeroGPU (zero-a10g) — Pro 무료
+
+## 라이선스
+MIT (코드) · 답변 데이터는 PIPC/privacy.go.kr 출처표시

README_ui.md

@@ -0,0 +1,42 @@
+---
+title: 개인정보보호법 미니 상담 (KPAA)
+emoji: ⚖️
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 8080
+pinned: false
+short_description: 한국 개인정보보호법 RAG 챗봇 (Open WebUI + Gemma 4)
+license: mit
+---
+
+# 개인정보보호법 미니 상담 챗봇 (KPAA)
+
+> 개인 · 소상공인 · 작은 병원을 위한 한국 개인정보보호법 안내 챗봇.
+>
+> **Open WebUI** 인터페이스. 추론은 [scvcoder/kpaa](https://huggingface.co/spaces/scvcoder/kpaa) Space (Gemma 4 E2B + ZeroGPU)로 위임됩니다.
+
+## 아키텍처
+
+```
+사용자 ──▶ [이 Space — Open WebUI UI]
+              │
+              │ POST /v1/chat/completions
+              ▼
+         [kpaa Space — Gemma 4 + RAG + ZeroGPU]
+              │
+              ▼
+         법제처 OPEN API + 상담사례 SQLite
+```
+
+## 사용 방법
+1. 이 Space 페이지 열기 → 채팅창에 질문 입력
+2. 첫 응답은 백엔드 모델 cold start로 30-60초 소요 가능
+3. 답변에 인용·면책 자동 부착
+
+## 한계
+- 법률 자문이 아닙니다. 구체적 사안은 변호사 또는 [개인정보보호위원회](https://www.privacy.go.kr) 문의
+- 신고: KISA 개인정보침해신고센터 ☎ 118
+
+## 라이선스
+MIT (코드) · 답변 데이터는 PIPC/privacy.go.kr 출처표시

app.py

@@ -1,31 +1,32 @@
-"""KPAA Backend Space — Gradio + ZeroGPU + KPAA OpenAI-compatible API.
+"""HF Spaces (Gradio SDK + ZeroGPU) 진입점.
 
-Strategy validated via minimal test:
-  - demo.launch() (Gradio's own uvicorn) is the path that activates ZeroGPU.
-  - mount_gradio_app + manual uvicorn does NOT activate ZeroGPU.
+HF Spaces 빌더가 자동으로 `python app.py` 를 실행한다. 로컬에서도 같은
+파일로 미리보기 가능:
 
-So we use demo.launch(), and AFTER launch we attach KPAA's /v1 routes to
-the underlying FastAPI (demo.app) via app.include_router. Routes added at
-runtime are picked up because Starlette dispatches by traversing app.routes
-on each request.
+    pip install -e ".[dev,llm,hf]"
+    KPAA_LLM_BACKEND=llama_cpp python app.py    # 로컬 GGUF 로 UI 만 미리보기
+    # → http://127.0.0.1:7860
 
-Hardware: ZeroGPU (zero-a10g).
-Required secret: LAW_OC.
+HF Spaces 환경에서는 자동으로 `SPACE_ID` 가 잡혀 ZeroGPU 백엔드가 활성화된다.
+LAW_OC 는 Space Settings > Secrets 에 등록.
 """
+from __future__ import annotations
+
 import os
 import sys
-import time
 from pathlib import Path
 
-print(f"[kpaa-backend] SPACES_ZERO_GPU={os.environ.get('SPACES_ZERO_GPU')!r}", flush=True)
-print(f"[kpaa-backend] SPACE_ID={os.environ.get('SPACE_ID')!r}", flush=True)
-
-# HF Spaces: src/ on sys.path
+# HF Spaces 에서는 `pip install -e .` 가 동작하지 않는다 (requirements.txt 처리
+# 시점에 app 파일이 아직 mount 되지 않음). 대신 src/ 를 sys.path 에 prepend.
+# 로컬 editable install 환경에서도 무해.
 sys.path.insert(0, str(Path(__file__).resolve().parent / "src"))
 
 
-# ─── monkey-patch: gradio_client `/api_info` schema bug ────────────────────
-import gradio_client.utils as _gc_utils
+# ─── monkey-patch: Gradio /api_info schema bug ────────────────────────────
+# Gradio 5.x 의 gradio_client.utils 가 JSON Schema 의 `additionalProperties: True`
+# (bool, 합법적 형식) 를 dict 로만 가정해서 `if "const" in schema:` 에서 TypeError.
+# get_type 와 _json_schema_to_python_type 모두 bool 입력을 안전하게 처리하도록 wrap.
+import gradio_client.utils as _gc_utils  # noqa: E402
 
 _orig_get_type = _gc_utils.get_type
 _orig_jstpt = _gc_utils._json_schema_to_python_type
@@ -48,136 +49,42 @@ _gc_utils._json_schema_to_python_type = _safe_jstpt
 # ──────────────────────────────────────────────────────────────────────────
 
 
-import spaces
-import gradio as gr
-
-
-# ─── ZeroGPU canary wired to a Gradio event ───────────────────────────────
-# Critical insight: HF detector requires @spaces.GPU functions to be wired
-# to Gradio components, not standalone. So we keep `echo` as a real button
-# handler in the status UI.
-@spaces.GPU(duration=10)
-def echo(text: str) -> str:
-    import torch
-    device = "cuda" if torch.cuda.is_available() else "cpu"
-    return f"GPU echo ({device}): {text}"
-
-
-with gr.Blocks(title="KPAA Backend") as demo:
-    gr.Markdown(
-        """
-        # 🧠 KPAA Backend
-
-        한국 개인정보보호법 RAG 추론 백엔드.
-
-        ## API
-        - `POST /v1/chat/completions`
-        - `GET  /v1/models`
-        - `GET  /healthz`
-
-        UI 는 [`scvcoder/korean-privacy-ai-assistant`](https://huggingface.co/spaces/scvcoder/korean-privacy-ai-assistant) 에서 제공.
-
-        ---
-        ### GPU 진단
-        """
-    )
-    with gr.Row():
-        inp = gr.Textbox(label="입력", value="hello", scale=3)
-        out = gr.Textbox(label="출력 (GPU 검증)", scale=3)
-    btn = gr.Button("GPU echo 테스트")
-    btn.click(echo, inputs=inp, outputs=out)
-
-
-def _attach_kpaa_routes() -> None:
-    """Mount KPAA OpenAI-compatible /v1 routes onto demo's FastAPI.
-
-    Called AFTER demo.launch() — demo.app is the live Gradio FastAPI by then.
-    """
-    from kpaa.server import create_app
-    kpaa_app = create_app()
-
-    n_added = 0
-    skipped = 0
-    for route in kpaa_app.routes:
-        path = getattr(route, "path", None)
-        if path in ("/", None):
-            skipped += 1
-            continue
-        demo.app.routes.append(route)
-        n_added += 1
-    print(f"[kpaa-backend] attached {n_added} KPAA routes (skipped {skipped})", flush=True)
-
-
-def _attach_split_view() -> None:
-    """`/split` endpoint — Open WebUI iframe + 참고자료 polling 분할 레이아웃.
-
-    KPAA local 의 _SPLIT_HTML 을 그대로 재사용하되 iframe src 만 UI Space URL 로
-    교체. / 접속 시 /split 으로 리다이렉트 — Gradio 가 / 를 점유하지만 우리
-    redirect 라우트를 routes 리스트 *앞* 에 끼워넣어 우선권 획득.
-    """
-    from fastapi.responses import HTMLResponse, RedirectResponse
-    from fastapi.routing import APIRoute
-
-    from kpaa.server import _SPLIT_HTML
-
-    UI_SPACE_URL = "https://scvcoder-korean-privacy-ai-assistant.hf.space"
-    hf_html = _SPLIT_HTML.replace(
-        'src="http://localhost:8080/"',
-        f'src="{UI_SPACE_URL}"',
-    )
-
-    # 핸들러 한 개를 /split 와 / 양쪽에 라우팅 — 동일 HTML + 페이지 진입 시
-    # 우측 참고자료 자동 초기화 (이전 세션 잔여 데이터 노출 방지).
-    async def _split_handler():
-        import time as _time
-        from kpaa.server import _last_refs
-
-        _last_refs.update({
-            "ts": _time.time(),
-            "query": "",
-            "intents": [],
-            "jo_targets": [],
-            "elapsed_ms": 0,
-            "excerpts": [],
-            "cited_citations": [],
-            "llm_excerpt_citations": [],
-            "geungeo_indices_in_answer": [],
-        })
-        return HTMLResponse(hf_html)
-
-    # /split — 명시적 별칭 (백워드 호환).
-    demo.app.routes.insert(
-        0,
-        APIRoute("/split", _split_handler, methods=["GET"], include_in_schema=False),
-    )
+# ─── HF Spaces ZeroGPU startup canary ─────────────────────────────────────
+# HF Spaces 의 ZeroGPU 는 startup 시점에 module-level `@spaces.GPU` 함수가
+# 적어도 하나 검출되어야 GPU 스케줄을 잡는다. 실제 GPU 작업은
+# ZeroGPUBackend.stream_chat 안의 `_run_generate` 에서 일어나지만, 그건 함수
+# 호출 시점에야 데코레이트되므로 startup 스캔에서 안 보임.
+# 본 카나리는 호출되지 않으며, 단지 detector 통과용.
+try:
+    import spaces  # type: ignore[import-not-found]
+
+    @spaces.GPU(duration=1)
+    def _zerogpu_startup_canary() -> None:
+        """HF Spaces ZeroGPU detector 통과용 sentinel."""
+        return None
+except ImportError:
+    pass  # 로컬 dev — spaces 패키지 없음
+# ──────────────────────────────────────────────────────────────────────────
 
-    # / — Gradio 의 / 보다 *앞* 에 끼워 넣어 우선권 획득. 사용자가 백엔드 URL 만
-    # 입력해도 분할 화면이 바로 보임. Gradio status UI 는 더 이상 노출되지 않지만
-    # ZeroGPU 검출은 module-level @spaces.GPU 캐나리로 이미 충족됨.
-    demo.app.routes.insert(
-        0,
-        APIRoute("/", _split_handler, methods=["GET"], include_in_schema=False),
-    )
 
-    print(f"[kpaa-backend] / and /split serve split HTML (UI iframe -> {UI_SPACE_URL})", flush=True)
+from kpaa.ui.gradio import build_app  # noqa: E402
 
 
-if __name__ == "__main__":
-    # Launch Gradio in a non-blocking way so we can patch demo.app afterwards.
-    demo.queue()
-    demo.launch(
+def main() -> None:
+    app = build_app()
+    # HF Spaces 는 7860 노출 표준. 로컬 미리보기도 동일 포트 사용.
+    port = int(os.environ.get("PORT", "7860"))
+    # 큐 활성화 — async generator (스트리밍) 이 작동하려면 필수.
+    # ssr_mode=False  — Node SSR 서브프로세스 없이 순수 uvicorn 으로 단일 프로세스화.
+    # show_api=False  — /api_info 노출 스킵 (위 monkey-patch 와 함께 belt-and-suspenders).
+    app.queue(max_size=20).launch(
         server_name="0.0.0.0",
-        server_port=int(os.environ.get("PORT", "7860")),
+        server_port=port,
+        show_error=True,
         ssr_mode=False,
         show_api=False,
-        prevent_thread_lock=True,
     )
 
-    # demo.app is now a live Starlette/FastAPI app — attach KPAA routes + split view.
-    _attach_kpaa_routes()
-    _attach_split_view()
-    print("[kpaa-backend] ready: Gradio at /, /v1/... API, /split (Open WebUI + 참고자료)", flush=True)
 
-    # Block forever (Gradio runs on background thread).
-    while True:
-        time.sleep(60)
+if __name__ == "__main__":
+    main()

app_backend.py

@@ -0,0 +1,183 @@
+"""KPAA Backend Space — Gradio + ZeroGPU + KPAA OpenAI-compatible API.
+
+Strategy validated via minimal test:
+  - demo.launch() (Gradio's own uvicorn) is the path that activates ZeroGPU.
+  - mount_gradio_app + manual uvicorn does NOT activate ZeroGPU.
+
+So we use demo.launch(), and AFTER launch we attach KPAA's /v1 routes to
+the underlying FastAPI (demo.app) via app.include_router. Routes added at
+runtime are picked up because Starlette dispatches by traversing app.routes
+on each request.
+
+Hardware: ZeroGPU (zero-a10g).
+Required secret: LAW_OC.
+"""
+import os
+import sys
+import time
+from pathlib import Path
+
+print(f"[kpaa-backend] SPACES_ZERO_GPU={os.environ.get('SPACES_ZERO_GPU')!r}", flush=True)
+print(f"[kpaa-backend] SPACE_ID={os.environ.get('SPACE_ID')!r}", flush=True)
+
+# HF Spaces: src/ on sys.path
+sys.path.insert(0, str(Path(__file__).resolve().parent / "src"))
+
+
+# ─── monkey-patch: gradio_client `/api_info` schema bug ────────────────────
+import gradio_client.utils as _gc_utils
+
+_orig_get_type = _gc_utils.get_type
+_orig_jstpt = _gc_utils._json_schema_to_python_type
+
+
+def _safe_get_type(schema):
+    if not isinstance(schema, dict):
+        return ""
+    return _orig_get_type(schema)
+
+
+def _safe_jstpt(schema, defs):
+    if not isinstance(schema, dict):
+        return "Any"
+    return _orig_jstpt(schema, defs)
+
+
+_gc_utils.get_type = _safe_get_type
+_gc_utils._json_schema_to_python_type = _safe_jstpt
+# ──────────────────────────────────────────────────────────────────────────
+
+
+import spaces
+import gradio as gr
+
+
+# ─── ZeroGPU canary wired to a Gradio event ───────────────────────────────
+# Critical insight: HF detector requires @spaces.GPU functions to be wired
+# to Gradio components, not standalone. So we keep `echo` as a real button
+# handler in the status UI.
+@spaces.GPU(duration=10)
+def echo(text: str) -> str:
+    import torch
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    return f"GPU echo ({device}): {text}"
+
+
+with gr.Blocks(title="KPAA Backend") as demo:
+    gr.Markdown(
+        """
+        # 🧠 KPAA Backend
+
+        한국 개인정보보호법 RAG 추론 백엔드.
+
+        ## API
+        - `POST /v1/chat/completions`
+        - `GET  /v1/models`
+        - `GET  /healthz`
+
+        UI 는 [`scvcoder/korean-privacy-ai-assistant`](https://huggingface.co/spaces/scvcoder/korean-privacy-ai-assistant) 에서 제공.
+
+        ---
+        ### GPU 진단
+        """
+    )
+    with gr.Row():
+        inp = gr.Textbox(label="입력", value="hello", scale=3)
+        out = gr.Textbox(label="출력 (GPU 검증)", scale=3)
+    btn = gr.Button("GPU echo 테스트")
+    btn.click(echo, inputs=inp, outputs=out)
+
+
+def _attach_kpaa_routes() -> None:
+    """Mount KPAA OpenAI-compatible /v1 routes onto demo's FastAPI.
+
+    Called AFTER demo.launch() — demo.app is the live Gradio FastAPI by then.
+    """
+    from kpaa.server import create_app
+    kpaa_app = create_app()
+
+    n_added = 0
+    skipped = 0
+    for route in kpaa_app.routes:
+        path = getattr(route, "path", None)
+        if path in ("/", None):
+            skipped += 1
+            continue
+        demo.app.routes.append(route)
+        n_added += 1
+    print(f"[kpaa-backend] attached {n_added} KPAA routes (skipped {skipped})", flush=True)
+
+
+def _attach_split_view() -> None:
+    """`/split` endpoint — Open WebUI iframe + 참고자료 polling 분할 레이아웃.
+
+    KPAA local 의 _SPLIT_HTML 을 그대로 재사용하되 iframe src 만 UI Space URL 로
+    교체. / 접속 시 /split 으로 리다이렉트 — Gradio 가 / 를 점유하지만 우리
+    redirect 라우트를 routes 리스트 *앞* 에 끼워넣어 우선권 획득.
+    """
+    from fastapi.responses import HTMLResponse, RedirectResponse
+    from fastapi.routing import APIRoute
+
+    from kpaa.server import _SPLIT_HTML
+
+    UI_SPACE_URL = "https://scvcoder-korean-privacy-ai-assistant.hf.space"
+    hf_html = _SPLIT_HTML.replace(
+        'src="http://localhost:8080/"',
+        f'src="{UI_SPACE_URL}"',
+    )
+
+    # 핸들러 한 개를 /split 와 / 양쪽에 라우팅 — 동일 HTML + 페이지 진입 시
+    # 우측 참고자료 자동 초기화 (이전 세션 잔여 데이터 노출 방지).
+    async def _split_handler():
+        import time as _time
+        from kpaa.server import _last_refs
+
+        _last_refs.update({
+            "ts": _time.time(),
+            "query": "",
+            "intents": [],
+            "jo_targets": [],
+            "elapsed_ms": 0,
+            "excerpts": [],
+            "cited_citations": [],
+            "llm_excerpt_citations": [],
+            "geungeo_indices_in_answer": [],
+        })
+        return HTMLResponse(hf_html)
+
+    # /split — 명시적 별칭 (백워드 호환).
+    demo.app.routes.insert(
+        0,
+        APIRoute("/split", _split_handler, methods=["GET"], include_in_schema=False),
+    )
+
+    # / — Gradio 의 / 보다 *앞* 에 끼워 넣어 우선권 획득. 사용자가 백엔드 URL 만
+    # 입력해도 분할 화면이 바로 보임. Gradio status UI 는 더 이상 노출되지 않지만
+    # ZeroGPU 검출은 module-level @spaces.GPU 캐나리로 이미 충족됨.
+    demo.app.routes.insert(
+        0,
+        APIRoute("/", _split_handler, methods=["GET"], include_in_schema=False),
+    )
+
+    print(f"[kpaa-backend] / and /split serve split HTML (UI iframe -> {UI_SPACE_URL})", flush=True)
+
+
+if __name__ == "__main__":
+    # Launch Gradio in a non-blocking way so we can patch demo.app afterwards.
+    demo.queue()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", "7860")),
+        ssr_mode=False,
+        show_api=False,
+        prevent_thread_lock=True,
+    )
+
+    # demo.app is now a live Starlette/FastAPI app — attach KPAA routes + split view.
+    _attach_kpaa_routes()
+    _attach_split_view()
+    print("[kpaa-backend] ready: Gradio at /, /v1/... API, /split (Open WebUI + 참고자료)", flush=True)
+
+    # Block forever (Gradio runs on background thread).
+    while True:
+        time.sleep(60)

data/hf_dataset/README.md

@@ -0,0 +1,271 @@
+---
+language:
+- ko
+license: other
+license_name: pipc-attribution
+license_link: LICENSE.md
+pretty_name: Korean Privacy Law RAG Corpus
+size_categories:
+- 1K<n<10K
+task_categories:
+- question-answering
+- text-retrieval
+- text-generation
+tags:
+- legal
+- privacy
+- korean
+- rag
+- retrieval-augmented-generation
+- contextual-retrieval
+- pipa
+- pipc
+- privacy-law
+configs:
+- config_name: default
+  data_files:
+  - split: train
+    path: "*.jsonl"
+---
+
+# 한국 개인정보보호법 관련 RAG 구축을 위한 코퍼스
+
+개인정보 포털(privacy.go.kr)의 각종 개인정보보호법 관련 가이드와 상담사례 1,745건을
+RAG(Retrieval-Augmented Generation)에 바로 쓸 수 있도록 **의미 단위 청킹·문맥 보강**한
+코퍼스입니다. 모든 청크에는 [Contextual Retrieval](https://www.anthropic.com/news/contextual-retrieval)
+기법을 적용한 `chunk_context` 필드가 포함되어 있어, 임베딩 검색 정확도를 즉시 끌어올릴
+수 있습니다.
+
+테스트링크: https://scvcoder-kpaa.hf.space/
+
+### 구성
+
+- 개인정보_질의응답_모음집(2025.12.).pdf
+- 소상공인을_위한_개인정보 보호_핸드북(2024.12).pdf
+- 고정형 영상정보처리기기_설치_운영_안내서(2024.12).pdf
+- 분야별 개인정보 보호 안내서(2024.12).pdf — 의료기관 편까지 청킹 완료(부분 공개), 약국·학원·통계·공공·온라인 경품 편 추가 예정
+- 개인정보포털 홈페이지 상담사례 1745건
+
+**English** — A Korean RAG corpus on personal information protection law (PIPA),
+built from official guides and 1,745 consultation cases published on the
+Personal Information Portal (privacy.go.kr). Each chunk is semantically
+segmented and enriched with a `chunk_context` field following the Contextual
+Retrieval technique — ready to drop into a RAG pipeline and improve
+embedding-search accuracy out of the box.
+
+---
+
+## 1. 데이터셋 개요
+
+| 항목 | 값 |
+|---|---|
+| 총 레코드 수 | **2,202** 청크 |
+| 언어 | 한국어 |
+| 도메인 | 개인정보보호법(PIPA) · 개인정보보호 실무 |
+| 형식 | JSON Lines (`.jsonl`) |
+| 인코딩 | UTF-8 |
+| 출처 | 개인정보보호위원회 (자세한 내용은 §7 참조) |
+| 적용 기법 | Semantic Chunking, Contextual Retrieval |
+
+### 구성 (`source_type`으로 필터링)
+
+| 파일 | `source_type` | 청크 수 | 출처 | 발행/수집 시점 |
+|---|---|---:|---|---|
+| 개인정보_질의응답_모음집(2025.12.).jsonl | `guide` | 99 | PIPC 공식 가이드 PDF | 2025.12 |
+| 소상공인을_위한_개인정보 보호_핸드북(2024.12).jsonl | `guide` | 41 | PIPC 공식 가이드 PDF | 2024.12 |
+| 고정형 영상정보처리기기_설치_운영_안내서(2024.12).jsonl | `guide` | 71 | PIPC 공식 가이드 PDF | 2024.12 |
+| 분야별_개인정보_보호_안내서(2024.12).jsonl | `guide` | 246 *(진행 중)* | PIPC 공식 가이드 PDF — 8개 편 중 인사·노무, 사회복지시설, 의료기관 편 완료 | 2024.12 |
+| 개인정보포털_상담사례.jsonl | `case` | 1,745 | privacy.go.kr 상담사례 | 2012~ 누적 |
+
+---
+
+## 2. 스키마
+
+모든 레코드는 다음 **공통 필드**(앞 10개)를 갖고, 그 뒤에 출처별 필드가 이어집니다.
+출처별 원본 필드는 모두 보존했습니다.
+
+### 공통 필드
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `chunk_id` | string | 청크 고유 ID (예: `질의응답_모음집_0000`, `상담사례_0001`) |
+| `source_type` | string | `"guide"` 또는 `"case"` |
+| `doc_id` | string | 원문 문서 식별자 |
+| `doc_title` | string | 원문 제목 |
+| `doc_date` | string | 발행일 (`YYYY.MM` 또는 `YYYY.MM.DD`) |
+| `section` | string | 장·절·카테고리 (가이드: 목차, 사례: `대분류 > 중분류 > 소분류`) |
+| `body` | string | **임베딩 대상 본문** |
+| `chunk_context` | string | Contextual Retrieval — 본문이 속한 맥락·인접 조항·법 근거 요약 |
+| `source_pdf` | string | 가이드의 원본 PDF 파일명 (사례는 빈 문자열) |
+| `source_url` | string | 사례의 원본 URL (가이드는 빈 문자열) |
+
+### 가이드(`source_type="guide"`) 추가 필드
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `chunk_no` | int | 문서 내 청크 일련번호 |
+| `pages` | string | 책의 페이지 번호 (예: `"p.3"`) |
+
+### 상담사례(`source_type="case"`) 추가 필드
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `ntt_id`, `ntt_no` | string | privacy.go.kr 게시물 ID |
+| `title` | string | 사례 제목(질문) |
+| `summary` | string | 사례 요약 |
+| `type_code`, `type_label` | string | 사례 유형 (`COU` = 상담 사례집 등) |
+| `category1`, `category2`, `category3` | string | 분류 체계 |
+| `reg_dt` | string | 등록일 (`YYYYMMDD`) |
+| `case_year` | string | 사례 연도 |
+| `source_note` | string | 출처 주석 |
+| `detail_url` | string | privacy.go.kr 상세 경로 |
+
+---
+
+## 3. 샘플 레코드
+
+### 가이드 청크 예시
+
+```json
+{
+  "chunk_id": "질의응답_모음집_0000",
+  "source_type": "guide",
+  "doc_id": "질의응답_모음집",
+  "doc_title": "개인정보 질의응답 모음집",
+  "doc_date": "2025.12",
+  "section": "I.정의 [Q&A] Q1 ID와 결제상품정보가 개인정보에 해당",
+  "body": "Q1 ID와 결제상품정보가 개인정보에 해당하나요? …",
+  "chunk_context": "이 청크는 「개인정보 질의응답 모음집(2025.12)」 Ⅰ.정의 영역 첫 사례(Q1, 책 p.3)로, …",
+  "source_pdf": "1. 개인정보 질의응답 모음집(2025.12.).pdf",
+  "source_url": "",
+  "chunk_no": 0,
+  "pages": "p.3"
+}
+```
+
+### 상담사례 청크 예시
+
+```json
+{
+  "chunk_id": "상담사례_0001",
+  "source_type": "case",
+  "doc_id": "개인정보포털_상담사례",
+  "doc_title": "개인정보포털 상담사례",
+  "doc_date": "2012.01.20",
+  "section": "개인정보처리자(민간) > 개인정보 수집·이용 > 보건·의료",
+  "body": "Q) 의료기관에 환자가 처음으로 내원한 경우에 …",
+  "chunk_context": "이 청크는 「개인정보 상담사례 #1(2012, privacy.go.kr)」 보건·의료 업종 …",
+  "source_pdf": "",
+  "source_url": "https://www.privacy.go.kr/front/case/view.do?ntt_id=1&nttno=1",
+  "ntt_id": "1",
+  "title": "병원에서 초진 환자의 개인정보 수집시 동의 취득 여부",
+  "category1": "개인정보처리자(민간)",
+  "category2": "개인정보 수집·이용",
+  "category3": "보건·의료",
+  "reg_dt": "20120120",
+  "case_year": "2012"
+}
+```
+
+---
+
+## 4. 사용 예시
+
+### 🤗 Datasets 로드
+
+```python
+from datasets import load_dataset
+
+ds = load_dataset("scvcoder/korean-privacy-law-corpus", split="train")
+
+guides = ds.filter(lambda x: x["source_type"] == "guide")  # 457
+cases  = ds.filter(lambda x: x["source_type"] == "case")   # 1,745
+```
+
+### 임베딩 시 권장: `chunk_context` + `body` 결합
+
+Contextual Retrieval 방식에 따라 임베딩 입력은 두 필드를 합쳐 사용하는 것을 권장합니다.
+
+```python
+def to_embedding_text(rec: dict) -> str:
+    return f"{rec['chunk_context']}\n\n{rec['body']}"
+```
+
+### BM25 / 하이브리드 검색
+
+`body`만 BM25 색인에 넣어도 무방하나, `chunk_context`까지 함께 색인하면 짧은 질의에서 회수율이
+크게 향상됩니다(특히 법조항 단편 검색).
+
+---
+
+## 5. 데이터 수집·가공 방법
+
+1. **원천 수집**
+   - 가이드 PDF 3종: PIPC 발행 공식 가이드 다운로드
+   - 상담사례: privacy.go.kr 상담사례 게시판 1,745건 수집
+2. **PDF → 청크 변환**
+   - 사람이 검토하는 인터랙티브 청킹 파이프라인. 책의 페이지·절 단위를 우선시하되,
+     의미가 끊기는 곳에서 청크 경계를 두었습니다 (1청크 ≈ 200~600 한국어 어절).
+3. **Contextual Retrieval 적용**
+   - 각 청크에 대해 인접 조항·법조 근거·도식 의미를 자연어로 요약한 `chunk_context`를 LLM으로 생성하고,
+     문서 작성자가 검수.
+4. **표준화**
+   - 본 코퍼스 단위로 공통 필드 10개를 모든 레코드에 도입(원본 필드 유지).
+
+---
+
+## 6. 활용 케이스
+
+- **Korean privacy assistant ai 챗봇** — 소상공인·작은병원·학교 등 비전문가용 상담 RAG.
+- **법률 LLM 파인튜닝의 retrieval 평가셋** — `title`/`body`를 질의·정답 쌍으로 변환 가능.
+- **한국어 법률·규제 도메인 retrieval 벤치마크** — 도메인 시프트(일반 ↔ 법률) 평가.
+
+---
+
+## 7. 출처표시
+
+본 데이터셋의 출처는 개인정보보호위원회의 가이드와 개인정보 포털(privacy.go.kr)의
+상담자료임을 밝힙니다. 본 데이터셋을 사용·인용·재배포할 때는 반드시 다음 출처를
+명시해 주십시오.
+
+### 원자료 출처
+
+1. 개인정보보호위원회, 「개인정보 질의응답 모음집」 2025.12.
+2. 개인정보보호위원회, 「소상공인을 위한 개인정보 보호 핸드북」 2024.12.
+3. 개인정보보호위원회, 「고정형 영상정보처리기기 설치·운영 안내서(공공 및 민간분야 통합본)」 2024.12.
+4. 개인정보보호위원회·보건복지부 등, 「분야별 개인정보 보호 안내서」 2024.12.
+5. 개인정보 포털 상담사례 : https://www.privacy.go.kr/front/case/list.do
+
+### 가공
+
+Semantic Chunking 및 Contextual Retrieval 기법으로 작성한 맥락 요약, 표준화 스키마는
+본 데이터셋 기여자의 2차 저작물이며, 위와 동일 조건으로 이용 가능합니다.
+
+원저작자가 전부 또는 일부의 삭제 또는 수정 요청을 할 경우 즉시 조치하겠습니다.
+
+1. Korean Privacy Law RAG Corpus (https://huggingface.co/datasets/scvcoder/korean-privacy-law-corpus)
+2. 가공내용 : Semantic Chunking, Contextual Retrieval 추가 등
+
+---
+
+## 8. 한계 및 주의사항
+
+- **법률 자문이 아닙니다.** 본 데이터는 교육·연구·도구 개발용이며, 구체적 사안에 대한 법적 판단은
+  전문��의 자문을 받아야 합니다.
+- **시점 기준** — 가이드는 발행일(2024.12 / 2025.12) 기준이며, 이후 법 개정이 있을 수 있습니다.
+  변경사항은 현행 법령을 확인하세요.
+- **상담사례** — privacy.go.kr 상담사례는 PIPC가 개별 사안에 회신한 답변으로,
+  유사한 사안에서도 사실관계가 다르면 결론이 달라질 수 있습니다.
+
+---
+
+## 9. 변경 이력
+
+| 버전 | 일자 | 내용 |
+|---|---|---|
+| v1.0 | 2026-05-02 | 최초 공개 — 가이드 3종 211청크 + 상담사례 1,745건, 표준화 스키마 적용 |
+| v1.1 | 2026-05-05 | 분야별 개인정보 보호 안내서(2024.12) 의료기관 편까지 청킹 246청크 부분 공개 (인사·노무 32 + 사회복지시설 72 + 의료기관 142). 약국·학원·통계·공공·온라인 경품 5개 편은 추가 작업 후 v1.2에서 공개 예정. 기존 가이드 3종(질의응답·핸드북·CCTV)도 `chunk_context` 보완 |
+
+---
+
+*Compiled and curated by [scvcoder](https://huggingface.co/scvcoder).*

docker-compose.yml

@@ -0,0 +1,61 @@
+# KPAA all-in-one — backend(=FastAPI + llama-cpp-python 임베드) + Open WebUI.
+# 외부 추론 데몬·서비스 없는 단일 프로세스 구성.
+#
+# 사용:
+#     cp .env.example .env       # LAW_OC=... 입력
+#     docker compose up -d
+#     # → http://localhost:3000 (Open WebUI)
+#
+# 첫 실행 시 backend 컨테이너가 Gemma 4 E2B GGUF (~3.2GB)을 자동으로
+# `kpaa-models` 볼륨에 받음. 5~15분 소요. `docker compose logs -f backend` 로 진행 확인.
+
+services:
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: kpaa-backend:latest
+    restart: unless-stopped
+    environment:
+      - LAW_OC=${LAW_OC:-}
+      - KPAA_HOST=0.0.0.0
+      - KPAA_PORT=8000
+      # GPU offload 는 *자동 감지*. 강제 override 시 host shell 에서 export:
+      #     KPAA_N_GPU_LAYERS=-1 docker compose up
+      - KPAA_N_GPU_LAYERS=${KPAA_N_GPU_LAYERS:-}
+    volumes:
+      - kpaa-models:/root/.cache/kpaa   # 모델 + 법제처 캐시 영속화
+    ports:
+      - "8000:8000"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8000/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 5
+      start_period: 60s   # 첫 모델 로드까지 시간 여유
+
+  open-webui:
+    image: ghcr.io/open-webui/open-webui:main
+    restart: unless-stopped
+    depends_on:
+      backend:
+        condition: service_started
+    environment:
+      # backend의 OpenAI-호환 endpoint를 미리 주입 — UI에서 별도 설정 불필요
+      - OPENAI_API_BASE_URLS=http://backend:8000/v1
+      - OPENAI_API_KEYS=local
+      - WEBUI_NAME=KPAA — 개인정보보호법 상담
+      # 백엔드 default preset(`gemma-4-e2b-q4`) 과 동일. dropdown 에서
+      # 다른 프리셋을 고르면 백엔드 ModelManager 가 자동 전환.
+      - DEFAULT_MODELS=개인정보 상담 AI(gemma-4-e2b-q4)
+      # OpenWebUI 의 Ollama 자동 감지 차단 — KPAA backend(:8000) 만 사용.
+      - ENABLE_OLLAMA_API=false
+      - DEFAULT_USER_ROLE=admin
+    volumes:
+      - open-webui-data:/app/backend/data
+    ports:
+      - "3000:8080"
+
+volumes:
+  kpaa-models:
+  open-webui-data:

manage.sh

@@ -0,0 +1,326 @@
+#!/usr/bin/env bash
+# KPAA 백엔드 + Open WebUI 통합 관리 스크립트.
+#
+# 사용법:
+#   ./manage.sh start     KPAA + Open WebUI 백그라운드 기동, ready 대기까지
+#   ./manage.sh stop      양쪽 모두 정확한 종료 (PID 파일 기반)
+#   ./manage.sh restart   stop → start
+#   ./manage.sh status    실행 여부 + PID + 포트 (양쪽)
+#   ./manage.sh logs      KPAA 로그 tail
+#   ./manage.sh logs-owui Open WebUI 로그 tail
+#
+# 환경변수 (KPAA):
+#   KPAA_HOST           기본 127.0.0.1
+#   KPAA_PORT           기본 8000
+#   KPAA_LOG_FILE       기본 /tmp/kpaa_serve.log
+#   KPAA_PID_FILE       기본 ./.run/kpaa.pid
+#   KPAA_READY_TIMEOUT  기본 90 (초)
+#
+# 환경변수 (Open WebUI):
+#   KPAA_OPENWEBUI_ENABLED       기본 1 (0 으로 비활성화)
+#   KPAA_OPENWEBUI_BIN           기본 ~/.kpaa-owui/bin/open-webui (PATH 폴백)
+#   KPAA_OPENWEBUI_HOST          기본 127.0.0.1
+#   KPAA_OPENWEBUI_PORT          기본 8080
+#   KPAA_OPENWEBUI_LOG_FILE      기본 /tmp/kpaa_openwebui.log
+#   KPAA_OPENWEBUI_READY_TIMEOUT 기본 120 (초, 첫 부팅 시 모델 다운로드 등 변수)
+#   KPAA_OPENWEBUI_OPENAI_BASE_URLS  기본 http://${KPAA_HOST}:${KPAA_PORT}/v1
+#                                (`;` 구분으로 다중 endpoint 가능)
+#   KPAA_OPENWEBUI_OPENAI_KEYS   기본 local
+#   KPAA_OPENWEBUI_DEFAULT_MODELS 기본 kpaa-privacy-ko (UI 첫 default 모델)
+#   KPAA_OPENWEBUI_NAME          기본 "KPAA — 개인정보보호법 상담"
+#   KPAA_OPENWEBUI_WEBUI_AUTH    기본 false — true 로 두면 본인 이메일/비밀번호 가입·로그인.
+#                                기본은 admin@localhost/admin 자동 생성·로그인 (로컬 전용).
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT_DIR"
+
+# ── KPAA ─────────────────────────────────────────────────────────────
+HOST="${KPAA_HOST:-127.0.0.1}"
+PORT="${KPAA_PORT:-8000}"
+LOG_FILE="${KPAA_LOG_FILE:-/tmp/kpaa_serve.log}"
+PID_DIR="${ROOT_DIR}/.run"
+PID_FILE="${KPAA_PID_FILE:-${PID_DIR}/kpaa.pid}"
+VENV_BIN="${ROOT_DIR}/.venv/bin"
+HEALTH_URL="http://${HOST}:${PORT}/v1/models"
+READY_TIMEOUT_S="${KPAA_READY_TIMEOUT:-90}"
+
+# ── Open WebUI ────────────────────────────────────────────────────────
+OWUI_ENABLED="${KPAA_OPENWEBUI_ENABLED:-1}"
+OWUI_BIN_DEFAULT="${HOME}/.kpaa-owui/bin/open-webui"
+OWUI_BIN="${KPAA_OPENWEBUI_BIN:-$OWUI_BIN_DEFAULT}"
+if [[ ! -x "$OWUI_BIN" ]] && command -v open-webui >/dev/null 2>&1; then
+  OWUI_BIN="$(command -v open-webui)"
+fi
+OWUI_HOST="${KPAA_OPENWEBUI_HOST:-127.0.0.1}"
+OWUI_PORT="${KPAA_OPENWEBUI_PORT:-8080}"
+OWUI_LOG_FILE="${KPAA_OPENWEBUI_LOG_FILE:-/tmp/kpaa_openwebui.log}"
+OWUI_PID_FILE="${PID_DIR}/openwebui.pid"
+OWUI_HEALTH_URL="http://${OWUI_HOST}:${OWUI_PORT}/health"
+OWUI_READY_TIMEOUT_S="${KPAA_OPENWEBUI_READY_TIMEOUT:-120}"
+
+C_GREEN='\033[0;32m'; C_YELLOW='\033[0;33m'; C_RED='\033[0;31m'; C_RESET='\033[0m'
+ok()   { printf "${C_GREEN}✓${C_RESET} %s\n" "$*"; }
+warn() { printf "${C_YELLOW}!${C_RESET} %s\n" "$*"; }
+err()  { printf "${C_RED}✗${C_RESET} %s\n" "$*" >&2; }
+
+# ── 공통 PID 헬퍼 ────────────────────────────────────────────────────
+is_alive() {
+  local pid="$1"
+  [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null
+}
+
+read_pid() {
+  local f="$1"
+  [[ -f "$f" ]] && cat "$f" 2>/dev/null || true
+}
+
+current_pid() {
+  # PID 파일 우선. 없거나 죽었으면 빈값. 포트로 *추론하지 않음* — Chrome 등
+  # 무관한 클라이언트 프로세스를 잘못 죽이는 사고 방지.
+  local pid; pid="$(read_pid "$1")"
+  if is_alive "$pid"; then
+    echo "$pid"
+  else
+    echo ""
+  fi
+}
+
+wait_health() {
+  local url="$1" timeout="$2" label="$3"
+  local deadline=$(( $(date +%s) + timeout ))
+  while (( $(date +%s) < deadline )); do
+    if curl -fsS --max-time 2 "$url" > /dev/null 2>&1; then
+      return 0
+    fi
+    sleep 1
+  done
+  return 1
+}
+
+# ── KPAA 시작 ────────────────────────────────────────────────────────
+start_kpaa() {
+  local existing; existing="$(current_pid "$PID_FILE")"
+  if [[ -n "$existing" ]]; then
+    warn "[kpaa] 이미 기동 중 (pid=$existing)"
+    return 0
+  fi
+
+  if [[ ! -x "${VENV_BIN}/kpaa" ]]; then
+    err "${VENV_BIN}/kpaa 가 없습니다. 가상환경을 먼저 활성화/설치하세요."
+    return 1
+  fi
+
+  if lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN >/dev/null 2>&1; then
+    err "[kpaa] 포트 ${PORT} 이미 점유."
+    lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN >&2
+    return 1
+  fi
+
+  mkdir -p "$PID_DIR"
+  : > "$LOG_FILE"
+
+  nohup "${VENV_BIN}/kpaa" serve --host "$HOST" --port "$PORT" \
+      >> "$LOG_FILE" 2>&1 &
+  local pid=$!
+  echo "$pid" > "$PID_FILE"
+  ok "[kpaa] 기동 시도 (pid=$pid, log=$LOG_FILE)"
+
+  if wait_health "$HEALTH_URL" "$READY_TIMEOUT_S" "kpaa"; then
+    ok "[kpaa] 준비 완료 — ${HEALTH_URL}"
+    return 0
+  fi
+  err "[kpaa] ${READY_TIMEOUT_S}초 내 ready 응답 없음. tail -n 80 $LOG_FILE"
+  return 1
+}
+
+# ── Open WebUI 시작 ──────────────────────────────────────────────────
+start_owui() {
+  if [[ "$OWUI_ENABLED" != "1" ]]; then
+    warn "[owui] 비활성화 (KPAA_OPENWEBUI_ENABLED=$OWUI_ENABLED) — 건너뜀"
+    return 0
+  fi
+  if [[ ! -x "$OWUI_BIN" ]]; then
+    warn "[owui] 실행 파일을 찾지 못함: $OWUI_BIN"
+    warn "      설치: pip install open-webui (전용 venv 권장: ${OWUI_BIN_DEFAULT%/bin/*})"
+    warn "      이 기능 영구 비활성화: export KPAA_OPENWEBUI_ENABLED=0"
+    return 0
+  fi
+
+  local existing; existing="$(current_pid "$OWUI_PID_FILE")"
+  if [[ -n "$existing" ]]; then
+    warn "[owui] 이미 기동 중 (pid=$existing)"
+    return 0
+  fi
+
+  if lsof -nP -iTCP:"${OWUI_PORT}" -sTCP:LISTEN >/dev/null 2>&1; then
+    err "[owui] 포트 ${OWUI_PORT} 이미 점유."
+    lsof -nP -iTCP:"${OWUI_PORT}" -sTCP:LISTEN >&2
+    return 1
+  fi
+
+  mkdir -p "$PID_DIR"
+  : > "$OWUI_LOG_FILE"
+
+  # OpenWebUI 가 KPAA backend 의 OpenAI 호환 endpoint 를 자동으로 부르도록
+  # 환경변수 주입 — docker-compose.yml 의 동일 패턴.
+  #
+  # KPAA 는 llama-cpp-python 임베드 단일 경로라, OpenWebUI 의 외부 추론 데몬
+  # 자동 감지(`ENABLE_OLLAMA_API`)는 항상 차단 — KPAA 백엔드만 사용.
+  local owui_envs=()
+  owui_envs+=("OPENAI_API_BASE_URLS=${KPAA_OPENWEBUI_OPENAI_BASE_URLS:-http://${HOST}:${PORT}/v1}")
+  owui_envs+=("OPENAI_API_KEYS=${KPAA_OPENWEBUI_OPENAI_KEYS:-local}")
+  owui_envs+=("DEFAULT_MODELS=${KPAA_OPENWEBUI_DEFAULT_MODELS:-kpaa-privacy-ko}")
+  owui_envs+=("WEBUI_NAME=${KPAA_OPENWEBUI_NAME:-KPAA — 개인정보보호법 상담}")
+  owui_envs+=("ENABLE_OLLAMA_API=false")
+  # 로컬 단일 사용자 — 기본 false 시 OpenWebUI 가 admin@localhost/admin 자동 생성·로그인.
+  # 본인 이메일/비밀번호로 운영하려면 export KPAA_OPENWEBUI_WEBUI_AUTH=true 후 재시작.
+  # 자세한 내용 README "🔐 인증 모드" 참고.
+  owui_envs+=("WEBUI_AUTH=${KPAA_OPENWEBUI_WEBUI_AUTH:-false}")
+
+  # `open-webui serve` 인자: --host / --port 지원. 0.5+ 기준.
+  # `env -S` 대신 nohup 앞에 환경변수 prefix — bash 표준 호환.
+  nohup env "${owui_envs[@]}" "$OWUI_BIN" serve --host "$OWUI_HOST" --port "$OWUI_PORT" \
+      >> "$OWUI_LOG_FILE" 2>&1 &
+  local pid=$!
+  echo "$pid" > "$OWUI_PID_FILE"
+  ok "[owui] 기동 시도 (pid=$pid, log=$OWUI_LOG_FILE)"
+  ok "       OPENAI_API_BASE_URLS=${KPAA_OPENWEBUI_OPENAI_BASE_URLS:-http://${HOST}:${PORT}/v1}"
+
+  if wait_health "$OWUI_HEALTH_URL" "$OWUI_READY_TIMEOUT_S" "owui"; then
+    ok "[owui] 준비 완료 — ${OWUI_HEALTH_URL}"
+    return 0
+  fi
+  warn "[owui] ${OWUI_READY_TIMEOUT_S}초 내 ready 응답 없음. tail -n 80 $OWUI_LOG_FILE"
+  warn "      KPAA backend 는 정상 동작 — OpenAI-호환 API 직접 호출 가능: http://${HOST}:${PORT}/v1"
+  return 0   # owui 실패는 *전체 start 실패* 로 보지 않음 — KPAA 는 동작
+}
+
+# ── 종료 헬퍼 ────────────────────────────────────────────────────────
+stop_one() {
+  local label="$1" pid_file="$2"
+  local pid; pid="$(current_pid "$pid_file")"
+  if [[ -z "$pid" ]]; then
+    warn "[$label] 실행 중 아님"
+    [[ -f "$pid_file" ]] && rm -f "$pid_file"
+    return 0
+  fi
+  ok "[$label] SIGTERM (pid=$pid)"
+  kill "$pid" 2>/dev/null || true
+  local deadline=$(( $(date +%s) + 15 ))
+  while is_alive "$pid" && (( $(date +%s) < deadline )); do
+    sleep 1
+  done
+  if is_alive "$pid"; then
+    warn "[$label] SIGTERM 무응답. SIGKILL."
+    kill -9 "$pid" 2>/dev/null || true
+    sleep 1
+  fi
+  if is_alive "$pid"; then
+    err "[$label] 여전히 살아있음 (pid=$pid). 수동 점검 필요."
+    return 1
+  fi
+  rm -f "$pid_file"
+  ok "[$label] 종료 완료"
+}
+
+# ── 통합 명령 ────────────────────────────────────────────────────────
+cmd_start() {
+  start_kpaa || return 1
+  start_owui || true   # owui 실패가 KPAA 부팅을 막지 않게
+}
+
+cmd_stop() {
+  # 종료 순서: owui 먼저 (자식 클라이언트 → 백엔드 순으로 깨끗)
+  stop_one owui "$OWUI_PID_FILE" || true
+  stop_one kpaa "$PID_FILE" || true
+}
+
+cmd_restart() {
+  cmd_stop || true
+  cmd_start
+}
+
+cmd_status() {
+  local kpid opid
+  kpid="$(current_pid "$PID_FILE")"
+  opid="$(current_pid "$OWUI_PID_FILE")"
+
+  if [[ -n "$kpid" ]]; then
+    ok "[kpaa] RUNNING (pid=$kpid, port=$PORT)"
+    if curl -fsS --max-time 2 "$HEALTH_URL" >/dev/null 2>&1; then
+      ok "[kpaa] 헬스체크 OK — $HEALTH_URL"
+    else
+      warn "[kpaa] 프로세스 alive 이나 헬스체크 미응답 (부팅 중일 수 있음)"
+    fi
+  else
+    warn "[kpaa] STOPPED"
+    if lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN >/dev/null 2>&1; then
+      warn "      다만 포트 ${PORT} 다른 프로세스가 점유:"
+      lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN
+    fi
+  fi
+
+  if [[ "$OWUI_ENABLED" != "1" ]]; then
+    warn "[owui] 비활성화 (KPAA_OPENWEBUI_ENABLED=$OWUI_ENABLED)"
+  elif [[ -n "$opid" ]]; then
+    ok "[owui] RUNNING (pid=$opid, port=$OWUI_PORT)"
+    if curl -fsS --max-time 2 "$OWUI_HEALTH_URL" >/dev/null 2>&1; then
+      ok "[owui] 헬스체크 OK — $OWUI_HEALTH_URL"
+    else
+      warn "[owui] 프로세스 alive 이나 헬스체크 미응답 (부팅 중일 수 있음)"
+    fi
+  else
+    warn "[owui] STOPPED"
+    if lsof -nP -iTCP:"${OWUI_PORT}" -sTCP:LISTEN >/dev/null 2>&1; then
+      warn "      다만 포트 ${OWUI_PORT} 다른 프로세스가 점유:"
+      lsof -nP -iTCP:"${OWUI_PORT}" -sTCP:LISTEN
+    fi
+  fi
+
+  echo "logs:"
+  echo "  kpaa : $LOG_FILE"
+  echo "  owui : $OWUI_LOG_FILE"
+}
+
+cmd_logs() {
+  if [[ ! -f "$LOG_FILE" ]]; then
+    err "로그 파일 없음: $LOG_FILE"
+    return 1
+  fi
+  exec tail -n 200 -f "$LOG_FILE"
+}
+
+cmd_logs_owui() {
+  if [[ ! -f "$OWUI_LOG_FILE" ]]; then
+    err "로그 파일 없음: $OWUI_LOG_FILE"
+    return 1
+  fi
+  exec tail -n 200 -f "$OWUI_LOG_FILE"
+}
+
+usage() {
+  cat <<EOF
+사용법: $(basename "$0") {start|stop|restart|status|logs|logs-owui}
+
+KPAA 백엔드 + Open WebUI 를 함께 관리합니다.
+
+환경변수 (요약):
+  KPAA_HOST / KPAA_PORT                   백엔드 (기본 127.0.0.1:8000)
+  KPAA_OPENWEBUI_ENABLED                  0 으로 두면 OpenWebUI 미동반
+  KPAA_OPENWEBUI_HOST / KPAA_OPENWEBUI_PORT  (기본 127.0.0.1:8080)
+  KPAA_OPENWEBUI_BIN                      open-webui 실행 경로 override
+EOF
+}
+
+case "${1:-}" in
+  start)     cmd_start ;;
+  stop)      cmd_stop ;;
+  restart)   cmd_restart ;;
+  status)    cmd_status ;;
+  logs)      cmd_logs ;;
+  logs-owui) cmd_logs_owui ;;
+  ""|-h|--help|help) usage ;;
+  *) usage; exit 2 ;;
+esac

pyproject.toml

@@ -48,6 +48,19 @@ hf = [
   "accelerate>=0.34",
   "spaces>=0.30",
 ]
+# Hybrid retrieval (BM25 + Dense) + Cross-encoder reranker.
+# - BGE-M3 임베딩 (1024 dim) + bge-reranker-v2-m3 로 한국어 SOTA급.
+# - sqlite-vec 로 별도 벡터 DB 서버 없이 임베디드 검색 (data/embeddings.sqlite).
+# - 노트북·HF Space 양쪽에서 동일 동작. BM25만 쓰는 사용자는 설치 불필요.
+rag = [
+  "sentence-transformers>=3.0",
+  "sqlite-vec>=0.1.6",
+  "torch>=2.4",
+  # 주의: python 의 sqlite3 가 extension loading 활성으로 빌드되어 있어야 한다.
+  # macOS python.org 인스톨러 빌드는 비활성 — Homebrew/conda/pyenv-from-source 의
+  # python 으로 venv 를 만들면 활성. .venv 생성 시 `which python3` 가
+  # /opt/homebrew/bin/python3 같은 것을 가리키는지 확인.
+]
 # 빌드 타임 docling 의존성 — 두 용도가 같은 패키지 셋을 공유:
 #   1) PIPC 결정문 별지(이미지) → markdown OCR. 옵트인:
 #        pip install -e ".[pipc-ocr]"

requirements.txt

@@ -33,9 +33,3 @@ spaces>=0.30
 # HF Spaces 는 requirements.txt 처리 시점에 app 파일이 아직 /home/user/app 에
 # mount 되어 있지 않아 `-e .` 가 동작하지 않는다. 대신 app.py 에서
 # `src/` 를 sys.path 에 prepend 한다.
-
-# ── Hybrid retrieval (BM25 + Dense) + Cross-encoder reranker ──
-# BGE-M3 임베딩 + bge-reranker-v2-m3 재정렬 + sqlite-vec 벡터 DB.
-# torch/transformers 는 위 ZeroGPU 섹션에서 이미 설치됨.
-sentence-transformers>=3.0
-sqlite-vec>=0.1.6

src/kpaa/cli.py

@@ -461,8 +461,10 @@ def main(argv: list[str] | None = None) -> int:
                 )
         else:
             import sqlite3
+
             from kpaa.cases.index import default_db_path as case_db_path
-            con = sqlite3.connect(case_db_path()); con.row_factory = sqlite3.Row
+            con = sqlite3.connect(case_db_path())
+            con.row_factory = sqlite3.Row
             for h in hits:
                 ntt_id = h.chunk_id.removeprefix("case_")
                 row = con.execute("SELECT title, body, summary FROM cases WHERE ntt_id=?", (ntt_id,)).fetchone()

src/kpaa/config.py

@@ -24,9 +24,6 @@ class Settings(BaseSettings):
     kpaa_host: str = "127.0.0.1"
     kpaa_port: int = 8000
 
-    kpaa_rewrite: bool = False
-    kpaa_max_context_tokens: int = 16384
-
     # LLM 백엔드 선택. None=auto: HF Spaces 환경(SPACE_ID 설정)이면 zerogpu,
     # 아니면 llama_cpp. 강제 override: "llama_cpp" | "zerogpu".
     kpaa_llm_backend: str | None = None

src/kpaa/embeddings/embedder.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import logging
 import os
 from functools import cached_property
-from typing import ClassVar, TYPE_CHECKING
+from typing import TYPE_CHECKING, ClassVar
 
 if TYPE_CHECKING:
     import numpy as np
@@ -39,20 +39,20 @@ def _detect_device() -> str:
 class Embedder:
     """BGE-M3 (또는 KPAA_EMBEDDER 지정 모델) singleton."""
 
-    _instance: ClassVar["Embedder | None"] = None
+    _instance: ClassVar[Embedder | None] = None
 
     def __init__(self, model_name: str | None = None, device: str | None = None) -> None:
         self.model_name = model_name or os.environ.get("KPAA_EMBEDDER", _DEFAULT_MODEL)
         self.device = device or _detect_device()
 
     @classmethod
-    def default(cls) -> "Embedder":
+    def default(cls) -> Embedder:
         if cls._instance is None:
             cls._instance = cls()
         return cls._instance
 
     @cached_property
-    def model(self) -> "SentenceTransformer":
+    def model(self) -> SentenceTransformer:
         from sentence_transformers import SentenceTransformer
         logger.info("Loading embedding model %s on %s ...", self.model_name, self.device)
         return SentenceTransformer(self.model_name, device=self.device)
@@ -61,7 +61,7 @@ class Embedder:
     def dim(self) -> int:
         return _DIM_BY_MODEL.get(self.model_name) or self.model.get_sentence_embedding_dimension()
 
-    def encode_chunks(self, texts: list[str], *, batch: int = 32, show_progress: bool = True) -> "np.ndarray":
+    def encode_chunks(self, texts: list[str], *, batch: int = 32, show_progress: bool = True) -> np.ndarray:
         """문서 측 임베딩. cosine 검색 위해 정규화."""
         return self.model.encode(
             texts,
@@ -71,7 +71,7 @@ class Embedder:
             convert_to_numpy=True,
         )
 
-    def encode_query(self, text: str) -> "np.ndarray":
+    def encode_query(self, text: str) -> np.ndarray:
         """쿼리 측 임베딩."""
         return self.model.encode(
             text,

src/kpaa/embeddings/index.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 import logging
 import sqlite3
 from collections.abc import Iterator
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Literal, NamedTuple
 
@@ -150,7 +150,7 @@ def build_embed_index(
     texts = [p[3] for p in pending]
     vectors = embedder.encode_chunks(texts, batch=batch)
 
-    now = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    now = datetime.now(UTC).isoformat(timespec="seconds")
     for (cid, doc_id, src, _), vec in zip(pending, vectors):
         cur.execute(
             "INSERT INTO chunk_vectors(chunk_id, embedding) VALUES (?, ?)",

src/kpaa/guides/extractor.py

@@ -124,23 +124,6 @@ def derive_doc_id(pdf_filename: str) -> str:
     return name or "guide"
 
 
-def derive_doc_date(pdf_filename: str) -> str:
-    """파일명 끝의 (YYYY.MM) 또는 (YYYY) 추출. 없으면 빈 문자열."""
-    import re
-    m = re.search(r"\((\d{4})(?:[.\-](\d{1,2}))?[.\s]*\)", pdf_filename)
-    if not m:
-        # "2026 개인정보 처리방침..." 같이 prefix 에 연도만 있는 경우
-        m2 = re.search(r"(?:^|\s)(\d{4})(?:\s|$)", pdf_filename)
-        if m2:
-            return m2.group(1)
-        return ""
-    year = m.group(1)
-    month = m.group(2)
-    if month:
-        return f"{year}.{int(month):02d}"
-    return year
-
-
 def derive_doc_title(pdf_filename: str) -> str:
     """파일명 → 사람이 읽을 한국어 제목 (★, 번호, 확장자 제거)."""
     name = pdf_filename
@@ -154,4 +137,4 @@ def derive_doc_title(pdf_filename: str) -> str:
     return name
 
 
-__all__ = ["extract", "derive_doc_id", "derive_doc_date", "derive_doc_title"]
+__all__ = ["extract", "derive_doc_id", "derive_doc_title"]

src/kpaa/llm/llama_cpp_backend.py

@@ -162,15 +162,15 @@ def _print_env_summary(n_gpu_layers: int, n_threads: int | None) -> None:
     )
     if plat == "darwin" and n_gpu_layers == 0:
         msg += (
-            f"  · 참고: macOS Metal GPU 가속은 *opt-in* 입니다 (Gemma 4 E2B Q4_K_M\n"
-            f"          + Metal 조합 segfault 회귀 회피). 시도하려면 환경변수\n"
-            f"          `KPAA_N_GPU_LAYERS=-1` 후 재시작.\n"
+            "  · 참고: macOS Metal GPU 가속은 *opt-in* 입니다 (Gemma 4 E2B Q4_K_M\n"
+            "          + Metal 조합 segfault 회귀 회피). 시도하려면 환경변수\n"
+            "          `KPAA_N_GPU_LAYERS=-1` 후 재시작.\n"
         )
     if n_gpu_layers == 0 and plat in ("linux", "win32"):
         msg += (
-            f"  · 빠르게: GPU 빌드 재설치하면 자동 가속.\n"
-            f"          CMAKE_ARGS='-DGGML_CUDA=on' pip install --force-reinstall \\\n"
-            f"            --no-cache-dir llama-cpp-python\n"
+            "  · 빠르게: GPU 빌드 재설치하면 자동 가속.\n"
+            "          CMAKE_ARGS='-DGGML_CUDA=on' pip install --force-reinstall \\\n"
+            "            --no-cache-dir llama-cpp-python\n"
         )
     if n_threads is not None and cpu and n_threads < cpu:
         msg += (

src/kpaa/llm/manager.py

@@ -19,7 +19,6 @@ import json
 import logging
 import os
 from pathlib import Path
-from typing import Any
 
 from kpaa.config import get_settings
 from kpaa.llm.base import LLMBackend

src/kpaa/llm/presets.py

@@ -1,12 +1,8 @@
-"""모델 프리셋 카탈로그 — UI 에서 선택 가능한 후보 목록.
+"""모델 프리셋 카탈로그.
 
 각 프리셋은 *동일 가중치의 두 형식* 을 함께 가진다:
   - llama_cpp_repo / llama_cpp_file : 로컬 노트북용 GGUF (Hugging Face 자동 다운로드)
   - hf_repo                         : HF Spaces ZeroGPU 용 transformers 가중치 (옵션)
-
-목적: 사용자가 채팅 답변 속도/품질 트레이드오프를 *런타임에* 비교해볼 수 있게.
-초기 후보는 한국어 RAG 답변 + 라우팅 분류 양쪽 모두에 충분히 작동한다고 알려진
-모델 위주.
 """
 from __future__ import annotations
 
@@ -25,15 +21,14 @@ class ModelPreset:
     is_default: bool = False
 
 
-# 후보 목록 — Unsloth Dynamic Quants 시리즈로 양자화 비트수만 다르게 비교용.
-# 모두 같은 가중치(google/gemma-4-E2B-it) 의 GGUF 변환본. HF Space(ZeroGPU)
-# 에서는 어떤 프리셋을 골라도 hf_repo 의 BF16 transformers 가중치를 로드하므로
-# 동일한 답변 — 양자화별 차이는 *로컬(llama-cpp-python)* 에서만 체감됨.
+# google/gemma-4-E2B-it 의 GGUF 변환본 (Unsloth Dynamic Quants). HF Space(ZeroGPU)
+# 에서는 hf_repo 의 BF16 transformers 가중치를 로드 — 양자화는 로컬
+# (llama-cpp-python) 경로에서만 적용된다.
 PRESETS: list[ModelPreset] = [
     ModelPreset(
         # Unsloth Dynamic Quants 2.0 (UD-Q4_K_XL) — 평균 ~4-bit 이지만 층별로
         # 중요한 부분은 더 높은 정밀도로 보존해 동일 4-bit 그룹 중 품질 최상.
-        id="gemma-4-e2b-unsloth-q4",
+        id="gemma-4-e2b-q4",
         label="Gemma 4 E2B UD-Q4 (기본·균형)",
         short="2B · ~1.7GB · 4-bit Dynamic · 권장 (속도·품질 균형)",
         llama_cpp_repo="unsloth/gemma-4-E2B-it-GGUF",
@@ -42,28 +37,6 @@ PRESETS: list[ModelPreset] = [
         family="gemma",
         is_default=True,
     ),
-    ModelPreset(
-        # UD-Q3_K_XL — 3-bit Dynamic. 더 작은 RAM/디스크 + 더 빠른 토큰 속도,
-        # 답변 품질 약간 ↓ (한국어 비문 살짝 증가). 노트북 RAM 부족 환경 권장.
-        id="gemma-4-e2b-unsloth-q3",
-        label="Gemma 4 E2B UD-Q3 (3-bit·빠름)",
-        short="2B · ~1.3GB · 3-bit Dynamic · 메모리 ↓ 속도 ↑ 품질 살짝 ↓",
-        llama_cpp_repo="unsloth/gemma-4-E2B-it-GGUF",
-        llama_cpp_file="gemma-4-E2B-it-UD-Q3_K_XL.gguf",
-        hf_repo="google/gemma-4-E2B-it",
-        family="gemma",
-    ),
-    ModelPreset(
-        # UD-Q2_K_XL — 2-bit Dynamic. 가장 작고 빠르나 품질 손실 뚜렷.
-        # 저사양 환경 실험·벤치마킹용. 일반 답변 품질은 권장 안 함.
-        id="gemma-4-e2b-unsloth-q2",
-        label="Gemma 4 E2B UD-Q2 (2-bit·실험)",
-        short="2B · ~1.0GB · 2-bit Dynamic · 가장 빠르나 품질 저하 뚜렷",
-        llama_cpp_repo="unsloth/gemma-4-E2B-it-GGUF",
-        llama_cpp_file="gemma-4-E2B-it-UD-Q2_K_XL.gguf",
-        hf_repo="google/gemma-4-E2B-it",
-        family="gemma",
-    ),
 ]
 
 

src/kpaa/llm/zerogpu_backend.py

@@ -131,7 +131,7 @@ class ZeroGPUBackend:
                 print(f"[kpaa.zerogpu] _gen start, device={device}", flush=True)
                 if device == "cuda":
                     model.to(device)
-                    print(f"[kpaa.zerogpu] model moved to cuda", flush=True)
+                    print("[kpaa.zerogpu] model moved to cuda", flush=True)
                 ids = input_ids.to(device)
                 print(f"[kpaa.zerogpu] input shape={tuple(ids.shape)}, max_new_tokens={opts.max_tokens}", flush=True)
 
@@ -156,14 +156,14 @@ class ZeroGPUBackend:
                             generation_config=gen_cfg,
                             streamer=streamer,
                         )
-                        print(f"[kpaa.zerogpu] generate() returned normally", flush=True)
+                        print("[kpaa.zerogpu] generate() returned normally", flush=True)
                     except Exception as e:
                         print(f"[kpaa.zerogpu] generate() raised: {type(e).__name__}: {e}", flush=True)
                         raise
                     finally:
                         try:
                             streamer.end()
-                            print(f"[kpaa.zerogpu] streamer.end() called", flush=True)
+                            print("[kpaa.zerogpu] streamer.end() called", flush=True)
                         except Exception as e:
                             print(f"[kpaa.zerogpu] streamer.end() failed: {e}", flush=True)
 

src/kpaa/pipeline.py

@@ -48,7 +48,7 @@ async def build_context(
     *,
     client: KoreanLawClient | None = None,
     backend: LLMBackend | None = None,
-    on_progress: "ProgressCB" = None,
+    on_progress: ProgressCB = None,
 ) -> RetrievalResult:
     """라우팅(LLM 분류기 1샷) → chain orchestrator → 컨텍스트 빌드.
 
@@ -221,7 +221,7 @@ async def generate(
             True (기본) — 답변 본문 끝에 "참고한 자료" 섹션을 부착.
                 Open WebUI 같이 우측 패널이 없는 클라이언트용.
             False — 답변 본문은 면책까지만. references는 별도 retrieval
-                event payload에서 받아서 클라이언트가 표시 (자체 채팅 UI).
+                event payload에서 받아서 클라이언트가 표시.
     """
     bk = backend or get_backend()
 

src/kpaa/related_laws.py

@@ -31,7 +31,7 @@ SOURCES: tuple[tuple[str, str], ...] = (
 # 여기서는 backward-compat 으로 `KNOWN_ALIASES` 이름만 재노출 (스크래이프 + yaml
 # 출력 흐름이 이 이름을 사용 중이라 유지). 신규 코드는 `from kpaa.law_api.aliases
 # import LAW_ALIASES, normalize_law_name, ...` 를 직접 써라.
-from kpaa.law_api.aliases import LAW_ALIASES as KNOWN_ALIASES  # noqa: F401
+from kpaa.law_api.aliases import LAW_ALIASES as KNOWN_ALIASES  # noqa: E402, F401
 
 
 def _gen_keywords(name: str) -> list[str]:

src/kpaa/retrieval/chains.py

@@ -73,7 +73,7 @@ def _fetchers():
 def _make_fetch_call(
     source: str,
     client: KoreanLawClient,
-    plan: "RouterPlan",
+    plan: RouterPlan,
     spec_jo_hints: tuple[str, ...],
     on_progress: ProgressCB,
 ) -> Awaitable[list[Excerpt]] | None:
@@ -125,7 +125,7 @@ def _make_chain_fn(spec: dict[str, Any]) -> ChainFn:
 
     async def _run(
         client: KoreanLawClient,
-        plan: "RouterPlan",
+        plan: RouterPlan,
         *,
         on_progress: ProgressCB = None,
     ) -> list[Excerpt]:

src/kpaa/retrieval/reranker.py

@@ -20,8 +20,9 @@ from __future__ import annotations
 
 import logging
 import os
+from collections.abc import Callable
 from functools import cached_property
-from typing import Callable, ClassVar, TypeVar
+from typing import ClassVar, TypeVar
 
 logger = logging.getLogger("kpaa.retrieval.reranker")
 
@@ -48,7 +49,7 @@ def _disabled() -> bool:
 class Reranker:
     """sentence-transformers CrossEncoder wrapper (lazy singleton)."""
 
-    _instance: ClassVar["Reranker | None"] = None
+    _instance: ClassVar[Reranker | None] = None
     _missing: ClassVar[bool] = False  # 한 번 실패하면 retry 안 함
 
     def __init__(self, model_name: str | None = None, device: str | None = None) -> None:
@@ -56,7 +57,7 @@ class Reranker:
         self.device = device or _detect_device()
 
     @classmethod
-    def default(cls) -> "Reranker | None":
+    def default(cls) -> Reranker | None:
         """싱글톤 인스턴스 — disabled 또는 첫 로드 실패 시 None.
 
         retriever 가 매 요청마다 호출하므로 None 반환 시 BM25+Dense 결과 그대로 사용.

src/kpaa/retrieval/retriever.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import os
 import re
 from collections.abc import Awaitable, Callable
 from datetime import datetime
@@ -27,15 +28,12 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
-import os
-
 from kpaa.cases import CasesIndex
 from kpaa.guides import GuidesIndex
 from kpaa.law_api import KoreanLawClient
 from kpaa.retrieval.excerpts import Excerpt
 from kpaa.retrieval.router import RouterPlan
 
-
 # ─── Hybrid retrieval (BM25 + Dense via sqlite-vec) ────────────────────────
 # `kpaa build-embeddings` 로 data/embeddings.sqlite 가 빌드되어 있으면 자동 사용.
 # 빌드 안 된 환경 / 실패 시 BM25 단독으로 fallback.

src/kpaa/retrieval/verify.py

@@ -30,7 +30,6 @@ from dataclasses import dataclass, field
 
 from kpaa.retrieval.excerpts import Excerpt
 
-
 # ─────────────────────────────── 정규식 ───────────────────────────────
 
 # PIPC 결정 번호 — "PIPC 결정 2024-12-345", "개인정보보호위원회 결정 2024-2345"

src/kpaa/server.py

@@ -24,7 +24,7 @@ import uuid
 from collections.abc import AsyncIterator
 from typing import Any, Literal
 
-from fastapi import FastAPI, HTTPException, Query
+from fastapi import FastAPI, HTTPException
 from fastapi.responses import HTMLResponse, StreamingResponse
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -59,8 +59,7 @@ def preset_id_from_model(model: str | None) -> str | None:
     return m.group("id") if m else None
 
 
-# 기본 모델 ID — `/healthz`, 자체 chat UI 헤더, `/info` curl 예시, 그리고
-# 테스트 호환용. 항상 default_preset() 의 표시 ID 와 동기.
+# 기본 모델 ID — `/healthz` 응답 및 테스트 호환용. 항상 default_preset() 과 동기.
 MODEL_ID = model_id_for(default_preset())
 
 
@@ -111,7 +110,7 @@ _last_refs: dict[str, Any] = {
 }
 
 
-from kpaa.retrieval.citation_match import (
+from kpaa.retrieval.citation_match import (  # noqa: E402
     extract_geungeo_indices as _extract_geungeo_indices,
 )
 
@@ -179,12 +178,6 @@ class ChatMessage(BaseModel):
     content: str
 
 
-class SelectModelReq(BaseModel):
-    """`/api/select-model` 요청 바디 — preset_id 하나."""
-
-    preset_id: str
-
-
 class ChatRequest(BaseModel):
     model_config = ConfigDict(extra="ignore")  # 모르는 필드는 무시 (Open WebUI가 보내는 필드 다양)
 
@@ -237,13 +230,6 @@ class ModelList(BaseModel):
 
 # ───────────────────────── helpers ─────────────────────────
 
-def _last_user_query(messages: list[ChatMessage]) -> str:
-    for m in reversed(messages):
-        if m.role == "user" and m.content.strip():
-            return m.content.strip()
-    raise HTTPException(400, "no user message with content")
-
-
 def _split_history_and_query(messages: list[ChatMessage]) -> tuple[list[LLMChatMessage], str]:
     """ChatRequest.messages → (history, last_user_query).
 
@@ -555,7 +541,7 @@ def create_app() -> FastAPI:
 
     @app.get("/", response_class=HTMLResponse)
     async def index() -> str:
-        # 루트 = Open WebUI + 참고자료 분할 화면. 백엔드 정보 페이지는 /info.
+        # 루트 = Open WebUI + 참고자료 분할 화면.
         # 페이지 진입(리로드 포함) 시 우측 참고자료 서버 상태를 비움 — 이전 세션
         # 잔여 _last_refs 가 폴링에 의해 즉시 렌더되는 것을 방지. HF 백엔드의
         # _split_handler 와 동일 정책.
@@ -571,65 +557,14 @@ def create_app() -> FastAPI:
         })
         return _SPLIT_HTML
 
-    @app.get("/info", response_class=HTMLResponse)
-    async def info_page() -> str:
-        return f"""<!doctype html>
-<html lang="ko"><head><meta charset="utf-8">
-<title>KPAA — 백엔드 정보</title>
-<style>
-  body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-         max-width: 720px; margin: 40px auto; padding: 0 16px; color: #222; line-height: 1.6; }}
-  code {{ background: #f4f4f4; padding: 2px 6px; border-radius: 4px; font-size: 0.95em; }}
-  pre  {{ background: #f4f4f4; padding: 12px; border-radius: 6px; overflow-x: auto; }}
-  a    {{ color: #0a66c2; }}
-  h1   {{ font-size: 1.5rem; }}
-  h2   {{ font-size: 1.1rem; margin-top: 1.6em; }}
-  table {{ border-collapse: collapse; width: 100%; }}
-  td, th {{ border-bottom: 1px solid #eee; padding: 6px 8px; text-align: left; }}
-  .muted {{ color: #888; font-size: 0.9em; }}
-</style></head>
-<body>
-<h1>KPAA — 개인정보보호법 미니 상담 백엔드</h1>
-<p class="muted">버전 {__version__} · 기본 모델 <code>{MODEL_ID}</code></p>
-<p class="muted">선택 가능: {", ".join(f"<code>{model_id_for(p)}</code>" for p in list_presets())}</p>
-
-<p style="background:#0a66c2;color:#fff;padding:14px 16px;border-radius:8px;font-weight:600;">
-👉 <a href="/" style="color:#fff;">Open WebUI + 참고자료 분할 화면 (홈)</a> &nbsp; · &nbsp;
-<a href="/chat" style="color:#fff;">자체 채팅 UI</a>
-</p>
-
-<h2>Endpoints</h2>
-<table>
-<tr><th>Method</th><th>Path</th><th>설명</th></tr>
-<tr><td>GET</td><td><a href="/">/</a></td><td><b>홈</b> — Open WebUI + 참고자료 분할 화면</td></tr>
-<tr><td>GET</td><td><a href="/chat">/chat</a></td><td>자체 채팅 UI (답변 + 참고자료 좌/우 분할)</td></tr>
-<tr><td>GET</td><td>/api/chat?q=…</td><td>SSE 스트림 (자체 UI용)</td></tr>
-<tr><td>GET</td><td><a href="/healthz">/healthz</a></td><td>Liveness</td></tr>
-<tr><td>GET</td><td><a href="/v1/models">/v1/models</a></td><td>OpenAI-호환 모델 목록</td></tr>
-<tr><td>POST</td><td>/v1/chat/completions</td><td>OpenAI-호환 chat (Open WebUI용)</td></tr>
-<tr><td>GET</td><td><a href="/docs">/docs</a></td><td>Swagger UI</td></tr>
-</table>
-
-<h2>Open WebUI 연결</h2>
-<p>Settings → Connections → <b>OpenAI API</b> → URL <code>http://localhost:8000/v1</code>, Key <code>local</code></p>
-
-<h2>curl 예시</h2>
-<pre>curl -N -X POST http://localhost:8000/v1/chat/completions \\
-  -H 'Content-Type: application/json' \\
-  -d '{{"model":"{MODEL_ID}","messages":[{{"role":"user","content":"매장 CCTV 안내문구는?"}}],"stream":true}}'</pre>
-
-<p class="muted">※ 본 챗봇 답변은 일반적 정보 제공이며 법률 자문이 아닙니다. 신고: KISA 118 / privacy.go.kr</p>
-</body></html>"""
-
     @app.get("/healthz")
     async def healthz() -> dict[str, str]:
         return {"status": "ok", "version": __version__, "model": MODEL_ID}
 
     @app.get("/v1/models")
     async def list_models() -> ModelList:
-        # 프리셋별 1개씩 — Open WebUI 모델 dropdown 에 동시에 노출.
-        # 사용자가 dropdown 에서 선택한 모델 이름이 ChatRequest.model 로 전달되며,
-        # `_switch_to_requested_model` 가 그 이름을 보고 ModelManager 를 전환한다.
+        # 프리셋별 1개씩. 사용자가 Open WebUI dropdown 에서 고르면 그 이름이
+        # ChatRequest.model 로 들어오고 `_switch_to_requested_model` 가 매니저를 전환.
         now = int(time.time())
         return ModelList(
             data=[ModelInfo(id=model_id_for(p), created=now) for p in list_presets()]
@@ -697,48 +632,12 @@ def create_app() -> FastAPI:
             choices=[ChatChoice(message=ChatChoiceMessage(content=text))],
         )
 
-    # ───────────────────────── 자체 채팅 UI (좌/우 분할) ─────────────────────────
-
-    @app.get("/chat", response_class=HTMLResponse)
-    async def chat_ui() -> str:
-        return _CHAT_HTML
+    # ─── 분할 화면 (`/`) JS 폴링이 사용하는 API ─────────────────────────
 
     @app.get("/api/last-references")
     async def api_last_refs() -> dict[str, Any]:
         return dict(_last_refs)
 
-    @app.get("/api/models")
-    async def api_models() -> dict[str, Any]:
-        """프리셋 목록 + 현재 선택. 프런트 dropdown 채우기용."""
-        mgr = get_manager()
-        return {
-            "current": mgr.current_id,
-            "presets": [
-                {
-                    "id": p.id,
-                    "label": p.label,
-                    "short": p.short,
-                    "family": p.family,
-                    "is_default": p.is_default,
-                }
-                for p in list_presets()
-            ],
-        }
-
-    @app.post("/api/select-model")
-    async def api_select_model(req: SelectModelReq) -> dict[str, Any]:
-        """모델 프리셋 전환 — 다음 답변부터 새 모델로."""
-        try:
-            preset = get_manager().set_current(req.preset_id)
-        except ValueError as e:
-            raise HTTPException(400, str(e)) from e
-        return {
-            "status": "ok",
-            "current": preset.id,
-            "label": preset.label,
-            "short": preset.short,
-        }
-
     @app.post("/api/clear-references")
     async def api_clear_refs() -> dict[str, str]:
         """우측 참고자료 패널 초기화 — Open WebUI 새 채팅 등에서 사용."""
@@ -754,41 +653,6 @@ def create_app() -> FastAPI:
         })
         return {"status": "cleared"}
 
-    @app.get("/api/chat")
-    async def api_chat(q: str = Query(..., min_length=1, max_length=2000)):
-        """SSE: token + references + done events. EventSource 호환."""
-
-        async def gen():
-            opts = LLMOptions()
-            refs_sent = False
-            # 자체 UI는 우측 패널에 참고자료를 별도 표시하므로 답변 본문에는 부착 X
-            async for evt in generate(q.strip(), options=opts, inline_references=False):
-                if evt["event"] == "stage":
-                    payload = {"stage": evt["stage"], **(evt.get("payload") or {})}
-                    yield f"event: stage\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"
-                elif evt["event"] == "retrieval":
-                    res = evt["result"]
-                    payload = {
-                        "intents": [i.name for i in res.plan.intents],
-                        "jo_targets": list(res.plan.jo_targets),
-                        "elapsed_ms": res.elapsed_ms,
-                        "excerpts": [_excerpt_to_dict(e) for e in res.excerpts],
-                    }
-                    yield f"event: references\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"
-                    refs_sent = True
-                elif evt["event"] == "token":
-                    yield f"event: token\ndata: {json.dumps({'delta': evt['delta']}, ensure_ascii=False)}\n\n"
-                elif evt["event"] == "done":
-                    yield f"event: done\ndata: {json.dumps({'answer': evt['answer']}, ensure_ascii=False)}\n\n"
-            if not refs_sent:
-                yield "event: references\ndata: {\"excerpts\": []}\n\n"
-
-        return StreamingResponse(
-            gen(),
-            media_type="text/event-stream",
-            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
-        )
-
     return app
 
 
@@ -1056,261 +920,3 @@ console.log("[kpaa-parent] message listener attached");
 </script>
 </body></html>"""
 
-
-_CHAT_HTML = """<!doctype html>
-<html lang="ko"><head><meta charset="utf-8">
-<title>KPAA — 개인정보보호법 상담</title>
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<style>
-  *, *::before, *::after { box-sizing: border-box; }
-  html, body { margin: 0; height: 100%; font-family: -apple-system, BlinkMacSystemFont, "Apple SD Gothic Neo", "Segoe UI", sans-serif; color: #222; background: #fafafa; }
-  .app { display: flex; height: 100vh; }
-  .pane { display: flex; flex-direction: column; min-width: 0; }
-  .left  { flex: 1 1 50%; border-right: 1px solid #e5e5e5; background: #fff; }
-  .right { flex: 1 1 50%; background: #f6f7f9; overflow-y: auto; }
-  header { padding: 12px 18px; border-bottom: 1px solid #e5e5e5; background: #fff; display: flex; align-items: center; gap: 12px; }
-  header h1 { margin: 0; font-size: 1.0rem; font-weight: 600; }
-  header .muted { color: #888; font-size: 0.85em; }
-  .messages { flex: 1; overflow-y: auto; padding: 18px; }
-  .msg { margin: 0 0 16px 0; }
-  .msg .role { font-size: 0.78em; color: #888; margin-bottom: 4px; }
-  .msg.user  .role { color: #0a66c2; }
-  .msg.bot   .role { color: #15833a; }
-  .msg .body { white-space: pre-wrap; word-break: break-word; line-height: 1.65; font-size: 0.96rem; }
-  .composer { display: flex; padding: 12px 18px; border-top: 1px solid #e5e5e5; gap: 8px; background: #fff; }
-  .composer textarea { flex: 1; resize: none; padding: 10px 12px; border-radius: 8px; border: 1px solid #d0d0d0; font: inherit; min-height: 44px; max-height: 160px; }
-  .composer button { padding: 0 16px; border-radius: 8px; border: 0; background: #0a66c2; color: #fff; font-weight: 600; cursor: pointer; }
-  .composer button:disabled { background: #999; cursor: not-allowed; }
-  .right header { background: #f6f7f9; }
-  .refs-list { padding: 12px 18px; }
-  .refs-empty { color: #888; padding: 24px; text-align: center; }
-  .ref { background: #fff; border: 1px solid #e5e5e5; border-radius: 10px; padding: 12px 14px; margin-bottom: 12px; }
-  .ref .head { display: flex; align-items: baseline; gap: 8px; flex-wrap: wrap; margin-bottom: 6px; }
-  .ref .badge { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 0.72em; font-weight: 600; color: #fff; }
-  .badge.case  { background: #0a66c2; }
-  .badge.law   { background: #15833a; }
-  .badge.related_law { background: #0d8e8a; }
-  .badge.guide { background: #107869; }
-  .badge.pipc  { background: #ad7100; }
-  .badge.interpretation { background: #6633bb; }
-  .badge.precedent { background: #b03060; }
-  .badge.admin_rule { background: #555; }
-  .ref .citation { font-weight: 600; font-size: 0.92em; }
-  .ref .title { color: #444; font-size: 0.9em; margin-bottom: 6px; }
-  .ref .content { font-size: 0.85em; line-height: 1.55; color: #333; background: #fafafa; padding: 8px 10px; border-radius: 6px; white-space: pre-wrap; max-height: 240px; overflow-y: auto; border: 1px solid #eee; }
-  .ref .footer { margin-top: 8px; display: flex; justify-content: space-between; align-items: center; gap: 8px; }
-  .ref a.orig { color: #0a66c2; font-size: 0.85em; text-decoration: none; }
-  .ref a.orig:hover { text-decoration: underline; }
-  .ref .nolink { color: #888; font-size: 0.78em; font-style: italic; }
-  .meta-line { font-size: 0.78em; color: #888; padding: 8px 18px; border-bottom: 1px solid #eee; background: #f0f1f4; }
-  .disclaimer { font-size: 0.8em; color: #666; padding: 8px 12px; background: #fff8e1; border-radius: 8px; margin-top: 8px; }
-  .typing { display: inline-block; width: 6px; height: 14px; background: #15833a; vertical-align: -3px; animation: blink 1s infinite; }
-  @keyframes blink { 50% { opacity: 0; } }
-  @media (max-width: 800px) {
-    .app { flex-direction: column; }
-    .left, .right { flex: 1 1 50%; }
-    .left { border-right: 0; border-bottom: 1px solid #e5e5e5; }
-  }
-</style></head>
-<body>
-<div class="app">
-  <section class="pane left">
-    <header>
-      <h1>KPAA — 개인정보보호법 상담</h1>
-      <select id="model-select" title="답변 LLM 모델 — 변경 시 다음 질문부터 적용"
-              style="margin-left:auto; padding:4px 8px; border-radius:6px; border:1px solid #d0d0d0; background:#fff; font-size:0.82em; max-width: 240px;">
-      </select>
-    </header>
-    <div id="model-status" class="meta-line" style="display:none;"></div>
-    <div class="messages" id="messages">
-      <div class="msg bot">
-        <div class="role">상담 도우미</div>
-        <div class="body">안녕하세요. 개인 · 소상공인 · 작은 병원의 개인정보보호법 궁금증을 평이한 한국어로 안내해 드립니다. 무엇이 궁금하신가요?</div>
-      </div>
-    </div>
-    <form class="composer" id="form">
-      <textarea id="input" placeholder="예: 매장 CCTV 안내문구는 어떻게 작성하나요?    (Enter=전송, Shift+Enter=줄바꿈)" rows="2" required></textarea>
-      <button type="submit" id="send">보내기</button>
-    </form>
-  </section>
-  <section class="pane right">
-    <header>
-      <h1>참고한 자료</h1>
-      <span class="muted" id="refs-count"></span>
-    </header>
-    <div class="meta-line" id="meta">질문을 보내면 LLM이 본 근거가 여기에 표시됩니다.</div>
-    <div class="refs-list" id="refs">
-      <div class="refs-empty">아직 답변이 없습니다.</div>
-    </div>
-  </section>
-</div>
-<script>
-const LABEL = { case: "상담사례", guide: "안내서", law: "법조문", related_law: "관련 법령", pipc: "PIPC 결정", interpretation: "법령해석례", precedent: "판례", admin_rule: "행정규칙", constitutional: "헌법재판소", oldnew: "구·신 비교", article_history: "조문 변천" };
-const messagesEl = document.getElementById("messages");
-const refsEl = document.getElementById("refs");
-const refsCountEl = document.getElementById("refs-count");
-const metaEl = document.getElementById("meta");
-const form = document.getElementById("form");
-const input = document.getElementById("input");
-const send = document.getElementById("send");
-
-function escapeHtml(s) {
-  return (s || "").replace(/[&<>"']/g, c => ({"&":"&amp;","<":"&lt;",">":"&gt;","\\"":"&quot;","'":"&#39;"}[c]));
-}
-
-function appendMsg(role, html) {
-  const div = document.createElement("div");
-  div.className = "msg " + (role === "user" ? "user" : "bot");
-  const r = role === "user" ? "사용자" : "상담 도우미";
-  div.innerHTML = `<div class="role">${r}</div><div class="body"></div>`;
-  div.querySelector(".body").innerHTML = html;
-  messagesEl.appendChild(div);
-  messagesEl.scrollTop = messagesEl.scrollHeight;
-  return div.querySelector(".body");
-}
-
-function renderRefs(payload) {
-  const excerpts = payload.excerpts || [];
-  refsCountEl.textContent = excerpts.length ? `${excerpts.length}건` : "";
-  if (payload.intents !== undefined) {
-    const intents = (payload.intents.length ? payload.intents.join(", ") : "(매칭 없음)");
-    const jo = (payload.jo_targets.length ? payload.jo_targets.join(", ") : "-");
-    metaEl.textContent = `의도: ${intents}  ·  조문 후보: ${jo}  ·  검색 ${payload.elapsed_ms}ms`;
-  }
-  refsEl.innerHTML = "";
-  if (!excerpts.length) {
-    refsEl.innerHTML = '<div class="refs-empty">근거가 검색되지 않았습니다.</div>';
-    return;
-  }
-  for (const e of excerpts) {
-    const card = document.createElement("div");
-    card.className = "ref";
-    const label = LABEL[e.source_type] || e.source_type;
-    const link = e.url
-      ? `<a class="orig" href="${escapeHtml(e.url)}" target="_blank" rel="noopener noreferrer">원문 페이지 열기 ↗</a>`
-      : `<span class="nolink">원문 페이지 미제공 — 아래 본문을 LLM이 직접 참조</span>`;
-    card.innerHTML = `
-      <div class="head">
-        <span class="badge ${e.source_type}">${label}</span>
-        <span class="citation">${escapeHtml(e.citation)}</span>
-      </div>
-      <div class="title">${escapeHtml(e.title || "")}</div>
-      <div class="content">${escapeHtml(e.content || "")}</div>
-      <div class="footer">${link}</div>`;
-    refsEl.appendChild(card);
-  }
-}
-
-let activeStream = null;
-
-form.addEventListener("submit", (ev) => {
-  ev.preventDefault();
-  const q = input.value.trim();
-  if (!q || activeStream) return;
-
-  appendMsg("user", escapeHtml(q));
-  const botBody = appendMsg("bot", '<span class="typing"></span>');
-  refsEl.innerHTML = '<div class="refs-empty">법령 검색 중…</div>';
-  refsCountEl.textContent = "";
-  metaEl.textContent = "검색 중…";
-
-  send.disabled = true;
-  input.value = "";
-
-  const es = new EventSource("/api/chat?q=" + encodeURIComponent(q));
-  activeStream = es;
-  let acc = "";
-
-  es.addEventListener("references", (e) => {
-    try { renderRefs(JSON.parse(e.data)); } catch (_) {}
-  });
-
-  es.addEventListener("token", (e) => {
-    try {
-      const { delta } = JSON.parse(e.data);
-      acc += delta;
-      botBody.textContent = acc;
-      messagesEl.scrollTop = messagesEl.scrollHeight;
-    } catch (_) {}
-  });
-
-  es.addEventListener("done", (e) => {
-    try {
-      const { answer } = JSON.parse(e.data);
-      botBody.textContent = answer;
-    } catch (_) {}
-    es.close();
-    activeStream = null;
-    send.disabled = false;
-    input.focus();
-  });
-
-  es.onerror = () => {
-    if (!acc) botBody.textContent = "(응답 오류)";
-    es.close();
-    activeStream = null;
-    send.disabled = false;
-  };
-});
-
-// ─ 모델 선택 dropdown (자체 chat UI) ─
-const modelSelect = document.getElementById("model-select");
-const modelStatus = document.getElementById("model-status");
-function showModelStatus(msg, ok) {
-  modelStatus.textContent = msg;
-  modelStatus.style.display = "block";
-  modelStatus.style.color = ok ? "#15833a" : "#c0392b";
-  setTimeout(() => { modelStatus.style.display = "none"; }, 4000);
-}
-async function loadModels() {
-  try {
-    const r = await fetch("/api/models", { cache: "no-store" });
-    if (!r.ok) return;
-    const data = await r.json();
-    modelSelect.innerHTML = "";
-    for (const p of data.presets || []) {
-      const opt = document.createElement("option");
-      opt.value = p.id;
-      opt.textContent = p.label;
-      opt.title = p.short;
-      if (p.id === data.current) opt.selected = true;
-      modelSelect.appendChild(opt);
-    }
-  } catch (_) {}
-}
-modelSelect.addEventListener("change", async () => {
-  const preset_id = modelSelect.value;
-  modelSelect.disabled = true;
-  try {
-    const r = await fetch("/api/select-model", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ preset_id }),
-    });
-    if (!r.ok) {
-      const txt = await r.text();
-      showModelStatus(`모델 변경 실패: ${txt}`, false);
-      return;
-    }
-    const data = await r.json();
-    showModelStatus(`✅ 모델 변경됨 — ${data.label} (다음 질문부터 적용 · 첫 사용 시 다운로드)`, true);
-  } catch (e) {
-    showModelStatus(`네트워크 오류: ${e}`, false);
-  } finally {
-    modelSelect.disabled = false;
-  }
-});
-loadModels();
-
-input.addEventListener("keydown", (e) => {
-  // 일반 채팅 UX: Enter = 전송, Shift+Enter = 줄바꿈.
-  // 한국어 IME 조합 중 Enter(글자 확정)는 무시.
-  if (e.key !== "Enter") return;
-  if (e.shiftKey) return;                            // 줄바꿈
-  if (e.isComposing || e.keyCode === 229) return;     // IME 글자 확정
-  e.preventDefault();
-  form.requestSubmit();
-});
-input.focus();
-</script>
-</body></html>"""

src/kpaa/ui/__init__.py

@@ -1,5 +1,4 @@
 """KPAA UI 패키지.
 
 - `gradio` 모듈 — HF Spaces 데모 (Gradio Blocks).
-- 로컬 노트북용 자체 채팅 UI 는 `kpaa.server` 의 `/chat` 엔드포인트.
 """

tasks.py

@@ -0,0 +1,64 @@
+"""Cross-platform task runner. Run via `invoke <task>` after `pip install invoke`.
+
+Replaces the role of a Makefile so Windows/Mac/Linux users get the same UX.
+"""
+from __future__ import annotations
+
+from invoke import task
+
+
+@task
+def install(c):
+    """Editable install with dev + llm extras."""
+    c.run('pip install -e ".[dev,llm]"')
+
+
+@task
+def lint(c):
+    c.run("ruff check src/ tests/")
+
+
+@task
+def fmt(c):
+    c.run("ruff format src/ tests/")
+
+
+@task
+def test(c):
+    c.run("pytest tests/ -v")
+
+
+@task(help={"q": "Question to send through the pipeline"})
+def smoke(c, q="매장 CCTV 안내문구 어떻게 써요?"):
+    """Run a single end-to-end smoke through the RAG pipeline."""
+    c.run(f'python -m kpaa smoke "{q}"')
+
+
+@task
+def evalq(c):
+    """Run golden-question evaluation."""
+    c.run("python -m kpaa eval")
+
+
+@task
+def serve(c):
+    """Start the FastAPI backend on :8000."""
+    c.run("python -m kpaa serve")
+
+
+@task
+def up(c):
+    c.run("docker compose up -d")
+
+
+@task
+def down(c):
+    c.run("docker compose down")
+
+
+@task(help={"since": "YYYY-MM-DD; only fetch cases registered after this date"})
+def refresh_cases(c, since=""):
+    cmd = "python -m kpaa refresh-cases"
+    if since:
+        cmd += f" --since {since}"
+    c.run(cmd)