update2

.gitignore

@@ -225,3 +225,7 @@ __marimo__/
 **/.streamlit/secrets.toml
 # قاعدة بيانات SQLite المحلية للتجربة
 **/data/eval_local.db
+
+# النماذج المُكمَّمة (ONNX) والنسخة الاحتياطية للـ embeddings — كبيرة، تُبنى محليًا
+**/models_onnx/
+**/data/embeddings_backup_fp32/

README.md

@@ -0,0 +1,27 @@
+---
+title: القاموس العكسي للعربية
+emoji: 🔍
+colorFrom: green
+colorTo: gray
+sdk: streamlit
+sdk_version: 1.40.0
+app_file: reverse-dictionary/frontend/streamlit_app.py
+pinned: false
+---
+
+# 🔍 القاموس العكسي للعربية — تقييم البحث الدلالي
+
+تطبيق Streamlit يقارن 3 نماذج Embedding عربية: تُدخل تعريفًا، فتظهر أقرب
+الكلمات في كل نموذج، ويقيّمها المستخدمون (صح/خطأ لكل كلمة)، وتُجمَّع
+التقييمات في قاعدة Supabase.
+
+- النماذج مُكمَّمة (ONNX int8) لتسريع التشغيل وتقليل الذاكرة على CPU.
+- الملفات الكبيرة (النماذج + الـ embeddings) تُنزَّل تلقائيًا من Hugging Face Hub.
+
+## النشر
+راجع [README_STREAMLIT_CLOUD.md](reverse-dictionary/README_STREAMLIT_CLOUD.md)
+و [README_DEPLOY.md](reverse-dictionary/README_DEPLOY.md).
+
+## الأسرار المطلوبة (Space settings → Secrets)
+- `HF_DATA_REPO` — مستودع HF الذي يحوي النماذج والـ embeddings.
+- `DATABASE_URL` — رابط Supabase (Postgres pooler).

requirements.txt

@@ -0,0 +1,15 @@
+# ============================================================
+# 📄 requirements.txt (جذر المستودع) — يقرأه Streamlit Cloud / HF Spaces.
+# نسخة مطابقة لـ reverse-dictionary/backend/requirements.txt
+# ============================================================
+
+streamlit
+python-dotenv
+pandas
+numpy
+scikit-learn
+sentence-transformers
+torch
+sqlalchemy
+psycopg[binary]
+huggingface_hub

reverse-dictionary/README_STREAMLIT_CLOUD.md

@@ -0,0 +1,86 @@
+# 🚀 النشر على Streamlit Community Cloud (مجاني)
+
+التطبيق ينشر برابط عام. الملفات الكبيرة (النماذج + الـ embeddings) تُخزَّن على
+**Hugging Face Hub** (لأن GitHub المجاني يسمح بـ 1GB فقط)، والكود على **GitHub**،
+والتقييمات في **Supabase**.
+
+```
+GitHub (الكود)  →  Streamlit Cloud (يشغّل التطبيق)
+                         │
+                         ├─ ينزّل النماذج/الـ embeddings من  Hugging Face Hub
+                         └─ يحفظ التقييمات في  Supabase
+```
+
+---
+
+## 1) رفع الملفات الكبيرة إلى Hugging Face Hub
+
+1. أنشئي حساب على <https://huggingface.co> (مجاني).
+2. أنشئي **Access Token**: الصورة الشخصية → Settings → Access Tokens → New token
+   (نوع **Write**). انسخيه.
+3. في الطرفية (من مجلد `reverse-dictionary/backend`):
+   ```bash
+   export HF_TOKEN=hf_xxxxxxxx                       # التوكن من الخطوة 2
+   export HF_DATA_REPO="USERNAME/reverse-dictionary-assets"   # بدّلي USERNAME
+   .venv/bin/python scripts/upload_assets.py
+   ```
+4. بعد الرفع: افتحي المستودع على HF → **Settings** → اجعليه **Public**.
+
+> هذا يرفع ~1.7GB مرة واحدة. المستودع العام لا يحتاج توكن عند التنزيل.
+
+---
+
+## 2) إعداد Supabase (لتخزين التقييمات)
+
+اتبعي الخطوات في [README_DEPLOY.md](README_DEPLOY.md) قسم «إعداد Supabase»
+للحصول على `DATABASE_URL` (نوع pooler، يبدأ بـ `postgresql://`).
+
+---
+
+## 3) رفع الكود على GitHub
+
+من جذر المشروع (`semantic-search-system`):
+```bash
+git add -A
+git commit -m "تجهيز للنشر على Streamlit Cloud"
+git branch -M main
+git remote add origin https://github.com/USERNAME/REPO.git   # بدّلي
+git push -u origin main
+```
+> الملفات الكبيرة مُستثناة من Git (في `.gitignore`) — لا تُرفع على GitHub.
+
+---
+
+## 4) النشر على Streamlit Cloud
+
+1. ادخلي <https://share.streamlit.io> وسجّلي دخول بحساب GitHub.
+2. **Create app** → **Deploy a public app from GitHub**.
+3. عبّئي:
+   - **Repository:** مستودعك على GitHub.
+   - **Branch:** `main`.
+   - **Main file path:** `reverse-dictionary/frontend/streamlit_app.py`
+   - **Advanced settings → Python version:** `3.11`
+4. في **Advanced settings → Secrets**، الصقي:
+   ```toml
+   HF_DATA_REPO = "USERNAME/reverse-dictionary-assets"
+   DATABASE_URL = "postgresql://postgres.xxxx:PASSWORD@...pooler.supabase.com:6543/postgres"
+   ```
+5. **Deploy!**
+
+> أول تشغيل بطيء: يثبّت المكتبات ثم ينزّل ~1.7GB من HF Hub. الإقلاعات اللاحقة أسرع.
+
+---
+
+## 5) متابعة التقييمات
+
+من لوحة **Supabase → Table Editor → ratings** تشوفين كل التقييمات وتصدّرينها CSV.
+
+---
+
+## ⚠️ ملاحظات
+- **الذاكرة:** Streamlit Cloud المجاني محدود الذاكرة. خفّفنا الاستهلاك (نماذج
+  مُكمَّمة + `mmap` للـ embeddings). لو ظهر خطأ ذاكرة (الرسالة "Oh no"/إعادة تشغيل
+  متكررة)، الحل الأأمن هو **Hugging Face Spaces** (ذاكرته 16GB) بنفس هذي الملفات.
+- **عند تحديث الكود:** ادفعي على GitHub، و Streamlit Cloud يعيد النشر تلقائيًا.
+- **عند تحديث النماذج/الـ embeddings:** أعيدي تشغيل `upload_assets.py`، ثم
+  أعيدي تشغيل التطبيق من لوحة Streamlit Cloud (Reboot) لإعادة التنزيل.

reverse-dictionary/backend/app/assets.py

@@ -0,0 +1,73 @@
+# ============================================================
+# 📄 الملف: app/assets.py
+# 🎯 الغرض: تنزيل الملفات الكبيرة تلقائيًا عند النشر (Streamlit Cloud).
+#
+# الملفات الكبيرة (النماذج المُكمَّمة + الـ embeddings + البيانات) لا تُرفع
+# على GitHub (تتجاوز حد 1GB). نخزّنها في مستودع Hugging Face Hub عام،
+# والتطبيق ينزّلها أول تشغيل فقط إن لم تكن موجودة محليًا.
+#
+# اسم مستودع Hugging Face يُقرأ من الأسرار: st.secrets["HF_DATA_REPO"]
+# (مثال: "username/reverse-dictionary-assets"). المستودع عام فلا يحتاج توكن.
+#
+# محليًا (الملفات موجودة) لا يحدث أي تنزيل — الدالة ترجع فورًا.
+# ============================================================
+
+import os
+from pathlib import Path
+
+import streamlit as st
+
+import config
+
+# ما الذي نُنزّله (أنماط المسارات داخل مستودع HF):
+#   - data/embeddings/   : المتجهات المحفوظة (.npy)
+#   - data/processed/    : البيانات المنظّفة (data.csv)
+#   - models/ksaa_custom : النموذج الثالث المحلي (الأول والثاني يُنزَّلان تلقائيًا من HF)
+DOWNLOAD_PATTERNS = [
+    "data/embeddings/**",
+    "data/processed/data.csv",
+    "models/ksaa_custom/**",
+]
+
+
+def _repo_id() -> str | None:
+    """اسم مستودع HF الذي يحوي الملفات الكبيرة (من الأسرار أو البيئة)."""
+    try:
+        return st.secrets["HF_DATA_REPO"]
+    except Exception:
+        return os.getenv("HF_DATA_REPO")
+
+
+def assets_ready() -> bool:
+    """هل كل الملفات الكبيرة موجودة محليًا؟"""
+    if not config.PROCESSED_DATA_PATH.exists():
+        return False
+    if not Path(config.MODEL_3_PATH).exists():
+        return False
+    for m in config.MODELS:
+        if not config.embedding_path(m["key"]).exists():
+            return False
+    return True
+
+
+def ensure_assets() -> None:
+    """يُنزّل الملفات الكبيرة من Hugging Face Hub إن لم تكن موجودة."""
+    if assets_ready():
+        return
+
+    repo = _repo_id()
+    if not repo:
+        raise RuntimeError(
+            "الملفات الكبيرة (النماذج/الـ embeddings) غير موجودة، و HF_DATA_REPO "
+            "غير مضبوط في الأسرار. راجع README_STREAMLIT_CLOUD.md."
+        )
+
+    from huggingface_hub import snapshot_download
+
+    # تُنزَّل مباشرة إلى جذر المشروع بنفس البنية (data/، models/...)
+    snapshot_download(
+        repo_id=repo,
+        repo_type="model",
+        local_dir=str(config.BASE_DIR),
+        allow_patterns=DOWNLOAD_PATTERNS,
+    )

reverse-dictionary/backend/app/models_loader.py

@@ -52,7 +52,9 @@ class ResourceManager:
                     f"ملف الـ embeddings غير موجود: {path}\n"
                     "شغّل أولًا: python scripts/build_embeddings.py"
                 )
-            self.embeddings[model_key] = np.load(path)
+            # mmap_mode="r": تبقى المصفوفة على القرص ولا تُحمّل كاملة في
+            # الذاكرة — يوفّر ~مئات الميغابايت (مهم للنشر على ذاكرة محدودة).
+            self.embeddings[model_key] = np.load(path, mmap_mode="r")
         return self.embeddings[model_key]
 
     # --------------------------------------------------------

reverse-dictionary/backend/requirements.txt

@@ -13,3 +13,4 @@ sentence-transformers  # نماذج الـ embedding + Cross-Encoder (reranker)
 torch                # محرّك التعلّم العميق (يأتي مع sentence-transformers)
 sqlalchemy           # التعامل مع قاعدة البيانات (Supabase / SQLite)
 psycopg[binary]      # موصّل Postgres لـ Supabase
+huggingface_hub      # تنزيل الملفات الكبيرة من HF Hub عند النشر

reverse-dictionary/backend/scripts/upload_assets.py

@@ -0,0 +1,61 @@
+# ============================================================
+# 📄 الملف: scripts/upload_assets.py
+# 🎯 الغرض: رفع الملفات الكبيرة إلى مستودع Hugging Face Hub (مرة واحدة).
+#
+# يرفع: data/embeddings/ (المتجهات) + data/processed/data.csv (البيانات)
+#        + models/ksaa_custom/ (النموذج الثالث المحلي).
+# النموذجان الأول والثاني يُنزَّلان تلقائيًا من HuggingFace فلا يُرفعان.
+# بعدها يقدر التطبيق المنشور ينزّل هذي الملفات تلقائيًا.
+#
+# قبل التشغيل:
+#   1) سجّلي دخول HF مرة واحدة:   huggingface-cli login
+#      (أو صدّري التوكن:  export HF_TOKEN=hf_xxx)
+#   2) حدّدي اسم المستودع:        export HF_DATA_REPO="username/repo-name"
+#
+# ثم (من داخل مجلد backend):
+#   python scripts/upload_assets.py
+# ============================================================
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.append(str(Path(__file__).resolve().parent.parent))
+import config
+
+from huggingface_hub import HfApi, create_repo
+
+
+def main():
+    repo = os.getenv("HF_DATA_REPO")
+    if not repo:
+        raise SystemExit("❌ حدّدي المستودع أولًا:  export HF_DATA_REPO=\"username/repo\"")
+
+    print(f"📦 المستودع: {repo}")
+    create_repo(repo, repo_type="model", exist_ok=True)
+    api = HfApi()
+
+    # 1) الـ embeddings
+    print("⏫ رفع data/embeddings/ ...")
+    api.upload_folder(folder_path=str(config.EMBEDDINGS_DIR),
+                      path_in_repo="data/embeddings",
+                      repo_id=repo, repo_type="model")
+
+    # 2) البيانات المنظّفة
+    print("⏫ رفع data/processed/data.csv ...")
+    api.upload_file(path_or_fileobj=str(config.PROCESSED_DATA_PATH),
+                    path_in_repo="data/processed/data.csv",
+                    repo_id=repo, repo_type="model")
+
+    # 3) النموذج الثالث المحلي (ksaa)
+    print("⏫ رفع models/ksaa_custom/ ...")
+    api.upload_folder(folder_path=str(config.MODEL_3_PATH),
+                      path_in_repo="models/ksaa_custom",
+                      repo_id=repo, repo_type="model")
+
+    print(f"✅ تم الرفع. اجعلي المستودع عامًّا (Public) من إعداداته على HF.")
+    print(f"   ثم في أسرار Streamlit Cloud:  HF_DATA_REPO = \"{repo}\"")
+
+
+if __name__ == "__main__":
+    main()

reverse-dictionary/frontend/streamlit_app.py

@@ -31,12 +31,26 @@ import streamlit as st
 import config
 from app.search import search_one_model
 from app import database as db
+from app import assets
 
 # عدد الكلمات المعروضة لكل نموذج
 TOP_N = 5
 
 st.set_page_config(page_title="البحث الدلالي", layout="wide")
 
+
+# ============================================================
+# 📥 تجهيز الملفات الكبيرة (تنزيل من HF Hub أول تشغيل على السحابة)
+#     محليًا: الملفات موجودة فترجع فورًا بلا تنزيل.
+# ============================================================
+@st.cache_resource(show_spinner="⏳ تجهيز النماذج لأول مرة (تنزيل)… قد يأخذ دقائق")
+def _bootstrap_assets():
+    assets.ensure_assets()
+    return True
+
+
+_bootstrap_assets()
+
 # ============================================================
 # 🎨 التصميم — لوحة هادئة: رمادي محايد + نعناعي
 # ============================================================