structverify 0.3.0__py3-none-any.whl

structverify/graph/graph_builder.py

@@ -0,0 +1,238 @@
+"""
+graph/graph_builder.py — Claim/Evidence Graph 조립 (Step 6)
+
+유도된 스키마와 클레임 정보를 바탕으로 그래프 노드/엣지를 생성한다.
+
+[참고] 설계 근거 논문:
+  - GraphRAG (arXiv 2501.00309) — 텍스트→그래프 구성·검색 패턴
+  - AutoSchemaKG (arXiv 2505.23628) — LLM schema → 그래프 노드/엣지 변환
+  - Fact Verification on KG (EMNLP Findings 2025) — KG 위 프로그래밍적 사실 검증
+  - FEVER (Thorne et al., NAACL 2018) — Claim 단위 검증, VerdictType 3-class 근거
+  - HOVER (Jiang et al., EMNLP 2020) — 멀티홉 서브그래프 추론 (Claim 중심 구조)
+  - TabFact (Chen et al., ICLR 2020) — 통계표 수치 검증 (KOSIS Evidence 모델)
+
+[Step 6 — 담당: 이수민]
+  Claim + ClaimSchema
+    → 노드 생성:
+      - ClaimNode  (claim_id, claim_text)
+      - MetricNode (indicator명)
+      - TimeNode   (time_period)
+      - EntityNode (population/대상)
+    → 엣지 생성:
+      - claim → MEASURED_AT → time
+      - claim → BELONGS_TO  → metric
+      - claim → BELONGS_TO  → entity
+    → GraphNode[], GraphEdge[] 반환 (Neo4j 저장은 별도)
+
+  [pipeline 수정 - 담당 : 김예슬]
+  - build_claim_graph() 시그니처 변경: sir_doc 파라미터 추가
+  · sir_doc이 있으면 extract_context_edges() 호출 → NEXT_SENT/IN_BLOCK/IN_DOC 추가
+  · GraphRAG 2-hop 탐색의 핵심 — 같은 문단 내 연관 수치 자동 발견
+
+- COMPARE 엣지 추가 (핵심 변경):
+  · 같은 MetricNode(indicator)를 공유하는 Claim 쌍에 COMPARE 엣지 생성
+  · 예: C1("21만7천") ↔ C2("8만4천") → 둘 다 indicator="쉬었음인구"
+  · → C3("2.6배") 같은 파생 주장 검증 시 C1+C2를 함께 KOSIS 조회 가능
+  · 같은 지표 여러 시점: C7(12.77개월/2024) ↔ C8(10.71개월/2004)
+    → "첫취업소요기간이 2.06개월 늘었다"는 주장도 C7+C8 동시 검증
+
+- 문맥 엣지를 GraphEdge 객체로 변환하여 반환값에 포함
+  · graph_store.py(박재윤)에서 Neo4j MERGE 시 일괄 처리 가능
+
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+
+from structverify.core.schemas import (
+    Claim, GraphEdge, GraphEdgeType, GraphNode, GraphNodeType, SIRDocument,ClaimType
+)
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# 문맥 엣지 타입 문자열 → GraphEdgeType 매핑
+_CONTEXT_EDGE_MAP = {
+    "NEXT_SENT": GraphEdgeType.NEXT_SENT,
+    "IN_BLOCK":  GraphEdgeType.IN_BLOCK,
+    "IN_DOC":    GraphEdgeType.IN_DOC,
+}
+
+
+def build_claim_graph(
+    claims: list[Claim],
+    sir_doc: SIRDocument | None = None,
+) -> tuple[list[GraphNode], list[GraphEdge]]:
+    """
+    Claim 리스트 → Knowledge Graph (노드 + 엣지) 조립.
+
+    Args:
+        claims:  Claim 객체 리스트 (schema 포함)
+        sir_doc: SIRDocument (있으면 NEXT_SENT/IN_BLOCK/IN_DOC 문맥 엣지 추가)
+
+    생성되는 노드/엣지:
+      ClaimNode  → BELONGS_TO → MetricNode (indicator)
+      ClaimNode  → MEASURED_AT → TimeNode  (time_period)
+      ClaimNode  → BELONGS_TO → EntityNode (population)
+      ClaimNode  ↔ COMPARE ↔  ClaimNode   (같은 indicator 공유 시)
+      SentNode   → NEXT_SENT → SentNode   (문맥 순서)
+      SentNode   → IN_BLOCK  → BlockNode  (문단 소속)
+      BlockNode  → IN_DOC    → DocNode    (문서 소속)
+    """
+    nodes: list[GraphNode] = []
+    edges: list[GraphEdge] = []
+    seen_node_ids: set[str] = set()
+
+    def _add_node(node: GraphNode) -> None:
+        if node.node_id not in seen_node_ids:
+            nodes.append(node)
+            seen_node_ids.add(node.node_id)
+
+    # ── 1) 기본 Claim 노드/엣지 (기존 로직) ───────────────────────────
+    # indicator별 claim_id 추적 (COMPARE 엣지 생성용)
+    metric_to_claims: dict[str, list[str]] = defaultdict(list)
+
+    for claim in claims:
+        claim_node_id = f"claim:{claim.claim_id.hex[:8]}"
+        _add_node(GraphNode(
+            node_id=claim_node_id,
+            node_type=GraphNodeType.CLAIM,
+            label=claim.claim_text[:60],
+            properties={
+                "claim_text": claim.claim_text,
+                "value": claim.schema.value if claim.schema else None,
+                "claim_type": claim.claim_type,
+                "canonical_type": (
+                    claim.canonical_type.value
+                    if isinstance(claim.canonical_type, ClaimType)
+                    else claim.canonical_type
+                ),
+            },
+        ))
+
+        if not claim.schema:
+            continue
+
+        schema = claim.schema
+
+        # MetricNode + BELONGS_TO
+        if schema.indicator:
+            metric_node_id = f"metric:{schema.indicator}"
+            _add_node(GraphNode(
+                node_id=metric_node_id,
+                node_type=GraphNodeType.METRIC,
+                label=schema.indicator,
+                properties={"unit": schema.unit},
+            ))
+            edges.append(GraphEdge(
+                from_node=claim_node_id,
+                to_node=metric_node_id,
+                edge_type=GraphEdgeType.BELONGS_TO,
+            ))
+            # COMPARE 엣지 대상 추적
+            metric_to_claims[schema.indicator].append(claim_node_id)
+
+        # TimeNode + MEASURED_AT
+        if schema.time_period:
+            time_node_id = f"time:{schema.time_period}"
+            _add_node(GraphNode(
+                node_id=time_node_id,
+                node_type=GraphNodeType.TIME,
+                label=schema.time_period,
+            ))
+            edges.append(GraphEdge(
+                from_node=claim_node_id,
+                to_node=time_node_id,
+                edge_type=GraphEdgeType.MEASURED_AT,
+            ))
+
+        # EntityNode + BELONGS_TO
+        if schema.population:
+            entity_node_id = f"entity:{schema.population}"
+            _add_node(GraphNode(
+                node_id=entity_node_id,
+                node_type=GraphNodeType.ENTITY,
+                label=schema.population,
+            ))
+            edges.append(GraphEdge(
+                from_node=claim_node_id,
+                to_node=entity_node_id,
+                edge_type=GraphEdgeType.BELONGS_TO,
+            ))
+
+    # ── 2) COMPARE 엣지 — 같은 indicator 공유 Claim 쌍 ────────────────
+    #
+    # 왜 필요한가:
+    #   "쉬었음 청년이 20년 새 2.6배 늘었다" → 이건 C1(21만7천)+C2(8만4천) 비율
+    #   두 Claim이 indicator="쉬었음인구"를 공유 → COMPARE 엣지로 연결
+    #   검증 시 MetricNode 2-hop으로 C1+C2를 함께 KOSIS 조회 → 비율 계산
+    #
+    compare_added: set[tuple[str, str]] = set()
+    for indicator, claim_ids in metric_to_claims.items():
+        if len(claim_ids) < 2:
+            continue
+        for i in range(len(claim_ids)):
+            for j in range(i + 1, len(claim_ids)):
+                pair = (claim_ids[i], claim_ids[j])
+                if pair not in compare_added:
+                    edges.append(GraphEdge(
+                        from_node=claim_ids[i],
+                        to_node=claim_ids[j],
+                        edge_type=GraphEdgeType.COMPARE,
+                        properties={"shared_indicator": indicator},
+                    ))
+                    compare_added.add(pair)
+
+    # ── 3) 문맥 엣지 — NEXT_SENT / IN_BLOCK / IN_DOC ──────────────────
+    #
+    # sir_doc이 있으면 extract_context_edges()로 문장-문단-문서 관계를 추가.
+    # 이 엣지들이 없으면:
+    #   - 같은 문단에 있는 수치들이 서로 연결되지 않음
+    #   - "이 기사에서 취업 관련 수치 모두 검증" 쿼리 시
+    #     Block B3 → IN_BLOCK → C7+C8+C9 탐색 불가
+    #   - C1 다음 문장이 C2, 그 다음이 C3(2.6배) 관계를 모름
+    #     → 파생 주장 자동 탐지 불가
+    #
+    if sir_doc is not None:
+        from structverify.preprocessing.sir_builder import extract_context_edges
+        context_edges = extract_context_edges(sir_doc)
+
+        for ce in context_edges:
+            edge_type = _CONTEXT_EDGE_MAP.get(ce["edge_type"])
+            if edge_type is None:
+                continue
+            edges.append(GraphEdge(
+                from_node=ce["from_node"],
+                to_node=ce["to_node"],
+                edge_type=edge_type,
+            ))
+
+        # 문맥 엣지에 등장하는 노드(블록/문장)도 등록
+        # (Claim이 아닌 SentNode, BlockNode, DocNode)
+        context_node_ids = set()
+        for ce in context_edges:
+            context_node_ids.add(ce["from_node"])
+            context_node_ids.add(ce["to_node"])
+        for nid in context_node_ids:
+            if nid not in seen_node_ids:
+                # node_type은 node_id prefix로 구분
+                if nid.startswith("node:doc:"):
+                    ntype = GraphNodeType.SOURCE
+                elif nid.startswith("node:b"):
+                    ntype = GraphNodeType.SOURCE  # Block → SOURCE로 임시 매핑
+                else:
+                    ntype = GraphNodeType.ENTITY
+                _add_node(GraphNode(
+                    node_id=nid,
+                    node_type=ntype,
+                    label=nid,
+                ))
+
+        logger.info(
+            f"Graph 조립: {len(nodes)} nodes, {len(edges)} edges "
+            f"(COMPARE: {len(compare_added)}쌍, 문맥엣지: {len(context_edges)}개)"
+        )
+    else:
+        logger.info(f"Graph 조립: {len(nodes)} nodes, {len(edges)} edges (문맥엣지 없음 — sir_doc 미전달)")
+
+    return nodes, edges

structverify/graph/graph_multihop.py

@@ -0,0 +1,335 @@
+"""
+graph/graph_multihop.py — Multi-hop GraphRAG 파생 주장 검증 (Step 7.5)
+
+[김예슬 - 2026-05-08 / v1]
+KOSIS에서 직접 검증 불가능한 "파생 주장"을 Graph 2-hop 탐색으로 검증.
+
+[문제]
+  "쉬었음 청년이 20년 새 2.6배 늘었다" 같은 비율/배수 주장은
+  KOSIS에 "2.6배"라는 수치가 직접 존재하지 않음 → 항상 unverifiable.
+
+[해결 — Multi-hop GraphRAG]
+  COMPARE 엣지로 같은 indicator를 공유하는 Claim들을 연결한 뒤,
+  파생 주장(C3: "2.6배")을 그 원천 주장(C1, C2)들의 검증된 수치로 재계산.
+
+  탐색 흐름 (2-hop):
+    C3("2.6배") -[BELONGS_TO]-> MetricNode("쉬었음인구")
+                                    ^
+                                    | [BELONGS_TO]
+                            C1(21만7천, 2024), C2(8만4천, 2004)
+    → C1, C2가 각각 KOSIS로 MATCH 판정됨
+    → 217000 / 84000 = 2.58 ≈ 2.6 → C3도 MATCH
+
+[설계 원칙]
+  - LLM 미사용 — 비율/배수/차이 계산은 deterministic
+  - C1, C2가 먼저 검증(MATCH/MISMATCH)되어 있어야 함 → Step 8 이후 실행
+  - 원천 주장이 검증 안 됐으면 multi-hop도 unverifiable
+
+[참고] GraphRAG (Edge et al., 2024) — 엔티티 그래프 기반 멀티홉 추론
+"""
+from __future__ import annotations
+
+import re
+
+from structverify.core.schemas import (
+    Claim, ClaimType, GraphEdge, VerdictType, VerificationResult,
+)
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ── 파생 주장 판별 ──────────────────────────────────────────────────────────
+
+# 배수/비율 표현 패턴 — "2.6배", "두 배", "3분의 1" 등
+_RATIO_PATTERNS = [
+    re.compile(r"(\d+\.?\d*)\s*배"),           # 2.6배
+    re.compile(r"(\d+\.?\d*)\s*퍼센트|%"),     # 30%
+]
+# 차이 표현 — "8만→22만", "8만에서 22만으로"
+_DIFF_PATTERNS = [
+    re.compile(r"(\d[\d,]*)\s*[만천]?\s*[→~]\s*(\d[\d,]*)"),
+]
+
+
+def is_derived_claim(claim: Claim) -> bool:
+    """
+    파생 주장(비율/배수/차이)인지 판별.
+
+    파생 주장:
+      - canonical_type이 SCALE / COMPARISON
+      - claim_text에 "배", "배로", "분의" 등 비율 표현
+      - schema.value가 비율값으로 보임 (0 < value < 100, unit이 "배"/"%")
+    """
+    text = claim.claim_text or ""
+
+    # 1) canonical_type 기반
+    if claim.canonical_type in (ClaimType.SCALE, ClaimType.COMPARISON):
+        return True
+
+    # 2) 텍스트 패턴 — "N배"
+    if re.search(r"\d+\.?\d*\s*배", text):
+        return True
+
+    # 3) unit이 "배"
+    if claim.schema and claim.schema.unit:
+        if "배" in claim.schema.unit:
+            return True
+
+    return False
+
+
+def extract_ratio_value(claim: Claim) -> float | None:
+    """
+    파생 주장에서 비율/배수 값을 추출.
+    "2.6배 늘었다" → 2.6
+    """
+    if claim.schema and claim.schema.value is not None:
+        v = claim.schema.value
+        if 0 < v < 1000:   # 비율로 보이는 범위
+            return v
+
+    text = claim.claim_text or ""
+    m = re.search(r"(\d+\.?\d*)\s*배", text)
+    if m:
+        try:
+            return float(m.group(1))
+        except ValueError:
+            pass
+    return None
+
+
+# ── COMPARE 엣지 2-hop 탐색 ─────────────────────────────────────────────────
+
+def find_compare_neighbors(
+    target_claim: Claim,
+    all_claims: list[Claim],
+    edges: list[GraphEdge],
+) -> list[Claim]:
+    """
+    target_claim과 COMPARE 엣지로 연결된 Claim들을 반환.
+
+    Graph 2-hop:
+      target -[BELONGS_TO]-> MetricNode <-[BELONGS_TO]- neighbor
+      (graph_builder가 이미 COMPARE 엣지로 표현해둠)
+
+    Args:
+        target_claim: 파생 주장
+        all_claims:   전체 claim 목록
+        edges:        graph_builder가 만든 엣지 목록
+
+    Returns:
+        같은 indicator를 공유하는 다른 Claim들
+    """
+    target_nid = f"claim:{target_claim.claim_id.hex[:8]}"
+
+    # COMPARE 엣지에서 target과 연결된 노드 id 수집
+    neighbor_nids: set[str] = set()
+    for edge in edges:
+        etype = edge.edge_type
+        etype_val = etype.value if hasattr(etype, "value") else etype
+        if etype_val != "compare":
+            continue
+        if edge.from_node == target_nid:
+            neighbor_nids.add(edge.to_node)
+        elif edge.to_node == target_nid:
+            neighbor_nids.add(edge.from_node)
+
+    if not neighbor_nids:
+        return []
+
+    # node_id → Claim 매핑
+    neighbors = []
+    for claim in all_claims:
+        nid = f"claim:{claim.claim_id.hex[:8]}"
+        if nid in neighbor_nids:
+            neighbors.append(claim)
+
+    return neighbors
+
+
+# ── Multi-hop 검증 ──────────────────────────────────────────────────────────
+
+def verify_via_multihop(
+    target_claim: Claim,
+    all_claims: list[Claim],
+    edges: list[GraphEdge],
+    results_by_claim: dict[str, VerificationResult],
+    config: dict | None = None,
+) -> VerificationResult | None:
+    """
+    파생 주장을 COMPARE 이웃들의 검증된 수치로 재검증.
+
+    [핵심 로직]
+      C3: "2.6배 늘었다" (파생 주장)
+        → COMPARE 이웃: C1(217000, 2024), C2(84000, 2004)
+        → C1, C2가 모두 검증됨 (official_value 존재)
+        → 큰값 / 작은값 = 217000 / 84000 = 2.58
+        → claimed 2.6 vs computed 2.58 → 오차 0.8% → MATCH
+
+    Args:
+        target_claim:      검증할 파생 주장
+        all_claims:        전체 claim
+        edges:             graph 엣지
+        results_by_claim:  {claim_id_hex: VerificationResult} — Step 8 결과
+        config:            설정 (tolerance 등)
+
+    Returns:
+        재검증된 VerificationResult, 또는 multi-hop 불가 시 None
+    """
+    config = config or {}
+    tolerance = config.get("verification", {}).get("multihop_tolerance_pct", 10.0)
+
+    # 1) 파생 주장인지 확인
+    if not is_derived_claim(target_claim):
+        return None
+
+    claimed_ratio = extract_ratio_value(target_claim)
+    if claimed_ratio is None:
+        logger.debug(f"파생 주장이지만 비율값 추출 실패: {target_claim.claim_text[:40]}")
+        return None
+
+    # 2) COMPARE 이웃 탐색 (2-hop)
+    neighbors = find_compare_neighbors(target_claim, all_claims, edges)
+    if len(neighbors) < 2:
+        logger.debug(
+            f"Multi-hop 불가 — COMPARE 이웃 부족 "
+            f"({len(neighbors)}개): {target_claim.claim_text[:40]}"
+        )
+        return None
+
+    # 3) 이웃들 중 검증된(official_value 있는) 수치 수집
+    verified_values: list[tuple[float, str]] = []   # (official_value, time_period)
+    for nb in neighbors:
+        nb_hex = nb.claim_id.hex
+        nb_result = results_by_claim.get(nb_hex)
+        if not nb_result or not nb_result.evidence:
+            continue
+        official = nb_result.evidence.official_value
+        if official is None or official == 0:
+            continue
+        # 원천 주장이 MATCH/MISMATCH(=수치 확인됨)인 것만 사용
+        if nb_result.verdict == VerdictType.UNVERIFIABLE:
+            continue
+        period = ""
+        if nb.schema and nb.schema.time_period:
+            period = nb.schema.time_period
+        verified_values.append((official, period))
+
+    if len(verified_values) < 2:
+        logger.debug(
+            f"Multi-hop 불가 — 검증된 이웃 수치 부족 "
+            f"({len(verified_values)}개): {target_claim.claim_text[:40]}"
+        )
+        return None
+
+    # 4) 비율 계산 — 큰 값 / 작은 값
+    values_only = sorted([v for v, _ in verified_values], reverse=True)
+    largest = values_only[0]
+    smallest = values_only[-1]
+
+    if smallest == 0:
+        return None
+
+    computed_ratio = largest / smallest
+
+    # 5) 판정 — claimed vs computed
+    diff_pct = abs(claimed_ratio - computed_ratio) / max(computed_ratio, 1e-9) * 100
+
+    if diff_pct <= tolerance:
+        verdict = VerdictType.MATCH
+        conf = min(0.9, 1.0 - diff_pct / 100)
+    elif diff_pct <= 30:
+        verdict = VerdictType.UNVERIFIABLE
+        conf = 0.4
+    else:
+        verdict = VerdictType.MISMATCH
+        conf = min(0.85, diff_pct / 100)
+
+    logger.info(
+        f"[Multi-hop] {target_claim.claim_text[:40]} → "
+        f"claimed={claimed_ratio:.2f}배 vs computed={computed_ratio:.2f}배 "
+        f"({largest:.0f}/{smallest:.0f}) → {verdict.value} (오차 {diff_pct:.1f}%)"
+    )
+
+    # 원천 주장 evidence를 멀티홉 결과에 첨부 (가장 큰 값 쪽)
+    source_evidence = None
+    for nb in neighbors:
+        nb_result = results_by_claim.get(nb.claim_id.hex)
+        if nb_result and nb_result.evidence:
+            if nb_result.evidence.official_value == largest:
+                source_evidence = nb_result.evidence
+                break
+
+    result = VerificationResult(
+        claim_id=target_claim.claim_id,
+        verdict=verdict,
+        confidence=conf,
+        evidence=source_evidence,
+    )
+    # multi-hop 사용 표시 (explainer가 참고)
+    result.multihop_used = True
+    result.multihop_detail = {
+        "claimed_ratio":  claimed_ratio,
+        "computed_ratio": round(computed_ratio, 3),
+        "largest_value":  largest,
+        "smallest_value": smallest,
+        "neighbor_count": len(verified_values),
+    }
+    return result
+
+
+def apply_multihop_verification(
+    claims: list[Claim],
+    results: list[VerificationResult],
+    edges: list[GraphEdge],
+    config: dict | None = None,
+) -> list[VerificationResult]:
+    """
+    Step 8 이후 호출 — UNVERIFIABLE인 파생 주장들을 multi-hop으로 재검증.
+
+    runtime_agent에서:
+      results = [verify_claim(c, ev) for c in claims]   # Step 8
+      results = apply_multihop_verification(claims, results, edges)  # Step 8.5
+
+    Args:
+        claims:  전체 claim
+        results: Step 8 검증 결과 (claims와 같은 순서)
+        edges:   graph 엣지 (COMPARE 포함)
+        config:  설정
+
+    Returns:
+        multi-hop 재검증이 반영된 results (UNVERIFIABLE → MATCH/MISMATCH 가능)
+    """
+    # claim_id_hex → result 매핑
+    results_by_claim = {
+        str(r.claim_id.hex if hasattr(r.claim_id, "hex") else r.claim_id): r
+        for r in results
+    }
+    # claim 순서 유지용
+    result_by_idx = {i: r for i, r in enumerate(results)}
+
+    multihop_count = 0
+    for idx, claim in enumerate(claims):
+        current = result_by_idx[idx]
+
+        # 이미 MATCH/MISMATCH면 multi-hop 불필요
+        if current.verdict != VerdictType.UNVERIFIABLE:
+            continue
+
+        # 파생 주장만 시도
+        if not is_derived_claim(claim):
+            continue
+
+        mh_result = verify_via_multihop(
+            claim, claims, edges, results_by_claim, config
+        )
+        if mh_result is not None:
+            result_by_idx[idx] = mh_result
+            results_by_claim[claim.claim_id.hex] = mh_result
+            multihop_count += 1
+
+    if multihop_count:
+        logger.info(f"[Multi-hop] {multihop_count}건 재검증 완료")
+
+    return [result_by_idx[i] for i in range(len(results))]