update

reverse-dictionary/backend/app/ratings.py

@@ -1,124 +0,0 @@
-# ============================================================
-# 📄 الملف: app/ratings.py
-# 🎯 الغرض: إدارة سجل التقييمات (حفظ / قراءة / حذف / إحصاء).
-#
-# كل تقييم يُحفظ كصف في ملف CSV (ratings.csv) بترميز utf-8-sig
-# عشان العربية تظهر صح في Excel. هذا الملف يوفّر كل العمليات
-# على السجل: إضافة تقييم، جلب السجل كامل، حذف صفوف محدّدة،
-# حذف الكل، وحساب ملخّص أداء النماذج.
-# ============================================================
-
-import os
-from datetime import datetime
-
-import pandas as pd
-
-import config
-
-# أسماء الأعمدة في ملف التقييمات
-COLUMNS = ["التاريخ والوقت", "الاستعلام", "النموذج", "التقييم",
-           "Threshold", "أفضل كلمة", "أعلى تشابه"]
-REQUIRED = ["التاريخ والوقت", "الاستعلام", "النموذج", "التقييم"]
-
-
-# ------------------------------------------------------------
-# 💾 حفظ تقييم جديد (إضافة صف للملف)
-# ------------------------------------------------------------
-def save_rating(query, model_display_name, rating, threshold,
-                top_lemma=None, top_score=None) -> None:
-    row = {
-        "التاريخ والوقت": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
-        "الاستعلام": query,
-        "النموذج": model_display_name,
-        "التقييم": rating,
-        "Threshold": threshold,
-        "أفضل كلمة": top_lemma or "",
-        "أعلى تشابه": round(top_score, 3) if top_score else "",
-    }
-    write_header = not config.RATINGS_PATH.exists()
-    pd.DataFrame([row]).to_csv(
-        config.RATINGS_PATH, mode="a", header=write_header,
-        index=False, encoding="utf-8-sig",
-    )
-
-
-# ------------------------------------------------------------
-# 📖 قراءة كل التقييمات (مع تنظيف الملف التالف تلقائيًا)
-# ------------------------------------------------------------
-def load_ratings() -> pd.DataFrame:
-    if not config.RATINGS_PATH.exists():
-        return pd.DataFrame(columns=COLUMNS)
-    try:
-        df = pd.read_csv(config.RATINGS_PATH, encoding="utf-8-sig")
-        # لو الملف ناقص أعمدة أساسية نعتبره تالفًا ونحذفه
-        if not all(c in df.columns for c in REQUIRED):
-            config.RATINGS_PATH.unlink()
-            return pd.DataFrame(columns=COLUMNS)
-        return df
-    except Exception:
-        config.RATINGS_PATH.unlink()
-        return pd.DataFrame(columns=COLUMNS)
-
-
-# ------------------------------------------------------------
-# 🗑️ حذف تقييمات محدّدة (حسب مفاتيح: التاريخ + الاستعلام + النموذج)
-# ------------------------------------------------------------
-def delete_ratings(keys: list[dict]) -> int:
-    """keys = [{datetime, query, model}, ...]. يرجّع عدد الصفوف المحذوفة."""
-    df = load_ratings()
-    if df.empty:
-        return 0
-
-    key_tuples = {(k["datetime"], k["query"], k["model"]) for k in keys}
-    mask = df[["التاريخ والوقت", "الاستعلام", "النموذج"]].apply(tuple, axis=1).isin(key_tuples)
-    deleted_count = int(mask.sum())
-
-    remaining = df[~mask]
-    if len(remaining) > 0:
-        remaining.to_csv(config.RATINGS_PATH, index=False, encoding="utf-8-sig")
-    elif config.RATINGS_PATH.exists():
-        config.RATINGS_PATH.unlink()
-    return deleted_count
-
-
-# ------------------------------------------------------------
-# ⚠️ حذف كل التقييمات
-# ------------------------------------------------------------
-def delete_all_ratings() -> None:
-    if config.RATINGS_PATH.exists():
-        config.RATINGS_PATH.unlink()
-
-
-# ------------------------------------------------------------
-# 📊 ملخّص أداء النماذج + إحصاءات عامة
-# ------------------------------------------------------------
-def get_summary() -> dict:
-    df = load_ratings()
-    if df.empty:
-        return {"stats": {}, "performance": []}
-
-    # إحصاءات عامة
-    stats = {
-        "total": len(df),
-        "ممتاز": int((df["التقييم"] == "ممتاز").sum()),
-        "جيد": int((df["التقييم"] == "جيد").sum()),
-        "ضعيف": int((df["التقييم"] == "ضعيف").sum()),
-    }
-
-    # أداء كل نموذج
-    performance = []
-    for model_name, group in df.groupby("النموذج"):
-        excellent = int((group["التقييم"] == "ممتاز").sum())
-        good = int((group["التقييم"] == "جيد").sum())
-        weak = int((group["التقييم"] == "ضعيف").sum())
-        total = excellent + good + weak
-        performance.append({
-            "model": model_name,
-            "ممتاز": excellent,
-            "جيد": good,
-            "ضعيف": weak,
-            "الإجمالي": total,
-            "نسبة الممتاز": round(excellent / total * 100, 1) if total else 0.0,
-        })
-
-    return {"stats": stats, "performance": performance}

reverse-dictionary/backend/app/routes.py

@@ -1,96 +0,0 @@
-# ============================================================
-# 📄 الملف: app/routes.py
-# 🎯 الغرض: تعريف نقاط النهاية (Endpoints) للـ API.
-#
-# هذا الملف يربط بين طلبات HTTP القادمة من الـ frontend
-# ومنطق المشروع (البحث، التقييمات). كل دالة هنا تمثّل
-# "عنوانًا" يستدعيه الـ frontend:
-#
-#   GET    /api/models          → قائمة النماذج
-#   POST   /api/search          → تنفيذ بحث
-#   GET    /api/ratings         → جلب كل التقييمات + الملخّص
-#   POST   /api/ratings         → حفظ تقييم
-#   POST   /api/ratings/delete  → حذف تقييمات محدّدة
-#   DELETE /api/ratings         → حذف كل التقييمات
-# ============================================================
-
-from fastapi import APIRouter
-
-import config
-from app import ratings as ratings_service
-from app.search import search_all_models
-from app.schemas import (
-    DeleteRatingsRequest,
-    ModelInfo,
-    RatingRequest,
-    SearchRequest,
-    SearchResponse,
-)
-
-router = APIRouter(prefix="/api")
-
-
-# ------------------------------------------------------------
-# 🤖 قائمة النماذج
-# ------------------------------------------------------------
-@router.get("/models", response_model=list[ModelInfo])
-def get_models():
-    return [
-        ModelInfo(model_index=i, model_key=m["key"], display_name=m["display_name"])
-        for i, m in enumerate(config.MODELS)
-    ]
-
-
-# ------------------------------------------------------------
-# 🔎 البحث
-# ------------------------------------------------------------
-@router.post("/search", response_model=SearchResponse)
-def search(request: SearchRequest):
-    results = search_all_models(request.query.strip(), request.threshold,
-                                rerank=request.rerank)
-    return SearchResponse(
-        query=request.query,
-        threshold=request.threshold,
-        results=results,
-    )
-
-
-# ------------------------------------------------------------
-# ⭐ التقييمات
-# ------------------------------------------------------------
-@router.get("/ratings")
-def get_ratings():
-    df = ratings_service.load_ratings()
-    summary = ratings_service.get_summary()
-    return {
-        "ratings": df.to_dict(orient="records"),
-        "stats": summary["stats"],
-        "performance": summary["performance"],
-    }
-
-
-@router.post("/ratings")
-def add_rating(request: RatingRequest):
-    ratings_service.save_rating(
-        query=request.query,
-        model_display_name=request.model_display_name,
-        rating=request.rating,
-        threshold=request.threshold,
-        top_lemma=request.top_lemma,
-        top_score=request.top_score,
-    )
-    return {"status": "ok", "message": "تم حفظ التقييم"}
-
-
-@router.post("/ratings/delete")
-def delete_selected(request: DeleteRatingsRequest):
-    keys = [{"datetime": k.datetime, "query": k.query, "model": k.model}
-            for k in request.keys]
-    count = ratings_service.delete_ratings(keys)
-    return {"status": "ok", "deleted": count}
-
-
-@router.delete("/ratings")
-def delete_all():
-    ratings_service.delete_all_ratings()
-    return {"status": "ok", "message": "تم حذف جميع التقييمات"}

reverse-dictionary/backend/app/schemas.py

@@ -1,84 +0,0 @@
-# ============================================================
-# 📄 الملف: app/schemas.py
-# 🎯 الغرض: تعريف أشكال البيانات (Schemas) الداخلة والخارجة من الـ API.
-#
-# نستخدم Pydantic عشان:
-#   1. التحقّق التلقائي من صحة البيانات القادمة من الـ frontend.
-#   2. توليد توثيق تلقائي للـ API (صفحة /docs).
-#   3. توضيح "العقد" بين الواجهة والخادم: وش يرسل ووش يستقبل.
-# ============================================================
-
-from typing import List, Optional
-
-from pydantic import BaseModel, Field
-
-
-# ------------------------------------------------------------
-# 🔎 طلبات واستجابات البحث
-# ------------------------------------------------------------
-class SearchRequest(BaseModel):
-    """طلب البحث القادم من الواجهة."""
-    query: str = Field(..., description="التعريف أو النص المُراد البحث عنه")
-    threshold: float = Field(0.70, ge=0.0, le=1.0, description="حد التشابه الأدنى")
-    rerank: bool = Field(False, description="تفعيل إعادة الترتيب بالـ Cross-Encoder")
-
-
-class ResultItem(BaseModel):
-    """نتيجة واحدة (كلمة) داخل قائمة نتائج نموذج."""
-    lemma: str
-    definition: str
-    example: str = ""
-    pos: str = ""
-    score: float
-
-
-class ModelResult(BaseModel):
-    """نتائج نموذج واحد كاملة."""
-    model_index: int
-    model_key: str
-    display_name: str
-    items: List[ResultItem]
-    top_lemma: Optional[str] = None
-    top_score: Optional[float] = None
-
-
-class SearchResponse(BaseModel):
-    """الاستجابة الكاملة للبحث (نتائج النماذج الثلاثة)."""
-    query: str
-    threshold: float
-    results: List[ModelResult]
-
-
-# ------------------------------------------------------------
-# ⭐ طلبات واستجابات التقييمات
-# ------------------------------------------------------------
-class RatingRequest(BaseModel):
-    """طلب حفظ تقييم لنتيجة نموذج."""
-    query: str
-    model_display_name: str
-    rating: str = Field(..., description="ممتاز | جيد | ضعيف")
-    threshold: float
-    top_lemma: Optional[str] = ""
-    top_score: Optional[float] = None
-
-
-class RatingKey(BaseModel):
-    """مفتاح يُعرّف صف تقييم بشكل فريد (للحذف)."""
-    datetime: str
-    query: str
-    model: str
-
-
-class DeleteRatingsRequest(BaseModel):
-    """طلب حذف مجموعة تقييمات محدّدة."""
-    keys: List[RatingKey]
-
-
-# ------------------------------------------------------------
-# 🤖 معلومات النماذج
-# ------------------------------------------------------------
-class ModelInfo(BaseModel):
-    """معلومات نموذج تُعرض للواجهة (بدون كشف المسارات الداخلية)."""
-    model_index: int
-    model_key: str
-    display_name: str

reverse-dictionary/backend/main.py

@@ -1,66 +0,0 @@
-# ============================================================
-# 📄 الملف: main.py
-# 🎯 الغرض: نقطة تشغيل الخادم (Backend) — تطبيق FastAPI.
-#
-# هذا هو الملف اللي تشغّله لرفع الـ backend. مسؤوليّاته:
-#   1. إنشاء تطبيق FastAPI.
-#   2. تفعيل CORS (يسمح للـ frontend باستدعاء الـ API).
-#   3. ربط نقاط النهاية (من app/routes.py).
-#   4. تحميل النماذج مسبقًا عند الإقلاع (warmup).
-#
-# طريقة التشغيل:
-#   cd backend
-#   uvicorn main:app --reload --port 8000
-#
-# توثيق الـ API يكون تلقائيًا على:  http://localhost:8000/docs
-# ============================================================
-
-from contextlib import asynccontextmanager
-
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-
-from app.models_loader import resources
-from app.routes import router
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """يُنفَّذ مرة عند إقلاع الخادم: تحميل النماذج والبيانات مسبقًا."""
-    print("🔥 تسخين الموارد (تحميل النماذج والـ embeddings)...")
-    try:
-        resources.warmup()
-        print("✅ الموارد جاهزة")
-    except FileNotFoundError as e:
-        # لا نوقف الخادم؛ فقط ننبّه المطوّر أن البيانات ناقصة
-        print(f"⚠️ تحذير: {e}")
-    yield
-    print("👋 إيقاف الخادم")
-
-
-app = FastAPI(
-    title="القاموس العكسي للعربية — API",
-    description="واجهة برمجية لمقارنة 3 نماذج Embedding في البحث الدلالي العربي",
-    version="1.0.0",
-    lifespan=lifespan,
-)
-
-# ------------------------------------------------------------
-# 🌐 CORS: نسمح للواجهة (تعمل على منفذ مختلف) باستدعاء الـ API
-# ملاحظة: في الإنتاج، حدّد النطاقات المسموحة بدل "*"
-# ------------------------------------------------------------
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# ربط نقاط النهاية
-app.include_router(router)
-
-
-@app.get("/")
-def root():
-    """نقطة فحص بسيطة للتأكّد أن الخادم يعمل."""
-    return {"status": "ok", "message": "الخادم يعمل ✅ — التوثيق على /docs"}

reverse-dictionary/backend/requirements.txt

@@ -1,16 +1,13 @@
 # ============================================================
 # 📄 الملف: requirements.txt
-# 🎯 الغرض: قائمة مكتبات بايثون اللازمة لتشغيل الـ backend.
+# 🎯 الغرض: قائمة مكتبات بايثون اللازمة لتشغيل المشروع (Streamlit).
 # التثبيت:  pip install -r requirements.txt
 # ============================================================
 
-fastapi              # إطار عمل الـ API
-uvicorn[standard]    # خادم تشغيل FastAPI
-pydantic             # التحقّق من البيانات
+streamlit            # الواجهة (frontend/streamlit_app.py)
 python-dotenv        # قراءة ملف .env
 pandas               # معالجة البيانات
 numpy                # العمليات الرقمية
 scikit-learn         # حساب تشابه الجيب التمام (cosine)
-sentence-transformers  # نماذج الـ embedding
+sentence-transformers  # نماذج الـ embedding + Cross-Encoder (reranker)
 torch                # محرّك التعلّم العميق (يأتي مع sentence-transformers)
-streamlit            # واجهة Streamlit (frontend/streamlit_app.py)

reverse-dictionary/frontend/streamlit_app.py

@@ -146,11 +146,12 @@ def cached_search(query: str, model_key: str, rerank: bool):
 # ============================================================
 # 🖥️ الواجهة
 # ============================================================
-st.markdown("<h2 style='text-align:center;'>🔍 البحث الدلالي</h2>",
+st.markdown("<h2 style='text-align:center;'>🔍 تقييم البحث الدلالي</h2>",
             unsafe_allow_html=True)
 st.markdown(
     "<p style='text-align:center; color:#78909C;'>"
-    "اكتب تعريفًا، وأشّر ☑️ الكلمات المناسبة في كل نموذج، ثم احفظ التقييم."
+    "ساهِم في تقييم النماذج: اكتب تعريفًا، واطّلع على النتائج المقترحة من كل "
+    "نموذج، ثم اختر التقييم الأنسب لكل نموذج."
     "</p>", unsafe_allow_html=True)
 
 # زر بحث على اليسار + شريط الإدخال على اليمين