StructVerify 사용법

"""① 빠른 시작 — 규정 준수 검사 (대표 사용례).

내 규정집(PDF/txt)을 색인하고, 문서가 규정을 지켰는지 True/False로 읽는다.

필요: pip install structverify   +   UPSTAGE_API_KEY (.env 또는 환경변수)
실행: python examples/01_quickstart_conformance.py
"""
import structverify as sv

sv.configure_logging(level="WARNING")   # 결과만 보이게

# ── 1) 규정집 색인 — provider만 정하면 끝 (조항 단위 청킹 + 임베딩) ──
rules = sv.Ruleset.from_file("examples/demo/식품영양강조표시기준.txt", provider="upstage")
print(f"색인된 조항: {len(rules)}개")

# ── 2) 문장 하나 검사 → Verdict ──
v = rules.check("이 제품은 나트륨 함량이 100g당 200mg이므로 '低나트륨'으로 표시하였다.")
print("준수 여부 :", v.compliant)          # bool — if 문에 바로 사용
print("적용 조항 :", v.article)
print("기준 vs 주장:", v.rule_value, "vs", v.claim_value, v.unit or "")
print("근거     :", v.reason)

# ── 3) 문서 전체 — 측정값이 있는 줄마다 자동 판정 ──
for r in rules.check_file("examples/demo/영양성분_분석서.txt"):
    if r.is_unverifiable:
        continue
    print((" 준수" if r.compliant else " 위반"), r.article, "—", (r.claim or "")[:40])

# 큰 규정집이면 agent=True — 검색→판정→검색어 재구성→재검색을 스스로 반복(ReAct):
#   rules = sv.Ruleset.from_file("big_rulebook.pdf", provider="upstage", agent=True)
#   v.iterations 로 몇 번 만에 확정했는지 확인 가능

"""② 사실 검증 — 회사 CSV를 정답 데이터로.

참조 통계 CSV(지표·연도·값·단위 행)를 정답으로 연결하고, 문서 속 수치 주장을
자동으로 참/거짓 판정한다.

필요: pip install structverify   +   UPSTAGE_API_KEY
실행: python examples/02_factcheck_csv.py
"""
import structverify as sv

sv.configure_logging(level="WARNING")

# ── 1) 정답 데이터 연결 + 엔진 준비 (재사용 가능) ──
engine = sv.Verifier(
    provider="upstage",
    data=sv.DataSource.csv("examples/demo/factcheck_public_enterprise.csv"),
)

# ── 2) 텍스트 검증 → Report (주장별 Result의 컬렉션) ──
report = engine.verify(
    "한국전력공사의 2023년 부채비율은 600%에 달했다. "
    "같은 해 임직원 수는 2만 3천여 명이었다."
)

# ── 3) 결과 읽기 ──
print("문서 통과? ", report.ok)            # 거짓(mismatch) 주장이 없으면 True
for r in report:
    print(f" {r.verdict:13s} {r.claim[:38]}…")
    if r.is_mismatch:
        print(f"    → 실제 값: {r.value} {r.unit or ''} ({r.source}) — {r.reason[:60]}")

print("반박된 주장만:", len(report.mismatches), "건")
print(report.to_dict()["summary"] or "")    # JSON 직렬화도 지원

# 파일 검증은 engine.verify_file("연차보고서.pdf") — PDF/DOCX/txt 지원
# 일회성이면 sv.verify("문장", provider="upstage", data="kpi.csv") 한 줄로도 충분

"""③ 회사 DB 검증 — 정돈된 표 & 에이전틱 모드.

SQLAlchemy DSN이면 어떤 DB든 연결된다 (sqlite·postgres·mysql·Snowflake).
이 예제는 sqlite 파일을 즉석에서 만들어 셀프컨테인드로 시연한다.

필요: pip install "structverify[db]"   +   UPSTAGE_API_KEY
실행: python examples/03_database_agentic.py
"""
import sqlite3

import structverify as sv

sv.configure_logging(level="WARNING")

# ── 0) 시연용 DB 준비 (실전에서는 이미 있는 회사 DB에 연결) ──
db = "examples/_demo_company.db"
con = sqlite3.connect(db)
con.executescript("""
DROP TABLE IF EXISTS kpi;
CREATE TABLE kpi (name TEXT, year INT, value REAL, unit TEXT);
INSERT INTO kpi VALUES
  ('누적 고객 수', 2023, 1500000, '명'),
  ('평균 주문 금액', 2023, 145274, '달러'),
  ('연간 순매출', 2023, 3304, '억 달러');
DROP TABLE IF EXISTS orders;
CREATE TABLE orders (order_id INT, order_date TEXT, amount REAL);
INSERT INTO orders SELECT value, '2023-0' || (value % 9 + 1) || '-01', value * 137.5
  FROM (WITH RECURSIVE n(value) AS (SELECT 1 UNION ALL SELECT value+1 FROM n LIMIT 200) SELECT value FROM n);
""")
con.commit(); con.close()

# ── A) 정돈된 지표 표 — 컬럼 매핑만 주면 끝 ──
tidy = sv.DataSource.db(
    f"sqlite:///{db}", table="kpi",
    columns={"indicator": "name", "time_period": "year", "value": "value", "unit": "unit"},
)
report = sv.verify("2023년 평균 주문 금액은 20만 달러였다.", provider="upstage", data=tidy)
print("[정돈 표] 판정:", report[0].verdict, "— 실제", report[0].value, report[0].unit)

# ── B) 에이전틱 모드 — 원시 트랜잭션 테이블, 지표 정의 없이 ──
#    에이전트가 스키마를 조사해 claim마다 읽기전용 집계 SELECT를 자동 생성한다.
raw = sv.DataSource.db(f"sqlite:///{db}", agentic=True, tables=["orders"])
report = sv.verify("2023년 총 주문 건수는 200건이다.", provider="upstage", data=raw)
print("[에이전틱] 판정:", report[0].verdict, "—", report[0].reason[:70])

# 임베딩 의미검색 제어 (지표가 수백 개 이상일 때):
#   sv.DataSource.db(dsn, table="BIG_KPI", use_embedding="auto", embed_threshold=200)
# Snowflake 예:
#   sv.DataSource.db("snowflake://user:pw@account/DB/SCHEMA?warehouse=WH", table="REPORTING.KPI", ...)

"""④ 설정·로깅·진행상황 — 운영에서 쓰는 손잡이들.

필요: pip install structverify   +   UPSTAGE_API_KEY
실행: python examples/04_config_logging_progress.py
"""
import structverify as sv

# ── 1) 로깅 — 콘솔 + 파일, verbose로 상세도 제어 ──
sv.configure_logging("verification.log", level="INFO", verbose=False)

# ── 2) config를 미리 만들어 재사용 — 세부 키는 dict로 직접 조정 ──
cfg = sv.build_config(
    provider="upstage",              # upstage | openai | gemini | hcx
    tolerance=2.0,                   # 수치 허용오차(%) — verification.tolerance_percent
    data="examples/demo/factcheck_public_enterprise.csv",
)
cfg["llm"]["max_concurrency"] = 2          # 429(rate limit) 나면 낮추기
cfg["llm"]["min_call_interval_ms"] = 800   # 호출 간 간격(ms)도 함께
cfg["agent"]["loop"]["max_iterations"] = 6 # claim당 에이전트 반복 상한

engine = sv.Verifier(config=cfg)

# ── 3) 진행상황 — 로컬 웹 대시보드 + 터미널 진행바 ──
#    환경변수로도 제어: SV_PROGRESS=off|terminal|web (인자보다 우선)
with sv.progress_dashboard(web=False):      # 터미널만. 웹까지: sv.progress_dashboard()
    report = engine.verify("한국전력공사의 2023년 부채비율은 600%에 달했다.")

print("판정:", [r.verdict for r in report], "→ verification.log에 로그 저장됨")

"""⑤ 감독 학습 루프 — 정답 데이터로 자체 모델 기르기.

이 파일은 GPU 없이 끝까지 실행된다 (학습은 핸드오프 명령만 출력).
GPU 머신(Colab T4/L4, RTX 3060+)에서는 run=True로 바꾸면 그 자리에서 학습.

필요: pip install structverify            # 코어는 GPU 불필요
       pip install "structverify[training]"      # NVIDIA에서 실제 학습 시
       pip install "structverify[training-mac]" # Apple Silicon에서 실제 학습 시
실행: python examples/05_training_loop.py
"""
import json

from structverify.training import LearningLoop
from structverify.training.dataset import write_jsonl
from structverify.training.tasks import build_example

# ── 1) 학습 데이터 만들기 — 정답 표에서 match/mismatch 예시를 프로그램 생성 ──
#    실전에서는 검증 운영 결과를 loop.add_reports(reports)로 넣는 게 핵심 재료.
GROUND_TRUTH = [
    {"indicator": "누적 고객 수", "value": 1_500_000, "unit": "명"},
    {"indicator": "평균 주문 금액", "value": 145_274, "unit": "달러"},
    {"indicator": "유럽 순매출 비율", "value": 20.05, "unit": "%"},
]
rows = []
for g in GROUND_TRUTH:
    v, u = g["value"], g["unit"]
    rows.append(build_example(                      # match 예시
        "verdict", claim_text=f"{g['indicator']}는 {v:,}{u}입니다.",
        evidence_value=v, evidence_unit=u,
        output=json.dumps({"verdict": "match",
                           "reason": f"주장이 공식 수치 {v:,}{u}와 일치합니다."}, ensure_ascii=False)))
    rows.append(build_example(                      # mismatch 예시 (40% 부풀림)
        "verdict", claim_text=f"{g['indicator']}는 {round(v*1.4):,}{u}에 달합니다.",
        evidence_value=v, evidence_unit=u,
        output=json.dumps({"verdict": "mismatch",
                           "reason": f"주장은 실제 {v:,}{u}와 약 40% 차이로 불일치합니다."}, ensure_ascii=False)))
write_jsonl(rows, "gt_dataset.jsonl")

# ── 2) 수집 → 품질검사 → 학습 ──
loop = LearningLoop(base_model="unsloth/Qwen2.5-7B-Instruct")
loop.add_seed().add_jsonl("gt_dataset.jsonl")        # 시드(한국어 파싱·SQL·판정 톤) + 내 데이터
ds, curation = loop.prepare("train.jsonl")           # 중복·라벨오류·편중 격리 + 사유 리포트

# run=False: 학습 머신에서 실행할 명령만 출력(핸드오프). GPU 머신이면 run=True.
# 학습 중에는 실시간 감독 한 줄 UI가 뜨고, 수렴하면 스스로 조기 종료한다.
info = loop.train("train.jsonl", "./adapter", backend="auto",
                  run=False, steps=500, early_stop=True, patience=200)

# ── 3) 학습 후 (GPU 머신에서) ──
# loop.diagnose("./adapter/trainer_state.json")      # 사후 진단 + 처방
# 스모크 테스트: python -m structverify.training.recipe.sample --adapter ./adapter
# 자가평가/채택: loop.evaluate(eval_set, tuned_engine=tuned) → .accepted

"""⑥ 학습된 모델 주입 — 어댑터를 파이프라인에 꽂고 EvalGate로 채택.

사전 준비 (GPU 서버에서 어댑터를 OpenAI 호환으로 서빙):
    # Ollama: Modelfile → FROM qwen2.5:7b-instruct / ADAPTER ./adapter
    ollama create sv-tuned -f Modelfile && ollama serve
    # vLLM:
    vllm serve Qwen/Qwen2.5-7B-Instruct --enable-lora --lora-modules sv-tuned=./adapter

필요: pip install structverify   (+ 위 서빙이 떠 있어야 실제 실행됨)
실행: python examples/06_custom_model_injection.py
"""
import structverify as sv
from structverify.training import EvalGate

data = sv.DataSource.csv("examples/demo/factcheck_public_enterprise.csv")

# ── 1) 기존(클라우드) 엔진 — 비교 기준 ──
base = sv.Verifier(provider="upstage", data=data)

# ── 2) 학습 모델 주입 — base_url + 티어별 "부분" 주입이 핵심 ──
#    llm.models는 티어 단위로 덮어쓸 수 있어서, 학습된 자리만 자체 모델로 점진 전환:
#      structured = 스키마 추출·판정 ·  heavy = 에이전틱 SQL·설명 ·  light = 분류·랭킹
cfg = sv.build_config(provider="upstage", api_key="none", data=data)
cfg["llm"]["base_url"] = "http://localhost:11434/v1"      # 자체 서빙 주소 (Ollama/vLLM)
cfg["llm"]["models"] = {"structured": "sv-tuned"}         # 판정·추출 자리만 교체
tuned = sv.Verifier(config=cfg)

# ── 3) EvalGate — 채택은 증명 후에 (학습 전/후를 같은 평가셋으로 채점) ──
eval_set = [
    {"text": "한국전력공사의 2023년 부채비율은 600%에 달했다.", "expected": "mismatch"},
    {"text": "한국전력공사의 2023년 임직원 수는 23,000여 명이다.", "expected": "match"},
    # ... 라벨된 문장 30~50개 권장
]
gate = EvalGate(base).evaluate(eval_set, tuned_engine=tuned, margin=0.0)
print(gate.summary())            # before/after 정확도 + 채택 / 거부
if gate.accepted:
    engine = tuned               # 다음 검증부터 학습된 모델 사용 (나빠졌으면 자동 거부)