structverify 0.3.0__py3-none-any.whl

structverify/graph/graph_store.py

@@ -0,0 +1,281 @@
+"""
+graph/graph_store.py — Graph DB 인터페이스 (Neo4j)
+
+Claim Graph / Evidence Graph / Temporal Graph 의 노드·엣지를 Neo4j에 저장하고
+서브그래프를 조회한다.
+
+[설계 — 라이브러리 배포 전제]
+StructVerify는 라이브러리로 배포되므로 Neo4j는 *완전 옵셔널*이다.
+  - 사용자가 default.yaml의 graph.store.enabled=true + 접속정보를 넣어야 동작
+  - enabled=false / 섹션 없음 → GraphStore 비활성, 모든 호출 no-op
+  - neo4j 패키지 미설치 → 경고 후 비활성 (파이프라인은 그대로 진행)
+  - 연결/쿼리 실패 → 경고 후 해당 호출만 skip (검증 파이프라인 중단 없음)
+
+default.yaml 예시:
+    graph:
+      store:
+        enabled: true
+        uri: bolt://localhost:7687
+        user: neo4j
+        password: ${NEO4J_PASSWORD}
+        database: neo4j          # 선택, 기본 neo4j
+
+[참고] GraphRAG (arXiv 2501.00309)
+  Graph 기반 Evidence 검색 — subgraph 조회를 통한 다중 hop 추론 지원
+"""
+from __future__ import annotations
+
+from structverify.core.schemas import GraphNode, GraphEdge
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _safe_label(raw: str) -> str:
+    """Cypher 라벨/관계타입에 안전한 문자열로 정제.
+
+    영숫자와 밑줄만 허용 (Cypher injection 방지). node_type/edge_type은
+    Enum value라 보통 안전하지만 방어적으로 정제한다.
+    """
+    cleaned = "".join(
+        ch if (ch.isalnum() or ch == "_") else "_" for ch in str(raw)
+    )
+    if not cleaned or cleaned[0].isdigit():
+        cleaned = "N_" + cleaned
+    return cleaned
+
+
+def _to_primitive(value):
+    """Neo4j property로 쓸 수 있게 값을 정규화.
+
+    Neo4j는 중첩 dict/list를 property로 못 받으므로, 복합 타입은
+    문자열로 직렬화한다. None/숫자/bool/str은 그대로 통과.
+    """
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (list, tuple)):
+        if all(isinstance(v, (str, int, float, bool)) for v in value):
+            return list(value)
+        return str(list(value))
+    return str(value)
+
+
+def _clean_props(props: dict | None) -> dict:
+    """properties dict의 모든 값을 Neo4j 호환 형태로 변환."""
+    if not props:
+        return {}
+    return {k: _to_primitive(v) for k, v in props.items()}
+
+
+class GraphStore:
+    """
+    Neo4j 기반 Graph DB 인터페이스.
+
+    노드/엣지를 Cypher MERGE로 upsert하고, N-hop 서브그래프를 조회한다.
+    Neo4j가 없거나 비활성화면 모든 메서드가 안전하게 no-op 한다.
+    """
+
+    def __init__(self, config: dict | None = None):
+        """
+        Args:
+            config: default.yaml의 graph.store 섹션
+                    {enabled, uri, user, password, database}
+        """
+        self.config = config or {}
+        self.enabled = bool(self.config.get("enabled", False))
+        self.database = self.config.get("database") or "neo4j"
+        self.driver = None
+        self._connect_failed = False
+
+        if not self.enabled:
+            logger.info(
+                "[GraphStore] graph.store.enabled=false — Neo4j 저장 비활성화 "
+                "(노드/엣지는 메모리에서만 사용)"
+            )
+            return
+
+        uri = self.config.get("uri")
+        user = self.config.get("user")
+        password = self.config.get("password")
+        if not uri:
+            logger.warning(
+                "[GraphStore] enabled=true 이지만 graph.store.uri 미설정 "
+                "— Neo4j 저장 skip"
+            )
+            self.enabled = False
+            return
+
+        # neo4j 패키지는 옵셔널 의존성 — 미설치 시 graceful degrade
+        try:
+            from neo4j import AsyncGraphDatabase
+        except ImportError:
+            logger.warning(
+                "[GraphStore] 'neo4j' 패키지 미설치 — Neo4j 저장 skip. "
+                "사용하려면: pip install neo4j"
+            )
+            self.enabled = False
+            return
+
+        try:
+            auth = (user, password) if user else None
+            self.driver = AsyncGraphDatabase.driver(uri, auth=auth)
+            logger.info(
+                f"[GraphStore] Neo4j driver 초기화: {uri} "
+                f"(database={self.database})"
+            )
+        except Exception as e:
+            logger.warning(
+                f"[GraphStore] Neo4j driver 초기화 실패 — 저장 skip: {e}"
+            )
+            self.enabled = False
+            self.driver = None
+
+    def is_active(self) -> bool:
+        """저장이 실제로 가능한 상태인지."""
+        return bool(
+            self.enabled and self.driver is not None
+            and not self._connect_failed
+        )
+
+    async def save_nodes(self, nodes: list[GraphNode]) -> int:
+        """
+        노드 리스트를 Neo4j에 upsert한다 (Cypher MERGE).
+
+        node_type을 라벨로, node_id를 고유 키로 사용.
+        Returns: 저장된 노드 수 (비활성/실패 시 0).
+        """
+        if not self.is_active() or not nodes:
+            return 0
+        # 라벨(node_type)별로 묶어서 UNWIND 일괄 처리
+        by_label: dict[str, list[dict]] = {}
+        for n in nodes:
+            label = (
+                n.node_type.value if hasattr(n.node_type, "value")
+                else str(n.node_type)
+            )
+            label = _safe_label(label)
+            by_label.setdefault(label, []).append({
+                "node_id": n.node_id,
+                "label": n.label,
+                "domain": getattr(n, "domain", None),
+                "props": _clean_props(getattr(n, "properties", None)),
+            })
+
+        saved = 0
+        try:
+            async with self.driver.session(database=self.database) as session:
+                for label, rows in by_label.items():
+                    query = (
+                        f"UNWIND $rows AS row "
+                        f"MERGE (n:{label} {{node_id: row.node_id}}) "
+                        f"SET n.label = row.label, "
+                        f"    n.domain = row.domain, "
+                        f"    n += row.props"
+                    )
+                    await session.run(query, rows=rows)
+                    saved += len(rows)
+            logger.info(
+                f"[GraphStore] 노드 {saved}건 저장 (labels={list(by_label)})"
+            )
+        except Exception as e:
+            logger.warning(f"[GraphStore] 노드 저장 실패 — skip: {e}")
+            self._connect_failed = True
+            return 0
+        return saved
+
+    async def save_edges(self, edges: list[GraphEdge]) -> int:
+        """
+        엣지 리스트를 Neo4j에 upsert한다 (Cypher MATCH + MERGE).
+
+        from_node/to_node가 이미 저장된 노드를 가리킨다고 가정.
+        Returns: 저장된 엣지 수 (비활성/실패 시 0).
+        """
+        if not self.is_active() or not edges:
+            return 0
+        by_type: dict[str, list[dict]] = {}
+        for e in edges:
+            etype = (
+                e.edge_type.value if hasattr(e.edge_type, "value")
+                else str(e.edge_type)
+            )
+            etype = _safe_label(etype).upper()
+            by_type.setdefault(etype, []).append({
+                "from": e.from_node,
+                "to": e.to_node,
+                "weight": getattr(e, "weight", 1.0),
+                "props": _clean_props(getattr(e, "properties", None)),
+            })
+
+        saved = 0
+        try:
+            async with self.driver.session(database=self.database) as session:
+                for etype, rows in by_type.items():
+                    # 노드는 라벨 무관하게 node_id로 매칭
+                    query = (
+                        f"UNWIND $rows AS row "
+                        f"MATCH (a {{node_id: row.from}}) "
+                        f"MATCH (b {{node_id: row.to}}) "
+                        f"MERGE (a)-[r:{etype}]->(b) "
+                        f"SET r.weight = row.weight, r += row.props"
+                    )
+                    await session.run(query, rows=rows)
+                    saved += len(rows)
+            logger.info(
+                f"[GraphStore] 엣지 {saved}건 저장 (types={list(by_type)})"
+            )
+        except Exception as e:
+            logger.warning(f"[GraphStore] 엣지 저장 실패 — skip: {e}")
+            self._connect_failed = True
+            return 0
+        return saved
+
+    async def save_graph(
+        self, nodes: list[GraphNode], edges: list[GraphEdge],
+    ) -> tuple[int, int]:
+        """노드 먼저, 엣지 나중에 저장 (엣지가 노드를 참조하므로 순서 중요)."""
+        n = await self.save_nodes(nodes)
+        e = await self.save_edges(edges)
+        return n, e
+
+    async def get_subgraph(self, anchor_id: str, hops: int = 2) -> dict:
+        """
+        특정 앵커 노드에서 N-hop 서브그래프를 조회한다.
+
+        Returns: {"nodes": [...], "edges": [...]} — 비활성/실패 시 빈 결과.
+        """
+        if not self.is_active():
+            return {"nodes": [], "edges": []}
+        hops = max(1, min(int(hops), 5))  # 폭주 방지
+        try:
+            async with self.driver.session(database=self.database) as session:
+                query = (
+                    f"MATCH path = (n {{node_id: $anchor}})-[*1..{hops}]-(m) "
+                    f"WITH nodes(path) AS ns, relationships(path) AS rs "
+                    f"UNWIND ns AS nd "
+                    f"WITH collect(DISTINCT nd) AS nodes, rs "
+                    f"UNWIND rs AS rel "
+                    f"RETURN nodes, collect(DISTINCT rel) AS rels"
+                )
+                result = await session.run(query, anchor=anchor_id)
+                rec = await result.single()
+                if not rec:
+                    return {"nodes": [], "edges": []}
+                nodes = [dict(nd) for nd in rec["nodes"]]
+                edges = [
+                    {"type": rel.type, **dict(rel)} for rel in rec["rels"]
+                ]
+                return {"nodes": nodes, "edges": edges}
+        except Exception as e:
+            logger.warning(f"[GraphStore] 서브그래프 조회 실패: {e}")
+            return {"nodes": [], "edges": []}
+
+    async def close(self):
+        """드라이버 종료."""
+        if self.driver is not None:
+            try:
+                await self.driver.close()
+                logger.info("[GraphStore] Neo4j driver 종료")
+            except Exception as e:
+                logger.debug(f"[GraphStore] driver 종료 중 무시된 예외: {e}")
+            finally:
+                self.driver = None

structverify/graph/provenance.py

@@ -0,0 +1,52 @@
+"""
+graph/provenance.py — Provenance (출처 이력) 추적
+
+검증 결과가 어떤 커넥터 → 어떤 통계표 → 어떤 수치를 근거로 도출되었는지
+전체 경로를 기록하고 렌더링한다.
+
+[참고] Fact Verification on KG via Programmatic Reasoning (EMNLP Findings 2025)
+  KG 위에서 검증 경로를 프로그래밍적으로 추적하는 방법론.
+"""
+from __future__ import annotations
+from structverify.core.schemas import (
+    ProvenanceRecord, GraphNode, GraphEdge, GraphNodeType, GraphEdgeType)
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def build_provenance_subgraph(
+    provenance: ProvenanceRecord,
+    claim_node_id: str,
+    evidence_node_id: str,
+) -> tuple[list[GraphNode], list[GraphEdge]]:
+    """
+    Provenance 정보를 그래프 노드/엣지로 변환하여 출처 경로를 기록한다.
+
+    Returns:
+        tuple[nodes, edges]: 출처 그래프 구성 요소
+    """
+    source_node = GraphNode(
+        node_id=f"source:{provenance.provenance_id}",
+        node_type=GraphNodeType.SOURCE,
+        label=provenance.source_connector,
+        properties={"source_id": provenance.source_id,
+                    "query_used": provenance.query_used},
+    )
+
+    edges = [
+        GraphEdge(from_node=evidence_node_id, to_node=source_node.node_id,
+                  edge_type=GraphEdgeType.SOURCED_FROM),
+        GraphEdge(from_node=claim_node_id, to_node=evidence_node_id,
+                  edge_type=GraphEdgeType.VERIFIED_BY),
+    ]
+
+    return [source_node], edges
+
+
+def render_provenance_text(provenance: ProvenanceRecord) -> str:
+    """Provenance를 사람이 읽을 수 있는 텍스트로 렌더링한다."""
+    return (f"출처: {provenance.source_connector} | "
+            f"통계표 ID: {provenance.source_id} | "
+            f"검색어: {provenance.query_used} | "
+            f"조회 시각: {provenance.fetched_at.isoformat()}")

structverify/memory/__init__.py

@@ -0,0 +1,44 @@
+# [이수민 - 2026-05-13]
+# - AgentMemory 모듈 패키지 진입점 (초안)
+# - 그래프 누적 KG 방향 — Phase 2로 보류
+#
+# [이수민 - 2026-05-14 — 방향 재정렬]
+# - 작업 목표가 "정확도 개선용 사례 메모리(exemplar retrieval)"로 재조정됨
+#   목적:
+#     · 도메인 분류 정확도 ↑ (Step 3)
+#     · 시간 해석 정확도 ↑ ("작년", "올해" 등의 해석, Step 4.5)
+# - 신규 노출: ExemplarStore, DomainExample, TemporalExample, get_embedding
+# - 기존 AgentMemory 골격(agent_memory.py 등)은 보존하지만 import 안 함
+#   (Phase 2에서 그래프 누적 KG 합칠 때 다시 활용 예정)
+"""
+structverify.memory — 정확도 개선용 사례 메모리 + (보류) 그래프 누적 KG
+
+[현재 활성]  exemplar_store.py / embedder.py
+[Phase 2]   agent_memory.py / normalizer.py / storage/ (그래프 누적)
+"""
+from structverify.memory.working_memory import (
+    DocumentWorkingMemory,
+    StatIdUsage,
+)
+from structverify.memory.exemplar_store import (
+    ExemplarStore,
+    DomainExample,
+    TemporalExample,
+    format_domain_hint,
+    format_temporal_hint,
+)
+from structverify.memory.embedder import get_embedding, EMBEDDING_DIM
+
+__all__ = [
+    # ★ 현재 활성: Document-scoped Working Memory
+    "DocumentWorkingMemory",
+    "StatIdUsage",
+    # Phase 2 보류: 영속 사례 retrieval
+    "ExemplarStore",
+    "DomainExample",
+    "TemporalExample",
+    "format_domain_hint",
+    "format_temporal_hint",
+    "get_embedding",
+    "EMBEDDING_DIM",
+]

structverify/memory/agent_memory.py

@@ -0,0 +1,142 @@
+# [이수민 - 2026-05-13]
+# - 누적 KG 영속화 + dedup의 단일 진입점 (facade)
+# - load() : 파이프라인 시작 시 JSONL 전체 → ClaimGraph 로 복원
+# - merge(): Step 7 종료 후 호출, 신규 노드/엣지를 누적 메모리에 머지
+#            · 공유 노드(Metric/Entity/Time/Source/Evidence) dedup
+#            · 문서별 노드(Document/Claim/Sentence) append
+#            · 같은 (Metric, Time, Entity) 다른 value → CONTRADICTS edge 자동 생성
+# - query_metric() / query_evidence(): 과거 검증 결과 재활용용 조회 API
+# - 메서드 본문은 Phase 2에서 구현 (현재는 시그니처+docstring만)
+"""
+memory/agent_memory.py — AgentMemory facade
+
+누적 KG의 load / merge / query를 담당.
+파이프라인 시작 시 load(), Step 7 종료 후 merge() 호출.
+
+[Phase 1 — 구조화]
+메서드 시그니처만 정의. 본문은 Phase 2에서 구현.
+
+[Phase 2 — 구현 예정]
+- load(): JSONL 전부 읽어 ClaimGraph 인스턴스 구성
+- merge(): 신규 노드/엣지 머지 (dedup + CONTRADICTS 자동 탐지)
+- query_metric(): 특정 Metric에 매달린 과거 Claim 조회
+
+[Phase 3 — 통합 예정]
+runtime_agent.py:
+  Step 0  memory = AgentMemory(); graph = await memory.load()
+  Step 7 이후  await memory.merge(all_nodes, all_edges, doc_id, run_id)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from structverify.core.schemas import Claim, GraphEdge, GraphNode
+from structverify.graph.claim_graph import ClaimGraph
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class AgentMemory:
+    """
+    누적 KG의 영속화 + dedup layer.
+
+    [라이프사이클]
+        memory = AgentMemory()
+        graph  = await memory.load()           # Step 0
+        ...
+        await memory.merge(nodes, edges, ...)  # Step 7 이후
+    """
+
+    def __init__(
+        self,
+        memory_dir: str | Path = "backend/structverify/memory",
+    ):
+        """
+        Args:
+            memory_dir: JSONL 데이터 루트. 하위에 nodes/ edges/ 디렉터리 존재.
+        """
+        self.memory_dir = Path(memory_dir)
+        self.nodes_dir = self.memory_dir / "nodes"
+        self.edges_dir = self.memory_dir / "edges"
+
+    # ── 1. 로드 ──────────────────────────────────────────────────────────────
+
+    async def load(self) -> ClaimGraph:
+        """
+        JSONL 전체 → ClaimGraph 인스턴스.
+
+        파이프라인 시작 시 호출. 누적된 과거 KG를 인-메모리로 올림.
+
+        Returns:
+            ClaimGraph: 모든 과거 노드/엣지가 포함된 facade
+        """
+        raise NotImplementedError  # Phase 2
+
+    # ── 2. 머지 (Step 7 이후) ────────────────────────────────────────────────
+
+    async def merge(
+        self,
+        new_nodes: list[GraphNode],
+        new_edges: list[GraphEdge],
+        doc_id: str,
+        run_id: str,
+    ) -> dict:
+        """
+        신규 그래프를 누적 메모리에 머지.
+
+        흐름:
+          ① 공유 노드(Metric/Entity/Time/Source/Evidence) dedup by canonical_id
+          ② 문서별 노드(Document/Claim/Sentence) append
+          ③ 같은 (Metric, Time, Entity)에 다른 value 발견 → CONTRADICTS edge
+          ④ MemoryNode/MemoryEdge로 wrap (provenance 부착)
+          ⑤ JSONL append
+
+        Args:
+            new_nodes: 이번 doc의 신규 노드
+            new_edges: 이번 doc의 신규 엣지
+            doc_id:    이번 doc의 식별자
+            run_id:    이번 파이프라인 실행 식별자
+
+        Returns:
+            dict: {
+                "added_nodes":     int,
+                "deduped_nodes":   int,
+                "added_edges":     int,
+                "contradicts_found": int,
+            }
+        """
+        raise NotImplementedError  # Phase 2
+
+    # ── 3. 쿼리 ──────────────────────────────────────────────────────────────
+
+    async def query_metric(self, canonical_id: str) -> list[Claim]:
+        """
+        특정 Metric에 매달린 모든 과거 Claim 조회.
+
+        verifier가 새 claim 검증 전, 같은 indicator의 과거 verified claim이
+        있는지 확인할 때 사용. cache hit이면 KOSIS 재조회 생략 가능.
+
+        Args:
+            canonical_id: "metric:DT_1ES4001" 형식
+
+        Returns:
+            list[Claim]: 그 metric에 매달린 모든 Claim (verified 우선)
+        """
+        raise NotImplementedError  # Phase 2
+
+    async def query_evidence(self, stat_id: str, time_period: str | None = None):
+        """
+        특정 stat_id + 시점의 Evidence 캐시 조회.
+
+        같은 KOSIS row를 다른 doc이 이미 조회했다면 그 결과 재활용.
+        REUSED_BY 엣지 생성용.
+
+        Args:
+            stat_id:     KOSIS 통계표 ID (e.g. "DT_1ES4001")
+            time_period: 시점 (None이면 stat_id의 모든 시점)
+
+        Returns:
+            Evidence | None
+        """
+        raise NotImplementedError  # Phase 2

structverify/memory/embedder.py

@@ -0,0 +1,69 @@
+# [이수민 - 2026-05-14]
+# - HCX 임베딩 API 호출 헬퍼 (사례 저장/검색 공용)
+# - retrieval/catalog_search.py:_get_embedding 로직 재활용
+# - exemplar_store가 직접 HTTP 호출하지 않고 이 모듈을 통하도록 일원화
+# - KOSIS catalog와 같은 임베딩 모델 → 같은 벡터 공간에서 검색 일관성 확보
+# - 구조화 단계 — 시그니처와 인터페이스만. 본문은 다음 단계에서 구현.
+"""
+memory/embedder.py — 사례용 텍스트 임베딩 헬퍼
+
+[설계 의도]
+- 기존 KOSIS catalog 검색이 쓰는 HCX 임베딩(v2)을 재활용
+- 같은 임베딩 모델이어야 catalog와 같은 의미 공간에서 검색 가능
+- 벡터 차원: HCX-emb v2 = 1024차원
+
+[참조]
+- 원본 구현: structverify/retrieval/catalog_search.py:_get_embedding (line 230~)
+- 엔드포인트: https://clovastudio.stream.ntruss.com/v1/api-tools/embedding/v2
+"""
+from __future__ import annotations
+
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+EMBEDDING_DIM = 1024  # HCX-emb v2 차원
+
+
+async def get_embedding(text: str, api_key: str | None = None) -> list[float] | None:
+    """
+    텍스트 → HCX 임베딩 벡터 (1024-dim).
+
+    Args:
+        text:    임베딩 대상 텍스트 (도메인 분류용 본문 일부 또는 시간 표현+문맥)
+        api_key: CLOVASTUDIO_API_KEY (None이면 환경변수에서 읽음)
+
+    Returns:
+        list[float] (길이 1024) 또는 None (API 실패 시)
+    """
+    raise NotImplementedError  # 다음 단계
+
+
+async def get_embeddings_batch(
+    texts: list[str], api_key: str | None = None
+) -> list[list[float] | None]:
+    """
+    여러 텍스트 한 번에 임베딩 (배치).
+
+    초기 사례 일괄 적재 시 사용. 단건은 get_embedding() 권장.
+
+    Args:
+        texts: 임베딩 대상 텍스트 리스트
+
+    Returns:
+        list[list[float] | None] — 입력 순서 보존, 실패는 None
+    """
+    raise NotImplementedError
+
+
+# ── 보조 ────────────────────────────────────────────────────────────────────
+
+def vector_to_pgvector_str(vec: list[float]) -> str:
+    """
+    list[float] → pgvector INSERT용 문자열 "[1.0,2.0,...]".
+
+    pgvector는 vector 타입을 문자열 리터럴로 받음.
+    catalog_search.py:_search_pgvector의 변환 로직과 동일.
+    """
+    raise NotImplementedError