structverify 0.3.0__py3-none-any.whl

structverify/retrieval/base.py

@@ -0,0 +1,208 @@
+"""
+structverify.retrieval.base — DataSource 추상 인터페이스.
+
+KOSIS만이 아니라 *어떤 데이터 소스*든 (회사 DB, CSV 파일, 외부 API)
+*동일한 인터페이스*로 플러그인 가능하도록 설계.
+
+회사 사용 시나리오:
+  - 글로벌 회사: World Bank API + OECD API
+  - 사내 데이터: PostgreSQL/Snowflake + S3 CSV
+  - 한국 미디어: KOSIS (현재 default)
+
+Config (config/default.yaml):
+    data_sources:
+      enabled: ["kosis", "custom_csv"]
+      kosis: {...}
+      custom_csv: {...}
+
+Registry로 등록:
+    from structverify.retrieval.registry import register_datasource
+
+    @register_datasource("my_internal_db")
+    class MyInternalDB(BaseDataSource):
+        async def search_catalog(self, query, ...): ...
+        async def fetch_evidence(self, candidate_id, ...): ...
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+# ── Result 타입 (dict 호환, 가볍게) ──────────────────────────────
+
+class CatalogCandidate(dict):
+    """카탈로그 검색 결과 1건.
+
+    필수 키:
+        id          : 후보 식별자 (예: 'DT_1L9U108')
+        name        : 표/지표 이름
+        score       : 검색 점수 (0~1)
+    선택 키:
+        category    : 분류 (예: '인구/가구')
+        description : 설명
+        ...source-specific 필드
+    """
+
+
+class EvidenceData(dict):
+    """fetch 결과 raw 데이터.
+
+    필수 키:
+        value           : 수치값 (float)
+        unit            : 단위
+        time_period     : 시점 (YYYY 또는 YYYY-MM)
+    선택 키:
+        official_value  : 정규화된 값
+        raw_response    : API 원본 응답 (디버깅용)
+        rows            : 전체 row 목록 (KOSIS 같은 표 데이터)
+        ...
+    """
+
+
+# ── 추상 인터페이스 ───────────────────────────────────────────────
+
+class BaseDataSource(ABC):
+    """
+    모든 데이터 소스의 공통 인터페이스.
+
+    필수 구현:
+        - search_catalog: 키워드로 표/지표 후보 검색
+        - fetch_evidence: 후보 1개의 실제 데이터 조회
+
+    선택 구현 (기본은 False / no-op):
+        - supports_time_filter: API가 시점 파라미터 지원하는지
+        - supports_population_filter: 인구 필터 지원 여부
+        - close: 리소스 정리 (DB 커넥션 등)
+    """
+
+    name: str = "base"
+    """Registry에 등록될 이름. @register_datasource로 자동 설정."""
+
+    @abstractmethod
+    async def search_catalog(
+        self,
+        query: str,
+        category: list[str] | None = None,
+        top_k: int = 10,
+        context: dict[str, Any] | None = None,
+    ) -> list[CatalogCandidate]:
+        """카탈로그 검색.
+
+        Args:
+            query: 검색 키워드 (자연어 또는 키워드 조합).
+            category: 분류 힌트 (예: ['인구', '가구']).
+            top_k: 반환할 최대 후보 수.
+            context: [P31 2026-05-22] source-specific 부가 정보. 검색 정확도 보강용.
+                권장 키 (source가 알 만한 것만 사용):
+                    - 'parent_path': str — schema의 계층 카테고리 (예: "보건 > 의료자원 > 의료장비")
+                    - 'raw_claim':   str — 원문 claim 텍스트 (앞 200자)
+                    - 'population':  str — schema의 대상 집단/지역
+                    - 'indicator':   str — schema의 지표명
+                source가 모르는 키는 무시. KOSIS는 LLM 카테고리 추출 시 활용.
+
+        Returns:
+            CatalogCandidate 리스트. score 내림차순 권장.
+        """
+
+    @abstractmethod
+    async def fetch_evidence(
+        self,
+        candidate_id: str,
+        params: dict[str, Any] | None = None,
+        workspace: Any = None,
+    ) -> EvidenceData | None:
+        """실제 데이터 조회.
+
+        workspace: (선택) source별 캐시 핸들. KOSIS는 raw 응답 캐싱에 사용,
+            캐시가 불필요한 소스(CSV 등)는 받되 무시한다. 호출부(FetchEvidenceTool)가
+            모든 소스에 workspace를 넘기므로 시그니처에 포함한다.
+
+        Args:
+            candidate_id: search_catalog 결과의 'id'.
+            params: source-specific 파라미터.
+                예 (KOSIS): {'prdSe': 'M', 'startPrdDe': '202504'}.
+                예 (CSV):  {'column': 'sales', 'row_filter': 'region=KR'}.
+
+        Returns:
+            EvidenceData 또는 None (못 찾으면).
+        """
+
+    # ── 선택 기능 (기본 false / no-op) ─────────────────────────
+
+    def supports_time_filter(self) -> bool:
+        """API가 시점 파라미터 필터링을 지원하는지.
+
+        True면 fetch_evidence에 시점 params 전달 가능.
+        False면 모든 row 가져온 후 verifier가 필터링.
+        """
+        return False
+
+    def supports_population_filter(self) -> bool:
+        """인구/카테고리 필터 지원 여부."""
+        return False
+
+    async def close(self) -> None:
+        """리소스 정리. DB 커넥션 등."""
+        return None
+
+    async def get_table_meta(
+        self,
+        candidate_id: str,
+        meta_type: str = "ITM",
+    ) -> dict[str, Any] | list[dict[str, Any]] | None:
+        """[P30 2026-05-22] 표의 *항목/분류 메타* 조회 — *데이터는 X*.
+
+        용도: catalog_search → fetch_evidence 사이에서, 표 이름만으론 정답인지
+        불확실할 때 LLM이 *표 내부 구조*(어떤 항목/분류 코드)를 보고 판단하기
+        위한 가벼운 메타 호출.
+
+        Args:
+            candidate_id: search_catalog 결과의 'id' (stat_id 등).
+            meta_type: source-specific 메타 타입.
+                KOSIS: "ITM" (통계항목), "OBJL01"~"OBJL08" (분류 항목), "PRD", "CMMT".
+
+        Returns:
+            메타 dict 또는 list (source 형식 그대로). 실패/미지원이면 None.
+        """
+        return None
+
+
+# ── 헬퍼: 다중 source orchestration (Phase B+에서 활용) ───────────
+
+class MultiSourceRouter:
+    """
+    여러 DataSource를 묶어서 *순차/병렬* 검색.
+
+    Phase B에서 tool wrapper가 이 클래스 사용:
+      - config.data_sources.enabled = ["kosis", "custom_db"] 면 *둘 다* 검색
+      - 결과 합쳐서 ranked list 반환
+    """
+
+    def __init__(self, sources: list[BaseDataSource]):
+        self.sources = sources
+
+    async def search_catalog_all(
+        self,
+        query: str,
+        category: list[str] | None = None,
+        top_k_per_source: int = 5,
+    ) -> dict[str, list[CatalogCandidate]]:
+        """각 source 검색 결과 dict로."""
+        results: dict[str, list[CatalogCandidate]] = {}
+        for src in self.sources:
+            try:
+                results[src.name] = await src.search_catalog(
+                    query, category=category, top_k=top_k_per_source
+                )
+            except Exception as e:
+                # 한 source 실패해도 나머지 진행
+                results[src.name] = []
+        return results
+
+    async def close_all(self) -> None:
+        for src in self.sources:
+            try:
+                await src.close()
+            except Exception:
+                pass

structverify/retrieval/base_connector.py

@@ -0,0 +1,85 @@
+"""
+retrieval/base_connector.py — 데이터 커넥터 추상 인터페이스
+
+v2: to_graph_nodes(), tag_provenance() 메서드 추가
+
+[참고] RAG (Lewis et al., NeurIPS 2020) — https://github.com/huggingface/transformers
+  검색 → LLM context 주입 패턴. 커넥터의 search→fetch→context 흐름에 참고.
+"""
+# 수정자: 신준수
+# 수정 날짜: 2026-04-27
+# 수정 내용: StatData에 official_value·unit·time_period(증거 정규화; 출처 API 키는 커넥터가 채움)
+# [2026-05-14 | 이수민] memory/v1: StatData.category_path 추가
+#   - KOSIS catalog의 카테고리 경로를 evidence까지 전달해 verifier 도메인 가드에 활용
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+from structverify.core.schemas import GraphNode, ProvenanceRecord
+
+
+@dataclass
+class ConnectorQuery:
+    keyword: str
+    indicator: str | None = None
+    time_period: str | None = None
+    population: str | None = None
+    extra_params: dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class StatRecord:
+    stat_id: str; stat_name: str; org_name: str; org_id: str | None = None
+    available_periods: list[str] = field(default_factory=list)
+    relevance_score: float = 0.0
+    # 출처별 search 응답 한 행 전체; 커넥터·API별 추가 키는 여기로.
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class StatData:
+    stat_id: str; stat_name: str
+    values: dict[str, Any] = field(default_factory=dict)
+    raw_response: dict[str, Any] = field(default_factory=dict)
+    # Evidence/검증용 정규화(커넥터가 출처 API에서 채움; subgraph는 values 키를 직접 보지 않음)
+    official_value: float | None = None
+    unit: str | None = None
+    time_period: str | None = None
+    # [이수민 2026-05-14] working memory 도메인 가드용 — KOSIS catalog category_path
+    category_path: str | None = None
+
+
+class BaseConnector(ABC):
+    """
+    모든 커넥터의 추상 기본 클래스.
+    v2에서 to_graph_nodes()와 tag_provenance() 추가.
+    """
+    @abstractmethod
+    async def search(self, query: ConnectorQuery) -> list[StatRecord]: ...
+
+    @abstractmethod
+    async def fetch(self, stat_id: str, params: dict[str, Any]) -> StatData: ...
+
+    @abstractmethod
+    def to_graph_nodes(self, data: StatData) -> list[GraphNode]:
+        """v2: 조회 결과를 그래프 노드로 변환"""
+        ...
+
+    @abstractmethod
+    def tag_provenance(self, data: StatData, query: ConnectorQuery) -> ProvenanceRecord:
+        """v2: 출처 이력 기록"""
+        ...
+
+    async def search_and_fetch(self, query: ConnectorQuery) -> StatData | None:
+        records = await self.search(query)
+        if not records:
+            
+            return None
+        best = max(records, key=lambda r: r.relevance_score)
+        return await self.fetch(
+            best.stat_id,
+            {
+                "time_period": query.time_period,
+                "population": query.population,
+                "query": query,
+                "stat_record": best,
+            },
+        )

structverify/retrieval/catalog_ranker.py

@@ -0,0 +1,300 @@
+"""
+structverify.retrieval.catalog_ranker — LLM batch ranking.
+
+배경:
+  기존 indicator semantic guard(키워드 룰) + relevance_judge(per-table T/F) 두 가드를
+  *후보 N개 한 번에 비교하는 LLM ranking*으로 통합. 이유:
+    - 키워드 룰은 한정자가 사전에 없는 도메인(투석/혈관조영 등) 확장 불가.
+    - per-table 판단은 *비교*가 필요한 한정자 매칭(특수의료장비 vs 의료장비)을 잡지 못함.
+    - N표를 한 번에 비교하면 한정자 매칭 + 부분집합/상위집합 관계 판별이 자연스러움.
+
+설계:
+  - input: claim(indicator/population/parent_path/원문) + candidates[{id, name, org, ...}]
+  - output: [{id, score, reason}, ...] (score 0~1, 높은 순 정렬)
+  - 호출자가 score 임계치(예: 0.15) 미만은 reject, 나머지는 score 순서로 try.
+  - LLM 1회 호출 (메타데이터는 표 이름 + org_name + category_path까지만 노출 — 과적합 회피).
+
+config:
+  data_sources.kosis.catalog_ranker.{enabled, score_threshold, 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__)
+
+# LLM 응답이 표 5~25개 ranking이라 ~1KB 정도. v3 light tier 충분.
+_DEFAULT_MODEL_TIER = "light"
+_DEFAULT_SCORE_THRESHOLD = 0.15  # 이 미만은 reject
+
+
+def _normalize_candidate_for_prompt(c: dict) -> dict:
+    """LLM 프롬프트용으로 후보 메타데이터를 안전 추출. raw StatRecord 핸들링.
+
+    Returns:
+        {id, name, org_name, category_path}. 비어있는 필드는 ''.
+    """
+    cid = str(c.get("id") or "")
+    name = str(c.get("name") or "")
+    # name에 "[같은 job에서 ...]" 같은 hint label 붙어있으면 제거 (LLM 판단 오염 방지)
+    name = re.sub(r"\s*\[같은\s+job[^\]]*\]\s*$", "", name).strip()
+
+    org_name = ""
+    category_path = ""
+
+    # candidate dict 직접 필드
+    if c.get("org_name"):
+        org_name = str(c["org_name"])
+    if c.get("category_path"):
+        category_path = str(c["category_path"])
+
+    # raw에서 보강 (StatRecord 또는 dict)
+    raw = c.get("raw")
+    if raw is not None:
+        # dataclass StatRecord
+        if not org_name:
+            _org = getattr(raw, "org_name", None)
+            if _org:
+                org_name = str(_org)
+        if not category_path:
+            _md = getattr(raw, "metadata", None)
+            if isinstance(_md, dict):
+                _cp = _md.get("category_path")
+                if _cp:
+                    category_path = str(_cp)
+        # dict raw (예: from_job_success)
+        if isinstance(raw, dict):
+            if not org_name and raw.get("org_name"):
+                org_name = str(raw["org_name"])
+            if not category_path and raw.get("category_path"):
+                category_path = str(raw["category_path"])
+
+    return {
+        "id": cid,
+        "name": name,
+        "org_name": org_name,
+        "category_path": category_path,
+    }
+
+
+def _build_prompt(
+    *,
+    claim_text: str,
+    indicator: str,
+    population: str,
+    time_period: str,
+    parent_path: str,
+    candidates: list[dict],
+    source_context: str = "",
+) -> str:
+    """LLM 프롬프트 구성. candidates는 _normalize_candidate_for_prompt 결과.
+
+    source_context가 있으면(회사 등 임의 소스) *소스 무관 중립 프롬프트*를 쓴다 —
+    'KOSIS/해외 통계' 같은 공공통계 전용 가정을 넣지 않는다.
+    """
+    cands_lines: list[str] = []
+    for i, c in enumerate(candidates, start=1):
+        line = f"  [{i}] id={c['id']!r}\n      name={c['name']!r}"
+        if c.get("org_name"):
+            line += f"\n      org={c['org_name']!r}"
+        if c.get("category_path"):
+            line += f"\n      category_path={c['category_path']!r}"
+        cands_lines.append(line)
+    cands_block = "\n".join(cands_lines) if cands_lines else "  (없음)"
+
+    if source_context:
+        # ── 소스 무관 중립 랭커 (방대한 회사 데이터 등) ──
+        return f"""당신은 '검증 기준 데이터' 후보 ranking reviewer입니다.
+아래 주장을 검증하기에 적합한 후보를 의미 매칭 정도로 0~1 점수로 매기세요.
+
+[검증 기준 데이터]
+{source_context}
+
+[사용자 주장]
+- 원문: {claim_text or '(없음)'}
+- 검증 지표: {indicator or '(없음)'}
+- 대상/지역: {population or '(없음)'}
+- 시점: {time_period or '(없음)'}
+
+[후보 N개]
+{cands_block}
+
+[판단 기준]
+1. 후보의 이름/지표가 주장의 지표와 *의미상 일치*하면 score ↑ (같은 대상을 가리키는가?).
+2. 대상/지역/시점이 맞으면 가점. 지표 자체가 다르면 감점.
+3. 무관한 지표는 score 0.0~0.1. (공공/해외 여부는 판단하지 말 것 — 이 소스가 정답 기준이다.)
+4. score: 0.9~1.0 정확 / 0.5~0.8 도메인 맞고 부분 / 0.2~0.4 광범위·협소 / 0.0~0.1 무관.
+
+[응답 — JSON only, 모든 후보]
+{{"rankings": [{{"id": "<후보 id>", "score": 0.95, "reason": "<한 줄>"}}, ...]}}
+* id는 입력 candidates의 id 그대로. 누락 후보는 score=0.0 처리.
+"""
+
+    return f"""당신은 KOSIS 통계표 ranking reviewer입니다. 사용자 claim 검증에 적합한
+*표 후보 N개를 의미 매칭 정도로 비교*해 0~1 점수로 ranking 하세요.
+
+[사용자 claim]
+- 원문: {claim_text or '(없음)'}
+- 검증 지표 (indicator): {indicator or '(없음)'}
+- 대상 집단/지역 (population): {population or '(없음)'}
+- 시점 (time_period): {time_period or '(없음)'}
+- 카테고리 경로 (parent_path): {parent_path or '(없음)'}
+
+[후보 표 N개]
+{cands_block}
+
+[판단 기준 — 중요]
+1. **한정자 매칭**:
+   - claim의 indicator에 *한정자*가 있으면 (예: "체외 충격파 쇄석술 장비", "MRI 장비")
+     → 표 이름에 *그 한정자*가 직접/상위로 매칭되는 표가 *최우선* (예: "특수의료장비",
+       "진단방사선 장비" 등 한정자 포함 표가 score ↑).
+   - claim의 indicator에 한정자가 *없으면* (예: 단순 "의료장비 수", "인구")
+     → 표도 *한정자 없는 일반 집합* 표가 우선 (한정자 박힌 표는 *부분집합*이라 score ↓).
+2. **population 매칭**:
+   - 표 이름이나 category_path에 population을 포함/매칭하면 score ↑.
+   - "시도별/시군구별"처럼 지역 분할 표는 대부분의 population에 적합.
+3. **외국/장래/다른 도메인**:
+   - 해외 통계, 장래 추계·전망, 도메인 불일치(인구↔경제↔기상) → score 0.0~0.1.
+4. **score 의미**:
+   - 0.9~1.0: 한정자/도메인 모두 정확 매칭, 정답 확신
+   - 0.5~0.8: 도메인 맞고 한정자 부분 매칭 (상위 집합 등 row 검색으로 회수 가능)
+   - 0.2~0.4: 도메인 맞지만 한정자 mismatch 또는 너무 광범위/협소
+   - 0.0~0.1: 무관한 표 — 거부 권장
+
+[응답 형식 — JSON only, 모든 후보에 대해 작성]
+{{
+  "rankings": [
+    {{"id": "<후보 id>", "score": 0.95, "reason": "<한 줄 이유>"}},
+    ...
+  ]
+}}
+
+* id는 반드시 입력 candidates의 id 그대로 사용. 누락된 표는 score=0.0으로 처리됨.
+* score 순서로 정렬할 필요는 없음 (호출자가 정렬).
+"""
+
+
+def _parse(raw: str, valid_ids: set[str]) -> list[dict] | None:
+    """LLM JSON 응답 파싱. valid_ids에 있는 id만 채택.
+
+    Returns:
+        [{id, score, reason}, ...] — score 높은 순 정렬.
+        파싱 실패 시 None.
+    """
+    if not raw:
+        return None
+    # JSON 블록 추출 (코드펜스 / 앞뒤 텍스트 핸들링)
+    m = re.search(r"\{[\s\S]*\}", raw)
+    if not m:
+        logger.debug(f"[catalog_ranker] JSON 블록 못 찾음: raw={raw[:200]!r}")
+        return None
+    try:
+        data = json.loads(m.group(0))
+    except json.JSONDecodeError as e:
+        logger.debug(f"[catalog_ranker] JSON parse 실패: {e}, raw={raw[:200]!r}")
+        return None
+    rankings = data.get("rankings")
+    if not isinstance(rankings, list):
+        return None
+
+    out: list[dict] = []
+    seen_ids: set[str] = set()
+    for r in rankings:
+        if not isinstance(r, dict):
+            continue
+        rid = str(r.get("id") or "").strip()
+        if not rid or rid not in valid_ids or rid in seen_ids:
+            continue
+        try:
+            score = float(r.get("score", 0.0) or 0.0)
+        except (TypeError, ValueError):
+            score = 0.0
+        score = max(0.0, min(score, 1.0))
+        reason = str(r.get("reason") or "")[:200]
+        out.append({"id": rid, "score": score, "reason": reason})
+        seen_ids.add(rid)
+
+    # LLM이 누락한 id는 score=0.0으로 추가
+    for vid in valid_ids:
+        if vid not in seen_ids:
+            out.append({"id": vid, "score": 0.0, "reason": "LLM 응답에서 누락 — 기본 0.0"})
+
+    # score 순 정렬
+    out.sort(key=lambda x: -x["score"])
+    return out
+
+
+async def rank_candidates(
+    *,
+    claim_text: str,
+    indicator: str,
+    population: str,
+    time_period: str,
+    parent_path: str,
+    candidates: list[dict],
+    config: dict | None = None,
+) -> list[dict] | None:
+    """LLM batch ranking으로 후보 표 N개를 의미 점수로 정렬.
+
+    Args:
+        claim_text: claim 원문 (1~3문장).
+        indicator: schema.indicator.
+        population: schema.population.
+        time_period: schema.time_period.
+        parent_path: schema.parent_path.
+        candidates: [{id, name, score, raw?}, ...] — catalog_search 결과.
+        config: 전체 config dict. data_sources.kosis.catalog_ranker 섹션 사용.
+
+    Returns:
+        [{id, score, reason}, ...] — score 높은 순 정렬.
+        candidates 비었거나 LLM 실패 시 None.
+    """
+    if not candidates:
+        return None
+
+    # 후보 정규화 (메타데이터 추출)
+    norm_cands = [_normalize_candidate_for_prompt(c) for c in candidates]
+    valid_ids: set[str] = {c["id"] for c in norm_cands if c["id"]}
+    if not valid_ids:
+        return None
+
+    # config 추출 — data_sources.kosis.catalog_ranker
+    _cfg = ((config or {}).get("data_sources") or {}).get("kosis") or {}
+    _rk = _cfg.get("catalog_ranker") or {}
+    model_tier = str(_rk.get("model_tier") or _DEFAULT_MODEL_TIER).strip().lower()
+
+    # 소스 프로파일이 있으면 그 컨텍스트로 *중립 랭커*를 쓴다 (KOSIS 편향 제거).
+    _plan = ((config or {}).get("_source_profile") or {}).get("retrieval_plan") or {}
+    _source_context = str(_plan.get("ranker_context") or "")
+    prompt = _build_prompt(
+        claim_text=claim_text,
+        indicator=indicator,
+        population=population,
+        time_period=time_period,
+        parent_path=parent_path,
+        candidates=norm_cands,
+        source_context=_source_context,
+    )
+
+    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 표 ranking reviewer. JSON만 응답.",
+            model_tier=model_tier,
+        )
+    except Exception as e:
+        logger.warning(f"[catalog_ranker] LLM 호출 실패: {e}")
+        return None
+
+    parsed = _parse(raw, valid_ids)
+    if parsed is None:
+        logger.warning(f"[catalog_ranker] 응답 파싱 실패 — raw={raw[:300]!r}")
+        return None
+
+    return parsed