۱۱. پروژه (۱): خط‌کش‌های ذهن‌یار

New-Item -ItemType Directory -Force evals, projects\ch03_evaluation
New-Item -ItemType File projects\ch03_evaluation\__init__.py

"""خط‌کش‌های ذهن‌یار — سنجه‌های فصل ۳.

دو دسته سنجه این‌جاست:
  ۱. سنجهٔ مدل زبانی: سرگشتگی (perplexity) — مدل چقدر از یک متن غافلگیر می‌شود
  ۲. سنجه‌های شباهت با پاسخ مرجع: تطابق دقیق، هم‌پوشانی واژه‌ها،
     فاصلهٔ ویرایشی، هم‌پوشانی n-gram و شباهت کسینوسی

همه بدون هیچ کتابخانهٔ بیرونی.
"""
import math
import re


# ---------------------------------------------------------------------------
#  ۱. سرگشتگی
# ---------------------------------------------------------------------------

def perplexity(lm, text: str) -> dict:
    """سرگشتگی مدل روی یک متن، به‌همراه غافلگیری تک‌تک توکن‌ها.

    غافلگیری هر توکن = -log2(احتمالی که مدل به آن داده بود)  [بیت]
    آنتروپی متقاطع     = میانگین غافلگیری‌ها
    سرگشتگی            = 2 به توان آنتروپی متقاطع
    """
    from .tokenizer import EOS

    ids = lm.tok.encode(text) + [EOS]          # پایان متن را هم باید حدس بزند
    context, tokens, total_bits = [], [], 0.0
    for t in ids:
        p = lm.probs(context)[t]
        bits = -math.log2(p)
        total_bits += bits
        tokens.append((lm._show(t), p, bits))
        context.append(t)

    cross_entropy = total_bits / len(ids)
    return {
        "tokens": tokens,
        "cross_entropy": cross_entropy,                       # بیت به‌ازای هر توکن
        "perplexity": 2 ** cross_entropy,
        "bpc": total_bits / max(len(text), 1),                # بیت به‌ازای هر نویسه
        "bpb": total_bits / max(len(text.encode("utf-8")), 1),  # بیت به‌ازای هر بایت
    }


# ---------------------------------------------------------------------------
#  ۲. یکسان‌سازی متن فارسی
# ---------------------------------------------------------------------------

# «ي» و «ك» عربی با «ی» و «ک» فارسی ظاهراً یکی‌اند ولی برای کامپیوتر دو حرف جدا
_ARABIC = str.maketrans({"ي": "ی", "ك": "ک", "ة": "ه", "ۀ": "هٔ", "‌": " "})
_DIGITS = str.maketrans("۰۱۲۳۴۵۶۷۸۹٠١٢٣٤٥٦٧٨٩", "01234567890123456789")


def normalize(text: str) -> str:
    """متن را یکسان می‌کند تا تفاوت‌های ظاهری، «نه» حساب نشوند."""
    t = text.translate(_ARABIC).translate(_DIGITS).lower()
    t = re.sub(r"[^\w\s]", " ", t)               # علامت‌های نگارشی بیرون
    return re.sub(r"\s+", " ", t).strip()


def words(text: str) -> list[str]:
    return normalize(text).split()


# ---------------------------------------------------------------------------
#  ۳. تطابق دقیق
# ---------------------------------------------------------------------------

def exact_match(prediction: str, references: list[str]) -> bool:
    """دقیقاً برابر یکی از پاسخ‌های مرجع است؟ (بعد از یکسان‌سازی)"""
    p = normalize(prediction)
    return any(p == normalize(r) for r in references)


def contains_match(prediction: str, references: list[str]) -> bool:
    """یکی از پاسخ‌های مرجع **داخل** پاسخ هست؟ — آسان‌گیرتر، ولی خطرناک‌تر."""
    p = normalize(prediction)
    return any(normalize(r) in p for r in references)


# ---------------------------------------------------------------------------
#  ۴. شباهت واژگانی
# ---------------------------------------------------------------------------

def word_overlap(prediction: str, reference: str) -> float:
    """چه کسری از واژه‌های مرجع در پاسخ آمده؟ (بین ۰ و ۱)"""
    ref = words(reference)
    pred = set(words(prediction))
    return sum(1 for w in ref if w in pred) / len(ref) if ref else 0.0


def edit_distance(a: str, b: str) -> int:
    """کمترین تعداد حذف، درج یا جایگزینی حرف برای رسیدن از a به b."""
    prev = list(range(len(b) + 1))
    for i, ca in enumerate(a, 1):
        cur = [i]
        for j, cb in enumerate(b, 1):
            cur.append(min(prev[j] + 1,                 # حذف
                           cur[j - 1] + 1,              # درج
                           prev[j - 1] + (ca != cb)))   # جایگزینی (اگر فرق داشتند)
        prev = cur
    return prev[-1]


def edit_similarity(a: str, b: str) -> float:
    """فاصلهٔ ویرایشی، تبدیل‌شده به شباهتی بین ۰ و ۱."""
    a, b = normalize(a), normalize(b)
    longest = max(len(a), len(b))
    return 1 - edit_distance(a, b) / longest if longest else 1.0


def ngram_overlap(prediction: str, reference: str, n: int = 2) -> float:
    """چه کسری از n-gramهای مرجع در پاسخ هم هست؟ (خانوادهٔ ROUGE)"""
    def grams(ws):
        return [tuple(ws[i:i + n]) for i in range(len(ws) - n + 1)]
    ref = grams(words(reference))
    pred = set(grams(words(prediction)))
    return sum(1 for g in ref if g in pred) / len(ref) if ref else 0.0


# ---------------------------------------------------------------------------
#  ۵. شباهت کسینوسی
# ---------------------------------------------------------------------------

def cosine(a: list[float], b: list[float]) -> float:
    """کسینوس زاویهٔ بین دو بردار: ۱ یعنی هم‌جهت، ۰ یعنی بی‌ربط، -۱ یعنی مخالف."""
    dot = sum(x * y for x, y in zip(a, b))
    na = math.sqrt(sum(x * x for x in a))
    nb = math.sqrt(sum(y * y for y in b))
    return dot / (na * nb) if na and nb else 0.0


def all_scores(prediction: str, references: list[str], embedder=None) -> dict:
    """همهٔ سنجه‌های شباهت یک پاسخ، در برابر بهترین پاسخ مرجع."""
    best = lambda f: max(f(prediction, r) for r in references)
    scores = {
        "exact": exact_match(prediction, references),
        "contains": contains_match(prediction, references),
        "word_overlap": best(word_overlap),
        "edit_sim": best(edit_similarity),
        "bigram": best(ngram_overlap),
    }
    if embedder is not None:
        scores["semantic"] = best(lambda p, r: cosine(embedder.embed(p), embedder.embed(r)))
    return scores

"""امبدینگ ذهن‌یار — تبدیل متن به بردار، از صفر و بدون کتابخانهٔ بیرونی.

ایده‌اش جمله‌ای قدیمی از زبان‌شناسی است:
    «معنای هر واژه را از همسایه‌هایش بشناس.»
اگر «دما» و «top-p» در متن درس‌ها مدام کنار واژه‌های مشترکی مثل «احتمال»
و «نمونه‌برداری» بیایند، بردارشان هم شبیه می‌شود — بی‌آنکه کسی به مدل
گفته باشد این دو به هم ربط دارند.

چهار قدم:
  ۱. ریشه‌یابی سبک: «پاسخ‌ها» و «پاسخ» یک واژه حساب شوند
  ۲. هم‌نشینی: بشمار هر واژه در فاصلهٔ ۴ واژه‌ای از کدام واژه‌ها آمده
  ۳. PMI: هم‌نشینی‌هایی که بیشتر از «شانسی» اتفاق افتاده‌اند را پررنگ کن
  ۴. فشرده‌سازی و پرداخت: بردار هزاران‌بعدی را با «تصویر تصادفی» به ۱۲۸
     عدد برسان، طول همه را یکی کن، و جهتِ مشترکِ همه را از آن‌ها کم کن

این مدل کوچک روی چند صد پاراگراف آموزش می‌بیند؛ مدل‌های امبدینگ واقعی
روی میلیاردها جمله. پس انتظار معجزه نداشته باشید — ولی ایده همان است.
"""
import math
import random
import re
from collections import Counter, defaultdict

from .corpus import load_corpus

DIM = 128          # طول هر بردار
WINDOW = 4         # چند واژه این‌طرف و آن‌طرف را همسایه حساب کنیم
MIN_COUNT = 2      # واژه‌هایی که فقط یک بار آمده‌اند چیزی یاد نمی‌دهند

# واژه‌های پرتکراری که معنای خاصی نمی‌رسانند و همسایهٔ همه‌چیزند
STOPWORDS = set("""و در به از که این را با است برای یک آن هم تا اگر یا ها بر
نه همین هر ولی می‌شود می‌کند شود کند باید چه دیگر خود""".split())

# تکه‌ها و پسوندهای دستوری فارسی که معنای اصلی واژه را عوض نمی‌کنند
PIECES = set("ها های تر ترین ی ای می نمی".split())
SUFFIXES = ("ترین", "های", "ها", "تر", "ای", "ی")

_WORD = re.compile(r"[\w‌]+")


def stem(word: str) -> str:
    """ریشه‌یابی خیلی ساده: «می‌شوند» ← «شوند»، «پاسخ‌ها» ← «پاسخ»، «زبانی» ← «زبان»."""
    parts = [p for p in word.split("‌") if p and p not in PIECES]
    w = "".join(parts)
    for s in SUFFIXES:
        if w.endswith(s) and len(w) - len(s) >= 3:     # ریشهٔ خیلی کوتاه نماند
            return w[:-len(s)]
    return w


def tokenize_words(text: str) -> list[tuple[str, str]]:
    """فهرست (ریشه، شکل اصلی) واژه‌های معنادار متن."""
    out = []
    for w in _WORD.findall(text.lower()):
        if w in STOPWORDS or w.isdigit():
            continue
        s = stem(w)
        if s and s not in STOPWORDS:
            out.append((s, w))
    return out


class WordEmbedding:
    def __init__(self):
        self.vectors: dict[str, list[float]] = {}
        self.idf: dict[str, float] = {}
        self.surface: dict[str, str] = {}     # ریشه ← رایج‌ترین شکل نوشتاری‌اش

    def train(self, texts: list[str], seed: int = 0) -> "WordEmbedding":
        pairs = [tokenize_words(t) for t in texts]
        docs = [[s for s, _ in p] for p in pairs]
        counts = Counter(w for d in docs for w in d)
        vocab = {w for w, c in counts.items() if c >= MIN_COUNT}

        # برای نمایش: هر ریشه با رایج‌ترین شکلی که در متن داشته
        forms = defaultdict(Counter)
        for p in pairs:
            for s, w in p:
                forms[s][w] += 1
        self.surface = {s: f.most_common(1)[0][0] for s, f in forms.items()}

        # ۲. هم‌نشینی
        co = defaultdict(Counter)
        for d in docs:
            ws = [w for w in d if w in vocab]
            for i, w in enumerate(ws):
                for j in range(max(0, i - WINDOW), min(len(ws), i + WINDOW + 1)):
                    if i != j:
                        co[w][ws[j]] += 1
        total = sum(sum(c.values()) for c in co.values())
        row = {w: sum(c.values()) for w, c in co.items()}

        # ۴. برای هر واژه یک بردار تصادفی ثابت از +۱ و -۱
        rng = random.Random(seed)
        basis = {w: [rng.choice((-1.0, 1.0)) for _ in range(DIM)] for w in sorted(vocab)}

        # ۳ و ۴. بردار هر واژه = جمع بردار همسایه‌ها، هر کدام با وزن PMI
        for w, neighbours in co.items():
            v = [0.0] * DIM
            for u, n in neighbours.items():
                pmi = math.log(n * total / (row[w] * row[u]))
                if pmi > 0:                        # فقط هم‌نشینی‌های «معنادار»
                    b = basis[u]
                    for k in range(DIM):
                        v[k] += pmi * b[k]
            length = math.sqrt(sum(x * x for x in v)) or 1.0
            self.vectors[w] = [x / length for x in v]          # طول همه یکی

        # ۴. جهت مشترک: میانگین همهٔ بردارها را از هر کدام کم کن
        mean = [sum(v[k] for v in self.vectors.values()) / len(self.vectors) for k in range(DIM)]
        self.vectors = {w: [x - m for x, m in zip(v, mean)] for w, v in self.vectors.items()}

        # واژهٔ کمیاب‌تر، در معنای جمله سهم بیشتری دارد (وزن IDF)
        doc_freq = Counter(w for d in docs for w in set(d))
        self.idf = {w: math.log(len(docs) / doc_freq[w]) for w in vocab}
        return self

    def embed(self, text: str) -> list[float]:
        """امبدینگ یک جمله = جمع وزن‌دار بردار واژه‌هایش."""
        v = [0.0] * DIM
        for s, _ in tokenize_words(text):
            if s in self.vectors:
                weight = self.idf.get(s, 1.0)
                for k, x in enumerate(self.vectors[s]):
                    v[k] += weight * x
        return v

    def nearest(self, word: str, k: int = 6) -> list[tuple[str, float]]:
        """نزدیک‌ترین واژه‌ها به یک واژه — برای دیدن اینکه مدل چه یاد گرفته."""
        from .metrics import cosine
        key = stem(word.lower())
        if key not in self.vectors:
            return []
        target = self.vectors[key]
        scored = [(self.surface.get(u, u), cosine(target, v))
                  for u, v in self.vectors.items() if u != key]
        return sorted(scored, key=lambda x: -x[1])[:k]


_model: WordEmbedding | None = None


def get_embedder() -> WordEmbedding:
    """امبدینگ را یک بار روی پیکره آموزش می‌دهد و نگه می‌دارد (حدود یک ثانیه)."""
    global _model
    if _model is None:
        _model = WordEmbedding().train(load_corpus())
    return _model

[
  {
    "question": "مدل پایه چیست؟",
    "references": [
      "مدل پایه مدلی بزرگ و همه‌کاره است که می‌شود روی آن اپلیکیشن‌های مختلفی ساخت."
    ]
  },
  {
    "question": "توکن چیست؟",
    "references": [
      "توکن تکه‌ای بین حرف و کلمه است که مدل با آن کار می‌کند."
    ]
  },
  {
    "question": "تنظیم دقیق یعنی چه؟",
    "references": [
      "تنظیم دقیق یعنی ادامه دادن آموزش یک مدل آماده روی داده‌های خودمان، که وزن‌های مدل را عوض می‌کند."
    ]
  },
  {
    "question": "پشتهٔ مهندسی هوش مصنوعی چند لایه دارد؟",
    "references": [
      "سه",
      "سه لایه"
    ]
  },
  {
    "question": "پرامپت چیست؟",
    "references": [
      "پرامپت متنی است که به مدل می‌دهیم تا ادامه‌اش را بنویسد یا به آن جواب بدهد."
    ]
  }
]

"""پروژهٔ فصل ۳ (بخش ۱) — خط‌کش‌های ذهن‌یار.

اجرا:
    .venv\\Scripts\\python.exe -m projects.ch03_evaluation.run
"""
import json
import pathlib

from zehnyar import _console
from zehnyar.core.assistant import Zehnyar
from zehnyar.embedding import get_embedder
from zehnyar.lm import get_lm
from zehnyar.metrics import all_scores, edit_distance, perplexity, word_overlap

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

EVALS = pathlib.Path(__file__).resolve().parent.parent.parent / "evals" / "qa.json"


def title(text: str) -> None:
    print("\n" + "=" * 56)
    print(" " + text)
    print("=" * 56)


def main() -> None:
    lm = get_lm()

    # ---------- ۱. سرگشتگی ----------
    title("۱. سرگشتگی: مدل چقدر غافلگیر می‌شود؟")
    samples = [
        ("دیده‌شده", "مدل پایه از جعبه که بیرون می‌آید همه‌منظوره است."),
        ("تازه    ", "مادربزرگم هر جمعه آش رشته می‌پزد."),
        ("چرت‌وپرت", "کلمه گربه چون بنفش اینترنت."),
    ]
    for label, text in samples:
        r = perplexity(lm, text)
        print(f"\n  {label} | PPL={r['perplexity']:>7.1f} | "
              f"{r['cross_entropy']:.2f} بیت/توکن | {r['bpb']:.2f} بیت/بایت")
        print(f"           {text}")
        worst = sorted(r["tokens"], key=lambda t: -t[2])[:3]
        print("           غافلگیرکننده‌ترین: " +
              "، ".join(f"{tok} ({bits:.1f} بیت)" for tok, _, bits in worst))

    # ---------- ۲. شباهت واژگانی ----------
    title("۲. شباهت واژگانی")
    ref = "گربه‌های من موش‌ها را می‌ترسانند"
    for cand in ["گربه‌های من موش‌ها را می‌خورند", "گربه‌ها و موش‌ها همیشه دعوا می‌کنند"]:
        print(f"\n  مرجع : {ref}\n  پاسخ : {cand}")
        print(f"  هم‌پوشانی واژه‌ها: {word_overlap(cand, ref):.0%}")
    for a, b in [("bad", "bard"), ("bad", "cash")]:
        print(f"\n  فاصلهٔ ویرایشی {a} ← {b}: {edit_distance(a, b)}")

    # ---------- ۳. امبدینگ ----------
    title("۳. امبدینگ: همسایه‌های معنایی")
    emb = get_embedder()
    for word in ["دما", "سرگشتگی", "شباهت"]:
        near = emb.nearest(word, 5)
        print(f"\n  {word} ← " + "، ".join(f"{w} ({s:.2f})" for w, s in near))

    # ---------- ۴. ارزیابی ذهن‌یار ----------
    bot = Zehnyar()
    title(f"۴. ارزیابی ذهن‌یار با دادهٔ مرجع  |  provider={bot.info()['provider']}")
    items = json.loads(EVALS.read_text(encoding="utf-8"))
    totals = {}
    for item in items:
        answer = bot.ask(item["question"]).text
        s = all_scores(answer, item["references"], emb)
        for k, v in s.items():
            totals[k] = totals.get(k, 0) + float(v)
        print(f"\n  سؤال : {item['question']}")
        print(f"  پاسخ : {answer}")
        print(f"  exact={'✓' if s['exact'] else '✗'}  contains={'✓' if s['contains'] else '✗'}  "
              f"words={s['word_overlap']:.2f}  edit={s['edit_sim']:.2f}  "
              f"bigram={s['bigram']:.2f}  semantic={s['semantic']:.2f}")

    print("\n" + "-" * 56)
    print("میانگین روی " + str(len(items)) + " سؤال:")
    print("  " + "  ".join(f"{k}={v / len(items):.2f}" for k, v in totals.items()))


if __name__ == "__main__":
    main()

.venv\Scripts\python.exe -m projects.ch03_evaluation.run

========================================================
 ۱. سرگشتگی: مدل چقدر غافلگیر می‌شود؟
========================================================

  دیده‌شده | PPL=    3.2 | 1.69 بیت/توکن | 0.38 بیت/بایت
           مدل پایه از جعبه که بیرون می‌آید همه‌منظوره است.
           غافلگیرکننده‌ترین: ▁پایه (5.2 بیت)، ▁مدل (4.7 بیت)، ▁می‌آید (3.1 بیت)

  تازه     | PPL=  203.8 | 7.67 بیت/توکن | 2.64 بیت/بایت
           مادربزرگم هر جمعه آش رشته می‌پزد.
           غافلگیرکننده‌ترین: اد (13.5 بیت)، ▁آ (13.5 بیت)، ▁ر (13.5 بیت)

  چرت‌وپرت | PPL=  736.0 | 9.52 بیت/توکن | 2.14 بیت/بایت
           کلمه گربه چون بنفش اینترنت.
           غافلگیرکننده‌ترین: ▁اینترنت (15.6 بیت)، ▁کلمه (14.8 بیت)، ▁گر (13.8 بیت)

========================================================
 ۲. شباهت واژگانی
========================================================

  مرجع : گربه‌های من موش‌ها را می‌ترسانند
  پاسخ : گربه‌های من موش‌ها را می‌خورند
  هم‌پوشانی واژه‌ها: 88%

  مرجع : گربه‌های من موش‌ها را می‌ترسانند
  پاسخ : گربه‌ها و موش‌ها همیشه دعوا می‌کنند
  هم‌پوشانی واژه‌ها: 50%

  فاصلهٔ ویرایشی bad ← bard: 1

  فاصلهٔ ویرایشی bad ← cash: 3

========================================================
 ۳. امبدینگ: همسایه‌های معنایی
========================================================

  دما ← بشناس (0.37)، صفر (0.36)، متوسط (0.36)، توزیع (0.35)، top (0.34)

  سرگشتگی ← کمتر (0.44)، آنتروپی (0.41)، خورد (0.40)، bpc (0.38)، متقاطع (0.34)

  شباهت ← معنایی (0.59)، سنجه (0.36)، امبدینگ (0.35)، معنا (0.32)، واژه (0.31)

========================================================
 ۴. ارزیابی ذهن‌یار با دادهٔ مرجع  |  provider=mock
========================================================

  سؤال : مدل پایه چیست؟
  پاسخ : مدل پایه یک مدل بزرگ و همه‌منظوره است که می‌توان آن را پایهٔ ساخت ده‌ها اپلیکیشن مختلف قرار داد.
  exact=✗  contains=✗  words=0.65  edit=0.56  bigram=0.31  semantic=0.77

  سؤال : توکن چیست؟
  پاسخ : توکن واحد کار مدل است؛ چیزی بین حرف و کلمه. برای انگلیسی هر توکن حدوداً سه‌چهارم یک کلمه است.
  exact=✗  contains=✗  words=0.53  edit=0.43  bigram=0.29  semantic=0.83

  سؤال : تنظیم دقیق یعنی چه؟
  پاسخ : تنظیم دقیق یعنی ادامهٔ آموزش یک مدل آماده روی دادهٔ خودتان، که وزن‌های مدل را تغییر می‌دهد.
  exact=✗  contains=✗  words=0.81  edit=0.82  bigram=0.60  semantic=0.88

  سؤال : پشتهٔ مهندسی هوش مصنوعی چند لایه دارد؟
  پاسخ : پشتهٔ مهندسی هوش مصنوعی سه لایه دارد: توسعهٔ اپلیکیشن، توسعهٔ مدل، و زیرساخت.
  exact=✗  contains=✓  words=1.00  edit=0.10  bigram=1.00  semantic=0.44

  سؤال : پرامپت چیست؟
  پاسخ : هنوز چیزی در این باره بلد نیستم. در فصل ۶ با RAG یاد می‌گیرم که جواب را از متن درس‌ها پیدا کنم.
  exact=✗  contains=✗  words=0.22  edit=0.28  bigram=0.00  semantic=0.20

--------------------------------------------------------
میانگین روی 5 سؤال:
  exact=0.00  contains=0.20  word_overlap=0.64  edit_sim=0.44  bigram=0.44  semantic=0.62