structverify 0.3.0__py3-none-any.whl

structverify/memory/exemplar_store.py

@@ -0,0 +1,241 @@
+# [이수민 - 2026-05-14]
+# - 정확도 개선용 사례 메모리 (exemplar retrieval store)
+# - 목적:
+#   · 도메인 분류 정확도 ↑ — 과거 (텍스트, 정답 도메인) 사례 retrieve → few-shot hint
+#   · 시간 해석 정확도 ↑ — 과거 (표현, 문맥, anchor_year, 정답 resolved) 사례 retrieve
+# - 저장 단위: DomainExample, TemporalExample (둘 다 임베딩 포함)
+# - 검색 방식: pgvector cosine 유사도 (기존 KOSIS catalog 검색과 동일 패턴)
+# - 임베딩: catalog_search.py의 HCX 임베딩 API 재활용
+# - 구조화 단계 — 시그니처와 인터페이스만. 본문은 다음 단계에서 구현.
+"""
+memory/exemplar_store.py — 사례 기반 retrieval memory
+
+[설계 의도]
+LLM이 매번 추론(도메인 분류, 시간 풀이)을 처음부터 하지 않고,
+과거 검증된 사례를 retrieve해서 few-shot hint로 주입.
+
+[라이프사이클]
+  실행 후: pipeline 끝에 정답 케이스 → store_domain() / store_temporal()
+  실행 중: Step 3 (domain), Step 4.5 (temporal)에서 retrieve_* 호출 → 프롬프트 hint
+
+[저장 위치]
+  PostgreSQL의 별도 테이블 (pgvector extension 이미 활성화됨):
+    - domain_examples (text_embedding, domain, ...)
+    - temporal_examples (expression_embedding, context, anchor_year, resolved, ...)
+
+[Phase 2 — 통합 예정]
+  classify_domain():
+    exemplars = await store.retrieve_domain_examples(text, top_k=3)
+    prompt += "참고 사례: ..."
+    → LLM 호출
+
+  build_document_temporal_graph():
+    for expr in temporal_expressions:
+        exemplars = await store.retrieve_temporal_examples(expr, anchor_year, top_k=3)
+        prompt_hint += "..."
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ── 사례 데이터 모델 ────────────────────────────────────────────────────────
+
+class DomainExample(BaseModel):
+    """
+    도메인 분류 사례.
+
+    저장 시점: pipeline 끝, 검증 결과(verdict)가 정답으로 확인된 케이스만.
+    """
+    example_id:  str
+    text:        str                    # 원문 일부 (제목 + 처음 N문장)
+    embedding:   list[float] | None = None
+    domain:      str                    # 정답 도메인 (employment, environment 등)
+    confidence:  float = 1.0            # 사람 검수 / LLM 자체평가
+    created_at:  datetime = Field(default_factory=datetime.utcnow)
+    source_doc:  str | None = None      # 출처 doc_id (추적용)
+
+
+class TemporalExample(BaseModel):
+    """
+    시간 표현 해석 사례.
+
+    저장 시점: document_graph LLM agent 결과가 검증된 케이스.
+    """
+    example_id:  str
+    expression:  str                    # 원본 표현 ("작년", "재작년 같은 기간")
+    context:     str                    # 표현이 등장한 문장 + 앞뒤 1문장
+    embedding:   list[float] | None = None  # expression + context 임베딩
+    anchor_year: int                    # 그 문서의 anchor_year
+    resolved:    str                    # 정답 절대 시점 ("2024", "2022-01..2022-11")
+    basis:       str | None = None      # 풀이 근거
+    created_at:  datetime = Field(default_factory=datetime.utcnow)
+    source_doc:  str | None = None
+
+
+# ── Exemplar Store API ──────────────────────────────────────────────────────
+
+class ExemplarStore:
+    """
+    pgvector 기반 사례 저장/검색.
+
+    [라이프사이클]
+        store = ExemplarStore()
+        await store.connect()
+
+        # 저장 (pipeline 후)
+        await store.store_domain(text, domain, ...)
+        await store.store_temporal(expression, context, anchor, resolved, ...)
+
+        # 검색 (pipeline 중)
+        exs = await store.retrieve_domain_examples(text, top_k=3)
+        exs = await store.retrieve_temporal_examples(expr, anchor, top_k=3)
+    """
+
+    def __init__(self, config: dict | None = None):
+        """
+        Args:
+            config: {
+                "pg_dsn": "postgresql://...",
+                "embedding_dim": 1024,   # HCX 임베딩 차원
+            }
+        """
+        self.config = config or {}
+
+    async def connect(self) -> None:
+        """asyncpg 풀 생성 + 테이블 존재 확인."""
+        raise NotImplementedError  # 다음 단계
+
+    async def close(self) -> None:
+        """연결 종료."""
+        raise NotImplementedError  # 다음 단계
+
+    # ── 저장 ────────────────────────────────────────────────────────────────
+
+    async def store_domain(
+        self,
+        text: str,
+        domain: str,
+        confidence: float = 1.0,
+        source_doc: str | None = None,
+    ) -> str:
+        """
+        도메인 사례 저장.
+
+        흐름:
+          ① text → 임베딩 (HCX API)
+          ② DomainExample 객체 생성
+          ③ domain_examples 테이블에 INSERT
+
+        Returns:
+            example_id
+        """
+        raise NotImplementedError
+
+    async def store_temporal(
+        self,
+        expression: str,
+        context: str,
+        anchor_year: int,
+        resolved: str,
+        basis: str | None = None,
+        source_doc: str | None = None,
+    ) -> str:
+        """
+        시간 표현 사례 저장.
+
+        흐름:
+          ① (expression + context) → 임베딩
+          ② TemporalExample 객체 생성
+          ③ temporal_examples 테이블에 INSERT
+
+        Returns:
+            example_id
+        """
+        raise NotImplementedError
+
+    # ── 검색 ────────────────────────────────────────────────────────────────
+
+    async def retrieve_domain_examples(
+        self,
+        text: str,
+        top_k: int = 3,
+    ) -> list[DomainExample]:
+        """
+        주어진 텍스트와 의미적으로 가까운 도메인 사례 retrieve.
+
+        흐름:
+          ① text → 임베딩
+          ② pgvector cosine 유사도 검색
+          ③ top_k 사례 반환 (domain 분포 다양성 확보 위해 필요 시 re-rank)
+
+        Returns:
+            list[DomainExample] — 유사도 높은 순
+        """
+        raise NotImplementedError
+
+    async def retrieve_temporal_examples(
+        self,
+        expression: str,
+        context: str | None = None,
+        anchor_year: int | None = None,
+        top_k: int = 3,
+    ) -> list[TemporalExample]:
+        """
+        주어진 시간 표현과 비슷한 과거 사례 retrieve.
+
+        흐름:
+          ① (expression + context or expression only) → 임베딩
+          ② pgvector 검색 (anchor_year 가까운 케이스 우대)
+          ③ top_k 사례 반환
+
+        Args:
+            expression:  새 문서에서 추출된 시간 표현
+            context:     주변 문맥 (있으면 정확도 ↑)
+            anchor_year: 새 문서의 anchor_year (있으면 비슷한 anchor 사례 우대)
+
+        Returns:
+            list[TemporalExample]
+        """
+        raise NotImplementedError
+
+    # ── 유틸 ────────────────────────────────────────────────────────────────
+
+    async def count(self) -> dict[str, int]:
+        """저장된 사례 수 통계. {domain: N, temporal: M}"""
+        raise NotImplementedError
+
+
+# ── 프롬프트 hint 변환 헬퍼 ─────────────────────────────────────────────────
+# retrieve 결과를 LLM 프롬프트에 주입할 텍스트로 변환.
+# 도메인 분류 / 시간 해석에서 공통으로 쓰임.
+
+def format_domain_hint(examples: list[DomainExample]) -> str:
+    """
+    DomainExample 리스트 → 프롬프트에 끼울 few-shot 텍스트.
+
+    예시 출력:
+        # 참고 사례 (과거 분류 결과)
+        - "쉬었음 청년이 21만..." → employment (신뢰도 0.95)
+        - "연평균기온 14.8도..."   → environment (신뢰도 0.92)
+    """
+    raise NotImplementedError
+
+
+def format_temporal_hint(examples: list[TemporalExample]) -> str:
+    """
+    TemporalExample 리스트 → 프롬프트 hint 텍스트.
+
+    예시 출력:
+        # 참고 사례 (과거 시간 표현 풀이)
+        - "작년" (anchor=2024 문서) → 2023
+        - "재작년 같은 기간" (anchor=2024) → 2022-01..2022-11
+    """
+    raise NotImplementedError

structverify/memory/normalizer.py

@@ -0,0 +1,91 @@
+# [이수민 - 2026-05-13]
+# - C안(KOSIS stat_id 기반) 정규화 헬퍼 모음
+# - canonicalize_metric/source/evidence: stat_id → canonical node_id 문자열 생성
+#   · metric:{stat_id}        예) "metric:DT_1ES4001"
+#   · source:{stat_id}
+#   · evidence:{stat_id}:{time}   예) "evidence:DT_1ES4001:2024"
+# - rename_metric_to_canonical(): Step 7 이후 호출
+#   · 임시 Metric 노드(LLM이 뱉은 indicator명) → canonical id로 rename
+#   · 매달려있던 BELONGS_TO 등 엣지를 canonical 노드로 redirect
+# - 함수 본문은 Phase 2 구현 (현재는 시그니처+docstring만)
+"""
+memory/normalizer.py — Canonical key 생성
+
+C안 (KOSIS stat_id 기반 정규화):
+  임시 Metric 노드 (LLM이 뱉은 indicator명)
+    → Evidence 도착 후 stat_id로 canonical node_id 생성
+    → 누적 메모리의 동일 stat_id Metric과 자동 dedup
+
+[Phase 1 — 구조화]
+함수 시그니처만 정의. 본문은 Phase 2에서 구현.
+"""
+from __future__ import annotations
+
+from structverify.core.schemas import Evidence, GraphEdge, GraphNode
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ── Canonical id 생성 ────────────────────────────────────────────────────────
+
+def canonicalize_metric(stat_id: str) -> str:
+    """
+    KOSIS stat_id → Metric 노드의 canonical node_id.
+
+    예시:
+        canonicalize_metric("DT_1ES4001") → "metric:DT_1ES4001"
+
+    Args:
+        stat_id: KOSIS 통계표 ID (DT_로 시작하는 문자열)
+
+    Returns:
+        canonical node_id 문자열
+    """
+    raise NotImplementedError  # Phase 2
+
+
+def canonicalize_source(stat_id: str) -> str:
+    """KOSIS stat_id → Source 노드의 canonical node_id."""
+    raise NotImplementedError  # Phase 2
+
+
+def canonicalize_evidence(stat_id: str, time_period: str | None) -> str:
+    """
+    Evidence 노드의 canonical node_id.
+
+    같은 stat_id라도 시점이 다르면 다른 Evidence.
+
+    예시:
+        canonicalize_evidence("DT_1ES4001", "2024")    → "evidence:DT_1ES4001:2024"
+        canonicalize_evidence("DT_1ES4001", "2024-09") → "evidence:DT_1ES4001:2024-09"
+    """
+    raise NotImplementedError  # Phase 2
+
+
+# ── Metric 노드 rename + 엣지 redirect ───────────────────────────────────────
+
+def rename_metric_to_canonical(
+    nodes: list[GraphNode],
+    edges: list[GraphEdge],
+    evidence: Evidence,
+    temp_metric_id: str,
+) -> tuple[list[GraphNode], list[GraphEdge]]:
+    """
+    Step 7 이후 호출. 임시 Metric 노드를 canonical id로 rename + edge redirect.
+
+    흐름:
+      ① evidence.stat_table_id로 canonical id 계산
+      ② nodes에서 temp_metric_id를 찾아 node_id를 canonical로 교체
+      ③ edges에서 from_node/to_node가 temp_metric_id인 것을 canonical로 redirect
+
+    Args:
+        nodes:          Step 6에서 만든 노드 리스트 (in-place 수정 또는 copy)
+        edges:          Step 6에서 만든 엣지 리스트
+        evidence:       Step 7에서 받은 Evidence (stat_table_id 보유)
+        temp_metric_id: LLM이 뱉은 indicator 기반 임시 id (e.g. "metric:쉬었음인구")
+
+    Returns:
+        (정규화된 nodes, 정규화된 edges)
+    """
+    raise NotImplementedError  # Phase 2

structverify/memory/schema.py

@@ -0,0 +1,119 @@
+# [이수민 - 2026-05-13]
+# - AgentMemory에서 사용할 영속 데이터 모델 정의
+# - MemoryNode/MemoryEdge: 기존 GraphNode/GraphEdge에 provenance 부착한 wrapper
+# - Provenance: run_id + doc_id + 타임스탬프 (롤백·last-write-wins 용)
+# - CrossDocEdgeType: cross-doc 전용 엣지(AGREES_WITH/SUPERSEDES/REUSED_BY)
+#   ※ CONTRADICTS/SUPPORTS는 core/schemas.py:GraphEdgeType에 이미 존재 — 재사용
+# - 하단에 canonical key 컨벤션(metric:{stat_id} 등) 주석으로 명시
+"""
+memory/schema.py — AgentMemory 영속 스키마
+
+기존 GraphNode/GraphEdge를 감싸는 영속 wrapper.
+- provenance 필드 추가 (어느 doc/run에서 생성됐는지)
+- created_at / updated_at (last-write-wins용)
+- cross-doc 전용 엣지 타입 enum
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from structverify.core.schemas import GraphNode, GraphEdge, GraphNodeType, GraphEdgeType
+
+
+# ── Cross-doc 전용 엣지 타입 ─────────────────────────────────────────────────
+# core/schemas.py의 GraphEdgeType은 단일 doc 그래프용.
+# 여기는 누적 메모리에서 doc 간 관계를 표현하는 별도 enum.
+#
+# 주의: GraphEdgeType.CONTRADICTS / SUPPORTS는 이미 존재 — 재사용 가능.
+# AgentMemory가 새로 만들 수 있는 doc 간 엣지는 아래 3종.
+
+class CrossDocEdgeType(str, Enum):
+    AGREES_WITH = "agrees_with"   # 같은 (Metric, Time, Entity)에 같은 value (다른 doc)
+    SUPERSEDES  = "supersedes"    # 더 최근 doc이 같은 claim에 다른 값 (정정보도)
+    REUSED_BY   = "reused_by"     # 과거 Evidence를 새 Claim 검증에 재활용
+
+
+# ── Provenance 메타데이터 ───────────────────────────────────────────────────
+# 모든 MemoryNode/MemoryEdge에 부착. 잘못된 doc 발견 시 그 기여분만 롤백 가능.
+
+class Provenance(BaseModel):
+    created_in_run: str    # run_id (파이프라인 1회 실행 단위)
+    from_doc_id:    str    # doc_id (어느 문서에서 비롯됐는지)
+    created_at:     datetime = Field(default_factory=datetime.utcnow)
+
+
+# ── 영속 노드/엣지 ───────────────────────────────────────────────────────────
+
+class MemoryNode(BaseModel):
+    """
+    JSONL에 저장될 영속 노드.
+
+    GraphNode를 감싸고 provenance + 타임스탬프 추가.
+    공유 노드(Metric/Entity/Time/Source/Evidence)는 canonical key로 dedup,
+    문서별 노드(Document/Claim/Sentence)는 append-only.
+    """
+    # 기존 GraphNode 필드
+    node_id:    str                # canonical key (e.g. "metric:DT_1ES4001")
+    node_type:  GraphNodeType
+    label:      str
+    domain:     str | None = None
+    properties: dict[str, Any] = Field(default_factory=dict)
+
+    # 영속화용 필드
+    provenance: Provenance
+    updated_at: datetime = Field(default_factory=datetime.utcnow)  # last-write-wins
+
+    @classmethod
+    def from_graph_node(
+        cls,
+        node: GraphNode,
+        run_id: str,
+        doc_id: str,
+    ) -> "MemoryNode":
+        """런타임 GraphNode → 영속 MemoryNode 변환."""
+        raise NotImplementedError  # Phase 2 구현
+
+
+class MemoryEdge(BaseModel):
+    """
+    JSONL에 저장될 영속 엣지.
+
+    GraphEdge를 감싸고 provenance 추가.
+    edge_type은 GraphEdgeType 또는 CrossDocEdgeType.
+    """
+    edge_id:   str
+    from_node: str
+    to_node:   str
+    # edge_type은 GraphEdgeType.value 또는 CrossDocEdgeType.value 문자열
+    edge_type: str
+    weight:    float = 1.0
+    properties: dict[str, Any] = Field(default_factory=dict)
+
+    # 영속화용 필드
+    provenance: Provenance
+
+    @classmethod
+    def from_graph_edge(
+        cls,
+        edge: GraphEdge,
+        run_id: str,
+        doc_id: str,
+    ) -> "MemoryEdge":
+        """런타임 GraphEdge → 영속 MemoryEdge 변환."""
+        raise NotImplementedError  # Phase 2 구현
+
+
+# ── Canonical key 컨벤션 ────────────────────────────────────────────────────
+# 공유 노드의 node_id 형식. Phase 2에서 실제 생성 시 이 규칙 따름.
+#
+#   Metric    : "metric:{stat_id}"          예) "metric:DT_1ES4001"
+#   Source    : "source:{stat_id}"          예) "source:DT_1ES4001"
+#   Evidence  : "evidence:{stat_id}:{time}" 예) "evidence:DT_1ES4001:2024"
+#   Entity    : "entity:{normalized_name}"  예) "entity:청년"
+#   Time      : "time:{iso}"                예) "time:2024", "time:2024-09"
+#
+# 문서별 노드(Document/Claim/Sentence)는 기존 UUID/anchor_id 사용.

structverify/memory/storage/__init__.py

@@ -0,0 +1,29 @@
+# [이수민 - 2026-05-13]
+# - memory.storage 패키지 진입점 (I/O 전담 layer)
+# - 로직(agent_memory.py) / 저장(storage/)을 분리하는 경계
+# - 현재 노출: read_all_nodes / read_all_edges / append_node / append_edge
+# - Phase 2 마이그레이션 시 jsonl_store → neo4j_store로 교체
+#   agent_memory.py 인터페이스는 그대로 유지
+"""
+memory.storage — 영속 layer (Phase 1: JSONL, Phase 2: Neo4j)
+
+Phase 1 책임 분리:
+  agent_memory.py → 로직 (dedup, merge, query)
+  storage/        → I/O (read_all, append)
+
+Phase 2 마이그레이션 시 jsonl_store를 neo4j_store로 교체.
+agent_memory.py의 인터페이스는 그대로.
+"""
+from structverify.memory.storage.jsonl_store import (
+    read_all_nodes,
+    read_all_edges,
+    append_node,
+    append_edge,
+)
+
+__all__ = [
+    "read_all_nodes",
+    "read_all_edges",
+    "append_node",
+    "append_edge",
+]

structverify/memory/storage/jsonl_store.py

@@ -0,0 +1,117 @@
+# [이수민 - 2026-05-13]
+# - JSONL append-only 저장소 (Phase 1)
+# - 저장 위치:
+#     backend/structverify/memory/nodes/{type}.jsonl  (노드 타입별 분리)
+#     backend/structverify/memory/edges/edges.jsonl   (엣지는 단일 파일)
+# - 원칙: append-only, 수정/삭제 안 함. dedup은 in-memory load 시 last-write-wins
+# - 노출 함수: read_all_nodes / read_all_edges / append_node / append_edge
+# - _NODE_FILES dict로 GraphNodeType → 파일명 매핑
+# - 함수 본문은 Phase 2 구현 (현재는 시그니처+docstring만)
+"""
+memory/storage/jsonl_store.py — JSONL append-only 저장소 (Phase 1)
+
+[저장 위치]
+  backend/structverify/memory/nodes/{type}.jsonl
+  backend/structverify/memory/edges/edges.jsonl
+
+[원칙]
+- Append-only: 수정/삭제 안 함. dedup은 in-memory load 시 last-write-wins.
+- 노드 타입별 분리: metrics / entities / times / sources / evidences /
+  documents / claims / temporals
+- 엣지는 단일 파일
+
+[Phase 1 — 구조화]
+함수 시그니처만 정의. 본문은 Phase 2에서 구현.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from structverify.memory.schema import MemoryEdge, MemoryNode
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ── 노드 파일 이름 컨벤션 ───────────────────────────────────────────────────
+# GraphNodeType → JSONL 파일명 매핑
+_NODE_FILES = {
+    "metric":        "metrics.jsonl",
+    "entity":        "entities.jsonl",
+    "time":          "times.jsonl",
+    "source":        "sources.jsonl",
+    "evidence":      "evidences.jsonl",
+    "document":      "documents.jsonl",
+    "claim":         "claims.jsonl",
+    "sentence":      "sentences.jsonl",
+    "temporal_expr": "temporals.jsonl",
+    "resolved_time": "temporals.jsonl",
+}
+_EDGES_FILE = "edges.jsonl"
+
+
+# ── 읽기 ────────────────────────────────────────────────────────────────────
+
+def read_all_nodes(nodes_dir: Path) -> list[MemoryNode]:
+    """
+    nodes/ 디렉터리의 모든 .jsonl 파일을 읽어 MemoryNode 리스트로 반환.
+
+    같은 node_id가 여러 번 등장하면 마지막 것 채택 (last-write-wins).
+
+    Args:
+        nodes_dir: Path to backend/structverify/memory/nodes/
+
+    Returns:
+        list[MemoryNode]
+    """
+    raise NotImplementedError  # Phase 2
+
+
+def read_all_edges(edges_dir: Path) -> list[MemoryEdge]:
+    """
+    edges/edges.jsonl을 읽어 MemoryEdge 리스트로 반환.
+
+    edge는 dedup 안 함 — 같은 (from, to, type)이라도 다른 doc/run에서 왔으면
+    별개 엣지로 보존. (그래야 provenance 추적 가능)
+
+    Args:
+        edges_dir: Path to backend/structverify/memory/edges/
+
+    Returns:
+        list[MemoryEdge]
+    """
+    raise NotImplementedError  # Phase 2
+
+
+# ── 쓰기 (append) ───────────────────────────────────────────────────────────
+
+def append_node(node: MemoryNode, nodes_dir: Path) -> None:
+    """
+    MemoryNode를 적절한 타입별 JSONL 파일에 append.
+
+    파일 결정:
+        node.node_type.value → _NODE_FILES[...]
+
+    Args:
+        node:      append할 MemoryNode
+        nodes_dir: Path to backend/structverify/memory/nodes/
+    """
+    raise NotImplementedError  # Phase 2
+
+
+def append_edge(edge: MemoryEdge, edges_dir: Path) -> None:
+    """
+    MemoryEdge를 edges/edges.jsonl에 append.
+
+    Args:
+        edge:      append할 MemoryEdge
+        edges_dir: Path to backend/structverify/memory/edges/
+    """
+    raise NotImplementedError  # Phase 2
+
+
+# ── 유틸 ────────────────────────────────────────────────────────────────────
+
+def ensure_dirs(memory_dir: Path) -> None:
+    """nodes/, edges/ 디렉터리가 없으면 생성."""
+    raise NotImplementedError  # Phase 2