structverify 0.3.0__py3-none-any.whl

structverify/agent/builder_agent.py

@@ -0,0 +1,226 @@
+"""
+agent/builder_agent.py — Agent B: 도메인 적응 관리자
+
+[김예슬 - 2026-04-24]
+pretrain_domain() 파이프라인 완성:
+  1) KOSIS 메타 수집 (kosis_crawler — httpx 실제 호출)
+  2) 합성 데이터 생성 (synthetic_generator — claim/schema + candidate detection)
+  3) 학습 포맷 변환 (sample_builder — 5가지 태스크 포맷)
+  4) NCP Tuning API 학습 (adapter_trainer — Object Storage + Tuning API + polling)
+  5) 평가 → 합격 시 배포 (model.yaml 업데이트)
+
+[경로 1] 사전학습 pretrain_domain():
+  KOSIS 메타 → Self-Instruct 합성 → JSONL 변환 → NCP Object Storage
+  → Tuning API → polling → 평가 → domain-packs/{domain}/model.yaml 배포
+
+[경로 2] 피드백 학습 _trigger_adaptation():
+  Human Review 수정 결과 → finetune 포맷 → 추가 NCP Tuning → 평가 → 배포
+"""
+from __future__ import annotations
+
+from structverify.core.schemas import DomainPack, FeedbackEvent
+from structverify.adaptation.feedback_store import FeedbackStore
+from structverify.adaptation.kosis_crawler import crawl_kosis_catalog, save_to_db, is_catalog_ready
+from structverify.adaptation.sample_builder import build_training_samples
+from structverify.adaptation.synthetic_generator import generate_synthetic_pairs, save_synthetic_data
+from structverify.adaptation.adapter_trainer import AdapterTrainer
+from structverify.utils.llm_client import LLMClient
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class BuilderAgent:
+    """
+    Agent B: 도메인 적응 관리자.
+
+    - pretrain_domain(): 서비스 전 사전학습 (1회)
+    - log_feedback():    운영 피드백 기록
+    - _trigger_adaptation(): 피드백 누적 시 추가 학습
+    """
+
+    def __init__(self, config: dict | None = None):
+        self.config         = config or {}
+        self.feedback_store = FeedbackStore(config=self.config)
+        self.trainer        = AdapterTrainer(config=self.config)
+        self.llm            = LLMClient(config=self.config.get("llm", {}))
+        adapt_cfg           = self.config.get("adaptation", {})
+        self.threshold      = int(adapt_cfg.get("feedback_threshold", 10))
+        self.eval_min_score = float(adapt_cfg.get("eval_min_score", 0.85))
+
+    async def pretrain_domain(
+        self,
+        domain: str,
+        max_tables: int | None = None,
+    ) -> str | None:
+        """
+        도메인 사전학습 전체 파이프라인 실행.
+
+        Args:
+            domain:     학습할 도메인 (예: "news", "agriculture")
+            max_tables: 처리할 최대 KOSIS 통계표 수 (None=전체)
+
+        Returns:
+            배포된 adapter_path 또는 None (실패/평가 미통과)
+        """
+        logger.info(f"[Agent B] === 사전학습 시작: {domain} ===")
+
+        # ── Step 0-1: KOSIS 메타데이터 수집 ──────────────────────────
+        # [v2 김예슬 - 2026-04-30] catalog.rebuild=false이고 DB에 이미 데이터 있으면 skip
+        # config.yaml:
+        #   kosis.catalog.rebuild: false   # true이면 강제 재수집
+        #   kosis.catalog.min_rows: 1000   # 이 수 이상이면 구축됨으로 판단
+        catalog_cfg  = self.config.get("kosis", {}).get("catalog", {})
+        should_rebuild = catalog_cfg.get("rebuild", False)
+        min_rows       = int(catalog_cfg.get("min_rows", 1000))
+
+        logger.info("[Agent B] Step 0-1: KOSIS 메타데이터 수집")
+
+        if not should_rebuild and await is_catalog_ready(self.config, min_rows):
+            logger.info(
+                f"[Agent B] kosis_stat_catalog 이미 구축됨 (min_rows={min_rows}) → "
+                f"수집 skip. 강제 재수집: config.kosis.catalog.rebuild=true"
+            )
+            # catalog가 이미 DB에 있으므로 합성 데이터 생성도 skip
+            # → Step 0-2~5는 이미 학습된 adapter가 있는 경우에만 의미있음
+            # → pretrain_domain은 여기서 종료하고 기존 adapter 경로 반환
+            import os
+            model_yaml = os.path.join("domain-packs", domain, "model.yaml")
+            if os.path.exists(model_yaml):
+                import yaml
+                with open(model_yaml, encoding="utf-8") as f:
+                    model_info = yaml.safe_load(f)
+                existing_path = model_info.get("adapter_path")
+                if existing_path:
+                    logger.info(f"[Agent B] 기존 adapter 사용: {existing_path}")
+                    return existing_path
+            logger.info("[Agent B] catalog 구축됨이나 adapter 없음 → 합성 데이터 생성 진행")
+            catalog = []  # save_to_db skip, 합성 데이터는 DB catalog 기반으로 진행
+        else:
+            catalog = await crawl_kosis_catalog(self.config)
+            if not catalog:
+                logger.error("[Agent B] 메타데이터 수집 실패 (KOSIS_API_KEY 확인 필요)")
+                return None
+            await save_to_db(catalog, self.config)
+            logger.info(f"[Agent B] 메타데이터 {len(catalog)}건 수집 완료")
+
+        # ── Step 0-2: 합성 학습 데이터 생성 ──────────────────────────
+        logger.info("[Agent B] Step 0-2: Self-Instruct 합성 데이터 생성")
+        synthetic = await generate_synthetic_pairs(
+            catalog=catalog,
+            llm=self.llm,
+            claims_per_table=3,
+            max_tables=max_tables,
+        )
+        if not synthetic:
+            logger.error("[Agent B] 합성 데이터 생성 실패")
+            return None
+
+        # JSONL 파일로 저장 (ml/data/)
+        await save_synthetic_data(synthetic)
+        logger.info(f"[Agent B] 합성 데이터 {len(synthetic)}쌍 생성 완료")
+
+        # ── Step 0-3: 학습 포맷 변환 ─────────────────────────────────
+        logger.info("[Agent B] Step 0-3: 학습 포맷 변환 (pretrain)")
+        samples = build_training_samples(synthetic=synthetic, mode="pretrain")
+        logger.info(f"[Agent B] 학습 샘플 {len(samples)}건 생성")
+
+        if not samples:
+            logger.error("[Agent B] 학습 샘플 없음")
+            return None
+
+        # ── Step 0-4: NCP Tuning API 학습 ────────────────────────────
+        logger.info("[Agent B] Step 0-4: NCP Tuning API 학습 시작")
+        adapter_path = await self.trainer.train(domain, samples)
+        if not adapter_path:
+            logger.error("[Agent B] 학습 실패 (NCP Tuning API 확인 필요)")
+            return None
+
+        # ── Step 0-5: 평가 → 배포 ────────────────────────────────────
+        benchmark = f"domain-packs/{domain}/eval_dataset.jsonl"
+        score = await self.trainer.evaluate(adapter_path, benchmark)
+        logger.info(f"[Agent B] 평가 점수: {score:.3f} (기준: {self.eval_min_score})")
+
+        if score < self.eval_min_score:
+            logger.warning(
+                f"[Agent B] 평가 미통과 ({score:.3f} < {self.eval_min_score}) "
+                f"— Adapter 배포 안 함"
+            )
+            return None
+
+        deployed = await self.trainer.deploy(adapter_path, domain)
+        if deployed:
+            logger.info(f"[Agent B] === 사전학습 완료: {domain} Adapter 배포 ===")
+        return adapter_path
+
+    # ── 피드백 루프 ──────────────────────────────────────────────────────
+
+    async def log_feedback(self, event: FeedbackEvent) -> None:
+        """
+        Step 11: Human Review 피드백 저장 + 임계값 도달 시 학습 트리거.
+
+        TODO [박재윤]: feedback_store.save() → feedback_events 테이블 INSERT
+        """
+        await self.feedback_store.save(event)
+        logger.info(f"[Agent B] 피드백 기록: {event.feedback_type.value}")
+
+        count = await self.feedback_store.count_by_domain()
+        logger.debug(f"[Agent B] 누적 피드백: {count}건 (임계값: {self.threshold})")
+
+        if count >= self.threshold:
+            logger.info(f"[Agent B] 임계값 도달 → Adaptation 트리거")
+            await self._trigger_adaptation()
+
+    async def _trigger_adaptation(self) -> None:
+        """
+        Step 12: 피드백 기반 추가 학습.
+
+        pending 피드백 수집 → finetune 포맷 변환 → NCP Tuning → 평가 → 배포.
+        """
+        logger.info("[Agent B] 피드백 Adaptation 시작")
+
+        events = await self.feedback_store.get_pending()
+        if not events:
+            logger.warning("[Agent B] pending 피드백 없음")
+            return
+
+        samples = build_training_samples(events=events, mode="finetune")
+        logger.info(f"[Agent B] 피드백 샘플 {len(samples)}건")
+
+        if not samples:
+            return
+
+        adapter_path = await self.trainer.train("news", samples)
+        if not adapter_path:
+            return
+
+        benchmark = "domain-packs/news/eval_dataset.jsonl"
+        score = await self.trainer.evaluate(adapter_path, benchmark)
+
+        if score >= self.eval_min_score:
+            await self.trainer.deploy(adapter_path, "news")
+            logger.info("[Agent B] 피드백 Adapter 배포 완료")
+        else:
+            logger.warning(f"[Agent B] 피드백 Adapter 평가 미통과: {score:.3f}")
+
+    async def generate_domain_pack(self, domain: str) -> DomainPack:
+        """
+        새 도메인용 Domain Pack 디렉토리 및 기본 파일 생성.
+
+        TODO [김예슬]: KOSIS 메타 기반 few-shot 예시 자동 생성
+        """
+        import os, yaml
+
+        pack_dir = os.path.join("domain-packs", domain)
+        os.makedirs(pack_dir, exist_ok=True)
+
+        prompts_yaml = os.path.join(pack_dir, "prompts.yaml")
+        if not os.path.exists(prompts_yaml):
+            with open(prompts_yaml, "w", encoding="utf-8") as f:
+                yaml.dump(
+                    {"domain": domain, "few_shot_examples": []},
+                    f, allow_unicode=True,
+                )
+
+        logger.info(f"[Agent B] Domain Pack 생성: {pack_dir}")
+        return DomainPack(pack_id=f"pack_{domain}_v1", domain=domain, version="1.0")

structverify/agent/conformance_agent.py

@@ -0,0 +1,171 @@
+"""structverify.agent.conformance_agent — a ReAct loop for compliance checking.
+
+The one-shot path (retrieve top-k once → judge) is fine for a small rulebook,
+but breaks down when the rulebook is large: the single retrieval may miss the
+one article that actually applies. This agent adds the same *adaptive retrieval*
+that the KOSIS fact-verification loop uses — it iterates:
+
+    search → judge → (inconclusive?) reflect & reformulate the query → search again
+
+so it keeps hunting for the applicable article until it reaches a decisive
+verdict (compliant / violation) or exhausts its iteration budget. A small
+working memory of tried queries and inspected articles steers each reflection
+and prevents repeat searches.
+
+Retrieval and judgment are reused as-is (``CustomDocsDataSource`` +
+``judge_conformance``); this module only adds the loop around them.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from structverify.utils.llm_client import LLMClient
+from structverify.utils.logger import get_logger
+from structverify.verification.conformance import judge_conformance
+
+logger = get_logger(__name__)
+
+_DECISIVE = {"compliant", "violation"}
+
+_REFORMULATE_PROMPT = """너는 규정집에서 적용 조항을 찾는 검색 전략가다.
+
+[판정 대상]
+{statement}
+
+지금까지의 검색으로는 적용할 조항을 확정하지 못했다 (준수/위반 판정 불가).
+
+[이미 시도한 검색어]
+{tried}
+
+[방금 검색됐지만 적합하지 않았던 조항 일부]
+{snippet}
+
+더 적합한 조항을 찾기 위한 **새로운 검색어 하나**를 제안하라.
+- 측정 대상·항목명·단위·규제 키워드 중심으로 (예: 원소명, 성분명, 표시문구, 한도 유형).
+- 이미 시도한 검색어와 달라야 한다.
+JSON만 출력: {{"query": "새 검색어", "reason": "왜 이 검색어인지 한 문장"}}"""
+
+
+class ConformanceAgent:
+    """Adaptive, iterative compliance checker over a document data source.
+
+    Args:
+        ds: A ``CustomDocsDataSource`` (or any source exposing async
+            ``search_catalog(query, top_k)`` and ``fetch_evidence(id)``).
+        config: Engine config (``{"llm": {...}}``) for judgment/reflection.
+        max_iters: Maximum search→judge rounds before giving up.
+        top_k: Candidates retrieved per search.
+        votes: Self-consistency votes passed to ``judge_conformance``.
+    """
+
+    def __init__(
+        self, ds: Any, config: dict | None = None, *,
+        max_iters: int = 4, top_k: int = 5, votes: int = 3,
+    ):
+        self._ds = ds
+        self._config = config or {}
+        self._max_iters = max(1, max_iters)
+        self._top_k = top_k
+        self._votes = votes
+        self._llm = LLMClient(config=(self._config or {}).get("llm", {}))
+
+    async def check(self, statement: str) -> dict[str, Any]:
+        """Run the loop and return a ``judge_conformance``-style dict.
+
+        The returned dict carries the usual keys (``verdict``,
+        ``applicable_article``, ``rule_value``, ``claim_value``, ``unit``,
+        ``explanation``) plus ``iterations`` — how many rounds it took.
+        """
+        tried_queries: list[str] = []
+        seen_articles: dict[str, str] = {}   # id → text (dedup across rounds)
+        query = statement
+        last_result: dict[str, Any] = {"verdict": "unverifiable", "explanation": "검색 결과 없음"}
+
+        for i in range(1, self._max_iters + 1):
+            tried_queries.append(query)
+
+            # ── retrieve ────────────────────────────────────────────────
+            logger.info(f"[에이전트][{i}회] 검색 → {query!r}")
+            new_snippets = await self._retrieve(query, seen_articles)
+            if new_snippets:
+                top = " ".join(new_snippets[0].split())[:46]
+                logger.info(
+                    f"[에이전트][{i}회] 조회 → 조항 {len(seen_articles)}개 확보 "
+                    f"(신규 {len(new_snippets)}개, top: {top}…)"
+                )
+            else:
+                logger.info(
+                    f"[에이전트][{i}회] 조회 → 신규 조항 없음 (누적 {len(seen_articles)}개)"
+                )
+
+            # Judge against everything gathered so far (accumulated context helps
+            # when the right article surfaces only after a reformulated search).
+            corpus = "\n---\n".join(seen_articles.values())
+            if corpus.strip():
+                last_result = await judge_conformance(
+                    statement, corpus, self._config, votes=self._votes,
+                )
+            verdict = last_result.get("verdict")
+            rv, cv = last_result.get("rule_value"), last_result.get("claim_value")
+            unit = last_result.get("unit") or ""
+            logger.info(
+                f"[에이전트][{i}회] 판정 → {verdict}  (기준 {rv} vs 측정 {cv} {unit})"
+            )
+
+            # ── reflect: decisive verdict ends the loop ────────────────
+            if verdict in _DECISIVE:
+                logger.info(f"[에이전트] 확정 — {i}회 만에 종료 ({last_result.get('applicable_article')})")
+                last_result["iterations"] = i
+                return last_result
+
+            # ── replan: reformulate the query and search again ─────────
+            if i < self._max_iters:
+                logger.info(f"[에이전트][{i}회] 판정 불가 → 검색어 재구성 시도")
+                query = await self._reformulate(statement, tried_queries, new_snippets)
+                if not query or query in tried_queries:
+                    logger.info("[에이전트] 더 나은 검색어 없음 — 종료")
+                    break
+
+        last_result["iterations"] = i
+        return last_result
+
+    # ── tools ───────────────────────────────────────────────────────────
+
+    async def _retrieve(self, query: str, seen: dict[str, str]) -> list[str]:
+        """Search + fetch article texts; record new ones in ``seen``. Returns new snippets."""
+        fresh: list[str] = []
+        try:
+            cands = await self._ds.search_catalog(query, top_k=self._top_k)
+        except Exception as e:  # retrieval must never crash the loop
+            logger.warning(f"[conformance-agent] search 실패: {e}")
+            return fresh
+        for c in cands:
+            cid = c.get("id")
+            if cid in seen:
+                continue
+            ev = await self._ds.fetch_evidence(cid)
+            if ev and ev.get("text"):
+                seen[cid] = ev["text"]
+                fresh.append(ev["text"])
+        return fresh
+
+    async def _reformulate(
+        self, statement: str, tried: list[str], snippets: list[str],
+    ) -> str | None:
+        """Ask the LLM for a better search query given what didn't work."""
+        prompt = _REFORMULATE_PROMPT.format(
+            statement=statement,
+            tried="\n".join(f"- {q}" for q in tried),
+            snippet=("\n".join(snippets)[:800] or "(없음)"),
+        )
+        try:
+            out = await self._llm.generate_json_light(prompt)
+        except Exception as e:
+            logger.warning(f"[에이전트] 쿼리 재구성 실패: {e}")
+            return None
+        q = (out or {}).get("query")
+        if isinstance(q, str) and q.strip():
+            reason = str((out or {}).get("reason", "")).strip()
+            logger.info(f"[에이전트] 재구성 → {q.strip()!r}" + (f"  ({reason[:40]})" if reason else ""))
+            return q.strip()
+        return None

structverify/agent/dependency_planner.py

@@ -0,0 +1,151 @@
+"""Document-level Dependency Planner — Phase D+ (2026-05-21).
+
+각 sub-claim을 *독립적으로* planner+agent_loop에 보내던 기존 흐름의 한계:
+  - 같은 문장에서 분기된 base + derived sub-claim이 동시에 병렬 실행됨
+  - derived(예: 출생아 수 증가율)는 base(예: 출생아 수)의 KOSIS evidence가 있으면
+    재활용 가능한데, 병렬이라 base 결과가 아직 없어 derived가 또 fetch 시도
+  - 같은 indicator를 공유하는 base 그룹(의료장비 4개 시도 케이스)도 catalog 결과를
+    공유하지 못해 각자 catalog_search를 4회 반복
+
+처방: sub-claim들을 *실행 레벨*로 묶어 level 간 *순차*, level 내 *병렬*로 처리.
+verified_facts/successful_stat_ids 캐시가 level 간에 살아 있으므로 level 2의 claim들이
+level 1의 evidence를 자동 재활용.
+
+레벨 결정 신호:
+  - schema.value_role
+    - "base"               → Level 1 (단독 검증)
+    - "aggregation"        → Level 1 (다년 fetch — sibling 의존 없음, catalog 캐시 공유)
+    - "derived_rate"       → Level 2 (base 결과 의존)
+    - "derived_difference" → Level 2
+    - None / 기타          → Level 1 (default)
+
+옵션 (use_llm=True): LLM이 모든 sub-claim의 schema를 보고 더 정밀한 dependency 그래프
+구성. 현재는 stub (deterministic으로 fallback). Phase C+에서 prompt 구현 예정.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Awaitable
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ── 공개 API ──────────────────────────────────────────────────────────
+
+
+def build_execution_levels(
+    claims: list[Any],
+    *,
+    llm_call: Callable[[str], Awaitable[str]] | None = None,
+    use_llm: bool = False,
+) -> list[list[Any]]:
+    """sub-claim 리스트 → 실행 레벨 (list of lists).
+
+    Args:
+        claims: structverify Claim 리스트
+        llm_call: 옵션. LLM 기반 dependency 분석 (use_llm=True일 때 사용)
+        use_llm: True면 LLM document_planner 호출, False면 결정론 분석
+
+    Returns:
+        levels: [[claim, ...], [claim, ...], ...]
+            - 외부 list는 순차 실행 (level 간 순서 의존)
+            - 내부 list는 병렬 실행 가능 (level 안의 claim들)
+        모든 입력 claim은 정확히 한 level에 포함됨.
+    """
+    if not claims:
+        return []
+
+    if use_llm and llm_call is not None:
+        try:
+            levels = _llm_levels(claims, llm_call)
+            if levels and _all_claims_covered(claims, levels):
+                logger.info(
+                    f"[dep_planner] LLM mode: {len(levels)} levels, "
+                    f"sizes={[len(lvl) for lvl in levels]}"
+                )
+                return levels
+            logger.warning(
+                "[dep_planner] LLM 응답 부적합 → 결정론으로 fallback"
+            )
+        except Exception as e:
+            logger.warning(
+                f"[dep_planner] LLM mode 실패 → 결정론으로 fallback: "
+                f"{type(e).__name__}: {e}"
+            )
+
+    levels = _deterministic_levels(claims)
+    logger.info(
+        f"[dep_planner] deterministic mode: {len(levels)} levels, "
+        f"sizes={[len(lvl) for lvl in levels]}"
+    )
+    return levels
+
+
+# ── 결정론 분석 ──────────────────────────────────────────────────────
+
+
+def _deterministic_levels(claims: list[Any]) -> list[list[Any]]:
+    """결정론적 level 분할 — schema.value_role 기반.
+
+    Level 1: base + value_role 미지정 claim
+        - 단독 검증 가능. catalog_search → fetch → finish.
+        - 같은 indicator를 공유하는 claim들은 prior_success stat_id 캐시로
+          catalog 결과 자연스럽게 공유 (현재 매커니즘 그대로).
+
+    Level 2: derived_rate / derived_difference claim
+        - Level 1 끝난 후 실행. base claim의 fetch evidence가 verified_facts에
+          캐시되어 있어 prev/current 시점 fetch를 재활용할 수 있음.
+    """
+    base_or_unspecified: list[Any] = []
+    derived: list[Any] = []
+
+    for c in claims:
+        schema = getattr(c, "schema", None)
+        role = getattr(schema, "value_role", None) if schema else None
+        if role in ("derived_rate", "derived_difference"):
+            derived.append(c)
+        else:
+            # "base" / None / 기타 → Level 1
+            base_or_unspecified.append(c)
+
+    levels: list[list[Any]] = []
+    if base_or_unspecified:
+        levels.append(base_or_unspecified)
+    if derived:
+        levels.append(derived)
+
+    # 안전망: 모든 claim이 한 level에 들어갔는지
+    if not _all_claims_covered(claims, levels):
+        logger.warning(
+            "[dep_planner] 결정론 분할에서 누락 claim 발견 → 단일 level fallback"
+        )
+        return [list(claims)]
+
+    return levels
+
+
+def _all_claims_covered(claims: list[Any], levels: list[list[Any]]) -> bool:
+    """levels에 모든 claim이 정확히 한 번씩 들어갔는지 검증."""
+    flat = [c for lvl in levels for c in lvl]
+    if len(flat) != len(claims):
+        return False
+    flat_ids = {id(c) for c in flat}
+    return all(id(c) in flat_ids for c in claims)
+
+
+# ── LLM 기반 분석 (stub — Phase C+) ──────────────────────────────────
+
+
+def _llm_levels(
+    claims: list[Any],
+    llm_call: Callable[[str], Awaitable[str]],
+) -> list[list[Any]]:
+    """LLM이 모든 sub-claim의 schema를 보고 dependency 그래프 구성.
+
+    현재는 stub. Phase C+에서 prompt 구현 예정. 호출자는 fallback을 처리해야 함.
+    """
+    raise NotImplementedError(
+        "LLM document_planner는 Phase C+에서 구현 예정. "
+        "현재는 use_llm=False (결정론)만 작동."
+    )