structverify 0.3.0__py3-none-any.whl

structverify/agent/indexing_agent.py

@@ -0,0 +1,153 @@
+"""structverify.agent.indexing_agent — 색인 전략 ReAct 에이전트 (P1 재설계).
+
+단순 API 1회 호출이 아니라, *진짜 에이전트*:
+  · 파일 메모리(LocalWorkspaceBackend)에 관찰·판단을 기록(기억·추적·재개)
+  · 도구로 데이터를 필요할 때마다 직접 읽음 (peek/columns/sample/grep/stats)
+  · ReAct 루프: 생각 → 도구 호출 → 관찰 → 반복 → 최종 IndexingPlan
+
+기존 인프라 재사용: agent/workspace.py(메모리), utils/llm_client(추론).
+계획: docs/indexing-agent-plan.md
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+from typing import Any
+
+from structverify.agent.indexing_planner import (
+    INDEXING_PLAN_SCHEMA,
+    _analyze_source,
+    _apply_heuristic_guards,
+)
+from structverify.agent.workspace import LocalWorkspaceBackend
+from structverify.utils.llm_client import LLMClient
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+_STEP_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "thought": {"type": "string"},
+        "action": {"type": "string",
+                   "enum": ["peek", "columns", "sample", "grep", "stats", "finish"]},
+        "args": {"type": "object"},   # peek:{n}, sample:{n}, grep:{pattern}
+    },
+    "required": ["thought", "action"],
+}
+
+_TOOLS_DESC = (
+    "peek{n}: 원문 앞 n자 · columns: CSV 헤더 · sample{n}: 표 n행/문서 조각 · "
+    "grep{pattern}: 패턴 매칭 줄(조항·한도 탐색) · stats: 통계(행수·수치밀도·조항수) · "
+    "finish: 정보 충분하면 종료(다음 단계에서 IndexingPlan 확정)"
+)
+
+
+class IndexingAgent:
+    """데이터를 도구로 탐색하며 색인 전략을 세우는 ReAct 에이전트."""
+
+    def __init__(self, config: dict[str, Any] | None = None,
+                 workspace_root: str = "./agent_workspace/indexing"):
+        self.config = config or {}
+        self.llm = LLMClient(config=self.config.get("llm", {}))
+        self.ws = LocalWorkspaceBackend(workspace_root)
+        self.max_iters = int(self.config.get("indexing_max_iters", 6))
+
+    def _load(self, source: str) -> tuple[str, bool]:
+        if isinstance(source, str) and os.path.exists(source):
+            from structverify.retrieval.chunking import read_document
+            text = read_document(source)   # .pdf 추출 포함
+            is_csv = source.lower().endswith(".csv")
+        else:
+            text = source or ""
+            is_csv = "," in (text.splitlines()[0] if text.splitlines() else "")
+        return text, is_csv
+
+    # ── 도구 (데이터를 필요할 때 읽음) ──
+    def _run_tool(self, action: str, args: dict, source: str, text: str, is_csv: bool) -> str:
+        try:
+            if action == "peek":
+                return text[: int(args.get("n", 600))]
+            if action == "columns":
+                if not is_csv:
+                    return "(비정형 문서 — 컬럼 없음)"
+                return ", ".join(next(csv.reader(io.StringIO(text)), []))
+            if action == "sample":
+                n = int(args.get("n", 5))
+                if is_csv:
+                    rows = list(csv.reader(io.StringIO(text)))[1:n + 1]
+                    return "\n".join(", ".join(r) for r in rows)
+                return text[:200 * n][:1200]
+            if action == "grep":
+                pat = str(args.get("pattern", ""))
+                import re
+                hits = [ln for ln in text.splitlines() if pat and re.search(pat, ln)]
+                return "\n".join(hits[:15]) or "(매칭 없음)"
+            if action == "stats":
+                return json.dumps(_analyze_source(source), ensure_ascii=False, default=str)[:800]
+        except Exception as e:  # noqa: BLE001
+            return f"(도구 오류: {e})"
+        return "(알 수 없는 도구)"
+
+    async def run(self, source: str, run_id: str = "run") -> dict[str, Any]:
+        """데이터를 탐색하며 IndexingPlan을 세운다. 관찰·판단은 workspace에 기록."""
+        text, is_csv = self._load(source)
+        trace_key = f"{run_id}/trace.md"
+        self.ws.write_text(trace_key, f"# 색인 전략 에이전트 trace\nsource={source}\n\n")
+        observations: list[str] = []
+
+        for i in range(1, self.max_iters + 1):
+            step = await self._decide(observations)
+            thought, action, args = step.get("thought", ""), step.get("action", "stats"), step.get("args") or {}
+            self.ws.append_text(trace_key, f"## iter {i}\n- 생각: {thought}\n- 행동: {action} {args}\n")
+            if action == "finish":
+                self.ws.append_text(trace_key, "- → 종료, plan 확정\n")
+                break
+            obs = self._run_tool(action, args, source, text, is_csv)
+            observations.append(f"[{action} {args}] → {obs[:400]}")
+            self.ws.append_text(trace_key, f"- 관찰: {obs[:300]}\n\n")
+
+        plan = await self._finalize(observations)
+        plan = _apply_heuristic_guards(plan, _analyze_source(source), self.config)
+        self.ws.write_text(f"{run_id}/plan.json", json.dumps(plan, ensure_ascii=False, indent=2))
+        logger.info(f"[indexing_agent] plan: datasource={plan.get('datasource')} "
+                    f"verdict={plan.get('verdict_mode')} (iters={i}, trace={trace_key})")
+        return plan
+
+    async def _decide(self, observations: list[str]) -> dict[str, Any]:
+        hist = "\n".join(observations) or "(아직 관찰 없음)"
+        prompt = (
+            "너는 데이터 색인 전략가 에이전트다. 데이터를 도구로 조사해 색인 전략을 세운다.\n"
+            f"[도구]\n{_TOOLS_DESC}\n\n[지금까지 관찰]\n{hist}\n\n"
+            "다음 한 스텝을 정하라. 표형/문서형·수치성·조항구조·규모를 파악할 정보가 더 필요하면 "
+            "도구를 호출하고, 충분하면 finish. thought/action/args JSON만 출력."
+        )
+        try:
+            return await self.llm.generate_structured(
+                prompt, _STEP_SCHEMA, system_prompt="색인 전략 에이전트. JSON만.",
+            )
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"[indexing_agent] decide 실패: {e}")
+            return {"thought": "폴백", "action": "finish", "args": {}}
+
+    async def _finalize(self, observations: list[str]) -> dict[str, Any]:
+        hist = "\n".join(observations) or "(관찰 없음)"
+        prompt = (
+            "아래 데이터 조사 관찰을 근거로 IndexingPlan(JSON)을 확정하라.\n"
+            "- datasource: 표형=custom_csv, 자연어 문서=custom_docs, 혼합=hybrid\n"
+            "- search_mode: 정형=keyword, 동의어중요=embedding, 둘다=hybrid\n"
+            "- verdict_mode: 값대값=numeric, 텍스트규정 준수=conformance\n"
+            "- chunking(문서형): 조항多=article/문단=paragraph, size/overlap\n"
+            "- embedding.backend: 대규모=pgvector 아니면 memory · provider: config 우선\n"
+            "- column_mapping(표형) · rationale(왜 이렇게 정했는지)\n\n"
+            f"[관찰]\n{hist}\n\nIndexingPlan JSON만 출력."
+        )
+        try:
+            return await self.llm.generate_structured(
+                prompt, INDEXING_PLAN_SCHEMA, system_prompt="색인 전략가. IndexingPlan JSON만.",
+            )
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"[indexing_agent] finalize 실패 → 휴리스틱: {e}")
+            return {}

structverify/agent/indexing_planner.py

@@ -0,0 +1,169 @@
+"""structverify.agent.indexing_planner — 색인 전략 에이전트 (P1).
+
+데이터셋 샘플 + 유저 config 를 분석해 **IndexingPlan**(색인·검색·판정 전략) 초안을 만든다.
+사람이 keyword/semantic/chunk/provider/verdict를 손으로 고르지 않고, 에이전트가 결정.
+
+흐름: 데이터 로드/통계(휴리스틱) → LLM 구조화 판단 → IndexingPlan + rationale.
+계획: docs/indexing-agent-plan.md
+"""
+from __future__ import annotations
+
+import csv
+import io
+import os
+import re
+from typing import Any
+
+from structverify.utils.llm_client import LLMClient
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# 에이전트가 채우는 색인 전략 스키마 (generate_structured 강제)
+INDEXING_PLAN_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "datasource": {"type": "string", "enum": ["custom_csv", "custom_docs", "hybrid"]},
+        "search_mode": {"type": "string", "enum": ["keyword", "embedding", "hybrid"]},
+        "verdict_mode": {"type": "string", "enum": ["numeric", "conformance"]},
+        "chunking": {
+            "type": "object",
+            "properties": {
+                "strategy": {"type": "string", "enum": ["article", "paragraph", "fixed", "none"]},
+                "size": {"type": "integer"},
+                "overlap": {"type": "integer"},
+            },
+        },
+        "embedding": {
+            "type": "object",
+            "properties": {
+                "provider": {"type": "string"},
+                "backend": {"type": "string", "enum": ["memory", "pgvector"]},
+            },
+        },
+        "column_mapping": {"type": "object"},
+        "rationale": {"type": "string"},
+    },
+    "required": ["datasource", "search_mode", "verdict_mode", "rationale"],
+}
+
+_PGVECTOR_ROW_THRESHOLD = 20000   # 이상이면 pgvector 권장
+_ARTICLE_RE = re.compile(r"제?\s*\d+\s*조")
+_LIMIT_KW = ("한도", "이하", "이상", "초과", "미만", "기준", "상한", "최대", "최소")
+
+
+def _analyze_source(source: str) -> dict[str, Any]:
+    """데이터 샘플 + 휴리스틱 통계. source = 파일 경로 또는 원시 텍스트."""
+    from structverify.retrieval.chunking import read_document
+    is_path = isinstance(source, str) and os.path.exists(source)
+    ext = os.path.splitext(source)[1].lower() if is_path else ""
+    text = read_document(source) if is_path else (source or "")   # .pdf 추출 포함
+
+    stats: dict[str, Any] = {"ext": ext, "char_count": len(text)}
+
+    # CSV 판별 (확장자 또는 헤더에 콤마 다수)
+    first_line = text.splitlines()[0] if text.splitlines() else ""
+    looks_csv = ext == ".csv" or (first_line.count(",") >= 1 and ext in ("", ".csv"))
+    stats["is_tabular"] = looks_csv
+
+    if looks_csv:
+        rows = list(csv.reader(io.StringIO(text)))
+        header = rows[0] if rows else []
+        body = rows[1:]
+        stats["columns"] = header
+        stats["row_count"] = len(body)
+        stats["sample_rows"] = body[:5]
+        # 수치 컬럼 비율
+        num_cells = tot = 0
+        for r in body[:50]:
+            for c in r:
+                tot += 1
+                try:
+                    float(str(c).replace(",", ""))
+                    num_cells += 1
+                except ValueError:
+                    pass
+        stats["numeric_density"] = round(num_cells / tot, 2) if tot else 0.0
+        stats["has_operator_col"] = any("operator" in (h or "").lower() for h in header)
+    else:
+        stats["article_markers"] = len(_ARTICLE_RE.findall(text))
+        stats["sample_text"] = text[:1200]
+
+    stats["limit_keyword_hits"] = sum(text.count(k) for k in _LIMIT_KW)
+    return stats
+
+
+def _build_prompt(stats: dict[str, Any], config: dict[str, Any]) -> str:
+    emb_provider = ((config or {}).get("embedding") or {}).get("provider") \
+        or ((config or {}).get("llm") or {}).get("provider") or "(미지정)"
+    domain = ((config or {}).get("domain") or {}).get("description") or "(미지정)"
+    return (
+        "너는 데이터 색인 전략가다. 아래 데이터셋 통계와 유저 config를 보고, 이 데이터를 어떻게 "
+        "색인·검색·판정할지 IndexingPlan(JSON)으로 정하라.\n\n"
+        "[결정 기준]\n"
+        "- datasource: 정형 표(컬럼·값)면 custom_csv, 자연어 문서(조항·문단)면 custom_docs, 섞이면 hybrid\n"
+        "- search_mode: 지표 표기가 코드/정형이면 keyword, 동의어·의역 매칭이 중요하면 embedding, 둘 다면 hybrid\n"
+        "- verdict_mode: 값 대 값 수치비교가 되면 numeric, 텍스트 규정에 대한 준수여부면 conformance\n"
+        "- chunking(문서형만): 조항 마커 많으면 article, 문단 위주면 paragraph, 아니면 fixed\n"
+        "- embedding.backend: 행/청크가 매우 많으면(수만+) pgvector, 아니면 memory\n"
+        "- embedding.provider: 유저 config provider 우선\n"
+        "- column_mapping(표형): 컬럼→ indicator/value/unit/time/region/operator 매핑\n"
+        "- rationale: 왜 이렇게 정했는지 한국어로 2~3문장\n\n"
+        f"[데이터 통계]\n{stats}\n\n"
+        f"[유저 config] embedding/llm provider={emb_provider}, domain={domain}\n\n"
+        "IndexingPlan JSON만 출력."
+    )
+
+
+async def plan_indexing(source: str, config: dict[str, Any] | None = None) -> dict[str, Any]:
+    """데이터셋(source: 경로 또는 텍스트) + config → IndexingPlan(dict).
+
+    항상 초안을 만든다(유저가 이후 검토·확정). LLM 실패 시 휴리스틱 폴백.
+    """
+    config = config or {}
+    stats = _analyze_source(source)
+    llm = LLMClient(config=config.get("llm", {}))
+
+    try:
+        plan = await llm.generate_structured(
+            _build_prompt(stats, config),
+            INDEXING_PLAN_SCHEMA,
+            system_prompt="데이터 색인 전략가. 반드시 IndexingPlan JSON만 출력.",
+        )
+    except Exception as e:  # noqa: BLE001
+        logger.warning(f"[indexing_planner] LLM 실패 → 휴리스틱 폴백: {e}")
+        plan = {}
+
+    plan = _apply_heuristic_guards(plan, stats, config)
+    logger.info(
+        f"[indexing_planner] datasource={plan.get('datasource')} "
+        f"search={plan.get('search_mode')} verdict={plan.get('verdict_mode')}"
+    )
+    return plan
+
+
+def _apply_heuristic_guards(plan: dict[str, Any], stats: dict[str, Any],
+                            config: dict[str, Any]) -> dict[str, Any]:
+    """LLM 결과에 명백한 휴리스틱 보정 (빈 값 채우기·규모/provider 강제)."""
+    plan = dict(plan or {})
+    # 형태
+    if not plan.get("datasource"):
+        plan["datasource"] = "custom_csv" if stats.get("is_tabular") else "custom_docs"
+    # verdict: operator 컬럼 or 수치밀도 높으면 numeric
+    if not plan.get("verdict_mode"):
+        plan["verdict_mode"] = "numeric" if stats.get("is_tabular") else "conformance"
+    # search_mode 기본
+    if not plan.get("search_mode"):
+        plan["search_mode"] = "keyword" if stats.get("is_tabular") else "embedding"
+    # 규모 → backend
+    n = stats.get("row_count") or stats.get("article_markers") or 0
+    emb = dict(plan.get("embedding") or {})
+    if not emb.get("backend"):
+        emb["backend"] = "pgvector" if n >= _PGVECTOR_ROW_THRESHOLD else "memory"
+    # provider: config 우선
+    cfg_provider = ((config.get("embedding") or {}).get("provider")
+                    or (config.get("llm") or {}).get("provider"))
+    if cfg_provider:
+        emb["provider"] = cfg_provider
+    plan["embedding"] = emb
+    return plan

structverify/agent/integration_example.py

@@ -0,0 +1,182 @@
+"""structverify.agent.integration_example — runtime_agent에 agent loop를 끼우는 *예시 코드*.
+
+★ 이 파일은 *작동하는 코드가 아니라 가이드*. 사용자가 자신의 runtime_agent.py에 *수동 통합*.
+
+## 통합 단계
+
+### 1. config 확장 (`config/default.yaml`)
+
+```yaml
+agent:
+  enabled: false              # ← true로 켜야 agent loop 사용
+  llm:
+    plan_model: "HCX-007"
+    plan_temperature: 0.1
+  loop:
+    max_iterations: 10
+    mode: "deterministic"     # phase D는 이거만. Phase E에서 "reflect" 추가.
+
+data_sources:
+  enabled: ["kosis"]
+  default_source: "kosis"
+  kosis:
+    # 기존 KOSIS 설정 (api_key 등) 여기로 통합
+    api_key: null  # env var에서 자동 로드 가정
+```
+
+### 2. runtime_agent.py에 *config 분기* 추가
+
+기존 Step 7-8 (retrieve_evidence + verify_claim)을 *agent loop로 대체*:
+
+```python
+# runtime_agent.py (사용자 코드)
+
+class RuntimeAgent:
+    async def process(self, sir_doc):
+        # ... Steps 1-6 그대로 (도메인 분류, 클레임 탐지, 스키마 유도, 그래프 빌드)
+
+        for claim in claims:
+            if self.config.agent.enabled:
+                # ★ NEW: Agent loop 경로
+                result = await self._verify_with_agent(claim, source_text, anchor_year)
+            else:
+                # 기존 경로 (Step 7-8)
+                evidence = await self._retrieve_evidence(claim)
+                result = await self._verify_claim(claim, evidence)
+                result.explanation = await generate_explanation(claim, result, self.config)
+
+            results.append(result)
+        # ...
+
+    async def _verify_with_agent(self, claim, source_text, anchor_year):
+        '''Phase D: agent loop으로 검증.'''
+        from structverify.agent.planner import Planner, PlannerConfig
+        from structverify.agent.loop import agent_loop, LoopConfig
+        from structverify.agent.workspace import build_workspace
+        from structverify.retrieval.registry import build_all_enabled
+
+        # 1. workspace 준비
+        workspace = build_workspace(
+            job_id=str(self.job_id),
+            config=self.config.agent.workspace.model_dump() if hasattr(self.config.agent.workspace, 'model_dump') else dict(self.config.agent.workspace),
+        )
+        if not workspace.is_initialized():
+            workspace.initialize(source_text=source_text)
+        workspace.create_claim_dir(claim.claim_id, claim_dict=claim.model_dump(mode="json"))
+
+        # 2. DataSource 등록 (KOSIS만 우선)
+        from structverify.retrieval import kosis_source  # noqa — register_datasource 트리거
+        datasources = {
+            ds.name: ds for ds in build_all_enabled({
+                "enabled": ["kosis"],
+                "kosis": dict(self.config.data_sources.kosis) if hasattr(self.config.data_sources, 'kosis') else {},
+            })
+        }
+
+        # 3. Planner — LLM call wiring
+        async def llm_call_for_plan(prompt):
+            # ★ 사용자 wiring: HCX client 호출
+            # 예시 (실제 HCX 호출 방식에 맞게 수정):
+            from structverify.llm.hcx_client import call_hcx  # ← 실제 모듈/함수 이름 확인
+            return await call_hcx(
+                prompt=prompt,
+                model=self.config.agent.llm.plan_model,
+                temperature=0.1,
+            )
+
+        planner = Planner(
+            llm_call=llm_call_for_plan,
+            config=PlannerConfig(
+                model=self.config.agent.llm.plan_model,
+                temperature=0.1,
+            ),
+        )
+
+        # 4. Plan 생성
+        plan = await planner.plan(claim, source_text=source_text, anchor_year=anchor_year)
+        workspace.write_plan(claim.claim_id, plan.model_dump(mode="json"))
+
+        # 5. Loop 실행
+        verdict = await agent_loop(
+            plan=plan,
+            claim=claim,
+            workspace=workspace,
+            datasources=datasources,
+            config=self.config.model_dump() if hasattr(self.config, 'model_dump') else dict(self.config),
+            reflect_fn=None,  # Phase D = deterministic. Phase E에서 추가.
+            loop_config=LoopConfig(
+                max_iterations=self.config.agent.loop.max_iterations,
+                mode="deterministic",
+            ),
+        )
+
+        # 6. AgentVerdict → 기존 VerificationResult 변환
+        # (사용자 코드의 result schema에 맞게 변환)
+        result = self._agent_verdict_to_result(claim, verdict)
+        return result
+
+    def _agent_verdict_to_result(self, claim, agent_verdict):
+        '''AgentVerdict → 기존 VerificationResult 변환.
+
+        agent_verdict.verdict ('match' | 'mismatch' | ...) → result.verdict
+        agent_verdict.explanation → result.explanation
+        agent_verdict.confidence → result.confidence
+
+        evidence는 마지막 fetch_evidence observation에서 복원 가능 (workspace.read 등).
+        '''
+        # ★ 사용자 코드의 VerificationResult schema에 맞게 작성
+        from structverify.core.schemas import VerificationResult, VerdictType
+        return VerificationResult(
+            claim_id=claim.claim_id,
+            verdict=VerdictType(agent_verdict.verdict.value),
+            confidence=agent_verdict.confidence,
+            explanation=agent_verdict.explanation,
+            evidence=None,  # 또는 마지막 observation에서 복원
+        )
+```
+
+### 3. 첫 테스트 (안전 모드)
+
+`config.yaml`에서:
+```yaml
+agent:
+  enabled: true  # 켜기
+```
+
+같은 출생아 기사 재실행 후 로그 확인:
+- `[planner] {claim_id}: Plan 생성 완료. type=... data_points=...`
+- `[loop] {claim_id}: 시작. plan.type=growth_rate, steps=4, mode=deterministic`
+- `[loop] {claim_id} iter 1: action=catalog_search`
+- `[loop] {claim_id} iter 2: action=fetch_evidence`
+- ... 등
+
+만약 *Plan은 잘 생성되는데 Loop이 fail*하면:
+- KOSISDataSource의 TODO 4곳 (`structverify/retrieval/kosis_source.py`) 사용자 코드와 매핑 확인
+- 특히 catalog_search/kosis_connector의 *실제 함수 이름 + 시그니처*
+
+## 디버깅 팁
+
+1. **Plan 단계 실패** → planner 직접 호출해서 LLM 응답 확인:
+   ```python
+   plan = await planner.plan(claim, ...)
+   print(plan.model_dump_json(indent=2))
+   ```
+
+2. **DataSource 호출 실패** → KOSIS adapter 직접 테스트:
+   ```python
+   from structverify.retrieval.kosis_source import KOSISDataSource
+   ds = KOSISDataSource()
+   cands = await ds.search_catalog(query="출생아 수")
+   print(cands)
+   ```
+
+3. **agent.enabled=false로 즉시 롤백** — 기존 경로로 돌아감.
+
+## 점진적 도입 추천
+
+1. **Step 1**: agent.enabled=false 유지. Phase A-C zip만 적용 — *기존 결과 그대로*.
+2. **Step 2**: *별도 테스트 스크립트*로 planner.plan() 호출 → Plan JSON 확인.
+3. **Step 3**: kosis_source.py의 TODO 4곳 채움 + KOSIS DataSource 단독 테스트.
+4. **Step 4**: agent.enabled=true로 한 claim만 처리 → 로그 분석.
+5. **Step 5**: 8 claim 전체 실행. 기존 결과와 비교.
+"""