Record public Phoenix release status

.gitattributes

@@ -1,78 +1,2 @@
 *.mlmodel filter=lfs diff=lfs merge=lfs -text
 
-presentation_dashboard/assets/before_after/manuscript.png filter=lfs diff=lfs merge=lfs -text
-presentation_dashboard/assets/samples/clear/manuscript.jpg filter=lfs diff=lfs merge=lfs -text
-presentation_dashboard/assets/samples/logic/manuscript.png filter=lfs diff=lfs merge=lfs -text
-presentation_dashboard/assets/samples/medium/manuscript.jpg filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/01_تسجيل_الدخول.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/02_التفريغ.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/03_قائمة_المراجعة.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/04_لوحة_الأدلة.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/05_قرار_الباحث.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/06_مكتبة_المصادر.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/07_اختيار_المصادر.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/08_بعد_التنزيل.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/09_معاينة_OpenITI.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/10_بعد_فهرسة_OpenITI.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/11_معاينة_رابط_OpenITI.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/12_ترخيص_مصرَّح.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/13_IIIF_صور_فقط.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/14_IIIF_بنص.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/15_سجل_القرارات.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/16_بعد_الاسترجاع.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/17_كل_الأسطر_قابلة_للفتح.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/18_إلغاء_الإثراء.png filter=lfs diff=lfs merge=lfs -text
-reports/تسليم_صباحي/لقطات/19_حالات_المصادر.png filter=lfs diff=lfs merge=lfs -text
-samples/logic_router/sample_01_framed_margin.jpg.jpg filter=lfs diff=lfs merge=lfs -text
-samples/logic_router/sample_02_handwritten_logic[[:space:]](1).jpg filter=lfs diff=lfs merge=lfs -text
-samples/logic_router/sample_03_handwritten_logic[[:space:]](2).jpg filter=lfs diff=lfs merge=lfs -text
-samples/logic_router/sample_04_handwritten_logic[[:space:]](3).jpg filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0023.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0024.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0025.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0026.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0027.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0028.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0029.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0030.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0031.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0032.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0033.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0034.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0035.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0036.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0037.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0038.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0039.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0040.png filter=lfs diff=lfs merge=lfs -text
-tmp/book_pages/page_0041.png filter=lfs diff=lfs merge=lfs -text
-tmp/pdfs/PAPER_v2_page1.png filter=lfs diff=lfs merge=lfs -text
-tmp/pdfs/project_submission_review/page-01.png filter=lfs diff=lfs merge=lfs -text
-tmp/pdfs/project_submission_review/page-02.png filter=lfs diff=lfs merge=lfs -text
-tmp/pdfs/project_submission_review/page-03.png filter=lfs diff=lfs merge=lfs -text
-tmp/pdfs/project_submission_review/page-04.png filter=lfs diff=lfs merge=lfs -text
-tmp/pdfs/project_submission_review/page-05.png filter=lfs diff=lfs merge=lfs -text
-tmp/pdfs/project_submission_review/page-06.png filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_ARA_MS_1982_182182.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1926_0077.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1926_0144.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1943_180499.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1944_0006.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1977_0092.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1977_0093.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1977_0136.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1977_0153.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_1983_177819.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_23_42035.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_417_0009.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/BULAC_MS_ARA_417_0011.jpg filter=lfs diff=lfs merge=lfs -text
-top_15_easiest_images/تفريغ.zip filter=lfs diff=lfs merge=lfs -text
-عرض_قص_آلي/1944_مغربي_قص_آلي.jpg filter=lfs diff=lfs merge=lfs -text
-عرض_قص_آلي/1977_0092_مغربي_قص_آلي.jpg filter=lfs diff=lfs merge=lfs -text
-عرض_قص_آلي/1977_0136_مغربي_قص_آلي.jpg filter=lfs diff=lfs merge=lfs -text
-عرض_قص_آلي/1983_شرقي_سهل_قص_آلي.jpg filter=lfs diff=lfs merge=lfs -text
-عرض_قص_آلي/417_مغربي_قص_آلي.jpg filter=lfs diff=lfs merge=lfs -text
-عرض_قص_آلي/منطق_page16_قص_آلي.jpg filter=lfs diff=lfs merge=lfs -text
-عرض_قص_آلي/منطق_page17_قص_آلي.jpg filter=lfs diff=lfs merge=lfs -text
-عرض_منطق_قص_GT/تحرير_القواعد_المنطقية_في_شرح_الرسالة_الشمسية.pdf_page_16.jpg filter=lfs diff=lfs merge=lfs -text
-عرض_منطق_قص_GT/تحرير_القواعد_المنطقية_في_شرح_الرسالة_الشمسية.pdf_page_17.jpg filter=lfs diff=lfs merge=lfs -text

PUBLISH_CHECKLIST.md

@@ -1,15 +1,15 @@
 # Hugging Face publication checklist
 
-Uploaded privately on 2026-08-17 to:
+Published publicly on 2026-08-17 at:
 
 `https://huggingface.co/factlogic/phoenix-arabic-manuscript-htr`
 
-The repository remains private pending the license review below.
+The public release uses the conservative CC BY-NC-SA 2.0 license because Muharaf contributed to training. The checks below remain the release audit trail.
 
 ## Before publishing
 
 1. Confirm the repository name and owner.
-2. Keep the repository private until the training-data/license statement has been reviewed.
+2. Preserve the CC BY-NC-SA 2.0 license and the non-commercial training-data notice unless a new legal review authorizes a change.
 3. Verify `SHA256SUMS` against `model.mlmodel`.
 4. Confirm that the README has no placeholder comments.
 5. Confirm that aggregate benchmark JSON contains no line-level ground truth or restricted images.
@@ -28,4 +28,4 @@ $hf = "$env:LOCALAPPDATA\Programs\Python\Python313\Scripts\hf.exe"
 & $hf upload factlogic/phoenix-arabic-manuscript-htr . . --repo-type model
 ```
 
-Run the upload command from this directory. Remove `--private` only after the license decision is final.
+Run the upload command from this directory. The repository is already public; do not change the license metadata without reviewing upstream dataset obligations.

README.md

@@ -1,87 +1,254 @@
-# أثر — Athar / Phoenix AI
-
-منصة بحثية مفتوحة البنية لتفريغ المخطوطات العربية وتحقيقها بمشاركة الباحث.
-تجمع بين قص الأسطر، والتعرّف البصري، والقراءات البديلة، والنموذج اللغوي
-المحلي، والاسترجاع من مكتبة المصادر (RAC)، وقرار الإنسان القابل للتدقيق.
-
-## المعمارية
-
-```text
-صورة صفحة
-  → Athar Segmentation v4 (مضلعات الأسطر وbaselines)
-  → Athar HTR exp9 (مصفوفة CTC وقراءة greedy)
-  → بدائل بصرية + ترتيب لغوي محلي اختياري
-  → شواهد من مكتبة المصادر مع إسناد unique/ambiguous
-  → قبول/تحرير/رفض الباحث
-  → PAGE-XML أو TEI أو حزمة تدريب بشرية المراجعة
-```
+---
+language:
+- ar
+library_name: kraken
+pipeline_tag: image-to-text
+tags:
+- htr
+- ocr
+- arabic
+- arabic-manuscripts
+- historical-documents
+- kraken
+- ctc
+- human-in-the-loop
+license: cc-by-nc-sa-2.0
+model-index:
+- name: Phoenix — Arabic Manuscript HTR Model
+  results:
+  - task:
+      type: image-to-text
+      name: Arabic Handwritten Text Recognition
+    dataset:
+      name: Agapet sealed manuscripts
+      type: agapet-sealed
+    metrics:
+    - type: cer
+      value: 17.86
+      name: Raw CER (%)
+    - type: wer
+      value: 58.80
+      name: Raw WER (%)
+  - task:
+      type: image-to-text
+      name: Arabic Handwritten Text Recognition
+    dataset:
+      name: Omar document-level sealed split
+      type: omar-sealed
+    metrics:
+    - type: cer
+      value: 11.84
+      name: Raw CER (%)
+    - type: wer
+      value: 42.92
+      name: Raw WER (%)
+  - task:
+      type: image-to-text
+      name: Arabic Handwritten Text Recognition
+    dataset:
+      name: TariMa sealed manuscript test
+      type: tarima-sealed
+    metrics:
+    - type: cer
+      value: 10.72
+      name: Raw CER (%)
+    - type: wer
+      value: 38.89
+      name: Raw WER (%)
+---
+
+# Phoenix — Arabic Manuscript HTR Model
+
+**Phoenix** is a compact Arabic handwritten-text recognizer for Maghrebi manuscripts, historical manuscripts, and archival documents. Its internal checkpoint identifier is `exp9`; that identifier describes this release checkpoint, not the public model name. Phoenix is the recognizer deployed in the **Athar** human-in-the-loop manuscript investigation system.
+
+Phoenix uses a deliberately small **CNN + BiLSTM + CTC** architecture: convolutional layers extract visual features, bidirectional LSTMs model the character sequence, and CTC aligns image features to text without requiring character-level segmentation. It has **4,988,946 parameters** and a **19.94 MB** model file. Depending on manuscript domain and evaluation protocol, observed CER is roughly **7–18%**. In one local batch rehearsal it recognized 288 pre-segmented lines in 32 seconds (about 9 lines/s); this timing is hardware- and pipeline-specific, not a universal latency guarantee.
+
+The model is not presented as a universal Arabic OCR system. Its strongest evidence is a preregistered comparison with the preceding `exp8` checkpoint on 22,442 sealed lines: it substantially improved two large external domains and showed a small regression on a third domain. Across the two large sealed sets together (22,278 lines), character-weighted CER fell from **19.98% to 14.93%**, a **25.3% relative reduction in character errors**.
+
+## ملخص عربي
+
+**Phoenix — Arabic Manuscript HTR Model** نموذج صغير للتعرّف على الكتابة العربية اليدوية، وبنيته **CNN + BiLSTM + CTC** بحوالي 5 ملايين معامل وملف حجمه نحو 20 ميغابايت. حقق CER يتراوح تقريباً بين **7% و18%** باختلاف المجال والبروتوكول. معرّف `exp9` اسم داخلي لنقطة الحفظ الحالية، وليس الاسم العام للنموذج. في مجموعتي Agapet وOmar المختومتين معاً (22,278 سطراً) انخفض CER الموزون بالمحارف من 19.98% إلى 14.93% مقارنةً بنقطة الحفظ السابقة، أي خفض نسبي للأخطاء قدره 25.3%. النموذج جزء من منظومة «أثر» التي تعرض القراءات البديلة وشواهد المصادر وقرار الباحث، لكن هذه الميزات ليست مخزنة داخل الأوزان نفسها.
+
+النموذج بحثي وغير تجاري وفق الترخيص المحافظ CC BY-NC-SA 2.0 بسبب أحد مصادر التدريب. لا يُستخدم لإنتاج تحقيق علمي نهائي بلا مراجعة بشرية.
+
+## Evidence at a glance
+
+| Evidence level | What it measures | Status and headline |
+|---|---|---|
+| **Sealed evaluation** | Frozen `exp8` vs current `exp9` checkpoint on data opened once after selection | Strongest release evidence: **17.86% Agapet**, **11.84% Omar**, **10.72% TariMa** raw CER |
+| **Development diagnostics** | Same-protocol comparisons used for diagnosis and model selection | Useful but not independent final evidence: Phoenix CER spans **7.67–12.31%** across four listed guards |
+| **Additional server benchmark** | Phoenix vs Baseer__Nakba VLM aggregates supplied from a server run | **Preliminary**: Phoenix macro CER **9.71% vs 28.67%**, but Baseer wins Omar and exact-line accuracy |
+
+## Model summary
+
+| Field | Value |
+|---|---|
+| Public model name | Phoenix — Arabic Manuscript HTR Model |
+| Internal checkpoint ID | `exp9` |
+| Framework | Kraken / PyTorch |
+| Parameters | 4,988,946 |
+| Input | One-channel line image; Kraken resizes to model height 120 |
+| Output codec | 81 symbols + CTC blank |
+| Architecture | CNN + BiLSTM + CTC |
+| Main layers | 4 convolutional blocks + 4 bidirectional LSTM layers + linear CTC output |
+| Model file | `model.mlmodel` |
+| SHA-256 | `2896fef9d9665cbb82fba8faa3bf0c628ac6a5cc62eb678f40c707db833aebea` |
+| Intended use | Research-assisted transcription of Arabic handwriting with human review |
+
+## Sealed evaluation
+
+All values below use the same images, references, and greedy decoder for exp8 and exp9. No language model is included in these figures. The sealed sets were opened once after the two arms were frozen; exp9 was not tuned after seeing these results.
+
+| Sealed set | Lines | exp8 raw CER | exp9 raw CER | Change | exp8 → exp9 word accuracy |
+|---|---:|---:|---:|---:|---:|
+| Agapet: Sin423 + BnF Arabe 76 | 10,594 | 22.12% | **17.86%** | **−4.26 pp** | 23.91% → **33.23%** |
+| Omar: 11 held-out documents | 11,684 | 17.72% | **11.84%** | **−5.88 pp** | 33.40% → **46.83%** |
+| TariMa manuscript test | 164 | **10.39%** | 10.72% | +0.33 pp | 51.32% → 49.23% |
+
+Both Agapet manuscripts improved, and all eleven Omar documents improved. TariMa is the declared exception: exp9 regressed by 0.33 CER percentage points, within the 0.5-point tolerance registered before opening the sealed results.
+
+## Preliminary additional benchmark: Phoenix vs Baseer__Nakba
+
+In a **preliminary owner-run server comparison**, Phoenix achieved a substantially lower **four-domain macro CER** and **overall WER** than the multi-billion-parameter Baseer__Nakba VLM while using roughly three orders of magnitude fewer parameters. The comparison also exposes an important counter-result: Baseer__Nakba had higher exact-line accuracy and was markedly better on Omar. These aggregate values are reported as supplied; the raw per-line predictions, sample counts, preprocessing manifest, and executable evaluation bundle are not yet included in this repository. This is therefore preliminary supporting evidence, not a sealed or independently reproduced benchmark.
+
+| Metric | Phoenix | Baseer__Nakba | Result |
+|---|---:|---:|---|
+| Four-domain unweighted macro CER | **9.71%** | 28.67% | Phoenix: **66.1% relative CER reduction** |
+| Overall WER | **34.37%** | 59.52% | Phoenix: **−25.15 pp**, 42.3% relative reduction |
+| Exact-line accuracy | 13.38% | **26.38%** | Baseer__Nakba higher |
+| Parameters | **4,988,946** | ≈3.75B | Phoenix ≈**752× smaller** |
+| Model file | **19.94 MB** | ≈7.53 GB | Phoenix ≈**378× smaller** |
+
+### Raw CER by dataset
+
+| Dataset | Phoenix | Baseer__Nakba | Lower CER |
+|---|---:|---:|---|
+| Agapet | **11.13%** | 35.65% | Phoenix (68.8% relative reduction) |
+| Muharaf | **11.93%** | 25.51% | Phoenix (53.2% relative reduction) |
+| Omar | 6.88% | **0.48%** | Baseer__Nakba |
+| RASAM | **8.90%** | 53.06% | Phoenix (83.2% relative reduction) |
+
+The macro CER is an **unweighted mean of the four dataset CER values**, so each dataset contributes equally regardless of line or character count. The four displayed Baseer values average to 28.675%; the supplied 28.67% display is retained, while the unrounded recomputation is recorded in `baseer_server_benchmark.json`. The supported conclusion is therefore: **under this server protocol, Phoenix has lower CER on three of four datasets and a much lower macro CER at a fraction of the model size; Baseer__Nakba remains stronger on Omar and exact-line accuracy.**
+
+## Same-protocol diagnostic comparison
+
+All models below were decoded on the same pre-cropped line images and raw references with Kraken greedy decoding, without an LM or normalization. Each cell is **CER / word accuracy**.
+
+| Development guard | Lines | Original Muharaf | exp6 | exp8 | **exp9** |
+|---|---:|---:|---:|---:|---:|
+| Agapet | 991 | 33.15 / 16.62 | 23.82 / 24.71 | 20.08 / 33.58 | **9.47 / 67.40** |
+| Omar | 1,143 | 9.26 / 60.08 | 26.88 / 21.25 | 12.06 / 53.90 | **8.91 / 63.95** |
+| RASAM | 1,789 | 39.01 / 12.06 | 9.04 / 66.78 | 7.95 / 69.90 | **7.67 / 70.46** |
+| Muharaf | 920 | 13.28 / **64.15** | 36.47 / 15.74 | 12.72 / 58.30 | **12.31** / 59.32 |
+| **Four-domain unweighted macro** | **4,843** | 23.68 / 38.23 | 24.05 / 32.12 | 13.20 / 53.92 | **9.59 / 65.28** |
 
-## أهم الميزات
+Under this exact diagnostic protocol, exp9 had the lowest CER on **4/4** comparable guards and the highest word accuracy on **3/4**. Its macro CER was 9.59% versus 23.68% for the original Muharaf model, a 59.5% relative reduction in character errors. On the Muharaf guard itself, exp9 had lower CER (12.31% vs 13.28%) but lower word accuracy (59.32% vs 64.15%); both metrics are reported to avoid hiding the trade-off.
 
-- رفع صفحة كاملة أو استعمال PAGE-XML بقص بشري.
-- قراءة عربية متعددة المجالات بنموذج exp9.
-- قراءات بصرية بديلة مع درجات نسبية غير معروضة كاحتمالات معايرة.
-- نموذج لغوي محلي مشروط بالمجال والثقة، مع إبقاء القراءة الخام.
-- اقتراح LLM خارجي اختياري وموسوم بوصفه استشارياً.
-- مكتبة مصادر محلية قابلة للتوسعة، وامتناع عند غموض الإسناد.
-- قائمة مراجعة، وسجل قرارات الباحث، وتصدير PAGE-XML/TEI.
-- حزمة تدريب تستبعد المخرجات الآلية غير المعتمدة بشرياً افتراضياً.
+The 369-line TariMa manuscript guard is excluded from this macro because it was independent for exp9 but not for exp6/exp8. Its scores are retained in `BENCHMARKS.md` as a non-ranked diagnostic.
 
-## النماذج
+This table is a development diagnostic, not an independent final test: some of the guard sets participated in exp9 selection. Its purpose is to compare `muharaf_rec_best`, exp6, exp8, and exp9 under one raw-reference protocol. It must not be mixed with published Muharaf numbers obtained from a different split, codec, or normalization policy.
 
-الأوزان لا تدخل GitHub. نُشرت نسخة خاصة ومتحققة البصمة على Hugging Face:
+## Training data
 
-| الوظيفة | المستودع | SHA-256 |
+exp9 used document-aware training/replay from five sources:
+
+| Dataset | Role | Recorded license |
 |---|---|---|
-| Phoenix HTR (checkpoint: `exp9`) | `factlogic/phoenix-arabic-manuscript-htr` | `2896fef9d9665cbb82fba8faa3bf0c628ac6a5cc62eb678f40c707db833aebea` |
-| القص v4 | `factlogic/athar-segmentation-v4` | `dc07cdeefe17598535ea3f5b187f7ddd2463baed909138c9ffd274c88b0e9a24` |
+| Muharaf public line images | Archival handwriting | CC BY-NC-SA 2.0 |
+| RASAM | Maghrebi manuscripts | Apache-2.0 in the local dataset repository |
+| TariMa | Maghrebi/historical manuscripts | Apache-2.0 |
+| Agapet SA-418 | 13th-century historical manuscript | CC BY 4.0 |
+| Omar Al-Saleh manuscripts | Diverse archival documents | CC BY 4.0; access-gated at download time |
 
-بعد تسجيل الدخول إلى Hugging Face شغّل:
+Training and guard splits were separated at document or manuscript level where the source allowed it. The Agapet sealed manuscripts and the eleven Omar sealed documents did not enter training.
 
-```powershell
-hf auth login
-.\scripts\download_hf_models.ps1
-```
+Because Muharaf is CC BY-NC-SA 2.0, this release uses the same non-commercial ShareAlike license as the conservative publication choice. Users are responsible for checking whether their intended use and jurisdiction are compatible with every upstream dataset license.
+
+## Intended use
+
+- Research and non-commercial transcription assistance for Arabic manuscripts and archival documents.
+- Producing initial transcriptions for expert review.
+- Generating multiple CTC candidates for a human-in-the-loop workflow.
+- Use with PAGE-XML line polygons when layout segmentation is supplied externally.
+
+## Out-of-scope use
 
-النماذج اللغوية والنموذجان المتخصصان في المنطق محفوظة محلياً في `نماذج/`
-لكنها ليست جزءاً من مستودعي Hugging Face أعلاه.
+- Fully automatic scholarly editions without expert review.
+- Claims of universal accuracy across all Arabic scripts, periods, or image conditions.
+- Automatic attribution of text to a unique source without a separate retrieval/attribution layer.
+- Commercial use without a separate legal review of the training-data obligations.
+- Treating decoder scores as calibrated probabilities of correctness.
 
-## التشغيل على Windows
+## Inference
 
-يتطلب Python 3.10 وبيئة متوافقة مع Kraken/PyTorch.
+Install a Kraken version compatible with PyTorch 2.4, then use the model as a Kraken recognition model. A typical page command is:
 
-```powershell
-cd backend
-python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install -r requirements.txt
-Copy-Item .env.example .env
-cd ..
-.\تشغيل_المشروع.bat
+```bash
+kraken -i page.jpg output.txt segment ocr -m model.mlmodel
 ```
 
-ثم افتح `http://127.0.0.1:8001/app/`.
+For complex pages, the recommended Athar workflow supplies PAGE-XML polygons and runs recognition on the human-defined line regions. This avoids mixing segmentation failure with recognition error.
+
+## Language-model policy in Athar
+
+The published CER/WER values are greedy recognition values. The complete Athar system can additionally:
+
+- preserve the raw visual reading for every line;
+- generate up to eight visual candidates;
+- rerank candidates with a small local character n-gram model;
+- apply the general/Maghrebi LM automatically only in a conservative confidence band;
+- show an archival LM as advisory evidence instead of silently replacing the text;
+- protect numbers and punctuation from destructive LM changes.
+
+On a 1,789-line RASAM development guard, the deployed conservative general-LM policy produced only a small change (about −0.003 CER points and −0.141 WER points). The large exp9 gains therefore come from the visual recognizer, not from post-hoc language correction.
 
-يمكن وضع مفتاح OpenRouter أو مزود LLM في `backend/.env`. الملف محلي ومُتجاهل
-في Git؛ لا ترفع المفاتيح إلى المستودع.
+## Athar system capabilities
 
-## هيكل المشروع
+The `.mlmodel` file is one component of the larger architecture. The application adds:
 
-- `backend/app/`: FastAPI وخدمات OCR/LM/RAC والتصدير.
-- `frontend/`: واجهة التحقيق والمراجعة.
-- `digital_texts/`: مكتبة الاسترجاع المحلية وسجلات مصادرها.
-- `scripts/`: القياس، التدريب، التدقيق، وأدوات التشغيل.
-- `reports/`: أدلة القياس والادعاءات المنهجية.
-- `huggingface/`: بطاقات النماذج وبيانات نشرها، من دون أوزان داخل Git.
+- visual and language-ranked alternatives;
+- source retrieval with unique/ambiguous attribution states;
+- a review queue with reasons;
+- optional external-LLM suggestions labelled as advisory;
+- auditable human accept/edit/reject decisions;
+- PAGE-XML and TEI export;
+- a training package that excludes unreviewed automatic output by default.
 
-## البيانات وإعادة الإنتاج
+These are system capabilities, not properties encoded inside the model weights.
 
-بيانات التدريب والتقييم الكبيرة محفوظة خارج Git ولا تُرفع مع الكود. افصل
-التقسيمات على مستوى المخطوطة/الوثيقة، ولا تضبط المعاملات على مجموعة مختومة.
-درجات CTC والـbeam نسبية وليست احتمالات ثقة معايرة.
+## Limitations
+
+- Raw CER remains 17.86% on the difficult Agapet sealed set; human review is still necessary.
+- TariMa sealed performance is 0.33 CER points worse than exp8.
+- The model is optimized for Arabic handwriting, not modern printed OCR.
+- Layout/segmentation quality can dominate full-page performance.
+- The 81-symbol codec does not cover every possible Arabic-script or Latin character.
+- Confidence values and beam scores are not globally calibrated probabilities.
+- The same-protocol Muharaf comparison in this repository is a development comparison, not a new sealed benchmark.
+
+## Reproducibility
+
+- Model SHA-256: `2896fef9d9665cbb82fba8faa3bf0c628ac6a5cc62eb678f40c707db833aebea`
+- Python used in the verified local environment: 3.10.11
+- PyTorch: 2.4.1+cu121
+- Evaluation decoder: greedy, without LM
+- Raw and Arabic-normalized metrics are stored separately; the model card reports raw metrics unless explicitly labelled otherwise.
+
+See `BENCHMARKS.md`, `benchmark_summary.json`, `baseer_server_benchmark.json`, `DATA_AND_LICENSES.md`, and `metadata.json` in this repository for details.
+
+## Citation
+
+Until a final paper record is available, cite the project and this model version as:
+
+```bibtex
+@misc{athar_htr_exp9_2026,
+  title        = {Phoenix: Arabic Manuscript HTR Model},
+  author       = {Athar Project Team},
+  year         = {2026},
+  note         = {Internal checkpoint exp9; Kraken CNN-BiLSTM-CTC model; SHA-256 2896fef9d9665cbb82fba8faa3bf0c628ac6a5cc62eb678f40c707db833aebea}
+}
+```
 
-## الترخيص
+## Ethical and scholarly note
 
-الكود ووزن النموذج ليسا بالضرورة تحت الترخيص نفسه. نموذج exp9 منشور بترخيص
-محافظ `CC BY-NC-SA 2.0` بسبب أكثر مصادر تدريبه تقييداً، ومستودع نموذج القص
-خاص إلى أن تكتمل مراجعة أصل نموذج الـwarm-start. راجع بطاقات Hugging Face قبل
-أي نشر عام أو استعمال تجاري.
+The output is a research aid, not an authoritative edition. Manuscript transcription and source attribution require domain expertise. Preserve the image, the raw reading, the evidence trail, and the researcher's final decision.

SHA256SUMS

@@ -1,4 +1,4 @@
 2896fef9d9665cbb82fba8faa3bf0c628ac6a5cc62eb678f40c707db833aebea  model.mlmodel
 7184ae01c9f4a248d80ddeb84d852a8c21b8d7b213ca7619433edf4b18bf2fe7  benchmark_summary.json
-2592cdb457098fbac54bc80c37799e80af6ce09c5491d5a65be32d1bc3bae3c9  metadata.json
+d943903a68dd40859b42a66f244d8441b022a8b051a8b1d0716781b7ef9919e4  metadata.json
 1cc91f05e0ff7e5594b13029a0b82d0fa2b78de3dff1a16160d99ed61441f039  baseer_server_benchmark.json

metadata.json

@@ -12,7 +12,7 @@
   "python": "3.10.11",
   "pytorch": "2.4.1+cu121",
   "created_date": "2026-08-11",
-  "release_status": "uploaded_private_pending_publication_review",
+  "release_status": "published_public_2026-08-17",
   "license": "CC BY-NC-SA 2.0 (conservative choice due to upstream Muharaf training data)",
   "sealed_release_evidence": {
     "lines": 22442,