structverify 0.3.0__py3-none-any.whl

structverify/training/tasks.py

@@ -0,0 +1,79 @@
+"""structverify.training.tasks — 파인튜닝 대상 태스크 정의 + instruction 템플릿.
+
+StructVerify 검증 파이프라인에서 LLM이 하는 하위 작업 중, *회사 도메인/스키마에 특화*될수록
+이득이 큰 3개를 학습 대상으로 잡는다:
+
+  1. schema  — claim 문장 → 구조화 추출 {indicator, value, unit, time_period}
+               (회사 용어·표기를 배우면 탐지/스키마 정확도↑)
+  2. sql     — 스키마 + claim → 집계/파생 SQL (회사 테이블 스키마를 배우면 SQL 정확도↑)
+  3. verdict — claim + 근거값 → 판정(match/mismatch) + 근거 (회사 톤/기준을 배움)
+
+각 예시는 chat 포맷(messages: system/user/assistant)으로 표준화 — TRL/unsloth가
+apply_chat_template으로 바로 학습 가능. 백엔드·모델에 안 종속.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+TASKS = ("schema", "sql", "verdict")
+
+_SYS = {
+    "schema": "너는 문서의 수치 주장에서 검증에 필요한 구조를 추출하는 분석기다. JSON만 출력한다.",
+    "sql": "너는 회사 데이터베이스로 주장을 검증하는 SQL 분석가다. 읽기전용 단일 SELECT만 출력한다.",
+    "verdict": "너는 주장과 근거 데이터를 대조해 사실 여부를 판정하는 검증관이다.",
+}
+
+
+def _schema_user(claim_text: str) -> str:
+    return (
+        "아래 문장에서 검증 대상 수치를 추출해 JSON으로.\n"
+        f'문장: "{claim_text}"\n'
+        '{"indicator": "지표명", "value": 숫자, "unit": "단위", "time_period": "시점 또는 null", '
+        '"population": "대상/지역 또는 null"}'
+    )
+
+
+def _sql_user(indicator: str, schema_hint: str, claim_text: str, dialect: str = "snowflake") -> str:
+    return (
+        f"[{dialect}] 아래 지표를 검증할 단일 SELECT 집계 쿼리 하나를 작성.\n"
+        f"[스키마]\n{schema_hint}\n"
+        f"[검증할 지표] {indicator}\n"
+        f'[주장 원문] "{claim_text}"\n'
+        "결과는 스칼라 값 1개. 비율/증감율이면 %로 직접 계산."
+    )
+
+
+def _verdict_user(claim_text: str, evidence_value: Any, evidence_unit: str) -> str:
+    return (
+        "주장과 근거 데이터를 대조해 판정.\n"
+        f'주장: "{claim_text}"\n'
+        f"근거 데이터: {evidence_value} {evidence_unit}\n"
+        '판정(match/mismatch/unverifiable)과 한 줄 근거를 JSON으로: '
+        '{"verdict": "...", "reason": "..."}'
+    )
+
+
+def build_example(task: str, **kw: Any) -> dict:
+    """(task, 필드) → chat 포맷 학습 예시 dict.
+
+    schema:  claim_text, output(JSON str)
+    sql:     indicator, schema_hint, claim_text, output(SQL str), [dialect]
+    verdict: claim_text, evidence_value, evidence_unit, output(JSON str)
+    """
+    if task == "schema":
+        user = _schema_user(kw["claim_text"])
+    elif task == "sql":
+        user = _sql_user(kw["indicator"], kw["schema_hint"], kw["claim_text"],
+                         kw.get("dialect", "snowflake"))
+    elif task == "verdict":
+        user = _verdict_user(kw["claim_text"], kw["evidence_value"], kw["evidence_unit"])
+    else:
+        raise ValueError(f"미지원 task: {task!r} (schema/sql/verdict 중 하나)")
+    return {
+        "task": task,
+        "messages": [
+            {"role": "system", "content": _SYS[task]},
+            {"role": "user", "content": user},
+            {"role": "assistant", "content": str(kw["output"]).strip()},
+        ],
+    }

structverify/utils/embedding_client.py

@@ -0,0 +1,248 @@
+"""structverify.utils.embedding_client — 공용 임베딩 클라이언트 (#67-A 골격).
+
+config.embedding({provider, model, api_key_env, base_url?})을 읽어 provider 분기.
+utils/llm_client.py 의 provider dispatch 패턴을 따름.
+이번 단계는 *골격만* — 실제 HTTP 호출(_embed_hcx 등)은 NotImplementedError 스텁.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+import httpx
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+EMBEDDING_DIM = 1024  # HCX-EMB-V2 차원 (memory/embedder.py:26 과 동일)
+
+# HCX 호출 수치 — 일단 상수, 나중에 config화 여지 (kosis_crawler 기준)
+_HCX_TIMEOUT = 30          # 초
+_BATCH_CONCURRENCY = 3     # asyncio.Semaphore 동시 호출 수
+_BATCH_MAX_RETRY = 5       # 429 등 재시도 횟수
+
+# provider별 기본값 (config 미지정 시). base_url은 다음 단계 호출에서 사용.
+_PROVIDER_DEFAULTS: dict[str, dict[str, str]] = {
+    "hcx": {
+        "api_key_env": "CLOVASTUDIO_API_KEY",
+        "base_url": "https://clovastudio.stream.ntruss.com/v1/api-tools/embedding/v2",
+    },
+    "openai": {
+        "api_key_env": "OPENAI_API_KEY",
+        "base_url": "https://api.openai.com/v1",
+        "model": "text-embedding-3-small",
+    },
+    "upstage": {
+        "api_key_env": "UPSTAGE_API_KEY",
+        "base_url": "https://api.upstage.ai/v1",
+        # Upstage 임베딩: 검색어=embedding-query, 문서색인=embedding-passage (4096-dim).
+        # (구 solar-embedding-1-large 는 무효). 기본은 query — 문서 색인 시 config로 passage 지정.
+        "model": "embedding-query",
+    },
+}
+
+
+def _load_async_openai():
+    """openai SDK AsyncOpenAI 로드. 없으면 None(httpx 폴백). 테스트 monkeypatch 지점."""
+    try:
+        from openai import AsyncOpenAI
+        return AsyncOpenAI
+    except ImportError:
+        return None
+
+
+class EmbeddingClient:
+    """텍스트 → 임베딩 벡터. provider(hcx/openai/upstage) 분기.
+
+    config 예 (config/default.yaml의 embedding 섹션):
+        provider: "hcx"
+        model: "HCX-EMB-V2"
+        api_key_env: "NCP_API_KEY"
+        base_url: "..."            # 선택 (provider 기본값 있음)
+    """
+
+    def __init__(self, config: dict | None = None):
+        self.config = config or {}
+        # provider 디폴트는 두지 않되, 없으면 "hcx" (기존 동작 보존)
+        self.provider = self.config.get("provider", "hcx")
+        _defaults = _PROVIDER_DEFAULTS.get(self.provider, {})
+        # [#64 후속] provider만 바꿔도 동작하도록, provider!=hcx인데 config 값이 HCX 잔재면 무시.
+        #   (default.yaml embedding: model=HCX-EMB-V2, api_key_env=NCP_API_KEY 이 남아있어도)
+        _user_model = self.config.get("model")
+        if _user_model and self.provider != "hcx" and str(_user_model).upper().startswith("HCX"):
+            _user_model = None
+        self.model = _user_model or _defaults.get("model")
+        # 키는 *값*이 아니라 api_key_env *이름*으로 보관 → 호출 시점에 os.environ 조회 (lazy)
+        _user_key_env = self.config.get("api_key_env")
+        if _user_key_env and self.provider != "hcx" and _user_key_env in ("NCP_API_KEY", "CLOVASTUDIO_API_KEY"):
+            _user_key_env = None
+        self._api_key_env = _user_key_env or _defaults.get("api_key_env", "")
+        # [BYO] 테넌트 키 직접 주입 (env 대신). SaaS 사용자별 키 주입용.
+        self._direct_api_key = self.config.get("_direct_api_key") or ""
+        self.base_url = self.config.get("base_url") or _defaults.get("base_url", "")
+        logger.info(
+            f"[EmbeddingClient] provider={self.provider}, model={self.model!r}, "
+            f"api_key_env={self._api_key_env!r}"
+        )
+
+    @property
+    def api_key(self) -> str:
+        """직접 주입된 키(_direct_api_key) 우선, 없으면 api_key_env 환경변수 값."""
+        if self._direct_api_key:
+            return self._direct_api_key
+        if not self._api_key_env:
+            return ""
+        return os.environ.get(self._api_key_env, "")
+
+    # ── 공개 인터페이스 ──
+
+    async def embed(self, text: str, role: str = "query") -> list[float] | None:
+        """단건 임베딩 — provider 분기.
+
+        role: "query"(검색어) | "passage"(문서/청크 색인). upstage는 role별 모델
+        (embedding-query / embedding-passage)로 비대칭 검색을 지원 → 검색 정확도↑.
+        hcx/openai는 단일 모델(role 무시).
+        """
+        if self.provider == "hcx":
+            return await self._embed_hcx(text)
+        elif self.provider == "openai":
+            return await self._embed_openai(text)
+        elif self.provider == "upstage":
+            return await self._embed_upstage(text, role)
+        raise ValueError(f"미지원 embedding provider: {self.provider}")
+
+    async def embed_batch(self, texts: list[str], role: str = "passage") -> list[list[float]]:
+        """배치 임베딩 — provider 분기. role은 upstage 비대칭(query/passage)에만 적용."""
+        if self.provider == "hcx":
+            return await self._embed_batch_hcx(texts)
+        elif self.provider == "openai":
+            return await self._embed_batch_openai(texts)
+        elif self.provider == "upstage":
+            return await self._embed_batch_upstage(texts, role)
+        raise ValueError(f"미지원 embedding provider: {self.provider}")
+
+    # ── provider별 실제 호출 (다음 단계 구현) ──
+
+    async def _embed_hcx(self, text: str) -> list[float] | None:
+        # catalog_search._get_embedding 이식. 키 없으면 None, 예외 → 로그 후 None.
+        if not self.api_key:
+            return None
+        try:
+            async with httpx.AsyncClient(timeout=_HCX_TIMEOUT) as client:
+                resp = await client.post(
+                    self.base_url,  # config base_url 우선 (기본=hcx 엔드포인트)
+                    headers={
+                        "Authorization": f"Bearer {self.api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json={"text": text},
+                )
+                return resp.json()["result"]["embedding"]
+        except Exception as e:  # noqa: BLE001
+            logger.debug(f"[EmbeddingClient] hcx 임베딩 실패: {e}")
+            return None
+
+    async def _embed_openai(self, text: str) -> list[float] | None:
+        res = await self._embed_openai_compatible([text])
+        return res[0] if res else None
+
+    async def _embed_upstage(self, text: str, role: str = "query") -> list[float] | None:
+        # upstage 비대칭: 사용자가 model 미지정이면 role별 기본(embedding-query/passage).
+        model = self.model
+        if not self.config.get("model"):
+            model = "embedding-passage" if role == "passage" else "embedding-query"
+        res = await self._embed_openai_compatible([text], model_override=model)
+        return res[0] if res else None
+
+    async def _embed_openai_compatible(
+        self, inputs: list[str], model_override: str | None = None,
+    ) -> list[list[float]] | None:
+        """openai·upstage 공유. inputs(list) → 임베딩 list. 키 없으면 None, 예외→로그→None.
+
+        dimensions=EMBEDDING_DIM(1024) 강제 — pgvector vector(1024) 고정에 맞춤.
+        ⚠️ upstage(solar-embedding-1-large)는 dimensions 미지원일 수 있음 → 원차원(예: 4096)
+           반환 가능. 그 경우 아래 길이 검증에서 경고하고 그대로 반환(호출부/DB가 불일치 판단:
+           pgvector vector(1024)에 INSERT 시 차원 안 맞으면 거부됨).
+        """
+        if not self.api_key:
+            return None
+        try:
+            _AsyncOpenAI = _load_async_openai()
+            if _AsyncOpenAI is not None:
+                # OpenAI 공식 SDK 경로
+                client = _AsyncOpenAI(api_key=self.api_key, base_url=self.base_url)
+                # dimensions는 openai만 지원 (upstage embedding은 미지원 → 보내면 에러).
+                _kw = {"model": model_override or self.model, "input": inputs}
+                if self.provider == "openai":
+                    _kw["dimensions"] = EMBEDDING_DIM
+                resp = await client.embeddings.create(**_kw)
+                vectors = [d.embedding for d in resp.data]
+            else:
+                # SDK 없으면 httpx 로 POST {base_url}/embeddings
+                async with httpx.AsyncClient(timeout=_HCX_TIMEOUT) as client:
+                    resp = await client.post(
+                        f"{self.base_url.rstrip('/')}/embeddings",
+                        headers={
+                            "Authorization": f"Bearer {self.api_key}",
+                            "Content-Type": "application/json",
+                        },
+                        json={
+                            "model": model_override or self.model,
+                            "input": inputs,
+                            # dimensions는 openai만 지원 (upstage 미지원)
+                            **({"dimensions": EMBEDDING_DIM} if self.provider == "openai" else {}),
+                        },
+                    )
+                    data = resp.json()
+                    vectors = [d["embedding"] for d in data["data"]]
+            if vectors and len(vectors[0]) != EMBEDDING_DIM:
+                logger.warning(
+                    f"[EmbeddingClient] {self.provider} 임베딩 차원 {len(vectors[0])} "
+                    f"≠ EMBEDDING_DIM({EMBEDDING_DIM}) — pgvector(1024) 불일치 위험"
+                )
+            return vectors
+        except Exception as e:  # noqa: BLE001
+            logger.debug(f"[EmbeddingClient] {self.provider} 임베딩 실패: {e}")
+            return None
+
+    async def _embed_batch_hcx(self, texts: list[str]) -> list[list[float]]:
+        # kosis_crawler.get_embedding_safe 이식: Semaphore + 429 지수백오프 + 제로벡터 폴백.
+        if not self.api_key:
+            logger.warning("[EmbeddingClient] api_key 없음 → batch 제로벡터 반환")
+            return [[0.0] * EMBEDDING_DIM for _ in texts]
+        sem = asyncio.Semaphore(_BATCH_CONCURRENCY)
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        async def _one(client: httpx.AsyncClient, text: str) -> list[float]:
+            async with sem:
+                for retry in range(_BATCH_MAX_RETRY):
+                    resp = await client.post(
+                        self.base_url, headers=headers, json={"text": text},
+                    )
+                    data = resp.json()
+                    if data.get("result") is not None:
+                        return data["result"]["embedding"]
+                    if resp.status_code == 429:
+                        await asyncio.sleep(2 ** retry)
+                return [0.0] * EMBEDDING_DIM
+
+        async with httpx.AsyncClient(timeout=_HCX_TIMEOUT) as client:
+            return list(await asyncio.gather(*[_one(client, t) for t in texts]))
+
+    async def _embed_batch_openai(self, texts: list[str]) -> list[list[float]]:
+        # OpenAI는 input=list 배치 지원 → 한 번 호출. 실패 시 제로벡터 폴백(hcx와 동일 규약).
+        res = await self._embed_openai_compatible(texts)
+        return res if res is not None else [[0.0] * EMBEDDING_DIM for _ in texts]
+
+    async def _embed_batch_upstage(self, texts: list[str], role: str = "passage") -> list[list[float]]:
+        # 인덱싱은 passage 모델(문서), 검색은 query. 사용자가 model 지정하면 그대로.
+        model = self.model
+        if not self.config.get("model"):
+            model = "embedding-passage" if role == "passage" else "embedding-query"
+        res = await self._embed_openai_compatible(texts, model_override=model)
+        return res if res is not None else [[0.0] * EMBEDDING_DIM for _ in texts]