Initial backend code: src/kpaa, runtime data, requirements

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* 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

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KPAA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NOTICE

@@ -0,0 +1,36 @@
+korean-privacy-ai-assistant (KPAA)
+============================
+
+This project draws inspiration from korean-law-mcp
+(https://github.com/chrisryugj/korean-law-mcp) for the surface area of
+법제처 OPEN API endpoints to wrap. No source code is vendored; only the
+factual mapping of which government endpoints exist for which legal
+domains was used as a starting point.
+
+
+Data sources
+------------
+
+* 법제처 OPEN API (https://open.law.go.kr)
+  Requires an individual API key (LAW_OC) issued free at the URL above.
+  Government data, generally usable under 공공누리(KOGL).
+
+* 개인정보보호위원회 개인정보 상담사례 (https://www.privacy.go.kr)
+  Scraped via the public AJAX endpoint
+    /front/case/onMadangListAjax.do
+  Government data presumed under 공공누리 제1유형 (출처표시); the snapshot
+  shipped with this repo is a verbatim copy of the public board content,
+  trimmed only to fit chatbot context windows. Each citation in the
+  chatbot's answers includes the case number and the privacy.go.kr URL.
+
+
+Model
+-----
+
+Gemma 4 is licensed under the Gemma Terms of Use
+  https://ai.google.dev/gemma/terms
+End users are responsible for compliance with the Gemma terms when running
+this project. The GGUF distribution used by default is
+  bartowski/google_gemma-4-E2B-it-GGUF
+on Hugging Face; downloading the GGUF on first run is subject to the same
+Gemma terms.

data/cases.sqlite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a84162716f015395c4aa07d962d4e5441095840e2a7c19e07eff77a2822123aa
+size 14213120

data/chain_specs.yaml

@@ -0,0 +1,171 @@
+# KPAA chain orchestrator 메타데이터 (v2.2 — 16 chain)
+#
+# 원작 korean-law-mcp v3.5.1 의 16개 도구 직접 노출 패턴을 *결정적 fan-out*
+# 으로 미러링. 우리 시스템은 LLM 도구 호출 0회 — chain 안의 소스 조합은
+# 이 yaml + chains.py 가 결정한다.
+#
+# 라우팅 흐름:
+#   사용자 질문 → LLM 분류기(llm_router.py) → chain key 1개 선택 → chains.py 가
+#   해당 spec 의 sources 를 병렬 fan-out → fetcher 들이 Excerpt 리스트 반환.
+#
+# chain 추가/조정 시 이 파일만 손대면 충분 (chains.py 는 spec 기반 dispatch).
+# 단, llm_router.CHAIN_DESCRIPTIONS 와 _format_stage 의 한국어 라벨 매핑은
+# 별도로 갱신해야 LLM 분류 정확도 + UI 표시가 따라온다.
+#
+# 항목 형식:
+#   key: chain 식별자 (snake_case)
+#   ko: 한국어 라벨 (UI 표시용)
+#   description: LLM 분류기 prompt 의 *언제 이 chain 을 쓰는지* 설명 (자연어)
+#   jo_hints: 본법(개인정보보호법) 조문 번호 기본값. LLM 명시 안 하면 사용
+#   sources: 호출할 fetcher 목록. _fetch_<source>() 와 매핑.
+#     - case            : 상담사례 (로컬 SQLite)
+#     - guide           : PIPC 발간 안내서 청크 (로컬 SQLite, 인터랙티브 큐레이션)
+#     - law             : 본법 조문 (jo_targets 만큼)
+#     - related_law     : 관련 법령 본문 (plan.mst_targets 라이브)
+#     - related_law_static : 정적 관련 법령 리스트 (related_laws.yaml)
+#     - pipc            : PIPC 결정문
+#     - interpretation  : 법령해석례
+#     - precedent       : 판례
+#     - admin_rule      : 행정규칙(고시)
+
+chains:
+
+  - key: definition
+    ko: 정의·개요
+    description: |
+      법령·용어의 정의·개요·목적·원칙을 묻는 질문.
+      예: "개인정보보호법이 뭐야", "정보주체란?", "가명정보 정의", "개인정보처리자 누구를 말해?"
+    jo_hints: ["1", "2", "3"]
+    # constitutional 추가: 자기결정권·기본권 헌재 판단이 정의 질의에 깊이 보탬.
+    sources: [law, related_law, constitutional]
+
+  - key: related_laws
+    ko: 관련 법령 안내
+    description: |
+      개인정보보호법과 함께 적용되는 *다른 법률* 안내 요청.
+      예: "관련된 법은?", "다른 법 알려줘", "함께 봐야 할 법령".
+      특정 법령 본문 질의(예: '신용정보법 제32조')는 여기보다 general_practice/precedent_search 가 적합.
+    jo_hints: []
+    sources: [related_law, related_law_static]
+
+  - key: general_practice
+    ko: 일반 실무 (catch-all)
+    description: |
+      위 카테고리 어디에도 명확히 들어가지 않는 *일반 실무 질문* 의 catch-all.
+      모호하면 이걸 선택. 동의·CCTV·처리방침·유출·위탁·제3자제공·채용·아동·파기 등 어디에 둬야 할지
+      애매한 복합 질문에도 적합.
+    # catch-all 안전망: 모호 질문에도 본법 핵심 4개 조문이 항상 컨텍스트에 들어감.
+    # 제3조(원칙), 제15조(수집·이용), 제17조(제공), 제29조(안전조치).
+    jo_hints: ["3", "15", "17", "29"]
+    sources: [case, law, related_law, pipc, interpretation, precedent]
+
+  - key: precedent_search
+    ko: 판례·처벌 사례
+    description: |
+      판례·처벌 사례·위반 사례·손해배상·형사 판결 검색.
+      예: "○○ 위반 판례", "처벌 사례 알려줘", "어떤 형사 판결이 있어?"
+    jo_hints: []
+    sources: [law, related_law, pipc, precedent]
+
+  - key: safety_compliance
+    ko: 안전조치·고시
+    description: |
+      개인정보의 안전성 확보조치·기술적·관리적·물리적 보호조치·암호화·접근통제·
+      개인정보보호위원회 고시 관련.
+      예: "안전조치 기준", "암호화 어떻게", "접근권한 관리".
+    jo_hints: ["29"]
+    # three_tier 추가: 본법 제29조와 함께 *시행령 제30조 (안전성 확보조치 기준)* 자동 포함.
+    sources: [law, three_tier, admin_rule, pipc, guide]
+
+  - key: consent_collection
+    ko: 동의 수집·철회
+    description: |
+      개인정보 수집 동의·동의 철회·동의 방식(서면/전자) 관련 실무 질문.
+      예: "동의서 어떻게 받아야", "마케팅 동의 분리해야 하나", "동의 철회 절차".
+    jo_hints: ["15", "17", "22"]
+    sources: [law, case, pipc, interpretation, guide]
+
+  - key: cctv_video
+    ko: CCTV·영상정보처리기기
+    description: |
+      CCTV·영상정보처리기기 설치·안내문·녹음·운영 관련. 매장·아파트·병원·학원 등
+      현장 설치 사례.
+      예: "CCTV 어디 설치해야", "안내문 어떻게 써", "영상정보 보관기간", "녹음 같이 해도 되나".
+    jo_hints: ["25"]
+    sources: [law, admin_rule, pipc, case, guide]
+
+  - key: breach_notification
+    ko: 유출 신고·통지
+    description: |
+      개인정보 유출·분실·도난·침해 시 신고 절차·정보주체 통지·보호위원회 신고 기한.
+      예: "유출되면 며칠 안에 신고", "침해 통지 의무", "유출 신고 어디에".
+    jo_hints: ["34"]
+    sources: [law, admin_rule, pipc, interpretation, guide]
+
+  - key: processing_consignment
+    ko: 처리 위탁
+    description: |
+      개인정보 처리 위탁·외주·클라우드·수탁자 관리 관련.
+      예: "클라우드에 자료 맡겨도 되나", "위탁업체 관리 어떻게", "재위탁 가능?"
+    jo_hints: ["26"]
+    sources: [law, case, pipc, interpretation, guide]
+
+  - key: third_party_provision
+    ko: 제3자 제공·공유
+    description: |
+      개인정보 제3자 제공·공유·양도·매각·계열사 공유 관련.
+      예: "제3자 제공 동의", "계열사에 공유해도", "양수도 시 개인정보".
+    jo_hints: ["17", "18"]
+    sources: [law, case, pipc, precedent, guide]
+
+  - key: data_subject_rights
+    ko: 정보주체 권리 (열람·정정·삭제)
+    description: |
+      정보주체의 권리 행사 — 열람·정정·삭제·처리정지·이의제기.
+      예: "내 정보 보여줘 요청 받았어", "삭제 요청 거부 가능", "처리정지 절차".
+    jo_hints: ["35", "36", "37", "39"]
+    # constitutional 추가: 자기결정권 헌재 판단이 권리 범위 해석의 핵심 근거.
+    sources: [law, case, interpretation, pipc, guide, constitutional]
+
+  - key: retention_destruction
+    ko: 보유·파기
+    description: |
+      개인정보 보유기간·보존·파기·폐기 관련.
+      예: "1년 지나면 파기해야", "보관기간 어떻게 정해", "파기 방법".
+    jo_hints: ["21", "39의6"]
+    sources: [law, case, interpretation, guide]
+
+  - key: medical_health
+    ko: 의료·건강·민감정보
+    description: |
+      의료기관·병원·진료기록·건강정보·민감정보 처리 관련 (의료법 연계).
+      예: "환자 진료기록 마케팅 활용", "병원 CCTV", "의료법상 비밀유지", "건강정보 동의".
+      ※ 병원 CCTV 설치 위치 같은 *시설 설치* 질문은 cctv_video 가 더 적합.
+    jo_hints: ["23"]
+    # constitutional 추가: 의료정보·민감정보 자기결정권 헌재 판단 (예: 92헌마68 등).
+    sources: [law, related_law, case, pipc, constitutional]
+
+  - key: employment_recruitment
+    ko: 채용·근로
+    description: |
+      직원 채용·이력서·면접·인사·근로 과정의 개인정보 처리 (근로기준법 연계).
+      예: "이력서에 주민번호 받아도", "직원 동의 어떻게", "퇴사자 정보 보관".
+    jo_hints: ["15", "24의2"]
+    sources: [law, related_law, case, pipc, guide]
+
+  - key: policy_disclosure
+    ko: 처리방침·공개
+    description: |
+      개인정보 처리방침 작성·게시·공개 관련.
+      예: "처리방침 만들어야", "1인 사업자도 게시 의무", "처리방침 어떻게 써".
+    jo_hints: ["30"]
+    # three_tier 추가: 본법 제30조와 함께 *시행령 제31조 (처리방침 공개)* 자동 포함.
+    sources: [law, three_tier, admin_rule, case, pipc, guide]
+
+  - key: minor_protection
+    ko: 아동·미성년 보호
+    description: |
+      만 14세 미만 아동·미성년자·청소년 개인정보 처리·법정대리인 동의 관련.
+      예: "14세 미만 동의", "어린이 정보 수집", "법정대리인 동의 받는 법".
+    jo_hints: ["22의2"]
+    sources: [law, case, pipc, interpretation, guide]

data/guides.sqlite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3b9bea8e93e7b1024a7d807f9ed66511744d02c779dfbf25e4bb1d920662600a
+size 1601536

data/guides_meta.json

@@ -0,0 +1,22 @@
+{
+  "고정형_영상정보처리기기_설치_운영_안내서": {
+    "doc_title": "고정형 영상정보처리기기 설치·운영 안내서(공공 및 민간분야 통합본)",
+    "doc_date": "2024.12",
+    "source_pdf": "★고정형 영상정보처리기기 설치 운영 안내서(2024.12).pdf",
+    "chunks_count": 71
+  },
+  "소상공인을_위한_개인정보_보호_핸드북": {
+    "doc_title": "소상공인을 위한 개인정보 보호 핸드북",
+    "doc_date": "2024.12",
+    "source_pdf": "★소상공인을 위한 개인정보 보호 핸드북(2024.12).pdf",
+    "chunks_count": 41
+  },
+  "질의응답_모음집": {
+    "doc_title": "개인정보 질의응답 모음집",
+    "doc_date": "2025.12",
+    "source_pdf": "1. 개인정보 질의응답 모음집(2025.12.).pdf",
+    "chunks_count": 99
+  },
+  "_built_at": "2026-05-01 09:24:34",
+  "_total_chunks": 211
+}

data/keyword_intents.yaml

@@ -0,0 +1,175 @@
+# 의도 메타데이터 — KPAA v2 라우팅 데이터.
+#
+# v2부터 라우팅 1차는 **LLM 의도 분류기**(Gemma 4 E2B JSON-mode 1샷)가 담당.
+# 이 yaml은 (1) LLM 분류 결과의 intent name → 조문 힌트(jo_hints)/소스 보강용 메타데이터,
+# (2) LLM 호출 실패·timeout 시 rule_route fallback 의 키워드 사전 (keywords 필드).
+#
+# 즉 keywords 큐레이션 부담은 사라졌고 (LLM이 자연어 의도 파악) keywords는 *fallback 안전망*만 됨.
+# intent 이름과 jo_hints/sources는 LLM 분류기 결과와 직접 연결되므로 정확하게 유지.
+#
+# 항목 형식:
+#   - intent: 의도 식별자 (snake_case) — llm_router.INTENT_LIST 와 1:1 매칭되어야 함
+#     keywords: rule_route fallback 매칭 키워드 (소문자/대소문자 무관, 부분일치)
+#     jo_hints: 개인정보 보호법 조문 번호 (없으면 빈 리스트)
+#     sources: 보강용 데이터 카테고리 (chain orchestrator 가 기본값을 결정하고, 여기 sources는 union으로 병합)
+#       - case          : 상담사례 1,745건 (로컬 SQLite)
+#       - law           : 본법(개인정보보호법) 조문 + jo_targets 명시 시 라이브
+#       - related_law   : data/related_laws.yaml 의 매칭된 법령 본문 (라이브)
+#       - pipc          : 개인정보보호위원회 결정문
+#       - interpretation: 법령해석례
+#       - precedent     : 판례 (대법원·하급심)
+#       - admin_rule    : 행정규칙(고시)
+
+- intent: 동의_수집
+  keywords: [동의, 수집, 받아도, 받아도되, 마케팅, 광고, 홍보]
+  jo_hints: ["15", "22"]
+  sources: [case, law, pipc, precedent]
+
+- intent: 민감정보
+  keywords: [민감정보, 진료기록, 건강, 질병, 병력, 환자, 사진, 안면, 지문, 홍채, 생체]
+  jo_hints: ["23"]
+  # 의료기관 사례 → 의료법까지 가져오게 related_law 활성. 환자/병원 키워드 매칭 시.
+  sources: [case, law, related_law, pipc, precedent]
+
+- intent: 고유식별정보
+  keywords: [주민등록번호, 주민번호, 외국인등록번호, 운전면허, 여권번호, 고유식별, 식별번호]
+  jo_hints: ["24", "24의2"]
+  # 주민등록법까지 → related_law 활성
+  sources: [case, law, related_law, pipc, precedent]
+
+- intent: 영상정보처리
+  keywords: [CCTV, cctv, 영상정보, 영상정보처리기기, 안내문, 안내판, 매장, 카메라, 녹음]
+  jo_hints: ["25"]
+  # CCTV 녹음은 통신비밀보호법까지 → related_law 활성
+  sources: [case, law, related_law, pipc, precedent]
+
+- intent: 유출신고
+  keywords: [유출, 분실, 도난, 신고, 통지, 침해, 누출]
+  jo_hints: ["34"]
+  # 안전성 확보조치 기준 고시까지 → admin_rule 활성
+  sources: [case, law, pipc, admin_rule]
+
+- intent: 처리위탁
+  keywords: [위탁, 외주, 클라우드, 처리위탁, 수탁]
+  jo_hints: ["26"]
+  sources: [case, law, pipc, admin_rule]
+
+- intent: 제3자제공
+  keywords: [제3자, 제공, 공유, 양도, 매각]
+  jo_hints: ["17", "18"]
+  sources: [case, law, pipc, precedent]
+
+- intent: 채용
+  keywords: [채용, 이력서, 직원, 입사지원, 면접, 인사, 근로]
+  jo_hints: ["15", "23", "24의2"]
+  sources: [case, law, pipc]
+
+- intent: 처리방침
+  keywords: [처리방침, 개인정보처리방침, 방침, 게시, 공개]
+  jo_hints: ["30"]
+  sources: [case, law, admin_rule]
+
+- intent: 파기
+  keywords: [파기, 보관기간, 보유기간, 보존, 폐기, 보관]
+  jo_hints: ["21"]
+  sources: [case, law, interpretation]
+
+- intent: 아동
+  keywords: [아동, 미성년, 14세, 만14세, 어린이, 청소년, 학생]
+  jo_hints: ["22의2"]
+  sources: [case, law, pipc]
+
+- intent: 정보주체_권리
+  keywords: [열람, 정정, 삭제, 처리정지, 권리, 본인요청]
+  jo_hints: ["35", "36", "37"]
+  sources: [case, law, pipc, interpretation]
+
+- intent: 안전조치
+  keywords: [안전조치, 암호화, 접근권한, 접근통제, 안전성, 보안]
+  jo_hints: ["29"]
+  # 안전성 확보조치 기준 고시가 핵심 → admin_rule 우선
+  sources: [law, admin_rule, pipc]
+
+- intent: 보호책임자
+  keywords: [개인정보보호책임자, CPO, 책임자, 보호책임자]
+  jo_hints: ["31"]
+  sources: [law, admin_rule]
+
+# 판례·처벌 사례 요청 — "○○법 위반 판례", "처벌 사례", "어떻게 판결됐어"
+# precedent 카테고리를 명시적으로 활성화하기 위한 intent.
+- intent: 판례_요청
+  keywords:
+    - 판례
+    - 판결
+    - 판시
+    - 사건번호
+    - 위반
+    - 위반사례
+    - 처벌
+    - 처분
+    - 손해배상
+    - 형사
+  jo_hints: []
+  sources: [law, precedent, pipc]
+
+# 메타/정의/일반 질문 — "○○법이 뭐야", "정의", "원칙"
+- intent: 법령_일반
+  keywords:
+    - 개인정보보호법
+    - 개인정보 보호법
+    - 보호법
+    - 개인정보가
+    - 개인정보란
+    - 정보주체
+    - 개인정보처리자
+    - 가명정보
+    - 민감정보가
+    - 정의
+    - 원칙
+    - 개념
+    - 의미
+    - 뭐야
+    - 뭐예요
+    - 무엇
+    - 알려줘
+    - 설명
+    - 무엇인가요
+  jo_hints: ["1", "2", "3"]
+  sources: [law]   # 정의 질문엔 본법 조문만 — 노이즈 방지
+
+# 관련 법령 — 사용자가 "다른 법", "함께 적용" 등을 묻거나
+# 정통망법·신용정보법·의료법 같은 특정 관련 법령을 언급하면 매칭.
+# (실제 법령명별 keywords는 data/related_laws.yaml 의 각 item에 있음 — 라우터가 거기서 자동 매칭)
+- intent: 관련_법령
+  keywords:
+    - 관련 법
+    - 관련된 법
+    - 다른 법
+    - 함께 적용
+    - 참조 법
+    - 어떤 법
+    - 적용되는 법
+  jo_hints: []
+  sources: [related_law]
+
+# 개정 이력 — "개정 내용", "바뀐 점", "신·구법 비교" 같이 *언제·어떻게 바뀌었는지*
+# 묻는 질문. 매칭되면 신구법비교(oldnew) 소스가 union 으로 활성화 — 어느 chain
+# 에서든 본법 신구법 본문이 추가로 붙는다.
+- intent: 개정_이력
+  keywords:
+    - 개정
+    - 바뀐
+    - 바뀌었
+    - 변경된
+    - 신구법
+    - 신·구
+    - 신구
+    - 개정안
+    - 개정 이력
+    - 개정사항
+    - 어떻게 바
+  jo_hints: []
+  # oldnew=법령 단위 신구비교, article_history=조문 단위 시점별 변경 이력.
+  # 둘은 *세분화 수준이 다른 보완 관계* — 함께 활성화. article_history 는
+  # plan.jo_targets 가 명시될 때만 fetch (구현 측에서 gating).
+  sources: [oldnew, law, article_history]

data/related_laws.yaml

@@ -0,0 +1,323 @@
+_meta:
+  _generated_at: '2026-04-29T12:05:21'
+  _sources:
+  - https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  - https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  _count: 34
+  _count_law: 12
+  _count_admin_rule: 22
+items:
+- name: 개인정보 보호법
+  short: 개인정보보호법
+  keywords:
+  - 개인정보 보호법
+  - 개인정보보호법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EA%B0%9C%EC%9D%B8%EC%A0%95%EB%B3%B4%20%EB%B3%B4%ED%98%B8%EB%B2%95
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '270351'
+- name: 개인정보 보호법 시행령
+  short: 개인정보보호법 시행령
+  keywords:
+  - 개인정보 보호법 시행령
+  - 개인정보보호법 시행령
+  - 보호법 시행령
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EA%B0%9C%EC%9D%B8%EC%A0%95%EB%B3%B4%20%EB%B3%B4%ED%98%B8%EB%B2%95%20%EC%8B%9C%ED%96%89%EB%A0%B9
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '273745'
+- name: 신용정보의 이용 및 보호에 관한 법률
+  short: 신용정보법
+  keywords:
+  - 신용정보의 이용 및 보호에 관한 법률
+  - 신용정보법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EC%8B%A0%EC%9A%A9%EC%A0%95%EB%B3%B4%EC%9D%98%20%EC%9D%B4%EC%9A%A9%20%EB%B0%8F%20%EB%B3%B4%ED%98%B8%EC%97%90%20%EA%B4%80%ED%95%9C%20%EB%B2%95%EB%A5%A0
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '260423'
+- name: 국가인권위원회법
+  short: 인권위법
+  keywords:
+  - 국가인권위원회법
+  - 인권위법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EA%B5%AD%EA%B0%80%EC%9D%B8%EA%B6%8C%EC%9C%84%EC%9B%90%ED%9A%8C%EB%B2%95
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '266711'
+- name: 공공기관의 운영에 관한 법률
+  short: 공공기관운영법
+  keywords:
+  - 공공기관의 운영에 관한 법률
+  - 공공기관운영법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EA%B3%B5%EA%B3%B5%EA%B8%B0%EA%B4%80%EC%9D%98%20%EC%9A%B4%EC%98%81%EC%97%90%20%EA%B4%80%ED%95%9C%20%EB%B2%95%EB%A5%A0
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '276057'
+- name: 지방공기업법
+  short: 지방공기업법
+  keywords:
+  - 지방공기업법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EC%A7%80%EB%B0%A9%EA%B3%B5%EA%B8%B0%EC%97%85%EB%B2%95
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '276345'
+- name: 초·중등교육법
+  short: 초중등교육법
+  keywords:
+  - 초·중등교육법
+  - 초중등교육법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EC%B4%88%C2%B7%EC%A4%91%EB%93%B1%EA%B5%90%EC%9C%A1%EB%B2%95
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: ''
+- name: 고등교육법
+  short: 고등교육법
+  keywords:
+  - 고등교육법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EA%B3%A0%EB%93%B1%EA%B5%90%EC%9C%A1%EB%B2%95
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '268513'
+- name: 주민등록법
+  short: 주민등록법
+  keywords:
+  - 주민등록법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EC%A3%BC%EB%AF%BC%EB%93%B1%EB%A1%9D%EB%B2%95
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '268555'
+- name: 전자정부법
+  short: 전자정부법
+  keywords:
+  - 전자정부법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EC%A0%84%EC%9E%90%EC%A0%95%EB%B6%80%EB%B2%95
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '268103'
+- name: 전자서명법
+  short: 전자서명법
+  keywords:
+  - 전자서명법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EC%A0%84%EC%9E%90%EC%84%9C%EB%AA%85%EB%B2%95
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '236201'
+- name: 공공기관의 정보공개에 관한 법률
+  short: 정보공개법
+  keywords:
+  - 공공기관의 정보공개에 관한 법률
+  - 정보공개법
+  kind: law
+  kind_label: 개인정보 관련 법률·시행령
+  url: https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EA%B3%B5%EA%B3%B5%EA%B8%B0%EA%B4%80%EC%9D%98%20%EC%A0%95%EB%B3%B4%EA%B3%B5%EA%B0%9C%EC%97%90%20%EA%B4%80%ED%95%9C%20%EB%B2%95%EB%A5%A0
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=116
+  mst: '251019'
+- name: 개인정보처리방법에관한고시
+  short: ''
+  keywords:
+  - 개인정보처리방법에관한고시
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/개인정보처리방법에관한고시
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 개인정보의안전성확보조치기준
+  short: ''
+  keywords:
+  - 개인정보의안전성확보조치기준
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/개인정보의안전성확보조치기준
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 개인정보의기술적·관리적보호조치
+  short: ''
+  keywords:
+  - 개인정보의기술적·관리적보호조치
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/(개인정보보호위원회)개인정보의기술적·관리적보호조치/(2023-7,20230922)
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 표준개인정보보호지침
+  short: ''
+  keywords:
+  - 표준개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/(개인정보보호위원회)표준개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 개인정보영향평가에관한고시
+  short: ''
+  keywords:
+  - 개인정보영향평가에관한고시
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/(개인정보보호위원회)개인정보영향평가에관한고시
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 개인정보보호자율규제단체지정등에관한규정
+  short: ''
+  keywords:
+  - 개인정보보호자율규제단체지정등에관한규정
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/(개인정보보호위원회)개인정보보호자율규제단체지정등에관한규정
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 정보보호및개인정보보호관리체계인증등에관한고시
+  short: ''
+  keywords:
+  - 정보보호및개인정보보호관리체계인증등에관한고시
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/정보보호및개인정보보호관리체계인증등에관한고시
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 가명정보의결합및반출등에관한고시
+  short: ''
+  keywords:
+  - 가명정보의결합및반출등에관한고시
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/가명정보의결합및반출등에관한고시
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 경찰청개인정보보호규칙
+  short: ''
+  keywords:
+  - 경찰청개인정보보호규칙
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/경찰청개인정보보호규칙
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 경찰청영상정보처리기기운영규칙
+  short: ''
+  keywords:
+  - 경찰청영상정보처리기기운영규칙
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/경찰청영상정보처리기기운영규칙
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 주민등록증발급신청서등의관리에관한규칙
+  short: ''
+  keywords:
+  - 주민등록증발급신청서등의관리에관한규칙
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/주민등록증발급신청서등의관리에관한규칙
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 국토교통부개인정보보호세부지침
+  short: ''
+  keywords:
+  - 국토교통부개인정보보호세부지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/국토교통부개인정보보호세부지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 농림축산식품부개인정보보호지침
+  short: ''
+  keywords:
+  - 농림축산식품부개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/농림축산식품부개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 문화체육관광부개인정보보호지침
+  short: ''
+  keywords:
+  - 문화체육관광부개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/문화체육관광부개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 법무부개인정보보호지침
+  short: ''
+  keywords:
+  - 법무부개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/법무부개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 병무청개인정보보호관리규정
+  short: ''
+  keywords:
+  - 병무청개인정보보호관리규정
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/병무청개인정보보호관리규정
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 병무행정정보업무관리규정
+  short: ''
+  keywords:
+  - 병무행정정보업무관리규정
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/병무행정정보업무관리규정
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 산림청개인정보보호지침
+  short: ''
+  keywords:
+  - 산림청개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/산림청개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 중소벤처기업부개인정보보호지침
+  short: ''
+  keywords:
+  - 중소벤처기업부개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/중소벤처기업부개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 통계청개인정보보호지침
+  short: ''
+  keywords:
+  - 통계청개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/통계청개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 행정안전부개인정보보호지침
+  short: ''
+  keywords:
+  - 행정안전부개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/행정안전부개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''
+- name: 환경부개인정보보호지침
+  short: ''
+  keywords:
+  - 환경부개인정보보호지침
+  kind: admin_rule
+  kind_label: 개인정보 관련 행정규칙(고시·지침)
+  url: https://www.law.go.kr/행정규칙/환경부개인정보보호지침
+  source: https://www.privacy.go.kr/front/contents/cntntsView.do?contsNo=117
+  mst: ''

data/seed_laws.json

@@ -0,0 +1,20 @@
+{
+  "_doc": "라이브 검증 2026-04-29 — 법제처 OPEN API search_law 결과 캡쳐",
+  "personal_info_protection_act": {
+    "name": "개인정보 보호법",
+    "name_short": "개인정보보호법",
+    "mst": "270351",
+    "law_id": "011357",
+    "type_name": "법률",
+    "department": "개인정보보호위원회",
+    "promulgate_date": "20250401",
+    "enforce_date": "20251002"
+  },
+  "personal_info_protection_act_enforcement_decree": {
+    "name": "개인정보 보호법 시행령",
+    "mst": "273745",
+    "type_name": "대통령령",
+    "department": "개인정보보호위원회",
+    "enforce_date": "20251002"
+  }
+}

pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "korean-privacy-ai-assistant"
+version = "0.1.0"
+description = "Korean Privacy Law (개인정보보호법) consultation chatbot for individuals, SMBs, and small clinics"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = ["korean-law", "privacy", "개인정보보호법", "rag", "chatbot", "gemma"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Natural Language :: Korean",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "httpx[http2]>=0.27",
+  "pydantic>=2.6",
+  "pydantic-settings>=2.2",
+  "lxml>=5",
+  "diskcache>=5.6",
+  "tenacity>=8",
+  "platformdirs>=4",
+  "fastapi>=0.110",
+  "uvicorn[standard]>=0.27",
+  "python-dotenv>=1",
+  "pyyaml>=6",
+  "huggingface-hub>=0.23",
+  "tqdm>=4.66",
+  "sse-starlette>=2.1",
+  "truststore>=0.10",
+]
+
+[project.optional-dependencies]
+llm = ["llama-cpp-python>=0.3"]
+# HF Spaces (ZeroGPU) 데모 배포용 — 같은 가중치 `google/gemma-4-E2B-it` 를
+# transformers + @spaces.GPU 로 돌린다. 로컬 사용자는 설치 불필요.
+hf = [
+  "gradio>=5.0",
+  "transformers>=4.45",
+  "torch>=2.4",
+  "accelerate>=0.34",
+  "spaces>=0.30",
+]
+# 빌드 타임 docling 의존성 — 두 용도가 같은 패키지 셋을 공유:
+#   1) PIPC 결정문 별지(이미지) → markdown OCR. 옵트인:
+#        pip install -e ".[pipc-ocr]"
+#        export KPAA_PIPC_OCR=1
+#      EasyOCR 한국어 모델로 한글 별지 정확도 ↑ (docling 기본 ocrmac 대비).
+#   2) `kpaa extract-guide` (안내서 PDF → markdown). born-digital 이라 OCR 없이
+#      텍스트 직접 추출 → easyocr 가중치 다운로드는 발생하지 않음. 이후 청킹은
+#      사용자 + Claude 인터랙티브 큐레이션 → `data/guide/chunks/*.jsonl`.
+# 런타임(검색·답변)은 sqlite3 만 필요 — 일반 사용자는 이 extra 설치 불필요.
+pipc-ocr = ["docling>=2.0", "easyocr>=1.7"]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "vcrpy>=6",
+  "ruff>=0.4",
+  "invoke>=2.2",
+]
+
+[project.scripts]
+kpaa = "kpaa.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/sz1-kca/korean-privacy-ai-assistant"
+Issues = "https://github.com/sz1-kca/korean-privacy-ai-assistant/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kpaa"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["E501"]
+# SIM 룰은 가독성 호불호가 갈려서 select에서 제외 (한국어 분기 코드 가독성 우선)
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

requirements.txt

@@ -0,0 +1,35 @@
+# Hugging Face Spaces (Gradio SDK + ZeroGPU) 빌드용 평탄화 의존성.
+# 로컬 노트북 사용자는 이 파일을 쓰지 말고 `pip install -e ".[llm]"` (또는 pyproject.toml) 사용.
+# 이 파일은 HF Spaces 가 자동으로 `pip install -r requirements.txt` 로 처리.
+#
+# llama-cpp-python 은 *의도적으로* 빠짐 — HF Spaces 에서는 ZeroGPU 백엔드
+# (transformers + @spaces.GPU) 가 활성화되므로 필요 없음.
+
+# ── core (pyproject.toml dependencies 와 동기화) ──
+httpx[http2]>=0.27
+pydantic>=2.6
+pydantic-settings>=2.2
+lxml>=5
+diskcache>=5.6
+tenacity>=8
+platformdirs>=4
+fastapi>=0.110
+uvicorn[standard]>=0.27
+python-dotenv>=1
+pyyaml>=6
+huggingface-hub>=1.3   # transformers 5.x 가 요구. Gradio 5.20+ 은 HfFolder 의존 제거.
+tqdm>=4.66
+sse-starlette>=2.1
+truststore>=0.10
+
+# ── HF Spaces (ZeroGPU + Gradio) ──
+gradio>=5.0
+transformers>=5.0   # Gemma 4 토크나이저는 5.x 부터 (extra_special_tokens 리스트 포맷)
+torch>=2.4
+accelerate>=0.34
+spaces>=0.30
+
+# ── 패키지 자체 ──
+# HF Spaces 는 requirements.txt 처리 시점에 app 파일이 아직 /home/user/app 에
+# mount 되어 있지 않아 `-e .` 가 동작하지 않는다. 대신 app.py 에서
+# `src/` 를 sys.path 에 prepend 한다.

src/kpaa/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

src/kpaa/__main__.py

@@ -0,0 +1,4 @@
+from kpaa.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/kpaa/cases/__init__.py

@@ -0,0 +1,46 @@
+"""개인정보보호위원회 상담사례 (privacy.go.kr) — 로컬 SQLite FTS5 인덱스.
+
+    from kpaa.cases import CasesIndex
+    idx = CasesIndex.default()
+    hits = idx.search("CCTV 안내문구", k=3)
+    for h in hits:
+        print(h.citation(), h.title)
+
+리포 동봉 스냅샷은 `data/cases.sqlite`. 갱신은 `kpaa refresh-cases`.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from kpaa.cases.index import (
+    count as _count,
+)
+from kpaa.cases.index import (
+    default_db_path,
+    default_meta_path,
+)
+from kpaa.cases.index import (
+    search as _search,
+)
+from kpaa.cases.models import Case
+
+
+class CasesIndex:
+    """사용자 친화적 진입점."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self.db_path = db_path or default_db_path()
+
+    @classmethod
+    def default(cls) -> CasesIndex:
+        return cls()
+
+    @property
+    def total(self) -> int:
+        return _count(self.db_path)
+
+    def search(self, query: str, *, k: int = 5) -> list[Case]:
+        return _search(query, k=k, db_path=self.db_path)
+
+
+__all__ = ["CasesIndex", "Case", "default_db_path", "default_meta_path"]

src/kpaa/cases/index.py

@@ -0,0 +1,340 @@
+"""SQLite FTS5 인덱스 — 한국어 본문은 `unicode61` tokenizer 사용.
+
+(trigram도 시도했으나 길이 2 한국어 단어 — "병원", "환자", "동의", "유출",
+"신고" — 가 인덱싱되지 않아 부적합. unicode61은 띄어쓰기 단위 토큰화로
+한국어 검색에 안정적이며 SQLite 표준 기본값이라 추가 의존 없음.)
+
+DB 스키마:
+    cases(ntt_id PK, ntt_no, title, body, summary, type_code, type_label,
+          category1, category2, category3, reg_dt, case_year,
+          source_note, detail_url)
+    cases_fts (FTS5 가상테이블, 검색용)
+
+검색 결과 정렬은 `bm25(cases_fts)` 기본. 더 높은 점수 = 덜 관련 → 오름차순.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+from collections.abc import Iterable
+from pathlib import Path
+
+from kpaa.cases.models import Case
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS cases (
+    ntt_id        TEXT PRIMARY KEY,
+    ntt_no        TEXT,
+    title         TEXT,
+    body          TEXT,
+    summary       TEXT,
+    type_code     TEXT,
+    type_label    TEXT,
+    category1     TEXT,
+    category2     TEXT,
+    category3     TEXT,
+    reg_dt        TEXT,
+    case_year     TEXT,
+    source_note   TEXT,
+    detail_url    TEXT,
+    chunk_context TEXT
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS cases_fts USING fts5(
+    ntt_id UNINDEXED,
+    title,
+    body,
+    category UNINDEXED,
+    tokenize = "unicode61 remove_diacritics 2"
+);
+"""
+
+
+def default_db_path() -> Path:
+    """리포 동봉 스냅샷 경로(`data/cases.sqlite`)."""
+    return _data_dir() / "cases.sqlite"
+
+
+def default_meta_path() -> Path:
+    return _data_dir() / "cases_meta.json"
+
+
+def default_jsonl_path() -> Path:
+    """기본 JSONL export 경로 — `default_db_path()`와 같은 폴더."""
+    return default_db_path().parent / "cases_chunks.jsonl"
+
+
+# JSONL export 컬럼 — 변경 시 cases_chunks.jsonl 스키마가 바뀜
+_EXPORT_COLUMNS = (
+    "ntt_id", "ntt_no", "title", "summary", "body",
+    "type_code", "type_label",
+    "category1", "category2", "category3",
+    "reg_dt", "case_year", "source_note", "detail_url",
+    "chunk_context",
+)
+
+
+def _data_dir() -> Path:
+    """레포 루트의 data/ 폴더 우선, 없으면 사용자 캐시."""
+    repo_data = Path(__file__).resolve().parents[3] / "data"
+    if repo_data.exists():
+        return repo_data
+    from kpaa.config import get_settings
+
+    p = get_settings().cache_root / "cases"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _connect(db_path: Path) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    conn.executescript(SCHEMA_SQL)
+    return conn
+
+
+def _fts_body(case: Case) -> str:
+    """FTS body 컬럼: chunk_context가 있으면 body 앞에 prepend (Anthropic Contextual Retrieval)."""
+    if case.chunk_context:
+        return f"{case.chunk_context}\n\n{case.body}"
+    return case.body
+
+
+def export_jsonl(
+    *, db_path: Path | None = None, out_path: Path | None = None
+) -> int:
+    """cases.sqlite를 JSONL로 export — `cases_chunks.jsonl` 동기화용.
+
+    각 라인 = 1 사례, ntt_id 정수 오름차순, 모든 컬럼(chunk_context 포함).
+    `build_index()` / `upsert_cases()` 끝에서 자동 호출되므로 DB와 jsonl이
+    항상 동기화. chunk_context를 직접 SQL UPDATE한 경우엔 수동으로 한번 더
+    호출하면 jsonl에 반영됨.
+
+    out_path 미지정 시 `db_path` 옆에 `cases_chunks.jsonl`로 저장.
+    """
+    path = db_path or default_db_path()
+    if not path.exists():
+        return 0
+    out = out_path or (path.parent / "cases_chunks.jsonl")
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    conn = _connect(path)
+    n = 0
+    try:
+        cur = conn.execute(
+            f"SELECT {', '.join(_EXPORT_COLUMNS)} FROM cases "
+            "ORDER BY CAST(ntt_id AS INTEGER)"
+        )
+        with out.open("w", encoding="utf-8") as f:
+            for r in cur:
+                rec = {c: (r[c] or "") for c in _EXPORT_COLUMNS}
+                f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+                n += 1
+    finally:
+        conn.close()
+    return n
+
+
+def build_index(cases: Iterable[Case], *, db_path: Path) -> None:
+    """전체 다시 빌드 — 단순화를 위해 기존 데이터 wipe 후 재삽입.
+
+    빌드 후 `cases_chunks.jsonl`을 자동 export해 DB와 동기화.
+    """
+    conn = _connect(db_path)
+    try:
+        with conn:
+            conn.execute("DELETE FROM cases")
+            conn.execute("DELETE FROM cases_fts")
+            for case in cases:
+                conn.execute(
+                    """INSERT INTO cases
+                       (ntt_id, ntt_no, title, body, summary,
+                        type_code, type_label, category1, category2, category3,
+                        reg_dt, case_year, source_note, detail_url, chunk_context)
+                       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+                    (
+                        case.ntt_id, case.ntt_no, case.title, case.body, case.summary,
+                        case.type_code, case.type_label,
+                        case.category1, case.category2, case.category3,
+                        case.reg_dt, case.case_year, case.source_note, case.detail_url,
+                        case.chunk_context,
+                    ),
+                )
+                category = " > ".join(filter(None, (case.category1, case.category2, case.category3)))
+                conn.execute(
+                    "INSERT INTO cases_fts (ntt_id, title, body, category) VALUES (?,?,?,?)",
+                    (case.ntt_id, case.title, _fts_body(case), category),
+                )
+        conn.execute("VACUUM")
+    finally:
+        conn.close()
+    export_jsonl(db_path=db_path)
+
+
+def upsert_cases(cases: Iterable[Case], *, db_path: Path) -> int:
+    """증분 갱신: 기존 ntt_id 충돌 시 덮어씀. jsonl도 자동 동기화."""
+    conn = _connect(db_path)
+    n = 0
+    try:
+        with conn:
+            for case in cases:
+                # 기존 ntt_id 행 삭제 후 재삽입 (FTS5 재인덱싱 위함)
+                conn.execute("DELETE FROM cases WHERE ntt_id = ?", (case.ntt_id,))
+                conn.execute("DELETE FROM cases_fts WHERE ntt_id = ?", (case.ntt_id,))
+                conn.execute(
+                    """INSERT INTO cases
+                       (ntt_id, ntt_no, title, body, summary,
+                        type_code, type_label, category1, category2, category3,
+                        reg_dt, case_year, source_note, detail_url, chunk_context)
+                       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+                    (
+                        case.ntt_id, case.ntt_no, case.title, case.body, case.summary,
+                        case.type_code, case.type_label,
+                        case.category1, case.category2, case.category3,
+                        case.reg_dt, case.case_year, case.source_note, case.detail_url,
+                        case.chunk_context,
+                    ),
+                )
+                category = " > ".join(filter(None, (case.category1, case.category2, case.category3)))
+                conn.execute(
+                    "INSERT INTO cases_fts (ntt_id, title, body, category) VALUES (?,?,?,?)",
+                    (case.ntt_id, case.title, _fts_body(case), category),
+                )
+                n += 1
+    finally:
+        conn.close()
+    if n:
+        export_jsonl(db_path=db_path)
+    return n
+
+
+def search(
+    query: str, *, k: int = 5, db_path: Path | None = None
+) -> list[Case]:
+    """trigram FTS5 검색.
+
+    Args:
+        query: 한국어 키워드 (단일 단어 또는 다중 단어)
+        k: 최대 결과 수
+    """
+    path = db_path or default_db_path()
+    if not path.exists():
+        return []
+    if not query.strip():
+        return []
+    conn = _connect(path)
+    try:
+        # 따옴표/구두점을 sanitize 후 토큰 단위로 분리.
+        # 다중 토큰은 OR로 결합 → 한 단어만 일치해도 후보로 끌어옴.
+        # 단일 토큰은 그대로 phrase 처리.
+        safe = "".join(ch if ch.isalnum() or ord(ch) > 127 else " " for ch in query)
+        tokens = [t for t in safe.split() if t]
+        if not tokens:
+            return []
+        # prefix matching(`token*`)을 모든 토큰에 적용 — 한국어 조사 결합
+        # ("유출된", "검색사이트에") 도 매칭되게 함.
+        if len(tokens) == 1:
+            fts_query = f"{tokens[0]}*"
+        else:
+            fts_query = " OR ".join(f"{t}*" for t in tokens)
+        cur = conn.execute(
+            """SELECT c.* FROM cases_fts f
+               JOIN cases c ON c.ntt_id = f.ntt_id
+               WHERE cases_fts MATCH ?
+               ORDER BY bm25(cases_fts) ASC
+               LIMIT ?""",
+            (fts_query, k),
+        )
+        rows = cur.fetchall()
+    finally:
+        conn.close()
+    return [
+        Case(
+            ntt_id=r["ntt_id"], ntt_no=r["ntt_no"],
+            title=r["title"], summary=r["summary"], body=r["body"],
+            type_code=r["type_code"], type_label=r["type_label"],
+            category1=r["category1"], category2=r["category2"], category3=r["category3"],
+            reg_dt=r["reg_dt"], case_year=r["case_year"],
+            source_note=r["source_note"], detail_url=r["detail_url"],
+            chunk_context=(r["chunk_context"] if "chunk_context" in r.keys() else "") or "",
+        )
+        for r in rows
+    ]
+
+
+def count(db_path: Path | None = None) -> int:
+    path = db_path or default_db_path()
+    if not path.exists():
+        return 0
+    conn = _connect(path)
+    try:
+        cur = conn.execute("SELECT COUNT(*) FROM cases")
+        return cur.fetchone()[0]
+    finally:
+        conn.close()
+
+
+def list_all_cases(*, db_path: Path | None = None) -> list[Case]:
+    """기존 cases 테이블에서 모든 행을 Case 객체로 반환 (FTS5 재빌드 등에 사용)."""
+    path = db_path or default_db_path()
+    if not path.exists():
+        return []
+    conn = _connect(path)
+    try:
+        cur = conn.execute("SELECT * FROM cases")
+        rows = cur.fetchall()
+    finally:
+        conn.close()
+    return [
+        Case(
+            ntt_id=r["ntt_id"], ntt_no=r["ntt_no"],
+            title=r["title"], summary=r["summary"], body=r["body"],
+            type_code=r["type_code"], type_label=r["type_label"],
+            category1=r["category1"], category2=r["category2"], category3=r["category3"],
+            reg_dt=r["reg_dt"], case_year=r["case_year"],
+            source_note=r["source_note"], detail_url=r["detail_url"],
+            chunk_context=(r["chunk_context"] if "chunk_context" in r.keys() else "") or "",
+        )
+        for r in rows
+    ]
+
+
+def rebuild_fts(*, db_path: Path | None = None) -> int:
+    """cases 테이블 데이터로 cases_fts만 재생성. tokenizer 변경 후 사용.
+
+    스크래이프 없이 빠르게 인덱스만 갱신. chunk_context 일괄 UPDATE 후
+    호출하면 jsonl도 자동 동기화.
+    """
+    path = db_path or default_db_path()
+    cases = list_all_cases(db_path=path)
+    if not cases:
+        return 0
+    conn = _connect(path)
+    try:
+        with conn:
+            conn.execute("DROP TABLE IF EXISTS cases_fts")
+        # _connect가 schema를 다시 생성 — close & re-open 으로 새 schema 적용
+    finally:
+        conn.close()
+    conn = _connect(path)
+    try:
+        with conn:
+            for case in cases:
+                category = " > ".join(filter(None, (case.category1, case.category2, case.category3)))
+                conn.execute(
+                    "INSERT INTO cases_fts (ntt_id, title, body, category) VALUES (?,?,?,?)",
+                    (case.ntt_id, case.title, _fts_body(case), category),
+                )
+        conn.execute("VACUUM")
+    finally:
+        conn.close()
+    export_jsonl(db_path=path)
+    return len(cases)
+
+
+__all__ = [
+    "build_index", "upsert_cases", "search", "count",
+    "list_all_cases", "rebuild_fts", "export_jsonl",
+    "default_db_path", "default_meta_path", "default_jsonl_path",
+]

src/kpaa/cases/models.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Case(BaseModel):
+    """개인정보보호위원회 상담사례 1건.
+
+    privacy.go.kr `/front/case/onMadangListAjax.do`의 `resultDocuments` 1개 항목
+    에 1:1 매핑.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    ntt_no: str          # 케이스 번호 (예: "311")
+    ntt_id: str          # 내부 ID (예: "10561")
+    title: str           # NTT_SJ — 질문(제목)
+    summary: str         # NTT_CN  — 짧은 요약
+    body: str            # NTT_CN_FULL — 답변 본문 (HTML 엔티티 디코딩 후)
+    type_code: str       # NTT_TYPE — "INT" | "GUI"
+    type_label: str      # NTT_TYPE_NM — 한글 라벨
+    category1: str       # CASE_CLASS1_NM — 정보주체/처리자(민간/공공)
+    category2: str       # CASE_CLASS2_NM — 분야 (수집·이용 등)
+    category3: str       # CASE_CLASS3_NM — 업종 (경영·사무 등)
+    reg_dt: str          # YYYYMMDD
+    case_year: str       # YYYY
+    source_note: str     # ETC_CN
+    detail_url: str      # /front/case/view.do?ntt_id=...&nttno=...
+    chunk_context: str = ""  # Anthropic Contextual Retrieval prefix — 인덱싱 시 body 앞에 prepend (답변 출력은 body만)
+
+    def citation(self) -> str:
+        """답변에 박을 인용 태그.
+
+        예: '개인정보 상담사례 #311 (2024)'
+        """
+        if self.case_year:
+            return f"개인정보 상담사례 #{self.ntt_no} ({self.case_year})"
+        return f"개인정보 상담사례 #{self.ntt_no}"
+
+    def absolute_url(self) -> str:
+        if self.detail_url.startswith("http"):
+            return self.detail_url
+        return f"https://www.privacy.go.kr{self.detail_url}"

src/kpaa/cases/scraper.py

@@ -0,0 +1,268 @@
+"""privacy.go.kr 상담사례 1,745건 스크래퍼.
+
+엔드포인트(라이브 검증 2026-04-29):
+    https://www.privacy.go.kr/front/case/onMadangListAjax.do?page=N
+
+응답 JSON에서 `resultSet.result`는 7개 facet 그룹이 있고 그중
+**index 2 (totalSize=1745)** 가 케이스 본문 포함 그룹이다.
+다른 그룹은 통계/이벤트/게시판 ID들로 무관.
+
+각 페이지당 10건. 총 ~175페이지. 폴라이트 레이트 1.5 req/s.
+
+본문(`NTT_CN_FULL`)에는 HTML 엔티티(`(`, `·` 등)가 들어 있어
+`html.unescape()`로 풀어 저장한다.
+"""
+from __future__ import annotations
+
+import asyncio
+import html
+import json
+import logging
+import math
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from kpaa.cases.models import Case
+from kpaa.config import get_settings
+
+logger = logging.getLogger("kpaa.cases")
+
+LIST_URL = "https://www.privacy.go.kr/front/case/onMadangListAjax.do"
+ROBOTS_URL = "https://www.privacy.go.kr/robots.txt"
+
+# 폴라이트 레이트
+MIN_REQ_INTERVAL = 1.0 / 1.5   # 1.5 req/s → 0.667s
+TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+USER_AGENT = "kpaa/0.1 (+https://github.com/sz1-kca/korean-privacy-ai-assistant; cases-scraper)"
+
+# resultSet.result 의 index 2 그룹이 본문 포함 (라이브 검증으로 확인)
+CASE_GROUP_INDEX = 2
+
+# 한 답변 본문 trim (Plan: ≤1500자 컨텍스트 안전)
+BODY_LIMIT = 1500
+
+
+def _enable_truststore() -> None:
+    """macOS Python.framework SSL 이슈 회피 — 시스템 신뢰 저장소 사용."""
+    try:
+        import truststore
+
+        truststore.inject_into_ssl()
+    except ImportError:
+        logger.debug("truststore not available; relying on certifi")
+
+
+def _decode_body(raw: str) -> str:
+    """HTML 엔티티(`(`, `·`) 디코드 + 다중 공백 정리."""
+    if not raw:
+        return ""
+    text = html.unescape(raw)
+    # 너무 긴 본문은 trim (chatbot 컨텍스트 안전)
+    if len(text) > BODY_LIMIT:
+        text = text[: BODY_LIMIT].rstrip() + "\n…(중략)…"
+    return text
+
+
+def _to_case(doc: dict[str, Any]) -> Case | None:
+    """resultDocuments 1개 항목을 Case로 변환. 본문 필드 없으면 None."""
+    body_raw = doc.get("NTT_CN_FULL") or doc.get("NTT_CN") or ""
+    if not body_raw:
+        return None
+    return Case(
+        ntt_no=str(doc.get("NTT_NO") or "").strip(),
+        ntt_id=str(doc.get("NTT_ID") or "").strip(),
+        title=str(doc.get("NTT_SJ") or "").strip(),
+        summary=_decode_body(str(doc.get("NTT_CN") or "")),
+        body=_decode_body(str(body_raw)),
+        type_code=str(doc.get("NTT_TYPE") or "").strip(),
+        type_label=str(doc.get("NTT_TYPE_NM") or "").strip(),
+        category1=str(doc.get("CASE_CLASS1_NM") or "").strip(),
+        category2=str(doc.get("CASE_CLASS2_NM") or "").strip(),
+        category3=str(doc.get("CASE_CLASS3_NM") or "").strip(),
+        reg_dt=str(doc.get("REG_DT") or "").strip(),
+        case_year=str(doc.get("CASE_YEAR") or "").strip(),
+        source_note=str(doc.get("ETC_CN") or "").strip(),
+        detail_url=str(doc.get("URL_ADDR") or "").strip(),
+    )
+
+
+async def check_robots(client: httpx.AsyncClient) -> tuple[bool, str]:
+    """robots.txt 확인. (/front/case/ 경로 허용 여부, 원문)."""
+    r = await client.get(ROBOTS_URL)
+    text = r.text
+    # 매우 보수적 파서: 명시적 disallow에 /front/case가 포함되면 False
+    in_wildcard = False
+    forbidden = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.lower().startswith("user-agent:"):
+            in_wildcard = line.split(":", 1)[1].strip() == "*"
+        elif in_wildcard and line.lower().startswith("disallow:"):
+            path = line.split(":", 1)[1].strip()
+            if path:
+                forbidden.append(path)
+    case_blocked = any(p.startswith("/front/case") for p in forbidden)
+    return (not case_blocked, text)
+
+
+async def fetch_page(
+    client: httpx.AsyncClient, page: int
+) -> tuple[list[Case], int]:
+    """1 페이지 호출 → (cases, total_count)."""
+    r = await client.get(
+        LIST_URL,
+        params={"page": str(page)},
+        headers={
+            "User-Agent": USER_AGENT,
+            "X-Requested-With": "XMLHttpRequest",
+            "Accept": "application/json",
+        },
+    )
+    r.raise_for_status()
+    data = r.json()
+    result = data.get("resultSet", {}).get("result", [])
+    if len(result) <= CASE_GROUP_INDEX:
+        logger.warning("page %d: result group %d missing", page, CASE_GROUP_INDEX)
+        return ([], 0)
+    grp = result[CASE_GROUP_INDEX]
+    total = int(float(grp.get("totalSize", 0)))
+    docs = grp.get("resultDocuments", [])
+    cases = []
+    for doc in docs:
+        case = _to_case(doc)
+        if case is not None:
+            cases.append(case)
+    return (cases, total)
+
+
+async def fetch_all(
+    *,
+    since: str | None = None,
+    respect_robots: bool = False,
+    progress: bool = True,
+) -> tuple[list[Case], dict[str, Any]]:
+    """전수 페이지네이션 스크래이프.
+
+    Args:
+        since: "YYYY-MM-DD"면 그 일자 이후 등록된 케이스만 keep (증분).
+        respect_robots: True면 robots.txt 명시 disallow 발견시 중단.
+        progress: True면 페이지 진행률 한 줄씩 출력.
+    """
+    _enable_truststore()
+    since_yyyymmdd = ""
+    if since:
+        # "YYYY-MM-DD" → "YYYYMMDD"
+        since_yyyymmdd = since.replace("-", "").strip()
+
+    async with httpx.AsyncClient(timeout=TIMEOUT, follow_redirects=True) as c:
+        if respect_robots:
+            allowed, _txt = await check_robots(c)
+            if not allowed:
+                raise PermissionError(
+                    "robots.txt에서 /front/case 경로를 disallow하고 있습니다. "
+                    "스크래이프를 중단합니다."
+                )
+        # 1페이지로 totalCnt 확보
+        first_cases, total = await fetch_page(c, 1)
+        if total == 0:
+            return ([], {"total": 0, "pages": 0, "fetched": 0})
+
+        pages = math.ceil(total / 10)
+        all_cases: list[Case] = list(first_cases)
+        last_req_at = time.monotonic()
+
+        for page in range(2, pages + 1):
+            # 폴라이트 레이트
+            elapsed = time.monotonic() - last_req_at
+            wait = MIN_REQ_INTERVAL - elapsed
+            if wait > 0:
+                await asyncio.sleep(wait)
+            last_req_at = time.monotonic()
+            try:
+                cases, _ = await fetch_page(c, page)
+            except httpx.HTTPError as e:
+                logger.warning("page %d failed: %s — skipping", page, e)
+                continue
+            all_cases.extend(cases)
+            if progress and page % 10 == 0:
+                print(
+                    f"  …page {page}/{pages} "
+                    f"({len(all_cases)} cases fetched)",
+                    flush=True,
+                )
+
+        # 증분 필터
+        if since_yyyymmdd:
+            all_cases = [c for c in all_cases if c.reg_dt >= since_yyyymmdd]
+
+        # ntt_id 중복 제거 (안전장치)
+        seen: set[str] = set()
+        deduped: list[Case] = []
+        for case in all_cases:
+            key = case.ntt_id or f"no:{case.ntt_no}"
+            if key in seen:
+                continue
+            seen.add(key)
+            deduped.append(case)
+
+        meta = {
+            "total": total,
+            "pages": pages,
+            "fetched": len(deduped),
+            "scraped_at": datetime.now().isoformat(timespec="seconds"),
+            "source_url": LIST_URL,
+            "since": since or "",
+        }
+        return (deduped, meta)
+
+
+async def refresh(
+    *,
+    since: str | None = None,
+    respect_robots: bool = False,
+) -> int:
+    """스크래이프 → SQLite 인덱스 빌드 → meta 갱신. CLI 진입점."""
+    from kpaa.cases.index import build_index, default_db_path, default_meta_path
+
+    print(f"▶ privacy.go.kr 상담사례 스크래이프 시작 (since={since or 'ALL'})")
+    cases, meta = await fetch_all(since=since, respect_robots=respect_robots)
+    if not cases:
+        print("(가져온 케이스 없음)")
+        return 0
+
+    db_path = default_db_path()
+    meta_path = default_meta_path()
+    print(f"▶ {len(cases)}건 → SQLite FTS5 인덱스 빌드: {db_path}")
+    build_index(cases, db_path=db_path)
+
+    # 메타 저장
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    with meta_path.open("w", encoding="utf-8") as f:
+        json.dump(meta, f, ensure_ascii=False, indent=2)
+    print(f"▶ 메타: {meta_path}")
+    print(
+        f"  total(remote)={meta['total']}  fetched={meta['fetched']}  "
+        f"scraped_at={meta['scraped_at']}"
+    )
+    return 0
+
+
+__all__ = ["fetch_all", "fetch_page", "refresh", "check_robots"]
+
+
+# 사전 스냅샷 경로 헬퍼 (data/cases.sqlite) — index.py에서 사용
+def _project_data_dir() -> Path:
+    """리포 안의 data/ 폴더를 우선 사용, 그 외에는 user_cache."""
+    repo_data = Path(__file__).resolve().parents[3] / "data"
+    if repo_data.exists():
+        return repo_data
+    s = get_settings()
+    p = s.cache_root / "cases"
+    p.mkdir(parents=True, exist_ok=True)
+    return p

src/kpaa/cli.py

@@ -0,0 +1,416 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+
+def _utf8_console() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+        except (AttributeError, OSError):
+            pass
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="kpaa", description="개인정보보호법 미니 상담 챗봇 CLI")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # ── serve / smoke / eval ────────────────────────────────────────
+    p_serve = sub.add_parser("serve", help="FastAPI 백엔드 실행")
+    p_serve.add_argument("--host", default=None)
+    p_serve.add_argument("--port", type=int, default=None)
+
+    p_smoke = sub.add_parser("smoke", help="단일 질문으로 RAG 파이프라인 종단 검증 (LLM 포함)")
+    p_smoke.add_argument("query")
+
+    p_retrieve = sub.add_parser(
+        "retrieve",
+        help="RAG 컨텍스트 블록만 빌드 (LLM 호출 없음 — 검증용)",
+    )
+    p_retrieve.add_argument("query")
+
+    p_route = sub.add_parser(
+        "route",
+        help="라우터 결과만 출력 (intents/jo/mst/sources, LLM·검색 없음)",
+    )
+    p_route.add_argument("query")
+
+    p_eval = sub.add_parser("eval", help="골든 질문 일괄 평가 (LLM 라이브)")
+    p_eval.add_argument("--limit", type=int, default=None, help="첫 N건만 실행")
+    p_eval.add_argument("--show-answers", action="store_true", help="모든 답변 본문 출력")
+    p_eval.add_argument("--out", default=None, help="결과 JSON 저장 경로")
+
+    # ── law ─────────────────────────────────────────────────────────
+    p_law = sub.add_parser("law", help="법제처 SDK 직접 호출 (법령)")
+    law_sub = p_law.add_subparsers(dest="law_cmd", required=True)
+    sp = law_sub.add_parser("search", help="법령 검색")
+    sp.add_argument("query")
+    sp.add_argument("--display", type=int, default=10)
+
+    sp = law_sub.add_parser("text", help="법령 본문 또는 특정 조문")
+    sp.add_argument("mst", help="법령일련번호 (예: 270351 = 개인정보 보호법)")
+    sp.add_argument("--jo", help='조문 번호 (예: "15", "24의2")')
+
+    sp = law_sub.add_parser("annexes", help="별표·별지서식 검색")
+    sp.add_argument("--law-id", help="관련법령ID(6자리, 예: 011357)", default=None)
+    sp.add_argument("--query", default="")
+    sp.add_argument("--display", type=int, default=10)
+
+    # ── pipc ────────────────────────────────────────────────────────
+    p_pipc = sub.add_parser("pipc", help="개인정보보호위원회 결정문")
+    pipc_sub = p_pipc.add_subparsers(dest="pipc_cmd", required=True)
+    sp = pipc_sub.add_parser("search")
+    sp.add_argument("query")
+    sp.add_argument("--display", type=int, default=10)
+    sp = pipc_sub.add_parser("text")
+    sp.add_argument("decision_id")
+
+    # ── expc (interpretation) ───────────────────────────────────────
+    p_expc = sub.add_parser("expc", help="법령해석례")
+    expc_sub = p_expc.add_subparsers(dest="expc_cmd", required=True)
+    sp = expc_sub.add_parser("search")
+    sp.add_argument("query")
+    sp.add_argument("--display", type=int, default=10)
+    sp = expc_sub.add_parser("text")
+    sp.add_argument("interpretation_id")
+
+    # ── cases (privacy.go.kr 상담사례) ──────────────────────────────
+    p_cases = sub.add_parser("cases", help="개인정보 상담사례 검색")
+    cases_sub = p_cases.add_subparsers(dest="cases_cmd", required=True)
+    sp = cases_sub.add_parser("search")
+    sp.add_argument("query")
+    sp.add_argument("-k", type=int, default=5)
+
+    p_refresh = sub.add_parser("refresh-cases", help="privacy.go.kr 상담사례 재스크래이프")
+    p_refresh.add_argument("--since", help="YYYY-MM-DD 이후만 갱신")
+    p_refresh.add_argument("--respect-robots", action="store_true")
+
+    # ── guides (PIPC 발간 안내서) ───────────────────────────────────
+    p_guides = sub.add_parser("guides", help="개인정보 보호 안내서 청크 검색")
+    guides_sub = p_guides.add_subparsers(dest="guides_cmd", required=True)
+    sp = guides_sub.add_parser("search")
+    sp.add_argument("query")
+    sp.add_argument("-k", type=int, default=5)
+
+    p_extract = sub.add_parser(
+        "extract-guide",
+        help="PDF → markdown 추출 (인터랙티브 청킹의 사전 단계)",
+    )
+    p_extract.add_argument("pdf_path", help="data/guide/*.pdf 한 건")
+
+    p_build_guides = sub.add_parser(
+        "build-guides",
+        help="data/guide/chunks/*.jsonl → guides.sqlite 빌드",
+    )
+    p_build_guides.add_argument("--rebuild", action="store_true", default=True)
+
+    sub.add_parser(
+        "refresh-related-laws",
+        help="privacy.go.kr 개인정보 관련 법령·행정규칙 목록 재스크래이프 (data/related_laws.yaml)",
+    )
+
+    return p
+
+
+# ───────────────────────── command handlers ─────────────────────────
+
+async def _law_search(query: str, display: int) -> int:
+    from kpaa.law_api import KoreanLawClient
+
+    async with KoreanLawClient() as client:
+        hits = await client.law.search(query, display=display)
+        if not hits:
+            print(f'(검색 결과 없음: "{query}")')
+            return 0
+        for hit in hits:
+            print(
+                f"- [{hit.mst}] {hit.name} "
+                f"({hit.type_name or '-'}; 시행 {hit.enforce_date or '-'}; "
+                f"소관 {hit.department or '-'})"
+            )
+    return 0
+
+
+async def _law_text(mst: str, jo: str | None) -> int:
+    from kpaa.law_api import KoreanLawClient
+
+    async with KoreanLawClient() as client:
+        text = await client.law.get_text(mst=mst, jo=jo)
+        print(f"# {text.name} (MST={text.mst}, 시행 {text.enforce_date}, 소관 {text.department})")
+        if not text.articles:
+            print("(조문 없음)")
+            return 0
+        for art in text.articles:
+            print(f"\n## {art.citation(law_name=text.name)}  {art.title}")
+            print(art.raw_text)
+    return 0
+
+
+async def _law_annexes(law_id: str | None, query: str, display: int) -> int:
+    from kpaa.law_api import KoreanLawClient
+
+    async with KoreanLawClient() as client:
+        hits = await client.law.get_annexes(
+            related_law_id=law_id, query=query, display=display
+        )
+        for h in hits:
+            print(
+                f"- [{h.annex_id}] {h.name} ({h.annex_kind}; "
+                f"관련법령 {h.related_law_name}; 공포 {h.promulgate_date})"
+            )
+    return 0
+
+
+async def _pipc_search(query: str, display: int) -> int:
+    from kpaa.law_api import KoreanLawClient
+
+    async with KoreanLawClient() as client:
+        hits = await client.pipc.search_decisions(query, display=display)
+        for h in hits:
+            print(
+                f"- [{h.decision_id}] {h.title}\n"
+                f"  (의안 {h.decision_no or '-'}; 의결 {h.decision_date or '-'}; "
+                f"{h.decision_kind or '-'})"
+            )
+    return 0
+
+
+async def _pipc_text(decision_id: str) -> int:
+    from kpaa.law_api import KoreanLawClient
+
+    async with KoreanLawClient() as client:
+        d = await client.pipc.get_decision_text(decision_id=decision_id)
+        print(f"# {d.citation()}  {d.title}")
+        print(f"  의결: {d.decision_date or '-'} | 결정구분: {d.decision_kind or '-'} | {d.agency or '-'}")
+        if d.main_text:
+            print(f"\n## 주문\n{d.main_text}")
+        if d.reason:
+            print(f"\n## 이유\n{d.reason}")
+    return 0
+
+
+async def _expc_search(query: str, display: int) -> int:
+    from kpaa.law_api import KoreanLawClient
+
+    async with KoreanLawClient() as client:
+        hits = await client.interpretation.search(query, display=display)
+        for h in hits:
+            print(
+                f"- [{h.interpretation_id}] {h.title}\n"
+                f"  (안건 {h.case_no or '-'}; 회신 {h.decided_date or '-'}; "
+                f"질의 {h.inquirer} → {h.responder})"
+            )
+    return 0
+
+
+async def _expc_text(interpretation_id: str) -> int:
+    from kpaa.law_api import KoreanLawClient
+
+    async with KoreanLawClient() as client:
+        e = await client.interpretation.get_text(interpretation_id=interpretation_id)
+        print(f"# {e.citation()}  {e.title}")
+        print(f"  해석: {e.decided_date or '-'} | 질의 {e.inquirer} → 회신 {e.responder}")
+        if e.question:
+            print(f"\n## 질의요지\n{e.question}")
+        if e.answer:
+            print(f"\n## 회답\n{e.answer}")
+        if e.reason:
+            print(f"\n## 이유\n{e.reason}")
+    return 0
+
+
+# ───────────────────────── entry ─────────────────────────
+
+def main(argv: list[str] | None = None) -> int:
+    _utf8_console()
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.cmd == "serve":
+        from kpaa.config import get_settings
+
+        s = get_settings()
+        host = args.host or s.kpaa_host
+        port = args.port or s.kpaa_port
+        try:
+            from kpaa.server import run as run_server
+        except ImportError:
+            print("(server 모듈은 Day 6에 구현됩니다)", file=sys.stderr)
+            return 2
+        run_server(host=host, port=port)
+        return 0
+
+    if args.cmd == "smoke":
+        from kpaa.pipeline import smoke as smoke_fn
+
+        return asyncio.run(smoke_fn(args.query))
+
+    if args.cmd == "retrieve":
+        from kpaa.pipeline import smoke as smoke_fn
+
+        # smoke와 동일하게 컨텍스트 출력 (LLM은 아직 통합 전이라 둘이 같음)
+        return asyncio.run(smoke_fn(args.query))
+
+    if args.cmd == "route":
+        from kpaa.retrieval.router import (
+            load_intents,
+            load_related_laws,
+        )
+        from kpaa.retrieval.router import (
+            route as route_fn,
+        )
+
+        load_intents.cache_clear()
+        load_related_laws.cache_clear()
+        plan = asyncio.run(route_fn(args.query))
+        print(f"질문: {args.query!r}\n")
+        print(f"chain          : {plan.chain or '(미결정)'}")
+        print(f"routed_by      : {plan.routed_by}")
+        print(f"intents        : {[i.name for i in plan.intents] or '(없음)'}")
+        print(f"jo_targets     : {plan.jo_targets or '-'}")
+        print(f"mst_targets    : {plan.mst_targets or '-'}")
+        print(f"name_targets   : {plan.name_targets or '-'}")
+        print(f"active_sources : {plan.active_sources or '-'}")
+        print(f"search_keywords: {plan.search_keywords or '-'}")
+        print(f"top_keyword    : {plan.top_keyword!r}")
+        return 0
+
+    if args.cmd == "eval":
+        from pathlib import Path as _P
+
+        from kpaa.cli_eval import run as run_eval
+
+        return asyncio.run(
+            run_eval(
+                limit=args.limit,
+                show_answers=args.show_answers,
+                out_path=_P(args.out) if args.out else None,
+            )
+        )
+
+    if args.cmd == "law":
+        if args.law_cmd == "search":
+            return asyncio.run(_law_search(args.query, args.display))
+        if args.law_cmd == "text":
+            return asyncio.run(_law_text(args.mst, args.jo))
+        if args.law_cmd == "annexes":
+            return asyncio.run(_law_annexes(args.law_id, args.query, args.display))
+
+    if args.cmd == "pipc":
+        if args.pipc_cmd == "search":
+            return asyncio.run(_pipc_search(args.query, args.display))
+        if args.pipc_cmd == "text":
+            return asyncio.run(_pipc_text(args.decision_id))
+
+    if args.cmd == "expc":
+        if args.expc_cmd == "search":
+            return asyncio.run(_expc_search(args.query, args.display))
+        if args.expc_cmd == "text":
+            return asyncio.run(_expc_text(args.interpretation_id))
+
+    if args.cmd == "cases":
+        from kpaa.cases import CasesIndex
+
+        idx = CasesIndex.default()
+        if idx.total == 0:
+            print(
+                "(상담사례 인덱스가 비어 있습니다 — `kpaa refresh-cases` 로 빌드하세요)",
+                file=sys.stderr,
+            )
+            return 1
+        if args.cases_cmd == "search":
+            hits = idx.search(args.query, k=args.k)
+            if not hits:
+                print(f'(검색 결과 없음: "{args.query}")')
+                return 0
+            for h in hits:
+                cat = " > ".join(filter(None, (h.category1, h.category2, h.category3)))
+                print(f"\n# {h.citation()}  {h.title}")
+                print(f"  분류: {cat or '-'} | 등록: {h.reg_dt or '-'} | {h.type_label or '-'}")
+                if h.body:
+                    print(f"  본문:\n  {h.body[:500]}")
+                if h.source_note:
+                    print(f"  출처: {h.source_note}")
+                print(f"  링크: {h.absolute_url() if h.detail_url else '-'}")
+            return 0
+
+    if args.cmd == "refresh-cases":
+        from kpaa.cases.scraper import refresh
+
+        return asyncio.run(refresh(since=args.since, respect_robots=args.respect_robots))
+
+    if args.cmd == "guides":
+        from kpaa.guides import GuidesIndex
+
+        idx = GuidesIndex.default()
+        if idx.total == 0:
+            print(
+                "(가이드 인덱스가 비어 있습니다 — `kpaa build-guides` 로 빌드하세요)",
+                file=sys.stderr,
+            )
+            return 1
+        if args.guides_cmd == "search":
+            hits = idx.search(args.query, k=args.k)
+            if not hits:
+                print(f'(검색 결과 없음: "{args.query}")')
+                return 0
+            for h in hits:
+                print(f"\n# {h.citation()}")
+                print(f"  문서: {h.doc_title} ({h.doc_date or '-'})")
+                print(f"  섹션: {h.section or '-'} | chunk #{h.chunk_no}")
+                if h.body:
+                    print(f"  본문:\n  {h.body[:500]}")
+                print(f"  원본 PDF: {h.source_pdf or '-'}")
+            return 0
+
+    if args.cmd == "extract-guide":
+        from pathlib import Path as _P
+
+        from kpaa.guides.extractor import (
+            derive_doc_id,
+            derive_doc_title,
+            extract,
+        )
+        from kpaa.guides.index import extracted_dir
+
+        pdf = _P(args.pdf_path)
+        if not pdf.exists():
+            print(f"(PDF 없음: {pdf})", file=sys.stderr)
+            return 1
+        doc_id = derive_doc_id(pdf.name)
+        title = derive_doc_title(pdf.name)
+        print(f"PDF: {pdf.name}", file=sys.stderr)
+        print(f"  doc_id   : {doc_id}", file=sys.stderr)
+        print(f"  doc_title: {title}", file=sys.stderr)
+        print("docling 변환 중 ... (born-digital, OCR off)", file=sys.stderr)
+        try:
+            md = extract(pdf)
+        except RuntimeError as e:
+            print(f"✗ {e}", file=sys.stderr)
+            return 1
+        out_dir = extracted_dir()
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out = out_dir / f"{doc_id}.md"
+        out.write_text(md, encoding="utf-8")
+        print(
+            f"✓ {len(md):,}자 → {out}\n"
+            f"  다음: 새 Claude 세션에서 '다음 PDF 청킹: {doc_id}' 라고 지시.",
+            file=sys.stderr,
+        )
+        return 0
+
+    if args.cmd == "build-guides":
+        from kpaa.guides.builder import build
+
+        build()
+        return 0
+
+    if args.cmd == "refresh-related-laws":
+        from kpaa.related_laws import refresh as refresh_rl
+
+        return asyncio.run(refresh_rl())
+
+    parser.print_help()
+    return 2

src/kpaa/cli_eval.py

@@ -0,0 +1,182 @@
+"""골든 질문 자동 평가 (`kpaa eval`).
+
+`tests/eval_questions.yaml`의 10개 질문을 라이브 파이프라인에 던지고,
+각 질문의 `expected_phrases`(모두 매칭)와 `forbidden_phrases`(하나라도 매칭 시 실패),
+면책 문구 부착 여부를 검사한다.
+
+라이브 LLM 추론이 들어가므로 10건 × ~30~60초 = 5~10분 소요.
+빠른 검증은 `--limit N`로 일부만.
+
+CI에서는 LLM 호출이 너무 무거우므로 이 스크립트는 사용자 로컬 검증용.
+"""
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from kpaa.pipeline import generate
+
+_DISCLAIMER_RE = re.compile(r"※[\s\S]{0,400}법률\s*자문")
+
+
+@dataclass
+class CaseResult:
+    id: int
+    question: str
+    answer: str
+    elapsed_s: float
+    missed_expected: list[str]
+    hit_forbidden: list[str]
+    has_disclaimer: bool
+
+    @property
+    def passed(self) -> bool:
+        return (
+            not self.missed_expected
+            and not self.hit_forbidden
+            and self.has_disclaimer
+        )
+
+
+def _load_eval(path: Path | None = None) -> list[dict[str, Any]]:
+    p = path or (Path(__file__).resolve().parents[2] / "tests" / "eval_questions.yaml")
+    if not p.exists():
+        raise FileNotFoundError(f"eval yaml not found: {p}")
+    raw = yaml.safe_load(p.read_text(encoding="utf-8"))
+    return list(raw or [])
+
+
+def _check(answer: str, item: dict[str, Any]) -> tuple[list[str], list[str], bool]:
+    """답변에서 expected/forbidden 정규식 매칭 + 면책 문구 검사."""
+    missed = []
+    for pat in item.get("expected_phrases", []) or []:
+        if not re.search(pat, answer):
+            missed.append(pat)
+    hit = []
+    for pat in item.get("forbidden_phrases", []) or []:
+        if re.search(pat, answer):
+            hit.append(pat)
+    has_disclaimer = bool(_DISCLAIMER_RE.search(answer))
+    return missed, hit, has_disclaimer
+
+
+async def _generate_answer(query: str) -> tuple[str, float]:
+    """파이프라인 종단 호출 → 최종 답변과 경과 시간."""
+    t0 = time.monotonic()
+    final = ""
+    chunks: list[str] = []
+    async for evt in generate(query):
+        if evt["event"] == "token":
+            chunks.append(evt["delta"])
+        elif evt["event"] == "done":
+            final = evt["answer"]
+    if not final:
+        final = "".join(chunks)
+    return final, time.monotonic() - t0
+
+
+async def run(
+    *,
+    limit: int | None = None,
+    eval_path: Path | None = None,
+    show_answers: bool = False,
+    out_path: Path | None = None,
+) -> int:
+    items = _load_eval(eval_path)
+    if limit is not None:
+        items = items[:limit]
+    print(f"▶ kpaa eval — 골든 질문 {len(items)}건 평가 시작")
+    print(f"  (각 질문 LLM 추론 ~30–60초, 총 {len(items) * 45 / 60:.1f}분 소요 예상)\n")
+
+    results: list[CaseResult] = []
+    for i, item in enumerate(items, 1):
+        q = item["question"]
+        qid = item.get("id", i)
+        print(f"[{i}/{len(items)}] #{qid} {q}")
+        try:
+            answer, secs = await _generate_answer(q)
+        except Exception as e:
+            print(f"  ✗ ERROR: {type(e).__name__}: {e}\n")
+            results.append(
+                CaseResult(
+                    id=qid, question=q, answer="", elapsed_s=0.0,
+                    missed_expected=item.get("expected_phrases", []) or [],
+                    hit_forbidden=[],
+                    has_disclaimer=False,
+                )
+            )
+            continue
+
+        missed, hit, has_dc = _check(answer, item)
+        r = CaseResult(
+            id=qid, question=q, answer=answer, elapsed_s=secs,
+            missed_expected=missed, hit_forbidden=hit, has_disclaimer=has_dc,
+        )
+        results.append(r)
+
+        flag = "✅" if r.passed else "❌"
+        print(f"  {flag} ({secs:.1f}s) "
+              f"missed={len(missed)} forbidden={len(hit)} disclaimer={has_dc}")
+        if missed:
+            print(f"     missed: {missed}")
+        if hit:
+            print(f"     forbidden hit: {hit}")
+        if not has_dc:
+            print("     disclaimer absent")
+        if show_answers or not r.passed:
+            preview = answer.replace("\n", "\n     ")
+            print(f"     ─── 답변 ─────────────\n     {preview}")
+        print()
+
+    # 종합
+    passed = sum(1 for r in results if r.passed)
+    total = len(results)
+    print("─" * 60)
+    print(f"결과: {passed}/{total} 통과 ({100*passed/total if total else 0:.0f}%)")
+    print("─" * 60)
+    if passed < total:
+        print("\n실패한 질문:")
+        for r in results:
+            if not r.passed:
+                print(f"  #{r.id}: {r.question}")
+                if r.missed_expected:
+                    print(f"     missing: {r.missed_expected}")
+                if r.hit_forbidden:
+                    print(f"     forbidden: {r.hit_forbidden}")
+                if not r.has_disclaimer:
+                    print("     disclaimer absent")
+
+    if out_path is not None:
+        import json
+
+        out_path.write_text(
+            json.dumps(
+                [
+                    {
+                        "id": r.id,
+                        "question": r.question,
+                        "answer": r.answer,
+                        "elapsed_s": round(r.elapsed_s, 2),
+                        "passed": r.passed,
+                        "missed_expected": r.missed_expected,
+                        "hit_forbidden": r.hit_forbidden,
+                        "has_disclaimer": r.has_disclaimer,
+                    }
+                    for r in results
+                ],
+                ensure_ascii=False,
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+        print(f"\n결과 저장: {out_path}")
+
+    return 0 if passed == total else 1
+
+
+__all__ = ["run", "CaseResult"]

src/kpaa/config.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from platformdirs import user_cache_dir, user_config_dir
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    law_oc: str = ""
+
+    kpaa_model_repo: str = "bartowski/google_gemma-4-E2B-it-GGUF"
+    kpaa_model_file: str = "google_gemma-4-E2B-it-Q4_K_M.gguf"
+    kpaa_model_dir: Path | None = None
+
+    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
+
+    # ZeroGPU 백엔드용 — 같은 가중치의 transformers repo (게이트 X, Apache 2.0).
+    kpaa_hf_model_repo: str = "google/gemma-4-E2B-it"
+    kpaa_hf_model_dtype: str = "bfloat16"
+    # @spaces.GPU 함수당 GPU 점유 한도(초). 기본 60s 는 긴 답변에 부족할 수 있어
+    # 120s 사용. ZeroGPU Pro 는 300s 까지 허용.
+    kpaa_hf_gpu_duration: int = 120
+
+    @property
+    def cache_root(self) -> Path:
+        p = Path(user_cache_dir("kpaa"))
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def config_root(self) -> Path:
+        p = Path(user_config_dir("kpaa"))
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def model_dir(self) -> Path:
+        p = self.kpaa_model_dir or (self.cache_root / "models")
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def law_cache_dir(self) -> Path:
+        p = self.cache_root / "law"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()

src/kpaa/guides/__init__.py

@@ -0,0 +1,57 @@
+"""PIPC 발간 안내서 — 로컬 SQLite FTS5 인덱스.
+
+    from kpaa.guides import GuidesIndex
+    idx = GuidesIndex.default()
+    hits = idx.search("CCTV 안내문구", k=3)
+    for h in hits:
+        print(h.citation(), h.section)
+
+리포 동봉 스냅샷은 `data/guides.sqlite`. 갱신은 `kpaa build-guides`.
+
+청크 원본(`data/guide/chunks/*.jsonl`)은 사용자 + Claude 의 인터랙티브
+큐레이션 결과 — 자동 휴리스틱으로 만들어지지 않으므로 PDF 변경 시 jsonl 도
+함께 갱신해야 한다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from kpaa.guides.index import (
+    count as _count,
+)
+from kpaa.guides.index import (
+    default_db_path,
+    default_meta_path,
+)
+from kpaa.guides.index import (
+    doc_count as _doc_count,
+)
+from kpaa.guides.index import (
+    search as _search,
+)
+from kpaa.guides.models import GuideChunk
+
+
+class GuidesIndex:
+    """사용자 친화적 진입점."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self.db_path = db_path or default_db_path()
+
+    @classmethod
+    def default(cls) -> GuidesIndex:
+        return cls()
+
+    @property
+    def total(self) -> int:
+        return _count(self.db_path)
+
+    @property
+    def doc_total(self) -> int:
+        return _doc_count(self.db_path)
+
+    def search(self, query: str, *, k: int = 5) -> list[GuideChunk]:
+        return _search(query, k=k, db_path=self.db_path)
+
+
+__all__ = ["GuidesIndex", "GuideChunk", "default_db_path", "default_meta_path"]

src/kpaa/guides/builder.py

@@ -0,0 +1,140 @@
+"""`data/guide/chunks/*.jsonl` → `data/guides.sqlite` 빌드.
+
+청크 자체는 사용자 + Claude 의 인터랙티브 큐레이션 결과(jsonl). 본 모듈은 그
+파일들을 읽어 sqlite/FTS5 인덱스에 적재하고 manifest 를 갱신할 뿐, PDF 청킹
+로직은 수행하지 않는다.
+
+manifest(`data/guides_meta.json`):
+    {
+        "doc_id": {
+            "doc_title": ..., "doc_date": ...,
+            "source_pdf": ..., "chunks_count": N
+        }, ...
+        "_built_at": "YYYY-MM-DD HH:MM:SS",
+        "_total_chunks": N
+    }
+
+실행: `kpaa build-guides` (cli.py 의 핸들러가 이 모듈을 호출).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from kpaa.guides.index import (
+    build_index,
+    chunks_dir,
+    default_db_path,
+    default_meta_path,
+)
+from kpaa.guides.models import GuideChunk
+
+logger = logging.getLogger("kpaa.guides.builder")
+
+_STALE_MONTHS = 18
+
+
+def _load_jsonl(path: Path) -> list[GuideChunk]:
+    out: list[GuideChunk] = []
+    with path.open("r", encoding="utf-8") as f:
+        for ln, line in enumerate(f, 1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError as e:
+                raise RuntimeError(f"{path.name}:{ln} JSON parse error: {e}") from e
+            try:
+                out.append(GuideChunk.model_validate(row))
+            except Exception as e:
+                raise RuntimeError(f"{path.name}:{ln} schema error: {e}") from e
+    return out
+
+
+def _months_since(doc_date: str) -> int | None:
+    """'2024.10' → 현재 시점 기준 경과 개월. parse 실패면 None."""
+    if not doc_date:
+        return None
+    parts = doc_date.split(".")
+    try:
+        year = int(parts[0])
+        month = int(parts[1]) if len(parts) > 1 else 6
+    except (ValueError, IndexError):
+        return None
+    now = datetime.now()
+    return (now.year - year) * 12 + (now.month - month)
+
+
+def build(*, db_path: Path | None = None, meta_path: Path | None = None) -> int:
+    """`data/guide/chunks/*.jsonl` 전부 읽어 sqlite 빌드. 청크 총 개수 반환."""
+    cdir = chunks_dir()
+    cdir.mkdir(parents=True, exist_ok=True)
+    files = sorted(cdir.glob("*.jsonl"))
+
+    db = db_path or default_db_path()
+    meta = meta_path or default_meta_path()
+
+    all_chunks: list[GuideChunk] = []
+    manifest: dict = {}
+
+    if not files:
+        logger.warning(
+            "%s 에 청크 jsonl 이 없습니다. `kpaa extract-guide` 후 인터랙티브 "
+            "청킹으로 jsonl 을 먼저 작성하세요.",
+            cdir,
+        )
+        # 빈 인덱스로라도 빌드 — 회귀 안전망 (검색은 0건 반환)
+        build_index([], db_path=db)
+        manifest["_built_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        manifest["_total_chunks"] = 0
+        meta.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+        return 0
+
+    for f in files:
+        chunks = _load_jsonl(f)
+        if not chunks:
+            logger.warning("%s 비어 있음 — skip", f.name)
+            continue
+        first = chunks[0]
+        # doc_id 일관성 검증
+        for c in chunks:
+            if c.doc_id != first.doc_id:
+                raise RuntimeError(
+                    f"{f.name} 안에서 doc_id 가 섞여 있습니다: "
+                    f"{first.doc_id!r} vs {c.doc_id!r}"
+                )
+        all_chunks.extend(chunks)
+        manifest[first.doc_id] = {
+            "doc_title": first.doc_title,
+            "doc_date": first.doc_date,
+            "source_pdf": first.source_pdf,
+            "chunks_count": len(chunks),
+        }
+        # 18개월 경과 경고
+        age = _months_since(first.doc_date)
+        if age is not None and age > _STALE_MONTHS:
+            print(
+                f"⚠ {first.doc_title} ({first.doc_date}) — 발간 {age}개월 경과. "
+                f"PIPC 최신본 확인 권장.",
+                file=sys.stderr,
+            )
+
+    build_index(all_chunks, db_path=db)
+
+    manifest["_built_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    manifest["_total_chunks"] = len(all_chunks)
+    meta.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    print(
+        f"✓ guides.sqlite 빌드 완료: {len(all_chunks)} 청크, "
+        f"{len(files)} 문서 → {db}",
+        file=sys.stderr,
+    )
+    return len(all_chunks)
+
+
+__all__ = ["build"]

src/kpaa/guides/extractor.py

@@ -0,0 +1,157 @@
+"""docling 으로 PDF → 원시 markdown 추출만 담당 (청킹은 인터랙티브 단계).
+
+청크 경계 결정은 사용자 + Claude 의 대화로 진행되므로, 이 모듈은 'PDF 한 권을
+가능한 한 충실한 markdown 으로 변환' 까지만 책임진다. 결과는 작업용 파일로
+`data/guide/extracted/{doc_id}.md` 에 떨어지고, Claude 가 다음 세션에서 이
+파일을 읽어 청크 후보를 사용자에게 제안한다.
+
+페이지 마커 — docling 의 `page_break_placeholder` 옵션을 사용해
+`<!-- PAGE: N -->` 마커를 페이지 경계마다 삽입. 청킹 시 각 청크의 시작/끝
+페이지를 추적해 `pages` 메타로 기록하기 위함.
+
+옵트인 의존성: `pip install -e ".[pipc-ocr]"` (docling). PIPC 별지 OCR 과 같은
+extra 를 재사용하지만 본 모듈은 OCR 을 *끄고* 동작 — privacy.go.kr 안내서는
+born-digital 이라 텍스트 직접 추출이 가능하다.
+
+추출 결과가 500자 미만이면 RuntimeError → 운영자가 PDF 가 스캔본인지 직접
+확인하도록 강제 (은밀한 OCR 폴백으로 인덱스를 오염시키지 않는다).
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("kpaa.guides.extractor")
+
+_MIN_CHARS = 500
+
+# 페이지 경계 마커. 청킹 시 청크의 시작/끝 페이지 추적에 사용.
+# 형식: '<!-- PAGE: N -->' (N = 1-based page number).
+PAGE_MARKER_PREFIX = "<!-- PAGE: "
+PAGE_MARKER_SUFFIX = " -->"
+
+_converter = None  # lazy singleton
+
+
+def _get_converter():
+    """docling DocumentConverter (lazy + singleton, OCR off).
+
+    PIPC 별지용 컨버터(retrieval/pipc_annex.py)는 EasyOCR 를 켜는 반면,
+    안내서 PDF 는 born-digital 이라 do_ocr=False 로 충분하고 빠르다.
+    """
+    global _converter
+    if _converter is not None:
+        return _converter
+    try:
+        from docling.datamodel.base_models import InputFormat
+        from docling.datamodel.pipeline_options import PdfPipelineOptions
+        from docling.document_converter import DocumentConverter, PdfFormatOption
+    except ImportError as e:
+        raise RuntimeError(
+            "docling 이 설치돼 있지 않습니다. `pip install -e \".[pipc-ocr]\"` "
+            "로 설치 후 다시 실행하세요."
+        ) from e
+
+    pdf_opts = PdfPipelineOptions()
+    pdf_opts.do_ocr = False
+    pdf_opts.do_table_structure = True
+
+    _converter = DocumentConverter(
+        format_options={
+            InputFormat.PDF: PdfFormatOption(pipeline_options=pdf_opts),
+        }
+    )
+    return _converter
+
+
+def extract(pdf_path: Path) -> str:
+    """PDF → markdown 문자열. 페이지 경계마다 `<!-- PAGE: N -->` 마커 삽입.
+
+    Raises:
+        RuntimeError: docling 미설치 / 추출 실패 / 500자 미만.
+    """
+    if not pdf_path.exists():
+        raise FileNotFoundError(pdf_path)
+    conv = _get_converter()
+    try:
+        result = conv.convert(str(pdf_path))
+    except Exception as e:
+        raise RuntimeError(f"docling 변환 실패 ({pdf_path.name}): {e}") from e
+
+    doc = result.document
+    # 페이지별로 export 해서 페이지 번호 마커를 사이에 삽입.
+    # docling 자체 page_break_placeholder 는 동일 문자열만 끼워줘서 페이지 번호가
+    # 명시되지 않으므로, 페이지별 export 결과를 직접 합친다.
+    parts: list[str] = []
+    for pno in sorted(doc.pages.keys()):
+        page_md = doc.export_to_markdown(page_no=pno).strip()
+        if not page_md:
+            continue
+        parts.append(f"{PAGE_MARKER_PREFIX}{pno}{PAGE_MARKER_SUFFIX}")
+        parts.append(page_md)
+    md = "\n\n".join(parts).strip()
+
+    if len(md) < _MIN_CHARS:
+        raise RuntimeError(
+            f"PDF 추출 결과가 {len(md)}자 (< {_MIN_CHARS}). "
+            f"스캔본일 가능성 — `{pdf_path.name}` 확인 후 별도 OCR 처리 필요."
+        )
+    return md
+
+
+def derive_doc_id(pdf_filename: str) -> str:
+    """파일명 → 짧은 슬러그.
+
+    예: '★개인정보의 안전성 확보조치 기준 안내서(2024.10).pdf' →
+        '안전성_확보조치_안내서'
+    예: '1. 개인정보 질의응답 모음집(2025.12.).pdf' → '질의응답_모음집'
+    """
+    name = pdf_filename
+    if name.lower().endswith(".pdf"):
+        name = name[:-4]
+    # 1) 선행 번호 prefix 제거 ("1. ", "2026 ")
+    import re
+    name = re.sub(r"^[★☆\d\s.\-_]+", "", name).strip()
+    # 2) 끝의 (YYYY.MM) / (YYYY.MM.) / (YYYY) 제거
+    name = re.sub(r"\([\d.\s]+\)\s*$", "", name).strip()
+    # 3) "개인정보의 ", "개인정보 ", "고정형 " 같은 흔한 접두 제거
+    for prefix in ("개인정보의 ", "개인정보 ", "고정형 "):
+        if name.startswith(prefix):
+            name = name[len(prefix):]
+            break
+    # 4) 공백 → underscore
+    name = re.sub(r"\s+", "_", name).strip("_")
+    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
+    if name.lower().endswith(".pdf"):
+        name = name[:-4]
+    import re
+    name = re.sub(r"^[★☆]+\s*", "", name)
+    name = re.sub(r"^\d+\.\s*", "", name)
+    # 끝의 괄호 날짜 제거
+    name = re.sub(r"\s*\([\d.\s]+\)\s*$", "", name).strip()
+    return name
+
+
+__all__ = ["extract", "derive_doc_id", "derive_doc_date", "derive_doc_title"]

src/kpaa/guides/index.py

@@ -0,0 +1,241 @@
+"""SQLite FTS5 인덱스 — PIPC 발간 안내서 청크용.
+
+cases/index.py와 동일한 패턴(unicode61 tokenizer, BM25, 임베딩 없음).
+
+DB 스키마:
+    guides(chunk_id PK, doc_id, doc_title, doc_date, section,
+           chunk_no, body, source_pdf)
+    guides_fts (FTS5 가상테이블, 검색용 — title 컬럼은 doc_title+section 합성)
+"""
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterable
+from pathlib import Path
+
+from kpaa.guides.models import GuideChunk
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS guides (
+    chunk_id       TEXT PRIMARY KEY,
+    doc_id         TEXT,
+    doc_title      TEXT,
+    doc_date       TEXT,
+    section        TEXT,
+    chunk_no       INTEGER,
+    body           TEXT,
+    pages          TEXT,
+    source_pdf     TEXT,
+    chunk_context  TEXT
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS guides_fts USING fts5(
+    chunk_id UNINDEXED,
+    title,
+    body,
+    section UNINDEXED,
+    tokenize = "unicode61 remove_diacritics 2"
+);
+"""
+
+
+def default_db_path() -> Path:
+    return _data_dir() / "guides.sqlite"
+
+
+def default_meta_path() -> Path:
+    return _data_dir() / "guides_meta.json"
+
+
+def chunks_dir() -> Path:
+    return _data_dir() / "guide" / "chunks"
+
+
+def extracted_dir() -> Path:
+    return _data_dir() / "guide" / "extracted"
+
+
+def _data_dir() -> Path:
+    repo_data = Path(__file__).resolve().parents[3] / "data"
+    if repo_data.exists():
+        return repo_data
+    from kpaa.config import get_settings
+
+    p = get_settings().cache_root / "guides"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _connect(db_path: Path) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    conn.executescript(SCHEMA_SQL)
+    return conn
+
+
+def _fts_title(c: GuideChunk) -> str:
+    """FTS title 컬럼: 문서명 + 섹션명 합성으로 매칭률 ↑."""
+    if c.section:
+        return f"{c.doc_title} {c.section}"
+    return c.doc_title
+
+
+def _fts_body(c: GuideChunk) -> str:
+    """FTS body 컬럼: chunk_context가 있으면 body 앞에 prepend (Anthropic Contextual Retrieval)."""
+    if c.chunk_context:
+        return f"{c.chunk_context}\n\n{c.body}"
+    return c.body
+
+
+def build_index(chunks: Iterable[GuideChunk], *, db_path: Path) -> None:
+    """전체 다시 빌드 — wipe 후 재삽입."""
+    conn = _connect(db_path)
+    try:
+        with conn:
+            conn.execute("DELETE FROM guides")
+            conn.execute("DELETE FROM guides_fts")
+            for c in chunks:
+                conn.execute(
+                    """INSERT INTO guides
+                       (chunk_id, doc_id, doc_title, doc_date,
+                        section, chunk_no, body, pages, source_pdf, chunk_context)
+                       VALUES (?,?,?,?,?,?,?,?,?,?)""",
+                    (
+                        c.chunk_id, c.doc_id, c.doc_title, c.doc_date,
+                        c.section, c.chunk_no, c.body, c.pages, c.source_pdf,
+                        c.chunk_context,
+                    ),
+                )
+                conn.execute(
+                    "INSERT INTO guides_fts (chunk_id, title, body, section) VALUES (?,?,?,?)",
+                    (c.chunk_id, _fts_title(c), _fts_body(c), c.section),
+                )
+        conn.execute("VACUUM")
+    finally:
+        conn.close()
+
+
+def search(
+    query: str, *, k: int = 5, db_path: Path | None = None
+) -> list[GuideChunk]:
+    """FTS5 검색 (cases.search 패턴 그대로: prefix matching + 다중 토큰 OR)."""
+    path = db_path or default_db_path()
+    if not path.exists():
+        return []
+    if not query.strip():
+        return []
+    conn = _connect(path)
+    try:
+        safe = "".join(ch if ch.isalnum() or ord(ch) > 127 else " " for ch in query)
+        tokens = [t for t in safe.split() if t]
+        if not tokens:
+            return []
+        if len(tokens) == 1:
+            fts_query = f"{tokens[0]}*"
+        else:
+            fts_query = " OR ".join(f"{t}*" for t in tokens)
+        cur = conn.execute(
+            """SELECT g.* FROM guides_fts f
+               JOIN guides g ON g.chunk_id = f.chunk_id
+               WHERE guides_fts MATCH ?
+               ORDER BY bm25(guides_fts) ASC
+               LIMIT ?""",
+            (fts_query, k),
+        )
+        rows = cur.fetchall()
+    finally:
+        conn.close()
+    return [
+        GuideChunk(
+            chunk_id=r["chunk_id"], doc_id=r["doc_id"],
+            doc_title=r["doc_title"], doc_date=r["doc_date"],
+            section=r["section"], chunk_no=r["chunk_no"],
+            body=r["body"], pages=r["pages"] or "",
+            source_pdf=r["source_pdf"],
+            chunk_context=(r["chunk_context"] if "chunk_context" in r.keys() else "") or "",
+        )
+        for r in rows
+    ]
+
+
+def count(db_path: Path | None = None) -> int:
+    path = db_path or default_db_path()
+    if not path.exists():
+        return 0
+    conn = _connect(path)
+    try:
+        cur = conn.execute("SELECT COUNT(*) FROM guides")
+        return cur.fetchone()[0]
+    finally:
+        conn.close()
+
+
+def list_all_chunks(*, db_path: Path | None = None) -> list[GuideChunk]:
+    path = db_path or default_db_path()
+    if not path.exists():
+        return []
+    conn = _connect(path)
+    try:
+        cur = conn.execute("SELECT * FROM guides ORDER BY doc_id, chunk_no")
+        rows = cur.fetchall()
+    finally:
+        conn.close()
+    return [
+        GuideChunk(
+            chunk_id=r["chunk_id"], doc_id=r["doc_id"],
+            doc_title=r["doc_title"], doc_date=r["doc_date"],
+            section=r["section"], chunk_no=r["chunk_no"],
+            body=r["body"], pages=r["pages"] or "",
+            source_pdf=r["source_pdf"],
+            chunk_context=(r["chunk_context"] if "chunk_context" in r.keys() else "") or "",
+        )
+        for r in rows
+    ]
+
+
+def rebuild_fts(*, db_path: Path | None = None) -> int:
+    """guides 테이블 데이터로 guides_fts만 재생성."""
+    path = db_path or default_db_path()
+    chunks = list_all_chunks(db_path=path)
+    if not chunks:
+        return 0
+    conn = _connect(path)
+    try:
+        with conn:
+            conn.execute("DROP TABLE IF EXISTS guides_fts")
+    finally:
+        conn.close()
+    conn = _connect(path)
+    try:
+        with conn:
+            for c in chunks:
+                conn.execute(
+                    "INSERT INTO guides_fts (chunk_id, title, body, section) VALUES (?,?,?,?)",
+                    (c.chunk_id, _fts_title(c), _fts_body(c), c.section),
+                )
+        conn.execute("VACUUM")
+    finally:
+        conn.close()
+    return len(chunks)
+
+
+def doc_count(db_path: Path | None = None) -> int:
+    """고유 doc_id 개수 — meta 표시용."""
+    path = db_path or default_db_path()
+    if not path.exists():
+        return 0
+    conn = _connect(path)
+    try:
+        cur = conn.execute("SELECT COUNT(DISTINCT doc_id) FROM guides")
+        return cur.fetchone()[0]
+    finally:
+        conn.close()
+
+
+__all__ = [
+    "build_index", "search", "count", "doc_count",
+    "list_all_chunks", "rebuild_fts",
+    "default_db_path", "default_meta_path",
+    "chunks_dir", "extracted_dir",
+]

src/kpaa/guides/models.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class GuideChunk(BaseModel):
+    """PIPC 발간 안내서 1청크.
+
+    `data/guide/chunks/{doc_id}.jsonl`의 한 줄과 1:1 매핑.
+    인터랙티브 큐레이션(사용자 + Claude)으로 생성된 canonical chunk source.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    chunk_id: str        # "{doc_id}_{chunk_no:04d}"
+    doc_id: str          # "안전성_확보조치_안내서"
+    doc_title: str       # "개인정보의 안전성 확보조치 기준 안내서"
+    doc_date: str        # "2024.10" (YYYY.MM)
+    section: str         # "II.3 접근권한 관리"
+    chunk_no: int        # 0부터 순번
+    body: str            # 청크 본문 (≤1500자)
+    pages: str = ""      # 원본 PDF 페이지 범위 (예: "p.8" 또는 "p.8-9")
+    source_pdf: str      # 원본 PDF 파일명
+    chunk_context: str = ""  # Anthropic Contextual Retrieval prefix — 인덱싱 시 body 앞에 prepend (답변 출력은 body만)
+
+    def citation(self) -> str:
+        """답변에 박을 인용 태그.
+
+        예: '안전성 확보조치 안내서 §II.3 접근권한 관리, 2024.10, p.8-9'
+        """
+        short = self.doc_title
+        # 흔한 접두 표현 제거해 짧게
+        for prefix in ("개인정보의 ", "개인정보 ", "고정형 "):
+            if short.startswith(prefix):
+                short = short[len(prefix):]
+                break
+        bits = [short]
+        if self.section:
+            bits.append(f"§{self.section}")
+        out = " ".join(bits)
+        tail: list[str] = []
+        if self.doc_date:
+            tail.append(self.doc_date)
+        if self.pages:
+            tail.append(self.pages)
+        if tail:
+            out = f"{out}, {', '.join(tail)}"
+        return out

src/kpaa/law_api/__init__.py

@@ -0,0 +1,362 @@
+"""한국 법제처 OPEN API의 Python SDK.
+
+`korean-law-mcp`(MCP 서버)의 도구 표면을 참조하되, MCP 프로토콜 의존 없이
+일반 Python 라이브러리로 사용한다.
+
+    async with KoreanLawClient(oc="my_id") as client:
+        hits = await client.law.search("개인정보보호법")
+        text = await client.law.get_text(mst=hits[0].mst, jo="15")
+        decisions = await client.pipc.search_decisions("동의 철회")
+        # 미구현 카테고리도 generic raw 호출 가능
+        rows = await client.raw.search("ftc", query="과징금")
+
+라이브 검증 / 라이선스 / 미확정 target 정보는 `endpoints.py`를 참조.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from kpaa.law_api.client import LawApiCall, LawGoKrClient
+
+# ───────────────────────── 네임스페이스 ─────────────────────────
+
+class _LawNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.law import search_law
+
+        return await search_law(self._c, query=query, display=display)
+
+    async def get_text(self, *, mst: str, jo: str | int | None = None):
+        from kpaa.law_api.law import get_law_text
+
+        return await get_law_text(self._c, mst=mst, jo=jo)
+
+    async def get_article(self, *, mst: str, article_no: str | int):
+        from kpaa.law_api.law import get_article_detail
+
+        return await get_article_detail(self._c, mst=mst, article_no=article_no)
+
+    async def get_annexes(
+        self, *, related_law_id: str | None = None, query: str = "", display: int = 20
+    ):
+        from kpaa.law_api.law import get_annexes
+
+        return await get_annexes(
+            self._c, related_law_id=related_law_id, query=query, display=display
+        )
+
+
+class _PIPCNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search_decisions(self, query: str, *, display: int = 20):
+        from kpaa.law_api.pipc import search_decisions
+
+        return await search_decisions(self._c, query=query, display=display)
+
+    async def get_decision_text(self, *, decision_id: str):
+        from kpaa.law_api.pipc import get_decision_text
+
+        return await get_decision_text(self._c, decision_id=decision_id)
+
+
+class _InterpretationNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.interpretation import search_interpretations
+
+        return await search_interpretations(self._c, query=query, display=display)
+
+    async def get_text(self, *, interpretation_id: str):
+        from kpaa.law_api.interpretation import get_interpretation_text
+
+        return await get_interpretation_text(self._c, interpretation_id=interpretation_id)
+
+
+class _AdminRuleNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, knd: int | None = None, display: int = 20):
+        from kpaa.law_api.admin_rule import search_admin_rules
+
+        return await search_admin_rules(self._c, query=query, knd=knd, display=display)
+
+    async def get_text(self, *, rule_id: str):
+        from kpaa.law_api.admin_rule import get_admin_rule_text
+
+        return await get_admin_rule_text(self._c, rule_id=rule_id)
+
+
+class _PrecedentNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.precedent import search_precedents
+
+        return await search_precedents(self._c, query=query, display=display)
+
+    async def get_text(self, *, precedent_id: str):
+        from kpaa.law_api.precedent import get_precedent_text
+
+        return await get_precedent_text(self._c, precedent_id=precedent_id)
+
+
+class _OrdinanceNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.ordinance import search_ordinances
+
+        return await search_ordinances(self._c, query=query, display=display)
+
+    async def get_text(self, *, ordinance_id: str):
+        from kpaa.law_api.ordinance import get_ordinance_text
+
+        return await get_ordinance_text(self._c, ordinance_id=ordinance_id)
+
+
+class _TreatyNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.treaty import search_treaties
+
+        return await search_treaties(self._c, query=query, display=display)
+
+    async def get_text(self, *, treaty_id: str):
+        from kpaa.law_api.treaty import get_treaty_text
+
+        return await get_treaty_text(self._c, treaty_id=treaty_id)
+
+
+class _FTCNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.ftc import search_ftc_decisions
+
+        return await search_ftc_decisions(self._c, query=query, display=display)
+
+    async def get_text(self, *, decision_id: str):
+        from kpaa.law_api.ftc import get_ftc_decision_text
+
+        return await get_ftc_decision_text(self._c, decision_id=decision_id)
+
+
+class _NLRCNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.nlrc import search_nlrc_decisions
+
+        return await search_nlrc_decisions(self._c, query=query, display=display)
+
+    async def get_text(self, *, decision_id: str):
+        from kpaa.law_api.nlrc import get_nlrc_decision_text
+
+        return await get_nlrc_decision_text(self._c, decision_id=decision_id)
+
+
+class _ACRNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.acr import search_acr_decisions
+
+        return await search_acr_decisions(self._c, query=query, display=display)
+
+    async def get_text(self, *, decision_id: str):
+        from kpaa.law_api.acr import get_acr_decision_text
+
+        return await get_acr_decision_text(self._c, decision_id=decision_id)
+
+
+class _TermsNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.terms import search_legal_terms
+
+        return await search_legal_terms(self._c, query=query, display=display)
+
+    async def get_detail(self, *, term_id: str):
+        from kpaa.law_api.terms import get_legal_term_detail
+
+        return await get_legal_term_detail(self._c, term_id=term_id)
+
+
+class _EnglishNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.english import search_english_laws
+
+        return await search_english_laws(self._c, query=query, display=display)
+
+    async def get_text(self, *, mst: str):
+        from kpaa.law_api.english import get_english_law_text
+
+        return await get_english_law_text(self._c, mst=mst)
+
+
+class _ArticleHistoryNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(
+        self,
+        *,
+        law_id: str,
+        jo: str | int | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        on_date: str | None = None,
+        org: str | None = None,
+        page: int = 1,
+    ):
+        from kpaa.law_api.article_history import search_article_history
+
+        return await search_article_history(
+            self._c,
+            law_id=law_id,
+            jo=jo,
+            from_date=from_date,
+            to_date=to_date,
+            on_date=on_date,
+            org=org,
+            page=page,
+        )
+
+
+class _ConstitutionalNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(
+        self,
+        query: str,
+        *,
+        display: int = 20,
+        case_number: str | None = None,
+        sort: str | None = None,
+    ):
+        from kpaa.law_api.constitutional import search_constitutional_decisions
+
+        return await search_constitutional_decisions(
+            self._c,
+            query=query,
+            display=display,
+            case_number=case_number,
+            sort=sort,
+        )
+
+    async def get_text(self, *, decision_id: str):
+        from kpaa.law_api.constitutional import get_constitutional_decision_text
+
+        return await get_constitutional_decision_text(
+            self._c, decision_id=decision_id
+        )
+
+
+class _OldNewNamespace:
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(self, query: str, *, display: int = 20):
+        from kpaa.law_api.oldnew import search_old_new
+
+        return await search_old_new(self._c, query=query, display=display)
+
+    async def compare(self, *, mst: str):
+        from kpaa.law_api.oldnew import compare_old_new
+
+        return await compare_old_new(self._c, mst=mst)
+
+
+class _RawNamespace:
+    """Generic 호출 — 풀구현된 카테고리 외 임의 target에 사용."""
+
+    def __init__(self, c: LawGoKrClient) -> None:
+        self._c = c
+
+    async def search(
+        self,
+        target: str,
+        *,
+        query: str = "",
+        display: int = 20,
+        extra_params: dict[str, Any] | None = None,
+    ):
+        from kpaa.law_api.raw import raw_search
+
+        return await raw_search(
+            self._c, target, query=query, display=display, extra_params=extra_params
+        )
+
+    async def get(
+        self,
+        target: str,
+        *,
+        id: str | None = None,
+        mst: str | None = None,
+        extra_params: dict[str, Any] | None = None,
+    ) -> str:
+        from kpaa.law_api.raw import raw_get
+
+        return await raw_get(
+            self._c, target, id=id, mst=mst, extra_params=extra_params
+        )
+
+
+# ───────────────────────── 진입점 ─────────────────────────
+
+class KoreanLawClient:
+    """High-level 법제처 SDK.
+
+    카테고리별 네임스페이스로 노출 (라이브 검증된 15개 target 토큰 기반).
+    미구현 카테고리는 `client.raw.search/get`으로 임의 target 호출 가능.
+    """
+
+    def __init__(self, oc: str | None = None) -> None:
+        self._client = LawGoKrClient(oc=oc)
+        self.law = _LawNamespace(self._client)
+        self.pipc = _PIPCNamespace(self._client)
+        self.interpretation = _InterpretationNamespace(self._client)
+        self.admin_rule = _AdminRuleNamespace(self._client)
+        self.precedent = _PrecedentNamespace(self._client)
+        self.ordinance = _OrdinanceNamespace(self._client)
+        self.treaty = _TreatyNamespace(self._client)
+        self.ftc = _FTCNamespace(self._client)
+        self.nlrc = _NLRCNamespace(self._client)
+        self.acr = _ACRNamespace(self._client)
+        self.terms = _TermsNamespace(self._client)
+        self.english = _EnglishNamespace(self._client)
+        self.old_new = _OldNewNamespace(self._client)
+        self.constitutional = _ConstitutionalNamespace(self._client)
+        self.article_history = _ArticleHistoryNamespace(self._client)
+        self.raw = _RawNamespace(self._client)
+
+    async def __aenter__(self) -> KoreanLawClient:
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self._client.__aexit__(*exc)
+
+
+__all__ = ["KoreanLawClient", "LawGoKrClient", "LawApiCall"]

src/kpaa/law_api/acr.py

@@ -0,0 +1,45 @@
+"""국민권익위원회 결정 (target=acr).
+
+라이브 검증 row 필드: 결정문일련번호 / 제목 / 민원표시명 / 의안번호 /
+회의종류 / 결정구분 / 의결일.
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import ACR
+from kpaa.law_api.parsers import child_text, parse_xml
+
+
+async def search_acr_decisions(
+    client: LawGoKrClient, *, query: str, display: int = 20
+) -> list[dict[str, str]]:
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    body = await client.fetch(
+        LawApiCall(target=ACR.target, path=LIST_PATH,
+                   params={"query": query, "display": str(display)},
+                   cache_ttl=3600)
+    )
+    root = parse_xml(body)
+    return [
+        {
+            "decision_id": child_text(el, "결정문일련번호"),
+            "title": child_text(el, "제목"),
+            "subject": child_text(el, "민원표시명"),
+            "decision_no": child_text(el, "의안번호"),
+            "meeting_kind": child_text(el, "회의종류"),
+            "decision_kind": child_text(el, "결정구분"),
+            "decision_date": child_text(el, "의결일"),
+        }
+        for el in root.findall(f".//{ACR.row_tag}")
+    ]
+
+
+async def get_acr_decision_text(client: LawGoKrClient, *, decision_id: str) -> str:
+    return await client.fetch(
+        LawApiCall(target=ACR.target, path=DETAIL_PATH,
+                   params={"ID": str(decision_id)}, cache_ttl=24 * 3600)
+    )
+
+
+__all__ = ["search_acr_decisions", "get_acr_decision_text"]

src/kpaa/law_api/admin_rule.py

@@ -0,0 +1,72 @@
+"""행정규칙 (훈령/예규/고시) — target=admrul.
+
+knd 파라미터: 1=훈령, 2=예규, 3=고시 (필터, 미지정시 전체).
+챗봇은 개인정보보호위원회 고시(knd=3)에 관심.
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import ADMRUL
+from kpaa.law_api.parsers import child_text, parse_xml
+
+CACHE_TTL_SEARCH = 3600
+CACHE_TTL_DETAIL = 24 * 3600
+
+
+async def search_admin_rules(
+    client: LawGoKrClient,
+    *,
+    query: str,
+    knd: int | None = None,
+    display: int = 20,
+) -> list[dict[str, str]]:
+    """행정규칙 목록 검색.
+
+    Args:
+        knd: 1=훈령, 2=예규, 3=고시. None이면 전체.
+    """
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    params: dict[str, str] = {"query": query, "display": str(display)}
+    if knd is not None:
+        if knd not in (1, 2, 3):
+            raise ValueError("knd must be 1(훈령), 2(예규), or 3(고시)")
+        params["knd"] = str(knd)
+    call = LawApiCall(
+        target=ADMRUL.target, path=LIST_PATH, params=params, cache_ttl=CACHE_TTL_SEARCH
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+    out: list[dict[str, str]] = []
+    for el in root.findall(f".//{ADMRUL.row_tag}"):
+        out.append(
+            {
+                "rule_id": child_text(el, ADMRUL.id_field),
+                "name": child_text(el, "행정규칙명"),
+                "kind": child_text(el, "행정규칙종류"),
+                "issue_date": child_text(el, "발령일자"),
+                "issue_no": child_text(el, "발령번호"),
+                "department": child_text(el, "소관부처명"),
+                "status": child_text(el, "현행연혁구분"),
+                "amend_type": child_text(el, "제개정구분명"),
+                "enforce_date": child_text(el, "시행일자"),
+            }
+        )
+    return out
+
+
+async def get_admin_rule_text(
+    client: LawGoKrClient,
+    *,
+    rule_id: str,
+) -> str:
+    """행정규칙 본문 — raw XML 반환."""
+    call = LawApiCall(
+        target=ADMRUL.target, path=DETAIL_PATH,
+        params={"ID": str(rule_id)},
+        cache_ttl=CACHE_TTL_DETAIL,
+    )
+    return await client.fetch(call)
+
+
+__all__ = ["search_admin_rules", "get_admin_rule_text"]

src/kpaa/law_api/aliases.py

@@ -0,0 +1,254 @@
+"""법령 약칭 ↔ 정식명 매핑.
+
+법제처 OPEN API는 검색어로 *약칭*을 받으면 0건이 자주 나는 알려진 함정이 있다
+(예: "신용정보법" 직접 검색 → 빈 결과). 이 모듈은:
+
+1. 정식명 → 약칭 리스트(`LAW_ALIASES`)와 그 역방향(`ABBR_TO_OFFICIAL`)을 동시 제공.
+2. 사용자 질의에서 약칭을 *정식명* 으로 치환(`normalize_law_name`).
+3. 단일 쿼리를 *검색 후보 다중화*해 폴백 큐로 활용(`expand_search_terms`).
+
+쿼리 시점·LLM 라우터·rule fallback 모두 이 모듈을 import해 일관 처리한다.
+원작 chrisryugj/korean-law-mcp `LAW_ALIAS_ENTRIES`(52종) 의 매핑 사실을 참고하되,
+KPAA 도메인(개인정보·정보통신·금융·의료) 항목을 우선 보강했다.
+"""
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+# ────────────────────────────────────────────────────────────────────────────
+# 정식명 → 약칭 리스트
+# ────────────────────────────────────────────────────────────────────────────
+# 원칙: 정식 법령명(법제처 등록명)을 키로, 통용 약칭을 값으로.
+# 약칭은 띄어쓰기·중점(·) 변형까지 포함해 매칭 누수를 줄인다.
+# 도메인 분류는 주석으로만 남김 (코드는 단일 dict).
+LAW_ALIASES: dict[str, list[str]] = {
+    # ── 개인정보 도메인 (KPAA 핵심) ──────────────────────────────────────
+    "개인정보 보호법": ["개인정보보호법", "개보법", "개인정보법"],
+    "개인정보 보호법 시행령": ["개인정보보호법 시행령", "개보법 시행령", "보호법 시행령"],
+    "개인정보 보호법 시행규칙": ["개인정보보호법 시행규칙", "개보법 시행규칙"],
+    "정보통신망 이용촉진 및 정보보호 등에 관한 법률": [
+        "정보통신망법",
+        "정통망법",
+        "정보통신망 이용촉진법",
+    ],
+    "신용정보의 이용 및 보호에 관한 법률": ["신용정보법", "신정법"],
+    "위치정보의 보호 및 이용 등에 관한 법률": ["위치정보법"],
+    "통신비밀보호법": ["통비법"],
+    "전자정부법": ["전정법"],
+    "전자서명법": [],
+    "공공기관의 정보공개에 관한 법률": ["정보공개법", "정공법"],
+    "공공기관의 운영에 관한 법률": ["공공기관운영법", "공운법"],
+    "주민등록법": [],
+    "전자금융거래법": ["전금법"],
+    "특정 금융거래정보의 보고 및 이용 등에 관한 법률": ["특금법", "특정금융거래법"],
+
+    # ── 의료·보건 (개인정보 민감정보 인접) ─────────────────────────────
+    "의료법": [],
+    "약사법": [],
+    "감염병의 예방 및 관리에 관한 법률": ["감염병예방법"],
+    "정신건강증진 및 정신질환자 복지서비스 지원에 관한 법률": ["정신건강복지법"],
+    "국민건강보험법": ["건강보험법", "국건법"],
+    "보건의료기본법": [],
+
+    # ── 청소년·아동·교육 ────────────────────────────────────────────
+    "아동복지법": [],
+    "청소년 보호법": ["청보법"],
+    "초·중등교육법": ["초중등교육법"],
+    "고등교육법": [],
+    "유아교육법": [],
+
+    # ── 노무·고용 (채용 chain) ─────────────────────────────────────────
+    "근로기준법": ["근기법"],
+    "직업안정법": [],
+    "남녀고용평등과 일·가정 양립 지원에 관한 법률": ["남녀고용평등법"],
+    "산업안전보건법": ["산안법"],
+    "중대재해 처벌 등에 관한 법률": ["중처법", "중대재해처벌법"],
+    "기간제 및 단시간근로자 보호 등에 관한 법률": ["기간제법"],
+    "근로자퇴직급여 보장법": ["퇴직급여보장법"],
+    "산업재해보상보험법": ["산재보험법"],
+    "고용보험법": ["고보법"],
+
+    # ── 금융·소비자 ───────────────────────────────────────────────
+    "자본시장과 금융투자업에 관한 법률": ["자본시장법", "자금법"],
+    "약관의 규제에 관한 법률": ["약관법"],
+    "할부거래에 관한 법률": ["할부거래법"],
+    "전자상거래 등에서의 소비자보호에 관한 법률": ["전자상거래법", "전상법"],
+
+    # ── 공정거래 ──────��────────────────────────────────────────────
+    "독점규제 및 공정거래에 관한 법률": ["공정거래법", "독규법"],
+    "하도급거래 공정화에 관한 법률": ["하도급법"],
+    "표시·광고의 공정화에 관한 법률": ["표시광고법"],
+    "가맹사업거래의 공정화에 관한 법률": ["가맹사업법"],
+
+    # ── 부동산·임대차 ──────────────────────────────────────────────
+    "주택임대차보호법": ["주임법"],
+    "상가건물 임대차보호법": ["상임법"],
+    "부동산 거래신고 등에 관한 법률": ["부거법", "부동산거래신고법"],
+
+    # ── 행정·일반 ──────────────────────────────────────────────────
+    "행정기본법": ["행기법"],
+    "행정절차법": ["행절법"],
+    "행정심판법": [],
+    "행정소송법": [],
+    "민원 처리에 관한 법률": ["민원처리법"],
+
+    # ── 형사·민사 절차 ───────────────────────────────────────────
+    "형법": [],
+    "민법": [],
+    "형사소송법": ["형소법"],
+    "민사소송법": ["민소법"],
+    "민사집행법": ["민집법"],
+    "상법": [],
+
+    # ── 부패·청렴 ──────────────────────────────────────────────────
+    "부정청탁 및 금품등 수수의 금지에 관한 법률": ["청탁금지법", "김영란법"],
+    "공직자의 이해충돌 방지법": ["이해충돌방지법"],
+    "공익신고자 보호법": [],
+
+    # ── 공무원 ────────────────────────────────────────────────────
+    "국가공무원법": [],
+    "지방공무원법": ["지공법"],
+
+    # ── 인권 ───────────────────────────────────────────────────────
+    "국가인권위원회법": ["인권위법"],
+
+    # ── 기타 KPAA-related ──────────────────────────────────────────
+    "지방공기업법": [],
+    "지능정보화 기본법": [],
+    "전기통신사업법": ["전사법"],
+}
+
+# ────────────────────────────────────────────────────────────────────────────
+# 역인덱스: 약칭 → 정식명 (1:1)
+# ────────────────────────────────────────────────────────────────────────────
+def _build_reverse() -> dict[str, str]:
+    """약칭 한 개가 두 개 이상의 정식명에 매핑되면 *나중에 등록된 것* 으로 덮어쓴다.
+
+    실제 LAW_ALIASES는 충돌이 없도록 큐레이션되어야 한다 (충돌은 의도적 선택).
+    """
+    out: dict[str, str] = {}
+    for official, abbrevs in LAW_ALIASES.items():
+        for ab in abbrevs:
+            ab_norm = ab.strip()
+            if not ab_norm:
+                continue
+            out[ab_norm] = official
+    return out
+
+
+ABBR_TO_OFFICIAL: dict[str, str] = _build_reverse()
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# 매칭 유틸
+# ────────────────────────────────────────────────────────────────────────────
+@lru_cache(maxsize=1)
+def _abbrev_pattern() -> re.Pattern[str]:
+    """모든 약칭을 한 번에 잡는 정규식. 긴 약칭부터 매칭(부분매칭 우선순위)."""
+    keys = sorted(ABBR_TO_OFFICIAL.keys(), key=len, reverse=True)
+    if not keys:
+        # 빈 사전이면 절대 매칭 안 되는 패턴
+        return re.compile(r"(?!.*)")
+    escaped = [re.escape(k) for k in keys]
+    return re.compile("|".join(escaped))
+
+
+def normalize_law_name(text: str) -> str:
+    """텍스트 안의 *약칭 토큰* 을 정식 법령명으로 치환.
+
+    예시:
+        "신용정보법 위반 사례"   → "신용정보의 이용 및 보호에 관한 법률 위반 사례"
+        "정통망법 제22조"        → "정보통신망 이용촉진 및 정보보호 등에 관한 법률 제22조"
+
+    이미 ���식명 형태면 그대로 반환. 약칭이 다른 단어의 부분문자열이면 매칭하지 않게
+    조심해야 하지만, 한국어 법률 약칭은 대부분 단어 경계 의미가 모호하므로 *최장
+    매칭 우선* 전략으로만 처리한다 (충분히 안전).
+    """
+    if not text:
+        return text
+    pat = _abbrev_pattern()
+    return pat.sub(lambda m: ABBR_TO_OFFICIAL[m.group(0)], text)
+
+
+def aliases_for(official_name: str) -> list[str]:
+    """정식명 → 약칭 리스트. 등록 안 됐으면 빈 리스트."""
+    return list(LAW_ALIASES.get(official_name, []))
+
+
+def is_known_alias(token: str) -> bool:
+    """token 이 등록된 약칭인지."""
+    return token.strip() in ABBR_TO_OFFICIAL
+
+
+def official_name_for(abbrev: str) -> str | None:
+    """약칭 → 정식명. 등록 안 됐으면 None."""
+    return ABBR_TO_OFFICIAL.get(abbrev.strip())
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# 검색어 확장 (폴백 큐 생성용)
+# ────────────────────────────────────────────────────────────────────────────
+_LAW_ABBR_SUFFIX_RE = re.compile(r"법$")
+
+
+def expand_search_terms(query: str, *, max_variants: int = 5) -> list[str]:
+    """단일 쿼리를 *검색 폴백 후보들* 로 확장.
+
+    법제처 API 검색 미스가 잦은 케이스 대응 용도. 호출자는 반환된 후보들을
+    순서대로 시도해 첫 번째 비어있지 않은 결과를 채택한다.
+
+    확장 규칙:
+        1) 원본 쿼리 (그대로)
+        2) 약칭이 포함되었으면 *정식명 치환본*
+        3) 본질 명사만 (예: "신용정보법" → "신용정보")
+        4) 정식명에서 본질 명사만 (예: "...신용정보의 이용..." → "신용정보 이용")
+        5) 약칭 자체 (정식명이 입력된 경우 역으로 약칭도 시도)
+
+    중복은 제거하되 *원본 우선* 순서를 보존.
+    """
+    if not query.strip():
+        return []
+    seen: set[str] = set()
+    out: list[str] = []
+
+    def _push(t: str) -> None:
+        t = t.strip()
+        if t and t not in seen:
+            seen.add(t)
+            out.append(t)
+
+    # (1) 원본
+    _push(query)
+
+    # (2) 약칭 → 정식명 치환
+    normalized = normalize_law_name(query)
+    if normalized != query:
+        _push(normalized)
+
+    # (3) "...법" 약칭에서 "법" 떼고 본질 명사만 (예: 신용정보법 → 신용정보)
+    for abbrev in ABBR_TO_OFFICIAL:
+        if abbrev in query:
+            stem = _LAW_ABBR_SUFFIX_RE.sub("", abbrev).strip()
+            if stem and stem != abbrev:
+                _push(query.replace(abbrev, stem))
+                _push(stem)
+
+    # (4) 약칭 자체도 후보로 (정식명이 직접 들어온 경우 등)
+    for official, abbrevs in LAW_ALIASES.items():
+        if official in query and abbrevs:
+            for ab in abbrevs:
+                _push(query.replace(official, ab))
+
+    return out[:max_variants]
+
+
+__all__ = [
+    "LAW_ALIASES",
+    "ABBR_TO_OFFICIAL",
+    "normalize_law_name",
+    "aliases_for",
+    "is_known_alias",
+    "official_name_for",
+    "expand_search_terms",
+]

src/kpaa/law_api/article_history.py

@@ -0,0 +1,141 @@
+"""조문 변경 이력 (target=lsJoHstInf) — *list endpoint 전용*.
+
+라이브 검증 완료 (2026-05-01 LAW_OC 환경):
+    path = lawSearch.do
+    params:
+        - ID=<법령ID> (필수, MST 아님 주의)
+        - JO=<6자리코드> (선택)
+        - **fromRegDt + toRegDt** = YYYYMMDD (사실상 필수 — 없으면 0건 반환)
+        - regDt = 단일 일자 (선택)
+        - page = 페이지 (선택)
+    응답 root → `<LawSearch>` → `<law id="N">` 다수
+        - `<법령정보>` → 법령명한글, 법령ID, 법령일련번호, 공포일자, 공포번호,
+          제개정구분명, 소관부처명, 법령구분명, 시행일자
+        - `<조문정보>` → `<jo num="N">` 다수
+            - 조문번호(6자리), 변경사유, 조문링크, 조문변경이력상세링크,
+              조문개정일, 조문시행일
+
+⚠️ 라이브 검증 시 발견한 quirk:
+    - fromRegDt+toRegDt 미지정 시 totalCnt=0 응답 (endpoint 가 무한 검색 거부)
+    - `<jo>` 가 `<law>` 직속이 아니라 `<조문정보>` 아래에 중첩
+    이 두 가지를 코드가 흡수해 호출자는 *그냥 search* 만 하면 동작.
+
+KPAA 활용: `개정_이력` intent 매칭 + plan.jo_targets 명시 시 활성화.
+oldnew(법령 단위 신구비교) 와는 *세분화 수준* 이 달라 함께 호출되어도 의미 있음.
+"""
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+from kpaa.law_api.client import LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import LSJOHSTINF
+from kpaa.law_api.jo import decode_jo, encode_jo
+from kpaa.law_api.models import ArticleHistoryItem
+from kpaa.law_api.parsers import child_text, parse_xml
+
+CACHE_TTL_LIST = 24 * 3600   # 24h — 개정 이력은 자주 안 바뀜
+
+# 기간 default — endpoint 의 *기간 필터 필수* 특성 흡수용. KPAA 도메인은 *최근*
+# 개정에 관심이 큼 → 기본 10년. 호출자가 명시하면 override.
+_DEFAULT_LOOKBACK_DAYS = 365 * 10
+
+
+def _default_period() -> tuple[str, str]:
+    today = date.today()
+    past = today - timedelta(days=_DEFAULT_LOOKBACK_DAYS)
+    return past.strftime("%Y%m%d"), today.strftime("%Y%m%d")
+
+
+async def search_article_history(
+    client: LawGoKrClient,
+    *,
+    law_id: str,
+    jo: str | int | None = None,
+    from_date: str | None = None,
+    to_date: str | None = None,
+    on_date: str | None = None,
+    org: str | None = None,
+    page: int = 1,
+) -> list[ArticleHistoryItem]:
+    """조문 개정 이력 list 조회.
+
+    Args:
+        law_id: 법령ID. **MST 아님 주의** — `client.law.get_text(mst=...)`의
+            응답 LawText.law_id 에서 얻을 수 있다.
+        jo: 조문 번호 ("15", "24의2", 15, …). encode_jo 로 6자리 코드 변환.
+            None 이면 모든 조문 이력.
+        on_date / from_date / to_date: YYYYMMDD 형식. 시점·기간 필터.
+            **from_date+to_date 미지정 시 자동으로 최근 10년 default 적용**
+            (endpoint quirk 흡수).
+        org: 소관부처코드.
+        page: 페이지 번호.
+    """
+    if not law_id:
+        raise ValueError("law_id required (lsJoHstInf 는 lawId 기반)")
+    params: dict[str, str] = {"ID": str(law_id), "page": str(page)}
+    if jo is not None:
+        # encode_jo 는 이미 6자리면 그대로 통과. "15" → "001500"
+        params["JO"] = encode_jo(jo)
+    if on_date:
+        params["regDt"] = str(on_date)
+    elif not (from_date or to_date):
+        # 기간 미지정 + on_date 미지정 시 default 기간 박음 (endpoint quirk).
+        f, t = _default_period()
+        params["fromRegDt"] = f
+        params["toRegDt"] = t
+    if from_date:
+        params["fromRegDt"] = str(from_date)
+    if to_date:
+        params["toRegDt"] = str(to_date)
+    if org:
+        params["org"] = str(org)
+
+    body = await client.fetch(
+        LawApiCall(
+            target=LSJOHSTINF.target,
+            path=LIST_PATH,
+            params=params,
+            cache_ttl=CACHE_TTL_LIST,
+        )
+    )
+    root = parse_xml(body)
+
+    out: list[ArticleHistoryItem] = []
+    for law_el in root.findall(".//law"):
+        info = law_el.find("법령정보")
+        if info is None:
+            continue
+        law_name = child_text(info, "법령명한글")
+        rid = child_text(info, "법령ID") or law_id
+        mst = child_text(info, "법령일련번호")
+        promul = child_text(info, "공포일자")
+        change_type = child_text(info, "제개정구분명")
+        enforce = child_text(info, "시행일자")
+
+        # `<jo>` 는 `<law>` 직속이 아니라 `<조문정보>` 아래 중첩 (라이브 검증).
+        # `.//jo` 로 descendant 매칭하여 양쪽 구조 다 흡수.
+        for jo_el in law_el.findall(".//jo"):
+            jo_code = child_text(jo_el, "조문번호")
+            try:
+                jo_decoded = decode_jo(jo_code) if jo_code and len(jo_code) == 6 else jo_code
+            except ValueError:
+                jo_decoded = jo_code
+            out.append(
+                ArticleHistoryItem(
+                    law_name=law_name,
+                    law_id=rid,
+                    mst=mst,
+                    article_no=jo_decoded,
+                    article_jo_code=jo_code,
+                    change_type=change_type,
+                    change_reason=child_text(jo_el, "변경사유"),
+                    article_amend_date=child_text(jo_el, "조문개정일"),
+                    article_enforce_date=child_text(jo_el, "조문시행일"),
+                    promulgate_date=promul,
+                    enforce_date=enforce,
+                )
+            )
+    return out
+
+
+__all__ = ["search_article_history"]

src/kpaa/law_api/client.py

@@ -0,0 +1,154 @@
+"""법제처 OPEN API 베이스 HTTP 클라이언트.
+
+상위 모듈(`law.py`, `pipc.py`, …)이 `LawApiCall`을 만들어 `fetch()`로 보내고,
+이 클래스는 인증·재시도·캐시·동시성 캡을 통일 처리한다. XML 파싱은 호출자에서
+`parsers.py`를 사용해 진행한다.
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import diskcache
+import httpx
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential_jitter,
+)
+
+from kpaa.config import get_settings
+
+logger = logging.getLogger("kpaa.law_api")
+
+BASE_URL = "https://www.law.go.kr/DRF"
+LIST_PATH = "/lawSearch.do"
+DETAIL_PATH = "/lawService.do"
+
+_DEFAULT_TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+_USER_AGENT = "kpaa/0.1 (+https://github.com/sz1-kca/korean-privacy-ai-assistant)"
+
+_RETRYABLE_STATUS = {408, 425, 429, 500, 502, 503, 504}
+
+
+class _RetryableHTTPError(Exception):
+    """HTTP 상태가 일시적 오류군일 때 재시도 트리거용."""
+
+
+@dataclass(frozen=True)
+class LawApiCall:
+    target: str           # e.g. "law", "ppc", "expc", "prec", "admrul"
+    path: str             # LIST_PATH or DETAIL_PATH
+    params: dict[str, Any]
+    cache_ttl: int        # seconds (e.g. 3600 for search, 86400 for detail)
+
+
+class LawGoKrClient:
+    def __init__(
+        self,
+        *,
+        oc: str | None = None,
+        base_url: str = BASE_URL,
+        timeout: httpx.Timeout = _DEFAULT_TIMEOUT,
+        max_concurrency: int = 4,
+    ) -> None:
+        s = get_settings()
+        self.oc = oc if oc is not None else s.law_oc
+        self.base_url = base_url
+        self.timeout = timeout
+        self._http: httpx.AsyncClient | None = None
+        self._sem = asyncio.Semaphore(max_concurrency)
+        self._cache = diskcache.Cache(str(s.law_cache_dir))
+
+    async def __aenter__(self) -> LawGoKrClient:
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            http2=True,
+            headers={"User-Agent": _USER_AGENT, "Accept": "*/*"},
+        )
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    def _ensure_oc(self) -> str:
+        if not self.oc:
+            raise RuntimeError(
+                "법제처 OPEN API 인증 ID(LAW_OC)가 비어 있습니다. "
+                ".env 파일에 LAW_OC=<발급받은_id>를 입력하거나 "
+                "KoreanLawClient(oc=...)에 직접 전달하세요. "
+                "발급(무료): https://open.law.go.kr"
+            )
+        return self.oc
+
+    @staticmethod
+    def _cache_key(call: LawApiCall) -> str:
+        normalized = json.dumps(
+            {
+                "target": call.target,
+                "path": call.path,
+                "params": sorted(call.params.items()),
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+        )
+        return hashlib.sha1(normalized.encode("utf-8")).hexdigest()
+
+    async def fetch(self, call: LawApiCall) -> str:
+        if self._http is None:
+            raise RuntimeError("LawGoKrClient is not entered (use 'async with').")
+
+        key = self._cache_key(call)
+        cached = self._cache.get(key)
+        if cached is not None:
+            return cached  # type: ignore[return-value]
+
+        params: dict[str, Any] = {
+            "OC": self._ensure_oc(),
+            "type": "XML",
+            "target": call.target,
+            **call.params,
+        }
+
+        body: str | None = None
+        async with self._sem:
+            async for attempt in AsyncRetrying(
+                stop=stop_after_attempt(4),
+                wait=wait_exponential_jitter(initial=1, max=8),
+                retry=retry_if_exception_type(
+                    (httpx.TransportError, httpx.TimeoutException, _RetryableHTTPError)
+                ),
+                reraise=True,
+            ):
+                with attempt:
+                    resp = await self._http.get(call.path, params=params)
+                    if resp.status_code in _RETRYABLE_STATUS:
+                        raise _RetryableHTTPError(
+                            f"law.go.kr returned {resp.status_code} for target={call.target}"
+                        )
+                    resp.raise_for_status()
+                    body = resp.text
+
+        assert body is not None
+        # Sanity cap — *XML 안전한 byte 단순 절단은 불가능* (CDATA·태그 중간을
+        # 잘라 파서가 깨짐 — 라이브 검증 2026-05-01: 시행령 mst=273745 응답이
+        # 272K 라 이전 200K cap 에서 CDATA 미종료로 파싱 실패). 정책: *왜곡 없이
+        # 전달* 우선이므로 절단 안 함. 대신 *비정상적으로 큰 응답*(>5MB)은 경고
+        # 만 남기고 그대로 ���시 — 메모리 과사용 방어는 실용적 5MB 선에서.
+        if len(body) > 5_000_000:
+            logger.warning(
+                "law.go.kr response very large (%d chars) for target=%s — passing through anyway",
+                len(body),
+                call.target,
+            )
+
+        self._cache.set(key, body, expire=call.cache_ttl)
+        return body

src/kpaa/law_api/constitutional.py

@@ -0,0 +1,135 @@
+"""헌법재판소 결정문 (target=detc).
+
+라이브 검증 (원작 chrisryugj/korean-law-mcp 의 parseConstitutionalXML 매핑 기준):
+    list   : `lawSearch.do?target=detc&query=...&type=XML`
+             root=`<DetcSearch>` row=`<Detc>` (대문자 D)
+             필드: 헌재결정례일련번호 / 사건명 / 사건번호 / 종국일자 /
+                   헌재결정례상세링크
+    detail : `lawService.do?target=detc&ID=...&type=JSON`
+             JSON 컨테이너: `DetcService` 또는 `헌재결정례`
+             필드: 사건명·사건번호·종국일자·청구인·피청구인·
+                   판시사항·결정요지·참조조문·참조판례·전문(판례내용/결정내용)
+
+KPAA 활용: data_subject_rights/definition/medical_health chain 에서 자기결정권·
+기본권 헌재 판단 근거 보강.
+"""
+from __future__ import annotations
+
+import json
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import DETC
+from kpaa.law_api.models import ConstitutionalDecisionHit, ConstitutionalDecisionText
+from kpaa.law_api.parsers import child_text, parse_xml
+
+CACHE_TTL_SEARCH = 3600        # 1h
+CACHE_TTL_DETAIL = 24 * 3600   # 24h
+
+
+async def search_constitutional_decisions(
+    client: LawGoKrClient,
+    *,
+    query: str,
+    display: int = 20,
+    case_number: str | None = None,
+    sort: str | None = None,
+) -> list[ConstitutionalDecisionHit]:
+    """헌재 결정 검색.
+
+    Args:
+        query: 검색 키워드 (예: "자기결정권", "개인정보 자기결정권")
+        display: 1~100
+        case_number: 사건번호로 직접 조회 시 (예: "2020헌바123")
+        sort: 정렬 — lasc/ldes/dasc/ddes/nasc/ndes
+    """
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    params: dict[str, str] = {"display": str(display)}
+    if query:
+        params["query"] = query
+    if case_number:
+        params["nb"] = case_number
+    if sort:
+        params["sort"] = sort
+
+    body = await client.fetch(
+        LawApiCall(
+            target=DETC.target,
+            path=LIST_PATH,
+            params=params,
+            cache_ttl=CACHE_TTL_SEARCH,
+        )
+    )
+    root = parse_xml(body)
+    hits: list[ConstitutionalDecisionHit] = []
+    for el in root.findall(f".//{DETC.row_tag}"):
+        hits.append(
+            ConstitutionalDecisionHit(
+                decision_id=child_text(el, DETC.id_field),
+                title=child_text(el, "사건명"),
+                case_no=child_text(el, "사건번호"),
+                decision_date=child_text(el, "종국일자"),
+                detail_url=child_text(el, "헌재결정례상세링크"),
+            )
+        )
+    return hits
+
+
+async def get_constitutional_decision_text(
+    client: LawGoKrClient,
+    *,
+    decision_id: str,
+) -> ConstitutionalDecisionText | None:
+    """헌재 결정문 본문 (JSON detail).
+
+    응답이 비어있거나 형식 이상이면 None. 호출자는 None 처리.
+    """
+    if not decision_id:
+        raise ValueError("decision_id required")
+    # detail 응답은 JSON — params 의 type 키가 client.fetch 의 default("XML") 를 덮어씀.
+    body = await client.fetch(
+        LawApiCall(
+            target=DETC.target,
+            path=DETAIL_PATH,
+            params={"ID": str(decision_id), "type": "JSON"},
+            cache_ttl=CACHE_TTL_DETAIL,
+        )
+    )
+    if not body or not body.strip():
+        return None
+    try:
+        data = json.loads(body)
+    except json.JSONDecodeError:
+        return None
+    payload = data.get("DetcService") or data.get("헌재결정례") or {}
+    if not isinstance(payload, dict) or not payload:
+        return None
+
+    return ConstitutionalDecisionText(
+        decision_id=str(decision_id),
+        title=str(payload.get("사건명", "") or ""),
+        case_no=str(payload.get("사건번호", "") or ""),
+        decision_date=str(
+            payload.get("종국일자") or payload.get("선고일자") or ""
+        ),
+        petitioner=str(payload.get("청구인", "") or ""),
+        respondent=str(payload.get("피청구인", "") or ""),
+        issues=str(payload.get("판시사항", "") or ""),
+        summary=str(
+            payload.get("결정요지") or payload.get("판결요지") or ""
+        ),
+        refs_law=str(payload.get("참조조문", "") or ""),
+        refs_precedent=str(payload.get("참조판례", "") or ""),
+        body=str(
+            payload.get("판례내용")
+            or payload.get("결정내용")
+            or payload.get("전문")
+            or ""
+        ),
+    )
+
+
+__all__ = [
+    "search_constitutional_decisions",
+    "get_constitutional_decision_text",
+]

src/kpaa/law_api/endpoints.py

@@ -0,0 +1,228 @@
+"""법제처 OPEN API의 target 토큰과 응답 row 태그 매핑.
+
+라이브 검증 완료 (2026-04-29):
+    https://www.law.go.kr/DRF/lawSearch.do?OC=...&target=<TARGET>&query=...&type=XML
+    https://www.law.go.kr/DRF/lawService.do?OC=...&target=<TARGET>&{ID|MST}=...&type=XML
+
+`detail_key`는 detail 호출에서 사용하는 1차 식별자 파라미터명이다:
+- target=law → MST (법령일련번호)
+- 그 외 → ID
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TargetSpec:
+    target: str        # URL 파라미터 값 (예: "law", "ppc")
+    row_tag: str       # 응답 XML의 1건 row 태그 (예: "law", "ppc")
+    id_field: str      # row 안의 detail ID 필드명 (예: "법령일련번호")
+    title_field: str   # row 안의 제목 필드명
+    detail_key: str    # detail 호출 파라미터명 ("MST" or "ID")
+    label: str         # 사람용 한국어 라벨
+
+
+# 법령 (target=law)
+LAW = TargetSpec(
+    target="law",
+    row_tag="law",
+    id_field="법령일련번호",
+    title_field="법령명한글",
+    detail_key="MST",
+    label="법령",
+)
+
+# 개인정보보호위원회 결정문 (target=ppc)
+PPC = TargetSpec(
+    target="ppc",
+    row_tag="ppc",
+    id_field="결정문일련번호",
+    title_field="안건명",
+    detail_key="ID",
+    label="개인정보보호위원회 결정",
+)
+
+# 법령해석례 (target=expc)
+EXPC = TargetSpec(
+    target="expc",
+    row_tag="expc",
+    id_field="법령해석례일련번호",
+    title_field="안건명",
+    detail_key="ID",
+    label="법령해석례",
+)
+
+# 행정규칙(훈령/예규/고시) (target=admrul)
+# knd 파라미터: 1=훈령, 2=예규, 3=고시 (chatbot은 개보위 고시 위주)
+ADMRUL = TargetSpec(
+    target="admrul",
+    row_tag="admrul",
+    id_field="행정규칙일련번호",
+    title_field="행정규칙명",
+    detail_key="ID",
+    label="행정규칙",
+)
+
+# 판례 (target=prec)
+PREC = TargetSpec(
+    target="prec",
+    row_tag="prec",
+    id_field="판례일련번호",
+    title_field="사건명",
+    detail_key="ID",
+    label="판례",
+)
+
+# 별표/별지서식 (target=licbyl) — `lawSearch.do`로 검색
+LICBYL = TargetSpec(
+    target="licbyl",
+    row_tag="licbyl",
+    id_field="별표일련번호",
+    title_field="별표명",
+    detail_key="ID",
+    label="별표서식",
+)
+
+# 자치법규 (target=ordin) — row tag 가 "law" (재사용)
+ORDIN = TargetSpec(
+    target="ordin",
+    row_tag="law",
+    id_field="자치법규일련번호",
+    title_field="자치법규명",
+    detail_key="ID",
+    label="자치법규",
+)
+
+# 조약 (target=trty)
+TRTY = TargetSpec(
+    target="trty",
+    row_tag="Trty",
+    id_field="조약일련번호",
+    title_field="조약명",
+    detail_key="ID",
+    label="조약",
+)
+
+# 영문법령 (target=elaw)
+ELAW = TargetSpec(
+    target="elaw",
+    row_tag="law",
+    id_field="법령일련번호",
+    title_field="법령명영문",
+    detail_key="MST",
+    label="영문법령",
+)
+
+# 신구법비교 (target=oldAndNew)
+OLDNEW = TargetSpec(
+    target="oldAndNew",
+    row_tag="oldAndNew",
+    id_field="법령일련번호",
+    title_field="법령명한글",
+    detail_key="MST",
+    label="신구법비교",
+)
+
+# 시행일자별 법령 (target=eflaw)
+EFLAW = TargetSpec(
+    target="eflaw",
+    row_tag="law",
+    id_field="법령일련번호",
+    title_field="법령명한글",
+    detail_key="MST",
+    label="시행일자별 법령",
+)
+
+# 공정거래위원회 결정 (target=ftc)
+FTC = TargetSpec(
+    target="ftc",
+    row_tag="ftc",
+    id_field="결정문일련번호",
+    title_field="사건명",
+    detail_key="ID",
+    label="공정거래위원회 결정",
+)
+
+# 노동위원회 결정 (target=nlrc)
+NLRC = TargetSpec(
+    target="nlrc",
+    row_tag="nlrc",
+    id_field="결정문일련번호",
+    title_field="제목",
+    detail_key="ID",
+    label="노동위원회 결정",
+)
+
+# 국민권익위원회 결정 (target=acr)
+ACR = TargetSpec(
+    target="acr",
+    row_tag="acr",
+    id_field="결정문일련번호",
+    title_field="제목",
+    detail_key="ID",
+    label="국민권익위원회 결정",
+)
+
+# 법령용어 (target=lstrm)
+LSTRM = TargetSpec(
+    target="lstrm",
+    row_tag="lstrm",
+    id_field="법령용어ID",
+    title_field="법령용어명",
+    detail_key="trmSeqs",  # detail은 trmSeqs 파라미터 (복수 ID 전달 가능)
+    label="법령용어",
+)
+
+# 헌법재판소 결정문 (target=detc)
+# 라이브 검증 (원작 xml-parser 기반): 검색 응답 root=`<DetcSearch>`, row tag=`<Detc>`.
+# detail 응답은 *JSON* — `data.DetcService` 또는 `data.헌재결정례` 키 아래 본문.
+# row 필드: 헌재결정례일련번호, 사건명, 사건번호, 종국일자, 헌재결정례상세링크.
+DETC = TargetSpec(
+    target="detc",
+    row_tag="Detc",
+    id_field="헌재결정례일련번호",
+    title_field="사건명",
+    detail_key="ID",
+    label="헌법재판소 결정",
+)
+
+# 조문 변경 이력 (target=lsJoHstInf) — *list endpoint 만 존재* (detail 없음).
+# 라이브 검증 (원작 api-client.ts/article-history.ts 기준):
+#   path = lawSearch.do
+#   필수 params: ID=<법령ID>, optional JO=<6자리코드>, regDt/fromRegDt/toRegDt, page
+#   응답 구조: root → <law> 다수 → <법령정보> + <jo> 다수
+#     <법령정보>: 법령명한글 / 법령ID / 법령일련번호 / 공포일자 / 제개정구분명 / 시행일자
+#     <jo>: 조문번호(6자리코드) / 변경사유 / 조문개정일 / 조문시행일
+# 주의: ID 는 *법령ID* (예: "011357") — *법령일련번호(MST)* 와 다르다.
+LSJOHSTINF = TargetSpec(
+    target="lsJoHstInf",
+    row_tag="law",
+    id_field="법령ID",
+    title_field="법령명한글",
+    detail_key="ID",   # detail endpoint 는 없지만 spec 일관성 위해 채워둠
+    label="조문 변경 이력",
+)
+
+
+ALL: tuple[TargetSpec, ...] = (
+    LAW, PPC, EXPC, ADMRUL, PREC, LICBYL,
+    ORDIN, TRTY, ELAW, OLDNEW, EFLAW,
+    FTC, NLRC, ACR, LSTRM, DETC, LSJOHSTINF,
+)
+
+
+# Day 3 시점에서 라이브 검증 실패 — 정확한 target 토큰 미확정.
+# v1 SDK에는 미포함. 사용자 SDK 피드백으로 후속 보강.
+PENDING: dict[str, str] = {
+    "헌재 결정문":      "search_constitutional_decisions",
+    "행정심판":         "search_admin_appeals",
+    "이의신청 결정":     "search_appeal_review_decisions",
+    "조세심판":         "search_tax_tribunal_decisions",
+    "관세 해석":        "search_customs_interpretations",
+    "학교 학칙":        "search_school_rules",
+    "공공기관 규정":     "search_public_institution_rules",
+    "공기업 규정":       "search_public_corp_rules",
+    "권익위 특별행심":   "search_acr_special_appeals",
+    "생활법령(daily)":   "get_daily_term / get_daily_to_legal / get_legal_to_daily",
+}

src/kpaa/law_api/english.py

@@ -0,0 +1,40 @@
+"""영문 법령 (target=elaw)."""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import ELAW
+from kpaa.law_api.parsers import child_text, parse_xml
+
+
+async def search_english_laws(
+    client: LawGoKrClient, *, query: str, display: int = 20
+) -> list[dict[str, str]]:
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    body = await client.fetch(
+        LawApiCall(target=ELAW.target, path=LIST_PATH,
+                   params={"query": query, "display": str(display)},
+                   cache_ttl=3600)
+    )
+    root = parse_xml(body)
+    return [
+        {
+            "mst": child_text(el, "법령일련번호"),
+            "name_en": child_text(el, "법령명영문"),
+            "name_ko": child_text(el, "법령명한글"),
+            "promulgate_date": child_text(el, "공포일자"),
+            "enforce_date": child_text(el, "시행일자"),
+            "department": child_text(el, "소관부처명"),
+        }
+        for el in root.findall(f".//{ELAW.row_tag}")
+    ]
+
+
+async def get_english_law_text(client: LawGoKrClient, *, mst: str) -> str:
+    return await client.fetch(
+        LawApiCall(target=ELAW.target, path=DETAIL_PATH,
+                   params={"MST": str(mst)}, cache_ttl=24 * 3600)
+    )
+
+
+__all__ = ["search_english_laws", "get_english_law_text"]

src/kpaa/law_api/ftc.py

@@ -0,0 +1,45 @@
+"""공정거래위원회 결정 (target=ftc).
+
+라이브 검증 row 필드: 결정문일련번호 / 사건명 / 사건번호 / 문서유형 /
+회의종류 / 결정번호 / 결정일자.
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import FTC
+from kpaa.law_api.parsers import child_text, parse_xml
+
+
+async def search_ftc_decisions(
+    client: LawGoKrClient, *, query: str, display: int = 20
+) -> list[dict[str, str]]:
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    body = await client.fetch(
+        LawApiCall(target=FTC.target, path=LIST_PATH,
+                   params={"query": query, "display": str(display)},
+                   cache_ttl=3600)
+    )
+    root = parse_xml(body)
+    return [
+        {
+            "decision_id": child_text(el, "결정문일련번호"),
+            "case_name": child_text(el, "사건명"),
+            "case_no": child_text(el, "사건번호"),
+            "document_kind": child_text(el, "문서유형"),
+            "meeting_kind": child_text(el, "회의종류"),
+            "decision_no": child_text(el, "결정번호"),
+            "decision_date": child_text(el, "결정일자"),
+        }
+        for el in root.findall(f".//{FTC.row_tag}")
+    ]
+
+
+async def get_ftc_decision_text(client: LawGoKrClient, *, decision_id: str) -> str:
+    return await client.fetch(
+        LawApiCall(target=FTC.target, path=DETAIL_PATH,
+                   params={"ID": str(decision_id)}, cache_ttl=24 * 3600)
+    )
+
+
+__all__ = ["search_ftc_decisions", "get_ftc_decision_text"]

src/kpaa/law_api/interpretation.py

@@ -0,0 +1,96 @@
+"""법령해석례 — `target=expc`.
+
+라이브 검증(2026-04-29):
+- 검색: lawSearch.do?target=expc&query=...&display=...
+  root=<Expc>, row=<expc>, id=법령해석례일련번호
+- 본문: lawService.do?target=expc&ID=...
+  root=<ExpcService>, fields: 안건명/안건번호/해석일자/질의기관명/회신기관명/질의요지/회답/이유
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import EXPC
+from kpaa.law_api.models import InterpretationHit, InterpretationText
+from kpaa.law_api.parsers import child_text, parse_xml
+
+CACHE_TTL_SEARCH = 3600
+CACHE_TTL_DETAIL = 24 * 3600
+
+INTERPRETATION_BODY_LIMIT = 8000
+
+
+async def search_interpretations(
+    client: LawGoKrClient,
+    *,
+    query: str,
+    display: int = 20,
+) -> list[InterpretationHit]:
+    """법령해석례 목록 검색."""
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    call = LawApiCall(
+        target=EXPC.target,
+        path=LIST_PATH,
+        params={"query": query, "display": str(display)},
+        cache_ttl=CACHE_TTL_SEARCH,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+
+    hits: list[InterpretationHit] = []
+    for el in root.findall(f".//{EXPC.row_tag}"):
+        hits.append(
+            InterpretationHit(
+                interpretation_id=child_text(el, EXPC.id_field),
+                title=child_text(el, "안건명"),
+                case_no=child_text(el, "안건번호"),
+                decided_date=child_text(el, "회신일자"),
+                inquirer=child_text(el, "질의기관명"),
+                responder=child_text(el, "회신기관명"),
+            )
+        )
+    return hits
+
+
+async def get_interpretation_text(
+    client: LawGoKrClient,
+    *,
+    interpretation_id: str,
+) -> InterpretationText:
+    """법령해석례 본문."""
+    call = LawApiCall(
+        target=EXPC.target,
+        path=DETAIL_PATH,
+        params={"ID": str(interpretation_id)},
+        cache_ttl=CACHE_TTL_DETAIL,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+
+    question = child_text(root, "질의요지")
+    answer = child_text(root, "회답")
+    reason = child_text(root, "이유")
+
+    used = len(question) + len(answer) + len(reason)
+    if used > INTERPRETATION_BODY_LIMIT:
+        # 회답 우선, 그 다음 질의요지, 마지막 이유 잘라냄
+        budget = INTERPRETATION_BODY_LIMIT - len(answer) - len(question)
+        if budget < 0:
+            budget = 0
+        if budget < len(reason):
+            reason = reason[:budget] + "\n…(중략)…"
+
+    return InterpretationText(
+        interpretation_id=str(interpretation_id),
+        title=child_text(root, "안건명"),
+        case_no=child_text(root, "안건번호"),
+        decided_date=child_text(root, "해석일자"),
+        inquirer=child_text(root, "질의기관명"),
+        responder=child_text(root, "해석기관명") or child_text(root, "회신기관명"),
+        question=question,
+        answer=answer,
+        reason=reason,
+    )
+
+
+__all__ = ["search_interpretations", "get_interpretation_text"]

src/kpaa/law_api/jo.py

@@ -0,0 +1,134 @@
+"""법제처 OPEN API의 JO(조문) 6자리 코드 인코딩 + 항/조 번호 정규화.
+
+라이브 검증(2026-04-29):
+    "15"        → "001500"   (제15조)
+    "15의2"     → "001502"   (제15조의2)
+    "24의2"     → "002402"   (제24조의2 = 주민등록번호 처리의 제한)
+    "22의2"     → "002202"   (제22조의2 = 아동의 개인정보 보호)
+
+규칙: 4자리 조 번호 + 2자리 가지 번호 ("의 N"이 없으면 "00").
+"""
+from __future__ import annotations
+
+import re
+
+_RE = re.compile(
+    r"^\s*(?:제)?\s*(\d+)\s*(?:조)?\s*(?:의\s*(\d+)|[-_]\s*(\d+))?\s*(?:조)?\s*$"
+)
+
+
+def encode_jo(article_no: str | int) -> str:
+    """Encode an article number (조문 번호) to the 6-digit JO code.
+
+    Accepts:
+        15, "15", "제15조", "15조", "15의2", "15-2", "제24조의2", ...
+
+    Returns 6-digit string suitable for `JO=<code>` parameter.
+    """
+    if isinstance(article_no, int):
+        return f"{article_no:04d}00"
+    s = str(article_no).strip()
+    m = _RE.match(s)
+    if not m:
+        raise ValueError(f"unrecognized article number: {article_no!r}")
+    base = int(m.group(1))
+    branch_str = m.group(2) or m.group(3) or "0"
+    branch = int(branch_str)
+    if not 0 <= base <= 9999:
+        raise ValueError(f"article number out of range: {base}")
+    if not 0 <= branch <= 99:
+        raise ValueError(f"branch number out of range: {branch}")
+    return f"{base:04d}{branch:02d}"
+
+
+def decode_jo(code: str) -> str:
+    """Decode a 6-digit JO code back to a human-readable form.
+
+    "001500" → "15", "002402" → "24의2".
+    """
+    if not (isinstance(code, str) and len(code) == 6 and code.isdigit()):
+        raise ValueError(f"invalid JO code: {code!r}")
+    base = int(code[:4])
+    branch = int(code[4:])
+    return f"{base}" if branch == 0 else f"{base}의{branch}"
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# 원숫자(①②③) 파서 + 일반화된 항번호 파서
+# ────────────────────────────────────────────────────────────────────────────
+# 법제처 응답의 `<항번호>` 값은 한글 원숫자로 옴 — 예: "①", "② ", "(1)", "1.".
+# 단순 `int(raw)` / `int(raw.replace(...))` 는 NaN 또는 ValueError 를 낸다.
+# 이 매핑은 Unicode 코드포인트 동시 커버:
+#   U+2460..U+2473  ① ~ ⑳   (1~20)
+#   U+2474..U+2487  ⑴ ~ ⒇   (1~20, parenthesized)
+#   U+24EA          ⓪      (0)
+#   U+3251..U+325F  ㉑ ~ ㉟  (21~35)
+#   U+32B1..U+32BF  ㊱ ~ ㊿  (36~50)
+_CIRCLED_DIGIT_MAP: dict[str, int] = {}
+for _i in range(20):
+    _CIRCLED_DIGIT_MAP[chr(0x2460 + _i)] = _i + 1   # ①..⑳
+    _CIRCLED_DIGIT_MAP[chr(0x2474 + _i)] = _i + 1   # ⑴..⒇
+_CIRCLED_DIGIT_MAP[chr(0x24EA)] = 0
+for _i in range(15):
+    _CIRCLED_DIGIT_MAP[chr(0x3251 + _i)] = _i + 21  # ㉑..㉟
+for _i in range(15):
+    _CIRCLED_DIGIT_MAP[chr(0x32B1 + _i)] = _i + 36  # ㊱..㊿
+del _i
+
+_PLAIN_DIGITS_RE = re.compile(r"\d+")
+
+
+def parse_hang_number(raw: str | int | None) -> int | None:
+    """`<항번호>` 등 한국 법령 텍스트의 항/호 번호를 정수로 정규화.
+
+    수용 가능 입력:
+        ① ② ⑩      → 1, 2, 10
+        "① "         → 1   (뒤 공백 OK)
+        "(1)" "1." "1) " "제1항" "제1호" "1"  → 1
+        ⓪            → 0
+        None / ""    → None
+
+    빈/이해 불가 입력은 None. 값 비교 시 `if (n := parse_hang_number(x)) == 1`
+    패턴으로 사용.
+
+    원작 article-parser.ts 의 `parseHangNumber()` 동등 — 작은 모델 응답에서
+    "최대 제0항" 식의 NaN→0 오판정 회귀 방지가 도입 동기.
+    """
+    if raw is None:
+        return None
+    if isinstance(raw, int):
+        return raw
+    s = str(raw).strip()
+    if not s:
+        return None
+    # 1) 원숫자 직접 매칭 (가장 흔한 케이스)
+    for ch in s:
+        if ch in _CIRCLED_DIGIT_MAP:
+            return _CIRCLED_DIGIT_MAP[ch]
+    # 2) 일반 숫자 fallback — 첫 번째 숫자 시퀀스
+    m = _PLAIN_DIGITS_RE.search(s)
+    if m:
+        try:
+            return int(m.group(0))
+        except ValueError:
+            return None
+    return None
+
+
+def normalize_jo(raw: str | int) -> str:
+    """다양한 조문 표기를 *decoded JO* 형태로 통일.
+
+    "제24조의2", "24-2", "24의2", "24조의2", "24_2" 모두 → "24의2".
+    "제15조", "15조", " 15 " 모두 → "15".
+
+    실패 시 ValueError. encode_jo + decode_jo 를 거치므로 같은 검증을 재사용.
+    """
+    return decode_jo(encode_jo(raw))
+
+
+__all__ = [
+    "encode_jo",
+    "decode_jo",
+    "normalize_jo",
+    "parse_hang_number",
+]

src/kpaa/law_api/law.py

@@ -0,0 +1,255 @@
+"""법령 카테고리 — 법제처 OPEN API `target=law` + 별표 `target=licbyl`.
+
+핵심 함수 (Day 2):
+- search_law          : 법령 목록 검색
+- get_law_text        : 법령 본문 (전체 또는 특정 조문)
+- get_article_detail  : 단일 조문 (편의 래퍼)
+- get_annexes         : 별표·별지서식 목록
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import LAW, LICBYL
+from kpaa.law_api.jo import decode_jo, encode_jo
+from kpaa.law_api.models import (
+    AnnexHit,
+    Article,
+    LawHit,
+    LawText,
+)
+from kpaa.law_api.parsers import child_text, parse_xml
+
+CACHE_TTL_SEARCH = 3600       # 1h
+CACHE_TTL_DETAIL = 24 * 3600  # 24h
+
+# 조문 1개 본문 길이 컷 (캐시 전 적용). 정책: *왜곡 없이 전달* 우선이므로
+# 일반 조문(평균 500~2000자) 은 절대 안 잘리는 너그러운 상한. 별표·서식이 본문에
+# 함께 오는 비정상적 응답에 대한 sanity cap 역할만.
+ARTICLE_BODY_LIMIT = 12000
+
+
+async def search_law(
+    client: LawGoKrClient,
+    *,
+    query: str,
+    display: int = 20,
+) -> list[LawHit]:
+    """법령 목록 검색 (`lawSearch.do?target=law`)."""
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    call = LawApiCall(
+        target=LAW.target,
+        path=LIST_PATH,
+        params={"query": query, "display": str(display)},
+        cache_ttl=CACHE_TTL_SEARCH,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+
+    hits: list[LawHit] = []
+    for el in root.findall(f".//{LAW.row_tag}"):
+        hits.append(
+            LawHit(
+                mst=child_text(el, LAW.id_field),
+                name=child_text(el, "법령명한글"),
+                name_short=child_text(el, "법령약칭명"),
+                promulgate_date=child_text(el, "공포일자"),
+                promulgate_no=child_text(el, "공포번호"),
+                enforce_date=child_text(el, "시행일자"),
+                type_name=child_text(el, "법령구분명"),
+                department=child_text(el, "소관부처명"),
+            )
+        )
+    return hits
+
+
+async def get_law_text(
+    client: LawGoKrClient,
+    *,
+    mst: str,
+    jo: str | int | None = None,
+) -> LawText:
+    """법령 본문 (`lawService.do?target=law&MST=...`).
+
+    Args:
+        mst: 법령일련번호
+        jo: 특정 조문만 받으려면 "15", "24의2", 15 등으로 지정. None이면 전체.
+    """
+    params: dict[str, str] = {"MST": mst}
+    if jo is not None:
+        params["JO"] = encode_jo(jo) if not (isinstance(jo, str) and jo.isdigit() and len(jo) == 6) else jo
+    call = LawApiCall(
+        target=LAW.target,
+        path=DETAIL_PATH,
+        params=params,
+        cache_ttl=CACHE_TTL_DETAIL,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+    return _parse_law_text(root, mst=mst)
+
+
+async def get_article_detail(
+    client: LawGoKrClient,
+    *,
+    mst: str,
+    article_no: str | int,
+) -> Article:
+    """단일 조문 (편의 래퍼).
+
+    내부적으로 `get_law_text(mst, jo=article_no)`를 호출하고 첫 조문을 반환.
+    조문이 없으면 빈 Article 반환 (raw_text="").
+    """
+    text = await get_law_text(client, mst=mst, jo=article_no)
+    for art in text.articles:
+        return art
+    return Article(mst=mst, article_no=str(article_no), title="", raw_text="")
+
+
+async def get_annexes(
+    client: LawGoKrClient,
+    *,
+    related_law_id: str | None = None,
+    query: str = "",
+    display: int = 20,
+) -> list[AnnexHit]:
+    """별표·별지서식 검색 (`lawSearch.do?target=licbyl`).
+
+    Args:
+        related_law_id: 특정 법령의 별표만 추리려면 법령ID(6자리, 예: "011357").
+                        주의: MST 가 아니라 법령ID. korean-law-mcp의 별표 도구도 동일.
+        query: 별표명/관련법령명 키워드 (선택)
+        display: 1~100
+    """
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    params: dict[str, str] = {"display": str(display)}
+    if query:
+        params["query"] = query
+    if related_law_id:
+        params["LSID"] = related_law_id
+
+    call = LawApiCall(
+        target=LICBYL.target,
+        path=LIST_PATH,
+        params=params,
+        cache_ttl=CACHE_TTL_SEARCH,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+
+    hits: list[AnnexHit] = []
+    for el in root.findall(f".//{LICBYL.row_tag}"):
+        hits.append(
+            AnnexHit(
+                annex_id=child_text(el, LICBYL.id_field),
+                name=child_text(el, "별표명"),
+                related_law_mst=child_text(el, "관련법령일련번호"),
+                related_law_name=child_text(el, "관련법령명"),
+                annex_no=child_text(el, "별표번호"),
+                annex_kind=child_text(el, "별표종류"),
+                promulgate_date=child_text(el, "공포일자"),
+                department=child_text(el, "소관부처명"),
+                file_url=child_text(el, "별표서식파일링크"),
+            )
+        )
+    return hits
+
+
+# ───────────────────────── parsers (private) ─────────────────────────
+
+def _parse_law_text(root, *, mst: str) -> LawText:
+    """`<법령>` 응답을 LawText로 파싱."""
+    info = root.find("기본정보")
+    name = ""
+    law_id = ""
+    enforce_date = ""
+    promulgate_date = ""
+    department = ""
+    if info is not None:
+        name = child_text(info, "법령명_한글")
+        law_id = child_text(info, "법령ID")
+        enforce_date = child_text(info, "시행일자")
+        promulgate_date = child_text(info, "공포일자")
+        soguan = info.find("소관부처")
+        if soguan is not None and soguan.text:
+            department = soguan.text.strip()
+
+    articles: list[Article] = []
+    for unit in root.findall(".//조문/조문단위"):
+        # `조문여부`가 "조문"인 단위만 본문 (전문/체계는 패스)
+        kind = child_text(unit, "조문여부")
+        if kind != "조문":
+            continue
+        article_no_raw = child_text(unit, "조문번호")
+        article_branch = child_text(unit, "조문가지번호") or "0"
+        if article_branch and article_branch != "0":
+            article_no = f"{article_no_raw}의{article_branch}"
+        else:
+            # 일부 응답은 조문가지번호 없이 조문키 7자리("0024020")로만 가지를 표현
+            key = unit.get("조문키", "")
+            if len(key) >= 7:
+                branch = int(key[4:6])
+                if branch:
+                    article_no = f"{int(key[:4])}의{branch}"
+                else:
+                    article_no = article_no_raw
+            else:
+                article_no = article_no_raw
+
+        title = child_text(unit, "조문제목")
+        enforce = child_text(unit, "조문시행일자") or enforce_date
+
+        # 본문: 조문내용 + 항(번호+내용) + 호(번호+내용)
+        parts: list[str] = []
+        body = child_text(unit, "조문내용")
+        if body:
+            parts.append(body)
+        para_texts: list[str] = []
+        for para in unit.findall("항"):
+            num = child_text(para, "항번호")
+            txt = child_text(para, "항내용")
+            line = (f"{num} {txt}" if num and not txt.startswith(num.strip()) else txt).strip()
+            if line:
+                parts.append(line)
+                para_texts.append(line)
+            for ho in para.findall("호"):
+                hno = child_text(ho, "호번호")
+                hcn = child_text(ho, "호내용")
+                if hcn:
+                    parts.append(hcn if hcn.startswith(hno.strip()) else f"{hno} {hcn}")
+
+        raw_text = "\n".join(parts)
+        if len(raw_text) > ARTICLE_BODY_LIMIT:
+            raw_text = raw_text[:ARTICLE_BODY_LIMIT] + "\n…(중략)…"
+
+        articles.append(
+            Article(
+                mst=mst,
+                article_no=article_no,
+                title=title,
+                enforce_date=enforce,
+                paragraphs=tuple(para_texts),
+                raw_text=raw_text,
+            )
+        )
+
+    return LawText(
+        mst=mst,
+        law_id=law_id,
+        name=name,
+        enforce_date=enforce_date,
+        promulgate_date=promulgate_date,
+        department=department,
+        articles=tuple(articles),
+    )
+
+
+__all__ = [
+    "search_law",
+    "get_law_text",
+    "get_article_detail",
+    "get_annexes",
+    "encode_jo",
+    "decode_jo",
+]

src/kpaa/law_api/models.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class LawHit(BaseModel):
+    """법령 검색 1건 (`lawSearch.do?target=law`)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    mst: str
+    name: str
+    name_short: str = ""
+    promulgate_date: str = ""
+    promulgate_no: str = ""
+    enforce_date: str = ""
+    type_name: str = ""
+    department: str = ""
+
+
+class Article(BaseModel):
+    """법령 본문에서 추출된 1개 조문."""
+
+    model_config = ConfigDict(frozen=True)
+
+    mst: str
+    article_no: str       # "15", "24의2"
+    title: str            # "개인정보의 수집ㆍ이용"
+    enforce_date: str = ""
+    paragraphs: tuple[str, ...] = ()  # 항 본문 (각 ① ② … 그대로)
+    raw_text: str = ""    # 사람이 읽기 좋은 결합 본문 (조문내용 + 항 + 호)
+
+    def citation(self, *, law_name: str = "개인정보보호법") -> str:
+        """답변에 박을 인용 태그. 예: '개인정보보호법 제15조'."""
+        # 24의2 → 제24조의2
+        ano = self.article_no
+        if "의" in ano:
+            base, branch = ano.split("의", 1)
+            return f"{law_name} 제{base}조의{branch}"
+        return f"{law_name} 제{ano}조"
+
+
+class LawText(BaseModel):
+    """법령 본문 응답 (조문 다수 또는 특정 조문)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    mst: str
+    law_id: str = ""
+    name: str
+    enforce_date: str = ""
+    promulgate_date: str = ""
+    department: str = ""
+    articles: tuple[Article, ...] = ()
+
+
+class PIPCDecisionHit(BaseModel):
+    """PIPC 결정문 검색 1건 (`lawSearch.do?target=ppc`)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    decision_id: str
+    title: str
+    decision_no: str = ""    # 안건번호 / 의안번호
+    decision_date: str = ""  # 의결일 YYYYMMDD or YYYY.MM.DD
+    decision_kind: str = ""  # 결정구분
+    agency: str = ""         # 기관명
+
+
+class PIPCDecisionText(BaseModel):
+    """PIPC 결정문 본문 (`lawService.do?target=ppc&ID=`)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    decision_id: str
+    title: str
+    decision_no: str = ""
+    decision_date: str = ""
+    decision_kind: str = ""
+    agency: str = ""
+    main_text: str = ""    # 주문
+    reason: str = ""       # 이유
+
+    def citation(self) -> str:
+        """답변에 박을 인용 태그.
+
+        의안번호가 있으면 'PIPC 결정 YYYY-NNN' 형태로, 없으면 ID 사용.
+        """
+        if self.decision_no and self.decision_no.lower() != "null":
+            return f"PIPC 결정 {self.decision_no}"
+        return f"PIPC 결정문 #{self.decision_id}"
+
+
+class InterpretationHit(BaseModel):
+    """법령해석례 검색 1건 (`lawSearch.do?target=expc`)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    interpretation_id: str
+    title: str
+    case_no: str = ""        # 안건번호 (예: "20-0370")
+    decided_date: str = ""   # 회신일자
+    inquirer: str = ""       # 질의기관명
+    responder: str = ""      # 회신기관명
+
+
+class InterpretationText(BaseModel):
+    """법령해석례 본문 (`lawService.do?target=expc&ID=`)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    interpretation_id: str
+    title: str
+    case_no: str = ""
+    decided_date: str = ""
+    inquirer: str = ""
+    responder: str = ""
+    question: str = ""   # 질의요지
+    answer: str = ""     # 회답
+    reason: str = ""     # 이유
+
+    def citation(self) -> str:
+        if self.case_no:
+            return f"법령해석례 안건 {self.case_no}"
+        return f"법령해석례 #{self.interpretation_id}"
+
+
+class ConstitutionalDecisionHit(BaseModel):
+    """헌재 결정문 검색 1건 (`lawSearch.do?target=detc`).
+
+    응답 row tag: `<Detc>` (대문자 D). 라이브 검증 (원작 korean-law-mcp
+    parseConstitutionalXML 기반).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    decision_id: str        # 헌재결정례일련번호
+    title: str              # 사건명
+    case_no: str = ""       # 사건번호 (예: "2020헌바123")
+    decision_date: str = "" # 종국일자
+    detail_url: str = ""    # 헌재결정례상세링크
+
+
+class ConstitutionalDecisionText(BaseModel):
+    """헌재 결정문 본문 (`lawService.do?target=detc&type=JSON&ID=`).
+
+    응답은 *JSON* 으로 옴 — `data.DetcService` 또는 `data.헌재결정례` 키 아래.
+    본문 비교적 길어 판시사항·결정요지·전문 분리 보존.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    decision_id: str
+    title: str               # 사건명
+    case_no: str = ""        # 사건번호
+    decision_date: str = ""  # 종국일자 또는 선고일자
+    petitioner: str = ""     # 청구인
+    respondent: str = ""     # 피청구인
+    issues: str = ""         # 판시사항
+    summary: str = ""        # 결정요지/판결요지
+    refs_law: str = ""       # 참조조문
+    refs_precedent: str = "" # 참조판례
+    body: str = ""           # 판례내용/결정내용/전문
+
+    def citation(self) -> str:
+        """답변에 박을 인용 태그.
+
+        사건번호가 있으면 '헌재 YYYY헌○NNN' 형태, 없으면 ID 사용.
+        """
+        if self.case_no:
+            return f"헌재 {self.case_no}"
+        return f"헌법재판소 결정문 #{self.decision_id}"
+
+
+class ArticleHistoryItem(BaseModel):
+    """조문 개정 이력 1건 (`lawSearch.do?target=lsJoHstInf`).
+
+    한 법령의 *특정 시점* 개정에서 *특정 조문* 의 변경 사항. 같은 조가 여러
+    번 바뀌었으면 같은 article_no 로 여러 item.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    law_name: str           # 법령명한글
+    law_id: str             # 법령ID
+    mst: str                # 법령일련번호
+    article_no: str         # 디코드된 조문 번호 (예: "15", "24의2")
+    article_jo_code: str    # 6자리 JO 코드 (예: "001500")
+    change_type: str = ""   # 제개정구분명 (예: "일부개정")
+    change_reason: str = "" # 변경사유
+    article_amend_date: str = ""    # 조문개정일 YYYYMMDD
+    article_enforce_date: str = ""  # 조문시행일 YYYYMMDD
+    promulgate_date: str = ""       # 공포일자 (법령 단위)
+    enforce_date: str = ""          # 시행일자 (법령 단위)
+
+    def citation(self) -> str:
+        """답변에 박을 인용 태그.
+
+        예: '개인정보보호법 제15조 (2020-08-05 개정)'.
+        """
+        # article_no → 표시 형태
+        ano = self.article_no
+        if "의" in ano:
+            base, branch = ano.split("의", 1)
+            disp = f"제{base}조의{branch}"
+        else:
+            disp = f"제{ano}조"
+        date_part = ""
+        d = self.article_amend_date or self.promulgate_date
+        if d and len(d) == 8:
+            date_part = f" ({d[:4]}-{d[4:6]}-{d[6:]} 개정)"
+        return f"{self.law_name} {disp}{date_part}"
+
+
+class AnnexHit(BaseModel):
+    """별표·별지서식 검색 1건 (`lawSearch.do?target=licbyl`)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    annex_id: str
+    name: str
+    related_law_mst: str = ""
+    related_law_name: str = ""
+    annex_no: str = ""
+    annex_kind: str = ""        # 별표/별지/서식
+    promulgate_date: str = ""
+    department: str = ""
+    file_url: str = ""

src/kpaa/law_api/nlrc.py

@@ -0,0 +1,41 @@
+"""중앙노동위원회 결정 (target=nlrc).
+
+라이브 검증 row 필드: 결정문일련번호 / 제목 / 사건번호 / 등록일.
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import NLRC
+from kpaa.law_api.parsers import child_text, parse_xml
+
+
+async def search_nlrc_decisions(
+    client: LawGoKrClient, *, query: str, display: int = 20
+) -> list[dict[str, str]]:
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    body = await client.fetch(
+        LawApiCall(target=NLRC.target, path=LIST_PATH,
+                   params={"query": query, "display": str(display)},
+                   cache_ttl=3600)
+    )
+    root = parse_xml(body)
+    return [
+        {
+            "decision_id": child_text(el, "결정문일련번호"),
+            "title": child_text(el, "제목"),
+            "case_no": child_text(el, "사건번호"),
+            "registered_date": child_text(el, "등록일"),
+        }
+        for el in root.findall(f".//{NLRC.row_tag}")
+    ]
+
+
+async def get_nlrc_decision_text(client: LawGoKrClient, *, decision_id: str) -> str:
+    return await client.fetch(
+        LawApiCall(target=NLRC.target, path=DETAIL_PATH,
+                   params={"ID": str(decision_id)}, cache_ttl=24 * 3600)
+    )
+
+
+__all__ = ["search_nlrc_decisions", "get_nlrc_decision_text"]

src/kpaa/law_api/oldnew.py

@@ -0,0 +1,48 @@
+"""신구법비교 (target=oldAndNew) — 동일 법령의 개정 전후 조문 비교.
+
+라이브 검증 row 필드: 신구법일련번호 / 신구법명 / 신구법ID / 공포일자 /
+공포번호 / 시행일자 / 제개정구분명 / 법령구분명 / 소관부처명.
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import OLDNEW
+from kpaa.law_api.parsers import child_text, parse_xml
+
+
+async def search_old_new(
+    client: LawGoKrClient, *, query: str, display: int = 20
+) -> list[dict[str, str]]:
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    body = await client.fetch(
+        LawApiCall(target=OLDNEW.target, path=LIST_PATH,
+                   params={"query": query, "display": str(display)},
+                   cache_ttl=3600)
+    )
+    root = parse_xml(body)
+    return [
+        {
+            "mst": child_text(el, "신구법일련번호"),
+            "law_id": child_text(el, "신구법ID"),
+            "name": child_text(el, "신구법명"),
+            "amend_type": child_text(el, "제개정구분명"),
+            "law_kind": child_text(el, "법령구분명"),
+            "promulgate_date": child_text(el, "공포일자"),
+            "promulgate_no": child_text(el, "공포번호"),
+            "enforce_date": child_text(el, "시행일자"),
+            "department": child_text(el, "소관부처명"),
+        }
+        for el in root.findall(f".//{OLDNEW.row_tag}")
+    ]
+
+
+async def compare_old_new(client: LawGoKrClient, *, mst: str) -> str:
+    """신·구 법조문 비교 본문 (raw XML)."""
+    return await client.fetch(
+        LawApiCall(target=OLDNEW.target, path=DETAIL_PATH,
+                   params={"MST": str(mst)}, cache_ttl=24 * 3600)
+    )
+
+
+__all__ = ["search_old_new", "compare_old_new"]

src/kpaa/law_api/ordinance.py

@@ -0,0 +1,55 @@
+"""자치법규 (target=ordin)."""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import ORDIN
+from kpaa.law_api.parsers import child_text, parse_xml
+
+CACHE_TTL_SEARCH = 3600
+CACHE_TTL_DETAIL = 24 * 3600
+
+
+async def search_ordinances(
+    client: LawGoKrClient,
+    *,
+    query: str,
+    display: int = 20,
+) -> list[dict[str, str]]:
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    call = LawApiCall(
+        target=ORDIN.target, path=LIST_PATH,
+        params={"query": query, "display": str(display)},
+        cache_ttl=CACHE_TTL_SEARCH,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+    out: list[dict[str, str]] = []
+    for el in root.findall(f".//{ORDIN.row_tag}"):
+        out.append(
+            {
+                "ordinance_id": child_text(el, "자치법규일련번호") or child_text(el, "법령일련번호"),
+                "name": child_text(el, "자치법규명") or child_text(el, "법령명한글"),
+                "promulgate_date": child_text(el, "공포일자"),
+                "enforce_date": child_text(el, "시행일자"),
+                "agency": child_text(el, "소관부처명") or child_text(el, "지자체기관명"),
+                "type": child_text(el, "자치법규종류") or child_text(el, "법령구분명"),
+            }
+        )
+    return out
+
+
+async def get_ordinance_text(
+    client: LawGoKrClient,
+    *,
+    ordinance_id: str,
+) -> str:
+    call = LawApiCall(
+        target=ORDIN.target, path=DETAIL_PATH,
+        params={"ID": str(ordinance_id)},
+        cache_ttl=CACHE_TTL_DETAIL,
+    )
+    return await client.fetch(call)
+
+
+__all__ = ["search_ordinances", "get_ordinance_text"]

src/kpaa/law_api/parsers.py

@@ -0,0 +1,30 @@
+"""법제처 OPEN API XML 응답 파싱 헬퍼.
+
+법제처 응답은 한글 태그 이름을 그대로 사용하므로 lxml의 일반 find/findall 와
+이 모듈의 가벼운 보조 함수로 충분하다.
+"""
+from __future__ import annotations
+
+from lxml import etree
+
+
+def parse_xml(body: str) -> etree._Element:
+    return etree.fromstring(body.encode("utf-8"))
+
+
+def text_of(el: etree._Element | None, default: str = "") -> str:
+    if el is None or el.text is None:
+        return default
+    return el.text.strip()
+
+
+def child_text(parent: etree._Element, tag: str, default: str = "") -> str:
+    return text_of(parent.find(tag), default)
+
+
+def all_text(el: etree._Element | None) -> str:
+    """Return concatenated text of an element and all descendants, joined by newline."""
+    if el is None:
+        return ""
+    parts = [t.strip() for t in el.itertext() if t and t.strip()]
+    return "\n".join(parts)

src/kpaa/law_api/pipc.py

@@ -0,0 +1,94 @@
+"""개인정보보호위원회 결정문 (PIPC) — `target=ppc`.
+
+라이브 검증(2026-04-29):
+- 검색: lawSearch.do?target=ppc&query=...&display=...
+  root=<Ppc>, row=<ppc>, id=결정문일련번호
+- 본문: lawService.do?target=ppc&ID=...
+  root=<PpcService>, container=<의결서>
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import PPC
+from kpaa.law_api.models import PIPCDecisionHit, PIPCDecisionText
+from kpaa.law_api.parsers import child_text, parse_xml
+
+CACHE_TTL_SEARCH = 3600
+CACHE_TTL_DETAIL = 24 * 3600
+
+DECISION_BODY_LIMIT = 10_000
+
+
+async def search_decisions(
+    client: LawGoKrClient,
+    *,
+    query: str,
+    display: int = 20,
+) -> list[PIPCDecisionHit]:
+    """PIPC 결정문 목록 검색."""
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    call = LawApiCall(
+        target=PPC.target,
+        path=LIST_PATH,
+        params={"query": query, "display": str(display)},
+        cache_ttl=CACHE_TTL_SEARCH,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+    agency = child_text(root, "기관명")
+
+    hits: list[PIPCDecisionHit] = []
+    for el in root.findall(f".//{PPC.row_tag}"):
+        hits.append(
+            PIPCDecisionHit(
+                decision_id=child_text(el, PPC.id_field),
+                title=child_text(el, "안건명"),
+                decision_no=child_text(el, "의안번호"),
+                decision_date=child_text(el, "의결일"),
+                decision_kind=child_text(el, "결정구분"),
+                agency=agency,
+            )
+        )
+    return hits
+
+
+async def get_decision_text(
+    client: LawGoKrClient,
+    *,
+    decision_id: str,
+) -> PIPCDecisionText:
+    """PIPC 결정문 본문."""
+    call = LawApiCall(
+        target=PPC.target,
+        path=DETAIL_PATH,
+        params={"ID": str(decision_id)},
+        cache_ttl=CACHE_TTL_DETAIL,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+    container = root.find("의결서")
+    if container is None:
+        container = root
+
+    main_text = child_text(container, "주문")
+    reason = child_text(container, "이유")
+    if len(main_text) + len(reason) > DECISION_BODY_LIMIT:
+        # 주문 우선 보존, 이유 잘라내기
+        budget = max(0, DECISION_BODY_LIMIT - len(main_text))
+        if budget < len(reason):
+            reason = reason[:budget] + "\n…(중략)…"
+
+    return PIPCDecisionText(
+        decision_id=str(decision_id),
+        title=child_text(container, "안건명"),
+        decision_no=child_text(container, "의안번호") or child_text(container, "안건번호"),
+        decision_date=child_text(container, "의결연월일"),
+        decision_kind=child_text(container, "결정"),
+        agency=child_text(container, "기관명"),
+        main_text=main_text,
+        reason=reason,
+    )
+
+
+__all__ = ["search_decisions", "get_decision_text"]

src/kpaa/law_api/precedent.py

@@ -0,0 +1,62 @@
+"""판례 (target=prec) — thin wrapper.
+
+검색은 list endpoint, 본문은 detail endpoint. 각 row를 dict로 반환.
+챗봇 RAG는 핵심 8개 외에서만 보조적으로 사용.
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import PREC
+from kpaa.law_api.parsers import child_text, parse_xml
+
+CACHE_TTL_SEARCH = 3600
+CACHE_TTL_DETAIL = 24 * 3600
+
+
+async def search_precedents(
+    client: LawGoKrClient,
+    *,
+    query: str,
+    display: int = 20,
+) -> list[dict[str, str]]:
+    """판례 목록 검색. dict 리스트 반환 (사건명/사건번호/선고일자/법원명/판례일련번호 등)."""
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    call = LawApiCall(
+        target=PREC.target, path=LIST_PATH,
+        params={"query": query, "display": str(display)},
+        cache_ttl=CACHE_TTL_SEARCH,
+    )
+    body = await client.fetch(call)
+    root = parse_xml(body)
+    out: list[dict[str, str]] = []
+    for el in root.findall(f".//{PREC.row_tag}"):
+        out.append(
+            {
+                "precedent_id": child_text(el, PREC.id_field),
+                "case_name": child_text(el, "사건명"),
+                "case_no": child_text(el, "사건번호"),
+                "decision_date": child_text(el, "선고일자"),
+                "court_name": child_text(el, "법원명"),
+                "case_kind": child_text(el, "사건종류명"),
+                "verdict_type": child_text(el, "판결유형"),
+            }
+        )
+    return out
+
+
+async def get_precedent_text(
+    client: LawGoKrClient,
+    *,
+    precedent_id: str,
+) -> str:
+    """판례 본문 — raw XML 반환 (구조 다양성 큼)."""
+    call = LawApiCall(
+        target=PREC.target, path=DETAIL_PATH,
+        params={"ID": str(precedent_id)},
+        cache_ttl=CACHE_TTL_DETAIL,
+    )
+    return await client.fetch(call)
+
+
+__all__ = ["search_precedents", "get_precedent_text"]

src/kpaa/law_api/raw.py

@@ -0,0 +1,83 @@
+"""Generic raw 호출 인터페이스.
+
+특정 카테고리 풀구현(법령/PIPC/해석례)이 노출하지 않는 target에 대해
+임의 target/파라미터로 list 또는 detail을 호출할 수 있다.
+SDK 사용자가 KoreanLawClient의 미구현 카테고리를 직접 채워 쓸 수 있도록.
+
+    rows = await client.raw.search("ftc", query="개인정보", display=10)
+    detail = await client.raw.get("ftc", id="12345")
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from kpaa.law_api.client import (
+    DETAIL_PATH,
+    LIST_PATH,
+    LawApiCall,
+    LawGoKrClient,
+)
+from kpaa.law_api.parsers import parse_xml
+
+
+def _row_to_dict(el) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for child in el:
+        txt = (child.text or "").strip()
+        if txt and not list(child):
+            out[child.tag] = txt
+    return out
+
+
+async def raw_search(
+    client: LawGoKrClient,
+    target: str,
+    *,
+    query: str = "",
+    display: int = 20,
+    extra_params: dict[str, Any] | None = None,
+    cache_ttl: int = 3600,
+) -> list[dict[str, str]]:
+    """임의 target에 대한 lawSearch.do 호출."""
+    params: dict[str, Any] = {"display": str(display)}
+    if query:
+        params["query"] = query
+    if extra_params:
+        params.update(extra_params)
+    call = LawApiCall(
+        target=target, path=LIST_PATH, params=params, cache_ttl=cache_ttl
+    )
+    body = await client.fetch(call)
+    if not body.strip():
+        return []
+    root = parse_xml(body)
+    meta = {
+        "target", "키워드", "section", "totalCnt", "page", "key",
+        "numOfRows", "resultCode", "resultMsg", "기관명",
+    }
+    return [_row_to_dict(ch) for ch in root if ch.tag not in meta and len(ch) > 0]
+
+
+async def raw_get(
+    client: LawGoKrClient,
+    target: str,
+    *,
+    id: str | None = None,
+    mst: str | None = None,
+    extra_params: dict[str, Any] | None = None,
+    cache_ttl: int = 24 * 3600,
+) -> str:
+    """임의 target에 대한 lawService.do 호출. raw XML 본문 반환."""
+    params: dict[str, Any] = {}
+    if mst is not None:
+        params["MST"] = str(mst)
+    if id is not None:
+        params["ID"] = str(id)
+    if extra_params:
+        params.update(extra_params)
+    if not params:
+        raise ValueError("raw_get requires at least one of id/mst/extra_params")
+    call = LawApiCall(
+        target=target, path=DETAIL_PATH, params=params, cache_ttl=cache_ttl
+    )
+    return await client.fetch(call)

src/kpaa/law_api/terms.py

@@ -0,0 +1,46 @@
+"""법령용어 (target=lstrm).
+
+라이브 검증 row 필드: 법령용어ID / 법령용어명 / 사전구분코드 / 법령종류코드 /
+법령용어상세링크 / 법령용어상세검색.
+
+detail은 trmSeqs 파라미터를 쓰며 ID가 콤마로 여러 개 결합되어 있을 수 있음.
+"""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import LSTRM
+from kpaa.law_api.parsers import child_text, parse_xml
+
+
+async def search_legal_terms(
+    client: LawGoKrClient, *, query: str, display: int = 20
+) -> list[dict[str, str]]:
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    body = await client.fetch(
+        LawApiCall(target=LSTRM.target, path=LIST_PATH,
+                   params={"query": query, "display": str(display)},
+                   cache_ttl=3600)
+    )
+    root = parse_xml(body)
+    return [
+        {
+            "term_id": child_text(el, "법령용어ID"),
+            "term": child_text(el, "법령용어명"),
+            "dict_kind_code": child_text(el, "사전구분코드"),
+            "law_kind_code": child_text(el, "법령종류코드"),
+            "detail_url": child_text(el, "법령용어상세링크"),
+        }
+        for el in root.findall(f".//{LSTRM.row_tag}")
+    ]
+
+
+async def get_legal_term_detail(client: LawGoKrClient, *, term_id: str) -> str:
+    """법령용어 상세 — `trmSeqs` 파라미터 사용 (콤마 결합 ID 허용)."""
+    return await client.fetch(
+        LawApiCall(target=LSTRM.target, path=DETAIL_PATH,
+                   params={"trmSeqs": str(term_id)}, cache_ttl=24 * 3600)
+    )
+
+
+__all__ = ["search_legal_terms", "get_legal_term_detail"]

src/kpaa/law_api/treaty.py

@@ -0,0 +1,43 @@
+"""조약 (target=trty)."""
+from __future__ import annotations
+
+from kpaa.law_api.client import DETAIL_PATH, LIST_PATH, LawApiCall, LawGoKrClient
+from kpaa.law_api.endpoints import TRTY
+from kpaa.law_api.parsers import child_text, parse_xml
+
+
+async def search_treaties(
+    client: LawGoKrClient, *, query: str, display: int = 20
+) -> list[dict[str, str]]:
+    if not 1 <= display <= 100:
+        raise ValueError("display must be in [1, 100]")
+    body = await client.fetch(
+        LawApiCall(target=TRTY.target, path=LIST_PATH,
+                   params={"query": query, "display": str(display)},
+                   cache_ttl=3600)
+    )
+    root = parse_xml(body)
+    return [
+        {
+            "treaty_id": child_text(el, "조약일련번호"),
+            "name": child_text(el, "조약명"),
+            "kind": child_text(el, "조약구분명"),
+            "treaty_no": child_text(el, "조약번호"),
+            "country_no": child_text(el, "국가번호"),
+            "signed_date": child_text(el, "서명일자"),
+            "effective_date": child_text(el, "발효일자"),
+            "gazette_date": child_text(el, "관보게제일자"),
+        }
+        for el in root.findall(f".//{TRTY.row_tag}")
+    ]
+
+
+async def get_treaty_text(client: LawGoKrClient, *, treaty_id: str) -> str:
+    return await client.fetch(
+        LawApiCall(target=TRTY.target, path=DETAIL_PATH,
+                   params={"ID": str(treaty_id)},
+                   cache_ttl=24 * 3600)
+    )
+
+
+__all__ = ["search_treaties", "get_treaty_text"]

src/kpaa/llm/__init__.py

@@ -0,0 +1,20 @@
+"""LLM 백엔드 추상화.
+
+두 백엔드를 지원하며 같은 `LLMBackend` Protocol 을 만족:
+
+- `llama_cpp_backend` — 로컬 노트북용. Gemma 4 E2B GGUF 임베드, GGUF 는 첫
+  호출 시 Hugging Face 에서 자동 다운로드되어 `platformdirs.user_cache_dir`
+  에 캐시. 별도 데몬·외부 서비스 의존 없음.
+
+- `zerogpu_backend` — HF Spaces 데모용. 같은 가중치(`google/gemma-4-E2B-it`)
+  를 transformers 로 로드, `@spaces.GPU` 데코레이터로 함수 단위 GPU 할당.
+
+`get_backend()` 가 환경(`SPACE_ID` 존재 → zerogpu, 그 외 → llama_cpp)을
+자동 감지. `KPAA_LLM_BACKEND` 환경변수로 강제 override 가능.
+"""
+from __future__ import annotations
+
+from kpaa.llm.base import ChatMessage, LLMBackend, LLMOptions
+from kpaa.llm.factory import get_backend
+
+__all__ = ["ChatMessage", "LLMBackend", "LLMOptions", "get_backend"]