structverify 0.3.0__py3-none-any.whl

structverify/detection/domain_classifier.py

@@ -0,0 +1,75 @@
+"""
+detection/domain_classifier.py — 도메인 자동 분류 (Step 3)
+
+입력 텍스트의 도메인을 판별하고 적절한 Domain Pack을 선택한다.
+
+[김예슬 - 2026-04-22]
+- DOMAIN_CLASSIFY_PROMPT: few-shot 예시 3개 포함한 프롬프트로 교체
+- classify_domain(): model_tier="light"(HCX-DASH-001)로 명시적 지정
+- _build_text_preview(): 블록 타입 고려한 미리보기 텍스트 구성
+- _load_domain_pack(): domain-packs/{domain}/prompts.yaml 로드 시도
+
+[김예슬 - 2026-04-23 v1]
+- SUPPORTED_DOMAINS 하드코딩 제거 → domain-packs/ 디렉토리 기반으로 변경
+
+[김예슬 - 2026-04-23 v1]
+- DomainRegistry 클래스 추가: 레지스트리 기반 도메인 관리
+  · 문제: LLM 자유 생성 시 같은 주제를 다른 이름으로 분류하는 파편화 발생
+    (예: real_estate / housing_market / property → 모두 같은 주제)
+  · 해결: 기존 등록 도메인 목록 + 설명을 LLM 프롬프트에 주입
+    → LLM이 기존 도메인 중 유사한 게 있으면 재사용, 없으면 신규 생성
+  · 신규 도메인 생성 시 레지스트리(registry.yaml)에 자동 저장
+- classify_domain() 반환값: str → tuple[str, str] (domain, description)
+  · domain: 도메인 키 (영문 소문자)
+  · description: 도메인 한국어 설명 (레지스트리에서 조회 또는 신규 생성)
+- DOMAIN_CLASSIFY_PROMPT: 기존 도메인 목록 동적 주입 방식으로 변경
+
+[참고] ReAct (Yao et al., ICLR 2023)
+  Agent의 첫 단계로 도메인을 판별하여 이후 전략을 결정하는 패턴
+"""
+from __future__ import annotations
+
+from structverify.core.schemas import SIRDocument
+from structverify.detection.domain.classify import _classify_domain_with_llm
+from structverify.detection.domain.registry import (
+    CONFIDENCE_THRESHOLD,
+    DEFAULT_SEED_DOMAINS,
+    DOMAIN_NAME_PATTERN,
+    DomainRegistry,
+)
+from structverify.detection.prompts_loader import load_domain_pack
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ── 메인 진입점 ──────────────────────────────────────────────────────────────
+async def classify_domain(
+    sir_doc: SIRDocument,
+    config: dict | None = None,
+) -> tuple[str, str]:
+    """
+    SIR 문서의 도메인을 LLM으로 분류한다.
+
+    반환값이 (domain, description) 튜플로 바뀐 이유:
+      - domain만 반환하면 나중에 설명을 다시 조회해야 함
+      - 한 번에 받아서 schema_inductor 등에서 도메인 힌트로 바로 활용 가능
+
+    분류 로직:
+      1) 레지스트리에서 기존 도메인 목록 + 설명 로드
+      2) LLM 프롬프트에 목록 주입 → 기존 재사용 or 신규 생성
+      3) 신규 도메인이면 레지스트리에 자동 저장
+      4) confidence 낮으면 "general" fallback
+
+    Args:
+        sir_doc: 분류할 SIR 문서
+        config: 설정 dict
+
+    Returns:
+        (domain, description) 튜플
+        예: ("agriculture", "농림수산식품 (농가, 경작면적, ...)")
+    """
+    domain, description = await _classify_domain_with_llm(sir_doc, config)
+    sir_doc.detected_domain = domain
+    load_domain_pack(domain, config)
+    return domain, description

structverify/detection/prompts/__init__.py

@@ -0,0 +1 @@
+"""detection/prompts — Step 3~5 LLM 프롬프트·JSON schema 상수."""

structverify/detection/prompts/candidate.py

@@ -0,0 +1,38 @@
+"""detection/prompts/candidate.py — Step 4 candidate scoring 프롬프트.
+
+candidate_scorer.py에서 분리 (문자열 move-only, 동작 변경 없음).
+"""
+from __future__ import annotations
+
+
+# TODO [김예슬]: 프롬프트 튜닝 — domain-packs의 few-shot 예시 주입
+#   - 도메인별 positive/negative 예시 2~3개씩 추가
+#   - "공식 통계와 연결 가능" 기준을 예시로 명확히 제시
+CANDIDATE_PROMPT = """당신은 수치 기반 팩트체크 시스템의 1차 후보 탐지기입니다.
+아래 문장이 "공식 통계나 구조화된 데이터로 검증할 만한 후보 문장"인지 판단하세요.
+
+판단 기준:
+1. 수치/비율/규모/시점/대상 중 일부가 드러나는가?
+2. 의견/감상/단순 이벤트 일정이 아니라 검증 가능한 사실 주장인가?
+3. 공식 통계 또는 공공 데이터와 연결될 가능성이 있는가?
+
+문장: "{sentence}"
+
+중요:
+- candidate_label이 true이면 candidate_score는 반드시 0.5 이상이어야 합니다.
+- candidate_label이 false이면 candidate_score는 반드시 0.5 미만이어야 합니다.
+- JSON 앞뒤에 설명 문장을 절대 붙이지 마세요.
+
+JSON으로만 답하세요:
+{{
+  "candidate_score": 0.0,
+  "candidate_label": false,
+  "reason": "짧은 근거",
+  "signals": {{
+    "has_quantity": false,
+    "has_time_expr": false,
+    "has_population": false,
+    "has_comparison_expr": false
+  }}
+}}
+"""

structverify/detection/prompts/claim_worthiness.py

@@ -0,0 +1,48 @@
+"""detection/prompts/claim_worthiness.py — Step 4 check-worthiness 프롬프트.
+
+claim_detector.py에서 분리 (문자열 move-only, 동작 변경 없음).
+
+[박재윤 - 2026-05-14] CHECK_WORTHY_PROMPT 개선
+[박재윤 - 2026-05-18] 검증 가능 기준 보강
+"""
+from __future__ import annotations
+
+
+# TODO [김예슬]: 프롬프트 튜닝
+#   - domain-packs/{domain}/prompts.yaml에서 도메인별 few-shot 예시 로드
+#   - positive 예시: 공식 통계로 검증 가능한 수치 주장 2~3개
+#   - negative 예시: 의견/감상/단순 이벤트 일정 2~3개
+#   - claim_type 분류 기준 명확화 (increase/decrease/scale/comparison/forecast)
+CHECK_WORTHY_PROMPT = """팩트체크 전문가로서 아래 문장이 공식 통계로 검증 가능한 수치 기반 주장인지 판별하세요.
+
+[검증 가능 기준]
+1. 정부/공공기관이 발표한 구체적 수치가 포함된 사실 주장
+   (변동률, 상승률, 하락률, 비율, 절대값, 증감폭 등 모두 포함)
+2. 단순 일정/발언 소개/감상이 아닌 사실 주장
+3. 수치가 *과거 또는 현재* 실측값 (예보/예상/전망/목표 아님)
+
+[검증 불가 기준 — is_check_worthy=false]
+- 예보/예상/전망/목표 수치: "예상 강수량 20mm", "목표 성장률 3%"
+- 순위 표현만: "34년 만에 최대", "역대 최고"
+- 단순 발언/의견: "전문가는 ~라고 말했다"
+- 외국 기관 발표 수치 (KOSIS 검증 불가): "미국 연준이 금리를 0.25% 올렸다"
+
+[검증 가능 예시]
+✓ "2024년 4월 출생아 수는 2만 171명이다" → true
+✓ "고용률이 전년 대비 1.2% 상승했다" → true
+✓ "서울 표준주택 공시가격 상승률은 6.8%다" → true
+✓ "동작구 공시가 상승률은 10.6%로 가장 높다" → true
+✓ "전국 표준단독주택 공시가격 상승률은 4.5%다" → true
+✗ "올해 강수량이 20mm로 예상된다" → false
+✗ "출생아 수가 34년 만에 최대를 기록했다" → false
+
+문장: "{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}}
+"""

structverify/detection/prompts/domain.py

@@ -0,0 +1,41 @@
+"""detection/prompts/domain.py — Step 3 도메인 분류 프롬프트.
+
+domain_classifier.py에서 분리 (문자열 move-only, 동작 변경 없음).
+
+[김예슬 - 2026-04-22] DOMAIN_CLASSIFY_PROMPT few-shot 예시
+[김예슬 - 2026-04-23] 기존 도메인 목록 동적 주입 방식
+"""
+from __future__ import annotations
+
+
+DOMAIN_CLASSIFY_PROMPT = """당신은 한국 통계/뉴스 도메인 분류 전문가입니다.
+아래 문서를 읽고, 가장 적합한 도메인을 선택하거나 새로 생성하세요.
+
+[현재 등록된 도메인 목록]
+{domain_list}
+
+[도메인 선택 규칙]
+1. 위 목록에서 문서 내용과 가장 잘 맞는 도메인이 있으면 그 도메인을 선택하세요.
+2. 목록에 적합한 도메인이 없을 때만 새 도메인을 만드세요.
+   - 영어 소문자와 언더스코어(_)만 사용 (예: real_estate, it_industry)
+   - 새 도메인 설명은 한국어로 간략히 작성
+3. 분류가 모호하거나 복합 도메인이면 "general"을 선택하세요.
+
+[예시]
+문서: "통계청에 따르면 지난해 농가 인구는 216만 명으로 전년 대비 3.2% 감소했다."
+→ {{"domain": "agriculture", "description": "농림수산식품 (농가, 경작면적, 수확량, 축산, 어업)", "is_new": false, "confidence": 0.95, "reason": "농가 인구 통계"}}
+
+문서: "수도권 아파트 평균 매매가가 8억을 돌파하며 역대 최고치를 기록했다."
+→ {{"domain": "real_estate", "description": "부동산 (아파트, 매매가, 전세, 분양)", "is_new": true, "confidence": 0.93, "reason": "부동산 가격 통계로 기존 목록에 없음"}}
+
+[분류할 문서]
+{text_preview}
+
+JSON으로만 답하세요:
+{{
+  "domain": "도메인명",
+  "description": "도메인 한국어 설명",
+  "is_new": true 또는 false,
+  "confidence": 0.0~1.0,
+  "reason": "한 줄 근거"
+}}"""