structverify 0.3.0__py3-none-any.whl

structverify/detection/candidate/llm.py

@@ -0,0 +1,51 @@
+"""detection/candidate/llm.py — candidate scoring Teacher LLM.
+
+candidate_scorer.py에서 분리 (로직 move-only).
+
+TODO [김예슬]: domain-packs/{domain}/prompts.yaml candidate 예시 주입
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from structverify.detection._config import candidate_llm_label_floor, model_tier_for
+from structverify.detection._llm import get_llm_client
+from structverify.detection.prompts.candidate import CANDIDATE_PROMPT
+from structverify.detection.prompts_loader import resolve_prompt_for_step
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+async def _score_candidate_llm(
+    sentence: str,
+    *,
+    config: dict,
+    threshold: float,
+    domain: str | None = None,
+) -> tuple[float, bool, str, dict[str, Any]]:
+    llm = get_llm_client(config)
+    base = CANDIDATE_PROMPT.format(sentence=sentence)
+    prompt = resolve_prompt_for_step(base, domain, config, step="candidate")
+    result = await llm.generate_json(
+        prompt=prompt,
+        system_prompt="팩트체크 candidate detector. JSON으로만 답하세요.",
+        model_tier=model_tier_for(config, "candidate_score"),
+    )
+    # score = float(result.get("candidate_score", 0.0))
+    # label = bool(result.get("candidate_label", score >= threshold))
+    # signals = result.get("signals", {}) or {}
+    # signals["reason"] = result.get("reason")
+    # return score, label, "teacher_llm", signals
+    score = float(result.get("candidate_score", 0.0) or 0.0)
+    label = bool(result.get("candidate_label", score >= threshold))
+
+    # LLM이 label=true인데 score를 0으로 주는 경우 방어
+    if label and score < threshold:
+        score = max(score, candidate_llm_label_floor(config))
+
+    signals = result.get("signals", {}) or {}
+    signals["reason"] = result.get("reason")
+    signals["raw_llm_result"] = result
+
+    return score, label, "teacher_llm", signals

structverify/detection/candidate_scorer.py

@@ -0,0 +1,81 @@
+"""
+detection/candidate_scorer.py — 문장 단위 검증 후보 점수화
+
+[김예슬]
+- Teacher LLM 기반 0~1 점수화 로직 담당
+- heuristic fallback은 운영 안정성을 위한 보조 수단
+- 학습 데이터 충분 누적 후 소형 분류 모델(LoRA fine-tuned)로 교체 계획
+
+[설계 원칙]
+- regex/rule만으로 후보를 결정하지 않는다.
+- surface signal + teacher LLM + weak supervision 규칙을 결합할 수 있는 인터페이스 제공.
+- 현재 버전: "teacher LLM + heuristic fallback" 구조.
+- 이후 작은 classifier를 붙일 때 이 파일만 교체하면 된다.
+
+[LLM 학습 계획]
+  Phase 1: Teacher LLM (HCX-DASH-001)이 직접 판단 → 결과를 학습 샘플로 저장
+  Phase 2: Step 0 합성 데이터 + 운영 피드백 누적 → LoRA fine-tuning
+  Phase 3: 학습된 경량 모델로 교체 (비용 절감 + 속도 향상)
+
+출력
+- candidate_score: 0~1
+- candidate_label: bool
+- candidate_source: 점수 출처
+- candidate_signals: 분석용 signal
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from structverify.detection._config import candidate_detection_config
+from structverify.detection.candidate.heuristic import _score_candidate_heuristic
+from structverify.detection.candidate.llm import _score_candidate_llm
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+async def score_candidate(
+    sentence: str,
+    config: dict | None = None,
+    context: dict[str, Any] | None = None,
+) -> tuple[float, bool, str, dict[str, Any]]:
+    """
+    문장 후보 점수 계산.
+
+    현재 로직
+    1) teacher LLM 시도 (HCX-DASH-001 경량 모델)
+    2) 실패 시 heuristic fallback
+
+    TODO [김예슬]: 도메인 컨텍스트 활용
+      - context["domain"]을 프롬프트에 주입하여 도메인별 판단 기준 적용
+      - domain-packs/{domain}/prompts.yaml의 candidate 예시 주입
+
+    TODO [김예슬]: 학습 데이터 수집 로직 추가
+      - teacher LLM 판단 결과를 DB에 저장 (sample_builder.py 연동)
+      - 나중에 LoRA fine-tuning에 활용
+
+    TODO [김예슬]: 소형 분류 모델 교체 로직 (Phase 3)
+      - 학습된 adapter 경로 확인 → 있으면 PEFT 모델 추론
+      - adapter_path = config.get("adaptation", {}).get("adapter_path")
+      - if adapter_path: return _score_with_trained_model(sentence, adapter_path)
+    """
+    config = config or {}
+    cd_cfg = candidate_detection_config(config)
+    use_llm = cd_cfg.get("teacher_llm_fallback", True)
+    threshold = float(cd_cfg.get("threshold", 0.65))
+    domain = (context or {}).get("domain")
+
+    if use_llm:
+        try:
+            return await _score_candidate_llm(
+                sentence,
+                config=config,
+                threshold=threshold,
+                domain=domain,
+            )
+        except Exception as e:
+            logger.warning(f"candidate LLM 판별 실패 — heuristic fallback 사용: {e}")
+
+    # fallback: LLM 실패 시만 사용
+    return _score_candidate_heuristic(sentence, threshold=threshold)

structverify/detection/claim_detector.py

@@ -0,0 +1,164 @@
+"""
+detection/claim_detector.py — 검증 가능 주장 탐지 (Step 4)
+
+[김예슬]
+- check-worthiness 프롬프트 설계 및 튜닝 담당
+- candidate scoring → LLM 2차 판별 구조 담당
+- domain-packs 기반 도메인별 프롬프트 주입
+
+[변경 요약]
+- 기존: has_numeric=True 문장만 필터 → LLM check-worthiness
+- 변경: LLM/학습 기반 sentence candidate scoring → 상위 후보만 LLM check-worthiness
+
+[설계 원칙]
+- Regex 필터(has_numeric 등) 로 1차 후보를 결정하지 않습니다.
+- candidate_scorer.py의 Teacher LLM이 0~1 점수를 계산하고,
+  threshold 이상인 문장만 이 check-worthiness 단계로 전달됩니다.
+- 즉, Step 4를 다음 두 단계로 분리합니다:
+  1) Sentence Candidate Detection (candidate_scorer.py — Teacher LLM)
+  2) Claim Detection / Check-Worthiness (LLM 중량 모델)
+
+[박재윤 - 2026-05-14]: CHECK_WORTHY_PROMPT 개선
+   · 예보/예상/전망 수치 → false 기준 명시
+   · 순위 표현 단독 → false 기준 명시
+   · 외국 기관 발표 수치 → false 기준 명시
+   · positive/negative 예시 추가
+
+[박재윤 - 2026-05-18]: CHECK_WORTHY_PROMPT 검증 가능 기준 보강
+   · 기준 1번: "공식 통계 연결" → "정부/공공기관 발표 수치" 로 구체화
+   · 공시가격 변동률 등 부동산 수치 positive 예시 추가
+"""
+from __future__ import annotations
+
+import asyncio  # 병렬처리
+
+from structverify.core.schemas import Claim, SIRDocument, SourceOffset
+from structverify.detection.candidate_scorer import score_candidate
+from structverify.detection._config import candidate_detection_config, claim_min_confidence
+from structverify.detection._llm import get_llm_client
+from structverify.detection.claims.worthiness import _check_worthiness
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+async def detect_claims(
+    sir_doc: SIRDocument,
+    config: dict | None = None,
+) -> list[Claim]:
+    """
+    SIR Tree에서 검증 가능한 주장 탐지.
+
+    단계
+    1) LLM 기반 sentence candidate scoring
+    2) high-score 문장만 check-worthiness 판별 (LLM 중량 모델)
+    3) threshold 이상 claim만 Claim 객체로 변환
+
+    TODO [김예슬]: claim_type 분류 정확도 개선
+      - "increase": 증가/상승/올랐다
+      - "decrease": 감소/하락/내렸다
+      - "scale": 규모/비율/수준 언급
+      - "comparison": A가 B보다 높다/낮다
+      - "forecast": 전망/예상/목표
+    """
+    config = config or {}
+    llm = get_llm_client(config)
+
+    cd_cfg = candidate_detection_config(config)
+    candidate_threshold = float(cd_cfg.get("threshold", 0.65))
+    min_conf = claim_min_confidence(config)
+
+    concurrency = int(cd_cfg.get("concurrency", candidate_detection_config(config).get("concurrency", 4)))
+    sem = asyncio.Semaphore(concurrency)
+
+    sentence_items = []
+    for block in sir_doc.blocks:
+        for sent in block.sentences:
+            sentence_items.append((block, sent))
+
+    async def score_one(block, sent):
+        async with sem:
+            score, label, source, signals = await score_candidate(
+                sentence=sent.text,
+                config=config,
+                context={
+                    "block_id": block.block_id,
+                    "domain": sir_doc.detected_domain,
+                },
+            )
+            return block, sent, score, label, source, signals
+
+    # 1) candidate scoring 병렬 처리
+    score_results = await asyncio.gather(
+        *[score_one(block, sent) for block, sent in sentence_items],
+        return_exceptions=True,
+    )
+
+    candidates = []
+
+    for result in score_results:
+        if isinstance(result, Exception):
+            logger.warning(f"candidate scoring 실패: {result}")
+            continue
+
+        block, sent, score, label, source, signals = result
+
+        sent.candidate_score = score
+        sent.candidate_label = label
+        sent.candidate_source = source
+        sent.candidate_signals = signals
+
+        if score >= candidate_threshold and label:
+            candidates.append((block, sent))
+
+    logger.info(f"candidate 문장: {len(candidates)}건")
+
+    domain = sir_doc.detected_domain
+
+    async def check_one(block, sent):
+        async with sem:
+            cw_score, claim_type, canonical_type = await _check_worthiness(
+                llm,
+                sent.text,
+                config=config,
+                domain=domain,
+            )
+            return block, sent, cw_score, claim_type, canonical_type
+
+    # 2) check-worthiness도 병렬 처리
+    check_results = await asyncio.gather(
+        *[check_one(block, sent) for block, sent in candidates],
+        return_exceptions=True,
+    )
+
+    claims: list[Claim] = []
+
+    for result in check_results:
+        if isinstance(result, Exception):
+            logger.warning(f"check-worthiness 실패: {result}")
+            continue
+
+        block, sent, cw_score, claim_type, canonical_type = result
+
+        if cw_score < min_conf:
+            continue
+
+        claims.append(
+            Claim(
+                doc_id=sir_doc.doc_id,
+                block_id=block.block_id,
+                sent_id=sent.sent_id,
+                claim_text=sent.text,
+                claim_type=claim_type,
+                canonical_type=canonical_type,
+                check_worthy_score=cw_score,
+                graph_anchor_id=sent.graph_anchor_id,
+                source_offset=SourceOffset(
+                    char_start=sent.char_offset_start,
+                    char_end=sent.char_offset_end,
+                    page=block.source_offset.page if block.source_offset else None,
+                ),
+            )
+        )
+    logger.info(f"검증 가능 주장: {len(claims)}건")
+    return claims

structverify/detection/claims/__init__.py

@@ -0,0 +1 @@
+"""detection/claims — Step 4 check-worthiness·claim 조립."""

structverify/detection/claims/worthiness.py

@@ -0,0 +1,142 @@
+"""detection/claims/worthiness.py — check-worthiness LLM 판별.
+
+claim_detector.py에서 분리 (로직 move-only).
+
+TODO [김예슬]: 오류 응답 처리 강화 (재시도, score 클램핑)
+"""
+from __future__ import annotations
+
+from structverify.core.schemas import ClaimType
+from structverify.detection.prompts.claim_worthiness import CHECK_WORTHY_PROMPT
+from structverify.detection._config import claim_worthy_score_floor, model_tier_for
+from structverify.detection.prompts_loader import resolve_step_prompt
+from structverify.utils.llm_client import LLMClient
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# 연결된 소스에 적응하는 check-worthiness 프롬프트 (KOSIS 가정 제거).
+# config["_source_profile"] 가 있을 때 사용 — "정부 통계?" 대신 "이 소스로 검증되나?".
+_SOURCE_AWARE_PROMPT = """아래 문장이 '연결된 검증 데이터'로 대조 가능한 수치 기반 사실 주장인지 판별하세요.
+
+[연결된 검증 데이터]
+{source_desc}
+이 데이터가 다루는 지표(일부): {indicators}
+
+[검증 가능 기준 — is_check_worthy=true]
+1. 위 데이터의 지표와 관련된, 구체적 수치를 담은 *과거/현재 실측* 사실 주장
+   (절대값·비율·증감·금액·개수·수량 등 모두 포함)
+2. 단순 일정/발언 소개/감상이 아닌, 수치로 검증 가능한 사실 주장
+
+[검증 불가 기준 — is_check_worthy=false]
+- 예보/예상/전망/목표 수치 ("목표 성장률 3%")
+- 순위 표현만 ("역대 최대", "1위")
+- 단순 발언/의견 ("전문가는 ~라고 말했다")
+- 위 데이터가 다루지 않는 주제의 수치
+
+문장: "{sentence}"
+중요:
+- is_check_worthy=true이면 score는 반드시 0.5 이상
+- is_check_worthy=false이면 score는 반드시 0.5 미만
+- JSON만 출력. 설명 금지.
+JSON:
+{{"is_check_worthy": false, "score": 0.0, "claim_type": null}}"""
+
+
+# 에이전틱(text-to-SQL) 소스용 — 원시 DB라 SQL 집계로 임의 지표를 만들 수 있으므로
+# "제안 지표에 없는 주제"라고 쉽게 거부하지 않는다(지역·부문·연도별 분해 등 포함).
+_AGENTIC_SOURCE_PROMPT = """아래 문장이 '연결된 원시 데이터베이스'로 SQL 집계를 통해 대조 가능한 수치 기반 사실 주장인지 판별하세요.
+
+[연결된 검증 데이터]
+{source_desc}
+이 원시 데이터로 SQL 집계(합계·평균·건수, 지역별·부문별·세그먼트별·연도별 분해 등)를 자유롭게 만들 수 있습니다.
+참고 지표(일부): {indicators}
+
+[검증 가능 기준 — is_check_worthy=true]
+1. 위 데이터의 도메인과 관련된, 구체적 수치를 담은 과거/현재 실측 주장
+   (절대값·비율·증감·금액·개수·수량, 그리고 지역별·부문별·연도별 *분해*까지 모두 포함)
+2. 숫자를 동반한 비교/순위 주장도 그 숫자가 검증 대상이면 true
+   (예: "유럽이 4,369억 달러로 1위" → 4,369억이 검증 대상이므로 true)
+
+[검증 불가 기준 — is_check_worthy=false]
+- 예보/예상/전망/목표 수치 ("목표 성장률 3%")
+- *숫자 없는* 순수 순위·감상 ("역대 최대", "업계 최고")
+- 단순 발언/의견
+- 데이터 도메인과 전혀 무관한 주제의 수치
+
+문장: "{sentence}"
+중요:
+- is_check_worthy=true이면 score는 반드시 0.5 이상
+- is_check_worthy=false이면 score는 반드시 0.5 미만
+- JSON만 출력. 설명 금지.
+JSON:
+{{"is_check_worthy": false, "score": 0.0, "claim_type": null}}"""
+
+
+def _resolve_worthy_prompt(sentence: str, config: dict | None, domain: str | None) -> str:
+    """소스 프로파일이 있으면 소스-인지 프롬프트, 없으면 기존(도메인팩) 프롬프트.
+
+    에이전틱 소스면 SQL로 임의 집계가 가능하므로 더 관대한 프롬프트를 쓴다.
+    """
+    sp = (config or {}).get("_source_profile")
+    if sp and sp.get("indicators"):
+        _agentic = bool((sp.get("retrieval_plan") or {}).get("agentic"))
+        _tmpl = _AGENTIC_SOURCE_PROMPT if _agentic else _SOURCE_AWARE_PROMPT
+        return _tmpl.format(
+            sentence=sentence,
+            source_desc=sp.get("description") or "연결된 회사/사용자 데이터",
+            indicators=", ".join(sp["indicators"][:50]),   # headline 지표 포함되게 상한↑
+        )
+    return resolve_step_prompt(
+        CHECK_WORTHY_PROMPT, {"sentence": sentence},
+        domain, config, step="claim_worthiness",
+    )
+
+
+async def _check_worthiness(
+    llm: LLMClient,
+    sentence: str,
+    *,
+    config: dict | None = None,
+    domain: str | None = None,
+) -> tuple[float, str | None, ClaimType | None]:
+    """
+    LLM 기반 check-worthiness 판별 (2차 정밀 판별).
+    candidate detection 이후 상위 후보에만 적용.
+    """
+    try:
+        # 연결된 소스가 있으면 소스-인지 프롬프트, 없으면 기존(도메인팩) 프롬프트.
+        prompt = _resolve_worthy_prompt(sentence, config, domain)
+        r = await llm.generate_json(
+            prompt,
+            system_prompt="팩트체크 check-worthiness classifier. 반드시 JSON만 출력하세요.",
+            model_tier=model_tier_for(config, "claim_worthiness"),
+        )
+
+        is_check_worthy = bool(r.get("is_check_worthy", False))
+        score = float(r.get("score", 0.0) or 0.0)
+
+        # true인데 score=0으로 오는 문제 방어
+        if is_check_worthy and score <= 0.0:
+            score = claim_worthy_score_floor(config)
+
+        score = max(0.0, min(score, 1.0))
+
+        if not is_check_worthy:
+            return 0.0, None, None
+        raw_type = r.get("claim_type")
+        canonical = r.get("canonical_type")
+
+        claim_type = raw_type if raw_type and raw_type != "null" else None
+
+        try:
+            canonical_type = ClaimType(canonical) if canonical else None
+        except ValueError:
+            canonical_type = None
+
+        return score, claim_type, canonical_type
+
+    except Exception as e:
+        logger.error(f"check-worthiness 실패: {e}")
+        return 0.0, None, None

structverify/detection/domain/__init__.py

@@ -0,0 +1 @@
+"""detection/domain — Step 3 도메인 분류 (registry·preview·LLM)."""

structverify/detection/domain/classify.py

@@ -0,0 +1,84 @@
+"""detection/domain/classify.py — 도메인 LLM 분류 실행.
+
+domain_classifier.py에서 분리 (로직 move-only, 동작 변경 없음).
+"""
+from __future__ import annotations
+
+from structverify.core.schemas import SIRDocument
+from structverify.detection.domain.preview import _build_text_preview
+from structverify.detection.domain.registry import (
+    DEFAULT_SEED_DOMAINS,
+    DOMAIN_NAME_PATTERN,
+    DomainRegistry,
+)
+from structverify.detection._config import (
+    domain_confidence_threshold,
+    domain_registry_path,
+    model_tier_for,
+)
+from structverify.detection._llm import get_llm_client
+from structverify.detection.prompts.domain import DOMAIN_CLASSIFY_PROMPT
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+async def _classify_domain_with_llm(
+    sir_doc: SIRDocument,
+    config: dict | None = None,
+) -> tuple[str, str]:
+    """레지스트리 + LLM으로 (domain, description) 반환."""
+    config = config or {}
+    registry_path = domain_registry_path(config)
+    registry = DomainRegistry(registry_path)
+
+    preview = _build_text_preview(sir_doc)
+    domain_list_str = registry.format_for_prompt()
+    llm = get_llm_client(config)
+
+    try:
+        result = await llm.generate_json(
+            prompt=DOMAIN_CLASSIFY_PROMPT.format(
+                domain_list=domain_list_str,
+                text_preview=preview,
+            ),
+            system_prompt="도메인 분류 전문가. JSON으로만 답하세요.",
+            model_tier=model_tier_for(config, "domain_classify", default="light"),
+        )
+
+        raw_domain    = result.get("domain", "general")
+        description   = result.get("description", "")
+        is_new        = bool(result.get("is_new", False))
+        confidence    = float(result.get("confidence", 0.0))
+        reason        = result.get("reason", "")
+
+        # 도메인 형식 검증
+        if not DOMAIN_NAME_PATTERN.match(raw_domain):
+            logger.warning(f"도메인 형식 오류 '{raw_domain}' → general")
+            raw_domain, description = "general", DEFAULT_SEED_DOMAINS["general"]
+
+        # confidence 낮으면 general
+        if confidence < domain_confidence_threshold(config):
+            logger.warning(f"confidence 낮음 ({confidence:.2f}) → general")
+            raw_domain, description = "general", DEFAULT_SEED_DOMAINS["general"]
+
+        # 신규 도메인이면 레지스트리에 저장
+        if is_new and raw_domain != "general":
+            registry.register(raw_domain, description)
+
+        # 기존 도메인이면 레지스트리의 공식 설명 사용 (LLM 설명이 다를 수 있음)
+        if not is_new:
+            registered = registry.load()
+            description = registered.get(raw_domain, description)
+
+        domain = raw_domain
+        logger.info(
+            f"도메인 분류: {domain} ({'신규' if is_new else '기존'}) "
+            f"confidence={confidence:.2f}, reason={reason}"
+        )
+
+    except Exception as e:
+        logger.error(f"도메인 분류 실패: {e}")
+        domain, description = "general", DEFAULT_SEED_DOMAINS["general"]
+
+    return domain, description

structverify/detection/domain/preview.py

@@ -0,0 +1,36 @@
+"""detection/domain/preview.py — SIR 문서 미리보기 텍스트.
+
+domain_classifier.py에서 분리 (로직 move-only).
+
+[김예슬 - 2026-04-22] _build_text_preview — 블록 타입 고려
+"""
+from __future__ import annotations
+
+from structverify.core.schemas import SIRDocument
+
+
+def _build_text_preview(sir_doc: SIRDocument, max_chars: int = 600) -> str:
+    """
+    SIR 문서에서 분류에 유용한 미리보기 텍스트를 구성한다.
+    heading 블록 우선, 이후 paragraph 추가. table/list 제외.
+    """
+    from structverify.core.schemas import BlockType
+
+    parts: list[str] = []
+    total = 0
+
+    for block in sir_doc.blocks:
+        if block.type == BlockType.HEADING and block.content:
+            parts.append(block.content.strip())
+            total += len(block.content)
+            if total >= max_chars:
+                break
+
+    for block in sir_doc.blocks:
+        if block.type == BlockType.PARAGRAPH and block.content:
+            parts.append(block.content.strip())
+            total += len(block.content)
+            if total >= max_chars:
+                break
+
+    return " ".join(parts)[:max_chars]

structverify/detection/domain/registry.py

@@ -0,0 +1,99 @@
+"""detection/domain/registry.py — 도메인 레지스트리 (registry.yaml).
+
+domain_classifier.py에서 분리 (로직 move-only, 동작 변경 없음).
+
+[김예슬 - 2026-04-23] DomainRegistry — LLM 도메인 파편화 방지
+"""
+from __future__ import annotations
+
+import os
+import re
+
+import yaml
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# [김예슬 - 2026-04-23] DomainRegistry — LLM 도메인 파편화 방지
+# confidence_threshold 기본값 → detection/config.yaml (domain.confidence_threshold)
+CONFIDENCE_THRESHOLD = 0.6  # re-export 호환; 런타임은 config.domain_confidence_threshold()
+DOMAIN_NAME_PATTERN = re.compile(r"^[a-z][a-z_]{0,29}$")
+
+# 기본 시드 도메인 — 레지스트리 파일이 없을 때 초기값으로 사용
+DEFAULT_SEED_DOMAINS: dict[str, str] = {
+    "agriculture":  "농림수산식품 (농가, 경작면적, 수확량, 축산, 어업)",
+    "economy":      "경제/경기 (GDP, 성장률, 소비, 수출입, 물가, 산업생산)",
+    "finance":      "금융/증권 (금리, 환율, 주가, 대출, 가계부채, 보험)",
+    "population":   "인구/가구 (출생, 사망, 혼인, 고령화, 인구구조)",
+    "employment":   "고용/노동/임금 (취업률, 실업률, 임금, 근로시간)",
+    "healthcare":   "보건/의료 (질병, 의료기관, 사망률, 건강보험)",
+    "education":    "교육 (학생, 학교, 교육비, 진학률, 입시)",
+    "policy":       "정책/행정 (예산, 법률, 복지, 지원금, 정부)",
+    "environment":  "환경/에너지 (기후, 탄소, 재생에너지, 환경오염)",
+    "general":      "분류 불가 또는 복합 도메인",
+}
+
+
+class DomainRegistry:
+    """
+    도메인 레지스트리 — {domain: description} 매핑을 파일로 영속 관리.
+
+    registry.yaml 구조:
+        agriculture: "농림수산식품 (농가, 경작면적, ...)"
+        economy: "경제/경기 (GDP, 성장률, ...)"
+        real_estate: "부동산 (아파트, 매매가, ...)"   ← 런타임에 추가됨
+
+    사용법:
+        registry = DomainRegistry("domain-packs/registry.yaml")
+        domains = registry.load()           # {domain: description} 반환
+        registry.register("real_estate", "부동산 관련 통계")
+    """
+
+    def __init__(self, registry_path: str = "domain-packs/registry.yaml"):
+        self.registry_path = registry_path
+
+    def load(self) -> dict[str, str]:
+        """
+        레지스트리 파일 로드.
+        파일이 없으면 DEFAULT_SEED_DOMAINS를 파일로 저장 후 반환.
+        """
+        if not os.path.exists(self.registry_path):
+            logger.info(f"레지스트리 없음 → 시드 도메인으로 초기화: {self.registry_path}")
+            self._save(DEFAULT_SEED_DOMAINS)
+            return dict(DEFAULT_SEED_DOMAINS)
+
+        try:
+            with open(self.registry_path, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+            return {k: str(v) for k, v in data.items()}
+        except Exception as e:
+            logger.warning(f"레지스트리 로드 실패 → 시드 사용: {e}")
+            return dict(DEFAULT_SEED_DOMAINS)
+
+    def register(self, domain: str, description: str) -> None:
+        """
+        새 도메인을 레지스트리에 추가하고 파일로 저장.
+        이미 있으면 무시.
+        """
+        current = self.load()
+        if domain in current:
+            return
+
+        current[domain] = description
+        self._save(current)
+        logger.info(f"새 도메인 등록: {domain} — {description}")
+
+    def _save(self, data: dict[str, str]) -> None:
+        os.makedirs(os.path.dirname(self.registry_path) or ".", exist_ok=True)
+        with open(self.registry_path, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, allow_unicode=True, sort_keys=True)
+
+    def format_for_prompt(self) -> str:
+        """
+        프롬프트 주입용 문자열 생성.
+        예: "- agriculture: 농림수산식품 (농가, 경작면적, ...)"
+        """
+        domains = self.load()
+        lines = [f"- {k}: {v}" for k, v in sorted(domains.items())]
+        return "\n".join(lines)