bayan-proxy: README.md

README.md

@@ -1,10 +1,91 @@
 ---
-title: Bayan Proxy
-emoji: 🐨
-colorFrom: red
-colorTo: blue
+title: Muaalem Proxy
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# وسيط «بيان» — Muaalem Proxy
+
+المصدر الرسميّ لِـHF Space `hatimqman-muaalem-proxy`. كان يعيش صندوقًا أسود على HF فقط؛
+هذا مصدره الحقيقيّ داخل المستودع (`Quran_Rateel/hf-endpoint/proxy/`).
+
+يجلس بين عميل **بيان** المنشور على Cloudflare Pages وبين ثلاث نقاط HF Inference، فيؤدّي:
+
+- **يحمل توكن HF سرًّا** (من متغيّر البيئة `HF_TOKEN`) ويحقنه في نداء النقطة — لا يصل التوكن للعميل أبدًا.
+- **يتجاوز حجب Cloudflare 1010**: العميل ينادي هذا الـSpace، والـSpace ينادي خادم HF.
+- **فان-آوت** لثلاث نقاط علويّة عبر ثلاثة مسارات.
+- **يقبل جسمًا مسطّحًا** ويغلّفه `{ "inputs": { … } }` قبل تمريره للنقطة، فيبقى `STT_URL` و`MUAALEM_URL`
+  في `bayan/web/app.js` بلا تغيير عنوان.
+- **CORS** لنطاق Pages، **حدّ معدّل** لكلّ IP، **إعادة محاولة** على البدء البارد (scale-to-zero)،
+  و**تدهورٌ آمن**: أيّ فشلٍ للنقطة يُرجَع خطأ HTTP نظيفًا (لا استثناء) فيتجاهله العميل بصمتٍ.
+
+## المسارات (واجهة العميل — مسطّحة)
+
+| المسار | يقبل من العميل | يُمرَّر للنقطة | النقطة العلويّة |
+|---|---|---|---|
+| `POST /stt` | `{pcm}` أو `{pcm, ref}` | `{inputs:{pcm, ref?}}` | `STT_ENDPOINT_URL` (الطبقة الصوتية) |
+| `POST /analyze` | `{pcm, surah, ayahs\|ayah, mode?, scope?, sifat?}` | `{inputs:{…}}` | `ANALYZE_ENDPOINT_URL` (المُعلِّم QPS) |
+| `WS /stream?kind=tlog\|clean` | إطارات int16 PCM 16k + نصّ `"end"` | تمريرٌ شفّاف | `STREAM_ENDPOINT_URL` (بثّ احتياطيّ) |
+| `GET /health` | — | — | فحص جهوزيّة (يكشف أيّ نقطةٍ مُهيَّأة) |
+
+### عقد `POST /analyze`
+
+```
+req  {"pcm":"<b64 PCM16 LE 16k أحاديّ>", "surah":1, "ayahs":[1,2,3,4,5,6,7],
+      "mode?":"whole|teacher", "scope?":{…}, "sifat?":true}
+      // أو "ayah":n لآيةٍ مفردة بدل ayahs
+res  ردّ النقطة كما هو: {uthmani, match, per, words:[{w,hard,soft, …}],
+      word_hard, word_soft, flagged, ops, ref_phonemes, pred_phonemes, mode, …}
+```
+`mode`/`scope`/`sifat` تُمرَّر شفّافةً؛ النقطة الحاليّة تتجاهلها بأمان، وطبقتا P1/P2 تستهلكانها.
+
+### عقد `POST /stt`
+
+```
+req  {"pcm":"<b64 PCM16 LE 16k>", "ref?":"<كلمات التشكيل للمحاذاة القسريّة>"}
+res  {"text":"…", "words?":[{w,start_ms,end_ms,prob,gop,status}], "provider":"quran-stt-acoustic"}
+```
+بلا `ref`: نصّ فقط. مع `ref`: محاذاة قسريّة + توقيت/GOP/رأس نطق.
+
+## متغيّرات البيئة (Settings → Variables and secrets)
+
+| المتغيّر | النوع | الافتراضيّ | الوصف |
+|---|---|---|---|
+| `HF_TOKEN` | **سرّ** | — | توكن HF (Bearer) لنقاط الاستدلال. **إلزاميّ** إن كانت النقاط محميّة. |
+| `STT_ENDPOINT_URL` | متغيّر | — | URL كامل لنقطة الطبقة الصوتية. فارغٌ ⇒ `/stt` يُرجِع 503 نظيفًا. |
+| `ANALYZE_ENDPOINT_URL` | متغيّر | — | URL كامل لنقطة المُعلِّم QPS. فارغٌ ⇒ `/analyze` يُرجِع 503 نظيفًا. |
+| `STREAM_ENDPOINT_URL` | متغيّر | — | URL كامل لنقطة البثّ (`ws://`/`wss://`). فارغٌ ⇒ `/stream` يُغلَق بلطف. |
+| `ALLOWED_ORIGINS` | متغيّر | — | أصولٌ صريحة مفصولة بفواصل (بجانب النمط أدناه). |
+| `ALLOWED_ORIGIN_REGEX` | متغيّر | `*.pages.dev`/`*.workers.dev`/localhost | نمط CORS. عدِّله لتقييده على نطاق Pages بعينه. |
+| `RATE_LIMIT_PER_MIN` | متغيّر | `40` | سقف الطلبات لكلّ IP في الدقيقة. `0` = مُعطَّل. |
+| `UPSTREAM_TIMEOUT` | متغيّر | `150` | سقف ميزانية الطلب الكلّيّة (ث) عبر كلّ المحاولات. |
+| `ATTEMPT_TIMEOUT` | متغيّر | `60` | مهلة قراءة المحاولة الواحدة (ث). |
+| `MAX_RETRIES` | متغيّر | `6` | أقصى عدد محاولات على البدء البارد. |
+| `RETRY_BACKOFF` | متغيّر | `4` | أساس التراجع الخطّيّ (ث). |
+| `RETRY_BACKOFF_MAX` | متغيّر | `20` | سقف التراجع بين المحاولات (ث). |
+| `MAX_BODY_BYTES` | متغيّر | `25165824` | سقف حجم جسم الطلب (~24MB). |
+| `LOG_LEVEL` | متغيّر | `INFO` | مستوى السجلّ. |
+
+> إعادة المحاولة تُطلَق على حالات `500/502/503/504` (النقطة تستيقظ من scale-to-zero) وعلى أخطاء
+> الاتصال/المهلة. أمّا `4xx` الحتميّة فتُعاد فورًا بلا إعادة محاولة.
+
+## التشغيل المحلّيّ
+
+```bash
+pip install -r requirements.txt
+export HF_TOKEN=hf_xxx
+export ANALYZE_ENDPOINT_URL=https://<endpoint>.endpoints.huggingface.cloud
+export STT_ENDPOINT_URL=https://<endpoint>.endpoints.huggingface.cloud
+python app.py                 # يستمع على :7860 (أو $PORT)
+# فحص:  curl localhost:7860/health
+```
+
+## النشر على HF Space
+
+1. أنشئ Space من نوع **Docker**.
+2. ارفع `app.py` و`requirements.txt` و`Dockerfile` و`README.md` (front matter أعلاه يضبط `app_port=7860`).
+3. أضِف الأسرار/المتغيّرات من الجدول أعلاه (`HF_TOKEN` سرًّا؛ عناوين النقاط متغيّراتٍ).
+4. أبقِ `MUAALEM_URL`/`STT_URL` في `bayan/web/app.js` على `https://<space>.hf.space/{analyze,stt}` بلا تغيير.
+
+**لا شيء هنا يَنشُر تلقائيًّا — كودٌ فقط.**