structverify 0.3.0__py3-none-any.whl

structverify/adaptation/synthetic_generator.py

@@ -0,0 +1,320 @@
+"""
+adaptation/synthetic_generator.py — 합성 학습 데이터 자동 생성 (Step 0-2)
+
+[김예슬 - 2026-04-24]
+- CANDIDATE_DETECTION_PROMPT 추가:
+  · positive: 통계표에서 파생된 검증 가능 수치 주장
+  · negative: 의견/일정/감상 등 검증 불가 문장
+- _generate_candidate_samples(): candidate detection 학습 데이터 생성
+- generate_synthetic_pairs()에 candidate detection 샘플 통합
+- _filter_quality(): candidate 샘플 필터 조건 추가
+
+[참고] Self-Instruct (Wang et al., ACL 2023)
+[참고] Textbooks Are All You Need (Gunasekar et al., Microsoft, 2023)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from structverify.utils.llm_client import LLMClient
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# ── 프롬프트 ──────────────────────────────────────────────────────────────
+
+CLAIM_GENERATION_PROMPT = """당신은 한국 뉴스 기자입니다.
+아래 공식 통계표 정보를 보고, 이 통계표로 검증할 수 있는 뉴스 주장 {n}개를 생성하세요.
+
+통계표 ID: {stat_id}
+통계표명: {stat_name}
+발행기관: {org_name}
+분류: {category_path}
+관련 키워드: {keywords}
+
+규칙:
+- 실제 뉴스에 나올법한 자연스러운 한국어 문장
+- 반드시 구체적인 수치(%, 만명, 억원, ha 등) 포함
+- 주장 유형 다양하게: 증가/감소/규모/비교 중 섞어서
+- 검증 가능한 사실적 주장만 (의견/전망 제외)
+
+JSON 배열로만 답하세요:
+[
+  {{
+    "claim": "뉴스에 나올법한 주장 문장 (수치 포함)",
+    "indicator": "검증할 핵심 지표명",
+    "stat_id": "{stat_id}",
+    "claim_type": "increase|decrease|scale|comparison",
+    "expected_unit": "%, 만명, ha 등"
+  }}
+]"""
+
+SCHEMA_GENERATION_PROMPT = """아래 뉴스 주장에서 검증에 필요한 핵심 정보를 추출하세요.
+
+주장: "{claim}"
+관련 통계표: {stat_name} ({stat_id})
+
+JSON으로만 답하세요:
+{{
+  "indicator": "측정 지표",
+  "time_period": "기준 시점",
+  "unit": "단위",
+  "population": "대상 범위",
+  "value": 수치 또는 null,
+  "stat_id": "{stat_id}"
+}}"""
+
+CANDIDATE_DETECTION_PROMPT = """아래 통계표 정보를 바탕으로 candidate detection 학습 데이터를 생성하세요.
+
+통계표: {stat_name} ({stat_id})
+키워드: {keywords}
+
+다음 두 종류의 문장을 각각 {n}개씩 생성하세요:
+
+[positive] 이 통계표로 검증 가능한 수치 기반 주장:
+  - 구체적인 수치/비율/규모 포함
+  - 공식 통계와 대조 가능한 사실 주장
+
+[negative] 검증 불가능한 문장 (다양한 유형으로):
+  - 의견/감상 (예: "정책이 아쉽다")
+  - 단순 이벤트 일정 (예: "박람회가 10월에 열린다")
+  - 미래 전망 (예: "줄어들 것으로 보인다")
+  - 추상적 주장 (예: "문제가 심각하다")
+
+JSON으로만 답하세요:
+{{
+  "positives": ["문장1", "문장2", ...],
+  "negatives": ["문장1", "문장2", ...]
+}}"""
+
+
+# ── 메인 함수 ─────────────────────────────────────────────────────────────
+
+async def generate_synthetic_pairs(
+    catalog: list[dict[str, Any]],
+    llm: LLMClient,
+    claims_per_table: int = 3,
+    max_tables: int | None = None,
+) -> list[dict[str, Any]]:
+    """
+    KOSIS 메타데이터 → LLM Self-Instruct → 학습 쌍 자동 생성.
+
+    생성 태스크:
+      1) claim_to_stat   : 주장 → 관련 통계표 매핑
+      2) claim_to_schema : 주장 → 구조화 스키마 추출
+      3) stat_to_claim   : 통계표 → 주장 판별 (역방향)
+      4) candidate_pos   : 검증 후보 문장 (positive)
+      5) candidate_neg   : 검증 비후보 문장 (negative)
+    """
+    tables = catalog[:max_tables] if max_tables else catalog
+    logger.info(f"합성 데이터 생성: {len(tables)}개 통계표 × {claims_per_table}쌍")
+
+    all_pairs: list[dict[str, Any]] = []
+    success, fail = 0, 0
+
+    for idx, table in enumerate(tables):
+        try:
+            # claim/schema 쌍 생성
+            claims = await _generate_claims(llm, table, claims_per_table)
+            for claim_data in claims:
+                schema = await _generate_schema(llm, claim_data, table)
+                all_pairs.append({
+                    "task":         "claim_to_stat",
+                    "claim":        claim_data.get("claim", ""),
+                    "stat_id":      table["stat_id"],
+                    "stat_name":    table["stat_name"],
+                    "indicator":    claim_data.get("indicator", ""),
+                    "claim_type":   claim_data.get("claim_type", ""),
+                    "schema":       schema,
+                    "source_table": table,
+                })
+
+            # candidate detection 쌍 생성
+            candidate_samples = await _generate_candidate_samples(
+                llm, table, n=claims_per_table
+            )
+            all_pairs.extend(candidate_samples)
+
+            success += 1
+            if (idx + 1) % 50 == 0:
+                logger.info(f"진행: {idx + 1}/{len(tables)} ({len(all_pairs)}쌍)")
+
+        except Exception as e:
+            fail += 1
+            logger.warning(f"통계표 {table.get('stat_id')} 실패: {e}")
+
+    filtered = _filter_quality(all_pairs)
+    logger.info(
+        f"합성 데이터 완료: 성공 {success}개, 실패 {fail}개 | "
+        f"생성 {len(all_pairs)}쌍 → 필터 후 {len(filtered)}쌍"
+    )
+    return filtered
+
+
+# ── 내부 생성 함수 ────────────────────────────────────────────────────────
+
+async def _generate_claims(
+    llm: LLMClient, table: dict, n: int
+) -> list[dict[str, Any]]:
+    """통계표 → 뉴스 주장 N개 생성"""
+    prompt = CLAIM_GENERATION_PROMPT.format(
+        n=n,
+        stat_id=table.get("stat_id", ""),
+        stat_name=table.get("stat_name", ""),
+        org_name=table.get("org_name", ""),
+        category_path=table.get("category_path", ""),
+        keywords=", ".join(table.get("keywords", [])),
+    )
+    result = await llm.generate_json(
+        prompt=prompt,
+        system_prompt="한국 뉴스 기자. JSON 배열로만 답하세요.",
+    )
+    if isinstance(result, list):
+        return result
+    if isinstance(result, dict) and "raw" not in result:
+        return [result]
+    return []
+
+
+async def _generate_schema(
+    llm: LLMClient, claim_data: dict, table: dict
+) -> dict[str, Any]:
+    """주장 → 검증 스키마 추출"""
+    prompt = SCHEMA_GENERATION_PROMPT.format(
+        claim=claim_data.get("claim", ""),
+        stat_name=table.get("stat_name", ""),
+        stat_id=table.get("stat_id", ""),
+    )
+    try:
+        return await llm.generate_json(
+            prompt=prompt,
+            system_prompt="통계 분석 전문가. JSON으로만 답하세요.",
+        )
+    except Exception:
+        return {}
+
+
+async def _generate_candidate_samples(
+    llm: LLMClient, table: dict, n: int = 3
+) -> list[dict[str, Any]]:
+    """
+    통계표 기반 candidate detection 학습 데이터 생성.
+    positive/negative 쌍으로 candidate_scorer 학습에 사용.
+    """
+    prompt = CANDIDATE_DETECTION_PROMPT.format(
+        stat_name=table.get("stat_name", ""),
+        stat_id=table.get("stat_id", ""),
+        keywords=", ".join(table.get("keywords", [])),
+        n=n,
+    )
+    try:
+        result = await llm.generate_json(
+            prompt=prompt,
+            system_prompt="학습 데이터 생성기. JSON으로만 답하세요.",
+        )
+    except Exception as e:
+        logger.warning(f"candidate 샘플 생성 실패 ({table.get('stat_id')}): {e}")
+        return []
+
+    samples = []
+    stat_id   = table.get("stat_id", "")
+    stat_name = table.get("stat_name", "")
+
+    for sent in result.get("positives", []):
+        if isinstance(sent, str) and sent.strip():
+            samples.append({
+                "task":            "candidate_detection",
+                "sentence":        sent.strip(),
+                "candidate_label": True,
+                "stat_id":         stat_id,
+                "stat_name":       stat_name,
+            })
+
+    for sent in result.get("negatives", []):
+        if isinstance(sent, str) and sent.strip():
+            samples.append({
+                "task":            "candidate_detection",
+                "sentence":        sent.strip(),
+                "candidate_label": False,
+                "stat_id":         stat_id,
+                "stat_name":       stat_name,
+            })
+
+    return samples
+
+
+# ── 품질 필터링 ───────────────────────────────────────────────────────────
+
+import re
+_NUMERIC_RE = re.compile(r"\d")
+
+
+def _filter_quality(pairs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    합성 데이터 품질 필터링.
+
+    claim_to_stat 필터:
+      - 주장 10자 미만 제거
+      - 수치 미포함 제거
+      - stat_id 누락 제거
+      - 중복 제거
+
+    candidate_detection 필터:
+      - 문장 5자 미만 제거
+      - positive는 수치 필수
+    """
+    seen: set[str] = set()
+    filtered: list[dict[str, Any]] = []
+
+    for pair in pairs:
+        task = pair.get("task", "")
+
+        if task == "candidate_detection":
+            sentence = pair.get("sentence", "").strip()
+            if len(sentence) < 5:
+                continue
+            if pair.get("candidate_label") is True and not _NUMERIC_RE.search(sentence):
+                continue
+            key = f"cand:{sentence}"
+            if key in seen:
+                continue
+            seen.add(key)
+            filtered.append(pair)
+
+        else:
+            claim = pair.get("claim", "").strip()
+            if len(claim) < 10:
+                continue
+            if not _NUMERIC_RE.search(claim):
+                continue
+            if not pair.get("stat_id"):
+                continue
+            key = f"claim:{claim}"
+            if key in seen:
+                continue
+            seen.add(key)
+            filtered.append(pair)
+
+    return filtered
+
+
+async def save_synthetic_data(
+    pairs: list[dict[str, Any]],
+    output_path: str = "ml/data/synthetic_pretrain.jsonl",
+) -> None:
+    """합성 데이터 JSONL 저장"""
+    import os
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        for pair in pairs:
+            f.write(json.dumps(pair, ensure_ascii=False) + "\n")
+
+    task_counts: dict[str, int] = {}
+    for p in pairs:
+        t = p.get("task", "unknown")
+        task_counts[t] = task_counts.get(t, 0) + 1
+
+    logger.info(f"합성 데이터 저장: {output_path} ({len(pairs)}건)")
+    logger.info(f"태스크별 분포: {task_counts}")

structverify/adaptation/update_embeddings.py

@@ -0,0 +1,178 @@
+"""
+# 수정자: 박재윤
+# 수정 날짜: 2026-04-30
+# 수정 내용: KOSIS 딥 메타데이터 수집 및 벡터 DB 재구축
+
+# [DONE] KOSIS 메타 API로 항목명/분류명/단위 수집 후 임베딩 텍스트 보강
+# [DONE] 지자체/지역 통계 제외 (197,956건만 처리)
+# [DONE] 세마포어 기반 병렬 처리 (API=5, HCX=3)
+# [DONE] prdSe Y→M→Q 순회 + err:20 objL 에스컬레이션
+# [DONE] 429/타임아웃 재시도 로직 (최대 5회)
+# [DONE] 배치 단위 DB UPDATE (ON CONFLICT 없이 순수 UPDATE)
+# [TODO] 실패 건(None 반환) 별도 재시도 스크립트 작성
+# [TODO] err:21 테이블 대상 별도 파라미터 방식 시도
+# [TODO] 완료 후 factcheck_test.py 재실행 및 정확도 검증
+"""
+
+import os
+import json
+import asyncio
+import httpx
+import psycopg2
+from psycopg2.extras import execute_values
+from dotenv import load_dotenv
+
+from structverify.core.config_loader import load_config
+from structverify.utils.embedding_client import EmbeddingClient
+
+# 환경변수 로드
+load_dotenv()
+
+# [#67-D] HCX_API_KEY 모듈 전역 제거 → EmbeddingClient(config.embedding)로 일원화.
+KOSIS_API_KEY = os.getenv("KOSIS_API_KEY")
+PG_CONN = {
+    "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")
+}
+
+CATALOG_JSON_FILE = "kosis_catalog_cache.json"
+
+async def fetch_kosis_deep_meta(client, org_id, tbl_id):
+    """KOSIS API 상세 정보 조회 (Y->M->Q 순회 및 에러 핸들링 강화)"""
+    
+    # 연간(Y), 월간(M), 분기(Q) 순으로 시도
+    for prdSe in ["Y", "M", "Q"]:
+        base_params = {
+            "method": "getList", "apiKey": KOSIS_API_KEY, "format": "json", "jsonVD": "Y",
+            "orgId": org_id, "tblId": tbl_id, "itmId": "ALL", "objL1": "ALL",
+            "prdSe": prdSe, "newEstPrdCnt": "1"
+        }
+
+        try:
+            resp = await client.get("https://kosis.kr/openapi/Param/statisticsParameterData.do", params=base_params, timeout=15)
+            data = resp.json()
+
+            # 에러 20 (세부항목 누락) 발생 시 파라미터 에스컬레이션
+            if isinstance(data, dict) and data.get("err") == "20":
+                for level in range(2, 9):
+                    base_params[f"objL{level}"] = "ALL"
+                    resp = await client.get("https://kosis.kr/openapi/Param/statisticsParameterData.do", params=base_params, timeout=15)
+                    data = resp.json()
+                    if not (isinstance(data, dict) and data.get("err") == "20"):
+                        break
+
+            # 에러 30 (데이터 없음) -> 다음 시점(M, Q)으로 재시도
+            if isinstance(data, dict) and data.get("err") == "30":
+                continue 
+
+            # 에러 31 (너무 큼) 등 기타 에러 -> 과감히 포기 (기본 이름으로 임베딩)
+            if isinstance(data, dict) and "err" in data:
+                # 에러 로그가 너무 많이 뜨면 불편하니 31번은 조용히 넘깁니다.
+                if data.get("err") != "31": 
+                    print(f"⚠️ KOSIS API 에러 [{tbl_id}]: {data.get('err')} - {data.get('errMsg')}")
+                return None
+
+            # 정상 데이터 파싱
+            items, categories, units = set(), set(), set()
+            for row in data:
+                if row.get("ITM_NM"): items.add(row["ITM_NM"])
+                if row.get("UNIT_NM"): units.add(row["UNIT_NM"])
+                for key in row.keys():
+                    if "OBJ_NM" in key and row[key]:
+                        categories.add(row[key])
+
+            return {
+                "items": ", ".join(items)[:200],
+                "categories": ", ".join(categories)[:300],
+                "units": ", ".join(units)[:50]
+            }
+
+        except Exception as e:
+            # 타임아웃 등 통신 오류 시 조용히 넘김
+            return None
+
+    # Y, M, Q 다 돌았는데도 없으면 None 반환
+    return None
+
+async def process_single_table(client, item, semaphore_api, semaphore_hcx, embedder=None):
+    # [#67-D] 인라인 HCX 임베딩 → 공용 EmbeddingClient.embed 로 교체.
+    #   embed()는 실패 시 None → 기존 'skip on failure'(None은 update_records에서 제외) 보존.
+    #   embedder 미주입 시 기본 EmbeddingClient (hcx + CLOVASTUDIO_API_KEY) → 기존 키 동작.
+    #   주의: 단건 embed 경로엔 429 재시도가 없음(_embed_batch_hcx에만 이식). 재실행형
+    #         스크립트라 이번 run에서 누락(skip)된 표는 다음 run(embedding IS NULL)이 보강.
+    if embedder is None:
+        embedder = EmbeddingClient({})
+
+    async with semaphore_api:
+        meta = await fetch_kosis_deep_meta(client, item["org_id"], item["stat_id"])
+
+    embed_text = f"{item['category_path']} > {item['stat_name']}"
+    if meta:
+        embed_text += f" | 항목: {meta['items']} | 분류: {meta['categories']} | 단위: {meta['units']}"
+
+    async with semaphore_hcx:
+        vec = await embedder.embed(embed_text)
+    if vec is None:
+        return None
+    return (vec, item["stat_id"])
+
+async def main():
+    print("🚀 KOSIS 딥 메타데이터 수집 및 벡터 DB 재구축 시작 (안정화 버전)")
+
+    # [#67-D] config.embedding 으로 EmbeddingClient 구성 (없으면 {} → hcx + CLOVASTUDIO_API_KEY)
+    embedder = EmbeddingClient(load_config().get("embedding", {}))
+
+    with open(CATALOG_JSON_FILE, 'r', encoding='utf-8') as f:
+        catalog = json.load(f)
+
+    # 타겟 필터링 유지
+    target_catalog = [
+        item for item in catalog
+        if "지자체" not in item.get("category_path", "") and "지역" not in item.get("category_path", "")
+    ]
+
+    # ⭐ 핵심 수정: 동시 접속 수 대폭 축소 (서버 부하 방지)
+    semaphore_api = asyncio.Semaphore(5)   # 기존 15 -> 5 로 축소 (KOSIS 서버 과부하 방지)
+    semaphore_hcx = asyncio.Semaphore(3)   # 기존 5 -> 3 로 축소 (안정적인 임베딩 요청)
+
+    conn = psycopg2.connect(**PG_CONN)
+    cur = conn.cursor()
+
+    BATCH_SIZE = 100
+    async with httpx.AsyncClient(timeout=30) as client:
+        # 이전에 실패했던 지점(예: 600번)부터 다시 시작할 수 있도록 인덱스를 직접 설정할 수 있습니다.
+        # 처음부터 다시 하려면 0으로 두세요.
+        start_index = 0
+
+        for i in range(start_index, len(target_catalog), BATCH_SIZE):
+            batch = target_catalog[i:i+BATCH_SIZE]
+
+            tasks = [process_single_table(client, item, semaphore_api, semaphore_hcx, embedder) for item in batch]
+            results = await asyncio.gather(*tasks)
+
+            update_records = [res for res in results if res is not None]
+
+            if update_records:
+                try:
+                    execute_values(
+                        cur,
+                        "UPDATE kosis_stat_catalog SET embedding = data.vector::vector FROM (VALUES %s) AS data(vector, stat_id) WHERE kosis_stat_catalog.stat_id = data.stat_id",
+                        update_records
+                    )
+                    conn.commit()
+                except Exception as e:
+                    print(f"❌ DB 업데이트 실패 (배치 {i}~{i+BATCH_SIZE}): {e}")
+                    conn.rollback() # DB 업데이트 실패 시 롤백
+
+            print(f"🔄 처리 중: {i + len(batch)} / {len(target_catalog)} 건 (성공: {len(update_records)}건)")
+            await asyncio.sleep(1)  # ← 추가
+
+    cur.close()
+    conn.close()
+    print("🎉 완료되었습니다!")
+
+if __name__ == "__main__":
+    asyncio.run(main())

structverify/agent/__init__.py

@@ -0,0 +1,21 @@
+"""
+structverify.agent — Agentic 검증 시스템.
+
+기존 (v6.14까지):
+  - builder_agent: 카탈로그 구축 agent
+  - runtime_agent: 검증 파이프라인 오케스트레이션 (Step 3~9)
+
+Phase A 추가:
+  - workspace: Agent 작업 공간 (파일 시스템 추상화)
+  - memory:    멀티턴 메모리 (markdown append)
+  - schemas:   Plan / PlanStep / Observation / AgentVerdict 데이터 모델
+
+Phase B 예정: tools/ (catalog_search, fetch_evidence, calculate, finish)
+Phase C 예정: planner.py (Plan Agent)
+Phase D 예정: reflector.py + loop.py (멀티턴 실행)
+Phase E 예정: verifier 확장 — 여러 data point 받아 계산
+Phase F 예정: runtime_agent.py 통합 (Step 7-8을 agent_loop로 교체)
+"""
+
+# 기존 export는 그대로 (수정 X)
+# 새 모듈은 import하지 않음 (사용자가 명시적으로 from structverify.agent.workspace import ...)