DEPLOY_GUIDE.md

# 🚀 دليل النشر على Hugging Face Spaces

## المتطلبات
- حساب على [Hugging Face](https://huggingface.co/) (مجاني)
- [Git](https://git-scm.com/) مثبّت على جهازك

---

## الخطوات

### 1. إنشاء Space جديد

1. اذهب إلى: https://huggingface.co/new-space
2. **Space name**: `murshid`
3. **SDK**: اختر **Docker**
4. **Visibility**: Public (مجاني) أو Private
5. اضغط **Create Space**

### 2. رفع المشروع

```powershell
cd d:\murishd

# تهيئة Git (إذا لم يكن موجوداً)
git init

# إضافة الـ remote (غيّر YOUR_USERNAME باسم حسابك)
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/murshid

# إضافة الملفات والرفع
git add .
git commit -m "Initial deployment"
git push space main
```

> ⚠️ إذا طلب كلمة مرور، استخدم **Access Token** من:
> https://huggingface.co/settings/tokens

### 3. إعداد المتغيرات البيئية (Secrets)

اذهب إلى إعدادات الـ Space: `Settings → Variables and secrets`

أضف هذه المتغيرات:

| الاسم | القيمة | النوع |
|-------|--------|-------|
| `MURSHID_DB_URL` | `sqlite:////app/data/murshid.db` | Variable |
| `MURSHID_MODELS_DIR` | `/app/Needed` | Variable |
| `MURSHID_SKIP_LLM` | `true` | Variable |
| `SECRET_KEY` | (اختر كلمة سر عشوائية) | **Secret** |
| `HF_TOKEN` | (اختياري — لو تبغى Llama) | **Secret** |

### 4. انتظر البناء

- HF Spaces يبني الـ Docker image تلقائياً
- يأخذ **3-5 دقائق** للبناء الأول
- بعد النجاح، الرابط يكون:
  ```
  https://YOUR_USERNAME-murshid.hf.space
  ```

---

## الروابط بعد النشر

| الرابط | الوصف |
|--------|-------|
| `https://YOUR_USERNAME-murshid.hf.space` | الواجهة الرئيسية |
| `https://YOUR_USERNAME-murshid.hf.space/docs` | توثيق Swagger |
| `https://YOUR_USERNAME-murshid.hf.space/health` | فحص الحالة |

---

## ملاحظات

### الوضع الحالي (LITE mode)
- المشروع ينشر بوضع **LITE** (بدون torch/SecureBERT+)
- تحليل القواعد يعمل لكن بدقة أقل (embeddings عشوائية)
- مناسب لاختبار الواجهة والـ API

### للترقية إلى LOCAL mode (SecureBERT+ بدون Llama)
عدّل `Dockerfile` وأزل التعليق من سطر torch:
```dockerfile
RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu transformers sentencepiece
```
> ⚠️ هذا يزيد حجم الصورة ~800MB ويحتاج ذاكرة أكثر

### للترقية إلى FULL mode (مع Llama 3)
- غيّر الـ Space إلى **GPU (T4)** من الإعدادات ($0.60/ساعة)
- عدّل `MURSHID_SKIP_LLM=false`
- أضف `HF_TOKEN` في الـ Secrets
- استخدم `requirements.txt` الكامل بدل `requirements_light.txt`

---

## استكشاف الأخطاء

| المشكلة | الحل |
|---------|------|
| Build فشل | تحقق من الـ Logs في تبويب الـ Space |
| 502 Bad Gateway | انتظر دقيقة — الخادم يبدأ |
| DB خطأ | تحقق من `MURSHID_DB_URL` في المتغيرات |
| Frontend لا يتصل | الـ BASE URL أصبح تلقائي (`window.location.origin`) |