structverify 0.3.0__py3-none-any.whl

structverify/agent/schemas.py

@@ -0,0 +1,262 @@
+"""
+structverify.agent.schemas — Agent 시스템의 데이터 모델.
+
+핵심 개념:
+  - DataPointSpec    : claim 검증에 필요한 *하나의 데이터 점* (지표 + 시점 + 인구)
+  - Plan             : 검증 계획 — 어떤 데이터 점들이 필요한지 + 어떻게 찾을지
+  - PlanStep         : 다음 행동 한 단위 (action + input + rationale)
+  - Observation      : action 실행 결과
+  - ReflectDecision  : Reflect Agent가 결정한 다음 행동
+  - AgentVerdict     : Agent loop 최종 결과
+
+Phase A에서는 *모델 정의*만. 실제 사용은:
+  - Plan       → Phase C (Plan Agent)
+  - Observation → Phase D (Loop)
+  - ReflectDecision → Phase D (Reflect Agent)
+  - AgentVerdict → Phase E (Verifier 확장)
+
+사용 패턴:
+    from structverify.agent.schemas import Plan, DataPointSpec, ClaimType
+
+    plan = Plan(
+        claim_id="abc-123",
+        claim_type=ClaimType.COMPARISON,
+        required_data=[
+            DataPointSpec(indicator="평균소비성향", time="2014"),
+            DataPointSpec(indicator="평균소비성향", time="2024"),
+        ],
+        initial_steps=[...],
+    )
+    workspace.write_plan(claim_id, plan.model_dump())
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+from pydantic import BaseModel, Field
+
+
+# ── Enums ─────────────────────────────────────────────────────────
+
+class ClaimType(str, Enum):
+    """Claim의 검증 유형 — Plan Agent가 분류한다."""
+
+    ABSOLUTE = "absolute"
+    """단일 시점 절대값. 예: '출생아 수 20,171명' (1개 데이터 점)."""
+
+    DIFFERENCE = "difference"
+    """두 시점 사이 차이값. 예: '0.04명 증가' (2개 데이터 점 + 차이 계산)."""
+
+    GROWTH_RATE = "growth_rate"
+    """두 시점 사이 증가율(%). 예: '6.7% 증가' (2개 데이터 점 + 비율 계산)."""
+
+    COMPARISON = "comparison"
+    """두 시점 직접 비교 (X→Y 형식). 예: '73.6% → 70.3%' (2개 데이터 점)."""
+
+    RANKING = "ranking"
+    """순위/상대 비교. 예: '1위', '하락폭이 가장 컸다' (여러 데이터 점)."""
+
+    AGGREGATION = "aggregation"
+    """[2026-05-21] 다년/다기간 집계 — 평균/총합/최대/최소 등.
+    예: '최근 3년 평균 …', '2022~2024년 총합 …' (N개 데이터 점 + 집계 계산).
+    도메인 무관, schema_inductor가 LLM으로 신호 감지. 시퀀스:
+    catalog_search → fetch_evidence × N → calculate(agg) → finish."""
+
+    UNKNOWN = "unknown"
+    """분류 불가."""
+
+
+class ActionType(str, Enum):
+    """Agent가 실행 가능한 action."""
+
+    CATALOG_SEARCH = "catalog_search"
+    """지정된 데이터 소스의 카탈로그(표 목록)에서 검색."""
+
+    EXPLORE_CATALOG = "explore_catalog"
+    """[패치 Q] 카탈로그의 카테고리 분포 + 대표 표를 탐색.
+
+    LLM이 어떤 카테고리 어휘를 써야 할지 모를 때(예: '기상관측통계' vs '기후 변화')
+    먼저 이 도구를 호출해 카탈로그가 실제로 어떤 분류·어휘를 쓰는지 파악한 뒤,
+    그 정보를 바탕으로 정확한 catalog_search query/category를 만든다.
+    룰베이스 도메인 매핑 없이도 DataSource 어휘를 자가학습."""
+
+    FETCH_EVIDENCE = "fetch_evidence"
+    """카탈로그에서 찾은 후보의 실제 데이터 조회."""
+
+    READ_ORIGINAL = "read_original"
+    """원문 기사 읽기 (claim 외 정보 필요할 때)."""
+
+    CALCULATE = "calculate"
+    """확보한 데이터로 수식 계산 (증가율, 차이 등)."""
+
+    REPLAN = "replan"
+    """[2026-05-26] plan 자체가 틀린 경우 — claim 값이 표에 직접 row로 없고
+    *계산해야 하는* 경우 (예: '증가 수 52'는 row가 아니라 current-prev delta).
+    기존 fallback(try_ids/catalog retry/row_matcher 등)이 모두 같은 plan 안에서
+    답 찾는 거라면, replan은 *plan을 통째로 새로 만든다*.
+
+    호출 조건:
+      - 모든 catalog 후보 fetch 실패 + catalog retry도 소진
+      - 표 sample을 보고 LLM이 'claim 값이 row로 없는 *계산 대상*'이라 판단할 때
+      - per-claim 최대 2회 (무한 replan 방지)
+    """
+
+    FINISH = "finish"
+    """판정 확정 후 종료."""
+
+
+class VerdictType(str, Enum):
+    """Agent loop 결과 verdict."""
+    MATCH = "match"
+    MISMATCH = "mismatch"
+    PARTIAL = "partial"
+    UNVERIFIABLE = "unverifiable"
+
+
+class StopReason(str, Enum):
+    """Agent loop 종료 이유."""
+    COMPLETED = "completed"
+    """모든 데이터 확보 + 계산 + finish 결정."""
+
+    MAX_ITERATIONS = "max_iterations"
+    """max_iter 초과 — 미완료 상태로 종료."""
+
+    GIVE_UP = "give_up"
+    """agent가 명시적으로 포기 (충분히 시도했으나 데이터 없음)."""
+
+    TOKEN_BUDGET = "token_budget"
+    """LLM 토큰 예산 초과."""
+
+    ERROR = "error"
+    """예외 발생."""
+
+
+# ── Data point ────────────────────────────────────────────────────
+
+class DataPointSpec(BaseModel):
+    """
+    검증에 필요한 *하나의 데이터 점* 명세.
+
+    Plan Agent가 claim에서 추출하고, agent loop이 *resolved_value*를 채움.
+    """
+    indicator: str
+    """지표명. '출생아 수', '평균소비성향' 등."""
+
+    time: str
+    """시점. 'YYYY' 또는 'YYYY-MM' 형식 권장."""
+
+    population: str | None = None
+    """대상 인구. '전체', '30대 이하' 등."""
+
+    unit_hint: str | None = None
+    """단위 힌트. '%', '명', '원' (LLM이 추론 — 절대 강제 X)."""
+
+    # ── 채워지는 필드 (agent loop 진행 중) ────────────────────────
+    resolved_value: float | None = None
+    """확보된 수치값. None이면 *아직 못 찾음*."""
+
+    resolved_unit: str | None = None
+    """실제 fetch된 데이터의 단위."""
+
+    source: str | None = None
+    """데이터 출처. 'KOSIS:DT_1L9U108', 'CSV:my_sales.csv' 등."""
+
+    source_time: str | None = None
+    """실제 fetch된 시점 (요청 시점과 다를 수 있음 — 가까운 row 매칭)."""
+
+
+# ── Plan ──────────────────────────────────────────────────────────
+
+class PlanStep(BaseModel):
+    """Plan에 포함된 *예상 행동 단계*. Reflect Agent가 변경/건너뛸 수 있다."""
+
+    action: ActionType
+    input: dict[str, Any]
+    rationale: str
+
+
+class FallbackStrategy(BaseModel):
+    """1차 탐색 실패 시 대안."""
+
+    use_original_text: bool = False
+    """원문에서 직접 수치 추출 시도."""
+
+    alternative_keywords: list[str] = Field(default_factory=list)
+    """다른 검색어 후보."""
+
+    give_up_after_attempts: int = 5
+    """이 횟수 시도 후에도 데이터 못 찾으면 unverifiable."""
+
+
+class Plan(BaseModel):
+    """Plan Agent가 생성하는 검증 계획."""
+
+    claim_id: str
+    claim_type: ClaimType
+    required_data: list[DataPointSpec]
+    initial_steps: list[PlanStep] = Field(default_factory=list)
+    fallback: FallbackStrategy = Field(default_factory=FallbackStrategy)
+    calculation_formula: str | None = None
+    """예: '(current - prev) / prev * 100' (증가율), 'X - Y' (차이)."""
+
+    notes: str | None = None
+    """Plan Agent의 자유 형식 메모 (디버깅용)."""
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+# ── Observation + Reflect ────────────────────────────────────────
+
+class Observation(BaseModel):
+    """Action 실행 결과."""
+
+    iter_num: int
+    action: ActionType
+    input: dict[str, Any]
+    output: dict[str, Any]
+    """Tool 호출 raw 결과. observations/*.json에도 저장됨."""
+
+    summary: str
+    """memory.md에 들어갈 한 줄 요약. agent가 다음 턴에 참고."""
+
+    success: bool = True
+    error: str | None = None
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class ReflectDecision(BaseModel):
+    """Reflect Agent의 다음 행동 결정."""
+
+    thought: str
+    """추론 과정 (디버깅 + 사용자에게 보일 수도)."""
+
+    action: ActionType
+    input: dict[str, Any]
+
+    confidence_so_far: float = 0.0
+    """0~1. finish 결정에 영향."""
+
+    # finish action일 때만 채워짐
+    proposed_verdict: VerdictType | None = None
+    proposed_explanation: str | None = None
+
+
+# ── Verdict ──────────────────────────────────────────────────────
+
+class AgentVerdict(BaseModel):
+    """Agent loop 최종 결과."""
+
+    claim_id: str
+    verdict: VerdictType
+    confidence: float
+    explanation: str
+
+    data_points: list[DataPointSpec] = Field(default_factory=list)
+    """확보된 데이터 점들. verifier.py가 이걸로 *최종 검산*."""
+
+    iterations_used: int = 0
+    total_tokens: int = 0
+    stop_reason: StopReason = StopReason.COMPLETED
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

structverify/agent/source_profiler.py

@@ -0,0 +1,229 @@
+"""structverify.agent.source_profiler — 연결된 데이터소스의 '검증 프로파일' 생성.
+
+목적: 탐지·스키마 파이프라인이 KOSIS를 가정하지 않고, *연결된 소스*로 검증
+가능한 것을 기준으로 삼게 한다.
+
+에이전트 관점:
+  · inspect  — 소스를 조회해 지표/단위/샘플을 수집 (도구)
+  · reason   — LLM이 도메인·검증 범위를 요약
+  · remember — SourceProfile(의미기억)로 캐시 → 탐지 프롬프트에 주입
+
+메모리 구조: SourceProfile 은 소스당 1회 만들어 캐시하는 *semantic memory*.
+(같은 소스로 여러 문서를 검증해도 재생성 안 함.)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# 지표가 이보다 많으면 "방대"로 보고 임베딩+랭커 전략을 쓴다. (KOSIS 26만 표 = 방대)
+_LARGE_THRESHOLD = 200
+
+
+@dataclass
+class SourceProfile:
+    """연결된 데이터소스가 '무엇을 검증할 수 있는지'에 대한 의미기억."""
+    source_name: str
+    domain: str = ""                       # 추론된 도메인 (예: 'corporate_finance')
+    description: str = ""                   # 이 데이터가 다루는 것 한 문장
+    indicators: list[str] = field(default_factory=list)   # 검증 가능한 지표들
+    units: list[str] = field(default_factory=list)
+    samples: list[str] = field(default_factory=list)       # 예시 사실 몇 개
+    # ★ 검색 전략 — 프로파일러가 데이터 규모를 보고 결정 (소스 이름 분기 대체).
+    #   {scale, indicator_count, method: keyword|embedding, use_ranker: bool, ranker_context}
+    retrieval_plan: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def is_empty(self) -> bool:
+        return not self.indicators
+
+
+def _decide_plan(indicators: list[str], domain: str, description: str) -> dict[str, Any]:
+    """데이터 특성을 보고 검색 전략을 정한다.
+
+    규모-적응은 *검색 방식*에만 적용:
+      작음  → 키워드 매칭 (후보가 적어 임베딩 비용 회피).
+      방대  → 임베딩 의미검색 (KOSIS 26만 표처럼 키워드로 못 좁힘).
+
+    판별(랭커)은 *규모와 무관하게 항상 ON* — KOSIS 수준의 자동 disambiguation.
+    소규모라도 "총 주문건수 vs 연간 주문건수", "특수의료장비 vs 의료장비"처럼
+    claim에 맞는 표를 고르는 모호성은 늘 존재한다. 후보가 2개 이상이면 LLM 랭커가
+    claim(지표·시점·대상)에 가장 맞는 표를 고른다. (후보 1개면 호출자가 스킵.)
+    """
+    n = len(indicators)
+    large = n > _LARGE_THRESHOLD
+    ctx = f"{domain}: {description}".strip(" :") if (domain or description) else ""
+    return {
+        "indicator_count": n,
+        "scale": "large" if large else "small",
+        "method": "embedding" if large else "keyword",
+        "use_ranker": n > 1,   # 후보 판별이 필요할 수 있으면 항상 (KOSIS 파리티)
+        "ranker_context": ctx[:200],
+    }
+
+
+# 소스명 → SourceProfile (프로세스 캐시). 같은 소스 재프로파일 방지.
+_CACHE: dict[str, SourceProfile] = {}
+
+
+def _inspect_tabular(ds: Any) -> tuple[list[str], list[str], list[str]]:
+    """csv/db 소스에서 (지표목록, 단위목록, 샘플문장). _read_rows 를 쓰는 소스용."""
+    rows = ds._read_rows()
+    cm = getattr(ds, "column_mapping", {})
+    ind_c, unit_c, val_c = cm.get("indicator", "indicator"), cm.get("unit", "unit"), cm.get("value", "value")
+    inds, units, samples = [], [], []
+    seen_i, seen_u = set(), set()
+    for r in rows:
+        i = (r.get(ind_c) or "").strip()
+        if i and i not in seen_i:
+            seen_i.add(i); inds.append(i)
+        u = (r.get(unit_c) or "").strip()
+        if u and u not in seen_u:
+            seen_u.add(u); units.append(u)
+    for r in rows[:6]:
+        i, v, u = (r.get(ind_c) or ""), (r.get(val_c) or ""), (r.get(unit_c) or "")
+        if i:
+            samples.append(f"{i} = {v}{u}")
+    # 지표가 많은 소스(예: 부품유형 150+)에서 프로파일 상한에 잘려 'headline' 지표
+    # (총/지역/연간/평균 등)가 빠지는 문제 방지 — 짧고 일반적인 이름을 앞으로 정렬.
+    # (짧은 지표명 = 대개 종합/대표 지표; 긴 이름 = 세부 카테고리.)
+    inds.sort(key=lambda s: (len(s), s))
+    return inds, units, samples
+
+
+def _inspect_docs(ds: Any) -> tuple[list[str], list[str], list[str]]:
+    """custom_docs 소스에서 조각 미리보기 → 주제(지표 대용)."""
+    chunks = getattr(ds, "_chunks", None) or getattr(ds, "chunks", None) or []
+    previews = []
+    for ch in list(chunks)[:8]:
+        txt = ch if isinstance(ch, str) else (ch.get("text", "") if isinstance(ch, dict) else "")
+        txt = " ".join(str(txt).split())[:60]
+        if txt:
+            previews.append(txt)
+    return previews, [], previews
+
+
+_PROFILE_PROMPT = """아래는 사실 검증의 '정답 기준'으로 쓸 데이터 소스의 내용이다.
+이 소스로 어떤 주장을 검증할 수 있는지 파악하라.
+
+[소스에 있는 지표/항목]
+{indicators}
+
+[단위]
+{units}
+
+[샘플]
+{samples}
+
+JSON으로만 답하라:
+{{"domain": "이 데이터의 도메인 한 단어(영문 스네이크, 예: corporate_finance)",
+  "description": "이 데이터가 다루는 내용을 한 문장으로"}}"""
+
+
+async def profile_source(
+    ds: Any,
+    source_name: str,
+    config: dict | None = None,
+    *,
+    max_indicators: int = 60,
+) -> SourceProfile:
+    """데이터소스를 프로파일링해 SourceProfile 반환 (캐시)."""
+    # 캐시 키: 소스명 + 실제 데이터 식별자(테이블/경로) — 같은 custom_db라도 테이블이
+    # 다르면 다른 프로파일이어야 한다.
+    _ident = (
+        getattr(ds, "table", None) or getattr(ds, "query", None)
+        or getattr(ds, "csv_path", None) or getattr(ds, "docs_path", None)
+        or (",".join(getattr(ds, "tables", []) or []) if getattr(ds, "agentic", False) else "")
+        or ""
+    )
+    cache_key = f"{source_name}:{_ident}"
+    if cache_key in _CACHE:
+        return _CACHE[cache_key]
+
+    # ── 에이전틱(text-to-SQL) 소스: 스키마 조사 → LLM이 지표 후보 제안 ──
+    if getattr(ds, "agentic", False) and hasattr(ds, "propose_metrics"):
+        try:
+            meta = await ds.propose_metrics(config)
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"[source-profiler] propose_metrics 실패({source_name}): {e}")
+            meta = {}
+        profile = SourceProfile(
+            source_name=source_name,
+            domain=str(meta.get("domain", "") or ""),
+            description=str(meta.get("description", "") or ""),
+            indicators=list(meta.get("indicators", []) or [])[:max_indicators],
+            units=list(meta.get("units", []) or [])[:20],
+            samples=list(meta.get("samples", []) or [])[:6],
+        )
+        if profile.indicators:
+            profile.retrieval_plan = _decide_plan(
+                profile.indicators, profile.domain, profile.description,
+            )
+            profile.retrieval_plan["agentic"] = True  # SQL로 임의 집계 가능 → worthiness 관대
+            logger.info(
+                f"[source-profiler] {source_name}(에이전틱): domain={profile.domain!r} "
+                f"제안지표 {len(profile.indicators)}개 · text-to-SQL 모드"
+            )
+        else:
+            logger.info(f"[source-profiler] {source_name}(에이전틱): 지표 제안 없음")
+        _CACHE[cache_key] = profile
+        return profile
+
+    # ── inspect ──
+    try:
+        if hasattr(ds, "_read_rows"):
+            inds, units, samples = _inspect_tabular(ds)
+        else:
+            inds, units, samples = _inspect_docs(ds)
+    except Exception as e:  # noqa: BLE001 — 프로파일 실패는 빈 프로파일로(파이프라인 보호)
+        logger.warning(f"[source-profiler] inspect 실패({source_name}): {e}")
+        inds = units = samples = []
+
+    profile = SourceProfile(
+        source_name=source_name,
+        indicators=inds[:max_indicators],
+        units=units[:20],
+        samples=samples[:6],
+    )
+    if not inds:
+        logger.info(f"[source-profiler] {source_name}: 지표 없음 — 빈 프로파일")
+        _CACHE[cache_key] = profile
+        return profile
+
+    # ── reason (LLM 요약) ──
+    try:
+        from structverify.utils.llm_client import LLMClient
+        llm = LLMClient(config=(config or {}).get("llm", {}))
+        out = await llm.generate_json_light(_PROFILE_PROMPT.format(
+            indicators="\n".join(f"- {i}" for i in inds[:40]),
+            units=", ".join(units[:20]) or "(미상)",
+            samples="\n".join(samples) or "(없음)",
+        ))
+        profile.domain = str((out or {}).get("domain", "") or "").strip()
+        profile.description = str((out or {}).get("description", "") or "").strip()
+    except Exception as e:  # noqa: BLE001
+        logger.warning(f"[source-profiler] reason 실패({source_name}): {e}")
+
+    # ★ 규모 보고 검색 전략 결정 (키워드 vs 임베딩+랭커)
+    profile.retrieval_plan = _decide_plan(
+        profile.indicators, profile.domain, profile.description,
+    )
+
+    logger.info(
+        f"[source-profiler] {source_name} 프로파일: domain={profile.domain!r} "
+        f"지표 {len(profile.indicators)}개 · 전략={profile.retrieval_plan['method']}"
+        f"(랭커 {'ON' if profile.retrieval_plan['use_ranker'] else 'OFF'})"
+    )
+    _CACHE[cache_key] = profile
+    return profile
+
+
+def clear_cache() -> None:
+    _CACHE.clear()

structverify/agent/tools/__init__.py

@@ -0,0 +1,64 @@
+"""
+structverify.agent.tools — Agent가 호출하는 Tool 모음.
+
+각 Tool은 *@register_tool(ActionType.X)* 데코레이터로 자동 등록됨.
+이 패키지를 import하면 *모든 Tool이 registry에 등록됨*.
+
+Phase B Tool 목록:
+  - catalog_search  : DataSource 카탈로그(표) 검색
+  - fetch_evidence  : 후보의 실제 수치 조회
+  - read_original   : workspace의 원문 기사 읽기
+  - calculate       : 안전한 수식 계산
+  - finish          : 검증 종료 + Verdict 생성
+
+회사 자체 Tool 추가:
+    from structverify.agent.tools import register_tool, ToolBase
+    from structverify.agent.schemas import ActionType
+
+    # ActionType에 새 항목 추가 후 (또는 기존 사용):
+    @register_tool(ActionType.YOUR_ACTION)
+    class YourTool(ToolBase):
+        ...
+
+Usage (Phase D Loop에서):
+    from structverify.agent.tools import get_tool_class, list_tools, render_all_help
+
+    # LLM prompt에 모든 Tool 설명 삽입
+    prompt = f"... Available tools:\n{render_all_help()} ..."
+
+    # LLM 응답 (decision)에서 action 받아서 실행
+    tool_cls = get_tool_class(decision.action)
+    tool = tool_cls()
+    result = await tool.execute(decision.input, context)
+"""
+from .base import (
+    ToolBase,
+    ToolContext,
+    ToolResult,
+    register_tool,
+    get_tool_class,
+    list_tools,
+    build_tool,
+    render_all_help,
+)
+
+# 모든 Tool 모듈 import — register_tool 데코레이터 실행 트리거.
+# (import 순서 무관 — registry는 ActionType 키 기반)
+from . import calculate           # noqa: F401
+from . import finish              # noqa: F401
+from . import read_original       # noqa: F401
+from . import catalog_search      # noqa: F401
+from . import fetch_evidence      # noqa: F401
+from . import explore_catalog     # noqa: F401
+from . import replan              # noqa: F401
+
+__all__ = [
+    "ToolBase",
+    "ToolContext",
+    "ToolResult",
+    "register_tool",
+    "get_tool_class",
+    "list_tools",
+    "build_tool",
+    "render_all_help",
+]