structverify 0.3.0__py3-none-any.whl

structverify/retrieval/query_builder.py

@@ -0,0 +1,72 @@
+"""
+
+retrieval/query_builder.py — 검색 쿼리 생성 (Schema → ConnectorQuery)
+
+[김예슬 - 2026-04-30 / v2]
+- build_query()에 raw_claim 추가: LLM Agent가 catalog 검색 시 원문 맥락 활용
+- ConnectorQuery.extra_params에 embedding_text 추가:
+  pgvector 유사도 검색에 사용할 텍스트 (indicator + population + time_period 조합)
+
+[참고] ProgramFC (Pan et al., NAACL 2023) — https://github.com/mbzuai-nlp/ProgramFC
+  structured representation → data source query 변환 구조 참고
+"""
+from __future__ import annotations
+from structverify.core.schemas import Claim
+from structverify.retrieval.base_connector import ConnectorQuery
+
+
+def build_query(claim: Claim) -> ConnectorQuery:
+    """
+    Claim Schema → 커넥터 검색 쿼리 생성
+
+    [v4 김예슬] extra_params에 추가:
+      - raw_claim: 원문 주장 (LLM Agent catalog 검색 시 맥락)
+      - embedding_text: pgvector 유사도 검색용 텍스트
+    """
+    s = claim.schema
+    # [v3 김예슬] context_text 있으면 raw_claim에 포함 → 검색 맥락 강화
+    context = getattr(claim, "context_text", None) or claim.claim_text
+
+    if not s:
+        return ConnectorQuery(
+            keyword=claim.claim_text[:50],
+            extra_params={
+                "raw_claim":      context,
+                "embedding_text": context[:200],
+            },
+        )
+
+    # keyword: source_reference(출처기관) + indicator + population 조합
+    # 출처기관이 있으면 KOSIS 검색 범위를 해당 기관으로 좁힐 수 있음
+    parts = [p for p in [s.source_reference, s.indicator, s.population] if p]
+    keyword = " ".join(parts) or claim.claim_text[:50]
+
+    #   "카테고리 > indicator | 항목: indicator | 분류: population | 단위: unit"
+    # KOSIS catalog의 임베딩 인덱싱 포맷과 정렬되어 유사도 검색 정확도 향상.
+    emb_cat = s.parent_path or ""
+    emb_indicator = s.indicator or ""
+    emb_population = s.population or ""
+    emb_unit = s.unit or ""
+    if emb_indicator:
+        embedding_text = (
+            f"{emb_cat} > {emb_indicator} | "
+            f"항목: {emb_indicator} | "
+            f"분류: {emb_population} | "
+            f"단위: {emb_unit}"
+        ).strip()
+    else:
+        embedding_text = keyword
+
+    return ConnectorQuery(
+        keyword=keyword,
+        indicator=s.indicator,
+        time_period=s.time_period,
+        population=s.population,
+        extra_params={
+            "raw_claim":      context,
+            "embedding_text": embedding_text,
+            "source_org":     s.source_reference,
+            # [v6.11] parent_path 전달 → catalog_search가 LLM 호출 없이 활용
+            "parent_path":    s.parent_path,
+        },
+    )

structverify/retrieval/registry.py

@@ -0,0 +1,133 @@
+"""
+structverify.retrieval.registry — DataSource 동적 등록.
+
+회사가 *자체 데이터 소스*를 등록 가능:
+
+    # company_package/sales_source.py
+    from structverify.retrieval.base import BaseDataSource
+    from structverify.retrieval.registry import register_datasource
+
+    @register_datasource("my_sales_db")
+    class MySalesDB(BaseDataSource):
+        async def search_catalog(self, query, ...):
+            ...
+        async def fetch_evidence(self, candidate_id, ...):
+            ...
+
+    # config/default.yaml
+    data_sources:
+      enabled: ["my_sales_db"]
+      my_sales_db:
+        dsn: "postgresql://..."
+
+Agent loop (Phase D)에서 이 registry를 통해 source 인스턴스 생성:
+
+    from structverify.retrieval.registry import build_datasource
+    source = build_datasource("my_sales_db", config={"dsn": "..."})
+"""
+from __future__ import annotations
+
+from structverify.utils.logger import get_logger
+from typing import Callable, Type
+
+from .base import BaseDataSource
+
+logger = get_logger(__name__)
+
+
+# ── Registry 본체 ────────────────────────────────────────────────
+
+_REGISTRY: dict[str, Type[BaseDataSource]] = {}
+
+
+def register_datasource(
+    name: str,
+) -> Callable[[Type[BaseDataSource]], Type[BaseDataSource]]:
+    """
+    DataSource 클래스를 등록하는 데코레이터.
+
+    Args:
+        name: config.data_sources.enabled 에 들어갈 이름.
+
+    Example:
+        @register_datasource("kosis")
+        class KOSISSource(BaseDataSource):
+            ...
+    """
+    def decorator(cls: Type[BaseDataSource]) -> Type[BaseDataSource]:
+        if not issubclass(cls, BaseDataSource):
+            raise TypeError(
+                f"{cls.__name__} must subclass BaseDataSource to be registered"
+            )
+        if name in _REGISTRY:
+            logger.warning(
+                f"[registry] DataSource '{name}' already registered, overwriting "
+                f"({_REGISTRY[name].__name__} → {cls.__name__})"
+            )
+        _REGISTRY[name] = cls
+        cls.name = name
+        logger.info(f"[registry] DataSource 등록: {name} ({cls.__name__})")
+        return cls
+    return decorator
+
+
+def get_datasource_class(name: str) -> Type[BaseDataSource]:
+    """등록된 클래스 반환. 없으면 KeyError."""
+    if name not in _REGISTRY:
+        available = list(_REGISTRY.keys())
+        raise KeyError(
+            f"DataSource '{name}' not registered. "
+            f"Available: {available}. "
+            f"Register via @register_datasource('{name}')."
+        )
+    return _REGISTRY[name]
+
+
+def list_datasources() -> list[str]:
+    """등록된 모든 DataSource 이름."""
+    return sorted(_REGISTRY.keys())
+
+
+def build_datasource(name: str, config: dict | None = None) -> BaseDataSource:
+    """Config에서 datasource 인스턴스 생성.
+
+    Args:
+        name: 등록된 이름.
+        config: 클래스 __init__에 전달될 kwargs.
+                None이면 인자 없이 생성.
+
+    Example:
+        source = build_datasource("kosis", config={"api_key": "..."})
+    """
+    cls = get_datasource_class(name)
+    if config:
+        return cls(**config)
+    return cls()
+
+
+# ── 편의 함수 ─────────────────────────────────────────────────────
+
+def build_all_enabled(config: dict) -> list[BaseDataSource]:
+    """
+    config['data_sources'] 섹션에서 *enabled* 된 모든 source 빌드.
+
+    Args:
+        config: config.data_sources 섹션 전체 dict.
+                예: {"enabled": ["kosis"], "kosis": {"api_key": "..."}, ...}
+
+    Returns:
+        활성화된 DataSource 인스턴스 리스트.
+    """
+    enabled = config.get("enabled", [])
+    sources: list[BaseDataSource] = []
+    for name in enabled:
+        try:
+            source_config = config.get(name, {})
+            sources.append(build_datasource(name, source_config))
+        except KeyError as e:
+            logger.warning(
+                f"[registry] enabled={name!r} but not registered — skipped. {e}"
+            )
+        except Exception as e:
+            logger.error(f"[registry] build_datasource({name!r}) failed: {e}")
+    return sources

structverify/retrieval/relevance_judge.py

@@ -0,0 +1,141 @@
+"""
+structverify.retrieval.relevance_judge — P32: LLM 기반 표 관련성 판단.
+
+배경:
+  kosis_connector._is_table_relevant()는 *토큰 매칭 룰베이스*라 sweet spot 밖
+  케이스에 false negative 발생. 예:
+    - indicator: "체외 충격파 쇄석술 장비 수"
+    - table_name: "시군구(서울인천경기강원)별 주요 의료장비 현황"
+    - 룰: "장비"(2글자, len<3 룰에 막힘), "쇄석술"(table에 없음) → 거부 ❌
+    - 의미적으로는 *정답 표* (장비 row가 의료장비 분류에 포함될 가능성 높음)
+
+설계:
+  룰베이스를 *fast-path*로 유지하되, 거부 결정 시 *LLM에게 한 번 더 위임*.
+  LLM은 claim 원문 + schema + table_name을 보고 *의미적 매칭* 판단.
+  룰 *통과* 시엔 LLM 호출 없음 (속도).
+
+  - 룰 통과 → 그대로 진행 (LLM 호출 X)
+  - 룰 거부 → LLM 가드 호출 → True/False → 최종 판단
+
+config:
+  kosis.relevance_guard.{enabled, llm_fallback, model_tier}
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _build_prompt(
+    claim_text: str,
+    indicator: str,
+    population: str,
+    parent_path: str,
+    table_name: str,
+) -> str:
+    return f"""당신은 KOSIS 통계표 관련성 reviewer입니다. 사용자 claim의 검증에
+*이 표가 의미적으로 적합한가*를 한 줄로 판단하세요.
+
+[사용자 claim]
+- 원문: {claim_text or '(없음)'}
+- 검증 지표 (indicator): {indicator or '(없음)'}
+- 대상 집단/지역 (population): {population or '(없음)'}
+- 카테고리 경로 (parent_path): {parent_path or '(없음)'}
+
+[후보 KOSIS 통계표]
+- 표 이름: {table_name}
+
+[판단 기준]
+- 표 이름이 indicator를 *포함하거나*, indicator의 *상위 분류* (예: "체외 충격파 쇄석술 장비"의 상위 = "의료장비")로 *직접 매칭*되면 → relevant.
+- 표 이름이 population (예: "강원도", "시도별")을 포함/매칭하면 → relevant 가능성 ↑.
+- 표 이름이 더 *광범위*해도 (예: "주요 의료장비"가 "체외 충격파 쇄석술 장비"의 상위) row 검색으로 정답 찾을 가능성 있으면 → relevant.
+- 외국 국가/해외 통계 / 장래 추계·전망 / 다른 도메인 (인구↔경제↔기상)이면 → NOT relevant.
+- parent_path와 표 이름이 같은 분류 트리에 있으면 → relevant.
+
+[응답 형식 — JSON only]
+{{
+  "relevant": true | false,
+  "reason": "한 줄 이유"
+}}
+"""
+
+
+def _parse(raw: str) -> tuple[bool | None, str]:
+    """LLM 응답 파싱. (relevant, reason). None이면 파싱 실패."""
+    try:
+        m = re.search(r"\{[^{}]*\}", raw, re.DOTALL)
+        if not m:
+            return None, ""
+        data = json.loads(m.group(0))
+        rel = data.get("relevant")
+        reason = str(data.get("reason") or "")
+        if isinstance(rel, bool):
+            return rel, reason
+        if isinstance(rel, str):
+            return rel.strip().lower() in ("true", "yes", "y", "1"), reason
+        return None, reason
+    except Exception as e:
+        logger.debug(f"[relevance_judge] 파싱 실패: {e}")
+        return None, ""
+
+
+async def is_table_relevant_semantic(
+    *,
+    claim_text: str,
+    indicator: str,
+    population: str,
+    parent_path: str,
+    table_name: str,
+    config: dict | None,
+) -> tuple[bool | None, str]:
+    """LLM 기반 표 관련성 판단.
+
+    Args:
+        claim_text: claim 원문 (1~3문장).
+        indicator: schema.indicator.
+        population: schema.population (지역/집단).
+        parent_path: schema.parent_path (계층 카테고리).
+        table_name: KOSIS 표 이름.
+        config: 전체 config dict.
+
+    Returns:
+        (relevant, reason).
+        relevant=True: 의미적 매칭 OK, fetch 진행 권장.
+        relevant=False: 매칭 안 됨, 거부 권장.
+        relevant=None: LLM 호출 실패/파싱 실패 → 호출자가 보수적으로 처리.
+    """
+    if not table_name or (not indicator and not claim_text):
+        return None, "input 부족"
+
+    _cfg = (config or {}).get("kosis") or {}
+    _rg = _cfg.get("relevance_guard") or {}
+    model_tier = str(_rg.get("model_tier") or "light").strip().lower()
+
+    prompt = _build_prompt(claim_text, indicator, population, parent_path, table_name)
+    from structverify.utils.llm_client import LLMClient
+    llm = LLMClient(config=(config or {}).get("llm") or {})
+    try:
+        raw = await llm.generate(
+            prompt=prompt,
+            system_prompt="KOSIS 표 관련성 reviewer. JSON만 응답.",
+            model_tier=model_tier,
+        )
+    except Exception as e:
+        logger.warning(f"[relevance_judge] LLM 호출 실패: {e}")
+        return None, f"llm_error: {e}"
+
+    rel, reason = _parse(raw)
+    if rel is None:
+        logger.info(f"[relevance_judge] 파싱 실패 raw={raw[:200]!r}")
+        return None, "parse_failed"
+
+    logger.info(
+        f"[relevance_judge] table={table_name!r} vs indicator={indicator!r}: "
+        f"relevant={rel} reason={reason[:120]!r}"
+    )
+    return rel, reason

structverify/retrieval/row_matcher.py

@@ -0,0 +1,267 @@
+"""
+structverify.retrieval.row_matcher — P33c: LLM 기반 row indicator 매칭.
+
+배경:
+  _select_best_row()의 _ind_match()는 정규화 후 정확 일치/substring 양방향 비교
+  하는 룰베이스. KOSIS 표가 *계층적 분류*를 가져서 row의 ITM_NM이 *상위 카테고리*
+  (예: "진단방사선·특수의료장비")인데 사용자 indicator가 *세부 항목*(예:
+  "체외 충격파 쇄석술 장비")이면 직접 매칭이 안 됨.
+
+  LLM이 rows의 unique ITM_NM / C1_NM~C4_NM 값들을 보고 indicator와
+  *의미적으로 매칭*되는 컬럼 값을 식별해 그 값으로 row 필터링.
+
+용도:
+  _select_best_row()의 indicator pre-filter가 0건일 때만 호출 (룰 통과 시엔
+  비용 절감 위해 LLM 호출 X). config.kosis.relevance_guard.row_match_llm_fallback
+  이 true일 때만 활성화.
+
+반환:
+  매칭 row list (1개 이상) 또는 빈 list. 빈 list면 진짜 그 표에 indicator가
+  없는 것이므로 호출자가 None 반환.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+_INDICATOR_FIELDS = ("ITM_NM", "C1_NM", "C2_NM", "C3_NM", "C4_NM")
+
+
+def _extract_unique_values(rows: list[dict], field: str, max_n: int = 80) -> list[str]:
+    """rows의 특정 컬럼에서 unique 값 list 추출 (LLM에 노출용)."""
+    seen: set[str] = set()
+    out: list[str] = []
+    for r in rows:
+        v = r.get(field)
+        if not v:
+            continue
+        s = str(v).strip()
+        if s and s not in seen:
+            seen.add(s)
+            out.append(s)
+            if len(out) >= max_n:
+                break
+    return out
+
+
+def _build_prompt(
+    indicator: str,
+    claim_text: str,
+    parent_path: str,
+    population: str,
+    field_values: dict[str, list[str]],
+) -> str:
+    """LLM prompt — unique 컬럼 값들 보고 indicator와 매칭되는 값 추천."""
+    lines = []
+    for f, vals in field_values.items():
+        if not vals:
+            continue
+        # 너무 길면 자름
+        shown = vals[:50]
+        more = f" (외 {len(vals)-len(shown)}개)" if len(vals) > len(shown) else ""
+        lines.append(f"- {f}: {', '.join(repr(v) for v in shown)}{more}")
+    field_block = "\n".join(lines) if lines else "(분류 컬럼 값 없음)"
+
+    return f"""당신은 KOSIS 통계표 row 매칭 reviewer입니다. 사용자 indicator가
+표 안 *어떤 row 분류 값*에 해당하는지 의미적으로 판단하세요.
+
+[사용자 검색 의도]
+- indicator: {indicator!r}
+- claim 원문: {claim_text or '(없음)'}
+- parent_path: {parent_path or '(없음)'}
+- population: {population or '(없음)'}
+
+[표 안 row의 분류 컬럼 unique 값 list]
+{field_block}
+
+[판단 기준]
+1. indicator의 *핵심 키워드*가 어느 컬럼의 어떤 값에 *직접/유사 매칭*되는가? (예: indicator="체외 충격파 쇄석술 장비" → ITM_NM 또는 C2_NM에 "체외 충격파 쇄석술기" 또는 "ESWL" 같은 값이 있으면 그것).
+2. parent_path(계층)에 비추어 *상위 카테고리* row (예: "진단방사선·특수의료장비" 합계)는 매칭이 *아니다*. *세부 항목 row*가 필요.
+3. claim 원문에 "보유대수", "장비 수" 같은 *수량 표현*은 indicator의 일반어이므로 row 분류 값과 직접 비교 불필요.
+4. 어느 컬럼에도 indicator와 의미적 매칭이 없으면 → 그 표에 indicator 없는 것 → "matches": [] 반환.
+
+★ field 라벨 정확성:
+  - "field"는 *반드시* 위 [표 안 row의 분류 컬럼 unique 값 list]에 *명시된 라벨*과 동일하게 적기.
+  - 예: 값이 "ITM_NM" list가 아니라 "C2_NM" list 안에 있으면 → field="C2_NM" (절대 ITM_NM이라 적지 말 것).
+  - field 잘못 적으면 row 필터링 0건이 되어 검증 실패. 정확한 컬럼명 사용 필수.
+
+[응답 형식 — JSON only, 다른 텍스트 금지]
+{{
+  "matches": [{{"field": "<컬럼명>", "value": "<매칭 값>"}}, ...],
+  "reasoning": "한 줄 이유"
+}}
+
+* matches는 0개 이상. 보통 1~3개. *상위 카테고리* 값은 절대 포함하지 마세요.
+"""
+
+
+def _parse(raw: str) -> tuple[list[dict], str]:
+    """LLM 응답 파싱. (matches list, reasoning)."""
+    try:
+        m = re.search(r"\{.*\}", raw, re.DOTALL)
+        if not m:
+            return [], ""
+        data = json.loads(m.group(0))
+        matches = data.get("matches") or []
+        reasoning = str(data.get("reasoning") or "")
+        if not isinstance(matches, list):
+            return [], reasoning
+        out: list[dict] = []
+        for m in matches:
+            if isinstance(m, dict) and m.get("field") and m.get("value"):
+                out.append({"field": str(m["field"]), "value": str(m["value"])})
+        return out, reasoning
+    except Exception as e:
+        logger.debug(f"[row_matcher] 파싱 실패: {e}")
+        return [], ""
+
+
+async def llm_select_rows(
+    *,
+    rows: list[dict],
+    indicator: str,
+    claim_text: str,
+    parent_path: str,
+    population: str,
+    config: dict | None,
+) -> list[dict]:
+    """LLM이 indicator와 의미적으로 매칭되는 row들을 식별해 반환.
+
+    Args:
+        rows: pop pre-filter 통과한 후보 row list.
+        indicator: schema.indicator.
+        claim_text: claim 원문 (앞 400자).
+        parent_path: schema.parent_path.
+        population: schema.population.
+        config: 전체 config dict.
+
+    Returns:
+        매칭 row list. 빈 list면 LLM이 "이 표에 indicator 없다"고 판단.
+    """
+    if not rows or not indicator:
+        return []
+
+    # 1) unique 분류 값 추출 (ITM_NM/C1~C4_NM)
+    field_values: dict[str, list[str]] = {}
+    for f in _INDICATOR_FIELDS:
+        vals = _extract_unique_values(rows, f, max_n=80)
+        if vals:
+            field_values[f] = vals
+
+    if not field_values:
+        logger.info("[row_matcher] 분류 컬럼 값 없음 → LLM 호출 skip")
+        return []
+
+    # 2) LLM 호출
+    _rg_cfg = ((config or {}).get("kosis") or {}).get("relevance_guard") or {}
+    model_tier = str(_rg_cfg.get("row_match_model_tier") or _rg_cfg.get("model_tier") or "light").strip().lower()
+
+    prompt = _build_prompt(indicator, claim_text, parent_path, population, field_values)
+    from structverify.utils.llm_client import LLMClient
+    llm = LLMClient(config=(config or {}).get("llm") or {})
+    try:
+        raw = await llm.generate(
+            prompt=prompt,
+            system_prompt="KOSIS row 매칭 reviewer. JSON만 응답.",
+            model_tier=model_tier,
+        )
+    except Exception as e:
+        logger.warning(f"[row_matcher] LLM 호출 실패: {e}")
+        return []
+
+    matches, reasoning = _parse(raw)
+    if not matches:
+        logger.info(
+            f"[row_matcher] LLM: 매칭 없음 — indicator={indicator!r} "
+            f"reason={reasoning[:120]!r}"
+        )
+        return []
+
+    # field/value swap 휴리스틱: LLM이 field 자리에 실제 매칭 값을 넣고
+    # value 자리에 DT 같은 측정치(숫자/짧은 문자열)를 넣어 응답하는 케이스 회복.
+    # (예: field='체외충격파쇄석기', value='18' → field='ITM_NM', value='체외충격파쇄석기')
+    swapped: list[dict] = []
+    for m in matches:
+        f, v = m["field"], m["value"]
+        if f not in _INDICATOR_FIELDS and (v.isdigit() or len(v) <= 3):
+            logger.warning(
+                f"[row_matcher] LLM field/value swap 감지 — "
+                f"field={f!r} value={v!r} → value={f!r}로 재해석"
+            )
+            swapped.append({"field": _INDICATOR_FIELDS[0], "value": f})
+        else:
+            swapped.append(m)
+    matches = swapped
+
+    logger.info(
+        f"[row_matcher] LLM 매칭 {len(matches)}건: {matches} "
+        f"reason={reasoning[:80]!r}"
+    )
+
+    # 3) matches dict({field, value})로 rows 필터링
+    def _norm(s: str) -> str:
+        if not s:
+            return ""
+        s = str(s)
+        for ch in (" ", "·", "ㆍ", "・", "/", "-", "_", "(", ")", "[", "]"):
+            s = s.replace(ch, "")
+        return s.strip().lower()
+
+    norm_matches = [
+        {"field": m["field"], "value_norm": _norm(m["value"]), "value_raw": m["value"]}
+        for m in matches
+    ]
+    filtered: list[dict] = []
+    field_mismatches: list[tuple[str, str]] = []  # (llm_field, actual_field) 로깅용
+
+    for r in rows:
+        matched = False
+        for nm in norm_matches:
+            target_v_norm = nm["value_norm"]
+            if not target_v_norm:
+                continue
+            # 1차: LLM이 지정한 field 우선 검사
+            v = r.get(nm["field"])
+            if v is not None:
+                v_norm = _norm(str(v))
+                if target_v_norm in v_norm or v_norm in target_v_norm:
+                    matched = True
+                    break
+            # 2차: LLM이 field를 잘못 지정한 경우 대비 — 모든 INDICATOR_FIELDS에서 value 검색.
+            # LLM은 "체외충격파쇄석기"가 ITM_NM이라 우길 수 있는데 실제로는 C2_NM 같은 다른
+            # 컬럼에 있음. value가 unique 분류라 다른 컬럼에 우연히 같은 단어 들어있을 가능성 낮음.
+            for fname in _INDICATOR_FIELDS:
+                if fname == nm["field"]:
+                    continue  # 1차에서 이미 봄
+                v = r.get(fname)
+                if v is None:
+                    continue
+                v_norm = _norm(str(v))
+                if target_v_norm in v_norm or v_norm in target_v_norm:
+                    matched = True
+                    field_mismatches.append((nm["field"], fname))
+                    break
+            if matched:
+                break
+        if matched:
+            filtered.append(r)
+
+    if field_mismatches:
+        # LLM이 잘못 지정한 field → 실제 매칭된 field 로깅 (1회만)
+        _ex = field_mismatches[0]
+        logger.info(
+            f"[row_matcher] LLM이 field={_ex[0]!r}로 지정했으나 실제로는 "
+            f"{_ex[1]!r}에 매칭됨 — all-field fallback으로 회복 "
+            f"({len(field_mismatches)} rows)"
+        )
+
+    logger.info(
+        f"[row_matcher] LLM 매칭 적용: {len(rows)} rows → {len(filtered)} rows"
+    )
+    return filtered