reverse-dictionary/backend/config.py

# ============================================================
# 📄 الملف: config.py
# 🎯 الغرض: الإعدادات المركزية للمشروع (المسارات + تعريف النماذج).
#
# هذا الملف هو "لوحة التحكم" لكل المشروع. أي مسار أو إعداد
# تحتاج تغيّره (مكان البيانات، مكان النموذج المحلي، أسماء النماذج،
# عدد النتائج...) تعدّله من هنا فقط — ولا تلمس باقي الملفات.
#
# القيم الحساسة (مثل مسار النموذج المحلي) تُقرأ من ملف .env
# عشان ما نكتبها داخل الكود مباشرة.
# ============================================================

import os
from pathlib import Path

import torch
from dotenv import load_dotenv

# تحميل متغيّرات البيئة من ملف .env بمساره الصريح (backend/.env)
# نحدّد المسار صراحةً حتى يُقرأ مهما كان مجلد التشغيل (CWD) —
# مثلاً عند تشغيل Streamlit من جذر المشروع.
load_dotenv(Path(__file__).resolve().parent / ".env")

# ------------------------------------------------------------
# 📁 المسارات الأساسية
# ------------------------------------------------------------
# BASE_DIR = جذر المشروع (المجلد اللي يحتوي backend/ و frontend/ و data/)
BASE_DIR = Path(__file__).resolve().parent.parent

DATA_DIR = BASE_DIR / "data"
RAW_DATA_PATH = DATA_DIR / "raw" / "lexicalentries.csv"        # البيانات الخام
PROCESSED_DATA_PATH = DATA_DIR / "processed" / "data.csv"      # البيانات بعد التنظيف
EMBEDDINGS_DIR = DATA_DIR / "embeddings"                        # ملفات .npy
RATINGS_PATH = DATA_DIR / "ratings.csv"                         # سجل التقييمات

# مسار النموذج الثالث المحلي (يُقرأ من .env، وله قيمة افتراضية)
MODEL_3_PATH = os.getenv("MODEL_3_PATH", str(BASE_DIR / "models" / "ksaa_custom"))

# مسار النموذج الرابع المحلي (نسخة أحدث من نموذج المعاجم — للمقارنة)
MODEL_4_PATH = os.getenv("MODEL_4_PATH", str(BASE_DIR / "models" / "ksaa_v2"))

# ------------------------------------------------------------
# 🖥️ الجهاز (GPU إن توفّر، وإلا CPU)
#   - cuda : كروت NVIDIA
#   - mps  : معالج Apple الرسومي (أجهزة Apple Silicon — M1/M2/M3...)
#   - cpu  : الافتراضي
# ------------------------------------------------------------
if torch.cuda.is_available():
    DEVICE = "cuda"
elif torch.backends.mps.is_available():
    DEVICE = "mps"
else:
    DEVICE = "cpu"

# ------------------------------------------------------------
# 🤖 تعريف النماذج الثلاثة
# ------------------------------------------------------------
# كل نموذج له:
#   key          = اسم داخلي قصير (يُستخدم لتسمية ملف الـ embeddings)
#   display_name = الاسم الظاهر للمستخدم في الواجهة
#   hf_id        = معرّف النموذج في HuggingFace أو مسار محلي
#   use_prefix   = هل يحتاج بادئة "query:" / "passage:" (خاص بنماذج e5)
#   top_k        = الحد الأقصى للنتائج (None = بدون حد)
# ------------------------------------------------------------
MODELS = [
    {
        "key": "model_1_microsoft",
        "display_name": "النموذج الأول",
        "hf_id": "intfloat/multilingual-e5-large",
        "use_prefix": True,
        "top_k": 10,
    },
    {
        "key": "model_2_researchers",
        "display_name": "النموذج الثاني",
        "hf_id": "Omartificial-Intelligence-Space/Arabic-Triplet-Matryoshka-V2",
        "use_prefix": False,
        "top_k": None,
    },
    {
        "key": "model_3_ksaa",
        "display_name": "النموذج الثالث",
        "hf_id": MODEL_3_PATH,
        "use_prefix": False,
        "top_k": None,
    },
    {
        "key": "model_4_ksaa_v2",
        "display_name": "النموذج الرابع",
        "hf_id": MODEL_4_PATH,
        "use_prefix": False,
        "top_k": None,
    },
]

# ------------------------------------------------------------
# ⚙️ إعدادات عامة
# ------------------------------------------------------------
DEFAULT_THRESHOLD = 0.70   # حد التشابه الافتراضي
BATCH_SIZE = 64            # حجم الدفعة عند بناء الـ embeddings

# الأعمدة المستخدمة في بناء النص المُدمج للـ embedding
TEXT_COLUMNS = ["lemma", "definition", "example"]


def embedding_path(model_key: str) -> Path:
    """يرجّع مسار ملف الـ embeddings (.npy) الخاص بنموذج معيّن."""
    return EMBEDDINGS_DIR / f"{model_key}.npy"