structverify 0.3.0__tar.gz → 0.3.2__tar.gz

{structverify-0.3.0/structverify.egg-info → structverify-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structverify
-Version: 0.3.0
+Version: 0.3.2
 Summary: Compliance & fact verification for documents — check your files against your own rulebook (PDF) or a data source, and read a plain True/False.
 Author-email: "김예슬 (Yeseul Kim)" <yesul0718@gmail.com>
 License: MIT License

{structverify-0.3.0 → structverify-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "structverify"
-version = "0.3.0"
+version = "0.3.2"
 description = "Compliance & fact verification for documents — check your files against your own rulebook (PDF) or a data source, and read a plain True/False."
 readme = "README.md"
 license = { file = "LICENSE" }

{structverify-0.3.0 → structverify-0.3.2}/structverify/__init__.py

@@ -54,7 +54,7 @@ _TRAINING_SYMBOLS = frozenset({
 })
 
 __all__ = sorted(_API_SYMBOLS | _PIPELINE_SYMBOLS | _PROGRESS_SYMBOLS | _TRAINING_SYMBOLS)
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 
 
 def __getattr__(name: str):

{structverify-0.3.0 → structverify-0.3.2}/structverify/training/curator.py

@@ -80,10 +80,14 @@ class DataCurator:
             t = str(row.get("task", "?"))
             rep.by_task[t] = rep.by_task.get(t, 0) + 1
         rep.kept = len(clean)
-        # 편중 경고
+        # 편중 경고 — 절대 과소 + 상대 편중(전체의 5% 미만) 둘 다 잡는다.
         for t, n in rep.by_task.items():
             if n < min_per_task:
                 rep.warnings.append(f"태스크 '{t}' 예시 {n}개 — {min_per_task}개 미만(과소). 보강 권장")
+            elif len(rep.by_task) > 1 and rep.kept and n / rep.kept < 0.05:
+                rep.warnings.append(
+                    f"태스크 '{t}' {n}건 ({n/rep.kept:.1%}) — 편중. 이 태스크는 학습 효과가 미미할 수 "
+                    f"있음 (generate_dataset·build_example로 보강하거나 학습 대상에서 제외 검토)")
         if not rep.by_task:
             rep.warnings.append("통과한 예시가 없음 — 포맷 확인 필요")
         return clean, rep

{structverify-0.3.0 → structverify-0.3.2}/structverify/training/doctor.py

@@ -72,13 +72,39 @@ class TrainDoctor:
             d.issues.append(f"[심각] loss 발산 — 최소 {min_v:.3f} 후 {vals[-1]:.3f}로 상승")
             d.prescriptions.append("learning_rate 낮추기(÷2~5), 최소 지점 체크포인트 사용")
 
-        # spike: 국소 급등(직전 대비 2배↑)
-        spikes = [losses[i][0] for i in range(1, len(vals))
-                  if vals[i] > vals[i - 1] * 2.0 and vals[i - 1] > 1e-6]
-        if spikes:
+        # spike: 국소 급등(직전 대비 2배↑) — 복귀 여부로 심각도를 가른다.
+        #   복귀한 스파이크(다음 기록이 원 수준으로 돌아옴)는 SGD의 정상 노이즈 → 정보성.
+        #   복귀 안 한 스파이크만 배치/데이터 문제로 경고.
+        spikes, unrecovered = [], []
+        for i in range(1, len(vals)):
+            if vals[i] > vals[i - 1] * 2.0 and vals[i - 1] > 1e-6:
+                spikes.append(losses[i][0])
+                nxt = vals[i + 1:i + 3]
+                if not nxt or min(nxt) > vals[i - 1] * 1.5:
+                    unrecovered.append(losses[i][0])
+        if unrecovered:
             d.healthy = False
-            d.issues.append(f"[주의] loss spike @ step {spikes[:3]} — 특정 배치 의심")
+            d.issues.append(f"[주의] 복귀 없는 loss spike @ step {unrecovered[:3]} — 특정 배치·데이터 의심")
             d.prescriptions.append("해당 구간 데이터 재검토(DataCurator), batch shuffle·grad clipping 확인")
+        elif spikes:
+            d.issues.append(f"[정보] 일시적 spike {len(spikes)}건 @ step {spikes[:3]} — 모두 즉시 복귀 (정상 노이즈)")
+
+        # 수렴 스텝 추정: 이동평균이 최저의 105% 안에 처음 든 지점 이후로 개선이 없으면,
+        # 그 뒤 스텝은 낭비 — "얼마나 일찍 멈출 수 있었나"를 정량화해 처방.
+        if len(vals) >= 30:
+            w = max(5, len(vals) // 50)
+            means = [sum(vals[max(0, i - w):i + 1]) / len(vals[max(0, i - w):i + 1])
+                     for i in range(len(vals))]
+            floor = min(means)
+            conv_i = next((i for i, m in enumerate(means) if m <= floor * 1.05), len(vals) - 1)
+            conv_step, last_step = losses[conv_i][0], losses[-1][0]
+            if last_step and conv_step and last_step > conv_step * 2:
+                wasted = (last_step - conv_step) / last_step
+                d.issues.append(f"[정보] 실질 수렴 @ step ~{conv_step} — 전체 {last_step}스텝 중 "
+                                f"{wasted:.0%}는 개선 없이 소모됨")
+                d.prescriptions.append(
+                    f"다음 학습은 실시간 감독의 조기 종료(early_stop=True, 기본값)에 맡기거나 "
+                    f"steps={int(conv_step * 1.3)} 수준으로 지정 — GPU 시간 {wasted:.0%} 절약")
 
         # 정체: 후반 개선 미미
         tail = vals[max(0, len(vals) - 5):]

{structverify-0.3.0 → structverify-0.3.2}/structverify/training/loop.py

@@ -59,11 +59,14 @@ class LearningLoop:
 
     # ── ② 학습: 위임 (레시피 핸드오프 or subprocess 실행) ──
     def train(self, dataset: str, output: str = "./adapter", *, backend: str = "auto",
-              run: bool = False, steps: int = 60) -> dict:
+              run: bool = False, steps: int = 60, early_stop: bool = True,
+              patience: int = 200) -> dict:
         """학습을 위임. run=False(기본)면 실행 명령만 반환(핸드오프).
 
         backend: "qlora"(NVIDIA/3060·T4) | "mlx"(Apple Silicon) | "auto"(플랫폼 감지).
         run=True는 해당 extra + 하드웨어가 있을 때만 — 별도 프로세스(샌드박스)로 실행.
+        early_stop: 🩺 실시간 감독이 plateau/발산을 감지하면 조기 종료 (qlora 백엔드).
+        patience: 이 스텝 동안 개선이 없으면 수렴 완료로 판단.
         """
         import platform
         if backend == "auto":
@@ -81,7 +84,10 @@ class LearningLoop:
             recipe = os.path.join(_dir, "train_qlora.py")
             cmd = ["python", "-m", "structverify.training.recipe.train_qlora",
                    "--model", self.base_model, "--data", os.path.abspath(dataset),
-                   "--out", os.path.abspath(output), "--max-steps", str(steps)]
+                   "--out", os.path.abspath(output), "--max-steps", str(steps),
+                   "--patience", str(patience)]
+            if not early_stop:
+                cmd.append("--no-early-stop")
             need = 'pip install "structverify[training]"  (NVIDIA GPU)'
             _probe = "torch"
         info = {"backend": backend, "recipe": recipe, "command": " ".join(cmd), "output": output}

structverify-0.3.2/structverify/training/monitor.py

@@ -0,0 +1,183 @@
+"""structverify.training.monitor — 학습 실시간 감독 (🩺 TrainDoctor live).
+
+레시피(HF Trainer 콜백)가 매 로그 스텝마다 :class:`LossMonitor` 에 loss를 먹이면,
+모니터가 ① 상태 판정(정상/스파이크/발산/plateau)과 ② 터미널 한 줄 UI 문자열을 돌려준다.
+순수 파이썬(토치 불필요)이라 코어에서 단위테스트 가능.
+
+터미널 UI 한 줄 예::
+
+    🧠 1234/2496 ▓▓▓▓▓▓░░░░░░ 49% · loss 0.114 ▂▁▁▁▁▁ · lr 1.2e-4 · ETA 1:12:03 · 🩺 수렴 유지
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+from dataclasses import dataclass, field
+
+_SPARK = "▁▂▃▄▅▆▇█"
+
+# ── 터미널 색 (v0.3.2 팔레트) ────────────────────────────────────────────────
+_ANSI = {"cyan": "\x1b[38;5;117m", "spark": "\x1b[38;5;111m", "dim": "\x1b[2m",
+         "bold": "\x1b[1m", "green": "\x1b[38;5;114m", "amber": "\x1b[38;5;179m",
+         "red": "\x1b[38;5;210m", "reset": "\x1b[0m"}
+
+
+def _color_enabled() -> bool:
+    """NO_COLOR면 끔, SV_COLOR=1이면 강제 켬, 그 외엔 tty 감지."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("SV_COLOR"):
+        return True
+    try:
+        return sys.stderr.isatty()
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _c(name: str, s: str, on: bool) -> str:
+    return f"{_ANSI[name]}{s}{_ANSI['reset']}" if on else s
+
+
+def sparkline(values: list[float], width: int = 8) -> str:
+    """최근 값들을 ▁▂▃ 스파크라인으로. 값이 없으면 빈 문자열."""
+    if not values:
+        return ""
+    vs = values[-width:]
+    lo, hi = min(vs), max(vs)
+    span = (hi - lo) or 1.0
+    return "".join(_SPARK[int((v - lo) / span * (len(_SPARK) - 1))] for v in vs)
+
+
+def _fmt_eta(seconds: float) -> str:
+    s = max(0, int(seconds))
+    h, s = divmod(s, 3600)
+    m, s = divmod(s, 60)
+    return f"{h}:{m:02d}:{s:02d}" if h else f"{m}:{s:02d}"
+
+
+@dataclass
+class LossMonitor:
+    """loss 흐름을 감시해 상태를 판정하는 감독 코어.
+
+    Args:
+        patience: 이만큼의 스텝 동안 개선이 없으면 plateau (early stop 후보).
+        min_steps: 이 스텝 전에는 절대 early stop 하지 않음 (워밍업 보호).
+        window: 이동평균 창 크기.
+        improve_eps: "개선"으로 인정할 최소 상대 하락폭 (예: 0.02 = 2%).
+        spike_ratio: 이동평균 대비 이 배수를 넘으면 스파이크로 기록.
+        diverge_ratio: 이동평균이 최저 대비 이 배수를 넘어 유지되면 발산 판정.
+    """
+
+    patience: int = 200
+    min_steps: int = 120
+    window: int = 20
+    improve_eps: float = 0.02
+    spike_ratio: float = 3.0
+    diverge_ratio: float = 2.0
+
+    losses: list[float] = field(default_factory=list)
+    means: list[float] = field(default_factory=list)      # 이동평균 궤적 (스파크라인용)
+    spikes: list[int] = field(default_factory=list)       # 스파이크 발생 스텝
+    best_mean: float | None = None
+    best_step: int = 0
+    step: int = 0
+    status: str = "워밍업"
+    should_stop: bool = False
+    stop_reason: str = ""
+    _diverge_run: int = 0
+
+    def update(self, step: int, loss: float) -> str:
+        """한 로그 스텝 반영 → 현재 상태 문자열 반환."""
+        self.step = step
+        self.losses.append(loss)
+        mean = sum(self.losses[-self.window:]) / min(len(self.losses), self.window)
+        self.means.append(mean)
+
+        warm = len(self.losses) < self.window
+        if warm:
+            self.status = "워밍업"
+            return self.status
+
+        # 스파이크: 단일 loss가 이동평균의 spike_ratio배 초과
+        if loss > mean * self.spike_ratio and loss > 0.05:
+            self.spikes.append(step)
+
+        # 개선 추적 (이동평균 기준)
+        if self.best_mean is None or mean < self.best_mean * (1 - self.improve_eps):
+            self.best_mean = mean
+            self.best_step = step
+
+        # 발산: 이동평균이 최저 대비 크게 나빠진 채 유지
+        if self.best_mean and mean > self.best_mean * self.diverge_ratio:
+            self._diverge_run += 1
+        else:
+            self._diverge_run = 0
+        if self._diverge_run >= self.window:
+            self.status = "발산 의심"
+            if step >= self.min_steps:
+                self.should_stop = True
+                self.stop_reason = (
+                    f"step {step}: 이동평균 loss {mean:.4f} — 최저 {self.best_mean:.4f} 대비 "
+                    f"{self.diverge_ratio}배 이상으로 {self.window}스텝 유지 (발산). lr을 낮춰 재시도 권장."
+                )
+            return self.status
+
+        # plateau: patience 스텝 동안 개선 없음
+        stale = step - self.best_step
+        if stale >= self.patience:
+            self.status = f"수렴 완료 (개선 없음 {stale}스텝)"
+            if step >= self.min_steps:
+                self.should_stop = True
+                self.stop_reason = (
+                    f"step {step}: {stale}스텝 동안 이동평균 개선 없음 (최저 {self.best_mean:.4f}, "
+                    f"step {self.best_step}). 더 학습해도 이득이 없어 조기 종료합니다."
+                )
+        elif stale >= self.patience // 2:
+            self.status = "수렴 유지"
+        else:
+            self.status = "학습 중"
+        return self.status
+
+    # ── 터미널 UI ───────────────────────────────────────────────────────────
+    def render(self, max_steps: int, started_at: float, lr: float | None = None,
+               width: int = 12, color: bool | None = None) -> str:
+        """현재 상태를 터미널 한 줄로 (tty면 색 포함 — NO_COLOR/SV_COLOR로 제어)."""
+        on = _color_enabled() if color is None else color
+        frac = self.step / max_steps if max_steps else 0.0
+        filled = int(frac * width)
+        bar = "▓" * filled + "░" * (width - filled)
+        loss = self.losses[-1] if self.losses else float("nan")
+        spark = sparkline(self.means)
+        elapsed = time.time() - started_at
+        eta = _fmt_eta(elapsed / frac - elapsed) if frac > 0.005 else "--:--"
+        st_color = ("red" if "발산" in self.status
+                    else "amber" if self.status == "워밍업" else "green")
+        parts = [
+            "🧠 " + _c("cyan", f"{self.step}/{max_steps} {bar} {frac*100:3.0f}%", on),
+            _c("bold", f"loss {loss:.3f}", on) + " " + _c("spark", spark, on),
+        ]
+        if lr:
+            parts.append(_c("dim", f"lr {lr:.1e}", on))
+        parts.append(_c("dim", f"ETA {eta}", on))
+        if self.spikes:
+            parts.append(_c("amber", f"⚡{len(self.spikes)}", on))
+        parts.append("🩺 " + _c(st_color, self.status, on))
+        return " · ".join(parts)
+
+    def summary(self) -> str:
+        """학습 종료 시 요약 (레시피가 마지막에 출력)."""
+        if not self.losses:
+            return "🩺 기록된 loss 없음"
+        lines = [
+            f"🩺 실시간 감독 요약 — {self.step}스텝 관찰",
+            f"  loss {self.losses[0]:.3f} → {self.losses[-1]:.3f} "
+            f"(이동평균 최저 {self.best_mean:.4f} @ step {self.best_step})",
+        ]
+        if self.spikes:
+            shown = ", ".join(str(s) for s in self.spikes[:5])
+            more = f" 외 {len(self.spikes)-5}건" if len(self.spikes) > 5 else ""
+            lines.append(f"  ⚡ 스파이크 {len(self.spikes)}건 (step {shown}{more}) — 모두 복귀함")
+        # 조기 종료 사유(✂)는 정지 시점에 콜백이 이미 출력하므로 여기선 상태만.
+        lines.append(f"  상태: {self.status}")
+        return "\n".join(lines)

structverify-0.3.2/structverify/training/recipe/sample.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+"""StructVerify 어댑터 스모크 테스트 — 학습된 모델이 실제로 뭘 배웠는지 즉석 확인.
+
+학습 데이터에 없는 새 문장으로 schema 추출·verdict 판정을 시켜 일반화 여부를 본다.
+GPU 머신(어댑터 학습한 곳)에서 실행:
+
+    python -m structverify.training.recipe.sample --adapter ./adapter
+    python -m structverify.training.recipe.sample --adapter ./adapter \
+        --task schema --claim "당사 물류 파트너는 2,300개사에 달했습니다."
+"""
+import argparse
+import os
+
+os.environ.setdefault("TF_CPP_MIN_LOG_LEVEL", "3")
+os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
+
+# 내장 테스트 — 시드/증강 데이터에 없는 새 표현으로 일반화를 확인.
+_DEFAULT_TESTS = [
+    dict(task="schema",
+         claim_text="당사와 협력하는 물류 파트너는 2,300개사에 달했습니다.", output=""),
+    dict(task="schema",
+         claim_text="지난해 해외 법인 매출은 1조 2,400억 원을 기록했습니다.", output=""),
+    dict(task="verdict", claim_text="분기 반품률은 12.5%였습니다.",
+         evidence_value=8.3, evidence_unit="%", output=""),
+    dict(task="verdict", claim_text="누적 다운로드는 340만 건입니다.",
+         evidence_value=3_400_000, evidence_unit="건", output=""),
+]
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--adapter", default="./adapter", help="학습 산출 어댑터 폴더")
+    ap.add_argument("--task", choices=["schema", "verdict"], help="단일 테스트 태스크")
+    ap.add_argument("--claim", help="단일 테스트 문장 (--task와 함께)")
+    ap.add_argument("--evidence", type=float, help="verdict용 근거값")
+    ap.add_argument("--unit", default="", help="verdict용 단위")
+    ap.add_argument("--max-tokens", type=int, default=120)
+    args = ap.parse_args()
+
+    from unsloth import FastLanguageModel
+
+    from structverify.training.tasks import build_example
+
+    if args.task and args.claim:
+        kw = dict(task=args.task, claim_text=args.claim, output="")
+        if args.task == "verdict":
+            kw.update(evidence_value=args.evidence, evidence_unit=args.unit)
+        tests = [kw]
+    else:
+        tests = _DEFAULT_TESTS
+
+    print(f"어댑터 로드: {args.adapter}")
+    model, tok = FastLanguageModel.from_pretrained(
+        args.adapter, max_seq_length=2048, load_in_4bit=True)
+    FastLanguageModel.for_inference(model)
+
+    for t in tests:
+        msgs = build_example(**t)["messages"][:2]     # system + user만
+        prompt = tok.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True)
+        ids = tok(prompt, return_tensors="pt").to(model.device)
+        out = model.generate(**ids, max_new_tokens=args.max_tokens, do_sample=False)
+        answer = tok.decode(out[0][ids["input_ids"].shape[1]:], skip_special_tokens=True).strip()
+        claim = t.get("claim_text", "")
+        print(f"\n[{t['task']}] {claim}")
+        if t["task"] == "verdict":
+            print(f"  근거: {t.get('evidence_value')} {t.get('evidence_unit')}")
+        print(f"  → {answer}")
+
+
+if __name__ == "__main__":
+    main()

{structverify-0.3.0 → structverify-0.3.2}/structverify/training/recipe/train_mlx.py

@@ -63,6 +63,9 @@ def main():
     ap.add_argument("--batch", type=int, default=1)
     ap.add_argument("--rank", type=int, default=8)
     ap.add_argument("--lr", type=float, default=1e-4)
+    ap.add_argument("--early-stop", dest="early_stop", action="store_true", default=True)
+    ap.add_argument("--no-early-stop", dest="early_stop", action="store_false")
+    ap.add_argument("--patience", type=int, default=200)
     args = ap.parse_args()
 
     os.makedirs(args.out, exist_ok=True)
@@ -76,19 +79,48 @@ def main():
         "--data", data_dir, "--adapter-path", args.out,
         "--iters", str(args.iters), "--batch-size", str(args.batch),
         "--num-layers", "8", "--learning-rate", str(args.lr),
-        "--steps-per-report", "1",   # TrainDoctor용 촘촘한 loss
+        "--steps-per-report", "1",   # 🩺 실시간 감독용 촘촘한 loss
+        "--save-every", "50",        # 조기 종료 대비 어댑터 주기 저장
     ]
     print("[train_mlx] 실행:", " ".join(cmd))
-    proc = subprocess.run(cmd, capture_output=True, text=True)
-    log = proc.stdout + "\n" + proc.stderr
-    print(log[-2000:])
+
+    # ── 🩺 실시간 감독: mlx 출력을 스트리밍으로 읽어 LossMonitor에 공급 ──
+    import re as _re
+    import time as _time
+
+    from structverify.training.monitor import LossMonitor
+
+    mon = LossMonitor(patience=args.patience)
+    t0 = _time.time()
+    log_lines: list[str] = []
+    stopped_early = False
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                            text=True, bufsize=1)
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        log_lines.append(line)
+        m = _re.search(r"Iter\s+(\d+):.*?Train loss\s+([\d.]+)", line)
+        if not m:
+            continue
+        mon.update(int(m.group(1)), float(m.group(2)))
+        print("\r\x1b[2K" + mon.render(args.iters, t0), end="", flush=True, file=sys.stderr)
+        if mon.should_stop and args.early_stop:
+            print("", file=sys.stderr)
+            print(f"✂ {mon.stop_reason}", file=sys.stderr)
+            proc.terminate()
+            stopped_early = True
+            break
+    proc.wait()
+    print("", file=sys.stderr)
+    print(mon.summary(), file=sys.stderr)
     shutil.rmtree(data_dir, ignore_errors=True)
 
     # mlx 로그 → 표준 trainer_state.json (TrainDoctor 호환)
-    hist = parse_mlx_log(log)
+    hist = parse_mlx_log("".join(log_lines))
     with open(os.path.join(args.out, "trainer_state.json"), "w", encoding="utf-8") as f:
         json.dump({"log_history": hist}, f, ensure_ascii=False)
-    if proc.returncode != 0:
+    if proc.returncode != 0 and not stopped_early:
+        print("".join(log_lines)[-2000:])
         print(f"⚠ mlx_lm.lora 종료코드 {proc.returncode} — 로그 확인")
         sys.exit(proc.returncode)
     print(f"\n✅ 완료 — 어댑터: {args.out}  (trainer_state.json {len(hist)}개 기록)")

structverify-0.3.2/structverify/training/recipe/train_qlora.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python
+"""StructVerify QLoRA 학습 레시피 — RTX 3060 12GB / Colab T4 검증됨(사양 기준).
+
+이 파일은 GPU 머신에서 실행하는 *샌드박스 레시피*다. 코어 라이브러리는 이 파일을 만들지도,
+직접 import 하지도 않는다(무거운 deps 격리). 표준 chat jsonl 만 먹으므로 데이터는 어떤
+경로로 만들어도 됨.
+
+준비 (GPU 머신):
+    pip install "structverify[training]"        # unsloth·trl·peft·bitsandbytes·torch
+    # 또는:  pip install unsloth trl peft bitsandbytes accelerate datasets
+
+실행:
+    python train_qlora.py --model unsloth/Qwen2.5-7B-Instruct \
+        --data train.jsonl --out ./adapter --max-steps 60
+
+산출: {out}/ 에 LoRA 어댑터 + trainer_state.json (→ TrainDoctor가 읽음)
+"""
+import argparse
+import json
+import os
+import sys
+import time
+
+# 학습과 무관한 라이브러리 잡음(TF·경고)을 미리 조용히 — UI 한 줄만 보이게.
+os.environ.setdefault("TF_CPP_MIN_LOG_LEVEL", "3")
+os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+# "Exception ignored in: <_io.BytesIO ...> BufferError" 도배 차단.
+#   Python 3.13 + datasets 멀티프로세스 토큰화의 무해한 정리 단계 잡음인데,
+#   워커가 fork로 뜨면서 이 훅을 물려받아 자식 프로세스 출력까지 조용해진다.
+sys.unraisablehook = lambda *_: None
+
+import logging
+import warnings
+
+warnings.filterwarnings("ignore")                       # Flax deprecated 등
+logging.getLogger("torchao").setLevel(logging.CRITICAL)  # torchao .so 로드 WARNING
+
+
+def load_chat_dataset(path):
+    from datasets import Dataset
+    rows = []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                rows.append(json.loads(line))
+    # messages 만 남김 (task 필드는 학습에 불필요)
+    return Dataset.from_list([{"messages": r["messages"]} for r in rows])
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--model", default="unsloth/Qwen2.5-7B-Instruct",
+                    help="4bit 베이스 모델 (unsloth 허브 권장). 3060 6GB면 3B 계열로.")
+    ap.add_argument("--data", required=True, help="chat jsonl (structverify가 export)")
+    ap.add_argument("--out", default="./adapter")
+    ap.add_argument("--max-steps", type=int, default=60)
+    ap.add_argument("--lr", type=float, default=2e-4)
+    ap.add_argument("--rank", type=int, default=16)
+    ap.add_argument("--seq-len", type=int, default=2048)
+    ap.add_argument("--batch", type=int, default=1)
+    ap.add_argument("--grad-accum", type=int, default=8)
+    # 🩺 실시간 감독 (LossMonitor) — plateau/발산이면 스스로 멈춘다.
+    ap.add_argument("--early-stop", dest="early_stop", action="store_true", default=True)
+    ap.add_argument("--no-early-stop", dest="early_stop", action="store_false",
+                    help="감독은 하되 조기 종료는 하지 않음 (관찰만)")
+    ap.add_argument("--patience", type=int, default=200,
+                    help="이 스텝 동안 개선 없으면 수렴 완료로 판단")
+    ap.add_argument("--keep-checkpoints", action="store_true",
+                    help="중간 체크포인트(checkpoint-*) 보존 — 기본은 성공 시 삭제 (어댑터만 수십 MB)")
+    args = ap.parse_args()
+
+    # unsloth: 3060/T4에서 QLoRA 2배 빠름 + 메모리 절약
+    from unsloth import FastLanguageModel
+    from trl import SFTTrainer, SFTConfig
+
+    # tqdm 진행바(체크포인트 로드·Map·Tokenizing) 대신 우리 phase 라인으로.
+    try:
+        import datasets as _ds
+        import transformers as _tf
+        _ds.disable_progress_bars()
+        _tf.utils.logging.disable_progress_bar()
+    except Exception:  # noqa: BLE001
+        pass
+
+    print(f"⚙ 베이스 모델 로드 — {args.model} (4bit)", file=sys.stderr)
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name=args.model,
+        max_seq_length=args.seq_len,
+        load_in_4bit=True,          # QLoRA — 12GB VRAM에 7B 적재
+    )
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r=args.rank,
+        target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
+                        "gate_proj", "up_proj", "down_proj"],
+        lora_alpha=args.rank * 2,
+        lora_dropout=0.0,
+        bias="none",
+        use_gradient_checkpointing="unsloth",
+    )
+
+    print("⚙ 데이터 준비·토큰화 중 …", file=sys.stderr)
+    ds = load_chat_dataset(args.data)
+
+    def fmt(ex):
+        return {"text": tokenizer.apply_chat_template(
+            ex["messages"], tokenize=False, add_generation_prompt=False)}
+    ds = ds.map(fmt)
+
+    trainer = SFTTrainer(
+        model=model, tokenizer=tokenizer, train_dataset=ds,
+        args=SFTConfig(
+            output_dir=args.out,
+            per_device_train_batch_size=args.batch,
+            gradient_accumulation_steps=args.grad_accum,
+            warmup_steps=5,
+            max_steps=args.max_steps,
+            learning_rate=args.lr,
+            logging_steps=1,            # TrainDoctor용 촘촘한 loss 기록
+            max_grad_norm=1.0,          # 발산 방지
+            optim="adamw_8bit",
+            lr_scheduler_type="linear",
+            seed=42,
+            dataset_text_field="text",
+            report_to="none",
+            disable_tqdm=True,          # 진행 표시는 🩺 감독 UI 한 줄이 담당
+        ),
+    )
+
+    # ── 🩺 TrainDoctor 실시간 감독: 상태 한 줄 UI + plateau/발산 조기 종료 ──
+    from transformers import TrainerCallback
+    from transformers.trainer_callback import PrinterCallback
+
+    from structverify.training.monitor import LossMonitor, _c, _color_enabled
+
+    class SVLiveCallback(TrainerCallback):
+        def __init__(self, early_stop: bool, patience: int):
+            self.mon = LossMonitor(patience=patience)
+            self.early_stop = early_stop
+            self.t0 = time.time()
+
+        def on_log(self, targs, state, control, logs=None, **kw):
+            if not logs or "loss" not in logs:
+                return control
+            self.mon.update(state.global_step, logs["loss"])
+            line = self.mon.render(state.max_steps, self.t0, lr=logs.get("learning_rate"))
+            print("\r\x1b[2K" + line, end="", flush=True, file=sys.stderr)
+            if self.mon.should_stop and self.early_stop:
+                print("", file=sys.stderr)
+                print(_c("amber", f"✂ {self.mon.stop_reason}", _color_enabled()), file=sys.stderr)
+                control.should_training_stop = True
+            return control
+
+        def on_train_end(self, targs, state, control, **kw):
+            print("", file=sys.stderr)
+            print(_c("green", self.mon.summary(), _color_enabled()), file=sys.stderr)
+            return control
+
+    trainer.remove_callback(PrinterCallback)     # {'loss': ...} dict 도배 제거
+    trainer.add_callback(SVLiveCallback(args.early_stop, args.patience))
+
+    es = "ON" if args.early_stop else "OFF (관찰만)"
+    print(f"🩺 실시간 감독 시작 — patience {args.patience} · 조기 종료 {es}", file=sys.stderr)
+    trainer.train()
+
+    # 어댑터 + trainer_state.json 저장 (TrainDoctor가 읽음)
+    model.save_pretrained(args.out)
+    tokenizer.save_pretrained(args.out)
+    trainer.state.save_to_json(f"{args.out}/trainer_state.json")
+
+    # 성공했으면 중간 체크포인트(옵티마이저 상태 포함, 수백 MB) 정리 — 최종 어댑터만 남긴다.
+    if not args.keep_checkpoints:
+        import glob
+        import shutil
+        for ck in glob.glob(os.path.join(args.out, "checkpoint-*")):
+            shutil.rmtree(ck, ignore_errors=True)
+
+    # 학습 메타 기록 — 이 어댑터가 무엇으로 어떻게 학습됐는지 (주입·추적용).
+    by_task: dict[str, int] = {}
+    with open(args.data, encoding="utf-8") as f:
+        for line in f:
+            if line.strip():
+                t = json.loads(line).get("task", "?")
+                by_task[t] = by_task.get(t, 0) + 1
+    hist = [h for h in trainer.state.log_history if "loss" in h]
+    meta = {
+        "library": "structverify", "backend": "qlora", "base_model": args.model,
+        "dataset": os.path.abspath(args.data), "examples": sum(by_task.values()),
+        "task_distribution": by_task, "max_steps": args.max_steps,
+        "trained_steps": trainer.state.global_step,
+        "loss": {"first": hist[0]["loss"] if hist else None,
+                 "last": hist[-1]["loss"] if hist else None,
+                 "min": min((h["loss"] for h in hist), default=None)},
+        "lora": {"rank": args.rank, "lr": args.lr, "seq_len": args.seq_len},
+        "trained_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+    }
+    with open(os.path.join(args.out, "training_meta.json"), "w", encoding="utf-8") as f:
+        json.dump(meta, f, ensure_ascii=False, indent=2)
+
+    print(f"\n✅ 완료 — 어댑터: {args.out}  (trainer_state.json · training_meta.json 포함)")
+    print("   다음: TrainDoctor로 진단, EvalGate로 채택 여부 판정")
+    print(f"   스모크 테스트: python -m structverify.training.recipe.sample --adapter {args.out}")
+
+
+if __name__ == "__main__":
+    main()

{structverify-0.3.0 → structverify-0.3.2/structverify.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structverify
-Version: 0.3.0
+Version: 0.3.2
 Summary: Compliance & fact verification for documents — check your files against your own rulebook (PDF) or a data source, and read a plain True/False.
 Author-email: "김예슬 (Yeseul Kim)" <yesul0718@gmail.com>
 License: MIT License