کلاس SafeEvaluator در فایل core/evaluator.py باید ابزاری باشد که بتواند عبارات ریاضی متنی را بر اساس مجموعه‌ای از متغیرها ارزیابی کرده و مقدار عددی دقیق آن را بازگرداند. ورودی اصلی متد eval یک رشته‌ی بیان ریاضی است، که ممکن است شامل عملگرهایی مثل جمع، تفریق، ضرب، تقسیم، توان، باقی‌مانده، و حتی فراخوانی توابعی مانند sqrt، log، sin یا cos باشد. خروجی آن باید یک عدد (صحیح یا اعشاری) باشد که با دقت مشخصی (مثلاً تا سه رقم اعشار) گرد شده است تا نتایج در تمام اجراها، قطعی و مشخص باقی بمانند. در صورتی که عبارت شامل نام‌های ناشناخته، توابع غیرمجاز یا سینتکس نامعتبر باشد، باید خطای ValueError بازگردانده شود تا از اجرای کد ناامن جلوگیری شود.

همچنین کلاس باید از ثابت‌های ریاضی مثل pi و e پشتیبانی کند تا تست‌هایی که از توابع مثلثاتی یا لگاریتمی استفاده می‌کنند به‌درستی کار کنند. اگر متغیرهایی مانند x، y یا a در عبارت وجود داشته باشند، مقادیر آن‌ها از دیکشنری ورودی گرفته می‌شود تا بتوان عبارات پارامتری را نیز ارزیابی کرد. به‌علاوه، در تست‌هایی که چند عمل ریاضی پشت‌سر‌هم ترکیب شده‌اند، ترتیب تقدم عملگرها و تو در تویی توابع باید حفظ شود تا نتایج عددی دقیقاً با خروجی کتابخانه‌ی math برابر باشند.

متد eval در کلاس SafeEvaluator نقش اصلی را در تبدیل یک رشته‌ی متنی حاوی عبارت ریاضی به مقدار عددی ایفا می‌کند. ورودی این متد یک رشته است که ممکن است شامل اعداد، متغیرها، عملگرهای ریاضی و توابع مجاز مانند sqrt, log, sin باشد و خروجی آن یک مقدار عددی (صحیح یا اعشاری) است که با **دقت مشخص گرد شده است.**همانطور که پیش‌تر گفته شد، این متد باید تمام ترکیب‌های تو در تو و زنجیره‌ای از عملیات ریاضی را به درستی محاسبه کند، به طوری که حتی عبارات پیچیده مثل a + b * c ** 2 - (b + c)/a یا sqrt(abs(log(exp((x + y)**2)))) دقیقاً همان نتیجه‌ای را بدهند که انتظار می‌رود.

علاوه بر این، eval باید به‌طور کامل ایمن باشد و هیچ‌گونه کد اجرایی یا فراخوانی توابع غیرمجاز را اجازه ندهد؛ اگر عبارت شامل نام‌های ناشناخته یا دستورات خطرناک باشد، باید خطای ValueError بدهد. در پیاده‌سازی، این متد با استفاده از تجزیه‌ی AST عمل می‌کند و هر گره‌ی عبارت (مثل عملیات باینری، یونیاری، فراخوانی تابع یا ثابت) را به صورت کنترل‌شده ارزیابی می‌کند تا علاوه بر دقت عددی، امنیت و پیش‌بینی‌پذیری کامل را نیز تضمین کند. همچنین در ترکیب با دیگر بخش‌های باقرآکادمی مانند PlaceholderProcessor و Renderer، متد eval پایه‌ی محاسبات پارامتری و جایگذاری مقادیر در قالب سوالات را تشکیل خواهد داد.

• توجه داشته باشید که در پیاده‌سازی این سوال شما به هیچ عنوان مجاز به استفاده از تابع eval پایتونی نیستید و استفاده از این مورد به صورت خودکار، نمره صفر برای گل پاسخ ارائه شده لحاظ خواهد کرد.

import ast
import operator as op
import math
from typing import Any, Dict, Optional
from utils.config_loader import ConfigLoader

config = ConfigLoader()
decimal_places: Optional[int] = config.get("decimal_places", 3)
enabled_functions = config.get(
    "math_functions",
    [
        "sqrt","sin","cos","tan","asin","acos","atan",
        "log","log10","exp","ceil","floor","abs","round"
    ]
)

OPERATORS = {
    ast.Add: op.add,
    ast.Sub: op.sub,
    ast.Mult: op.mul,
    ast.Div: op.truediv,
    ast.FloorDiv: op.floordiv,
    ast.Mod: op.mod,
    ast.Pow: op.pow,
    ast.USub: op.neg,
    ast.UAdd: op.pos,
}

builtins_dict = __builtins__ if isinstance(__builtins__, dict) else __builtins__.__dict__
SAFE_FUNCTIONS: Dict[str, Any] = {}
for name in enabled_functions:
    if name in ("abs", "round"):
        SAFE_FUNCTIONS[name] = builtins_dict[name]
    else:
        SAFE_FUNCTIONS[name] = getattr(math, name)

CONSTANTS = {"pi": math.pi, "e": math.e}

class SafeEvaluator:
    def __init__(self, vars: Optional[Dict[str, Any]] = None):
        pass

    def eval(self, expression: str) -> Any:
        pass

برای درک نقش SafeEvaluator و متد eval، می‌توان دو مثال زیر را در نظر گرفت. در مثال اول، یک عبارت تو در تو از توابع ریاضی با استفاده ازsqrt, abs, log, exp داریم:

ev = SafeEvaluator(vars={'x': 2, 'y': 3})
expr = 'sqrt(abs(log(exp((x + y) ** 2))))'
result = ev.eval(expr)

# sqrt((2 + 3) ** 2) = 5

• در اینجا، eval باید توانایی پردازش دقیق عملیات تو در تو را داشته باشد و مقادیر متغیرها (x=2, y=3) را جایگذاری کند. ترتیب اعمال تابع‌ها و عملیات ریاضی رعایت می‌شود تا نتیجه‌ی نهایی با مقدار مورد انتظار مطابق باشد.

در مثال دوم، یک عبارت ترکیبی از عملگرهای مختلف داریم که شامل جمع، ضرب، توان، تفریق و تقسیم است:

ev = SafeEvaluator(vars={'a': 2, 'b': 3, 'c': 4})
expr = 'a + b * c ** 2 - (b + c) / a'
result = ev.eval(expr)

# 2 + 3 * 4**2 - (3 + 4)/2 = 46.5

• در اینجا متد eval باید تقدم عملگرها را رعایت کند و محاسبات ترکیبی را به دقت انجام دهد. این مثال نشان می‌دهد که SafeEvaluator باید قادر باشد تا عبارات پیچیده‌ی عددی را به‌درستی محاسبه کند.

کلاس PlaceholderProcessor برای پردازش متن‌هایی طراحی شده است که شامل placeholderهای محاسباتی به شکل {{ ... }} هستند و هدف آن جایگذاری مقادیر محاسبه‌شده به‌طور در متن است. این کلاس هنگام ساخت، یک SafeEvaluator دریافت می‌کند تا هر بار که نیاز به محاسبه‌ی عبارت‌ها باشد، یک نمونه امن و مستقل ایجاد شود و هیچ تداخل یا تغییر ناخواسته‌ای در مقادیر رخ ندهد.

متد process متن ورودی را بررسی می‌کند و تمام بخش‌هایی که با الگوی {{...}} هم‌خوانی دارند را استخراج می‌کند. سپس برای هر placeholder، متغیرهای داده‌شده را جایگذاری کرده و عبارت را با استفاده از SafeEvaluator.eval محاسبه می‌کند. اگر هنگام محاسبات ریاضی، خطایی رخ دهد یا عبارت شامل متغیر یا تابع ناشناخته باشد، کلاس به صورت امن placeholder را بدون تغییر باقی می‌گذارد و از ایجاد خطا جلوگیری می‌کند. در نهایت، متن خروجی شامل همه‌ی placeholderهای جایگزین‌شده با مقادیر محاسبه‌شده است.

from .evaluator import SafeEvaluator

class PlaceholderProcessor:
    def __init__(self, evaluator_factory):
        pass

    def process(self, text: str, vars: Dict[str, float]) -> str:
        pass

• تابع process از کلاس PlaceholderProcessor مسئول پردازش متن‌هایی است که شامل placeholder یا عبارت‌های محاسباتی در قالب {{ ... }} هستند و با مقادیر متغیرها جایگذاری می‌شوند.

به‌عنوان مثال، اگر متن به شکل زیر باشد:

pp = PlaceholderProcessor(lambda: SafeEvaluator(vars={}))
text = "Sum = {{x + y}}"
result = pp.process(text, {'x': 2, 'y': 3})
# result باید برابر با "Sum = 5" باشد

• در این حالت، process ** حاصل عبارت داخل** {{x + y}} را پیدا می‌کند، مقادیر متغیرها (x=2, y=3) را جایگذاری می‌کند و با استفاده از SafeEvaluator.eval محاسبه می‌کند. نتیجه‌ی عددی به رشته تبدیل شده و در متن اصلی جایگزین می‌شود.

مثال دیگر که شامل توابع ریاضی و ترکیب‌ها است:

text = "Value={{ sqrt(x**2 + y**2) + log(z) }}"
result = pp.process(text, {'x': 3, 'y': 4, 'z': math.e})
# result باید برابر با "Value=6.0" باشد

• در اینجا process قادر است عبارات پیچیده و تو در تو را پردازش کند و مقادیر دقیق را جایگزین کند. اگر هرگونه خطا یا عبارت غیرقابل ارزیابی وجود داشته باشد، متن اصلی بدون تغییر حفظ می‌شود، یعنی placeholder باقی می‌ماند.

به طور خلاصه، PlaceholderProcessor پل بین داده‌های متغیر و مانفیست سوال شده است و تضمین می‌کند که همه‌ی placeholderها با مقادیر محاسبه‌شده جایگزین شوند.

کلاس Renderer مسئول تبدیل یک سوال با قالب متنی و مقادیر متغیرها به یک خروجی آماده است که شامل متن سوال، گزینه‌ها و پاسخ محاسبه‌شده می‌شود و هدف آن این است که تمام placeholderها به صورت با مقادیر مناسب جایگزین شوند. هنگام مقداردهی اولیه، Renderer یک نمونه از PlaceholderProcessor به همراه نمونه‌ی SafeEvaluator ایجاد می‌کند تا تمام پردازش‌های ریاضی و جایگذاری‌ها به صورت امن و قابل پیش‌بینی انجام شوند و هیچ تغییر ناخواسته‌ای روی مقادیر متغیرها رخ ندهد.

متد render ابتدا متن اصلی سوال یا stem را پردازش می‌کند و تمامی placeholderها را با مقادیر محاسبه‌شده جایگزین می‌کند. سپس اگر سوال شامل گزینه‌ها باشد، هر گزینه نیز با همان مقادیر متغیرها پردازش می‌شود تا تمامی توابع و عبارات ریاضی داخل گزینه‌ها به شکل صحیح جایگزین شوند. در نهایت، اگر سوال شامل پاسخ باشد، render آن را پردازش می‌کند و تلاش می‌کند تا مقادیر عددی را با تعداد رقم‌های اعشاری مشخص‌شده و واحد مناسب نمایش دهد. اگر مقدار قابل تبدیل به عدد نباشد، به همان شکل متنی نمایش داده می‌شود و هیچ خطایی ایجاد نمی‌شود.

from typing import Dict
from .placeholder import PlaceholderProcessor
from .evaluator import SafeEvaluator
from utils.config_loader import ConfigLoader

config = ConfigLoader()
DECIMAL_PLACES = config.get("decimal_places", 3)
DEFAULT_UNITS = config.get("default_units", {})

class Renderer:
    def __init__(self):
        pass

    def render(self, question, vars: Dict[str, float]) -> Dict[str, str]:
        pass

کلاس Renderer مسئول تبدیل یک سوال با مانیفست‌های دارای placeholder و مقادیر متغیر به خروجی نهایی است که شامل stem، گزینه‌ها و پاسخ پردازش‌شده می‌شود و تمامی placeholderها را با مقادیر واقعی جایگزین می‌کند. به عبارت دیگر، این کلاس متن خام سوال و گزینه‌ها را دریافت کرده و با استفاده از PlaceholderProcessor و SafeEvaluator مقادیر متغیرها و محاسبات ریاضی داخل placeholderها را محاسبه و در متن جایگذاری می‌کند.

به‌عنوان مثال، اگر یک سوال داشته باشیم با stem "Compute {{x}} + {{y}}" و گزینه‌های ["Sum={{x+y}}", "Double={{x*2}}"] و مقادیر متغیرهای {'x': 3, 'y': 5}، فراخوانی Renderer().render(question, {'x': 3, 'y': 5}) خروجی زیر را تولید می‌کند:

{
    "stem": "Compute 3 + 5",
    "options": ["Sum=8", "Double=6"]
}

• در این مثال، تمامی placeholderها با مقادیر محاسبه‌شده جایگزین شده‌اند و بدنه سوال جدید به شکل درست ارائه شده است. همچنین، اگر سوال دارای پاسخ عددی یا متنی باشد، Renderer پاسخ را با تعداد رقم‌های اعشار مشخص‌شده و واحد مناسب قالب‌بندی می‌کند. اگر پاسخ یک عبارت غیرقابل تبدیل به عدد باشد، به همان صورت رشته‌ای باقی می‌ماند.

کلاس VariableResolver مسئول مدیریت و تولید مقادیر تصادفی برای متغیرها در محدوده‌های تعریف شده است و به گونه‌ای طراحی شده که خروجی‌ها دترمنیستیک (Deterministic) باشند زمانی که یک seed مشخص یا seed سراسری در پیکربندی تعریف شده باشد. این کلاس، مقادیر پیش‌فرض بارگذاری شده از فایل پیکربندی را با محدوده‌های ارائه شده توسط کاربر ترکیب می‌کند و برای هر متغیر یک مقدار تصادفی تولید می‌کند که در بازه مشخص شده قرار دارد. این طراحی اجازه می‌دهد که مقادیر تولید شده به صورت قابل پیش‌بینی و هماهنگ با نیازها و اجرای برنامه باشند، حتی وقتی محدوده‌های متغیرها متنوع یا زیاد باشند.

متد resolve قابلیت تنظیم seed محلی برای تولید مقادیر قابل تکرار را دارد و این قابلیت باعث می‌شود هر بار که همان seed استفاده شود، خروجی‌های تولید شده دقیقاً یکسان باشند. اگر seed محلی مشخص نشده باشد، کلاس به طور خودکار از seed سراسری تعریف شده در پیکربندی استفاده می‌کند تا همچنان دترمنیستیک بودن حفظ شود.

در هنگام تولید مقادیر، هر مقدار با استفاده از round و تعداد رقم‌های اعشار مشخص شده در پیکربندی گرد می‌شود تا دقت عددی و قالب‌بندی عدد حفظ شود. این مسئله برای اطمینان از اینکه مقادیر تولید شده در محاسبات بعدی با دقت معین استفاده شوند بسیار مهم است و باعث می‌شود نتایج محاسباتی در تست‌ها یا رندرینگ سوالات دقیق و یکسان باقی بمانند. به عنوان مثال، اگر محدوده متغیرها به شکل {'x': (1, 5), 'y': (10, 20)} باشد و seed برابر با 42 تنظیم شود، فراخوانی VariableResolver({'x': (1,5), 'y':(10,20)}).resolve(seed=42) مقدار مشخص و تکرارپذیر مثل {'x': 3.14, 'y': 16.27} تولید می‌کند و هر بار با همان seed، همان مقادیر بازمی‌گردند.

import random
from typing import Dict, Any, Optional, Tuple
from utils.config_loader import ConfigLoader

config = ConfigLoader()
GLOBAL_SEED = config.get("random_seed", None)
DECIMAL_PLACES = config.get("decimal_places", 3)
CONFIG_RANGES = config.get("variable_ranges", {})

class VariableResolver:
    def __init__(self, ranges: Optional[Dict[str, Tuple[float, float]]] = None):
        pass

    def resolve(self, seed: Optional[int] = None) -> Dict[str, Any]:
        pass

• به‌عنوان مثال، فرض کنید یک سوال با stem و گزینه‌ها داریم که شامل placeholderهای ریاضی است:

class DummyQuestion:
    stem = "Compute {{x}} + {{y}}"
    options = ["Sum={{x+y}}", "Double={{x*2}}"]

r = Renderer()
rendered = r.render(DummyQuestion(), {'x': 2, 'y': 3})
# rendered['stem'] باید برابر "Compute 2 + 3" باشد
# rendered['options'] باید برابر ["Sum=5", "Double=4"] باشد

+‌ در این مثال، Renderer ابتدا placeholderهای stem را پردازش می‌کند و مقادیر x و y را جایگزین می‌کند. سپس گزینه‌ها را پردازش می‌کند، به طوری که محاسبات داخلی هر گزینه (x+y و x*2) انجام شده و خروجی نهایی جایگزین متن placeholder می‌شود. اگر پاسخ نهایی دارای واحد یا نیاز به گرد کردن باشد، کلاس به‌طور خودکار آن را مدیریت می‌کند.

به طور خلاصه، Renderer مسئول یکپارچه‌سازی و پردازش تمام متون و داده‌های سوال است، به طوری که خروجی دترمنیستیک، دقیق و آماده استفاده در نمایش یا ارزیابی باشد.