۱۳. پروژه (۲): خط لوله و داشبورد مقایسهٔ مدل‌ها

"""خط لولهٔ ارزیابی ذهن‌یار — فصل ۴.

یک مدل را روی کل دیتاست طلایی اجرا می‌کند، هر پاسخ را با بررسی‌های
checks.py می‌سنجد، نتیجه‌ها را برش‌به‌برش جمع می‌زند، با شرط‌های سخت
مقایسه می‌کند، و هر اجرا را با همهٔ تنظیماتش در دفترچهٔ آزمایش‌ها
ثبت می‌کند تا بعداً قابل‌مقایسه و قابل‌تکرار باشد.
"""
import json
import pathlib
from datetime import datetime

from . import checks, config
from .core.assistant import Zehnyar
from .evalset import SLICES, bootstrap, fingerprint

ROOT = pathlib.Path(__file__).resolve().parent.parent
LOG = ROOT / "runs" / "experiments.jsonl"
SEED = 0                     # بذر ثابت: مدل‌های احتمالی هر بار همان پاسخ را بدهند

LABELS = {"accuracy": "دقت", "hallucination": "توهم", "out_of_scope": "خارج از دامنه",
          "instructions": "پیروی از دستور", "p90_ms": "تأخیر p90"}


def run_model(provider_name: str, items: list[dict]) -> dict | None:
    """همهٔ سؤال‌ها را از یک مدل می‌پرسد؛ None یعنی این مدل در دسترس نیست."""
    bot = Zehnyar(provider_name)
    if bot.provider.name != provider_name:
        return None              # get_provider به mock برگشته؛ این دیگر همان مدل نیست
    bot.ask("سلام", seed=SEED)   # گرم کردن: اولین فراخوانی کندتر است و نباید حساب شود
    rows = []
    for it in items:
        r = bot.ask(it["question"], seed=SEED)
        rows.append({
            "id": it["id"], "slice": it["slice"], "question": it["question"],
            "answer": r.text,
            "outcome": checks.outcome(it, r.text),
            "instructions_ok": all(checks.instruction_checks(r.text).values()),
            "latency_ms": r.latency_ms,
            "out_tokens": r.completion_tokens,
            "cost_usd": r.cost_usd,
        })
    return {"provider": bot.provider.name, "model": bot.provider.model,
            "rows": rows, "summary": summarize(rows)}


def rate(rows: list[dict], *good: str) -> float:
    """چه کسری از این ردیف‌ها یکی از نتیجه‌های good را گرفته‌اند؟"""
    return sum(r["outcome"] in good for r in rows) / len(rows) if rows else 0.0


def summarize(rows: list[dict]) -> dict:
    inside = [r for r in rows if r["slice"] != checks.OUT_OF_SCOPE]
    outside = [r for r in rows if r["slice"] == checks.OUT_OF_SCOPE]
    latencies = sorted(r["latency_ms"] for r in rows)
    return {
        "accuracy": rate(inside, "درست"),
        "accuracy_ci": bootstrap([rate([r], "درست") for r in inside]),
        "hallucination": rate(inside, "توهم"),
        "out_of_scope": rate(outside, "رد درست"),
        "instructions": sum(r["instructions_ok"] for r in rows) / len(rows),
        "slices": {s: rate([r for r in rows if r["slice"] == s], "درست", "رد درست")
                   for s in SLICES},
        "p50_ms": latencies[len(latencies) // 2],
        "p90_ms": latencies[round(0.9 * (len(latencies) - 1))],
        "out_tokens": sum(r["out_tokens"] for r in rows) / len(rows),
        "cost_usd": sum(r["cost_usd"] for r in rows),
    }


def failed_criteria(summary: dict, criteria: dict) -> list[str]:
    """شرط‌های سختی که این مدل رد شده (فهرست خالی یعنی همه را دارد)."""
    failed = []
    for metric, (op, limit) in criteria.items():
        value = summary[metric]
        ok = value >= limit if op == ">=" else value <= limit
        if not ok:
            failed.append(metric)
    return failed


def log_experiment(result: dict, items: list[dict]) -> None:
    """هر چیزی که اگر عوض شود نتیجه عوض می‌شود، کنار نتیجه ثبت می‌شود."""
    entry = {
        "time": datetime.now().isoformat(timespec="seconds"),
        "dataset": fingerprint(items),
        "provider": result["provider"],
        "model": result["model"],
        "sampling": {**config.SAMPLING, "seed": SEED},
        "system_prompt": config.SYSTEM_PROMPT,
        "checks": {"max_words": checks.MAX_WORDS, "min_persian": checks.MIN_PERSIAN},
        "summary": result["summary"],
    }
    LOG.parent.mkdir(exist_ok=True)
    with LOG.open("a", encoding="utf-8") as f:
        f.write(json.dumps(entry, ensure_ascii=False) + "\n")

"""داشبورد مقایسهٔ مدل‌ها — یک فایل HTML که با مرورگر باز می‌شود (فصل ۴).

هیچ کتابخانه‌ای لازم ندارد: صفحه را مثل یک رشتهٔ متنی بزرگ می‌سازیم.
html.escape نمی‌گذارد متن پاسخ‌ها (مثلاً یک < یا >) صفحه را به هم بریزد.
"""
import html

from .evalset import SLICES
from .pipeline import LABELS

STYLE = """
body { font-family: Tahoma, sans-serif; direction: rtl; background: #f6f7f9; color: #1d2330;
       max-width: 1100px; margin: 24px auto; padding: 0 16px; line-height: 1.7; }
table { border-collapse: collapse; width: 100%; background: #fff; margin: 12px 0 28px; }
th, td { border: 1px solid #dde1e8; padding: 8px 10px; text-align: right; vertical-align: top; }
small { color: #6b7385; }
.ok { background: #e5f5ec; } .bad { background: #fbe9e9; }
.win { background: #1d4ed8; color: #fff; border-radius: 6px; padding: 0 8px; font-size: .8em; }
.bar { display: flex; align-items: center; gap: 8px; margin: 4px 0; }
.bar span { width: 70px; } .bar b { width: 48px; }
.bar i { display: block; height: 14px; background: #1d4ed8; border-radius: 4px; }
.tag { font-size: .8em; padding: 0 6px; border-radius: 6px; color: #fff; }
"""
COLORS = {"درست": "#15803d", "رد درست": "#15803d", "رد صادقانه": "#b45309",
          "توهم": "#b91c1c", "پاسخ بی‌جا": "#b91c1c"}


def fmt(metric: str, value: float) -> str:
    return f"{value / 1000:.2f} ثانیه" if metric.endswith("_ms") else f"{value:.0%}"


def write_dashboard(path, results: list[dict], criteria: dict, winner: dict | None,
                    dataset: str) -> None:
    e = html.escape

    # ۱. جدول شرط‌های سخت: سبز یعنی شرط برقرار است، قرمز یعنی نه
    head = "".join(f"<th>{LABELS[m]}<br><small>{'دست‌کم' if op == '>=' else 'حداکثر'} "
                   f"{fmt(m, lim)}</small></th>" for m, (op, lim) in criteria.items())
    table = ""
    for r in results:
        badge = " <span class='win'>انتخاب</span>" if r is winner else ""
        cells = "".join(f"<td class='{'bad' if m in r['failed'] else 'ok'}'>"
                        f"{fmt(m, r['summary'][m])}</td>" for m in criteria)
        table += f"<tr><th>{e(r['provider'])} / {e(r['model'])}{badge}</th>{cells}</tr>"

    # ۲. نمودار میله‌ای هر برش
    bars = ""
    for s in SLICES:
        bars += f"<h3>{e(s)}</h3>"
        for r in results:
            v = r["summary"]["slices"][s]
            bars += (f"<div class='bar'><span>{e(r['provider'])}</span>"
                     f"<i style='width:{v * 400:.0f}px'></i><b>{v:.0%}</b></div>")

    # ۳. تک‌تک سؤال‌ها، کنار هم
    detail = ""
    for i, row in enumerate(results[0]["rows"]):
        cells = ""
        for r in results:
            x = r["rows"][i]
            cells += (f"<td><span class='tag' style='background:{COLORS[x['outcome']]}'>"
                      f"{x['outcome']}</span> {e(x['answer'][:160])}</td>")
        detail += f"<tr><td>{row['id']}</td><td>{e(row['question'])}<br><small>{e(row['slice'])}</small></td>{cells}</tr>"
    models = "".join(f"<th>{e(r['provider'])}</th>" for r in results)

    choice = f"انتخاب: {e(winner['provider'])} / {e(winner['model'])}" if winner \
        else "هیچ مدلی همهٔ شرط‌های سخت را ندارد"
    page = (f"<!doctype html><html lang='fa'><head><meta charset='utf-8'>"
            f"<title>داشبورد ارزیابی ذهن‌یار</title><style>{STYLE}</style></head><body>"
            f"<h1>داشبورد ارزیابی ذهن‌یار</h1>"
            f"<p>دیتاست طلایی: <code>{dataset}</code> · {len(results[0]['rows'])} سؤال · <b>{choice}</b></p>"
            f"<h2>شرط‌های سخت</h2><table><tr><th>مدل</th>{head}</tr>{table}</table>"
            f"<h2>برش‌به‌برش</h2>{bars}"
            f"<h2>تک‌تک سؤال‌ها</h2><table><tr><th></th><th>سؤال</th>{models}</tr>{detail}</table>"
            f"</body></html>")
    path.parent.mkdir(exist_ok=True)
    path.write_text(page, encoding="utf-8")

"""پروژهٔ فصل ۴ (بخش ۲) — خط لوله و داشبورد مقایسهٔ مدل‌ها.

اجرا:
    .venv\\Scripts\\python.exe -m projects.ch04_pipeline.run_compare
"""
import pathlib

from zehnyar import _console
from zehnyar.dashboard import write_dashboard
from zehnyar.evalset import SLICES, fingerprint, load_golden
from zehnyar.pipeline import LABELS, failed_criteria, log_experiment, run_model

_console.setup()   # تا کنسول ویندوز فارسی را درست چاپ کند

ROOT = pathlib.Path(__file__).resolve().parent.parent.parent
GOLDEN = ROOT / "evals" / "golden.json"
REPORT = ROOT / "reports" / "dashboard.html"

CANDIDATES = ["mock", "local", "ollama"]

# شرط‌های سخت، مثل جدول ۴-۳ کتاب: مدلی که حتی یکی را نداشته باشد کنار می‌رود
CRITERIA = {
    "accuracy":      (">=", 0.40),   # دست‌کم ۴۰٪ سؤال‌های داخل دامنه درست
    "hallucination": ("<=", 0.20),   # حداکثر ۲۰٪ پاسخ غلطِ مطمئن
    "out_of_scope":  (">=", 0.50),   # دست‌کم نیمی از سؤال‌های بی‌ربط را رد کند
    "instructions":  (">=", 0.80),   # دست‌کم ۸۰٪ پاسخ‌ها فارسی، کوتاه و بی‌عبارت ممنوع
    "p90_ms":        ("<=", 5000),   # ۹۰٪ پاسخ‌ها زیر ۵ ثانیه
}


def main() -> None:
    items = load_golden(GOLDEN)
    print("=" * 56)
    print(f" مقایسهٔ مدل‌ها  |  {len(items)} سؤال  |  دیتاست {fingerprint(items)}")
    print("=" * 56)

    results = []
    for name in CANDIDATES:
        r = run_model(name, items)
        if r is None:
            print(f"\n▶ {name}: در دسترس نیست — از مقایسه کنار گذاشته شد")
            continue
        s = r["summary"]
        r["failed"] = failed_criteria(s, CRITERIA)
        results.append(r)
        log_experiment(r, items)

        low, high = s["accuracy_ci"]
        print(f"\n▶ {r['provider']} / {r['model']}")
        print(f"  دقت {s['accuracy']:.0%} (بازهٔ ۹۰٪: {low:.0%} تا {high:.0%})  |  "
              f"توهم {s['hallucination']:.0%}  |  خارج از دامنه {s['out_of_scope']:.0%}  |  "
              f"دستورها {s['instructions']:.0%}")
        print("  برش‌ها: " + " · ".join(f"{sl} {s['slices'][sl]:.0%}" for sl in SLICES))
        print("  شرط‌های سخت: " + ("همه ✓" if not r["failed"] else
              "رد شد در " + "، ".join(LABELS[m] for m in r["failed"])))
        print(f"  تأخیر p90: {s['p90_ms']:.1f} ms")

    passed = [r for r in results if not r["failed"]]
    winner = max(passed, key=lambda r: r["summary"]["accuracy"]) if passed else None
    print("\n" + "-" * 56)
    if winner:
        print(f"انتخاب: {winner['provider']} — بهترین دقت میان مدل‌هایی که همهٔ شرط‌ها را دارند")
    else:
        print("انتخاب: هیچ مدلی همهٔ شرط‌های سخت را ندارد")

    write_dashboard(REPORT, results, CRITERIA, winner, fingerprint(items))
    print("داشبورد: reports/dashboard.html")
    print("دفترچهٔ آزمایش‌ها: runs/experiments.jsonl")


if __name__ == "__main__":
    main()

.venv\Scripts\python.exe -m projects.ch04_pipeline.run_compare

========================================================
 مقایسهٔ مدل‌ها  |  20 سؤال  |  دیتاست 3fc6bde6fdcf
========================================================

▶ mock / zehnyar-mock-v1
  دقت 50% (بازهٔ ۹۰٪: 31% تا 69%)  |  توهم 6%  |  خارج از دامنه 75%  |  دستورها 100%
  برش‌ها: تعریف 100% · غلط تایپی 25% · سؤال سخت 0% · خارج از دامنه 75%
  شرط‌های سخت: همه ✓
  تأخیر p90: 50.7 ms

▶ local / zehnyar-ngram-v1
  دقت 0% (بازهٔ ۹۰٪: 0% تا 0%)  |  توهم 100%  |  خارج از دامنه 0%  |  دستورها 45%
  برش‌ها: تعریف 0% · غلط تایپی 0% · سؤال سخت 0% · خارج از دامنه 0%
  شرط‌های سخت: رد شد در دقت، توهم، خارج از دامنه، پیروی از دستور
  تأخیر p90: 216.1 ms
[هشدار] Ollama در دسترس نیست — به mock برگشتم.

▶ ollama: در دسترس نیست — از مقایسه کنار گذاشته شد

--------------------------------------------------------
انتخاب: mock — بهترین دقت میان مدل‌هایی که همهٔ شرط‌ها را دارند
داشبورد: reports/dashboard.html
دفترچهٔ آزمایش‌ها: runs/experiments.jsonl

start reports\dashboard.html

Get-Content runs\experiments.jsonl

========================================================
 مقایسهٔ مدل‌ها  |  20 سؤال  |  دیتاست 3fc6bde6fdcf
========================================================

▶ mock / zehnyar-mock-v1
  دقت 50% (بازهٔ ۹۰٪: 31% تا 69%)  |  توهم 6%  |  خارج از دامنه 75%  |  دستورها 100%
  برش‌ها: تعریف 100% · غلط تایپی 25% · سؤال سخت 0% · خارج از دامنه 75%
  شرط‌های سخت: همه ✓
  تأخیر p90: 51.1 ms

▶ local / zehnyar-ngram-v1
  دقت 0% (بازهٔ ۹۰٪: 0% تا 0%)  |  توهم 100%  |  خارج از دامنه 0%  |  دستورها 45%
  برش‌ها: تعریف 0% · غلط تایپی 0% · سؤال سخت 0% · خارج از دامنه 0%
  شرط‌های سخت: رد شد در دقت، توهم، خارج از دامنه، پیروی از دستور
  تأخیر p90: 125.9 ms

▶ ollama / qwen2.5:7b
  دقت 6% (بازهٔ ۹۰٪: 0% تا 19%)  |  توهم 94%  |  خارج از دامنه 25%  |  دستورها 90%
  برش‌ها: تعریف 0% · غلط تایپی 0% · سؤال سخت 20% · خارج از دامنه 25%
  شرط‌های سخت: رد شد در دقت، توهم، خارج از دامنه، تأخیر p90
  تأخیر p90: 39028.4 ms

--------------------------------------------------------
انتخاب: mock — بهترین دقت میان مدل‌هایی که همهٔ شرط‌ها را دارند
داشبورد: reports/dashboard.html
دفترچهٔ آزمایش‌ها: runs/experiments.jsonl