structverify 0.3.0__py3-none-any.whl

structverify/training/doctor.py

@@ -0,0 +1,99 @@
+"""structverify.training.doctor — TrainDoctor (학습 로그 이상 감지, 코어·GPU 불필요).
+
+표준 HuggingFace `trainer_state.json`(log_history: step/loss/learning_rate/eval_loss)을 읽어
+발산·NaN·spike·정체·overfit을 휴리스틱으로 감지하고, 자연어 진단 + 처방을 낸다.
+표준 포맷만 보므로 TRL/unsloth/axolotl 어떤 트레이너로 학습하든 동작(백엔드 무관).
+"""
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Diagnosis:
+    healthy: bool = True
+    issues: list[str] = field(default_factory=list)     # [severity] 설명
+    prescriptions: list[str] = field(default_factory=list)
+    stats: dict[str, Any] = field(default_factory=dict)
+
+    def summary(self) -> str:
+        head = "🩺 TrainDoctor — 정상" if self.healthy else "🩺 TrainDoctor — 이상 감지"
+        lines = [head]
+        s = self.stats
+        if s:
+            lines.append(f"  steps={s.get('steps')} · loss {s.get('first_loss')}→{s.get('last_loss')} "
+                         f"· min={s.get('min_loss')}")
+        for i in self.issues:
+            lines.append(f"  ⚠ {i}")
+        for p in self.prescriptions:
+            lines.append(f"  → {p}")
+        return "\n".join(lines)
+
+
+def _load_history(path_or_state: Any) -> list[dict]:
+    if isinstance(path_or_state, dict):
+        return path_or_state.get("log_history", [])
+    with open(path_or_state, encoding="utf-8") as f:
+        return json.load(f).get("log_history", [])
+
+
+class TrainDoctor:
+    def diagnose(self, trainer_state: Any) -> Diagnosis:
+        hist = _load_history(trainer_state)
+        losses = [(h.get("step"), h["loss"]) for h in hist if "loss" in h]
+        evals = [(h.get("step"), h["eval_loss"]) for h in hist if "eval_loss" in h]
+        d = Diagnosis()
+        if len(losses) < 2:
+            d.healthy = False
+            d.issues.append("[정보부족] loss 기록이 2개 미만 — 학습이 거의 안 돎")
+            d.prescriptions.append("스텝 수·로깅 간격(logging_steps) 확인")
+            return d
+
+        vals = [v for _, v in losses]
+        d.stats = {
+            "steps": losses[-1][0], "first_loss": round(vals[0], 4),
+            "last_loss": round(vals[-1], 4), "min_loss": round(min(vals), 4),
+        }
+
+        # NaN/inf
+        if any(math.isnan(v) or math.isinf(v) for v in vals):
+            d.healthy = False
+            d.issues.append("[치명] loss에 NaN/inf — 발산")
+            d.prescriptions.append("learning_rate를 1/5로 낮추고 warmup·grad clipping(max_grad_norm=1.0) 적용")
+            return d
+
+        # 발산: 마지막이 최소보다 크게 상승
+        min_v = min(vals)
+        if vals[-1] > min_v * 1.6 and vals[-1] > vals[0]:
+            d.healthy = False
+            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:
+            d.healthy = False
+            d.issues.append(f"[주의] loss spike @ step {spikes[:3]} — 특정 배치 의심")
+            d.prescriptions.append("해당 구간 데이터 재검토(DataCurator), batch shuffle·grad clipping 확인")
+
+        # 정체: 후반 개선 미미
+        tail = vals[max(0, len(vals) - 5):]
+        if len(tail) >= 3 and (max(tail) - min(tail)) < 0.01 and min_v > 0.5:
+            d.issues.append("[정보] 후반 loss 정체 — 이미 수렴했거나 lr 과소")
+            d.prescriptions.append("수렴이면 조기 종료, 아니면 lr↑ 또는 데이터 증강")
+
+        # overfit: eval_loss가 상승 전환
+        if len(evals) >= 2:
+            ev = [v for _, v in evals]
+            if ev[-1] > min(ev) * 1.15:
+                d.healthy = False
+                d.issues.append(f"[주의] overfit — eval_loss 최소 {min(ev):.3f} 후 {ev[-1]:.3f}로 상승")
+                d.prescriptions.append("early stopping, LoRA rank↓ 또는 dropout↑, 데이터 늘리기")
+
+        if d.healthy and not d.issues:
+            d.issues.append("[정상] 발산·spike·overfit 없음")
+        return d

structverify/training/evalgate.py

@@ -0,0 +1,96 @@
+"""structverify.training.evalgate — EvalGate (학습된 모델을 *검증 엔진으로* 자가평가).
+
+StructVerify만 할 수 있는 셀프-루프: 라벨된 eval 셋(확정 정답)으로 base vs 파인튜닝 모델의
+검증 정확도를 재고, 좋아졌을 때만 어댑터 채택(회귀 방지). GPU 불필요(엔진이 알아서 추론).
+
+eval 셋 포맷(라벨): [{"claim": "...", "expected": "match|mismatch|unverifiable"}, ...]
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class EvalResult:
+    n: int = 0
+    correct: int = 0
+    by_verdict: dict[str, dict] = field(default_factory=dict)   # expected → {n, correct}
+
+    @property
+    def accuracy(self) -> float:
+        return self.correct / self.n if self.n else 0.0
+
+    def summary(self) -> str:
+        parts = [f"정확도 {self.accuracy:.1%} ({self.correct}/{self.n})"]
+        for k, v in sorted(self.by_verdict.items()):
+            parts.append(f"{k} {v['correct']}/{v['n']}")
+        return " · ".join(parts)
+
+
+@dataclass
+class GateDecision:
+    before: EvalResult
+    after: EvalResult
+    margin: float
+    accepted: bool
+    reason: str
+
+    def summary(self) -> str:
+        mark = "✅ 채택" if self.accepted else "⛔ 거부"
+        return (f"🚦 EvalGate — {mark}\n"
+                f"  before: {self.before.summary()}\n"
+                f"  after : {self.after.summary()}\n"
+                f"  Δ정확도 {self.after.accuracy - self.before.accuracy:+.1%} (margin {self.margin:+.1%}) — {self.reason}")
+
+
+def _claim_verdict(report: Any) -> str:
+    """Report → 대표 판정. mismatch > match > unverifiable 우선(거짓을 놓치지 않게)."""
+    verds = [str(getattr(r, "verdict", "") or "") for r in report]
+    for pref in ("mismatch", "match", "unverifiable"):
+        if pref in verds:
+            return pref
+    return verds[0] if verds else "unverifiable"
+
+
+class EvalGate:
+    """검증 엔진(Verifier) 재사용해 라벨 셋에 대한 정확도 측정 + 채택 판정."""
+
+    def __init__(self, engine: Any):
+        self.engine = engine
+
+    def score(self, labeled: list[dict], engine: Any | None = None) -> EvalResult:
+        eng = engine or self.engine
+        res = EvalResult()
+        for row in labeled:
+            claim = str(row.get("claim", "")).strip()
+            exp = str(row.get("expected", "")).strip()
+            if not claim or not exp:
+                continue
+            try:
+                report = eng.verify(claim)
+                got = _claim_verdict(report)
+            except Exception:  # noqa: BLE001 — 개별 실패는 오답 처리
+                got = "unverifiable"
+            b = res.by_verdict.setdefault(exp, {"n": 0, "correct": 0})
+            res.n += 1
+            b["n"] += 1
+            if got == exp:
+                res.correct += 1
+                b["correct"] += 1
+        return res
+
+    def evaluate(self, labeled: list[dict], *, tuned_engine: Any,
+                 margin: float = 0.0) -> GateDecision:
+        """base(self.engine) vs tuned_engine 정확도 비교 → 채택/거부.
+
+        tuned_engine = 어댑터 로드된 Verifier (provider=local + adapter 서빙).
+        margin: after가 before보다 이만큼은 나아야 채택(기본 0 = 안 나빠지면 채택).
+        """
+        before = self.score(labeled, self.engine)
+        after = self.score(labeled, tuned_engine)
+        gain = after.accuracy - before.accuracy
+        accepted = gain >= margin
+        reason = ("개선됨" if gain > 0 else "동일" if gain == 0 else "악화") + \
+                 (" → 채택" if accepted else " → 거부(회귀 방지)")
+        return GateDecision(before, after, margin, accepted, reason)

structverify/training/generate.py

@@ -0,0 +1,101 @@
+"""structverify.training.generate — 합성 학습 데이터 생성 (증류/부트스트랩).
+
+초기엔 학습 데이터가 없다. 강한 클라우드 모델로 (주장→추출), (주장+근거→판정) 예시를
+대량 생성해 작은 로컬 모델에 증류(distill)한다. 회사 지표 목록을 주면 그 도메인에 맞춰 생성.
+
+    from structverify.training import generate_dataset
+    n = generate_dataset(llm_config, out="gen.jsonl",
+                         indicators=["매출","고객수","평균주문금액", ...], domain="유통", n=80)
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from .tasks import build_example
+
+
+def _extract_json_array(text: str) -> list[dict]:
+    m = re.search(r"\[[\s\S]*\]", text)
+    if not m:
+        return []
+    try:
+        data = json.loads(m.group(0))
+        return data if isinstance(data, list) else []
+    except json.JSONDecodeError:
+        return []
+
+
+_SCHEMA_GEN = """너는 학습 데이터 생성기다. {domain} 회사의 수치 주장 문장 {k}개를 만들고,
+각 문장에서 검증 대상 수치를 추출한 결과를 함께 제시하라.
+
+다양하게: 지표({inds} 등), 단위(명·건·개·억 달러·%·원), 시점(연도 유/무),
+그리고 **한국어 숫자 표기를 반드시 섞어라**(예: "1,500만"=15000000, "23만 8천"=238000, "2조 1,791억").
+
+JSON 배열로만:
+[{{"claim": "문장", "extraction": {{"indicator":"지표", "value": 숫자, "unit":"단위",
+  "time_period":"시점 또는 null", "population":"대상/지역 또는 null"}}}}, ...]"""
+
+_VERDICT_GEN = """너는 학습 데이터 생성기다. {domain} 회사 맥락의 (주장, 근거 데이터, 판정) 쌍 {k}개.
+근거값과 주장이 *일치(match)* 하는 것과 *어긋나는(mismatch)* 것을 대략 반반 섞어라.
+근거는 원시값(달러/명/건) 또는 %.
+
+JSON 배열로만:
+[{{"claim":"주장 문장", "evidence_value": 숫자, "evidence_unit":"단위",
+  "verdict":"match 또는 mismatch", "reason":"한 줄 근거"}}, ...]"""
+
+
+async def _agen(llm, prompt: str) -> list[dict]:
+    try:
+        raw = await llm.generate(prompt=prompt, system_prompt="JSON 배열만 출력.", model_tier="light")
+    except Exception:  # noqa: BLE001
+        return []
+    return _extract_json_array(raw)
+
+
+async def agenerate_dataset(llm_config: dict, out: str = "gen.jsonl", *,
+                            indicators: list[str] | None = None, domain: str = "회사",
+                            n: int = 80, batch: int = 8) -> int:
+    """비동기 생성. schema:verdict ≈ 6:4 비율로 n개 근처까지."""
+    from structverify.utils.llm_client import LLMClient
+    from .dataset import write_jsonl
+    llm = LLMClient(config=llm_config)
+    inds = ", ".join((indicators or ["매출", "고객수", "주문건수", "평균주문금액", "순매출", "공급업체수"])[:12])
+    rows: list[dict] = []
+    n_schema, n_verdict = int(n * 0.6), int(n * 0.4)
+
+    made = 0
+    while made < n_schema:
+        arr = await _agen(llm, _SCHEMA_GEN.format(domain=domain, k=min(batch, n_schema - made), inds=inds))
+        for e in arr:
+            ex = e.get("extraction") or {}
+            if e.get("claim") and ex.get("indicator") is not None and ex.get("value") is not None:
+                rows.append(build_example("schema", claim_text=str(e["claim"]),
+                                          output=json.dumps(ex, ensure_ascii=False)))
+                made += 1
+        if not arr:
+            break
+
+    made = 0
+    while made < n_verdict:
+        arr = await _agen(llm, _VERDICT_GEN.format(domain=domain, k=min(batch, n_verdict - made)))
+        for e in arr:
+            if e.get("claim") and e.get("verdict") in ("match", "mismatch"):
+                rows.append(build_example("verdict", claim_text=str(e["claim"]),
+                                          evidence_value=e.get("evidence_value"),
+                                          evidence_unit=e.get("evidence_unit", ""),
+                                          output=json.dumps({"verdict": e["verdict"],
+                                                             "reason": str(e.get("reason", ""))[:200]},
+                                                            ensure_ascii=False)))
+                made += 1
+        if not arr:
+            break
+
+    return write_jsonl(rows, out)
+
+
+def generate_dataset(llm_config: dict, out: str = "gen.jsonl", **kw: Any) -> int:
+    """동기 래퍼. 반환: 생성된 예시 수."""
+    import asyncio
+    return asyncio.run(agenerate_dataset(llm_config, out, **kw))

structverify/training/loop.py

@@ -0,0 +1,116 @@
+"""structverify.training.loop — LearningLoop (감독 학습 오케스트레이션).
+
+OSS 원칙대로: *차별화되는 부분(데이터·감독)은 소유*, *학습 자체는 위임*.
+  · export/curate/diagnose/evaluate → 코어(여기), GPU 불필요
+  · train → 표준 데이터셋을 넘겨 생태계(TRL/unsloth/axolotl/회사 파이프라인)에 위임
+
+    loop = LearningLoop(engine)
+    loop.add_seed(); loop.add_reports(reports)     # 데이터 모으기
+    ds = loop.prepare("train.jsonl")               # ① export + 🕵 DataCurator
+    loop.train(ds, "./out", run=False)             # ② 레시피/명령 핸드오프 (또는 run=True)
+    loop.diagnose("./out/trainer_state.json")      # 🩺 TrainDoctor
+    gate = loop.evaluate(eval_set, tuned_engine)   # 🚦 EvalGate
+    if gate.accepted: engine.use_adapter("./out")  # 채택
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from typing import Any
+
+from .curator import DataCurator, CurationReport
+from .dataset import build_example, export_dataset, read_jsonl, write_jsonl, _SEED_SPECS
+from .doctor import TrainDoctor, Diagnosis
+from .evalgate import EvalGate, GateDecision
+
+
+class LearningLoop:
+    def __init__(self, engine: Any = None, base_model: str = "unsloth/Qwen2.5-7B-Instruct"):
+        self.engine = engine
+        self.base_model = base_model
+        self._rows: list[dict] = []
+        self.curator = DataCurator()
+        self.doctor = TrainDoctor()
+
+    # ── 데이터 모으기 ──
+    def add_seed(self) -> "LearningLoop":
+        self._rows.extend(build_example(**spec) for spec in _SEED_SPECS)
+        return self
+
+    def add_reports(self, reports, include=("verdict",)) -> "LearningLoop":
+        tmp = "_ll_tmp.jsonl"
+        export_dataset(reports, tmp, include=include)
+        self._rows.extend(read_jsonl(tmp))
+        os.remove(tmp)
+        return self
+
+    def add_jsonl(self, path: str) -> "LearningLoop":
+        self._rows.extend(read_jsonl(path))
+        return self
+
+    # ── ① 준비: export + DataCurator ──
+    def prepare(self, out: str = "train.jsonl", *, verbose: bool = True) -> tuple[str, CurationReport]:
+        clean, rep = self.curator.curate(self._rows)
+        write_jsonl(clean, out)
+        if verbose:
+            print(rep.summary())
+            print(f"[LearningLoop] clean 데이터셋 저장 → {out} ({rep.kept}건)")
+        return out, rep
+
+    # ── ② 학습: 위임 (레시피 핸드오프 or subprocess 실행) ──
+    def train(self, dataset: str, output: str = "./adapter", *, backend: str = "auto",
+              run: bool = False, steps: int = 60) -> dict:
+        """학습을 위임. run=False(기본)면 실행 명령만 반환(핸드오프).
+
+        backend: "qlora"(NVIDIA/3060·T4) | "mlx"(Apple Silicon) | "auto"(플랫폼 감지).
+        run=True는 해당 extra + 하드웨어가 있을 때만 — 별도 프로세스(샌드박스)로 실행.
+        """
+        import platform
+        if backend == "auto":
+            backend = "mlx" if platform.machine() == "arm64" and platform.system() == "Darwin" else "qlora"
+        _dir = os.path.join(os.path.dirname(__file__), "recipe")
+        if backend == "mlx":
+            recipe = os.path.join(_dir, "train_mlx.py")
+            model = self.base_model if "mlx" in self.base_model else "mlx-community/Qwen2.5-7B-Instruct-4bit"
+            cmd = ["python", "-m", "structverify.training.recipe.train_mlx",
+                   "--model", model, "--data", os.path.abspath(dataset),
+                   "--out", os.path.abspath(output), "--iters", str(steps)]
+            need = 'pip install "structverify[training-mac]"  (Apple Silicon)'
+            _probe = "mlx_lm"
+        else:
+            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)]
+            need = 'pip install "structverify[training]"  (NVIDIA GPU)'
+            _probe = "torch"
+        info = {"backend": backend, "recipe": recipe, "command": " ".join(cmd), "output": output}
+        if not run:
+            print(f"[LearningLoop] 핸드오프({backend}) — 학습 머신에서 아래 실행:")
+            print("   " + info["command"])
+            return info
+        try:
+            __import__(_probe)
+        except Exception:  # noqa: BLE001
+            raise RuntimeError(f"run=True에는 학습 백엔드가 필요합니다 → {need}. "
+                               "또는 run=False로 명령만 받아 별도 실행하세요.")
+        import subprocess
+        import sys
+        print(f"[LearningLoop] 샌드박스 학습 시작 (backend={backend}) …")
+        subprocess.run([sys.executable] + cmd[1:], check=True)
+        return info
+
+    # ── 🩺 진단 ──
+    def diagnose(self, trainer_state: str, *, verbose: bool = True) -> Diagnosis:
+        d = self.doctor.diagnose(trainer_state)
+        if verbose:
+            print(d.summary())
+        return d
+
+    # ── 🚦 자가평가 ──
+    def evaluate(self, eval_set: list[dict], *, tuned_engine: Any,
+                 margin: float = 0.0, verbose: bool = True) -> GateDecision:
+        gate = EvalGate(self.engine).evaluate(eval_set, tuned_engine=tuned_engine, margin=margin)
+        if verbose:
+            print(gate.summary())
+        return gate

structverify/training/recipe/train_mlx.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+"""StructVerify LoRA 학습 레시피 — Apple Silicon (M1~M4, MLX 백엔드).
+
+Mac에는 CUDA가 없어 unsloth/bitsandbytes(QLoRA)가 안 돈다. 대신 Apple 네이티브 **MLX**로
+LoRA 파인튜닝. 36GB 통합메모리면 7B도 여유(4bit MLX 모델이면 더).
+
+준비 (Mac):
+    pip install "structverify[training-mac]"      # mlx-lm
+    #  또는:  pip install mlx-lm
+
+실행:
+    python -m structverify.training.recipe.train_mlx \
+        --model mlx-community/Qwen2.5-7B-Instruct-4bit \
+        --data train.jsonl --out ./adapter --iters 100
+
+산출: {out}/ 에 LoRA 어댑터 + trainer_state.json (mlx 로그를 표준 포맷으로 변환 → TrainDoctor 호환)
+"""
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+def to_mlx_data(chat_jsonl: str, data_dir: str, valid_frac: float = 0.1):
+    """우리 chat jsonl → MLX가 먹는 data 폴더(train.jsonl/valid.jsonl, messages 포맷)."""
+    os.makedirs(data_dir, exist_ok=True)
+    rows = []
+    with open(chat_jsonl, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                rows.append({"messages": json.loads(line)["messages"]})
+    n_valid = max(1, int(len(rows) * valid_frac))
+    valid, train = rows[:n_valid], rows[n_valid:] or rows
+    for name, part in (("train", train), ("valid", valid)):
+        with open(os.path.join(data_dir, f"{name}.jsonl"), "w", encoding="utf-8") as f:
+            for r in part:
+                f.write(json.dumps(r, ensure_ascii=False) + "\n")
+    return len(train), len(valid)
+
+
+def parse_mlx_log(text: str) -> list[dict]:
+    """mlx_lm.lora stdout("Iter N: Train loss X, ... Val loss Y")→ HF log_history 포맷."""
+    hist = []
+    for m in re.finditer(r"Iter\s+(\d+):.*?Train loss\s+([\d.]+)", text):
+        hist.append({"step": int(m.group(1)), "loss": float(m.group(2))})
+    for m in re.finditer(r"Iter\s+(\d+):\s*Val loss\s+([\d.]+)", text):
+        hist.append({"step": int(m.group(1)), "eval_loss": float(m.group(2))})
+    return sorted(hist, key=lambda h: h.get("step", 0))
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--model", default="mlx-community/Qwen2.5-7B-Instruct-4bit",
+                    help="MLX 모델 (mlx-community 허브). 메모리 빠듯하면 -3B-4bit 로.")
+    ap.add_argument("--data", required=True, help="chat jsonl (structverify export)")
+    ap.add_argument("--out", default="./adapter")
+    ap.add_argument("--iters", type=int, default=100)
+    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)
+    args = ap.parse_args()
+
+    os.makedirs(args.out, exist_ok=True)
+    data_dir = tempfile.mkdtemp(prefix="sv_mlx_")
+    ntr, nva = to_mlx_data(args.data, data_dir)
+    print(f"[train_mlx] MLX 데이터 변환: train {ntr} · valid {nva} → {data_dir}")
+
+    cmd = [
+        sys.executable, "-m", "mlx_lm", "lora",
+        "--model", args.model, "--train",
+        "--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
+    ]
+    print("[train_mlx] 실행:", " ".join(cmd))
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    log = proc.stdout + "\n" + proc.stderr
+    print(log[-2000:])
+    shutil.rmtree(data_dir, ignore_errors=True)
+
+    # mlx 로그 → 표준 trainer_state.json (TrainDoctor 호환)
+    hist = parse_mlx_log(log)
+    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:
+        print(f"⚠ mlx_lm.lora 종료코드 {proc.returncode} — 로그 확인")
+        sys.exit(proc.returncode)
+    print(f"\n✅ 완료 — 어댑터: {args.out}  (trainer_state.json {len(hist)}개 기록)")
+    print("   다음: TrainDoctor 진단, EvalGate 채택 판정")
+
+
+if __name__ == "__main__":
+    main()

structverify/training/recipe/train_qlora.py

@@ -0,0 +1,104 @@
+#!/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
+
+
+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)
+    args = ap.parse_args()
+
+    # unsloth: 3060/T4에서 QLoRA 2배 빠름 + 메모리 절약
+    from unsloth import FastLanguageModel
+    from trl import SFTTrainer, SFTConfig
+
+    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",
+    )
+
+    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",
+        ),
+    )
+    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")
+    print(f"\n✅ 완료 — 어댑터: {args.out}  (trainer_state.json 포함)")
+    print("   다음: TrainDoctor로 진단, EvalGate로 채택 여부 판정")
+
+
+if __name__ == "__main__":
+    main()