structverify 0.3.0__py3-none-any.whl

structverify/config/default.yaml

@@ -0,0 +1,350 @@
+# StructVerify Lab v2.0 — 기본 설정
+app:
+  name: "StructVerify Lab"
+  version: "0.2.0"
+  debug: true
+
+# ────────────────────────────────────────────────────────────────────────
+# Phase A 추가 섹션 — config/default.yaml 끝에 *추가*하세요.
+# 기존 섹션 (llm, embedding, kosis, ...) 은 *그대로* 유지.
+# ────────────────────────────────────────────────────────────────────────
+
+# === Agent (멀티턴 + memory + agentic 검증) ===
+# Phase A에서는 *자리만* 추가. 실제 호출은 Phase D (loop) 통합 후.
+agent:
+  enabled: true                              # Phase A는 false 유지. Phase D에서 true.
+
+  workspace:
+    backend: "local"                          # local | minio | s3 (지금은 local만 구현)
+    local_path: "./agent_workspace"           # workspace 디렉토리
+    persist_after_job: true                   # dev=true (디버깅), prod=false (정리)
+    cleanup_after_days: 7                     # persist=false 시 며칠 후 자동 삭제
+    # [2026-05-21] workspace 격리 단위:
+    #   - "doc_hash" : 본문 텍스트 md5 hash 기준. *같은 본문이면 같은 디렉토리*라
+    #                  KOSIS fetch 캐시(verified_facts/sibling_evidence/successful_stat_ids)가
+    #                  API 호출 사이에 살아있어 같은 기사 재검증이 빠름. 단점: KOSIS
+    #                  쪽 데이터가 갱신돼도 stale 캐시 사용 가능 + 다른 유저가 같은 텍스트
+    #                  넣으면 캐시 공유 (멀티-테넌트 격리 필요하면 부적합).
+    #   - "job_id"   : API job_id (sv_platform이 발급한 UUID) 기준. *매 요청마다 cold*
+    #                  start라 정확성↑ 속도↓. 라이브러리 단독 사용(CLI 등)에서 external_job_id
+    #                  미제공 시 fresh UUID로 폴백.
+    scope: "job_id"
+    # 외부에서 주입한 job_id (scope="job_id"일 때 사용). sv_platform이 자동 set.
+    # 라이브러리 직접 사용 시 None 두면 호출당 fresh UUID 발급.
+    external_job_id: null
+
+  memory:
+    backend: "file"                           # file | redis (지금은 file만)
+    max_length_chars: 50000                   # memory.md 읽을 때 LLM에 넘기는 상한
+    summarize_threshold: 30000                # 이 이상이면 LLM 요약 (Phase D+)
+
+  loop:
+    mode: "reflect"
+    max_iterations: 10                        # claim당 reflect 최대 횟수
+    enable_reflection: true                   # false면 plan만 따라감 (멀티턴 X)
+    single_pass_fallback: true                # agent 실패/예산 초과 시 v6.14 단일 패스
+    early_stop_on_confidence: 0.9             # 이상이면 finish 권장
+
+  llm:
+    # llm.models 에서 *이름*만 참조 — 기존 인프라 재사용
+    plan_model: "structured"                  # → HCX-007 (JSON 정확)
+    reflect_model: "light"                    # → HCX-DASH-002 (비용 ↓, 반복 호출)
+    explain_model: "heavy"                    # → HCX-003
+
+  budget:
+    max_tokens_per_job: 100000
+    max_concurrent_claims: 3                  # 동시 처리 claim 수
+    cost_alert_threshold_krw: 1000
+
+  cache:
+    enabled: true
+    ttl_hours: 24
+    backend: "memory"                         # memory | redis
+
+# === Data sources (KOSIS만 → multi-source 일반화) ===
+# 기존 kosis: 섹션은 *그대로 유지*. 여기서는 *추상화 레이어*만 추가.
+data_sources:
+  enabled: ["kosis"]                          # 회사: ["custom_db", "custom_csv"]
+  default_source: "kosis"
+
+  # KOSIS 데이터소스 — 검색/ranking/관련성 가드 설정
+  # 주의: 여기 'kosis' 섹션은 KOSISDataSource 생성자에 전달됨 (self._connector_config).
+  # 기존 top-level 'kosis:' 섹션(API URL, catalog 빌드 등)과 *별도*.
+  kosis:
+    # [2026-05-26] catalog_ranker — LLM batch ranking으로 키워드 가드 + per-table
+    # relevance_judge를 통합 대체. catalog_search + explore_catalog 결과를 union해
+    # 메타데이터(표 이름, 기관, category_path)와 함께 LLM에 1회 전달 → 의미 점수 순위.
+    catalog_ranker:
+      enabled: true                  # false면 기존 키워드 가드(Indicator Semantic Guard) 사용
+      score_threshold: 0.15          # 이 미만은 reject (안전망: 거부된 표도 try_ids 마지막에 추가)
+      pool_limit: 20                 # ranker에 보낼 후보 최대 개수
+      max_try: 10                    # ranker 순위로 try_ids 만들 때 상한
+      model_tier: "light"            # HCX-DASH-002
+
+    # [2026-05-26] remove_relevance_judge — true면 kosis_source의 per-table
+    # relevance_judge LLM 호출을 skip. catalog_ranker가 이미 의미 판단하므로
+    # 중복. 단, 1차 도입 시엔 안전망으로 *false*(둘 다 작동)로 두고, 18대/1336개
+    # 두 케이스 모두 OK 확인되면 true로 전환.
+    relevance_guard:
+      enabled: true                  # false면 per-table relevance_judge 완전 비활성
+      llm_fallback: true             # P32: 룰 거부 시 LLM 의미 판단 1회
+      model_tier: "light"
+      row_match_llm_fallback: true   # P33c: _select_best_row 매칭 0건일 때 LLM rescue
+      row_match_model_tier: "light"
+
+  # custom_csv — 회사 업로드 파일
+  custom_csv:
+    enabled: false
+    base_path: "./uploads/custom"
+    catalog_json: ""                          # 표 목록 JSON (필수)
+    embedding_cached: true
+
+  # custom_db — 회사 자체 DB
+  custom_db:
+    enabled: false
+    dsn_env: "CUSTOM_DB_DSN"                  # .env에서 로드
+    catalog_table: "stat_tables"
+    data_table_prefix: "data_"
+
+  # 외부 API plugin (확장 자리)
+  external:
+    world_bank:
+      enabled: false
+      base_url: "https://api.worldbank.org/v2"
+    oecd:
+      enabled: false
+
+# === Domain (도메인/언어 일반화) ===
+# 한국어 KOSIS 도메인 외 — 회사가 *자체 라벨/분류체계* 사용 가능.
+domain:
+  language: "ko"                              # ko | en | mixed
+
+  # 분류 라벨 (현재 코드에 하드코딩된 것 → config로)
+  classifier_labels_path: ""                  # YAML 파일 경로, 빈 값이면 inline 사용
+  classifier_labels:
+    - id: "population"
+      desc: "인구/가구 (출생, 사망, 혼인, 고령화, 인구구조)"
+    - id: "economy"
+      desc: "경제/산업/금융"
+    - id: "labor"
+      desc: "노동/고용"
+    - id: "health"
+      desc: "보건/복지"
+    - id: "education"
+      desc: "교육/문화"
+    # 회사 추가 예:
+    # - id: "internal_sales"
+    #   desc: "사내 매출/판매 지표"
+
+  schema_taxonomy_path: ""                    # parent_path 트리 YAML (선택)
+  extra_schema_fields: []                     # ClaimSchema 확장 필드 이름들
+
+llm:
+  provider: "upstage"                # hcx | openai | upstage  [conformance 테스트: HCX 키 없어 upstage]
+  # [v2 - 김예슬] HCX 키가 없으면 Upstage(Solar)로 전환 — OpenAI 호환이라 base_url만 다름.
+  #   provider:    "upstage"
+  #   api_key_env: "UPSTAGE_API_KEY"          # .env 에 UPSTAGE_API_KEY 세팅
+  #   base_url:    "https://api.upstage.ai/v1"
+  #   models: { heavy: "solar-pro", light: "solar-mini", structured: "solar-pro" }
+  #   (pip install openai 필요. ※ 임베딩/카탈로그는 아직 HCX-EMB 기준 — 임베딩 전환은 박재윤 파트)
+  models:
+    heavy:      "HCX-003"            # 복잡한 태스크 (check-worthiness, 설명 생성) — v1 API
+    light:      "HCX-DASH-002"       # 빠른 분류 (도메인, candidate scoring) — v3 API
+    structured: "HCX-007"            # JSON 구조화 추출 (schema_inductor 전용) — v3 Structured Outputs
+    reasoning:  "HCX-003"            # 복합 근거 종합
+  temperature: 0.1
+  max_tokens: 4096   # [2026-05-21] 2048 → 4096: reflect의 finish action에서 explanation이 길어져 JSON이 잘리는 케이스 방지. HCX-DASH-002 한도 내.
+  api_key_env: "NCP_API_KEY" # .env에 세팅
+  # [2026-05-21] 프로세스 전역 HCX 호출 사이 최소 간격(ms). 0이면 비활성.
+  # 22:24 로그 분석: 250ms(=4req/s)로 깔아도 21건 candidate 처리 중 지속적 429 발생.
+  # HCX 실제 sustained 한도는 1~2 req/s 추정 → 600ms로 상향.
+  # 권장값:
+  #   - 250ms (4 req/s)  : 너무 공격적, 429 빈발
+  #   - 500ms (2 req/s)  : 보통
+  #   - 600ms (≈1.6 r/s) : 안전 기본값
+  #   - 1000ms (1 req/s) : 매우 안전, 느림
+  min_call_interval_ms: 600         # 호출 사이 최소 간격(ms) — rate limit
+  max_concurrency: 4                # ★ 한 번에 보낼 최대 동시 LLM 요청 수 (429 방지 — 낮출수록 안전)
+
+embedding:
+  provider: "upstage"          # [conformance] HCX 키 없어 upstage (embedding-query/passage)
+  model: "HCX-EMB-V2"          # provider!=hcx면 무시됨 → embedding-query 자동
+  api_key_env: "UPSTAGE_API_KEY"
+
+reranker:
+  provider: "hcx"
+  model: "HCX-RERANKER"        # 리랭커 모델
+  api_key_env: "NCP_API_KEY"
+
+kosis:
+  base_url: "https://kosis.kr/openapi"
+  api_key_env: "KOSIS_API_KEY"
+  pgvector_dsn_env: "PGVECTOR_DSN"
+  timeout: 30
+  catalog:
+    rebuild: false          # true: 강제 재수집, false: DB에 있으면 skip
+    embed_batch_size: 100   # 임베딩 배치 크기
+    min_rows: 1000          # 이 수 이상이면 "이미 구축됨"으로 판단
+  # [P20 2026-05-22] KOSIS API raw 응답 캐시 TTL (시간).
+  # 같은 (stat_id, prdSe, startPrdDe, endPrdDe) 조합 재호출 시 API 호출 없이 캐시 사용.
+  # workspace 단위 파일 캐시 (agent_workspace/job_<id>/kosis_cache/<key>.json).
+  # scope=doc_hash 모드면 같은 본문 재검증 시 모든 KOSIS API 호출 skip.
+  #   - 0   : 영구 캐시 (만료 안 됨, 가장 빠름. KOSIS 갱신 시 수동 cleanup 필요)
+  #   - 24  : 24시간 (기본값, KOSIS 일일 갱신 대응)
+  #   - 168 : 1주일
+  cache_ttl_hours: 24
+
+  # [P32 2026-05-22] fetch_evidence의 *v6.17 표 관련성 가드*에 LLM fallback 추가.
+  # 룰베이스 _is_table_relevant()가 토큰 매칭으로 거부했을 때, LLM이 한 번 더
+  # *의미적*으로 판단해 false negative 회복.
+  # 예: indicator="체외 충격파 쇄석술 장비 수" + table="시군구별 주요 의료장비
+  # 현황" — 룰: "장비"(2글자, len<3 룰에 막힘) + "쇄석술"(table에 없음) → 거부.
+  # LLM: 표가 "의료장비"의 상위 분류이므로 row 검색하면 정답 찾을 가능성 ↑ → 통과.
+  # 룰 *통과* 시엔 LLM 호출 안 함 (속도). 룰 거부 시에만 LLM 1회 (~1초).
+  relevance_guard:
+    llm_fallback: true              # false면 룰베이스만 (P32 이전 동작)
+    model_tier: "light"             # HCX-DASH-002. heavy/structured/reasoning 격상 가능.
+    # [P33c 2026-05-22] row 매칭 단계 LLM fallback. _select_best_row가 indicator
+    # 룰 매칭 0건일 때 row의 unique ITM_NM/C_NM list를 LLM에 던져 의미적 매칭
+    # 식별. KOSIS 표 row가 *계층 분류*라 상위 카테고리 ITM_NM만 매칭되고 세부
+    # row를 못 찾는 케이스 (예: "체외 충격파 쇄석술 장비" vs ITM_NM='진단방사선
+    # ·특수의료장비')에서 진짜 row 식별.
+    row_match_llm_fallback: true
+    row_match_model_tier: "light"
+
+  # [P34 2026-05-22] Dimension resolver — KOSIS 표의 N차원 슬라이스 코드 결정.
+  # 기본 connector는 cmmt_rows[0]의 ITM_ID/OBJ_ID(합계 코드)를 박아 *세부 row
+  # 누락*. 이걸 메타+LLM으로 동적 결정해서 진짜 정답 슬라이스만 받음.
+  # 흐름: fetch 직전 → getMeta(ITM/OBJL01~04) 병렬 → LLM이 claim 매칭 코드 선택
+  #       → fetch_params.dim_overrides에 박음 → connector가 itmId/objL1~8 사용.
+  # 같은 stat_id는 process-level cache로 1회만 호출.
+  dimension_resolver:
+    enabled: true
+    model_tier: "light"             # HCX-DASH-002
+
+database:
+  # 로컬 개발용 DSN — 실제 비밀번호는 넣지 말고 각자 환경에 맞게 설정하세요.
+  # (규정 준수 검사 등 코어 기능은 DB가 필요 없습니다.)
+  url: "postgresql://localhost:5432/structverify"
+
+graph:
+  provider: "neo4j"             # "neo4j" | "memgraph"
+  uri: "bolt://localhost:7687"
+  user: "neo4j"
+  password_env: "NEO4J_PASSWORD"
+
+storage:
+  provider: "minio"
+  endpoint: "http://localhost:9000"
+  bucket: "structverify-raw"
+  access_key_env: "MINIO_ACCESS_KEY"
+  secret_key_env: "MINIO_SECRET_KEY"
+
+redis:
+  url: "redis://localhost:6379/0"
+
+dwh:
+  provider: "snowflake"         # "snowflake" | "bigquery" | "clickhouse"
+  snowflake:
+    account_env: "SNOWFLAKE_ACCOUNT"
+    user_env: "SNOWFLAKE_USER"
+    password_env: "SNOWFLAKE_PASSWORD"
+    warehouse: "STRUCTVERIFY_WH"
+    database: "STRUCTVERIFY_DB"
+    schema: "PUBLIC"
+
+adaptation:
+  feedback_threshold: 10        # 학습 트리거 최소 피드백 수
+  eval_min_score: 0.85          # 배포 게이트 최소 점수
+  mlflow_tracking_uri: "http://localhost:5000"
+
+verification:
+  tolerance_percent: 1.0
+  min_confidence: 0.7
+  
+# [P21 2026-05-22] catalog_search 의미 정확도 보강 — LLM rerank
+# [P25 2026-05-22] 일시 비활성 — row_preview가 LLM이 잘못된 표(DT_HIRA48_1,
+# DT_HIRA4Q 같은 *세부 분류 표*)를 정답(DT_35003_A7 같은 *시군구별 일반 표*)
+# 보다 우대하는 경향. 게다가 preview fetch가 KOSIS API에 5 candidates × 3 prdSe
+# = 15개 동시 호출을 만들어 "Server disconnected" 에러 + 30~50초 지연 유발.
+# 우선 catalog 임베딩 + prior_success score(P21A)만 사용. rerank 정확도 개선은
+# 다음 단계(prompt 강화 + preview Y-only + LLM 모델 격상 등)에서 처리.
+catalog_search:
+  # rerank_mode:
+  #   - "none"        : catalog 임베딩 + prior score만 (현재 기본)
+  #   - "table_name"  : top N 표 이름만 LLM에 노출해서 best 선택 (저비용)
+  #   - "row_preview" : top N 표의 sample row 1개 fetch + LLM에 노출 (정확도↑ 비용↑)
+  # [2026-05-26 회귀] row_preview rerank가 LLM 자유 추출 노이즈와 결합해 정답 표를
+  # 오히려 *다른 무관 표*로 옮기는 케이스 발생. 어제 잘 됐던 베이스(none)로 되돌림.
+  # 표 선택 정확도 개선은 별도 작업(indicator semantic guard 등)으로 처리.
+  rerank_mode: "none"
+  rerank_top_n: 5
+  rerank_min_score_gap: 0.15
+
+  # [P28 2026-05-22] Deep Exploration — row 단서 기반 외삽 reasoning.
+  # pgvector catalog은 *표 이름*만 임베딩 → row-level keyword (예: "체외 충격파
+  # 쇄석술", "치료 가능 사망률")는 cosine 검색에서 잘 안 잡힘. P21B의 row_preview
+  # rerank를 교체하는 새 mechanism (P25에서 P21B는 disable됨):
+  #   - top 3 후보 × Y prdSe × 5 row만 fetch (KOSIS 부하 ↓, P25 회피)
+  #   - prompt가 "best 단순 선택"이 아니라 "row 단서 외삽 reasoning"
+  #   - LLM이 "none"이면 호출자에 신호 → reflect가 query refinement 결정
+  #   - P20 KOSIS cache hit이면 비용 0
+  # 발동 조건 (둘 중 하나):
+  #   - T1: top1 score < trigger_low_score OR (top1-top2) < trigger_score_gap
+  #   - T2: catalog_search input에 force_explore=true (fetch 실패 후 reflect가 사용)
+  deep_explore:
+    enabled: true
+    top_n: 3                       # sample row 가져올 상위 후보 수
+    rows_per_table: 5              # 표당 LLM에 보여줄 row 수
+    trigger_low_score: 0.6         # top1 < 이 값이면 T1 발동
+    trigger_score_gap: 0.1         # top1-top2 < 이 값이면 T1 발동
+    max_per_claim: 2               # claim당 최대 발동 횟수 (loop 방지)
+    # 사용할 HCX 모델 tier — llm.models의 키 (heavy/light/structured/reasoning).
+    # row 패턴 의미 비교가 주작업이라 light(HCX-DASH-002) 충분. 정확도 더
+    # 필요하면 "heavy"(HCX-003) 또는 "structured"(HCX-007)로 격상 가능.
+    model_tier: "light"
+    # [P30 2026-05-22] force_explore=true 시 사용할 방식.
+    #   - "meta" (기본, 권장) : KOSIS getMeta(ITM/OBJ) — 표당 ~1초. ITM_NM list에
+    #                           indicator 키워드 직접 매칭 확인 가능. Catalog 후보
+    #                           안에 정답이 *있는데* cosine 점수로 묻힌 케이스에 강함.
+    #   - "row_preview"       : 표 전체 row preview — 표당 22~26초. Catalog 표 이름
+    #                           으론 모르지만 row 분류 패턴으로 외삽해야 하는 케이스.
+    # input의 explore_mode가 있으면 그게 우선. 없으면 이 default 사용.
+    explore_mode: "meta"
+    # meta 모드 옵션 — OBJ(분류 항목, 지역/연령 등) 메타도 가져올지.
+    # true: ITM + OBJL01 둘 다 → 정확도 ↑ 호출 수 2배.
+    # false: ITM만 → 1/2 호출.
+    include_obj: true
+
+  # [P30 2026-05-22] Query rewriter — catalog_search 직전에 LLM이 query 변형.
+  # input.query_rewrite=true일 때만 발동 (reflect가 명시 호출). row-level keyword
+  # (예: "체외 충격파 쇄석술 장비")로는 catalog 후보에 정답 표가 진입조차 안 되는
+  # 케이스에 사용. LLM이 "시군구별 의료장비" 같은 *표 이름 친화 어휘*로 변형 →
+  # 각 변형으로 catalog 검색 → 합집합 반환.
+  query_rewriter:
+    enabled: true
+    n_variations: 3                # 변형 query 개수 (원본 외에 추가로 생성할 개수)
+    model_tier: "light"
+
+candidate_detection:
+  enabled: true
+  threshold: 0.65
+  use_surface_signals: true
+  teacher_llm_fallback: true
+  # [2026-05-21] LLM 동시 호출 상한.
+  # candidate scoring(step 1) + check-worthiness(step 2) 두 단계가 각각 이 값을
+  # Semaphore 상한으로 사용. HCX-003은 *초당 요청 수* 제한이 빡세서 5 이상이면
+  # 429 Too Many Requests 폭주(2026-05-21 21:42 로그 — 5 concurrent → 전부 429).
+  # 22:24 재테스트: 4 concurrent + min_call_interval_ms=250도 지속 429 발생.
+  # → 2로 하향. min_call_interval_ms와 함께 *실제 처리량*을 결정.
+  concurrency: 2
+
+observability:
+  langfuse_enabled: false
+  log_level: "INFO"
+
+preprocessing:
+  sandbox_backend: "docker"      # "exec" | "docker" | "e2b"
+  use_llm_clean: true
+  
+enable_feedback: false   # 피드백/학습 루프 비활성화

structverify/core/config_loader.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+import os
+from pathlib import Path
+
+# 패키지에 번들된 기본 설정 — pip 설치 후에도 항상 존재한다.
+_PACKAGED_DEFAULT = Path(__file__).parent.parent / "config" / "default.yaml"
+# 개발 체크아웃(backend/config/default.yaml) 오버라이드 — 있으면 우선.
+_REPO_DEFAULT = Path(__file__).parent.parent.parent / "config" / "default.yaml"
+_REPO_ENV = Path(__file__).parent.parent.parent / ".env"
+
+
+def load_config(path: str | None = None) -> dict:
+    """설정을 로드한다.
+
+    우선순위: 명시 ``path`` → 개발 체크아웃(backend/config/default.yaml) →
+    패키지 번들(structverify/config/default.yaml). 어느 것도 없으면 ``{}``.
+    이 폴백 덕분에 ``pip install`` 후에도(리포 밖에서도) 기본 설정으로 동작한다.
+    """
+    from dotenv import load_dotenv
+    # 개발 체크아웃이면 .env 자동 로드 — 없으면 조용히 무시된다.
+    if _REPO_ENV.exists():
+        load_dotenv(_REPO_ENV)
+
+    import yaml
+    if path is None:
+        path = str(_REPO_DEFAULT if _REPO_DEFAULT.exists() else _PACKAGED_DEFAULT)
+    if not os.path.exists(path):
+        return {}
+    with open(path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}

structverify/core/pipeline.py

@@ -0,0 +1,280 @@
+"""
+# 수정자: 박재윤
+# 수정 날짜: 2026-04-29
+# 수정 내용: DBManager 초기화 및 save_claims, save_results 연동 구현
+
+# [DONE] DBManager 초기화 연동
+# [DONE] save_claims 파이프라인 연결
+# [DONE] save_results 파이프라인 연결
+# [DONE] 기사 텍스트 해시로 doc_id 고정 (재실행 시 중복 방지)
+# [DONE] save_claims source_type 파라미터 추가
+# [TODO] RawStorage 초기화 (MinIO/S3 업로드)
+# [TODO] DWHManager 초기화 (Snowflake)
+# [TODO] GraphStore 초기화 (Neo4j)
+# [TODO] save_document 구현 (db_manager.py)
+# [김예슬 - 2026-04-30 / v3]
+# - config 기본값 load_config() 적용
+# - feedback/학습: enable_feedback=false 이면 Step 11~12 skip
+# - runtime_agent에 kosis llm config 전달 (LLM Agent catalog 검색용)
+
+core/pipeline.py — v2.1 검증 파이프라인 (13단계)
+
+  ① 입력 → ② 전처리+SIR Tree → ③ 도메인 판별
+  → ④ Sentence Candidate Detection + Claim Detection
+  → ⑤ Schema Induction → ⑥ Graph Construction
+  → ⑦ Retrieval+Evidence Subgraph → ⑧ Verification
+  → ⑨ Explanation+Provenance → ⑩ Human Review
+  → ⑪ Feedback Logging → ⑫ Adaptation Trigger → ⑬ Report
+
+[김예슬]
+- 기존 Step 4의 "수치 포함 문장 필터링 + Claim Detection" 구조를
+  "문장 단위 candidate scoring + Claim Detection" 구조로 확장
+- has_numeric regex는 보조 surface signal로만 사용
+- 실제 검증 후보 여부는 candidate_score / candidate_label 기준으로 판단
+- 전체 파이프라인 흐름 및 Agent 간 연결 관리
+
+[참고] ReAct (Yao et al., ICLR 2023) — https://github.com/ysymyth/ReAct
+  Thought→Action→Observation 순환 기반 오케스트레이션 패턴
+"""
+from __future__ import annotations
+
+from structverify.core.schemas import (
+    SourceType,
+    SIRDocument,
+    VerificationReport,
+)
+from structverify.core.config_loader import load_config
+from structverify.preprocessing.extractor import extract_text
+from structverify.preprocessing.sir_builder import build_sir
+from structverify.agent.runtime_agent import RuntimeAgent
+from structverify.storage.db_manager import DBManager
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class VerificationPipeline:
+    """
+    13단계 검증 파이프라인 오케스트레이터.
+
+    사용법:
+        pipeline = VerificationPipeline()
+        report = await pipeline.run("https://news.example.com/article", "url")
+
+    Step 4 변경사항:
+        기존:
+            has_numeric=True 문장 선별 → LLM check-worthiness
+        변경:
+            sentence candidate scoring → 상위 후보에 대해 LLM check-worthiness
+
+    즉, Claim Detection 앞단에 "Sentence Candidate Detection"이 추가되었다.
+    """
+    def __init__(self, config: dict | None = None):
+        # [v3 김예슬] config 없으면 default.yaml 자동 로드
+        self.config = config if config is not None else load_config()
+
+        # runtime_agent에 kosis + llm 설정 합쳐서 전달
+        # → KOSISConnector가 LLM Agent(catalog 검색)에 llm 설정 필요
+        agent_config = {
+            **self.config,
+            "kosis": {
+                **self.config.get("kosis", {}),
+                "llm": self.config.get("llm", {}),
+            },
+        }
+        self.runtime_agent = RuntimeAgent(config=agent_config)
+
+        # [v1] - 박재윤: DBManager 초기화 연동
+        self.db_manager = DBManager(config=self.config.get("database", {}))
+
+        # [v3 김예슬] 피드백/학습 활성화 여부 (false면 Step 11~12 skip)
+        self.enable_feedback = bool(self.config.get("enable_feedback", False))
+
+        # TODO [김예슬]: BuilderAgent 초기화 (비동기 백그라운드 학습 루프)
+        # self.builder_agent = BuilderAgent(config=self.config)
+
+        # TODO [박재윤]: RawStorage 초기화 (MinIO/S3 업로드)
+        # self.raw_storage = RawStorage(config=self.config.get("storage", {}))
+
+        # TODO [박재윤]: DWHManager 초기화 (Snowflake)
+        # self.dwh_manager = DWHManager(config=self.config.get("dwh", {}))
+
+        # TODO [박재윤]: GraphStore 초기화 (Neo4j)
+        # self.graph_store = GraphStore(config=self.config.get("graph", {}))
+
+    async def run(
+        self,
+        source: str,
+        source_type: str = "text",
+        source_text: str | None = None,
+    ) -> VerificationReport:
+        """
+        source 입력을 받아 전체 검증 파이프라인을 수행한다.
+
+        Args:
+            source: 원본 입력 (텍스트/URL/PDF 경로 등)
+            source_type: "text" | "url" | "pdf" | "docx"
+            source_text: *옵션* — 이미 추출된 본문 텍스트가 있으면 전달.
+                URL/PDF 입력에서 sv_platform이 미리 추출해 Job.source_data에
+                저장한 뒤 그 텍스트를 그대로 넘겨주면 *중복 추출 없이* 파이프라인
+                진행. (실시간 partial 응답 매칭에도 사용됨.)
+                None이면 source에서 extract_text() 직접 호출.
+
+        Returns:
+            VerificationReport: 전체 검증 결과 보고서
+        """
+        src = SourceType(source_type)
+        logger.info(f"파이프라인 시작: {src.value}")
+        import structverify.progress as _progress
+        _enabled = list((self.config.get("data_sources", {}) or {}).get("enabled", []) or [])
+        _progress.emit("start", source=", ".join(_enabled) or src.value)
+
+        # ─────────────────────────────────────────────
+        # Step 1~2: 입력 → 전처리 → SIR Tree
+        # ─────────────────────────────────────────────
+        # TODO [이수민]: extractor.py — URL/PDF/DOCX 실제 추출 로직 구현
+        #   - URL: trafilatura.extract() 호출
+        #   - PDF: PyMuPDF(fitz) 페이지별 텍스트 추출
+        #   - DOCX: python-docx 단락 추출
+        if source_text is not None and source_text.strip():
+            # sv_platform이 사전 추출해 넘긴 경우 — 중복 호출 회피
+            raw_text = source_text
+            logger.info(f"파이프라인: 사전 추출 본문 사용 ({len(raw_text)}자)")
+        else:
+            raw_text = await extract_text(source, src)
+
+        # TODO [이수민]: sir_builder.py — SIR Tree 변환 검증
+        #   - block 분할 + 문장 분리 + 절대 offset 보정 확인
+        #   - entity_refs, event_refs 추출 (현재 regex placeholder → NER 교체 예정)
+        sir_doc = build_sir(
+            raw_text,
+            src,
+            source_uri=source if src == SourceType.URL else None,
+        )
+        # [v2] - 박재윤: 기사 텍스트 해시로 doc_id 고정 (재실행 시 중복 방지)
+        import hashlib
+        from uuid import UUID
+        text_hash = hashlib.md5(raw_text.encode()).hexdigest()
+        sir_doc.doc_id = UUID(text_hash)
+        # [2026-05-21] URL/PDF 입력의 추출된 본문을 SIRDocument에 보존.
+        # sv_platform이 Job.source_data로 복사해 프론트 "원문" 패널 렌더에 사용.
+        sir_doc.raw_text = raw_text
+        logger.info(f"SIR Tree: {len(sir_doc.blocks)} blocks")
+
+        # TODO [박재윤]: Step 1.5 — 원본 텍스트 → Raw Storage(S3/MinIO) 저장
+        # await self.raw_storage.upload(source, raw_text, metadata={"source_type": src.value})
+
+        # TODO [박재윤]: Step 2.5 — SIR Document → PostgreSQL 저장
+        # await self.db_manager.save_document(sir_doc)
+
+        # Step 3~9: Runtime Agent 실행
+        claims, results, nodes, edges = await self.runtime_agent.process(sir_doc)
+
+        # [v1] - 박재윤: Claims/Results → PostgreSQL 저장 (플랫폼 전용).
+        # 오픈소스 라이브러리 경로에는 postgres가 없으므로 저장 실패가
+        # 검증 자체를 죽이지 않게 감싼다 (psycopg2 미설치/연결불가 → 경고 후 진행).
+        try:
+            if claims:
+                await self.db_manager.save_claims(claims, domain=sir_doc.detected_domain, source_type=src.value)
+                logger.info(f"Claims 저장 완료: {len(claims)}건")
+            if results:
+                await self.db_manager.save_results(results, claims)
+                logger.info(f"Results 저장 완료: {len(results)}건")
+        except ImportError as e:
+            logger.debug(f"결과 저장 스킵 (DB 드라이버 없음 — 라이브러리 모드): {e}")
+        except Exception as e:  # noqa: BLE001 — 저장 실패가 검증 결과를 무효화하지 않음
+            logger.warning(f"결과 저장 실패 (검증 결과는 유효): {e}")
+
+        # TODO [박재윤]: Nodes/Edges → Neo4j 저장
+        # await self.graph_store.merge_nodes(nodes)
+        # await self.graph_store.merge_edges(edges)
+
+        # Step 10~13: 피드백/학습 루프 (enable_feedback=true 일 때만 활성화)
+        # [v3 김예슬] enable_feedback=false (기본값) → skip
+        # 활성화: config.yaml에서 enable_feedback: true
+        if self.enable_feedback:
+            pass
+            # TODO [김예슬]: Step 10 — Human Review 인터페이스 연동
+            # TODO [김예슬]: Step 11 — Feedback Logging
+            # TODO [김예슬]: Step 12 — Adaptation Trigger
+            # TODO [김예슬]: Step 13 — Report 렌더링
+        else:
+            logger.debug("Step 10~13 skip (enable_feedback=false)")
+
+        # TODO [박재윤]: DWH 적재 (검증 로그, 모델 성능, LLM 비용)
+        # await self.dwh_manager.load_verification_logs([...])
+
+        report = VerificationReport(
+            document=sir_doc,
+            claims=claims,
+            results=results,
+            graph_nodes=nodes,
+            graph_edges=edges,
+            domain_pack_used=sir_doc.detected_domain,
+        )
+        logger.info(f"파이프라인 완료: {len(results)} results")
+        _progress.emit("done", count=len(results))
+        return report
+
+
+async def verify_text(text: str, config: dict | None = None) -> VerificationReport:
+    """
+    최상위 API — 텍스트 입력 → 검증 보고서
+
+    Args:
+        text: 검증할 원문 텍스트
+        config: 선택적 설정 dict
+
+    Returns:
+        VerificationReport
+    """
+    return await VerificationPipeline(config).run(text, "text")
+
+
+# [v2 - 김예슬] 문서 입력(URL/PDF/DOCX/TEXT) 공개 진입점
+async def verify_document(
+    source: str,
+    source_type: str = "url",
+    config: dict | None = None,
+    source_text: str | None = None,
+) -> VerificationReport:
+    """
+    최상위 API — 문서 입력(URL/PDF/DOCX/TEXT) → 검증 보고서.
+
+    Args:
+        source: URL · 파일 경로 · 또는 본문 텍스트
+        source_type: "url" | "pdf" | "docx" | "text"
+        config: 선택적 설정 dict
+        source_text: 이미 추출된 본문이 있으면 전달(중복 추출 방지)
+
+    Returns:
+        VerificationReport
+    """
+    return await VerificationPipeline(config).run(source, source_type, source_text)
+
+
+# [v2 - 김예슬] 객체형 진입점 — 같은 config로 여러 번 검증할 때 (함수형은 일회성).
+class VerificationEngine:
+    """config를 한 번 주입해 두고 여러 문서를 검증하는 객체형 진입점.
+
+    - 함수형(`verify_text`/`verify_document`): 매번 config를 받는 *일회성* 호출에 편함.
+    - 객체형(`VerificationEngine`): 엔진을 만들어 두고 재사용.
+
+        engine = VerificationEngine(config)
+        r1 = await engine.verify_text("문장1")
+        r2 = await engine.verify_document(url, source_type="url")
+    """
+
+    def __init__(self, config: dict | None = None):
+        self._pipeline = VerificationPipeline(config)
+
+    async def verify_text(self, text: str) -> VerificationReport:
+        return await self._pipeline.run(text, "text")
+
+    async def verify_document(
+        self,
+        source: str,
+        source_type: str = "url",
+        source_text: str | None = None,
+    ) -> VerificationReport:
+        return await self._pipeline.run(source, source_type, source_text)