structverify 0.3.0__py3-none-any.whl

structverify/core/schemas.py

@@ -0,0 +1,362 @@
+# [2026-05-14 | 이수민] memory/v1: working memory 도메인 가드용 필드 추가
+#   - Evidence.category_path: KOSIS catalog의 카테고리 경로 (예: "인구 > 출생")
+#   - MismatchType.DOMAIN_MISMATCH: stat_id 카테고리가 문서 도메인과 어긋난 경우
+"""
+core/schemas.py — v3 전체 파이프라인 데이터 모델
+
+v2 변경점
+- Sentence에 regex 중심 has_numeric 대신
+  has_numeric_surface + candidate_score/candidate_label 추가
+- claim candidate detection을 독립 태스크로 다루기 위한 필드 추가
+- 기존 has_numeric는 하위 호환을 위해 제거하지 않고 property처럼 대체 가능하게 설계
+
+설계 의도
+- surface rule은 보조 신호로만 사용
+- 실제 검증 후보 여부는 candidate_score / candidate_label이 담당
+
+v3 변경점 [김예슬]
+- GraphEdgeType에 4개 추가
+- COMPARE 엣지: indicator가 같은 Claim 쌍을 전부 연결
+"쉬었음인구"를 indicator로 가진 C1과 C2가 COMPARE로 연결되면,
+"2.6배" 검증 시 MetricNode 2-hop으로 C1+C2를 함께 KOSIS에 조회해서 비율 계산이 가능
+- 문맥 엣지: sir_doc이 넘어오면 extract_context_edges()를 호출해서 NEXT_SENT/IN_BLOCK/IN_DOC를 GraphEdge로 변환해 반환값에 포함
+
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+# ── Enums ─────────────────────────────────────────────────────
+
+class SourceType(str, Enum):
+    URL = "url"
+    PDF = "pdf"
+    DOCX = "docx"
+    TEXT = "text"
+
+
+class BlockType(str, Enum):
+    PARAGRAPH = "paragraph"
+    TABLE = "table"
+    HEADING = "heading"
+    LIST = "list"
+
+
+class ClaimType(str, Enum):
+    """주장 유형 — ClaimBuster 계열 분류 확장"""
+    INCREASE = "increase"
+    DECREASE = "decrease"
+    SCALE = "scale"
+    COMPARISON = "comparison"
+    FORECAST = "forecast"
+    # [2026-05-21] aggregation claim 지원 — "최근 N년 평균/총합" 류
+    AGGREGATION = "aggregation"
+
+
+class VerdictType(str, Enum):
+    """판정 결과 — FEVER 3단계 매핑"""
+    MATCH = "match"
+    MISMATCH = "mismatch"
+    UNVERIFIABLE = "unverifiable"
+
+
+class MismatchType(str, Enum):
+    VALUE = "value"
+    TIME_PERIOD = "time_period"
+    POPULATION = "population"
+    EXAGGERATION = "exaggeration"
+    # [이수민 2026-05-14] working memory 도메인 가드용
+    DOMAIN_MISMATCH = "domain_mismatch"  # stat_id 카테고리가 문서 도메인과 어긋남
+
+
+class FeedbackType(str, Enum):
+    HUMAN_REVIEW = "human_review"
+    LOW_CONFIDENCE = "low_confidence"
+    FAILURE = "failure"
+    DRIFT = "drift"
+
+
+class GraphNodeType(str, Enum):
+    CLAIM = "claim"
+    ENTITY = "entity"
+    METRIC = "metric"
+    TIME = "time"
+    EVIDENCE = "evidence"
+    SOURCE = "source"
+    # ── 멀티홉 시간 그래프용 (document_graph.py) ──────────────────────────
+    DOCUMENT = "document"            # 문서 메타 (anchor_year property 보유)
+    SENTENCE = "sentence"            # 문장 (REFERS_TO 타겟, sir_doc 호환)
+    TEMPORAL_EXPR = "temporal_expr"  # "작년", "9월", "재작년 같은 기간"
+    RESOLVED_TIME = "resolved_time"  # 절대 시점 (2023, 2024-09 등)
+
+
+class GraphEdgeType(str, Enum):
+    MEASURED_AT = "measured_at"
+    BELONGS_TO = "belongs_to"
+    VERIFIED_BY = "verified_by"
+    SOURCED_FROM = "sourced_from"
+    CONTRADICTS = "contradicts"
+    SUPPORTS = "supports"
+    # GraphRAG 문맥 엣지 (sir_builder.extract_context_edges → graph_builder)
+    NEXT_SENT = "next_sent"    # 문장 → 다음 문장 (문맥 흐름)
+    IN_BLOCK  = "in_block"     # 문장 → 소속 문단
+    IN_DOC    = "in_doc"       # 문단 → 소속 문서
+    # 복합 주장 검증용 (같은 지표를 공유하는 Claim 간)
+    COMPARE   = "compare"      # C1 ↔ C2 (2.6배 같은 파생 주장 검증)
+    # ── 멀티홉 시간 그래프용 (document_graph.py) ──────────────────────────
+    HAS_TEMPORAL = "has_temporal"  # Sentence/Claim → TemporalExpr
+    RELATIVE_TO  = "relative_to"   # TemporalExpr → Document (anchor 의존)
+    RESOLVES_TO  = "resolves_to"   # TemporalExpr → ResolvedTime
+    REFERS_TO    = "refers_to"     # TemporalExpr → 다른 Sentence (coref)
+
+
+# ── SIR Tree ─────────────────────────────────────────────────
+
+class SourceOffset(BaseModel):
+    """원문 역추적용 절대 위치 정보"""
+    page: int | None = None
+    char_start: int = 0
+    char_end: int = 0
+
+
+class Sentence(BaseModel):
+    """
+    개별 문장 + candidate detection 결과
+
+    필드 설명
+    - has_numeric_surface:
+        정규식 기반의 약한 표면 신호. 최종 candidate 판단이 아님.
+    - candidate_score:
+        검증 후보 점수. 0~1 범위.
+    - candidate_label:
+        threshold를 적용한 최종 후보 여부.
+    - candidate_source:
+        점수의 출처 ("surface_rule", "weak_supervision", "teacher_llm" 등)
+    - candidate_signals:
+        디버깅/분석용 보조 신호
+    """
+    sent_id: str
+    text: str
+    char_offset_start: int = 0
+    char_offset_end: int = 0
+
+    # 기존 regex 탐지는 하위 호환을 위해 surface signal로 격하
+    has_numeric_surface: bool = False
+
+    # 논문형 candidate detection 결과
+    candidate_score: float = 0.0
+    candidate_label: bool = False
+    candidate_source: str | None = None
+    candidate_signals: dict[str, Any] = Field(default_factory=dict)
+
+    graph_anchor_id: str | None = None
+
+    @property
+    def has_numeric(self) -> bool:
+        """
+        하위 호환용 property.
+        기존 코드가 s.has_numeric를 참조하더라도 surface signal로 동작하게 한다.
+        """
+        return self.has_numeric_surface
+
+
+class SIRBlock(BaseModel):
+    block_id: str
+    type: BlockType
+    level: int | None = None
+    content: str | None = None
+    sentences: list[Sentence] = Field(default_factory=list)
+    headers: list[str] | None = None
+    rows: list[list[str]] | None = None
+    entity_refs: list[str] = Field(default_factory=list)
+    event_refs: list[str] = Field(default_factory=list)
+    graph_anchor_ids: list[str] = Field(default_factory=list)
+    source_offset: SourceOffset = Field(default_factory=SourceOffset)
+
+
+class SIRDocument(BaseModel):
+    doc_id: UUID = Field(default_factory=uuid4)
+    source_type: SourceType
+    source_uri: str | None = None
+    extracted_at: datetime = Field(default_factory=datetime.utcnow)
+    blocks: list[SIRBlock] = Field(default_factory=list)
+    detected_domain: str | None = None
+    # [2026-05-21] URL/PDF 입력 시 추출된 본문 텍스트. 프론트 "원문" 패널에서
+    # source_data 대체로 사용. text 입력은 source_data == raw_text이라 중복이지만
+    # 일관성 유지를 위해 항상 채움.
+    raw_text: str | None = None
+
+
+# ── Claim ────────────────────────────────────────────────────
+
+class ClaimSchema(BaseModel):
+    indicator: str | None = None
+    time_period: str | None = None
+    unit: str | None = None
+    population: str | None = None
+    value: float | None = None
+    comparison_type: ClaimType | None = None
+    source_reference: str | None = None
+    graph_schema_candidates: list[dict[str, str]] = Field(default_factory=list)
+    parent_path: str | None = None  # "노동 > 청년 > 쉬었음 인구" (계층 카테고리)
+    is_approximate: bool = False    # "안팎" 인지
+    modifier: str | None = None     # 근사 표현 원문
+    prev_value: float | None = None
+    prev_time_period: str | None = None
+    prev_phrase: str | None = None
+
+    # [2026-05-21] schema_inductor가 한 claim → N sub-claim 분기 시,
+    # 각 sub-claim의 *검증 역할*을 명시. planner LLM이 같은 claim_text를 보고
+    # 둘 다 동일 plan_type으로 잘못 분류하는 걸 방지하는 1차 신호.
+    #   - "base"             : 단일 값 단순 확인 (예: 출생아 수 = 20717명)
+    #                          → plan_type=absolute, 시퀀스: catalog → fetch → finish
+    #   - "derived_rate"     : 비율/증가율/감소율 계산 (단위 %, ~증가율 류)
+    #                          → plan_type=growth_rate
+    #   - "derived_difference": 절대 차이/변화량 (단위 절대단위, 차이값)
+    #                          → plan_type=difference
+    #   - "aggregation"      : 다년/다기간 집계 (평균/합계/최대/최소 류)
+    #                          → plan_type=aggregation, 시퀀스: catalog → fetch×N → calc(agg) → finish
+    #   - None               : 명시 안 됨 — planner LLM이 claim_text/schema로 추론
+    value_role: str | None = None
+
+    # [2026-05-21] aggregation claim 지원 — "최근 3년 평균 …", "총합 …" 류
+    # 도메인 무관, 모두 Optional. None이면 downstream에서 일반 base/derived 흐름으로 폴백.
+    # LLM(schema_inductor)이 claim_text에서 신호를 감지해 채우며, 한국어 키워드 하드코딩 X.
+    aggregation: str | None = None
+    """집계 연산자 — "mean" | "sum" | "max" | "min" | "median" 등. None이면 단일값 처리."""
+    aggregation_window: int | None = None
+    """집계 윈도우 크기 — "최근 N년/N분기/N개월" → N. None이면 explicit range 사용 또는 미사용."""
+    aggregation_time_range: list[str] | None = None
+    """집계 대상 시점 명시 — ["2022", "2023", "2024"]. None이면 window/anchor로 derive."""
+
+
+
+class Claim(BaseModel):
+    claim_id: UUID = Field(default_factory=uuid4)
+    doc_id: UUID
+    block_id: str
+    sent_id: str
+    claim_text: str
+    claim_type: str | None = None          # 자유 문자열
+    canonical_type: ClaimType | None = None
+    schema: ClaimSchema | None = None
+    source_offset: SourceOffset = Field(default_factory=SourceOffset)
+    check_worthy_score: float = 0.0
+    graph_anchor_id: str | None = None
+    # [v4 김예슬] 앞뒤 문맥 (SIR Tree에서 추출, runtime_agent가 부착)
+    # "이는 2.6배" 같은 대명사 참조 해소 + schema_inductor/query_builder에서 활용
+    context_text: str | None = None
+
+
+# ── Graph ────────────────────────────────────────────────────
+
+class GraphNode(BaseModel):
+    node_id: str
+    node_type: GraphNodeType
+    label: str
+    domain: str | None = None
+    properties: dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphEdge(BaseModel):
+    edge_id: str = Field(default_factory=lambda: str(uuid4())[:8])
+    from_node: str
+    to_node: str
+    edge_type: GraphEdgeType
+    weight: float = 1.0
+    properties: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProvenanceRecord(BaseModel):
+    provenance_id: str = Field(default_factory=lambda: str(uuid4())[:8])
+    source_connector: str
+    source_id: str | None = None
+    query_used: str | None = None
+    fetched_at: datetime = Field(default_factory=datetime.utcnow)
+    raw_snapshot: dict[str, Any] = Field(default_factory=dict)
+
+
+# ── Evidence / Verification ──────────────────────────────────
+
+class Evidence(BaseModel):
+    source_name: str
+    stat_table_id: str | None = None
+    official_value: float | None = None
+    unit: str | None = None
+    time_period: str | None = None
+    raw_response: dict[str, Any] = Field(default_factory=dict)
+    graph_nodes: list[GraphNode] = Field(default_factory=list)
+    provenance: ProvenanceRecord | None = None
+    # [이수민 2026-05-14] working memory 도메인 가드용
+    category_path: str | None = None  # KOSIS catalog의 "인구 > 출생" 등
+
+
+class VerificationResult(BaseModel):
+    result_id: UUID = Field(default_factory=uuid4)
+    claim_id: UUID
+    verdict: VerdictType
+    confidence: float = 0.0
+    evidence: Evidence | None = None
+    # [2026-05-21] derived claim (growth_rate/difference) 검증에 함께 쓰인 *보조 데이터*.
+    # primary evidence는 claim.schema.time_period와 매칭되는 시점값(current).
+    # supporting_evidence는 그 외 — 예: difference 검증의 prev 시점 KOSIS 값.
+    # base claim은 보통 비어있음 (단일 시점만 필요).
+    # 프론트는 "공식 통계 출처" 아래에 "함께 참조한 데이터" 섹션으로 렌더.
+    supporting_evidence: list[Evidence] = Field(default_factory=list)
+    mismatch_type: MismatchType | None = None
+    explanation: str | None = None
+    provenance_summary: str | None = None
+    reviewer_verdict: VerdictType | None = None
+    # ★ Phase E: growth_rate/diff 같은 계산 검증값
+    computed_value: float | None = None
+    """Calculate tool 결과값 — 주장값 vs 이 값 비교로 verdict 결정."""
+    formula: str | None = None
+    """사용된 수식 (예: '(current - prev) / prev * 100')."""
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    # [Multi-hop GraphRAG - 김예슬 2026-05-08]
+    # 파생 주장(2.6배 등)을 COMPARE 엣지 2-hop으로 검증한 경우 표시
+    multihop_used: bool = False
+    multihop_detail: dict | None = None
+
+
+# ── Feedback / Adaptation ────────────────────────────────────
+
+class FeedbackEvent(BaseModel):
+    event_id: UUID = Field(default_factory=uuid4)
+    claim_id: UUID
+    feedback_type: FeedbackType
+    original_verdict: VerdictType | None = None
+    corrected_verdict: VerdictType | None = None
+    reviewer_note: str | None = None
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class DomainPack(BaseModel):
+    pack_id: str
+    domain: str
+    version: str
+    config: dict[str, Any] = Field(default_factory=dict)
+    adapter_path: str | None = None
+    eval_score: float | None = None
+    is_active: bool = True
+
+
+# ── Report ───────────────────────────────────────────────────
+
+class VerificationReport(BaseModel):
+    report_id: UUID = Field(default_factory=uuid4)
+    document: SIRDocument
+    claims: list[Claim] = Field(default_factory=list)
+    results: list[VerificationResult] = Field(default_factory=list)
+    graph_nodes: list[GraphNode] = Field(default_factory=list)
+    graph_edges: list[GraphEdge] = Field(default_factory=list)
+    feedbacks: list[FeedbackEvent] = Field(default_factory=list)
+    domain_pack_used: str | None = None
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    summary: str | None = None

structverify/detection/__init__.py

@@ -0,0 +1,26 @@
+"""structverify.detection — Step 3~5 public API.
+
+domain classify → claim detect → schema induce
+"""
+from structverify.detection.claim_detector import detect_claims
+from structverify.detection.candidate_scorer import score_candidate
+from structverify.detection.domain_classifier import (
+    CONFIDENCE_THRESHOLD,
+    DEFAULT_SEED_DOMAINS,
+    DOMAIN_NAME_PATTERN,
+    DomainRegistry,
+    classify_domain,
+)
+from structverify.detection.schema_inductor import induce_schemas, regenerate_schema
+
+__all__ = [
+    "CONFIDENCE_THRESHOLD",
+    "DEFAULT_SEED_DOMAINS",
+    "DOMAIN_NAME_PATTERN",
+    "DomainRegistry",
+    "classify_domain",
+    "detect_claims",
+    "induce_schemas",
+    "regenerate_schema",
+    "score_candidate",
+]

structverify/detection/_config.py

@@ -0,0 +1,163 @@
+"""[리팩] Step 3~5 설정 로드 — detection/config.yaml (default.yaml 미수정).
+
+런타임: config.detection.*
+레거시: candidate_detection, verification.min_confidence 등 (fallback, 변경 없음)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_CONFIG_PATH = Path(__file__).with_name("config.yaml")
+_CONFIG_CACHE: dict[str, Any] | None = None
+
+
+def _load_module_config() -> dict[str, Any]:
+    global _CONFIG_CACHE
+    if _CONFIG_CACHE is None:
+        with open(_CONFIG_PATH, encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+        _CONFIG_CACHE = data if isinstance(data, dict) else {}
+    return dict(_CONFIG_CACHE)
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for key, value in override.items():
+        if (
+            key in out
+            and isinstance(out[key], dict)
+            and isinstance(value, dict)
+        ):
+            out[key] = _deep_merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def _root(config: dict | None) -> dict[str, Any]:
+    return config or {}
+
+
+def _runtime_detection(config: dict | None) -> dict[str, Any]:
+    block = _root(config).get("detection")
+    return block if isinstance(block, dict) else {}
+
+
+def detection_defaults() -> dict[str, Any]:
+    """detection/config.yaml 내용 (테스트·디버그용)."""
+    return _load_module_config()
+
+
+def _detection_effective(config: dict | None) -> dict[str, Any]:
+    """config.yaml + config.detection 병합 (레거시 키 제외)."""
+    return _deep_merge(_load_module_config(), _runtime_detection(config))
+
+
+def candidate_detection_config(config: dict | None = None) -> dict[str, Any]:
+    """
+    candidate detection 설정 병합.
+
+    우선순위: candidate_detection (레거시) > config.detection > config.yaml
+    """
+    det = _detection_effective(config)
+    legacy = _root(config).get("candidate_detection") or {}
+    if not isinstance(legacy, dict):
+        legacy = {}
+    base = det.get("candidate_detection") or det.get("candidate") or {}
+    if not isinstance(base, dict):
+        base = {}
+    merged = dict(base)
+    merged.update(legacy)
+    return merged
+
+
+def domain_packs_dir(config: dict | None = None) -> str:
+    root = _root(config)
+    if root.get("domain_packs_dir"):
+        return str(root["domain_packs_dir"])
+    runtime = _runtime_detection(config)
+    if runtime.get("domain_packs_dir"):
+        return str(runtime["domain_packs_dir"])
+    return str(_load_module_config().get("domain_packs_dir", "domain-packs"))
+
+
+def domain_registry_path(config: dict | None = None) -> str:
+    root = _root(config)
+    if root.get("domain_registry_path"):
+        return str(root["domain_registry_path"])
+    runtime = _runtime_detection(config)
+    if runtime.get("domain_registry_path"):
+        return str(runtime["domain_registry_path"])
+    return str(_load_module_config().get("domain_registry_path", "domain-packs/registry.yaml"))
+
+
+def domain_confidence_threshold(config: dict | None = None) -> float:
+    det = _detection_effective(config)
+    domain = det.get("domain") or {}
+    if isinstance(domain, dict) and domain.get("confidence_threshold") is not None:
+        return float(domain["confidence_threshold"])
+    if det.get("confidence_threshold") is not None:
+        return float(det["confidence_threshold"])
+    return 0.6
+
+
+def claim_min_confidence(config: dict | None = None) -> float:
+    """claim 채택 최소 confidence. 레거시 verification.min_confidence fallback."""
+    root = _root(config)
+    vconf = root.get("verification") or {}
+    if isinstance(vconf, dict) and vconf.get("min_confidence") is not None:
+        return float(vconf["min_confidence"])
+    runtime = _runtime_detection(config)
+    claim = runtime.get("claim") or {}
+    if isinstance(claim, dict) and claim.get("min_confidence") is not None:
+        return float(claim["min_confidence"])
+    if runtime.get("min_confidence") is not None:
+        return float(runtime["min_confidence"])
+    defaults_claim = _load_module_config().get("claim") or {}
+    if isinstance(defaults_claim, dict) and defaults_claim.get("min_confidence") is not None:
+        return float(defaults_claim["min_confidence"])
+    return 0.7
+
+
+def claim_worthy_score_floor(config: dict | None = None) -> float:
+    """check-worthy true인데 score=0일 때 보정값."""
+    det = _detection_effective(config)
+    claim = det.get("claim") or {}
+    if isinstance(claim, dict) and claim.get("worthy_score_floor") is not None:
+        return float(claim["worthy_score_floor"])
+    return 0.8
+
+
+def candidate_llm_label_floor(config: dict | None = None) -> float:
+    det = _detection_effective(config)
+    cand = det.get("candidate_detection") or det.get("candidate") or {}
+    if isinstance(cand, dict) and cand.get("llm_label_floor_score") is not None:
+        return float(cand["llm_label_floor_score"])
+    return 0.75
+
+
+def model_tier_for(config: dict | None, step: str, *, default: str = "heavy") -> str:
+    """Step별 LLM model_tier (domain_classify, candidate_score, ...)."""
+    det = _detection_effective(config)
+    tiers = det.get("model_tier") or {}
+    if isinstance(tiers, dict) and tiers.get(step):
+        return str(tiers[step])
+    return default
+
+
+def detected_domain(config: dict | None = None, *, default: str = "general") -> str:
+    det = _detection_effective(config)
+    root = _root(config)
+    value = det.get("detected_domain") or root.get("detected_domain")
+    return value if value else default
+
+
+def llm_config(config: dict | None = None) -> dict[str, Any]:
+    base = dict(_root(config).get("llm") or {})
+    det_llm = _detection_effective(config).get("llm") or {}
+    if isinstance(det_llm, dict):
+        base.update(det_llm)
+    return base

structverify/detection/_llm.py

@@ -0,0 +1,24 @@
+"""detection/_llm.py — Step 3~5 LLM thin wrapper.
+
+structverify.utils.llm_client.LLMClient를 detection 모듈에서 직접 생성하지 않고
+여기를 경유한다. (utils/llm_client.py 대수술 없음)
+
+[리팩 Phase C #14] detection 내 LLMClient 생성은 get_llm_client()로 통일.
+[리팩 Phase C #15] llm 서브설정은 detection._config.llm_config() 경유.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from structverify.detection._config import llm_config
+from structverify.utils.llm_client import LLMClient
+
+
+def get_llm_client(config: dict | None = None) -> LLMClient:
+    """detection._config.llm_config()로 LLMClient 생성 (레거시 config.llm 호환)."""
+    return LLMClient(config=llm_config(config))
+
+
+def llm_config_from(config: dict | None) -> dict[str, Any]:
+    """전체 config dict에서 llm 서브 dict 추출 (detection.llm 병합 포함)."""
+    return llm_config(config)

structverify/detection/candidate/__init__.py

@@ -0,0 +1 @@
+"""detection/candidate — Step 4 candidate scoring (LLM·heuristic)."""

structverify/detection/candidate/heuristic.py

@@ -0,0 +1,60 @@
+"""detection/candidate/heuristic.py — candidate scoring heuristic fallback.
+
+candidate_scorer.py에서 분리 (로직 move-only).
+
+LLM 실패 시만 사용 — rule 기반 1차 후보 결정 용도 아님.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# ── heuristic fallback 패턴 (LLM 실패 시만 사용) ────────────────────────
+# 아래 패턴들은 LLM이 호출 불가능할 때만 사용하는 fallback입니다.
+# 운영 환경에서는 LLM 판단이 우선입니다.
+TIME_PATTERN = re.compile(r"\d{4}년|\d+월|\d+분기|전년|지난해|올해")
+COMPARISON_PATTERN = re.compile(r"증가|감소|상승|하락|올랐다|내렸다|대비|비율|점유율|이상|이하|안팎")
+POPULATION_PATTERN = re.compile(r"국내|전국|가구|가계|농가|학생|청년|고령자|근로자|기업|미국|일본|유럽|한국")
+NUMBER_PATTERN = re.compile(r"\d")
+
+
+def _score_candidate_heuristic(
+    sentence: str,
+    threshold: float = 0.65,
+) -> tuple[float, bool, str, dict[str, Any]]:
+    """
+    최소한의 fallback heuristic.
+
+    TODO [김예슬]: 논문 실험 baseline으로도 활용 가능
+      - 이 함수의 성능(F1, precision, recall)을 측정하고
+        teacher LLM 및 fine-tuned 모델과 비교
+
+    주의: 이 heuristic은 LLM 호출 실패 시만 사용합니다.
+    Rule 기반으로 검증 후보를 결정하는 용도로 사용하지 마세요.
+    """
+    has_quantity = bool(NUMBER_PATTERN.search(sentence))
+    has_time_expr = bool(TIME_PATTERN.search(sentence))
+    has_population = bool(POPULATION_PATTERN.search(sentence))
+    has_comparison_expr = bool(COMPARISON_PATTERN.search(sentence))
+
+    score = 0.0
+    if has_quantity:
+        score += 0.35
+    if has_time_expr:
+        score += 0.20
+    if has_population:
+        score += 0.20
+    if has_comparison_expr:
+        score += 0.25
+
+    score = min(score, 1.0)
+    label = score >= threshold
+
+    signals = {
+        "has_quantity": has_quantity,
+        "has_time_expr": has_time_expr,
+        "has_population": has_population,
+        "has_comparison_expr": has_comparison_expr,
+        "reason": "heuristic_fallback",
+    }
+    return score, label, "heuristic_fallback", signals