structverify 0.3.0__py3-none-any.whl

structverify/agent/tools/base.py

@@ -0,0 +1,222 @@
+"""
+structverify.agent.tools.base — Tool 인터페이스 추상 클래스.
+
+Tool = Agent가 호출 가능한 *원자 단위 작업*.
+  - LLM이 reflect 단계에서 `{action: <ActionType>, input: {...}}` 결정
+  - Loop이 해당 ActionType의 Tool 인스턴스 찾아서 execute()
+  - 결과를 Observation으로 변환 → memory.md + log.jsonl + observations/*.json
+
+설계 원칙:
+  1. **추상화**: Tool은 *기존 코드 직접 import 금지*. ToolContext의 datasources/workspace만 사용.
+     → KOSIS 외 source 추가 시 *Tool은 수정 X*, DataSource만 등록.
+  2. **결과 표준화**: ToolResult 형식 통일. output dict + 요약 문자열 + 성공/실패.
+  3. **Plugin 지원**: register_tool 데코레이터로 *동적 등록*. 회사 자체 Tool 추가 가능.
+
+Phase B에서는 *5개 핵심 Tool* 구현:
+  - catalog_search: DataSource 후보 검색
+  - fetch_evidence: 데이터 조회
+  - read_original: workspace의 원문 읽기
+  - calculate: 안전한 수식 계산
+  - finish: 종료 + Verdict 생성
+
+Phase D (Loop)에서 이 Tool들을 *Reflect Agent가 선택해서 호출*한다.
+"""
+from __future__ import annotations
+
+from structverify.utils.logger import get_logger
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Callable, Type
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from ..schemas import ActionType
+from ..workspace import Workspace
+
+logger = get_logger(__name__)
+
+
+# ── 결과 모델 ────────────────────────────────────────────────────
+
+class ToolResult(BaseModel):
+    """Tool.execute()의 표준 반환 형식.
+
+    Loop이 이걸 Observation으로 변환 (iter_num + action 추가).
+    """
+
+    output: dict[str, Any] = Field(default_factory=dict)
+    """Tool 호출 raw 결과. observations/*.json에 저장됨."""
+
+    summary: str = ""
+    """memory.md에 들어갈 *한 줄 요약*. agent가 다음 턴에 참고."""
+
+    success: bool = True
+    error: str | None = None
+    tokens_used: int = 0
+    """이 호출에 쓴 LLM 토큰 (직접 LLM 호출하는 Tool만 채움)."""
+
+
+# ── ToolContext — Tool에 주입되는 의존성 묶음 ──────────────────────
+
+@dataclass
+class ToolContext:
+    """Tool 실행 시 필요한 *환경/의존성*. Loop이 만들어서 Tool에 전달.
+
+    Tool은 self나 전역 상태 대신 *항상 context를 통해* 외부와 통신.
+    이게 *추상화 + 테스트 용이성*의 핵심.
+    """
+
+    workspace: Workspace
+    """현재 job의 workspace. read_source / append_memory / write_observation 등."""
+
+    claim_id: str | UUID
+    """현재 처리 중인 claim 식별자. workspace 파일 경로용."""
+
+    config: dict[str, Any] = field(default_factory=dict)
+    """Agent + DataSource + LLM 설정 dict. config.agent.*, config.data_sources.* 등."""
+
+    datasources: dict[str, Any] = field(default_factory=dict)
+    """{이름: BaseDataSource} 등록된 데이터 소스들. catalog_search/fetch tool이 사용."""
+
+    iter_num: int = 0
+    """현재 iteration 번호. 로깅 + observation 파일 이름용."""
+
+    claim: Any = None
+    """★ ADD: 현재 처리 중인 Claim 객체. fetch_evidence가 claim.schema에서
+    indicator/time_period/population/unit을 추출해 KOSIS params에 자동 매핑하기 위해 필요."""
+
+    current_plan: Any = None
+    """[2026-05-26] 현재 loop이 실행 중인 Plan 객체. replan tool이 새 plan을
+    만들 때 *원래 plan*을 LLM에 보여주는 입력으로 사용. loop이 매 iter ctx에 주입."""
+
+    # 향후 추가 가능 (Phase D+):
+    # llm_client: Any = None  # LLM 호출 클라이언트 (Reflect Agent용)
+    # token_budget_remaining: int = 100_000
+
+
+# ── ToolBase 추상 ────────────────────────────────────────────────
+
+class ToolBase(ABC):
+    """모든 Tool의 공통 인터페이스.
+
+    필수 구현:
+        - name: ActionType (CATALOG_SEARCH, FETCH_EVIDENCE, ...)
+        - description: LLM에게 보여줄 설명 (Plan/Reflect Agent prompt에 삽입)
+        - input_schema: 입력 형식 (LLM prompt에 표시)
+        - execute(input_data, context): 실제 동작
+
+    선택 구현:
+        - validate_input(input_data): 호출 전 검증 (기본은 input_schema 키 존재만 확인)
+    """
+
+    name: ActionType
+    description: str = ""
+    """LLM이 이 Tool을 *언제 쓸지* 결정하도록 설명. Plan/Reflect prompt에 들어감."""
+
+    input_schema: dict[str, Any] = {}
+    """입력 dict의 *예상 키*와 *간단한 설명*.
+    예: {"query": "검색어 (한국어 키워드)", "top_k": "최대 후보 수 (기본 5)"}
+    """
+
+    @abstractmethod
+    async def execute(
+        self,
+        input_data: dict[str, Any],
+        context: ToolContext,
+    ) -> ToolResult:
+        """Tool 실행. *예외는 ToolResult(success=False, error=...)로 변환*해서 반환.
+
+        Loop은 ToolResult를 받아 Observation으로 wrap, memory에 기록.
+        """
+
+    def validate_input(self, input_data: dict[str, Any]) -> tuple[bool, str | None]:
+        """입력 검증. (valid, error_msg).
+
+        기본 구현은 *항상 통과* — Tool 내부 execute()에서 *실제* 검증을 한다
+        (input_schema는 *LLM용 문서화 정보*일 뿐, 강제 검증 X).
+
+        하위 클래스에서 *진짜 필수 입력만 빠진 케이스*를 검증하려면 override.
+        """
+        return True, None
+
+    def render_help(self) -> str:
+        """LLM prompt에 *이 Tool 설명*을 삽입할 때 사용. 사람-읽기 좋은 markdown."""
+        lines = [f"### {self.name.value}", self.description, ""]
+        if self.input_schema:
+            lines.append("**Input fields:**")
+            for k, desc in self.input_schema.items():
+                lines.append(f"- `{k}`: {desc}")
+        return "\n".join(lines)
+
+
+# ── Tool Registry ────────────────────────────────────────────────
+
+_TOOL_REGISTRY: dict[ActionType, Type[ToolBase]] = {}
+
+
+def register_tool(action: ActionType) -> Callable[[Type[ToolBase]], Type[ToolBase]]:
+    """Tool 클래스를 *ActionType*에 등록하는 데코레이터.
+
+    Loop이 `tool_registry.get(action)`으로 Tool 클래스 찾고 인스턴스 만들어 execute.
+
+    Usage:
+        @register_tool(ActionType.CALCULATE)
+        class CalculateTool(ToolBase):
+            name = ActionType.CALCULATE
+            description = "안전한 수식 계산"
+            async def execute(...): ...
+    """
+    def decorator(cls: Type[ToolBase]) -> Type[ToolBase]:
+        if not issubclass(cls, ToolBase):
+            raise TypeError(f"{cls.__name__} must subclass ToolBase")
+        if not getattr(cls, "name", None):
+            cls.name = action
+        if action in _TOOL_REGISTRY:
+            logger.warning(
+                f"[tools.registry] Tool '{action.value}' already registered, "
+                f"overwriting ({_TOOL_REGISTRY[action].__name__} → {cls.__name__})"
+            )
+        _TOOL_REGISTRY[action] = cls
+        logger.info(f"[tools.registry] Tool 등록: {action.value} ({cls.__name__})")
+        return cls
+    return decorator
+
+
+def get_tool_class(action: ActionType) -> Type[ToolBase]:
+    """등록된 Tool 클래스 반환. 없으면 KeyError."""
+    if action not in _TOOL_REGISTRY:
+        available = [a.value for a in _TOOL_REGISTRY]
+        raise KeyError(
+            f"Tool '{action.value}' not registered. Available: {available}"
+        )
+    return _TOOL_REGISTRY[action]
+
+
+def list_tools() -> list[ActionType]:
+    """등록된 모든 Tool action 목록."""
+    return list(_TOOL_REGISTRY.keys())
+
+
+def build_tool(action: ActionType) -> ToolBase:
+    """Tool 인스턴스 생성 (기본은 인자 없음, override 가능)."""
+    cls = get_tool_class(action)
+    return cls()
+
+
+def render_all_help(actions: list[ActionType] | None = None) -> str:
+    """모든 등록된 Tool의 help를 markdown으로 — Plan/Reflect prompt에 삽입.
+
+    Args:
+        actions: 표시할 action 목록. None이면 *전부*.
+    """
+    if actions is None:
+        actions = list(_TOOL_REGISTRY.keys())
+    parts = []
+    for a in actions:
+        try:
+            tool = build_tool(a)
+            parts.append(tool.render_help())
+        except Exception as e:
+            logger.debug(f"render_help 실패 ({a.value}): {e}")
+    return "\n\n".join(parts)

structverify/agent/tools/calculate.py

@@ -0,0 +1,244 @@
+"""
+structverify.agent.tools.calculate — 안전한 수식 계산 Tool.
+
+Agent가 *데이터 점 N개로 수식 계산*할 때 사용.
+
+예시 사용:
+  - 증가율: (current - prev) / prev * 100
+  - 차이: current - prev
+  - 비교: a / b * 100 (점유율)
+
+안전성:
+  - `eval()`은 *절대 사용 X*.
+  - AST 기반 *제한된 산술 평가*. 식별자(변수) + 숫자 + 4칙 연산 + 비교만.
+  - 함수 호출/속성 접근/import 등 일체 차단.
+
+변수 주입:
+  - input_data["variables"] = {"current": 20717, "prev": 19059}
+  - expression = "(current - prev) / prev * 100"
+  - → 결과: 8.7028...
+"""
+from __future__ import annotations
+
+import ast
+from structverify.utils.logger import get_logger
+import math
+import operator
+from typing import Any
+
+from ..schemas import ActionType
+from .base import ToolBase, ToolContext, ToolResult, register_tool
+
+logger = get_logger(__name__)
+
+
+# ── 허용된 AST 노드 + 연산 ─────────────────────────────────────────
+
+_ALLOWED_BIN_OPS = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv,
+    ast.Mod: operator.mod,
+    ast.Pow: operator.pow,
+}
+
+_ALLOWED_UNARY_OPS = {
+    ast.UAdd: operator.pos,
+    ast.USub: operator.neg,
+}
+
+_ALLOWED_COMPARE_OPS = {
+    ast.Eq: operator.eq,
+    ast.NotEq: operator.ne,
+    ast.Lt: operator.lt,
+    ast.LtE: operator.le,
+    ast.Gt: operator.gt,
+    ast.GtE: operator.ge,
+}
+
+# 안전한 math 함수 (필요 시 추가)
+_ALLOWED_FUNCS: dict[str, Any] = {
+    "abs": abs,
+    "round": round,
+    "min": min,
+    "max": max,
+    "sqrt": math.sqrt,
+    "log": math.log,
+    "log10": math.log10,
+}
+
+
+def _safe_eval(node: ast.AST, variables: dict[str, float]) -> float | int | bool:
+    """제한된 AST 평가."""
+    if isinstance(node, ast.Expression):
+        return _safe_eval(node.body, variables)
+
+    # 숫자 상수
+    if isinstance(node, ast.Constant):
+        if isinstance(node.value, (int, float, bool)):
+            return node.value
+        raise ValueError(f"허용되지 않는 상수: {type(node.value).__name__}")
+
+    # 변수 (식별자)
+    if isinstance(node, ast.Name):
+        if node.id in variables:
+            return variables[node.id]
+        if node.id in _ALLOWED_FUNCS:
+            return _ALLOWED_FUNCS[node.id]
+        raise NameError(f"정의되지 않은 변수: {node.id!r}")
+
+    # 이항 연산
+    if isinstance(node, ast.BinOp):
+        op_type = type(node.op)
+        if op_type not in _ALLOWED_BIN_OPS:
+            raise ValueError(f"허용되지 않는 연산: {op_type.__name__}")
+        left = _safe_eval(node.left, variables)
+        right = _safe_eval(node.right, variables)
+        return _ALLOWED_BIN_OPS[op_type](left, right)
+
+    # 단항 연산 (-x, +x)
+    if isinstance(node, ast.UnaryOp):
+        op_type = type(node.op)
+        if op_type not in _ALLOWED_UNARY_OPS:
+            raise ValueError(f"허용되지 않는 단항 연산: {op_type.__name__}")
+        return _ALLOWED_UNARY_OPS[op_type](_safe_eval(node.operand, variables))
+
+    # 비교 (a > b)
+    if isinstance(node, ast.Compare):
+        left = _safe_eval(node.left, variables)
+        for op, right_node in zip(node.ops, node.comparators):
+            op_type = type(op)
+            if op_type not in _ALLOWED_COMPARE_OPS:
+                raise ValueError(f"허용되지 않는 비교 연산: {op_type.__name__}")
+            right = _safe_eval(right_node, variables)
+            if not _ALLOWED_COMPARE_OPS[op_type](left, right):
+                return False
+            left = right
+        return True
+
+    # 함수 호출 (abs, round, ...)
+    if isinstance(node, ast.Call):
+        func = _safe_eval(node.func, variables)
+        if not callable(func):
+            raise ValueError("함수 호출 불가")
+        # 위치 인자만 (kwargs 차단)
+        args = [_safe_eval(a, variables) for a in node.args]
+        if node.keywords:
+            raise ValueError("키워드 인자는 허용되지 않음")
+        return func(*args)
+
+    raise ValueError(f"허용되지 않는 노드 타입: {type(node).__name__}")
+
+
+def safe_calculate(expression: str, variables: dict[str, float] | None = None) -> float:
+    """문자열 수식을 *안전하게* 계산.
+
+    Args:
+        expression: 예 "(current - prev) / prev * 100"
+        variables: 예 {"current": 20717, "prev": 19059}
+
+    Returns:
+        계산 결과 (float). 비교식이면 bool도 가능하지만 보통 float.
+
+    Raises:
+        ValueError, NameError, ZeroDivisionError 등 — 호출자가 catch.
+    """
+    variables = variables or {}
+    tree = ast.parse(expression.strip(), mode="eval")
+    result = _safe_eval(tree, variables)
+    return result
+
+
+# ── Tool 구현 ────────────────────────────────────────────────────
+
+@register_tool(ActionType.CALCULATE)
+class CalculateTool(ToolBase):
+    """수식 계산 Tool.
+
+    Agent가 *2개 이상 데이터 점*을 모은 후 계산이 필요할 때 호출.
+    예: 증가율, 차이, 비율, 점유율 등.
+    """
+
+    name = ActionType.CALCULATE
+    description = (
+        "수치 계산. 모은 데이터 점들로 증가율/차이/비율을 계산할 때 사용. "
+        "예: (current - prev) / prev * 100. "
+        "허용 연산: + - * / % ** , 함수: abs, round, min, max, sqrt, log, log10."
+    )
+    input_schema = {
+        "expression": "수식 문자열. 예: '(current - prev) / prev * 100'",
+        "variables": "변수 dict. 예: {'current': 20717, 'prev': 19059}",
+    }
+
+    async def execute(
+        self,
+        input_data: dict[str, Any],
+        context: ToolContext,
+    ) -> ToolResult:
+        # ★ Phase E: LLM이 'formula' / 'expr' / 'equation' 등 다양한 키 이름을 쓸 수 있음
+        #   tool은 모두 받아들임 (alias).
+        expression = (
+            input_data.get("expression")
+            or input_data.get("formula")
+            or input_data.get("expr")
+            or input_data.get("equation")
+            or ""
+        ).strip()
+        variables = (
+            input_data.get("variables")
+            or input_data.get("vars")
+            or input_data.get("values")
+            or {}
+        )
+
+        if not expression:
+            return ToolResult(
+                output={},
+                summary="실패: expression 비어있음",
+                success=False,
+                error="expression이 비어있습니다.",
+            )
+
+        # variables의 모든 값이 숫자인지 검증
+        try:
+            variables = {k: float(v) for k, v in variables.items()}
+        except (TypeError, ValueError) as e:
+            return ToolResult(
+                output={},
+                summary=f"실패: variables 변환 오류 — {e}",
+                success=False,
+                error=f"variables의 값은 모두 숫자여야 합니다: {e}",
+            )
+
+        try:
+            result = safe_calculate(expression, variables)
+        except Exception as e:
+            logger.info(f"[calculate] 실패: {expression!r} | {e}")
+            return ToolResult(
+                output={"expression": expression, "variables": variables},
+                summary=f"계산 실패: {expression} → {type(e).__name__}: {e}",
+                success=False,
+                error=f"{type(e).__name__}: {e}",
+            )
+
+        # 성공
+        var_desc = ", ".join(f"{k}={v}" for k, v in variables.items()) if variables else "(no vars)"
+        summary = f"계산: {expression} | {var_desc} = {result}"
+
+        # bool인 경우 비교 결과
+        if isinstance(result, bool):
+            result_value: Any = result
+        else:
+            result_value = float(result)
+
+        return ToolResult(
+            output={
+                "expression": expression,
+                "variables": variables,
+                "result": result_value,
+            },
+            summary=summary,
+            success=True,
+        )