structverify 0.3.0__py3-none-any.whl

structverify/adaptation/kosis_crawler.py

@@ -0,0 +1,317 @@
+"""
+# 수정자: 박재윤
+# 수정 날짜: 2026-04-27
+# 수정 내용: KOSIS 전체 통계표 메타데이터 수집 및 pgvector INSERT 구현
+
+# [DONE] _fetch_category KOSIS API 실제 호출 구현
+# [DONE] save_to_db pgvector 임베딩 INSERT 구현
+# [DONE] 주제별 통계(MT_ZTITLE) 카테고리 전체 확장
+# [DONE] save_to_db 배치 임베딩으로 최적화 (100건 단위)
+# [DONE] NCP 임베딩 모델로 교체 (HCX 임베딩 v2, 1024차원)
+# [DONE] save_to_db 세마포어 기반 rate limit 제어 (asyncio.Semaphore, 3개 동시 + 재시도)
+# [TODO] asyncpg로 마이그레이션 (현재 psycopg2 임시 사용)
+# [TODO] 기관별 통계(MT_OTITLE) 수집 추가 (별도 배치 스크립트)
+# [김예슬 - 2026-04-30 / v2]
+# [DONE] is_catalog_ready(): catalog 구축 여부 확인 함수 추가
+# [DONE] save_to_db(): embedding 미완성 행만 임베딩 처리 (skip 최적화)
+# [DONE] builder_agent에서 catalog.rebuild=false 이면 crawl_kosis_catalog skip
+
+adaptation/kosis_crawler.py — KOSIS 통계표 메타데이터 전량 수집 (Step 0-1)
+
+서비스 시작 전 1회 실행하여 KOSIS의 모든 통계표 메타데이터를 수집한다.
+수집된 데이터는 2가지 용도로 사용:
+  1) RAG — 임베딩하여 pgvector에 저장 (방법 1)
+  2) Self-Instruct — 합성 학습 데이터 생성의 seed (방법 3)
+
+[참고] Self-Instruct (Wang et al., ACL 2023)
+  - https://github.com/yizhongw/self-instruct
+  - seed 데이터(통계표 메타)로부터 학습 데이터를 자동 생성하는 출발점
+
+사용법:
+  python -m adaptation.kosis_crawler          # CLI 실행
+  await crawl_kosis_catalog(config)           # 코드에서 호출
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ── [v2] Catalog 준비 여부 확인 ──────────────────────────────────────────────
+
+async def is_catalog_ready(config: dict | None = None, min_rows: int = 1000) -> bool:
+    """
+    kosis_stat_catalog에 데이터가 충분히 있으면 True.
+
+    [v2 박재윤/김예슬 - 2026-04-30]
+    builder_agent.pretrain_domain()에서 호출:
+      config.kosis.catalog.rebuild=false + is_catalog_ready=True
+      → crawl_kosis_catalog() skip (재수집 방지)
+
+    Args:
+        min_rows: 이 수 이상이면 "이미 구축됨"으로 판단 (기본 1000)
+    """
+    config = config or {}
+    try:
+        import asyncpg
+        pg_dsn = os.environ.get(
+            config.get("pgvector_dsn_env", "PGVECTOR_DSN"),
+            "postgresql://structverify:svpass123@localhost:5432/structverify",
+        )
+        conn = await asyncpg.connect(pg_dsn)
+        total = await conn.fetchval("SELECT COUNT(*) FROM kosis_stat_catalog") or 0
+        embedded = await conn.fetchval(
+            "SELECT COUNT(*) FROM kosis_stat_catalog WHERE embedding IS NOT NULL"
+        ) or 0
+        await conn.close()
+        logger.info(
+            f"kosis_stat_catalog: total={total}, embedded={embedded} "
+            f"(min_rows 기준={min_rows})"
+        )
+        return int(total) >= min_rows
+    except Exception as e:
+        logger.debug(f"catalog 확인 실패 (테이블 없거나 DB 미연결): {e}")
+        return False
+
+# [기존] - 박재윤: 기존 카테고리 (ID 오류)
+# KOSIS_TOP_CATEGORIES = [
+#     {"vw_cd": "MT_ZTITLE", "parent_id": "A"},   # 인구/가구
+#     {"vw_cd": "MT_ZTITLE", "parent_id": "B"},   # 고용/노동/임금
+#     {"vw_cd": "MT_ZTITLE", "parent_id": "F"},   # 농림수산식품
+#     {"vw_cd": "MT_ZTITLE", "parent_id": "H"},   # 물가/가계
+#     {"vw_cd": "MT_ZTITLE", "parent_id": "I"},   # 경기/기업경영
+#     {"vw_cd": "MT_ZTITLE", "parent_id": "N"},   # 국민계정/재정/금융
+# ]
+
+# [v1] - 박재윤: 실제 KOSIS API 확인 후 전체 카테고리로 확장
+KOSIS_TOP_CATEGORIES = [
+    {"vw_cd": "MT_ZTITLE", "parent_id": "A"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "B"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "C"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "D"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "E"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "F"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "G"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "H1"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "H2"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "I1"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "I2"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "J1"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "J2"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "K1"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "K2"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "L"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "M1"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "M2"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "N1"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "N2"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "O"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "P1"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "P2"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "Q"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "R"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "S1"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "S2"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "T"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "U"},
+    {"vw_cd": "MT_ZTITLE", "parent_id": "V"},
+    # {"vw_cd": "MT_OTITLE", "parent_id": ""},   # 기관별 전체
+]
+
+
+async def crawl_kosis_catalog(config: dict | None = None) -> list[dict[str, Any]]:
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    config = config or {}
+    kosis_config = config.get("kosis", {})
+    api_key = os.environ.get(kosis_config.get("api_key_env", "KOSIS_API_KEY"), "")
+    base_url = kosis_config.get("base_url", "https://kosis.kr/openapi")
+    timeout = kosis_config.get("timeout", 30)
+
+    if not api_key:
+        logger.error("KOSIS_API_KEY 환경변수가 설정되지 않았습니다")
+        return []
+
+    all_tables: dict[str, dict] = {}
+
+    for category in KOSIS_TOP_CATEGORIES:
+        try:
+            tables = await _fetch_category(base_url, api_key, category, timeout)
+            for t in tables:
+                all_tables[t["stat_id"]] = t
+            logger.info(f"카테고리 {category['parent_id']} 수집: {len(tables)}건")
+        except Exception as e:
+            logger.error(f"카테고리 {category['parent_id']} 수집 실패: {e}")
+
+    result = list(all_tables.values())
+    logger.info(f"KOSIS 메타데이터 수집 완료: 총 {len(result)}건 (중복 제거됨)")
+    return result
+
+
+async def _fetch_category(base_url, api_key, category, timeout):
+    import httpx, re
+
+    results = []
+
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        async def fetch_recursive(parent_id, path_history, depth=0):
+            if depth > 7:
+                return
+
+            url = (
+                f"https://kosis.kr/openapi/statisticsList.do?method=getList"
+                f"&apiKey={api_key}&vwCd={category['vw_cd']}"
+                f"&parentListId={parent_id}&format=json"
+            )
+            response = await client.get(url)
+            text = response.text.strip()
+            try:
+                data = response.json()
+            except Exception:
+                fixed = re.sub(r'([{,])\s*([A-Za-z_][A-Za-z0-9_]*)\s*:', r'\1"\2":', text)
+                try:
+                    data = json.loads(fixed)
+                except Exception:
+                    return
+
+            if not isinstance(data, list):
+                return
+
+            for item in data:
+                if 'TBL_ID' in item:
+                    results.append({
+                        "stat_id": item['TBL_ID'],
+                        "stat_name": item.get('TBL_NM', ''),
+                        "org_id": item.get('ORG_ID', ''),
+                        "org_name": item.get('ORG_NM', ''),
+                        "category_path": path_history,
+                        "keywords": _extract_keywords(item.get('TBL_NM', '')),
+                        "available_periods": [],
+                        "description": item.get('TBL_NM', ''),
+                    })
+                elif 'LIST_ID' in item:
+                    current_path = f"{path_history} > {item.get('LIST_NM', '')}"
+                    await fetch_recursive(item['LIST_ID'], current_path, depth+1)
+
+        await fetch_recursive(category['parent_id'], category['vw_cd'])
+
+    return results
+
+
+def _extract_keywords(stat_name: str) -> list[str]:
+    stopwords = {"및", "의", "에", "별", "현황", "통계", "기준", "연도", "시도"}
+    tokens = stat_name.replace("(", " ").replace(")", " ").split()
+    return [t for t in tokens if len(t) >= 2 and t not in stopwords]
+
+
+
+async def save_to_db(catalog: list[dict], config: dict | None = None) -> int:
+    """
+    수집된 메타데이터 → kosis_stat_catalog INSERT + 임베딩 생성.
+
+    [v2 박재윤/김예슬 - 2026-04-30]
+    embedding skip 최적화:
+      이미 embedding이 있는 stat_id는 임베딩 API 호출 skip.
+      embedding IS NULL인 행만 임베딩 처리.
+      → 재실행 시 API 비용/시간 절감.
+
+    skip 판단:
+      1) INSERT ON CONFLICT DO UPDATE에서 embedding이 이미 있으면 기존 값 유지
+      2) catalog에 있지만 DB에 없는 신규 행만 임베딩 생성
+    """
+    import psycopg2
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    # [#67-D] 인라인 HCX 임베딩(get_embedding_safe) → 공용 EmbeddingClient.embed_batch 로 교체.
+    #   config.embedding({provider, model, api_key_env}) 사용. config 없으면 {} →
+    #   provider 기본 hcx + CLOVASTUDIO_API_KEY → 기존 키/동작 보존.
+    #   Semaphore(3)+429 지수백오프+zero폴백([0.0]*EMBEDDING_DIM)은
+    #   EmbeddingClient._embed_batch_hcx 에 그대로 이식돼 있음.
+    from structverify.utils.embedding_client import EmbeddingClient
+    embedder = EmbeddingClient((config or {}).get("embedding", {}))
+
+    conn = psycopg2.connect(
+        host=os.getenv("POSTGRES_HOST"),
+        port=os.getenv("POSTGRES_PORT"),
+        dbname=os.getenv("POSTGRES_DB"),
+        user=os.getenv("POSTGRES_USER"),
+        password=os.getenv("POSTGRES_PASSWORD")
+    )
+    cur = conn.cursor()
+
+    BATCH_SIZE = 100
+    for i in range(0, len(catalog), BATCH_SIZE):
+        batch = catalog[i:i+BATCH_SIZE]
+        texts = [f"{item['category_path']} {item['stat_name']}" for item in batch]
+
+        embeddings_list = await embedder.embed_batch(texts)
+
+        for item, embedding in zip(batch, embeddings_list):
+            # [v2 박재윤/김예슬] embedding skip 최적화:
+            # - 신규 행: embedding 포함 INSERT
+            # - 기존 행: stat_name/fetched_at만 UPDATE, embedding은 기존 값 유지
+            #   (ON CONFLICT DO UPDATE에서 embedding은 COALESCE로 이미 있는 값 보존)
+            cur.execute("""
+                INSERT INTO kosis_stat_catalog
+                    (stat_id, stat_name, org_id, org_name, category_path,
+                     keywords, embedding, raw_meta_json)
+                VALUES (%s, %s, %s, %s, %s, %s, %s::vector, %s::jsonb)
+                ON CONFLICT (stat_id) DO UPDATE
+                SET stat_name    = EXCLUDED.stat_name,
+                    org_name     = EXCLUDED.org_name,
+                    category_path= EXCLUDED.category_path,
+                    keywords     = EXCLUDED.keywords,
+                    raw_meta_json= EXCLUDED.raw_meta_json,
+                    fetched_at   = NOW(),
+                    embedding    = COALESCE(kosis_stat_catalog.embedding, EXCLUDED.embedding)
+            """, (
+                item["stat_id"],
+                item["stat_name"],
+                item["org_id"],
+                item["org_name"],
+                item["category_path"],
+                item["keywords"],
+                str(embedding),
+                json.dumps(item)
+            ))
+
+        conn.commit()
+        print(f"✅ {i+len(batch)}/{len(catalog)}건 저장 완료")
+
+    cur.close()
+    conn.close()
+    return len(catalog)
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    async def main():
+        logger.info("=== KOSIS 메타데이터 수집 시작 ===")
+        
+        CACHE_FILE = "kosis_catalog_cache.json"
+        
+        if os.path.exists(CACHE_FILE):
+            with open(CACHE_FILE, "r", encoding="utf-8") as f:
+                catalog = json.load(f)
+            logger.info(f"캐시에서 로드: {len(catalog)}건")
+        else:
+            catalog = await crawl_kosis_catalog()
+            with open(CACHE_FILE, "w", encoding="utf-8") as f:
+                json.dump(catalog, f, ensure_ascii=False)
+            logger.info("캐시 저장 완료")
+
+        for item in catalog[:3]:
+            print(item)
+
+        count = await save_to_db(catalog[120000:])
+        logger.info(f"=== 완료: {count}건 저장 ===")
+
+    asyncio.run(main())

structverify/adaptation/sample_builder.py

@@ -0,0 +1,149 @@
+"""
+adaptation/sample_builder.py — 학습 샘플 포맷 변환
+
+[김예슬 - 2026-04-24]
+- candidate_detection 태스크 샘플 포맷 추가
+  · instruction/input/output 필드 구조로 통일
+  · HuggingFace Dataset 호환 + NCP Tuning API JSONL 호환
+- 태스크별 샘플 수 로깅 추가
+
+[참고] Self-Instruct (Wang et al., ACL 2023)
+[참고] KnowLA (NAACL 2024)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from structverify.core.schemas import FeedbackEvent
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def build_training_samples(
+    events: list[FeedbackEvent] | None = None,
+    synthetic: list[dict[str, Any]] | None = None,
+    mode: str = "finetune",
+) -> list[dict[str, Any]]:
+    """
+    학습 데이터 → LoRA 학습 포맷 변환.
+
+    Args:
+        events: 피드백 이벤트 (mode="finetune")
+        synthetic: 합성 데이터 (mode="pretrain")
+        mode: "pretrain" | "finetune"
+
+    Returns:
+        [{"task": ..., "instruction": ..., "input": ..., "output": ...}, ...]
+    """
+    if mode == "pretrain":
+        return _build_pretrain_samples(synthetic or [])
+    elif mode == "finetune":
+        return _build_finetune_samples(events or [])
+    raise ValueError(f"미지원 모드: {mode}")
+
+
+def _build_pretrain_samples(synthetic: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    합성 데이터 → instruction-tuning 포맷 변환.
+
+    생성 태스크:
+      1) claim_to_stat      : 주장 → 관련 통계표
+      2) claim_to_schema    : 주장 → 구조화 스키마
+      3) stat_to_claim      : 통계표 → 주장 판별 (역방향)
+      4) candidate_detection: 검증 후보/비후보 분류
+    """
+    samples: list[dict[str, Any]] = []
+    task_counts: dict[str, int] = {}
+
+    for item in synthetic:
+        task = item.get("task", "")
+
+        # ── candidate detection 샘플 ──────────────────────────────────
+        if task == "candidate_detection":
+            sentence = item.get("sentence", "")
+            label    = item.get("candidate_label", False)
+
+            sample = {
+                "task": "candidate_detection",
+                "instruction": (
+                    "아래 문장이 공식 통계로 검증 가능한 수치 기반 주장인지 판단하세요.\n"
+                    'JSON으로만 답하세요: {"candidate_label": true 또는 false}'
+                ),
+                "input":  sentence,
+                "output": json.dumps({"candidate_label": label}, ensure_ascii=False),
+            }
+            samples.append(sample)
+            task_counts["candidate_detection"] = task_counts.get("candidate_detection", 0) + 1
+            continue
+
+        # ── claim/schema 샘플 ─────────────────────────────────────────
+        claim     = item.get("claim", "")
+        stat_id   = item.get("stat_id", "")
+        stat_name = item.get("stat_name", "")
+        indicator = item.get("indicator", "")
+        schema    = item.get("schema", {})
+
+        if not claim or not stat_id:
+            continue
+
+        # 태스크 1: claim_to_stat
+        samples.append({
+            "task": "claim_to_stat",
+            "instruction": "아래 주장을 검증하기 위해 필요한 KOSIS 통계표를 찾으세요.",
+            "input":  claim,
+            "output": json.dumps(
+                {"stat_id": stat_id, "stat_name": stat_name, "indicator": indicator},
+                ensure_ascii=False,
+            ),
+        })
+        task_counts["claim_to_stat"] = task_counts.get("claim_to_stat", 0) + 1
+
+        # 태스크 2: claim_to_schema
+        if schema and isinstance(schema, dict) and "raw" not in schema:
+            samples.append({
+                "task": "claim_to_schema",
+                "instruction": "아래 주장에서 검증에 필요한 핵심 정보를 추출하세요.",
+                "input":  claim,
+                "output": json.dumps(schema, ensure_ascii=False),
+            })
+            task_counts["claim_to_schema"] = task_counts.get("claim_to_schema", 0) + 1
+
+        # 태스크 3: stat_to_claim (역방향)
+        samples.append({
+            "task": "stat_to_claim",
+            "instruction": (
+                f'통계표 "{stat_name}"({stat_id})로 아래 주장을 검증할 수 있습니까?\n'
+                'JSON으로만 답하세요: {"verifiable": true 또는 false}'
+            ),
+            "input":  claim,
+            "output": json.dumps({"verifiable": True}, ensure_ascii=False),
+        })
+        task_counts["stat_to_claim"] = task_counts.get("stat_to_claim", 0) + 1
+
+    logger.info(f"사전학습 샘플: 총 {len(samples)}건")
+    logger.info(f"태스크별 분포: {task_counts}")
+    return samples
+
+
+def _build_finetune_samples(events: list[FeedbackEvent]) -> list[dict[str, Any]]:
+    """피드백 이벤트 → 추가 학습 포맷 변환"""
+    samples: list[dict[str, Any]] = []
+    for ev in events:
+        if not ev.corrected_verdict:
+            continue
+        samples.append({
+            "task": "verdict_correction",
+            "instruction": "아래 주장에 대한 검증 결과를 판정하세요.",
+            "input":  str(ev.claim_id),
+            "output": json.dumps(
+                {"verdict": ev.corrected_verdict.value},
+                ensure_ascii=False,
+            ),
+            "original_verdict": ev.original_verdict.value if ev.original_verdict else None,
+            "reviewer_note":    ev.reviewer_note,
+        })
+
+    logger.info(f"피드백 샘플: {len(samples)}건 (원본 {len(events)}건)")
+    return samples