README.md

---
title: HR Genie RAG API
emoji: "🤖"
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# HR Genie RAG API for Hugging Face Spaces

دي نسخة API من RAG Assistant عشان ترفعها على Hugging Face Space وتستخدمها من Laravel.

## 1) Create Space

1. ادخل Hugging Face > New Space.
2. اختار SDK = `Docker`.
3. خلّي visibility حسب احتياجك (`Public` أو `Private`).
4. ارفع محتويات الفولدر ده نفسه كجذر الـ Space repo:
   `README.md`, `Dockerfile`, `requirements.txt`, `app.py`.

## 2) Add Space Secrets

من Settings > Variables and secrets:

- `OPENROUTER_API_KEY` = OpenRouter key
- `OPENROUTER_MODEL` = `deepseek/deepseek-chat-v3-0324` (اختياري)
- `KNOWLEDGE_URL` (اختياري)
- `FAQ_URL` (اختياري)

## 3) API Endpoints

### Health

`GET /health`

### Chat

`POST /chat`

Request JSON:

```json
{
  "message": "متى يتم صرف الراتب؟",
  "session_id": "chat-123",
  "user_id": 10
}
```

Response JSON:

```json
{
  "answer": "...",
  "mode": "rag",
  "sources": [
    {
      "title": "...",
      "source_file": "...",
      "score": 0.81
    }
  ],
  "latency_ms": 1420
}
```

## 4) Connect from Laravel

في مشروع Laravel:

- `HR_GENIE_RAG_API_URL=https://<username>-<space-name>.hf.space`
- `HR_GENIE_RAG_API_TOKEN=` (لو Space private، حط HF token هنا)
- `HR_GENIE_RAG_API_TIMEOUT=45`

وبعدين:

```bash
php artisan config:clear
php artisan cache:clear
```

## 5) Notes

- أول تشغيل بياخد وقت بسبب تحميل الموديلات.
- لو الذاكرة محدودة في Space، ممكن تقلل التعقيد (مثلا BM25 only) أو ترفع hardware plan.