۱۳. پروژه (۲): خروجی ساختاریافته و اتصال به ذهن‌یار

"""خروجی ساختاریافته — دو ابزار از ابزارهایی که در درس ۱۰ دیدیم.

۱. نمونه‌برداری محدودشده (constrained sampling):
   در هر قدم، لاجیت توکن‌هایی که به یک خروجی مجاز نمی‌رسند حذف می‌شوند.
   مدل **نمی‌تواند** چیزی خارج از فهرست بگوید — نه اینکه «قول بدهد» نگوید.

۲. پس‌پردازش دفاعی (defensive parsing):
   مدل‌ها اشتباه‌های تکراری می‌کنند: آکولاد بسته را جا می‌اندازند، دور JSON
   علامت ``` می‌گذارند، یا ویرگول اضافه آخر فهرست می‌گذارند. این‌ها را با
   یک اسکریپت ساده درست می‌کنیم — همان کاری که لینکدین کرد و درصد خروجی
   سالمش را از ۹۰ به ۹۹٫۹۹ رساند.
"""
import json
import math
import random
import re

from . import sampling
from .lm import NGramLM


def generate_choice(lm: NGramLM, prompt: str, options: list[str],
                    temperature: float = 1.0, seed: int | None = None) -> dict:
    """یکی از گزینه‌های مجاز را تولید می‌کند — توکن به توکن، با فیلتر لاجیت."""
    rng = random.Random(seed)
    encoded = {opt: lm.tok.encode(" " + opt.strip()) for opt in options}
    context = lm.tok.encode(prompt)
    made: list[int] = []
    steps = []

    while True:
        # گزینه‌هایی که هنوز با آنچه تا اینجا ساخته‌ایم سازگارند
        alive = [o for o, ids in encoded.items() if ids[:len(made)] == made]
        done = [o for o in alive if len(encoded[o]) == len(made)]
        if done:
            choice = done[0]
            break

        allowed = {encoded[o][len(made)] for o in alive}
        logits = lm.logits(context)
        masked = {t: x for t, x in logits.items() if t in allowed}

        before = sampling.softmax(logits, 1.0)
        token, final = sampling.choose(masked, temperature, rng=rng)
        steps.append({
            "allowed": [lm.tok.vocab[t] for t in sorted(allowed)],
            "picked": lm.tok.vocab[token],
            "mass_kept": round(sum(before[t] for t in allowed), 6),
        })
        made.append(token)
        context.append(token)

    return {"choice": choice, "steps": steps}


def free_vs_constrained(lm: NGramLM, prompt: str, options: list[str],
                        temperature: float = 1.0, seed: int | None = None) -> dict:
    """یک بار آزاد تولید می‌کند، یک بار محدود — برای مقایسه در آزمایشگاه."""
    free = lm.generate(prompt, max_tokens=8, temperature=temperature, seed=seed)
    limited = generate_choice(lm, prompt, options, temperature, seed)
    scores = {}
    for o in options:
        lp, n = lm.logprob(prompt, " " + o.strip())
        scores[o] = round(lp / max(n, 1), 4)      # میانگین logprob، نه جمع
    return {
        "free": free.text,
        "free_valid": free.text.strip() in [o.strip() for o in options],
        "constrained": limited["choice"],
        "steps": limited["steps"],
        "avg_logprob": scores,
        "prob_share": _share(scores),
    }


def _share(avg_logprobs: dict) -> dict:
    exps = {k: math.exp(v) for k, v in avg_logprobs.items()}
    total = sum(exps.values())
    return {k: round(v / total, 4) for k, v in exps.items()}


# ---------------------------------------------------------------------------
#  پس‌پردازش دفاعی
# ---------------------------------------------------------------------------

def parse_json_defensive(text: str):
    """JSON نیمه‌خراب را تا جای ممکن تعمیر می‌کند. خروجی: (شیء یا None، فهرست تعمیرها)."""
    fixes = []
    s = text.strip()

    # ۱. حصار کد: ```json ... ```
    fence = re.search(r"```(?:json)?\s*(.*?)(?:```|$)", s, re.S)
    if fence:
        s = fence.group(1).strip()
        fixes.append("حذف حصار ```")

    # ۲. متن اضافهٔ قبل از اولین آکولاد: «حتماً! این هم JSON شما: {...}»
    start = min([i for i in (s.find("{"), s.find("[")) if i >= 0], default=-1)
    if start > 0:
        s = s[start:]
        fixes.append("حذف متن اضافهٔ اول")

    try:
        return json.loads(s), fixes
    except json.JSONDecodeError:
        pass

    # ۳. ویرگول آویزان: {"a": 1,}
    s2 = re.sub(r",\s*([}\]])", r"\1", s)
    if s2 != s:
        s = s2
        fixes.append("حذف ویرگول آویزان")

    # ۴. رشته یا آکولاد بسته‌نشده (معمولاً چون تولید زود متوقف شده)
    stack, in_str, esc = [], False, False
    for ch in s:
        if in_str:
            if esc:
                esc = False
            elif ch == "\\":
                esc = True
            elif ch == '"':
                in_str = False
        elif ch == '"':
            in_str = True
        elif ch in "{[":
            stack.append("}" if ch == "{" else "]")
        elif ch in "}]" and stack:
            stack.pop()
    if in_str:
        s += '"'
        fixes.append("بستن رشتهٔ نیمه‌کاره")
    if stack:
        s = re.sub(r",\s*$", "", s) + "".join(reversed(stack))
        fixes.append("بستن " + str(len(stack)) + " آکولاد/کروشه")

    try:
        return json.loads(s), fixes
    except json.JSONDecodeError:
        return None, fixes

"""پروژهٔ فصل ۲ (بخش ۲) — خروجی ساختاریافته.

اجرا:
    .venv\\Scripts\\python.exe -m projects.ch02_sampling.run_structured
"""
from zehnyar import _console
from zehnyar.lm import get_lm
from zehnyar.structured import generate_choice, parse_json_defensive

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


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


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

    # ---------- ۱. خروجی محدودشده ----------
    title("۱. نمونه‌برداری محدودشده")
    options = ["پرامپت", "داده", "ارزیابی"]
    q = "سه ابزار برای رام کردن مدل داریم و اولی مهندسی"
    free = lm.generate(q, max_tokens=6, temperature=1.0, seed=3).text
    pick = generate_choice(lm, q, options, temperature=1.0, seed=3)["choice"]
    print(f"\n  پرامپت : {q} ...")
    print(f"  آزاد   : {free}")
    print(f"  محدود  : {pick}   (فقط از بین {options})")

    # ---------- ۲. پس‌پردازش دفاعی ----------
    title("۲. تعمیر JSON نیمه‌کاره")
    broken = 'حتماً! این هم خروجی: {"topic": "نمونه‌برداری", "tags": ["دما", "top-p",'
    obj, fixes = parse_json_defensive(broken)
    print(f"\n  ورودی  : {broken}")
    print(f"  تعمیرها: {'، '.join(fixes)}")
    print(f"  نتیجه  : {obj}")

    print("\n" + "-" * 52)
    print("مدل آزاد هرچه بخواهد می‌گوید؛ با فیلتر لاجیت و پس‌پردازش، خروجی قابل‌استفاده می‌شود.")


if __name__ == "__main__":
    main()

.venv\Scripts\python.exe -m projects.ch02_sampling.run_structured

====================================================
 ۱. نمونه‌برداری محدودشده
====================================================

  پرامپت : سه ابزار برای رام کردن مدل داریم و اولی مهندسی ...
  آزاد   : که فقط‌ها آن را ک
  محدود  : پرامپت   (فقط از بین ['پرامپت', 'داده', 'ارزیابی'])

====================================================
 ۲. تعمیر JSON نیمه‌کاره
====================================================

  ورودی  : حتماً! این هم خروجی: {"topic": "نمونه‌برداری", "tags": ["دما", "top-p",
  تعمیرها: حذف متن اضافهٔ اول، بستن 2 آکولاد/کروشه
  نتیجه  : {'topic': 'نمونه\u200cبرداری', 'tags': ['دما', 'top-p']}

----------------------------------------------------
مدل آزاد هرچه بخواهد می‌گوید؛ با فیلتر لاجیت و پس‌پردازش، خروجی قابل‌استفاده می‌شود.

"""ارائه‌دهندهٔ مدل زبانی محلی — همان مدل n-gram فصل ۲، پشت قرارداد Provider.

این مدل فقط **پیش‌آموزش** دیده، پس‌آموزش ندیده. یعنی جواب نمی‌دهد؛
متن شما را **ادامه** می‌دهد — دقیقاً مثل مثال پیتزا در درس ۶.
برای همین پیش‌فرض ذهن‌یار هنوز mock است؛ این یکی برای دیدن رفتار
یک مدل خام است:

    $env:ZEHNYAR_PROVIDER = "local"
"""
import time

from .base import Provider, Message, Completion


class LocalLMProvider(Provider):
    name = "local"
    model = "zehnyar-ngram-v1"

    def __init__(self):
        from ..lm import get_lm
        self.lm = get_lm()

    def complete(self, messages: list[Message], **params) -> Completion:
        start = time.perf_counter()

        # مدل خام «گفت‌وگو» نمی‌فهمد؛ فقط آخرین پیام کاربر را ادامه می‌دهد
        prompt = next((m.content for m in reversed(messages) if m.role == "user"), "")
        gen = self.lm.generate(
            prompt,
            max_tokens=params.get("max_tokens", 40),
            temperature=params.get("temperature", 0.7),
            top_k=params.get("top_k", 0),
            top_p=params.get("top_p", 0.9),
            seed=params.get("seed"),
            # بعد از علامت سؤال، محتمل‌ترین ادامه «پایان متن» است؛ نمی‌گذاریم خالی برگردد
            min_tokens=params.get("min_tokens", 4),
        )

        elapsed = (time.perf_counter() - start) * 1000
        return Completion(
            text=gen.text,
            model=self.model,
            provider=self.name,
            prompt_tokens=len(self.lm.tok.encode(prompt)),
            completion_tokens=len(gen.steps),
            latency_ms=round(elapsed, 2),
            # هر توکن جدا ساخته می‌شود، پس اولین توکن سهم خودش را دارد
            ttft_ms=round(elapsed / max(len(gen.steps), 1), 2),
            cost_usd=0.0,          # محلی، پس رایگان
            meta={"stop_reason": gen.stop_reason},
        )

"""کارخانهٔ ارائه‌دهنده — بقیهٔ پروژه فقط با این تابع کار دارد."""
from .base import Provider, Message, Completion
from .mock import MockProvider
from .. import config


def get_provider(name: str | None = None) -> Provider:
    """ارائه‌دهندهٔ فعال را برمی‌گرداند.

    اگر ارائه‌دهندهٔ خواسته‌شده در دسترس نباشد، بی‌سروصدا
    به mock برمی‌گردیم تا آموزش هیچ‌وقت متوقف نشود.
    اسم این الگو «تنزل آرام» است و در فصل ۱۰ جدی‌تر سراغش می‌رویم.
    """
    name = (name or config.PROVIDER).lower()

    if name == "local":
        # مدل زبانی واقعی ولی خام فصل ۲ — همیشه در دسترس، چون روی همین دستگاه است
        from .local_lm import LocalLMProvider
        return LocalLMProvider()

    if name == "ollama":
        from .ollama import OllamaProvider
        p = OllamaProvider()
        if p.ping():
            return p
        print("[هشدار] Ollama در دسترس نیست — به mock برگشتم.")

    elif name == "openai":
        if config.OPENAI_KEY:
            from .openai_compat import OpenAIProvider
            return OpenAIProvider()
        print("[هشدار] کلید OpenAI تنظیم نشده — به mock برگشتم.")

    return MockProvider()


__all__ = ["Provider", "Message", "Completion", "MockProvider", "get_provider"]

"""تنظیمات پروژه — تنها جایی که باید برای عوض کردن مدل دست بزنید."""
import os

# گزینه‌ها: mock (آفلاین) | local (مدل خام فصل ۲) | ollama (محلی) | openai (نیازمند کلید)
PROVIDER = os.getenv("ZEHNYAR_PROVIDER", "mock")

OLLAMA_HOST = os.getenv("OLLAMA_HOST", "http://localhost:11434")
OLLAMA_MODEL = os.getenv("OLLAMA_MODEL", "llama3.2:3b")

OPENAI_BASE = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
OPENAI_KEY = os.getenv("OPENAI_API_KEY", "")
OPENAI_MODEL = os.getenv("OPENAI_MODEL", "gpt-4o-mini")

# قیمت تقریبی به ازای هر یک میلیون توکن (دلار) — برای تخمین هزینه
PRICING = {
    "gpt-4o-mini": {"in": 0.15, "out": 0.60},
}

# پارامترهای نمونه‌برداری پیش‌فرض (فصل ۲، درس ۸)
# دمای پایین برای دستیار پرسش‌وپاسخ: ثبات مهم‌تر از خلاقیت است
SAMPLING = {
    "temperature": float(os.getenv("ZEHNYAR_TEMPERATURE", "0.3")),
    "top_p": float(os.getenv("ZEHNYAR_TOP_P", "0.9")),
}

SYSTEM_PROMPT = (
    "تو «ذهن‌یار» هستی، دستیار آموزشی مهندسی هوش مصنوعی. "
    "کوتاه، دقیق و به فارسی ساده جواب بده. "
    "اگر چیزی را نمی‌دانی، صادقانه بگو نمی‌دانم."
)

"""هستهٔ ذهن‌یار. در هر فصل یک لایه به این کلاس اضافه می‌شود.

فصل ۱: فقط یک فراخوانی ساده.
فصل ۲: پارامترهای نمونه‌برداری (دما، top-p) از اینجا به مدل می‌رسند.
فصل ۵: کتابخانهٔ پرامپت نسخه‌دار اینجا وصل می‌شود.
فصل ۶: بازیابی متن مرتبط (RAG) قبل از فراخوانی اضافه می‌شود.
فصل ۱۰: نگهبان، مسیریاب و کش دور همین کلاس پیچیده می‌شوند.
"""
from .. import config
from ..providers import get_provider, Message


class Zehnyar:
    def __init__(self, provider_name: str | None = None):
        self.provider = get_provider(provider_name)
        self.system = config.SYSTEM_PROMPT

    def ask(self, question: str, **params):
        """یک سؤال می‌گیرد و پاسخ کامل به‌همراه سنجه‌ها برمی‌گرداند.

        هر پارامتری که ندهید از config.SAMPLING می‌آید؛ یعنی رفتار پیش‌فرض
        در یک جا تعریف شده و همهٔ ارائه‌دهنده‌ها همان را می‌گیرند.
        """
        messages = [
            Message(role="system", content=self.system),
            Message(role="user", content=question),
        ]
        return self.provider.complete(messages, **{**config.SAMPLING, **params})

    def info(self) -> dict:
        return {"provider": self.provider.name, "model": self.provider.model}

$env:ZEHNYAR_PROVIDER = "local"
.venv\Scripts\python.exe -m projects.ch01_foundation.run