Deploy Arabic Audio Reader worker

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.env
+.venv
+.venv-*
+__pycache__
+.pytest_cache
+outputs
+uploads
+data
+test_pdfs
+tests
+*.pyc
+*.pyo
+*.pyd
+*.log

.export-complete

@@ -0,0 +1 @@
+ready

.export-manifest.json

@@ -0,0 +1,105 @@
+{
+  "files": {
+    "Dockerfile": "9ec939ea5ce45fcd8d1cd1c72df61087be9e27630dad09f46d0d6b6ac56606f0",
+    "api/index.py": "b0fd5c43eadd241aea79131d12ea40fe032a97f06410ce1b607e81c45f33d6f2",
+    "app/__init__.py": "7eb70257593da06f682a3ddda54a9d260d4fc514f645237f5ca74b08f8da61a6",
+    "app/main.py": "96d3dd5ea42e6328c9891b8215bb5bb092a2c63980781b08e86524a7f27e3bd9",
+    "docs/best-free-arabic-pdf-audio-stack.md": "d73c1c1fca7a04517ae1abecb893175e238d36318c39c0755e9b4fa570d3910a",
+    "docs/father-user-guide.md": "cf5a955e30ecf8fa0c0179995cb9e90106cc9335a5994eb8b8368a8164c4d021",
+    "docs/huggingface-model-metadata.md": "4590229078c2048b184787e85e5a00dd687ef5fc90e8d8d0af32538b38363cc2",
+    "docs/live-deployment-checklist.md": "390f89084febb94489996a83287e3d3e97d67f996a648c7c0f79bbe8f510fbf8",
+    "docs/production-worker-architecture.md": "a1776a7db4397103ef4f4e7ae82588dfd01576a5b8aca7b22d25514c3ccfce8e",
+    "docs/recommended-decision-card.json": "78213faeeb8825a7d2c4bf4fe0886b282b6e9a9d522fc742aab54a55f6efb1b3",
+    "docs/recommended-decision-card.md": "0e353fda7e9dc410ec031a2f4ef10398cb5ce8b00aa0ddc03479995ef467a18f",
+    "docs/recommended-free-stack.md": "d2da77822fe5f94790ed560323b2c1c8cf7a8303315a973183633245aea1e491",
+    "docs/research-watchlist.md": "9ea43e6f3f1d434e514e451ccc8974faa469f4533d0ffe924c8db3d80755e592",
+    "docs/source-evidence.md": "f308cbd0dc83a5cf34ceb5a010c354cda9acbc690e9b2c93a80cdb519ec07976",
+    "requirements-arabic-glm-ocr.txt": "b4c950c1ef221bfe6e2deda1a93605377619059eb02019931dbfe1fe7bd49e10",
+    "requirements-arabic-qwen-ocr.txt": "c19f907a3834255ff9e9588df158a3cb772ce61e7234ddd6508fbfcd9b9188f2",
+    "requirements-baseer-ocr.txt": "e5ba1652d94d98b99b180330a198ac857c1c7b556ef3d7c5a0da1252ea33ec76",
+    "requirements-katib-ocr.txt": "47defded2d099f26caf3260a9764967b8c00e61d159949873325adfe9e5bcd27",
+    "requirements-paddleocr-vl.txt": "425f83d985be5751b624a11023110a6aef6f23339a00f90aaec9d92572b5c517",
+    "requirements-paddleocr.txt": "94de53878d0f730907ddcb37fb735714d5c83beb069e308d935002df850f3d3c",
+    "requirements-qari-ocr.txt": "71cafe3617954a657fa7fc983b330ba37899aa4ba95a43d3e7f8590ff0fd5be5",
+    "requirements-silma.txt": "63c10a7c78fcd65af653f3afd48dd031af7695b1b8545684efdef32dd814a872",
+    "requirements-supertonic.txt": "87b6e0fa01626aa259aa99eed3b0d9b57867cab7b2a1a37ea05de817f4a285b6",
+    "requirements-tawkeed-ocr.txt": "5e718dc14b8a2aa7e6269d63a85a37e15892d5863b42608e928e5217233edb22",
+    "requirements.txt": "59d736ba33b31a828a5987f3477bec3f7ed6f60ceafaf730ef027a0dbbcd0def",
+    "scripts/arabic_glm_ocr_extract.py": "f56578018b81ac8cd7928baa9576878791214e5659f972520e8817370a9d39ad",
+    "scripts/arabic_qwen_ocr_extract.py": "485e9f3cdf2ced92c666b2f483d4aa37a65cb34052a4967beac7183d02c9ddcc",
+    "scripts/audit_goal_readiness.py": "18835de059c01515e94813c8b32105da47c08c66126dad8275956c0213bfc958",
+    "scripts/baseer_ocr_extract.py": "056ca9cc33591db804639030a16d9635931b720d0d499b444ed6e7d0a653605a",
+    "scripts/benchmark_ocr.py": "b5ffb17845a7945b2a5c52e38bfabb6d82f3a8fbc8f2cdd5528843e09ad4deb4",
+    "scripts/benchmark_voices.py": "705bdfb6260fe90a4a68d9d2455953ea7221d282bbf0cc1cc4fa32cd5ed10205",
+    "scripts/check_deployment_readiness.py": "13ec851a25b1fde5f0e3f0ea0635d4145b0296a5acb28c6d9a61f286499eeba3",
+    "scripts/check_research_sources.py": "1db463ada18c6b6062f096fdc9f4b0f9fbdd9365d785265da3acdc45e1da0d88",
+    "scripts/check_test_environment.py": "7150b13aabad03a9b7ae2527f7cdd942511658eeafb76b41128eab7e0a6dc1ea",
+    "scripts/cleanup_outputs.py": "de8beacd9b8511dc3775d9c232a2c86dc5cbe91c532cb3c130c304117f0d6bfd",
+    "scripts/configure_vercel_worker.py": "b14067cf58d1bdc3243580532661369fcf70e7fe6f5fba33ee7329de924e058f",
+    "scripts/deploy_hf_space.py": "dd42220e78d025c68bbd52750c4af4187e080af62566c78a3f032698f72a755b",
+    "scripts/deployment_handoff.py": "acaab15aa32e0cd3b4f969e5a6fcb013bb9db24ce59215626e5f5809792c4713",
+    "scripts/deployment_status.py": "290e4fe5324473c8aaf5701e50a816cf006a1400e8a458f0e1a443b9f7393ae6",
+    "scripts/dry_run_pdf.py": "f162b566fb51d824d484a479a1337d4ee7e9a6762c0f2ccb5acd3173c1cf1bf8",
+    "scripts/easyocr_extract.py": "5a728a80bac7d49281113410316b5004cb6538ad50d1bc7c431eaea9c006ada9",
+    "scripts/export_hf_space.py": "121f817b9ece4ae7a85f4aba3b2c5323c9e67bbd7e22e1b95cfd95599eea73bc",
+    "scripts/export_ocr_sample_images.py": "eaf2ed2dca63f649317d283a1339ddae64d79b8d79eb42fe601d3b4a92ce8f45",
+    "scripts/export_tts_sample.py": "477ae98e81c60bc3336012167355b0b8724cd1988047e2af41f443b23de7e9f3",
+    "scripts/finish_live_deployment.py": "11b90f7f96bf5315220c8a4daef23722b73edc2133a26a93c12793d9e222163f",
+    "scripts/hosted_preflight.py": "931bae01a0e18b4c0490489c5e4eef463c92cce980c2d901705cbf4803c7f291",
+    "scripts/katib_ocr_extract.py": "cd667d9f242b6b348ddca99dd66045a24b1446e371995122b517f30eb24f6fcc",
+    "scripts/model_promotion_gate.py": "e0ecec8d8d437dfbae05d157e3e40aaeef8c34c56d80c80624521a5b305ff690",
+    "scripts/next_deployment_step.py": "5fbb188bc79fb1c98f1623e463ce0cf99c2b2fe9d8b249dcee94448bbf407b80",
+    "scripts/paddleocr_extract.py": "30637be8aed0f7951c8bd450274cf0f68b516b3c38de51b37f9b9195c56813a1",
+    "scripts/paddleocr_vl_extract.py": "8089d2e414bd0183d8593a4a51513d1914a3172776369882e6d5bbd8f541ee4a",
+    "scripts/preflight_check.py": "f7e7a4c6f2e96442ec08abb0bf0828cfc4b27edb672f64cdb886cb15095ff0c9",
+    "scripts/prepare_book_workflow.py": "b24c84de91b6912360c8c9bb7059988d2ce798c840260a53299b6d93b9d87e86",
+    "scripts/prepare_live_deployment.py": "e32f9463812d20e7e7a8cd6b7247142ced7491cdf2bfb866c2000443d4790239",
+    "scripts/prove_live_deployment.py": "d1fed48fdb902349b1ea99dd7f2d651bb4131f4c915e25ed3691b40cd5099675",
+    "scripts/prove_local_readiness.py": "7ccb00fc2d4aa086f8cec5ac9886f87fe044eb46c6f9a7fa7c5eb095d44095ad",
+    "scripts/qari_ocr_extract.py": "82ac22dae63e415c9795f4f597c000beba32af028b0a5afc749ba11bfebe2b22",
+    "scripts/refresh_research_evidence.py": "52209edf8485ff459bda6ada6cb1b978f12b22cdacb03413d293dab9245303fc",
+    "scripts/research_watchlist.py": "3d7640a8777b81ef596f1a24c6a4c8560233c396e09190de8cb739f2a405d37c",
+    "scripts/score_external_ocr.py": "e4b36187949dd38eaa9395979a97ccef88f7aff24a1404e3bf0793776eea136f",
+    "scripts/score_tts_preprocessor.py": "7b9afce94bbc914b884a09bb83bd4d267770f6b712ffb5721cfef7c34e2718a2",
+    "scripts/score_voice_listening.py": "22287145ab5677c4e4383a01dc9cb2090f3f22e20a37e0902bcfed8df7c7e5f6",
+    "scripts/select_test_pages.py": "b97f0599cb2a1371737ebd7110c62dde085377f35ce39b78413848f21a20d5c7",
+    "scripts/setup_arabic_glm_ocr.ps1": "5d0039918a41cd925bcff02a36aa627051abfd120665a681297a64ae7fe505e6",
+    "scripts/setup_arabic_glm_ocr.sh": "7040b741f39ad6f8fbc438fb2f5bc5a95d01704f483d64be29f1ceeb74a768c2",
+    "scripts/setup_arabic_qwen_ocr.ps1": "b2363d4eefb1e7308681f559c1ff98c898c82877d5daf1148408db704a760c64",
+    "scripts/setup_arabic_qwen_ocr.sh": "a6195851025c319f714ea499ea02ba18471c4ae41052c6ba307ee9def0ee122b",
+    "scripts/setup_baseer_ocr.ps1": "26789f174fcf3e65ef013897c6a98d92744ede6a61db0d2eb93f66a5889a3029",
+    "scripts/setup_baseer_ocr.sh": "ff242dbfdbe1bb8b5a7d9ebf5d2ed891c23646eddadd470222c9135795fa7998",
+    "scripts/setup_habibi.ps1": "5c0c4cfd1367169be10a68ea404b3ca3023ebf2ac140db82d5df36b76b6ba682",
+    "scripts/setup_habibi.sh": "a737e7a8266fa47eb1eba3deeed52ff2bc91042646fff3b721afe7edefaf41d8",
+    "scripts/setup_katib_ocr.ps1": "10b3e2a0781bcccec8a344f79b2639d13abcf26904025bf91ed1646fec34115e",
+    "scripts/setup_katib_ocr.sh": "ee59fccd22a76c1d773c40d1e734b6f33e12d04a3e65294c635892d019c9f673",
+    "scripts/setup_paddleocr.ps1": "afaaa71132582aa7bbaaa6cf45ebc6bfffe716ca542da66c0f9e7bb849dca689",
+    "scripts/setup_paddleocr.sh": "2365608707febc705a88df84d4323fae619020011e71cb1f3d0346bcf6deb548",
+    "scripts/setup_paddleocr_vl.ps1": "0840fc9f181b246bff754bff6ad6c28a2aaf80fc0771a745f0577737dea3a806",
+    "scripts/setup_paddleocr_vl.sh": "38d048a154d8c55e9ab4c068a7177e33618d921951c753745ab54312ec24e1ea",
+    "scripts/setup_qari_ocr.ps1": "d8dc9e30df59476dfc737d2538d84523a694c97122196690d175f13e5b5e9e6b",
+    "scripts/setup_qari_ocr.sh": "001792fe72c2b0c1f8015870b964ae0e45a9804b3da275b76e0d06e7b5bf3ead",
+    "scripts/setup_silma.ps1": "6f5219b837f47442a1f60213f4385bf8d79aa7dcfa35c8832c082efef7443ba6",
+    "scripts/setup_silma.sh": "752292c14b89f477376a23490e0d8794aa8749b3b2250833c63d0c41003d09a6",
+    "scripts/setup_supertonic.ps1": "f7982df82b13b2990d7e7505783eba170803abe7209584f7c332fbb82e828140",
+    "scripts/setup_supertonic.sh": "dd9e9a7239d87fdb5f9ee59cbde5562ab5935de7a886dd42a45d6b668d85e30d",
+    "scripts/setup_surya.ps1": "a36c540d7c6a2b3c8b65f6f4db233f684c01b168c37d3e75eca33f58ee52360a",
+    "scripts/setup_surya.sh": "59fb9ada4d50c51df2ed16ca748274691bd256f10fc8f58ddb58a228de9d5365",
+    "scripts/setup_tawkeed_ocr.ps1": "6cada07cb5e21c4a943d709f6012d230ba93c9890f7699cf38a00433bbd593b6",
+    "scripts/setup_tawkeed_ocr.sh": "fd2326592b1adb96bc6d94a434a0ed61ef67183791ef8fc00b1cbdaeb362d619",
+    "scripts/silma_synthesize.py": "20a9d891e9b235008e3ff017103c1cb56e0a0e16eb762dc6c6649c0cf8b2875e",
+    "scripts/supertonic_synthesize.py": "8223e3982de99e06091cff419d9b4584a56823b67c94b1493ce7143dd8c7f4f4",
+    "scripts/surya_extract.py": "7361a8a667779c46aed71fa67b7f869d16f8067b55591d202fa968b8fc7628d7",
+    "scripts/tawkeed_ocr_extract.py": "da554d5620237b70e234032b5525fcee8e9bebe9a924e5750746530c41972318",
+    "scripts/validate_deployment_env.py": "eee9ddcf8ddb24c7709657b5c2584f73afeafd2caac730990e979a28ad37103e",
+    "scripts/verify_pipeline.py": "57359e0e4399352976100f633ce780d9a022e96885e18d29d7f5bd4c4a43a857",
+    "scripts/verify_site.py": "883e682cf6f9c245e1581eeee89fd4178354608123f57d0206f271a04cb8edf6",
+    "scripts/verify_voice.py": "d8fb7e473e47060b2d2f957c5c230807a205e95b1469eef9c32b76d2bc8585b2",
+    "scripts/verify_worker.py": "751f74c6f21694c74049877ff498cce200897be1131e853f9388891d8b047066",
+    "static/app.js": "9adb1801253687d833d8cb9edca833c1ea3ce54a74bacfb2747dbfeb31647118",
+    "static/index.html": "23d74fcfe46c93a7e2b6c12b1916b4567745ab18d52c41e4252ab4993f6d251e",
+    "static/styles.css": "a45485cf99eaae8a46e57437a736ce1ebad2528dbf219c5bc79f124ec3c47164"
+  },
+  "source": "ArabicTranslator",
+  "version": 1
+}

Dockerfile

@@ -0,0 +1,68 @@
+FROM python:3.10-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    WORK_DIR=/data/arabic-translator \
+    DATABASE_PATH=/data/arabic-translator/data/arabic_reader.sqlite3 \
+    TESSDATA_DIR=/usr/share/tesseract-ocr/5/tessdata \
+    ESPEAK_NG_EXE=/usr/bin/espeak-ng \
+    OCR_ENGINE=arabic-max \
+    DEFAULT_VOICE_ID=silma-local \
+    MAX_UPLOAD_MB=512 \
+    OUTPUT_RETENTION_DAYS=7 \
+    OUTPUT_MAX_FILES=25 \
+    AUDIO_FORMAT=mp3 \
+    MP3_BITRATE=96k \
+    SILMA_FULL_NORMALIZER_DEPS=0 \
+    SILMA_ENABLE_NORMALIZER=0 \
+    SILMA_FORCE_TASHKEEL=0 \
+    SILMA_NORMALIZE_NUMBERS=0
+
+ARG INSTALL_QARI_OCR=0
+ARG INSTALL_TAWKEED_OCR=0
+ARG INSTALL_KATIB_OCR=0
+ARG INSTALL_ARABIC_QWEN_OCR=0
+ARG INSTALL_ARABIC_GLM_OCR=0
+ARG INSTALL_BASEER_OCR=0
+ARG INSTALL_PADDLEOCR_VL=0
+ARG INSTALL_SUPERTONIC=0
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    bash \
+    espeak-ng \
+    ffmpeg \
+    libsndfile1 \
+    tesseract-ocr \
+    tesseract-ocr-ara \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt requirements-silma.txt requirements-supertonic.txt requirements-paddleocr.txt requirements-paddleocr-vl.txt requirements-qari-ocr.txt requirements-tawkeed-ocr.txt requirements-katib-ocr.txt requirements-arabic-qwen-ocr.txt requirements-arabic-glm-ocr.txt requirements-baseer-ocr.txt ./
+COPY scripts/setup_silma.sh scripts/setup_supertonic.sh scripts/setup_paddleocr.sh scripts/setup_paddleocr_vl.sh scripts/setup_qari_ocr.sh scripts/setup_tawkeed_ocr.sh scripts/setup_katib_ocr.sh scripts/setup_arabic_qwen_ocr.sh scripts/setup_arabic_glm_ocr.sh scripts/setup_baseer_ocr.sh ./scripts/
+
+RUN python -m venv .venv \
+    && .venv/bin/python -m pip install --upgrade pip \
+    && .venv/bin/python -m pip install -r requirements.txt \
+    && chmod +x scripts/setup_silma.sh scripts/setup_supertonic.sh scripts/setup_paddleocr.sh scripts/setup_paddleocr_vl.sh scripts/setup_qari_ocr.sh scripts/setup_tawkeed_ocr.sh scripts/setup_katib_ocr.sh scripts/setup_arabic_qwen_ocr.sh scripts/setup_arabic_glm_ocr.sh scripts/setup_baseer_ocr.sh \
+    && PYTHON_BIN=python scripts/setup_silma.sh \
+    && PYTHON_BIN=python scripts/setup_paddleocr.sh \
+    && if [ "$INSTALL_SUPERTONIC" = "1" ]; then PYTHON_BIN=python scripts/setup_supertonic.sh; fi \
+    && if [ "$INSTALL_QARI_OCR" = "1" ]; then PYTHON_BIN=python scripts/setup_qari_ocr.sh; fi \
+    && if [ "$INSTALL_TAWKEED_OCR" = "1" ]; then PYTHON_BIN=python scripts/setup_tawkeed_ocr.sh; fi \
+    && if [ "$INSTALL_KATIB_OCR" = "1" ]; then PYTHON_BIN=python scripts/setup_katib_ocr.sh; fi \
+    && if [ "$INSTALL_ARABIC_QWEN_OCR" = "1" ]; then PYTHON_BIN=python scripts/setup_arabic_qwen_ocr.sh; fi \
+    && if [ "$INSTALL_ARABIC_GLM_OCR" = "1" ]; then PYTHON_BIN=python scripts/setup_arabic_glm_ocr.sh; fi \
+    && if [ "$INSTALL_BASEER_OCR" = "1" ]; then PYTHON_BIN=python scripts/setup_baseer_ocr.sh; fi \
+    && if [ "$INSTALL_PADDLEOCR_VL" = "1" ]; then PYTHON_BIN=python scripts/setup_paddleocr_vl.sh; fi
+
+COPY app ./app
+COPY api ./api
+COPY static ./static
+COPY scripts ./scripts
+
+RUN mkdir -p /data/arabic-translator/uploads /data/arabic-translator/outputs /data/arabic-translator/data
+
+EXPOSE 7860
+
+CMD [".venv/bin/python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,60 @@
----
-title: Arabic Audio Reader Worker
-emoji: 🌍
-colorFrom: indigo
-colorTo: blue
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Arabic Audio Reader Worker
+
+This is the Docker worker bundle for the Arabic PDF Reader.
+
+## Hugging Face Space Settings
+
+- SDK: Docker
+- Hardware: free CPU is acceptable for demos, but cold starts and long books can be slow
+- Free CPU Basic currently provides 2 vCPU, 16 GB RAM, and 50 GB non-persistent disk by default; treat generated audio as short-lived unless you add persistent/object storage
+- Port: 7860
+- Default build: installs SILMA, PaddleOCR Arabic, Tesseract Arabic, and eSpeak NG
+- Optional fast CPU voice: set Docker build arg `INSTALL_SUPERTONIC=1` to add Supertonic 3 Arabic-capable local TTS
+- Stronger OCR build: set Docker build arg `INSTALL_TAWKEED_OCR=1`, `INSTALL_KATIB_OCR=1`, `INSTALL_ARABIC_QWEN_OCR=1`, `INSTALL_ARABIC_GLM_OCR=1`, or `INSTALL_BASEER_OCR=1` for Arabic-trained models, or `INSTALL_QARI_OCR=1` for the heavier Arabic-book model
+
+Set these Space secrets:
+
+```text
+ACCESS_CODE=1234
+SECRET_KEY=<generated by outputs\deployment-handoff.md>
+CORS_ORIGINS=https://your-vercel-app.vercel.app
+COOKIE_SAMESITE=none
+COOKIE_SECURE=1
+OCR_ENGINE=arabic-max
+DEFAULT_VOICE_ID=silma-local
+OUTPUT_RETENTION_DAYS=7
+OUTPUT_MAX_FILES=25
+AUDIO_FORMAT=mp3
+MP3_BITRATE=96k
+```
+
+Generate the deployment handoff from the main repo to get the exact `SECRET_KEY`, worker secrets, Vercel environment variables, and final proof command:
+
+```powershell
+python scripts\deployment_handoff.py https://your-space.hf.space --origin https://your-vercel-app.vercel.app --code 1234
+```
+
+Keep `outputs\deployment-handoff.md` private because it contains deployment secrets.
+
+The compact process recommendation is included at `docs/recommended-free-stack.md`, with the machine-readable deployment decision card at `docs/recommended-decision-card.json` and its readable companion at `docs/recommended-decision-card.md`. The current practical default is PyMuPDF embedded text first, `OCR_ENGINE=arabic-max` for scanned Arabic pages, SILMA TTS for the first clean voice, and downloadable worker audio.
+
+Optional stronger-worker build args:
+
+```text
+INSTALL_QARI_OCR=1
+INSTALL_TAWKEED_OCR=1
+INSTALL_KATIB_OCR=1
+INSTALL_ARABIC_QWEN_OCR=1
+INSTALL_ARABIC_GLM_OCR=1
+INSTALL_BASEER_OCR=1
+INSTALL_PADDLEOCR_VL=1
+INSTALL_SUPERTONIC=1
+```
+
+Use `INSTALL_TAWKEED_OCR=1`, `INSTALL_KATIB_OCR=1`, `INSTALL_ARABIC_QWEN_OCR=1`, `INSTALL_ARABIC_GLM_OCR=1`, or `INSTALL_BASEER_OCR=1` first when you want an Arabic-trained OCR model. Use `INSTALL_QARI_OCR=1` when you want the strongest Arabic-book OCR and the worker has enough memory/GPU. Leave heavy options at `0` on free CPU Spaces unless a short benchmark proves the stronger model is worth the cold start, build time, memory, and runtime.
+
+After the Space builds, verify it from your main repo:
+
+```powershell
+python scripts\verify_worker.py https://your-space.hf.space --code 1234 --origin https://your-vercel-app.vercel.app --require-cors --smoke-upload --smoke-scanned --smoke-ocr-engine arabic-max
+```

api/index.py

@@ -0,0 +1,2 @@
+from app.main import app
+

app/__init__.py

@@ -0,0 +1 @@
+

docs/best-free-arabic-pdf-audio-stack.md

@@ -0,0 +1,616 @@
+# Best Free Arabic PDF-To-Audio Stack
+
+Last checked: June 7, 2026.
+
+The source evidence is summarized in `docs/source-evidence.md`; verify the research markers with `python scripts\check_research_sources.py --json`.
+
+## Recommendation
+
+For this project, the best practical free local stack is:
+
+1. PyMuPDF for embedded PDF text.
+2. `OCR_ENGINE=arabic-max` for scanned pages by default; it compares the strongest available Arabic OCR outputs and chooses the cleanest text. When QARI-OCR, Tawkeed, KATIB, Arabic-Qwen, or Baseer is installed, this includes Arabic-trained VLM OCR candidates.
+3. EasyOCR Arabic as a strong alternate for older scans and difficult layouts.
+4. `OCR_ENGINE=best` for short quality tests, which compares the free local OCR engines and picks the best-looking Arabic text.
+5. QARI-OCR as the optional Arabic-native heavy OCR path for strong workers.
+6. Tesseract Arabic as the final fallback.
+7. Speech cleanup that removes repeated headers, page numbers, digit-heavy OCR debris, symbol noise, and tiny layout fragments before TTS.
+8. SILMA TTS for the best local Arabic voice.
+9. Habibi-TTS MSA as an optional newer Arabic voice experiment.
+10. 3arab-TTS 500M as a very new Arabic-only Apache-2.0 voice benchmark.
+11. KaniTTS Arabic as a high-speed Arabic voice benchmark that needs license confirmation.
+12. Emirati VITS Male as an Apache-2.0 Gulf dialect voice benchmark.
+13. MOSS-TTS-Nano as an optional CPU-friendly multilingual Arabic voice benchmark.
+14. OmniVoice as a fresh optional multilingual Arabic voice benchmark.
+15. Lahgtna OmniVoice v2 as a new dialect-only OmniVoice benchmark candidate.
+16. Lahgtna Chatterbox as an optional Arabic dialect voice benchmark.
+17. NAMAA-Saudi-TTS as an MIT Saudi Arabic Chatterbox benchmark.
+18. Egyptian Arabic Chatterbox as an Apache-2.0 dialect-only Chatterbox benchmark.
+19. NileTTS-XTTS as an Apache-2.0 Egyptian Arabic XTTS benchmark.
+20. Arabic XTTS-v2 Egyptian fine-tune as a CPML/base-license dialect benchmark.
+21. Chatterbox-Multilingual ONNX as an MIT CPU/ONNX Arabic-capable voice benchmark.
+21. tts-arabic-onnx as a compact Arabic-only ONNX voice benchmark with license confirmation required.
+22. VoxCPM2 as an optional strong-worker multilingual Arabic voice benchmark.
+23. Voxtral TTS as a personal/non-commercial strong-worker Arabic voice benchmark only.
+24. Egyptian Arabic Qwen3-TTS as a dialect-only external benchmark.
+25. Saudi Arabic Qwen3-TTS and Emirati Qwen3.5-TTS as newer Apache-2.0 Gulf dialect external benchmarks.
+26. DeepSeek-OCR-2 as a latest Apache-2.0 general document OCR benchmark for strong workers.
+27. DeepSeek Arabic OCR v6 as a newer Apache-2.0 Arabic-labeled DeepSeek-OCR external benchmark.
+28. Qwen3-VL Persian/Arabic line OCR as a line-level OCR benchmark only, not a full-page book OCR default.
+29. Arabic handwritten OCR 4-bit Qwen2.5-VL as a lighter Apache-2.0 handwriting/manuscript OCR benchmark.
+30. NAKBA Arabic manuscript line OCR baseline as a line-level manuscript OCR benchmark only.
+31. HAFITH as an Apache-2.0 historical Arabic manuscript line-OCR benchmark.
+32. Glimpse RTL OCR as an Apache-2.0 Arabic/Persian text-line OCR benchmark.
+33. olmOCR Arabic LoRA v2 as an Apache-2.0 full-page Arabic manuscript OCR benchmark.
+34. Arabic OCR Qwen2.5-VL GGUF as a QariOCR-trained external GGUF/Unsloth benchmark for scanned books and mixed Arabic-English documents.
+35. Arabic Legal Documents OCR 1.0 as a domain-specific Gemma-licensed OCR benchmark for legal/form-like Arabic PDFs.
+36. oi-OCR as an Apache-2.0 Arabic-capable PDF/document parser benchmark for structured PDFs.
+37. NuExtract3 as an Apache-2.0 multilingual document-to-Markdown OCR benchmark for hard layouts and multi-page PDFs.
+38. Qianfan-OCR as an Apache-2.0 heavy multilingual document-intelligence OCR benchmark.
+39. Chandra OCR 2 as a strong multilingual structured-document OCR benchmark with modified OpenRAIL-M weights.
+40. dots.ocr as a compact MIT multilingual document-layout OCR benchmark.
+41. Arabic Large Nougat as a GPL-3.0 Arabic book-page OCR-to-Markdown benchmark.
+42. DocTR Arabic FAST/PARSEQ as a classic Arabic OCR detector/recognizer benchmark.
+43. Kraken/eScriptorium Arabic script as a historical-print/manuscript OCR benchmark.
+44. Kairawan/Qalamus manuscript OCR as a free service-only manuscript OCR signal, not a deployable default.
+45. GLM-OCR Arabic/French documents as an administrative/form-like OCR benchmark.
+46. mimoha Arabic OCR as a sparse-card low-priority Arabic OCR watchlist item.
+47. Saudi Chatterbox fine-tune as an Apache-2.0 Saudi dialect voice benchmark.
+48. Saudi TTS as an Apache-2.0 Saudi dialect voice benchmark.
+49. eSpeak NG as the fast local fallback voice.
+
+This is not the theoretically highest-accuracy Arabic OCR stack. The newest open OCR direction is moving toward vision-language document models, especially Arabic-specific VLMs such as QARI-OCR and general document parsers such as PaddleOCR-VL-1.6, but those are heavier than classic OCR and usually need a real worker with more RAM/GPU. For a free family website that needs to process 100 MB+ Arabic books reliably, the best practical default is still a lightweight OCR engine plus a per-book sample benchmark.
+
+## Decision Matrix
+
+| Layer | Chosen default | Why | When to switch |
+| --- | --- | --- | --- |
+| Embedded PDF text | PyMuPDF | Free, fast, and avoids OCR when the PDF already has text. | Do not switch unless extraction order is broken. |
+| Scanned Arabic OCR | Maximum Arabic OCR mode | It compares QARI-OCR, Tawkeed, KATIB, Arabic-Qwen, Baseer, PaddleOCR-VL, PaddleOCR Arabic PP-OCRv5, EasyOCR Arabic, Surya, and Tesseract Arabic, then keeps the best cleaned Arabic text. | Use `OCR_ENGINE=paddleocr` only when speed matters more than comparison. |
+| Single-engine OCR | PaddleOCR Arabic PP-OCRv5 | Official PaddleOCR docs list `arabic_PP-OCRv5_mobile_rec` for Arabic-script recognition, and it is lightweight enough for CPU workers. | Use EasyOCR or Tesseract when the per-book benchmark scores them better. |
+| OCR comparison | `OCR_ENGINE=best` on short samples only | It compares available free engines and picks the best cleaned Arabic text. | Do not use for full 300+ page books unless runtime is acceptable. |
+| Arabic-native optional OCR | QARI-OCR 0.4 | QARI-OCR 0.4 is fine-tuned for OCR on Islamic books and Arabic manuscripts, with Apache-2.0 model licensing. | Best Arabic-focused quality upgrade to benchmark on a GPU/strong worker. |
+| Arabic-native external OCR | QARI-OCR 0.4 GGUF | GGUF packaging of QARI-OCR 0.4 for external runtime experiments. | Keep benchmark-only until the exact vision runner and same-page text quality beat the wired QARI sidecar. |
+| Smaller Arabic-trained optional OCR | KATIB 0.8B | KATIB is fine-tuned for Arabic printed and handwritten OCR while being much smaller than QARI. | Try before QARI on smaller workers, then keep it only if it wins on the book sample. |
+| Small Arabic-trained optional OCR | Arabic-Qwen3.5-OCR-v4 | Apache-2.0 0.9B Arabic OCR VLM for printed, handwritten, classical, and diacritic-heavy text. | Try alongside KATIB on short samples; keep only if it wins on the target pages. |
+| Fresh Arabic OCR watchlist | aNS Qwen3-VL Arabic OCR v3 | Qwen3-VL-2B Arabic OCR fine-tune with a public Hugging Face card and no hosted inference provider. | Keep external until license fit, runtime, and same-page Arabic text quality beat QARI/KATIB/Arabic-Qwen/Baseer. |
+| Structured Arabic OCR watchlist | Waraqon v3 Arabic OCR HTML Qari | Apache-2.0 Qari-family Arabic OCR model aimed at HTML/structured output. | Benchmark externally for complex pages; normalize markup to readable Arabic and promote only if it preserves book text better than the wired stack. |
+| Latest general OCR watchlist | DeepSeek-OCR-2 | Official Apache-2.0 3B DeepSeek OCR successor with 2026 paper/model-card references and public document OCR benchmark results. | Benchmark externally only on strong-worker hardware; it is not Arabic-specific, so promote only if it beats QARI/KATIB/Baseer/Arabic-Qwen on the same book pages. |
+| Latest Arabic DeepSeek OCR watchlist | Loay Arabic-OCR-DeepSeek-OCR-2 | Apache-2.0 Arabic fine-tune of DeepSeek-OCR-2 for Arabic OCR and layout analysis. | Benchmark externally on the same exported page images before any sidecar work; it is promising but needs strong-worker proof. |
+| DeepSeek Arabic OCR watchlist | DeepSeek Arabic OCR v6 | Apache-2.0 Arabic-labeled DeepSeek-OCR fine-tune and newer than v4/v5. | Keep external until it proves better on the exported Arabic page images; the card has sparse Arabic-book evaluation detail and no hosted inference provider. |
+| Handwritten OCR watchlist | Arabic-English handwritten OCR Qwen3-VL | Apache-2.0 Qwen3-VL-4B handwritten OCR model for Arabic and English. | Keep external for handwriting-heavy pages; the model card says research-oriented and it is not deployed by inference providers. |
+| Handwritten OCR watchlist | Arabic-English handwritten OCR v3 | Apache-2.0 Qwen2.5-VL 3B-class handwritten/manuscript OCR model for Arabic and English. | Keep external for handwriting-heavy or manuscript pages; it is large and not deployed by inference providers. |
+| Quantized handwritten OCR watchlist | Arabic handwritten OCR 4-bit Qwen2.5-VL | Apache-2.0 4-bit Arabic handwritten OCR checkpoint with about 2.44GB of model assets. | Benchmark externally when handwriting/manuscript pages matter and the full handwritten checkpoint is too heavy; promote only if same-page text beats the wired stack without hallucinations. |
+| Manuscript line OCR watchlist | NAKBA Arabic manuscript line OCR baseline | Qwen3-VL-8B LoRA baseline for the NAKBA NLP 2026 Arabic manuscript understanding shared task, evaluated on line images. | Keep external and line-level only unless a preprocessing step crops pages into lines; confirm license fit before production. |
+| Historical manuscript line OCR watchlist | HAFITH | Apache-2.0 Arabic-native 642M OCR model for historical manuscript line recognition, with 5.10% CER claims and Arabic-native tokenization. | Keep external and line-level only; it needs text-line segmentation before inference, so it is not a full-page PDF default. |
+| RTL line OCR watchlist | Glimpse RTL OCR | Apache-2.0 Arabic/Persian RTL text-line OCR fine-tune with 6.97% CER claims on unseen RTL text lines. | Keep external and line-level only; it needs page images cropped into text lines before inference. |
+| Full-page manuscript OCR watchlist | olmOCR Arabic LoRA v2 | Apache-2.0 LoRA for full-page Arabic manuscript OCR on an olmOCR 7B base. | Benchmark externally on a large worker; keep out of default because 7B base/runtime/license confirmation is needed. |
+| GGUF OCR watchlist | Arabic OCR Qwen2.5-VL GGUF | QariOCR-v0.3-trained Arabic/English OCR fine-tune for scanned books, religious text, handwriting, and mixed-language documents on a Qwen2.5-VL 7B GGUF/Unsloth path. | Benchmark externally on a large worker; confirm license fit and keep only if it beats QARI/KATIB/Arabic-Qwen/Baseer on the same selected pages. |
+| Line-level OCR watchlist | Qwen3-VL Persian/Arabic line OCR | Apache-2.0 Qwen3-VL 2B fine-tune for Persian/Arabic text-line OCR. | Keep external unless pages are cropped into text lines; the model card says it is not designed for full-page OCR. |
+| Large Arabic OCR watchlist | Loay Arabic-OCR-Qwen2.5-VL-7B | Arabic OCR fine-tune of Qwen2.5-VL-7B for Arabic text from images. | Benchmark externally only on a large worker; 7B-class runtime is too heavy for the normal free default. |
+| Arabic manuscript OCR watchlist | Ketaba-OCR LoRA | Apache-2.0 Arabic manuscript LoRA with strong benchmark claims, but it needs a separate base VLM plus adapter setup. | Benchmark externally on selected page images when the wired Arabic OCR stack fails. |
+| Arabic manuscript OCR watchlist | Qari-OCR-LoRA | Apache-2.0 experimental QARI-family LoRA from the NakbaNLP 2026 Arabic manuscript OCR task; its model card says Ketaba was the primary winning submission. | Benchmark externally only as a secondary manuscript comparison after QARI 0.4, Ketaba, and the wired stack. |
+| Arabic-first optional OCR | Tawkeed OCR | Apache-2.0 Arabic-first QARI v0.3 fork tuned for Arabic documents, handwriting, scene text, and edge-style deployment. | Wired as `OCR_ENGINE=tawkeed-ocr`; benchmark on short samples before full books, especially when QARI 4B is too heavy. |
+| High-end optional OCR | PaddleOCR-VL-1.6 | The newest official PaddleOCR-VL document parser is an Apache-2.0 0.9B VLM path with state-of-the-art public document parsing claims and 109-language support. | Best general document-parser upgrade for a GPU/large-CPU worker; not the first default for free family hosting. |
+| External document parser watchlist | oi-OCR | Apache-2.0 English/Arabic PDF document parser with April 2026 ParseBench claims for layout, tables, charts, and faithfulness. | Benchmark externally for structured PDFs; it is not Arabic-book-specific and has no inference provider deployment. |
+| Multilingual document parser watchlist | NuExtract3 | Apache-2.0 4B document VLM for OCR, document-to-Markdown, tables, forms, invoices, contracts, multilingual documents, and multi-page PDF examples. | Benchmark externally for hard layouts; not the default Arabic-book OCR unless same-page scoring beats the Arabic-trained stack. |
+| Large document parser watchlist | Qianfan-OCR | Apache-2.0 5B multilingual document-intelligence OCR/VLM with strong general document benchmark claims. | Benchmark externally only on a GPU/large worker; it is not Arabic-book-specific and is too heavy for the default free family worker. |
+| Structured document parser watchlist | Chandra OCR 2 | 4B multilingual OCR/layout model for Markdown, HTML, JSON, tables, forms, and handwriting, with Arabic included among 90+ languages. | Benchmark externally for complex layouts only; modified OpenRAIL-M weights and GPU-heavy runtime keep it out of the default family-site stack. |
+| Compact document parser watchlist | dots.ocr | MIT 1.7B multilingual document parser for layout detection, reading order, tables, formulas, and content recognition. | Benchmark externally for difficult layouts or mixed pages; not Arabic-book-specific, so promote only if same-page scoring beats the Arabic-trained stack. |
+| Arabic book OCR-to-Markdown watchlist | Arabic Large Nougat | GPL-3.0 0.4B Arabic book-page OCR model for structured Markdown/text extraction. | Benchmark externally only; keep out of the default public worker because GPL licensing and model-card hallucination/context-length caveats need careful handling. |
+| Classic Arabic OCR watchlist | DocTR Arabic FAST/PARSEQ | Arabic FAST detector with an Arabic PARSEQ recognizer path. | Benchmark externally when VLM OCR is too heavy; confirm recognizer licensing and compare text ordering before promotion. |
+| Historical Arabic-script OCR watchlist | Kraken/eScriptorium Arabic script | Open-source ATR/OCR workflow for historical and non-Latin scripts, useful when pages look like older print, manuscripts, marginalia, or archival material. | Benchmark externally with an Arabic-script Kraken model or line-cropped eScriptorium workflow; keep out of the default worker until the selected model/license and page segmentation are proven on the book. |
+| Service-only manuscript OCR signal | Kairawan/Qalamus manuscript OCR | Free 2026 Arabic and Islamic manuscript transcription service signal, useful evidence that Arabic manuscript OCR is improving. | Keep external only unless a reusable open engine, API terms, privacy story, and same-page scoring beat QARI/KATIB/Kraken/HAFITH on the selected sample. |
+| Administrative OCR watchlist | GLM-OCR Arabic/French documents | GLM-OCR LoRA fine-tuned on Arabic/French scanned documents, forms, receipts, newspapers, and official documents. | Benchmark for structured or administrative PDFs, not ordinary book narration. |
+| Sparse-card OCR watchlist | mimoha Arabic OCR | Apache-2.0 Arabic OCR model card with minimal public details. | Keep low priority until a clean local runner and stronger evaluation details are available. |
+| Compact optional OCR VLM | Falcon-OCR | Apache-2.0 300M document OCR VLM from TII, with plain-text, formula, and table output modes. | Track for strong-worker benchmarks; do not default until it beats QARI/Paddle/Tesseract on Arabic book samples. |
+| Heavy optional OCR | Surya / Chandra | Current Datalab document models support layout, reading order, and 90+ languages including Arabic, but weights/licensing and runtime are less simple than PaddleOCR. | Use only for difficult scans on a worker that can handle heavier VLM-style OCR. |
+| Arabic-specific VLM OCR | Baseer OCR | Apache-2.0 Arabic document OCR fine-tuned from Qwen2-VL-2B, useful to track for difficult Arabic legal/complex layouts. | Promising, but 2B parameters and no default hosted inference provider make it optional research, not the default pipeline. |
+| Arabic OCR VLM sidecar | Arabic-GLM-OCR-v2 | Recent Apache-2.0 Arabic OCR VLM with model-card claims for Arabic document extraction and noise reduction. | Wired as an optional sidecar; benchmark on the same 5-page sample before any full-book run. |
+| Large Arabic OCR LoRA watchlist | DIMI Arabic OCR v2 | Apache-2.0 Arabic OCR LoRA based on Qwen2.5-VL-7B with model-card claims for improved diacritics handling and printed-document extraction. | Benchmark externally only on a large worker; 7B-class runtime is too heavy for the normal free default. |
+| Darija OCR watchlist | AtlasOCR | First open-source Darija/Moroccan Arabic OCR model based on Qwen2.5-VL 3B. | Use only for Moroccan/Darija PDFs and confirm license terms before production use. |
+| Legal/structured OCR watchlist | Arabic Legal Documents OCR 1.0 | Gemma-licensed Gemma-3-4B-IT fine-tune for low-quality scanned Arabic legal documents. | Benchmark externally only for legal or form-like PDFs; not a permissive default for ordinary book narration. |
+| OCR correction research | Raqim post-OCR correction | 2026 open-access research on Arabic OCR correction using dictionary-based correction and LLMs. | Do not run automatically before TTS; correction can alter exact book/religious wording. |
+| Arabic voice | SILMA TTS | Free/open Arabic-English TTS, Arabic Fusha/MSA support, normalization/tashkeel features, permissive model license. | Try Habibi MSA when you can afford a heavier optional sidecar; use eSpeak NG when speed matters more than naturalness. |
+| Optional Arabic voice | Habibi-TTS MSA | Newer Arabic F5-TTS family project; the MSA specialized model is Apache-2.0. | Keep it optional because the unified and some dialect models have non-commercial limits. |
+| Optional Arabic-only voice | 3arab-TTS 500M | Apache-2.0 Arabic-only 500M RF-DiT text-to-speech model, with a VoiceDesign variant updated in June 2026. | Benchmark externally on the same cleaned sample; too new to promote before long-form listening tests. |
+| Optional high-speed Arabic voice | KaniTTS Arabic | Arabic-only 400M TTS model with high-speed/low-latency claims, but current Hugging Face metadata reports `other` for license. | Benchmark externally on the same cleaned sample; promote only if license fit is confirmed and it preserves words and pacing better than SILMA/Habibi. |
+| Optional Gulf dialect voice | Emirati VITS Male | Apache-2.0 bilingual Emirati Arabic/English VITS voice. | Benchmark only when Gulf/Emirati pronunciation fits the PDF; not the default MSA audiobook voice. |
+| Optional CPU-friendly voice | MOSS-TTS-Nano | Apache-2.0 multilingual 0.1B TTS with Arabic support, packaged CLI, and ONNX CPU path. | Benchmark externally with an Arabic reference voice before wiring it into the app; SILMA remains the stable default. |
+| Optional CPU-friendly voice | Supertonic 3 | OpenRAIL multilingual 99M ONNX TTS with Arabic support and no GPU requirement. | Wired as `supertonic-ar` for local benchmarking; compare comfort against SILMA/Habibi before using it for full books. |
+| Optional multilingual voice | OmniVoice | Apache-2.0 0.6B zero-shot TTS with 646-language support and Arabic included. | Fresh benchmark candidate; compare listenability against SILMA/Habibi before app wiring. |
+| Optional Arabic adapter voice | OmniVoice Arabic LoRA | Apache-2.0 Arabic LoRA adapter for OmniVoice. | Try only after base OmniVoice works; compare against SILMA/Habibi on the same sample. |
+| Optional Arabic dialect voice | Lahgtna OmniVoice v2 | New Arabic-dialect OmniVoice fine-tune with broad dialect tags and diacritics support. | Benchmark externally for dialectal content; confirm licensing before production and keep SILMA/Habibi first for MSA books. |
+| Optional Arabic dialect voice | Lahgtna Chatterbox | MIT Arabic dialect TTS based on Chatterbox multilingual with several dialect tags. | Benchmark externally; the model card notes possible repetition, so long-form audiobook stability must be tested. |
+| Optional Saudi dialect voice | NAMAA-Saudi-TTS | MIT Chatterbox Multilingual fine-tune for natural Saudi Arabic dialect speech. | Benchmark only for Saudi/Gulf dialect fit; its model card says it targets everyday Saudi speech rather than MSA books. |
+| Optional Egyptian dialect voice | NAMAA-Egyptian-TTS | MIT Chatterbox Multilingual fine-tune for natural Egyptian Arabic dialect speech. | Benchmark only for Egyptian/dialectal PDFs; its model card targets everyday Egyptian speech rather than MSA books. |
+| Optional Saudi dialect voice | Saudi Chatterbox fine-tune | Apache-2.0 Chatterbox Multilingual T3 fine-tune for Saudi Arabic speech. | Benchmark beside NAMAA-Saudi-TTS and Saudi Qwen3-TTS for Gulf material; not a default MSA book voice. |
+| Optional Saudi dialect voice | Saudi TTS | Apache-2.0 Saudi Arabic TTS model. | Benchmark beside NAMAA-Saudi-TTS, Saudi Chatterbox fine-tune, and Saudi Qwen3-TTS for Gulf material; not a default MSA book voice. |
+| Optional Egyptian dialect voice | Egyptian Arabic Chatterbox | Apache-2.0 Chatterbox fine-tune on 120 hours of Egyptian Arabic. | Benchmark only for Egyptian/dialectal PDFs; not the default MSA audiobook voice and GPU is recommended. |
+| Optional Egyptian dialect voice | NileTTS-XTTS | Apache-2.0 XTTS v2 fine-tune from the 2026 NileTTS paper, trained on 38 hours of Egyptian Arabic. | Benchmark only for Egyptian/dialectal PDFs; it is not tuned for MSA book narration. |
+| Optional Egyptian dialect voice | Arabic XTTS-v2 Egyptian fine-tune | MIT project on top of XTTS-v2/Coqui Public Model License base, with Egyptian speaker fine-tuning and same-text comparisons. | Benchmark only for Egyptian/dialectal PDFs after license fit is acceptable; not the permissive default MSA book voice. |
+| Optional multilingual voice | Chatterbox-Multilingual | MIT multilingual TTS/voice-cloning project with Arabic listed among supported languages. | Benchmark externally against SILMA/Habibi on the exact same cleaned text before wiring. |
+| Optional Arabic Chatterbox voice | Chatterbox Arabic fine-tune | MIT LoRA/adapter for Chatterbox-Multilingual that claims better Arabic pronunciation, diacritics, intonation, MSA, and dialect support. | Benchmark externally against SILMA/Habibi on the exact same cleaned text; prove long-form stability before wiring. |
+| Optional CPU/ONNX multilingual voice | Chatterbox-Multilingual ONNX | MIT ONNX packaging for Chatterbox-Multilingual with Arabic listed among supported languages. | Benchmark externally on the same cleaned text to see whether CPU/ONNX runtime is practical for the free worker path. |
+| Optional compact Arabic ONNX voice | tts-arabic-onnx | Arabic-only FastPitch/MixerTTS ONNX package with small models, vocoder choices, speaker IDs, pace, and vowelizer options. | Benchmark externally for CPU practicality, but confirm overall model/repo licensing before production use. |
+| Optional Classical Arabic voice | Spark-TTS Arabic | Apache-2.0 Spark-TTS fine-tune on ClArTTS. | Benchmark externally only with diacritized input/reference audio; not a simple default. |
+| Optional dialect voice | Sofelia-TTS | Apache-2.0 Palestinian Arabic TTS/voice-cloning model. | Use only for Palestinian/dialectal content benchmarks, not standard MSA books. |
+| Optional strong-worker voice | VoxCPM2 | Apache-2.0 multilingual TTS with Arabic support, 2B parameters, 48 kHz output, and voice design/cloning. | Benchmark only on GPU/large worker; SILMA remains the practical Arabic-focused default. |
+| Personal/non-commercial strong-worker voice | Voxtral TTS | Mistral open-weight 4B TTS with Arabic among 9 listed languages and strong latency/quality claims. | Do not default for the public/family site because the model card lists `cc-by-nc-4.0` and 16GB+ GPU guidance. |
+| Personal/non-commercial voice caution | Arabic-F5-TTS-v2 | MSA F5-TTS fine-tune with strong Arabic sample claims. | Do not use as the default public free app voice because it is non-commercial and requires fully diacritized Arabic. |
+| Do-not-promote-yet TTS | Qwen3-TTS | Apache-2.0 and high quality, but official released model cards list 10 languages and do not include Arabic. | Track future Arabic checkpoints/fine-tunes; do not add to the Arabic reader dropdown yet. |
+| Dialect-only Qwen3-TTS benchmark | Egyptian Arabic Qwen3-TTS | Apache-2.0 1.7B Qwen3-TTS fine-tune for Egyptian Arabic with about 25 hours of clean Egyptian speech. | Benchmark only for Egyptian/dialectal content; it is too large and dialect-specific for the normal MSA book default. |
+| Dialect-only Qwen3-TTS benchmark | Saudi Arabic Qwen3-TTS | Apache-2.0 1.7B Qwen3-TTS fine-tune for Saudi/KSA Arabic speech. | Benchmark only when Saudi/Gulf pronunciation fits the PDF; keep SILMA/Habibi first for MSA books. |
+| Dialect-only Qwen3.5-TTS benchmark | Emirati Qwen3.5-TTS | Apache-2.0 Emirati Arabic Qwen3-TTS-family fine-tune. | Benchmark beside Emirati VITS Male for Gulf/Emirati material; do not make it the default MSA audiobook voice. |
+| Audio format | MP3 on workers, WAV locally | MP3 is much smaller for downloads when `ffmpeg` is available. | WAV is fine for short local tests. |
+
+## Why Arabic Specialist OCR Is The Default
+
+On the one-page sample from the user's scanned Arabic book:
+
+```text
+EasyOCR:   4,207 characters, 743 Arabic words
+PaddleOCR: 2,546 characters, 495 Arabic words
+Tesseract: 4,344 characters, 767 Arabic words
+```
+
+Tesseract was fastest and extracted a high volume of text, but its preview included more page-layout noise. PaddleOCR was faster than EasyOCR and uses a current Arabic PP-OCRv5 recognition model, but it dropped and garbled more text on this specific book page. EasyOCR had the cleanest main-text preview on that sample, so it remains an important alternate. Arabic specialist mode is now the default because it compares Arabic-configured recognizers and picks the cleanest text for the book page. Plain PaddleOCR remains available when speed matters more than automatic comparison.
+
+The important rule is: default to maximum Arabic-trained OCR for a new scanned book, but benchmark a representative sample before processing a long book. A single OCR engine is not consistently best across Arabic fonts, scan quality, page skew, and book layouts. QARI is the best Arabic-book model to try on a strong worker; KATIB is the smaller Arabic-trained model to try when QARI is too heavy.
+
+For short samples, the app supports `OCR_ENGINE=best`. That mode runs the available free local OCR engines, tries multiple Tesseract page segmentation modes, scores the cleaned Arabic text by Arabic-word volume, common-word hits, placeholder characters, repeated layout lines, tiny-line noise, digit-heavy lines, symbol noise, and Latin noise, then uses the best-scoring output. It is not the default for full books because it can multiply OCR time on 100 MB+ PDFs.
+
+The default best-mode settings are:
+
+```text
+BEST_OCR_RENDER_ZOOMS=1.5
+BEST_TESSERACT_PSMS=4
+```
+
+The render-zoom list is deliberately conservative. On this Windows test machine, adding `2.25` made the corrected one-page best-mode benchmark too slow for a routine website flow. If you still want a high-resolution bakeoff for a difficult page, temporarily set:
+
+```text
+BEST_OCR_RENDER_ZOOMS=1.5,2.25
+BEST_TESSERACT_PSMS=4,6
+```
+
+Use that only on quick tests or selected sample pages first. If the higher-resolution candidate clearly wins on a book, set the matching single-engine render zoom for the full run.
+
+The app also cleans the selected text before speech. This matters because the most accurate-looking OCR output can still include page numbers, repeated book headers, digit-heavy layout fragments, and symbol debris that would sound terrible if read aloud. The TTS-specific cleanup normalizes Arabic-Indic digits, removes tatweel and decorative Quran annotation marks, expands common Arabic ligatures such as `ﷺ`, and fixes punctuation spacing while preserving useful Arabic diacritics.
+
+The dry-run and benchmark tools report a text quality status before audio is generated. `quality=good` means the cleaned Arabic text is ready to send to TTS, `quality=warning` means the text is usable but still has minor artifacts, and `quality=poor` means OCR should be fixed before creating audio.
+
+The web job path uses the same gate in local, worker, and browser-cloud modes. Poor text does not proceed to speech generation, which protects free-worker CPU time and hosted TTS calls from audio that would not be listenable.
+
+For new books, the website defaults to a first-5-pages quick test. That keeps large scanned PDFs from tying up the free worker before OCR quality and pronunciation are known.
+
+When the opening pages are not representative, use `scripts/select_test_pages.py` to build a small sample from the most text-dense pages. It scores embedded Arabic text and low-resolution ink density, so it also works as a rough selector for scanned books.
+
+Voice quality should be tested the same way OCR quality is tested. Run `scripts/benchmark_voices.py --write-report outputs/voice-benchmark-report.md` to synthesize the same Arabic sample with SILMA, optional Habibi MSA, optional Supertonic 3, and eSpeak NG. For external candidates like 3arab-TTS 500M, KaniTTS Arabic, Emirati VITS Male, MOSS-TTS-Nano, OmniVoice/Arabic LoRA, Lahgtna OmniVoice v2, Lahgtna Chatterbox, NAMAA-Saudi-TTS, NAMAA-Egyptian-TTS, Saudi Chatterbox fine-tune, Chatterbox Arabic fine-tune, Saudi TTS, Egyptian Arabic Chatterbox, NileTTS-XTTS, Arabic XTTS-v2 Egyptian fine-tune, Chatterbox-Multilingual, Chatterbox-Multilingual ONNX, tts-arabic-onnx, Spark-TTS Arabic, Sofelia-TTS, Egyptian Arabic Qwen3-TTS, Saudi Arabic Qwen3-TTS, Emirati Qwen3.5-TTS, VoxCPM2, and personal/non-commercial Voxtral TTS, run `scripts/export_tts_sample.py C:\path\to\arabic-book.pdf --env-file outputs\recommended-ocr.env --out-dir outputs\external-tts-sample` and use the generated `outputs\external-tts-sample\arabic-tts-sample.txt` for every model. For external OCR candidates like QARI-OCR 0.4 GGUF, Loay Arabic-OCR-DeepSeek-OCR-2, DeepSeek-OCR-2, DeepSeek Arabic OCR v6, aNS Qwen3-VL Arabic OCR v3, Waraqon v3 Arabic OCR HTML Qari, DIMI Arabic OCR v2, Loay Arabic-OCR-Qwen2.5-VL-7B, Arabic-English handwritten OCR Qwen3-VL, Arabic-English handwritten OCR v3, Arabic handwritten OCR 4-bit Qwen2.5-VL, NAKBA Arabic manuscript line OCR baseline, HAFITH, Glimpse RTL OCR, olmOCR Arabic LoRA v2, Arabic OCR Qwen2.5-VL GGUF, Qwen3-VL Persian/Arabic line OCR, AtlasOCR, Ketaba-OCR, Qari-OCR-LoRA, DocTR Arabic FAST/PARSEQ, Kraken/eScriptorium Arabic script, Kairawan/Qalamus manuscript OCR, GLM-OCR Arabic/French documents, mimoha Arabic OCR, oi-OCR, Qianfan-OCR, and Falcon-OCR, run `scripts/export_ocr_sample_images.py C:\path\to\arabic-book.pdf --out-dir outputs\external-ocr-sample` and use the generated `page-*.png` files for every model. Then run `scripts\score_external_ocr.py` on the resulting text files so the external text is judged with the same Arabic speech-readiness metrics as the app. Tawkeed, Arabic-GLM-OCR-v2, Arabic-Qwen3.5-OCR-v4, and Baseer are already wired as optional sidecars, but you can still score external output if you have not installed the sidecars locally. The reports give timing and file paths, but the final choice should be made by listening to the audio samples and reading the OCR text because Arabic pronunciation, pacing, reading order, and comfort matter more than raw speed.
+
+On the one-page scanned Arabic book sample, the corrected `OCR_ENGINE=best` benchmark selected Tesseract at 2x render scale with page segmentation mode 4:
+
+```text
+easyocr@1.5x=3668.4
+paddleocr@1.5x=2479.5
+tesseract@2x-psm4=3736.0
+tesseract@2x-psm6=3255.5
+selected=tesseract@2x-psm4
+```
+
+That comparison took 260.83 seconds for one page on this Windows machine. The app now keeps Arabic specialist mode as the normal quality default because it catches cases where a single Arabic OCR engine fragments text. Use plain `OCR_ENGINE=paddleocr` only when you need a faster single-engine full-book run.
+
+`scripts/benchmark_ocr.py` now prints a concrete full-book environment recommendation from the winning sample extraction, such as `OCR_ENGINE=tesseract OCR_RENDER_ZOOM=2 TESSERACT_PSM=4`. This keeps the expensive comparison step separate from the long production run.
+
+## Research Notes
+
+- EasyOCR supports Arabic and many other scripts, and remains easy to run locally on CPU.
+- PaddleOCR 3.x includes `arabic_PP-OCRv5_mobile_rec`, an Arabic-script recognition model listed for Arabic, Persian, Uyghur, Urdu, Pashto, Kurdish, Sindhi, Balochi, and English. The same documentation reports 81.27 accuracy on its Arabic dataset with 22.83 improvement over the previous generation.
+- The PP-OCRv5 paper describes a 5M-parameter specialized OCR system intended to stay lightweight while competing with much larger OCR models on standard benchmarks. That supports using it as the practical free default rather than jumping straight to a large VLM.
+- QARI-OCR 0.4 is an Apache-2.0 Arabic OCR VLM on Hugging Face, built on Qwen3-VL-4B and fine-tuned on Arabic book/manuscript OCR pairs. This is now the most directly relevant Arabic-specific OCR upgrade in the repo. The older QARI-OCR v0.3 2B model remains configurable with `QARI_OCR_MODEL` for smaller workers.
+- QARI-OCR 0.4 GGUF is an external benchmark path for testing QARI-style Arabic book OCR with a GGUF runtime. Keep it benchmark-only until the exact vision runner, image-prompt format, speed, and text quality beat the wired QARI sidecar on the same selected pages.
+- KATIB 0.8B is an Apache-2.0 Arabic OCR VLM fine-tuned for Arabic printed and handwritten text. It is wired as the smaller Arabic-trained sidecar to try before the heavier QARI path.
+- Ketaba-OCR LoRA is an Apache-2.0 Arabic manuscript OCR benchmark candidate. Keep it external for now because it requires a Qwen2.5-VL base model plus adapter setup rather than a simple sidecar.
+- Qari-OCR-LoRA is an Apache-2.0 QARI-family manuscript LoRA from the NakbaNLP 2026 Arabic manuscript OCR task. Keep it secondary to Ketaba because its own model card describes Ketaba as the primary winning model.
+- Tawkeed OCR is an Apache-2.0 Arabic-first OCR model forked from QARI-OCR v0.3 and fine-tuned for Arabic documents, handwriting, and scene text. It is wired as `OCR_ENGINE=tawkeed-ocr`, and is most useful when QARI-OCR 0.4 is too heavy or when edge-style Arabic OCR matters.
+- PaddleOCR-VL-1.6 now has a June 2026 paper signal in addition to the model card and official PaddleOCR docs. It is described as a 0.9B document parsing VLM with 96.3% OmniDocBench v1.6 accuracy, 109-language support, and state-of-the-art results across text, formulas, and tables. This is the most important general free/open OCR direction to watch for a stronger hosted worker.
+- oi-OCR is an Apache-2.0 Arabic-capable PDF/document parser with April 2026 ParseBench claims. Keep it external and score it on the same exported page images because structured Markdown/table extraction is different from clean long-form Arabic book transcription.
+- NuExtract3 is an Apache-2.0 4B multilingual document understanding model for OCR, document-to-Markdown, structured extraction, and multi-page PDF workflows. It is useful for hard layouts, forms, tables, and contracts, but it is not Arabic-book-specific and should stay external until same-page scoring proves it beats QARI/KATIB/Arabic-Qwen/Baseer.
+- Qianfan-OCR is an Apache-2.0 5B multilingual document-intelligence OCR/VLM. It has strong general document benchmark claims and public model-card usage examples, but it is not Arabic-book-specific and needs a GPU/large-worker external benchmark before it should influence this app.
+- Chandra OCR 2 is a 4B multilingual structured-document OCR model with Arabic support, Markdown/HTML/JSON output, and strong layout/table/form claims. Its code is Apache-2.0, but the weights are modified OpenRAIL-M, so it stays in the external benchmark lane for personal/family testing rather than the default hosted stack.
+- dots.ocr is an MIT 1.7B multilingual document parser that combines layout detection and content recognition, including reading-order, table, and formula handling. It is promising for complex Arabic layouts, but not Arabic-book-specific, so it stays external until same-page scoring beats the Arabic-trained stack.
+- DocTR Arabic FAST/PARSEQ is a classic OCR alternative: the FAST detector card is Apache-2.0 and designed to pair with an Arabic PARSEQ recognizer. Keep it external until the recognizer license and same-page Arabic book accuracy are confirmed.
+- Kairawan/Qalamus manuscript OCR is a free 2026 web-service signal for Arabic manuscript transcription, not a reusable worker dependency yet. Keep it external unless an open package/API terms/privacy path becomes clear and same-page scoring beats the wired Arabic OCR stack.
+- GLM-OCR Arabic/French documents is a recent GLM-OCR LoRA fine-tune for scanned Arabic/French administrative documents. It belongs in the form/newspaper/official-document benchmark lane, not the default book OCR lane.
+- mimoha Arabic OCR is an Apache-2.0 sparse-card Arabic OCR watchlist item. Keep it low priority unless a clean local runner and stronger evaluation details appear.
+- Surya is promising and supports OCR, layout analysis, reading order, and table recognition in 90+ languages. Current Surya 2 is a 650M-parameter document OCR model that can use `llama.cpp` or `vllm`, making it a better future upgrade path than a first default for a simple family website.
+- Surya's code is Apache-2.0, but its model weights use a modified AI Pubs OpenRAIL-M license that is free for research, personal use, and startups under the stated revenue/funding threshold. That is fine for a family/personal project but less simple than PaddleOCR's default path.
+- SILMA TTS is a 150M-parameter Arabic/English TTS model with Arabic Fusha/MSA support, diacritization, text normalization, accepts text with or without tashkeel, MIT code, and Apache-2.0 model weights. SILMA's Hugging Face launch article also calls out Arabic text handling, chunking, normalization, robustness, and audio-quality improvements. It is currently the best free local Arabic voice in this project because it is Arabic-focused, permissively licensed, and practical to run as a worker sidecar.
+- SILMA includes Arabic diacritization and text normalization features. This project exposes them through `SILMA_ENABLE_NORMALIZER`, `SILMA_FORCE_TASHKEEL`, and `SILMA_NORMALIZE_NUMBERS`; they are off by default in the Windows sidecar and Docker worker because those setups use dependency stubs. On Linux, set `SILMA_FULL_NORMALIZER_DEPS=1` during setup/build if you want to install and test the full packages.
+- Mishkala Tashkeel is a lightweight Apache-2.0 Arabic diacritization model to test as a pronunciation preprocessor. Keep it external until listening tests prove it improves the exact book sample, because wrong automatic harakat can make Arabic narration sound worse or subtly change perceived meaning.
+- Tashkeel-350M is a larger Apache-2.0 Arabic diacritization benchmark. Compare it beside Mishkala on the same cleaned sample, because a larger preprocessor can improve pronunciation for one book and still make another book less comfortable or less faithful.
+- Mushkil is an Apache-2.0 AraT5V2 Arabic diacritization benchmark. Compare it beside Mishkala and Tashkeel-350M on the same cleaned sample, and keep it external unless it improves pronunciation while preserving meaning and long-listen comfort.
+- Thaka KSAA-2026 speech diacritization is a late-May 2026 shared-task-winning research signal for Arabic diacritization using speech plus text. Track it for future permissive code or checkpoints, but do not add it to the app yet because the current public evidence is a paper/benchmark result rather than a deployable model.
+- Habibi-TTS is a 2026 open-source Arabic speech synthesis project built around F5-TTS with a multi-dialect benchmark. Its specialized MSA model is Apache-2.0, but its unified, Saudi, and UAE models are CC-BY-NC-SA-4.0, so the app exposes `habibi-msa` as an optional MSA voice rather than making Habibi the default.
+- 3arab-TTS 500M is a very new Apache-2.0 Arabic-only 500M TTS model, with a VoiceDesign variant updated in June 2026. It is worth a same-sample listening benchmark, but it should not replace SILMA/Habibi until long-form stability, pacing, and setup complexity are proven.
+- KaniTTS Arabic is a recent Arabic-only 400M TTS model with high-speed claims. Test it when generation speed matters, but confirm license fit and compare skipped words, pronunciation, and long-passage comfort against SILMA/Habibi before promoting it.
+- Emirati VITS Male is an Apache-2.0 bilingual Emirati Arabic/English voice. It belongs in the dialect benchmark lane, not the default MSA audiobook lane, unless the target PDF benefits from Gulf pronunciation.
+- MOSS-TTS-Nano is an Apache-2.0 0.1B multilingual TTS model with Arabic among 20 supported languages. Its ONNX CPU path and packaged CLI make it a serious candidate for a free worker, but it needs an Arabic reference-voice benchmark before it should replace SILMA in the father-friendly UI.
+- Supertonic 3 is an OpenRAIL 99M multilingual TTS model with Arabic among 31 supported languages and a local ONNX CPU path. It is wired as optional `supertonic-ar`; use it as a speed/practicality benchmark, not as the Arabic-first default until listening tests beat SILMA/Habibi on the target book.
+- VoxCPM2 is an Apache-2.0 2B multilingual TTS model with Arabic listed among 30 supported languages, 48 kHz output, voice design/cloning, and roughly 8 GB VRAM guidance on its model card. It is now worth tracking as a strong-worker voice benchmark candidate, but SILMA remains the practical default because it is Arabic-focused and lighter.
+- Voxtral TTS is Mistral's open-weight 4B TTS model with Arabic among 9 listed languages and strong latency/quality claims. Keep it external and personal/non-commercial because the model card lists `cc-by-nc-4.0` and 16GB+ GPU guidance.
+- Falcon-OCR is an Apache-2.0 300M early-fusion document OCR VLM from TII. It is promising because it is much smaller than 0.9B+ document VLMs, but it is general document OCR rather than Arabic-book-specific, so it should enter the benchmark watchlist before it enters the default pipeline.
+- Baseer OCR V1.0 is an Apache-2.0 Arabic OCR VLM fine-tuned from Qwen2-VL-2B for Arabic legal/complex documents, including multi-column layouts, stamps, tables, handwritten, and printed text. It is wired as an optional sidecar; benchmark it on selected pages before full-book use.
+- Arabic-GLM-OCR-v2 is a newer Apache-2.0 Arabic OCR VLM sidecar. Its model card reports strong Arabic document extraction and noise reduction, but it still needs independent scoring against QARI/KATIB/PaddleOCR/Tesseract on the selected book images before any full-book run.
+- DIMI Arabic OCR v2 is a newer Apache-2.0 Arabic OCR LoRA fine-tuned from Qwen2.5-VL-7B. Keep it external unless the smaller Arabic OCR sidecars fail and a strong worker can handle 7B-class LoRA inference.
+- Raqim-style OCR correction is research-only for now. Dictionary/LLM correction can improve OCR metrics, but it can also change source wording; keep exact extracted text as the default for religious and book audio.
+- Arabic-Qwen3.5-OCR-v4 is a 0.9B Apache-2.0 Arabic OCR VLM now wired as an optional sidecar. Its model card claims printed, handwritten, classical, and diacritic-heavy Arabic support, so benchmark it against KATIB/QARI/PaddleOCR/Tesseract before full-book use.
+- DeepSeek-OCR-2 is the official Apache-2.0 3B DeepSeek OCR successor with 2026 model-card/paper references and public document OCR benchmark results. It is not Arabic-specific, so keep it external and compare only on the exported Arabic book page images.
+- Loay Arabic-OCR-DeepSeek-OCR-2 is an Apache-2.0 Arabic fine-tune of DeepSeek-OCR-2 for high-precision Arabic OCR and layout analysis. It is promising, but still belongs in the external benchmark lane because it needs same-page scoring against QARI/KATIB/Arabic-Qwen/Baseer and a strong-worker runtime check.
+- DeepSeek Arabic OCR v6 is a newer Apache-2.0 Arabic-labeled DeepSeek-OCR fine-tune. It is promising enough to benchmark, but not enough to default because the model card has sparse Arabic-book evidence and no hosted inference provider.
+- Arabic-English handwritten OCR Qwen3-VL is an Apache-2.0 Qwen3-VL-4B watchlist model for Arabic/English handwritten OCR. Keep it external for handwriting-heavy pages because the model card presents it as research-oriented and not inference-provider deployed.
+- Arabic-English handwritten OCR v3 is an Apache-2.0 Qwen2.5-VL 3B-class watchlist model for Arabic/English handwriting and manuscripts. Keep it external for handwriting-heavy pages because it is large and not inference-provider deployed.
+- Arabic handwritten OCR 4-bit Qwen2.5-VL is an Apache-2.0 4-bit handwriting/manuscript checkpoint with about 2.44GB of model assets. It is a better external benchmark than the full handwritten checkpoint when the worker is memory-constrained, but it still needs same-page scoring before any wiring.
+- NAKBA Arabic manuscript line OCR baseline is a Qwen3-VL-8B LoRA baseline for the NAKBA NLP 2026 Arabic manuscript understanding shared task. Keep it line-level and external unless page images are first cropped into manuscript text lines, and confirm license fit before production.
+- HAFITH is an Apache-2.0 historical Arabic manuscript recognition model with Arabic-native tokenization and strong line-level CER claims. Glimpse RTL OCR is a separate Apache-2.0 Arabic/Persian text-line OCR benchmark with 6.97% CER claims. Keep both external because they require pre-segmented text lines rather than full-page PDFs.
+- olmOCR Arabic LoRA v2 fills the full-page manuscript lane when line cropping is impractical. Benchmark it externally against Ketaba/QARI and line-cropped options because it depends on a 7B olmOCR base model.
+- Arabic Large Nougat is a 0.4B Arabic book-page OCR-to-Markdown benchmark. It is directly relevant to printed Arabic books, but keep it external because it is GPL-3.0 and the model card warns about hallucination and context-length limits.
+- Arabic OCR Qwen2.5-VL GGUF is a QariOCR-v0.3-trained Arabic/English OCR fine-tune on a Qwen2.5-VL 7B GGUF/Unsloth path. It is relevant for scanned books, religious text, handwriting, and mixed Arabic-English documents, but it is large and needs license confirmation and same-page scoring before wiring.
+- Qwen3-VL Persian/Arabic line OCR is an Apache-2.0 Qwen3-VL 2B watchlist model for cropped Persian/Arabic text-line OCR. Keep it external unless a layout step crops pages into lines because the model card says it is not designed for full-page OCR.
+- Loay Arabic-OCR-Qwen2.5-VL-7B is a larger Arabic OCR VLM fine-tuned from Qwen2.5-VL-7B for Arabic text in images. Keep it external unless the smaller Arabic OCR sidecars fail and a strong worker can handle 7B-class inference.
+- AtlasOCR is a Darija/Moroccan Arabic OCR model based on Qwen2.5-VL 3B. It is not the default for standard Arabic books, but it is worth tracking for Moroccan/Darija PDFs after license terms are confirmed.
+- Arabic Legal Documents OCR 1.0 is a Gemma-licensed Gemma-3-4B-IT fine-tune for low-quality scanned Arabic legal documents. It may help legal or form-like PDFs, but it is domain-specific and should stay outside the default book-to-audio stack.
+- Facebook MMS TTS supports Arabic and is useful as a hosted fallback in Vercel mode, but the broader MMS TTS license is CC-BY-NC-4.0, so it is not the best permissive default for the local/worker stack.
+
+## Voice Selection Process
+
+Use SILMA as the first local voice to test. It is the recommended baseline because it is Arabic-focused, lightweight compared with larger multilingual TTS systems, and Apache-2.0.
+
+Use Habibi MSA as the optional second test when the sidecar is installed. It may sound better for some Modern Standard Arabic passages, but keep it optional because only the specialized models are Apache-2.0.
+
+Use Mishkala Tashkeel, Tashkeel-350M, and Mushkil as external pronunciation-preprocessor benchmarks, not as automatic website defaults. Diacritize the same cleaned text sample, then listen-test plain, Mishkala, Tashkeel-350M, and Mushkil versions with SILMA/Habibi/Supertonic/eSpeak. Keep a preprocessor only if it improves pronunciation without adding distracting or wrong harakat and `scripts\score_tts_preprocessor.py` says the meaning-preservation score is high enough.
+
+Track Thaka KSAA-2026 speech diacritization as a research signal, not a website dependency. The paper shows a winning CATT-Whisper ensemble for speech dictation diacritization, which is useful for understanding where Arabic pronunciation preprocessing is going, but it should not affect the production stack until a permissive, practical implementation can be tested on the same cleaned book sample.
+
+Use 3arab-TTS 500M as a new Arabic-only external benchmark. It is permissively licensed and much smaller than VoxCPM2/Voxtral, but it is new enough that long-form stability and audiobook comfort need to be proven before it becomes a normal app voice.
+
+Use KaniTTS Arabic as a speed-focused Arabic-only external benchmark. It is smaller than large multilingual voices, but its current metadata reports `other`, so verify license fit, word preservation, and pacing on the exact cleaned book text before wiring it into the app.
+
+Use Emirati VITS Male only as a dialect-specific voice benchmark. It may be a nice match for Gulf/Emirati Arabic, but for MSA books SILMA/Habibi remain the better first tests.
+
+Use MOSS-TTS-Nano as a future CPU-friendly benchmark. It is permissively licensed, supports Arabic, and has an ONNX CPU path, but it needs a clean Arabic reference/prompt audio workflow before it should appear as a normal app voice.
+
+Use Supertonic 3 as the wired CPU-friendly comparison voice. It supports Arabic with a compact ONNX model and can be installed with `scripts/setup_supertonic.ps1`, but it is multilingual rather than Arabic-specialized, so listen against SILMA/Habibi on the same passage before choosing it for a full book.
+
+Do not add Kyutai Pocket TTS to the Arabic voice picker yet. The current official Kyutai page makes it attractive for CPU real-time TTS, but the listed Pocket TTS languages are English, French, German, Spanish, Portuguese, and Italian, not Arabic. Revisit it only if Kyutai publishes Arabic support.
+
+Use OmniVoice as the newest multilingual Arabic benchmark candidate. It is Apache-2.0, has Arabic in its broad language list, and is smaller than VoxCPM2, but it still needs side-by-side listening against SILMA/Habibi on the same cleaned Arabic text.
+
+Use OmniVoice Arabic LoRA only after base OmniVoice is working. It is an Apache-2.0 Arabic adapter, but it adds another moving part and still needs the same listening and runtime test.
+
+Use Lahgtna OmniVoice v2 only for dialect experiments. It is Arabic-focused and newer than the Chatterbox dialect entry, but the model card does not declare a license, so it should stay external until licensing and long-form stability are proven.
+
+Use Lahgtna Chatterbox as a dialect benchmark, not the default audiobook voice. It is MIT and Arabic-focused across dialects, but long-form repetition/stability needs to be tested on the same cleaned sample.
+
+Use Egyptian Arabic Chatterbox only for Egyptian/dialectal Arabic experiments. It is Apache-2.0 and trained on Egyptian Arabic, but it is a Chatterbox fine-tune that recommends GPU for real-time inference and may not fit MSA books.
+
+Use NileTTS-XTTS only for Egyptian/dialectal Arabic experiments. The 2026 NileTTS paper and model card report improved Egyptian Arabic intelligibility versus XTTS v2, but it is trained on Egyptian Arabic and should not replace SILMA or Habibi MSA for standard Arabic books.
+
+Use Arabic XTTS-v2 Egyptian fine-tune only as a dialectal listening benchmark after license review. Its project is MIT, but it is built on XTTS-v2 with the Coqui Public Model License, so keep it outside the default public/family deployment path unless that license and voice-cloning runtime fit the exact use case.
+
+Use Chatterbox-Multilingual as a broader MIT Arabic-capable benchmark. It supports Arabic via `language_id="ar"` and can use a reference voice, but long-form book pacing and watermarking should be judged before it becomes a website voice.
+
+Use Chatterbox Arabic fine-tune as the first Arabic-focused Chatterbox adapter to compare against SILMA/Habibi for MSA books. It is MIT and claims better Arabic pronunciation, diacritics, intonation, MSA, and dialect support, but it needs same-text listening tests and long-form stability proof before it becomes a normal app voice.
+
+Use Chatterbox-Multilingual ONNX as the CPU/ONNX variant to benchmark when the free worker path needs a more portable runtime. It is MIT and Arabic-capable, but repetition, pacing, and runtime still need same-sample listening tests.
+
+Use tts-arabic-onnx as a compact Arabic-only ONNX benchmark when CPU runtime is the bottleneck. It exposes smaller FastPitch/MixerTTS and vocoder combinations plus vowelizer options, but keep it external until the overall model/repo licensing is confirmed.
+
+Use Spark-TTS Arabic as an external Classical/MSA benchmark only when you can provide diacritized input and reference audio through the Spark-TTS repo. Its setup is too involved for the father-friendly default.
+
+Use Sofelia-TTS only for Palestinian/dialectal Arabic experiments. It is permissively licensed, but not a general MSA audiobook default.
+
+Use Egyptian Arabic Qwen3-TTS only for Egyptian/dialectal Arabic experiments. It is permissively licensed and Arabic-capable, but it is a 1.7B Qwen3-TTS fine-tune, not hosted by an inference provider, and not the right default for MSA book narration.
+
+Use NAMAA-Saudi-TTS, Saudi Chatterbox fine-tune, Saudi TTS, Saudi Arabic Qwen3-TTS, and Emirati Qwen3.5-TTS only for Gulf dialect experiments. NAMAA-Saudi-TTS is MIT and Chatterbox-based, Saudi Chatterbox fine-tune and Saudi TTS are Apache-2.0, while the Qwen voices are Apache-2.0 Qwen3-TTS-family fine-tunes; all should stay external until a same-text listening test proves they are better for the target PDF than SILMA/Habibi or Emirati VITS Male. Keep NAMAA-Saudi-TTS-V2 out of the default/free production lane because it is non-commercial, reference-audio based, and explicitly Najdi/Saudi rather than MSA book narration.
+
+Use NAMAA-Egyptian-TTS only for Egyptian/dialectal experiments. It is MIT and Chatterbox-based with local and hosted examples, but its own model card targets conversational Egyptian Arabic rather than Modern Standard Arabic books.
+
+Keep Arabic-F5-TTS-v2 out of the default public app. It may be useful for personal MSA experiments, but it is non-commercial and requires fully diacritized Arabic input.
+
+Use VoxCPM2 only as a future strong-worker benchmark. It is permissively licensed and supports Arabic, but its 2B size and GPU-oriented requirements make it a poor fit for the first free CPU family deployment.
+
+Use Voxtral TTS only for personal/non-commercial strong-worker benchmarks. It supports Arabic on the model card, but its license and GPU guidance make it the wrong default for a public family website.
+
+Use eSpeak NG when speed and reliability matter more than naturalness, or when the neural voices are not installed on the worker.
+
+The voice benchmark now reports both:
+
+```text
+recommended -> quality-first starting voice, usually silma-local
+fastest     -> fastest successful voice in the current run
+```
+
+The final voice choice still requires listening to the generated files, because Arabic pacing and comfort over long religious/commentary texts cannot be judged by runtime alone.
+
+## Optional Arabic-Trained VLM OCR Worker Paths
+
+The repo includes optional KATIB, Arabic-Qwen, and QARI-OCR wiring for hard Arabic scans. For maximum quality on a short sample or strong worker, use:
+
+```text
+OCR_ENGINE=arabic-max
+```
+
+`arabic-max` tries QARI-OCR, KATIB, Arabic-Qwen, Baseer, PaddleOCR-VL, PaddleOCR Arabic, EasyOCR Arabic, Surya, and Tesseract Arabic where installed, then keeps the cleanest text by the same speech-readiness score used by the app.
+
+Try KATIB first when you want a smaller Arabic-trained model:
+
+```text
+OCR_ENGINE=katib-ocr
+KATIB_OCR_RENDER_ZOOM=1.5
+```
+
+Install it locally on Windows with:
+
+```powershell
+.\scripts\setup_katib_ocr.ps1
+```
+
+KATIB 0.8B is Apache-2.0 and fine-tuned specifically for Arabic OCR, including printed and handwritten text. It is still a VLM path, so benchmark it on a small sample before using it for a full book.
+
+Try Arabic-Qwen3.5-OCR-v4 as a second smaller Arabic-trained model:
+
+```text
+OCR_ENGINE=arabic-qwen-ocr
+ARABIC_QWEN_OCR_RENDER_ZOOM=1.5
+```
+
+Install it locally on Windows with:
+
+```powershell
+.\scripts\setup_arabic_qwen_ocr.ps1
+```
+
+Arabic-Qwen3.5-OCR-v4 is Apache-2.0 and smaller than QARI. It is still a VLM path, so use it on short samples or a worker and promote it only if it beats the existing wired OCR stack on the same pages.
+
+QARI-OCR remains the stronger/heavier Arabic-book path:
+
+```text
+OCR_ENGINE=qari-ocr
+QARI_OCR_RENDER_ZOOM=1.5
+```
+
+Install it locally on Windows with:
+
+```powershell
+.\scripts\setup_qari_ocr.ps1
+```
+
+The QARI sidecar installs `transformers`, `qwen-vl-utils`, `accelerate`, `peft`, PyTorch, torchvision, and Pillow, then checks that the image-to-text model classes import successfully. The first real run downloads the model weights, so expect the first QARI test to take longer than later tests.
+
+Then benchmark it against the lighter engines:
+
+```powershell
+python scripts\benchmark_ocr.py C:\path\to\arabic-book.pdf --page-limit 1 --engines arabic baseer-ocr arabic-qwen-ocr katib-ocr qari-ocr paddleocr tesseract
+```
+
+`OCR_ENGINE=katib-ocr` tries KATIB first, then falls back to PaddleOCR, EasyOCR, and Tesseract. `OCR_ENGINE=arabic-qwen-ocr` tries Arabic-Qwen first, then falls back to PaddleOCR, EasyOCR, and Tesseract. `OCR_ENGINE=baseer-ocr` tries Baseer first, then falls back to PaddleOCR, EasyOCR, and Tesseract. `OCR_ENGINE=qari-ocr` tries QARI first, then falls back to PaddleOCR, EasyOCR, and Tesseract. `OCR_ENGINE=arabic` includes installed KATIB, Arabic-Qwen, Baseer, and QARI automatically unless `ARABIC_INCLUDE_KATIB_OCR=0`, `ARABIC_INCLUDE_ARABIC_QWEN_OCR=0`, `ARABIC_INCLUDE_BASEER_OCR=0`, or `ARABIC_INCLUDE_QARI_OCR=0` is set. `OCR_ENGINE=arabic-max` always opts into the heavy Arabic OCR comparison path where those sidecars are installed. `OCR_ENGINE=best` does not include those VLM engines unless `BEST_INCLUDE_KATIB_OCR=1`, `BEST_INCLUDE_ARABIC_QWEN_OCR=1`, `BEST_INCLUDE_BASEER_OCR=1`, or `BEST_INCLUDE_QARI_OCR=1` is set, because they can be much slower and heavier than the default OCR path.
+
+## Optional Surya Worker Path
+
+The repo includes optional Surya wiring for hard scanned books. This remains useful when PaddleOCR-VL is unavailable or when you want to compare a Datalab document OCR path:
+
+```text
+OCR_ENGINE=surya
+SURYA_RENDER_ZOOM=1.5
+```
+
+`OCR_ENGINE=surya` tries Surya first, then falls back to PaddleOCR, EasyOCR, and Tesseract. `OCR_ENGINE=best` does not include Surya unless `BEST_INCLUDE_SURYA=1` is set, because Surya can be much slower and heavier than the default OCR path.
+
+Install it only on a worker or powerful local machine:
+
+```powershell
+.\scripts\setup_surya.ps1
+```
+
+Surya also needs `llama.cpp` / `llama-server` for CPU or Apple Silicon, or `vLLM` for NVIDIA GPU. The setup script installs the Python sidecar but does not install those heavier backend runtimes.
+
+## Latest High-End OCR Watchlist
+
+The current implementation intentionally avoids making a heavy VLM the default, but these are the free options to revisit when the worker has enough RAM/GPU:
+
+1. QARI-OCR 0.4: strongest Arabic-specific upgrade candidate because it is directly trained for Arabic OCR on Islamic books and Arabic manuscripts.
+2. KATIB 0.8B: smaller Arabic-trained OCR VLM to try when QARI is too heavy.
+3. PaddleOCR-VL-1.6: best general document-parser candidate because it is in the official PaddleOCR ecosystem and supports 109 languages.
+4. Ketaba-OCR LoRA: Arabic manuscript LoRA candidate to benchmark externally when the wired Arabic OCR stack fails difficult scans.
+5. Qari-OCR-LoRA: secondary QARI-family manuscript LoRA benchmark after Ketaba and QARI 0.4.
+6. Tawkeed OCR: wired Apache-2.0 Arabic-first QARI v0.3 fork to benchmark when QARI 0.4 is too heavy or edge-style Arabic OCR matters.
+7. Falcon-OCR: compact Apache-2.0 300M document OCR VLM worth benchmarking when Arabic VLM OCR is too heavy or when layout/table handling matters.
+8. Baseer OCR V1.0: Arabic-specialized and Apache-2.0, worth tracking for difficult Arabic legal or complex-layout pages.
+9. Arabic-GLM-OCR-v2: newer Arabic OCR VLM optional sidecar that needs short-sample scoring before full-book use.
+10. Arabic-Qwen3.5-OCR-v4: 0.9B Apache-2.0 Arabic OCR VLM wired as an optional sidecar; benchmark it beside KATIB/QARI on the target pages.
+11. DeepSeek-OCR-2: official Apache-2.0 3B general document OCR VLM to benchmark externally on strong-worker hardware.
+12. DeepSeek Arabic OCR v6: newer Arabic-labeled DeepSeek-OCR fine-tune to benchmark externally before considering any sidecar work.
+13. Arabic-English handwritten OCR Qwen3-VL: 4B handwritten Arabic/English OCR watchlist model to benchmark externally for handwriting-heavy pages.
+14. Arabic-English handwritten OCR v3: 3B-class handwritten Arabic/English OCR watchlist model to benchmark externally when manuscript/handwriting pages are the main failure.
+15. Arabic handwritten OCR 4-bit Qwen2.5-VL: smaller Apache-2.0 handwriting/manuscript OCR checkpoint to benchmark when memory is tight.
+16. NAKBA Arabic manuscript line OCR baseline: 2026 manuscript-line benchmark to test only after pages are cropped into lines.
+17. HAFITH: Apache-2.0 historical Arabic manuscript line-OCR benchmark to test only after page images are segmented into text lines.
+18. Glimpse RTL OCR: Apache-2.0 Arabic/Persian line-OCR benchmark to test only after page images are segmented into text lines.
+19. olmOCR Arabic LoRA v2: full-page Arabic manuscript LoRA benchmark for large workers.
+20. Arabic Large Nougat: GPL-3.0 Arabic book-page OCR-to-Markdown benchmark to test externally for printed books.
+21. Arabic OCR Qwen2.5-VL GGUF: QariOCR-trained Arabic/English GGUF/Unsloth benchmark for scanned books, religious text, handwriting, and mixed-language documents.
+22. Qwen3-VL Persian/Arabic line OCR: Apache-2.0 line-level OCR model to benchmark only when pages can be cropped into text lines.
+23. DIMI Arabic OCR v2: high-capacity Qwen2.5-VL-7B LoRA to benchmark externally for printed Arabic and diacritics-heavy pages.
+24. Loay Arabic-OCR-Qwen2.5-VL-7B: high-capacity Arabic OCR VLM to benchmark externally when smaller Arabic OCR models are not enough.
+25. AtlasOCR: Darija/Moroccan Arabic OCR model to test only when the source PDFs need that dialect coverage.
+26. Arabic Legal Documents OCR 1.0: Gemma-licensed legal/structured-document OCR benchmark for legal PDFs only; not a default audiobook OCR engine.
+27. Kraken/eScriptorium Arabic script: open-source historical/non-Latin OCR workflow to test when pages look like archival Arabic print or manuscripts; model choice and line segmentation make it external-only for this app.
+28. Kairawan/Qalamus manuscript OCR: free web-service evidence for Arabic manuscript transcription, but service-only and not a deployable free-software worker component yet.
+29. Surya / Chandra: useful document parsing alternatives for layout-heavy scans, but less clean as a default because model-weight licensing and runtime needs are more complicated.
+
+## Latest High-End TTS Watchlist
+
+The current implementation keeps SILMA as the default local neural voice because it is Arabic-focused, permissively licensed, and practical to install as a sidecar. The strongest free/open voice candidates to revisit on a bigger worker are:
+
+1. Supertonic 3: OpenRAIL, Arabic among 31 supported languages, 99M parameters, ONNX CPU inference, and now wired as optional `supertonic-ar`. Benchmark it as the fast local CPU challenger.
+2. 3arab-TTS 500M: Apache-2.0, Arabic-only, about 500M parameters, and a VoiceDesign variant. Benchmark it on the same cleaned text before any app wiring because it is very new.
+3. KaniTTS Arabic: Arabic-only, about 400M parameters, and speed-focused, but license metadata needs confirmation. Benchmark it on the same cleaned text before any app wiring.
+4. Emirati VITS Male: Apache-2.0 bilingual Emirati Arabic/English. Benchmark only for Gulf dialect fit.
+5. MOSS-TTS-Nano: Apache-2.0, Arabic among 20 supported languages, 0.1B parameters, packaged CLI, and ONNX CPU path. Benchmark it with an Arabic reference voice as another CPU-friendly candidate.
+6. OmniVoice plus Arabic LoRA: Apache-2.0, Arabic included in 646-language coverage, and a separate Arabic LoRA adapter exists. Benchmark it externally as the newest broad multilingual candidate.
+7. Lahgtna OmniVoice v2: Arabic dialect OmniVoice fine-tune; benchmark externally for dialectal content and confirm licensing before any production wiring.
+8. Lahgtna Chatterbox: MIT Arabic dialect TTS; benchmark externally for dialectal content and watch for repetition on long text.
+9. Egyptian Arabic Chatterbox: Apache-2.0 Egyptian dialect Chatterbox fine-tune; benchmark only for Egyptian Arabic content.
+10. NileTTS-XTTS: Apache-2.0 Egyptian Arabic XTTS fine-tune with 2026 paper results; benchmark only for Egyptian/dialectal content.
+11. Arabic XTTS-v2 Egyptian fine-tune: promising Egyptian speaker quality work, but CPML/base-license review is required before any personal/public use decision.
+12. Chatterbox-Multilingual: MIT, Arabic listed among 23 supported languages, and simple local examples. Benchmark it with the same Arabic reference voice and listen for long-form pacing.
+13. Chatterbox-Multilingual ONNX: MIT ONNX packaging with Arabic support. Benchmark it for free CPU/ONNX worker practicality before wiring.
+13. tts-arabic-onnx: compact Arabic-only ONNX FastPitch/MixerTTS package. Benchmark CPU speed, speaker IDs, pace, and vowelizers, but confirm license fit before production.
+14. Mishkala, Tashkeel-350M, and Mushkil: Apache-2.0 pronunciation-preprocessor benchmarks. Test plain, lightweight tashkeel, larger-model tashkeel, and AraT5V2 tashkeel on the same voice before changing production settings.
+15. Thaka KSAA-2026 speech diacritization: research-only signal for speech-plus-text Arabic diacritization; wait for permissive code/weights before any app work.
+15. Spark-TTS Arabic: Apache-2.0 Classical/MSA candidate, but requires diacritized input and the Spark-TTS repo.
+16. Sofelia-TTS: Apache-2.0 Palestinian Arabic voice benchmark for dialectal content.
+17. VoxCPM2: Apache-2.0, Arabic among 30 supported languages, 48 kHz output, and voice design/cloning. Benchmark it only on GPU/large-worker hardware.
+18. Voxtral TTS: Arabic listed and high-quality open weights, but CC-BY-NC-4.0 and 4B GPU-oriented deployment. Benchmark only for personal/non-commercial strong-worker comparisons.
+19. Habibi-TTS MSA: Arabic-specific and already wired as an optional voice; continue comparing it against SILMA for MSA passages.
+20. Egyptian Arabic Qwen3-TTS: Apache-2.0 Qwen3-TTS dialect fine-tune to benchmark only for Egyptian Arabic; not the MSA audiobook default.
+21. Saudi Arabic Qwen3-TTS: Apache-2.0 Qwen3-TTS dialect fine-tune to benchmark only for Saudi/Gulf Arabic.
+22. Emirati Qwen3.5-TTS: Apache-2.0 Qwen3-TTS-family dialect fine-tune to benchmark beside Emirati VITS Male for Emirati/Gulf content.
+23. Arabic-F5-TTS-v2: personal/non-commercial MSA candidate that requires tashkeel; do not use as the default public free website voice.
+24. Qwen3-TTS: Apache-2.0 and strong generally, but official released model cards list Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, and Italian. Do not promote the base model until Arabic support and a practical Arabic inference path are verified from primary sources.
+
+For the current father-friendly website, the right process is still: run a 5-page sample, benchmark `arabic-max` and the lighter Arabic OCR modes, export the same cleaned TTS sample, listen to SILMA/Habibi/Supertonic/eSpeak samples, optionally test Mishkala/Tashkeel-350M/Mushkil preprocessing, 3arab-TTS 500M, KaniTTS Arabic, Emirati VITS Male, MOSS-TTS-Nano, OmniVoice/Arabic LoRA, Lahgtna OmniVoice v2, Lahgtna Chatterbox, NAMAA-Saudi-TTS, Saudi Chatterbox fine-tune, Saudi TTS, Egyptian Arabic Chatterbox, NileTTS-XTTS, Arabic XTTS-v2 Egyptian fine-tune, Chatterbox-Multilingual, Chatterbox-Multilingual ONNX, tts-arabic-onnx, Spark-TTS Arabic, Sofelia-TTS, Egyptian Arabic Qwen3-TTS, Saudi Arabic Qwen3-TTS, Emirati Qwen3.5-TTS, or personal/non-commercial Voxtral TTS externally with that exact text, then process the full book only after text quality is good.
+
+Do not confuse "free/open model" with "available as a hosted inference endpoint." Current Hugging Face model cards show QARI-OCR 0.4 and SILMA TTS as free/open candidates, but not served as a simple hosted Hugging Face inference route and not deployed by a hosted inference provider. That is why the recommended public website remains Vercel for the UI plus a Docker worker for OCR/TTS, not Vercel-only cloud TTS.
+
+Keep audio storage deliberately simple for the free hosted path. The Docker worker stores finished MP3/WAV files locally under `outputs/` and the app exposes download URLs until retention cleanup removes old files. That fits the father-friendly goal because the user downloads the audio when it is ready. Permanent hosted audio links should be a later opt-in using Vercel Blob or another object store, because long audiobook files can consume free storage, transfer, operation, and edge-request quotas quickly.
+
+If the wired OCR engines are not clean enough, export fixed page images before trying external OCR models:
+
+```powershell
+python scripts\export_ocr_sample_images.py C:\path\to\arabic-book.pdf --out-dir outputs\external-ocr-sample
+```
+
+Use the generated `external-ocr-sample.md` handoff and compare external QARI-OCR 0.4 GGUF, Loay Arabic-OCR-DeepSeek-OCR-2, DeepSeek-OCR-2, DeepSeek Arabic OCR v6, aNS Qwen3-VL Arabic OCR v3, Waraqon v3 Arabic OCR HTML Qari, Ketaba-OCR, Qari-OCR-LoRA, oi-OCR, NuExtract3, Qianfan-OCR, Chandra OCR 2, dots.ocr, Arabic Large Nougat, Kraken/eScriptorium Arabic script, Kairawan/Qalamus manuscript OCR, HAFITH, Glimpse RTL OCR, olmOCR Arabic LoRA v2, Falcon-OCR, DIMI Arabic OCR v2, Loay Arabic-OCR-Qwen2.5-VL-7B, Arabic Legal Documents OCR 1.0, Arabic-English handwritten OCR Qwen3-VL, Arabic-English handwritten OCR v3, Arabic handwritten OCR 4-bit Qwen2.5-VL, NAKBA Arabic manuscript line OCR baseline, Arabic OCR Qwen2.5-VL GGUF, Qwen3-VL Persian/Arabic line OCR, AtlasOCR, or similar OCR outputs against the wired Arabic stack on those exact same page images. Tawkeed, Arabic-GLM-OCR-v2, Arabic-Qwen3.5-OCR-v4, and Baseer are already wired as optional sidecars, but the same sample images are still useful if you want to score them externally before installing the sidecar.
+
+After the external OCR model writes text, score its output and save JSON for the promotion gate:
+
+```powershell
+python scripts\benchmark_ocr.py test_pdfs\book-best-5-pages.pdf --page-limit 5 --engines arabic-max arabic tawkeed-ocr baseer-ocr arabic-qwen-ocr katib-ocr qari-ocr paddleocr tesseract --json > outputs\external-ocr-sample\wired-ocr-baseline.json
+python scripts\score_external_ocr.py --candidate qari-gguf=outputs\external-ocr-sample\qari-gguf.txt --candidate loay-deepseek-ocr-2=outputs\external-ocr-sample\loay-deepseek-ocr-2.txt --candidate ketaba=outputs\external-ocr-sample\ketaba.txt --candidate loay-qwen25=outputs\external-ocr-sample\loay-qwen25.txt --candidate legal-docs-ocr=outputs\external-ocr-sample\legal-docs-ocr.txt --candidate nuextract3=outputs\external-ocr-sample\nuextract3.txt --candidate chandra=outputs\external-ocr-sample\chandra.txt --candidate dots-ocr=outputs\external-ocr-sample\dots-ocr.txt --candidate arabic-large-nougat=outputs\external-ocr-sample\arabic-large-nougat.txt --candidate kraken=outputs\external-ocr-sample\kraken.txt --candidate handwritten-4bit=outputs\external-ocr-sample\handwritten-4bit.txt --candidate olmocr-arabic-lora=outputs\external-ocr-sample\olmocr-arabic-lora.txt --candidate qwen25-gguf=outputs\external-ocr-sample\qwen25-gguf.txt --candidate falcon=outputs\external-ocr-sample\falcon.txt --candidate arabic-glm=outputs\external-ocr-sample\arabic-glm.txt --baseline-json outputs\external-ocr-sample\wired-ocr-baseline.json --write-report outputs\external-ocr-sample\external-ocr-score.md --write-json outputs\external-ocr-sample\external-ocr-score.json
+python scripts\model_promotion_gate.py --candidate-name "External OCR winner" --kind ocr --license Apache-2.0 --score-json outputs\external-ocr-sample\external-ocr-score.json --same-sample --runtime-ok --privacy-ok --human-reviewed --write-report outputs\model-promotion-gate.md
+```
+
+The repo now includes a deliberately optional PaddleOCR-VL sidecar:
+
+```powershell
+.\scripts\setup_paddleocr_vl.ps1
+python scripts\benchmark_ocr.py C:\path\to\arabic-book.pdf --page-limit 1 --engines arabic arabic-qwen-ocr katib-ocr qari-ocr paddleocr paddleocr-vl tesseract
+```
+
+Use `OCR_ENGINE=paddleocr-vl` only for short samples or a strong worker. It falls back to regular PaddleOCR, EasyOCR, and Tesseract when the sidecar is unavailable or fails. `OCR_ENGINE=best` does not include PaddleOCR-VL unless `BEST_INCLUDE_PADDLEOCR_VL=1` is set.
+
+## Source Links
+
+- EasyOCR: https://github.com/JaidedAI/EasyOCR
+- PaddleOCR PP-OCRv5 multilingual recognition: https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/algorithm/PP-OCRv5/PP-OCRv5_multi_languages.en.md
+- PaddleOCR OCR pipeline: https://www.paddleocr.ai/main/en/version3.x/pipeline_usage/OCR.html
+- PaddleOCR latest docs: https://www.paddleocr.ai/latest/en/index.html
+- PP-OCRv5 paper: https://arxiv.org/abs/2603.24373
+- QARI-OCR 0.4 model: https://huggingface.co/NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct
+- QARI-OCR 0.4 GGUF: https://huggingface.co/marwan-osama/Qari-OCR-0.4.0-VL-4B-Instruct-GGUF
+- QARI-OCR v0.3 lighter model: https://huggingface.co/NAMAA-Space/Qari-OCR-v0.3-VL-2B-Instruct
+- QARI-OCR paper: https://arxiv.org/abs/2506.02295
+- KATIB 0.8B Arabic OCR model: https://huggingface.co/oddadmix/Katib-Qwen3.5-0.8B-0.1
+- Ketaba-OCR LoRA: https://huggingface.co/HassanB4/Ketaba-OCR-LoRA
+- Qari-OCR-LoRA: https://huggingface.co/HassanB4/Qari-OCR-LoRA
+- Tawkeed OCR: https://huggingface.co/tawkeed-sa/tawkeed-ocr
+- PaddleOCR-VL-1.6 model: https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.6
+- PaddleOCR-VL-1.6 paper: https://arxiv.org/abs/2606.03264
+- oi-OCR: https://huggingface.co/oi-uae/oi-OCR
+- NuExtract3: https://huggingface.co/numind/NuExtract3
+- Qianfan-OCR: https://huggingface.co/baidu/Qianfan-OCR
+- Chandra OCR 2: https://github.com/datalab-to/chandra
+- dots.ocr: https://huggingface.co/rednote-hilab/dots.ocr
+- Arabic Large Nougat: https://huggingface.co/MohamedRashad/arabic-large-nougat
+- DocTR Arabic FAST detector: https://huggingface.co/madskills/doctr-fast_base-arabic
+- DocTR Arabic PARSEQ recognizer: https://huggingface.co/madskills/doctr-parseq-arabic
+- Kraken OCR documentation: https://kraken.re/main/index.html
+- eScriptorium overview: https://escriptorium.eu/about
+- HAFITH: https://huggingface.co/mdnaseif/hafith
+- Glimpse RTL OCR: https://huggingface.co/surfiniaburger/unsloth_finetune_ocr_arabic
+- olmOCR Arabic LoRA v2: https://huggingface.co/hastyle/olmOCR-arabic-lora-v2
+- GLM-OCR Arabic/French documents: https://huggingface.co/maloukafer/GLM-OCR-finetuned-documents
+- mimoha Arabic OCR: https://huggingface.co/mimoha/ocr
+- Falcon-OCR: https://huggingface.co/tiiuae/Falcon-OCR
+- Falcon Perception paper: https://arxiv.org/abs/2603.27365
+- Baseer OCR model: https://huggingface.co/AbdoTarek/Baseer-OCR-V1.0
+- Baseer OCR paper: https://arxiv.org/abs/2509.18174
+- Arabic-GLM-OCR-v2: https://huggingface.co/sherif1313/Arabic-GLM-OCR-v2
+- Arabic-Qwen3.5-OCR-v4: https://huggingface.co/sherif1313/Arabic-Qwen3.5-OCR-v4
+- DeepSeek-OCR-2: https://huggingface.co/deepseek-ai/DeepSeek-OCR-2
+- Loay Arabic-OCR-DeepSeek-OCR-2: https://huggingface.co/loay/Arabic-OCR-DeepSeek-OCR-2
+- DeepSeek Arabic OCR v6: https://huggingface.co/melsiddieg/deepseek_ocr_arabic_v6
+- Arabic-English handwritten OCR Qwen3-VL: https://huggingface.co/sherif1313/Arabic-English-handwritten-OCR-Qwen3-VL-4B
+- Arabic-English handwritten OCR v3: https://huggingface.co/sherif1313/Arabic-English-handwritten-OCR-v3
+- Waraqon v3 Arabic OCR HTML Qari: https://huggingface.co/FatimahEmadEldin/Waraqon-v3-Arabic-OCR-HTML-Qari
+- Arabic handwritten OCR 4-bit Qwen2.5-VL: https://huggingface.co/sherif1313/Arabic-handwritten-OCR-4bit-Qwen2.5-VL-3B-v3
+- NAKBA Arabic manuscript line OCR baseline: https://huggingface.co/U4RASD/ar-ms-baseline
+- Arabic OCR Qwen2.5-VL GGUF: https://huggingface.co/mo1998/arabic-ocr-qwen2.5-vl
+- Qwen3-VL Persian/Arabic line OCR: https://huggingface.co/mohajesmaeili/Qwen3-VL-2B-Persian-Arabic-Ocr-v1.0
+- Kairawan/Qalamus manuscript OCR: https://kairawan.org/
+- DIMI Arabic OCR v2: https://huggingface.co/AhmedZaky1/DIMI-Arabic-OCR-V2
+- Raqim post-OCR correction: https://www.sciencedirect.com/science/article/pii/S187705092600058X
+- Loay Arabic-OCR-Qwen2.5-VL-7B: https://huggingface.co/loay/Arabic-OCR-Qwen2.5-VL-7B-Vision
+- AtlasOCR: https://huggingface.co/atlasia/AtlasOCR
+- Arabic Legal Documents OCR 1.0: https://huggingface.co/bakrianoo/arabic-legal-documents-ocr-1.0
+- Surya: https://github.com/datalab-to/surya
+- SILMA TTS: https://huggingface.co/silma-ai/silma-tts
+- SILMA open source Arabic TTS models: https://silma.ai/open-source-arabic-tts-models
+- SILMA Hugging Face launch article: https://huggingface.co/blog/silma-ai/opensource-arabic-english-text-to-speech-model
+- SILMA Arabic TTS benchmark: https://silma.ai/arabic-tts-benchmark
+- Habibi-TTS: https://github.com/SWivid/Habibi-TTS
+- Habibi-TTS paper: https://arxiv.org/abs/2601.13802
+- Mishkala Tashkeel: https://huggingface.co/flokymind/mishkala
+- Tashkeel-350M: https://huggingface.co/Etherll/Tashkeel-350M
+- Mushkil: https://huggingface.co/riotu-lab/mushkil
+- Thaka KSAA-2026 speech diacritization: https://arxiv.org/abs/2605.25928
+- KSAA-2026 shared task: https://www.codabench.org/competitions/11859/
+- Supertonic 3: https://huggingface.co/Supertone/supertonic-3
+- MOSS-TTS-Nano: https://github.com/OpenMOSS/MOSS-TTS-Nano
+- 3arab-TTS 500M: https://huggingface.co/sherif1313/3arab-TTS-500M-v1
+- 3arab-TTS 500M VoiceDesign: https://huggingface.co/sherif1313/3arab-TTS-500M-v1-VoiceDesign
+- KaniTTS Arabic: https://huggingface.co/nineninesix/kani-tts-400m-ar
+- Emirati VITS Male: https://huggingface.co/vadimbelsky/emirati-vits-male-1.0
+- OmniVoice: https://huggingface.co/k2-fsa/OmniVoice
+- OmniVoice Arabic LoRA: https://huggingface.co/vivooglobal/omnivoice-lora-ar
+- Lahgtna OmniVoice v2: https://huggingface.co/oddadmix/lahgtna-omnivoice-v2
+- Lahgtna Chatterbox: https://huggingface.co/oddadmix/lahgtna-chatterbox-v1
+- NAMAA-Saudi-TTS: https://huggingface.co/NAMAA-Space/NAMAA-Saudi-TTS
+- NAMAA-Saudi-TTS-V2: https://huggingface.co/NAMAA-Space/NAMAA-Saudi-TTS-V2
+- NAMAA-Egyptian-TTS: https://huggingface.co/NAMAA-Space/NAMAA-Egyptian-TTS
+- Saudi Chatterbox fine-tune: https://huggingface.co/FatimahEmadEldin/saudi-tts-chatterbox-finetuned
+- Saudi TTS: https://huggingface.co/AhmedEladl/saudi-tts
+- Egyptian Arabic Chatterbox: https://huggingface.co/AliAbdallah/egyptian-arabic-tts-chatterbox
+- NileTTS-XTTS: https://huggingface.co/KickItLikeShika/NileTTS-XTTS
+- Arabic XTTS-v2 Egyptian fine-tune: https://huggingface.co/Moeeldouma/arabic-tts-xtts-v2
+- NileTTS paper: https://arxiv.org/abs/2602.15675
+- Chatterbox-Multilingual: https://github.com/resemble-ai/chatterbox
+- Chatterbox Arabic fine-tune: https://huggingface.co/juliardi/chatterbox-multilingual-finetuned-arabic
+- Chatterbox-Multilingual ONNX: https://huggingface.co/onnx-community/chatterbox-multilingual-ONNX
+- tts-arabic-onnx: https://huggingface.co/nipponjo/tts-arabic-onnx
+- tts_arabic repository: https://github.com/nipponjo/tts_arabic
+- Spark-TTS Arabic: https://huggingface.co/azeddinShr/Spark-TTS-Arabic-Complete
+- Sofelia-TTS: https://huggingface.co/hamdallah/Sofelia-TTS
+- Arabic-F5-TTS-v2: https://huggingface.co/IbrahimSalah/Arabic-F5-TTS-v2
+- Egyptian Arabic Qwen3-TTS: https://huggingface.co/itshamdi404/Egy_Arabic_Qwen3-TTS-12Hz-1.7B-Base
+- Saudi Arabic Qwen3-TTS: https://huggingface.co/vadimbelsky/qwen3-TTS-KSA
+- Emirati Qwen3.5-TTS: https://huggingface.co/vadimbelsky/qwen3.5-TTS-Emirati
+- VoxCPM2: https://huggingface.co/openbmb/VoxCPM2
+- VoxCPM paper: https://arxiv.org/abs/2509.24650
+- Voxtral TTS: https://huggingface.co/mistralai/Voxtral-4B-TTS-2603
+- Voxtral TTS paper: https://arxiv.org/abs/2603.25551
+- Qwen3-TTS 0.6B Base: https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-Base
+- Qwen3-TTS 1.7B Base: https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-Base
+- Qwen3-TTS technical report: https://arxiv.org/abs/2601.15621

docs/father-user-guide.md

@@ -0,0 +1,51 @@
+# Arabic PDF Reader User Guide
+
+This guide is for the person using the website, not for setup.
+
+## Normal Use
+
+1. Open the website.
+2. Enter the access code.
+3. Choose the Arabic PDF.
+4. Leave **Voice** on the best Arabic voice unless someone tells you to change it.
+5. Leave **Text quality** on **Maximum Arabic-trained OCR** for a new scanned book.
+6. Leave **Pages** on **Quick test** first.
+7. Press **Create Audio**.
+8. Wait until the status says the audio is ready.
+9. Listen to the short test.
+10. If it sounds good, change **Pages** to **Full book** and press **Create Audio** again.
+11. Press **Download Audio** when the full audio is ready.
+
+## Which Text Quality To Choose
+
+Use **Maximum Arabic-trained OCR** first. It is the safest choice for scanned Arabic books because it compares Arabic-trained OCR results and keeps the cleanest text.
+
+Use **QARI Arabic books** for a difficult scanned book when the normal option reads badly and the worker is strong enough. It is trained for Arabic books and manuscripts, but it can be much slower.
+
+Use **KATIB Arabic OCR** when QARI is too slow or too heavy. It is also trained for Arabic text and is smaller.
+
+Use **Best scan test** only on a short sample. It is useful for deciding which OCR engine works best for one book, but it is too slow for most full books.
+
+Use **PaddleOCR Arabic** when the test sounds good and you want the full book to run faster.
+
+Use **Tesseract Arabic fallback** when the other options are broken or when a benchmark says Tesseract worked best for that book.
+
+## If Something Fails
+
+If the app says the text quality is poor, do not make full-book audio yet. Try **Maximum Arabic-trained OCR**, then **Best scan test**, then **QARI Arabic books** or **KATIB Arabic OCR** if either is available.
+
+If the first pages are title pages or blank pages, make a 5-page test PDF from better pages and test that before the full book.
+
+If the website is running through a hosted worker, the job can keep running while the browser is open and checking progress. If the worker restarts, the recent audio list will show the job as failed instead of leaving it stuck.
+
+If the hosted website says downloadable cloud audio needs the worker, use **Read aloud** only as a temporary listening option. That browser voice can help you hear the text, but the normal **Download Audio** button comes back only after the worker is connected.
+
+If the audio sounds robotic but the text is correct, try another voice. **SILMA Arabic Best** is the preferred free local voice when it is available.
+
+## Best Routine For A New Book
+
+1. Run a quick test.
+2. Listen.
+3. If the Arabic text sounds wrong, change OCR before changing the voice.
+4. If the Arabic text sounds right but the voice is not comfortable, change the voice.
+5. Only run the full book after the short test sounds good.

docs/huggingface-model-metadata.md

@@ -0,0 +1,81 @@
+# Hugging Face Model Metadata
+
+Last refreshed: June 6, 2026.
+
+Generated by `scripts/check_research_sources.py --check-hf-metadata`.
+
+Rows marked `page-only` use verified public model-page evidence when live Hugging Face API/socket metadata is unavailable in the local environment.
+
+| Model | Status | Reported ID | License | License Check | Last Modified |
+| --- | --- | --- | --- | --- | --- |
+| AbdoTarek/Baseer-OCR-V1.0 | FAIL | - | - | - | - |
+| AhmedEladl/saudi-tts | PASS | AhmedEladl/saudi-tts | apache-2.0 | PASS | page-only |
+| AhmedZaky1/DIMI-Arabic-OCR-V2 | FAIL | - | - | - | - |
+| AliAbdallah/egyptian-arabic-tts-chatterbox | FAIL | - | - | - | - |
+| atlasia/AtlasOCR | FAIL | - | - | - | - |
+| azeddinShr/Spark-TTS-Arabic-Complete | FAIL | - | - | - | - |
+| baidu/Qianfan-OCR | PASS | baidu/Qianfan-OCR | apache-2.0 | PASS | page-only |
+| bakrianoo/arabic-legal-documents-ocr-1.0 | FAIL | - | - | - | - |
+| bilalRHCH/Arabic-text-to-speech | PASS | bilalRHCH/Arabic-text-to-speech | apache-2.0 | PASS | page-only |
+| datalab-to/chandra | PASS | datalab-to/chandra | openrail | - | page-only |
+| deepseek-ai/DeepSeek-OCR-2 | FAIL | - | - | - | - |
+| Etherll/Tashkeel-350M | FAIL | - | - | - | - |
+| FatimahEmadEldin/saudi-tts-chatterbox-finetuned | FAIL | - | - | - | - |
+| flokymind/mishkala | FAIL | - | - | - | - |
+| hamdallah/Sofelia-TTS | FAIL | - | - | - | - |
+| HassanB4/Ketaba-OCR-LoRA | PASS | HassanB4/Ketaba-OCR-LoRA | apache-2.0 | PASS | page-only |
+| HassanB4/Qari-OCR-LoRA | PASS | HassanB4/Qari-OCR-LoRA | apache-2.0 | PASS | page-only |
+| hastyle/olmOCR-arabic-lora-v2 | FAIL | - | - | - | - |
+| HumeAI/tada-3b-ml | FAIL | - | - | - | - |
+| IbrahimSalah/Arabic-F5-TTS-v2 | PASS | IbrahimSalah/Arabic-F5-TTS-v2 | fair-noncommercial-research-license | - | page-only |
+| itshamdi404/Egy_Arabic_Qwen3-TTS-12Hz-1.7B-Base | FAIL | - | - | - | - |
+| juliardi/chatterbox-multilingual-finetuned-arabic | FAIL | - | - | - | - |
+| k2-fsa/OmniVoice | FAIL | - | - | - | - |
+| KickItLikeShika/NileTTS-XTTS | FAIL | - | - | - | - |
+| loay/Arabic-OCR-DeepSeek-OCR-2 | FAIL | - | - | - | - |
+| loay/Arabic-OCR-Qwen2.5-VL-7B-Vision | FAIL | - | - | - | - |
+| madskills/doctr-fast_base-arabic | FAIL | - | - | - | - |
+| madskills/doctr-parseq-arabic | FAIL | - | - | - | - |
+| maloukafer/GLM-OCR-finetuned-documents | FAIL | - | - | - | - |
+| marwan-osama/Qari-OCR-0.4.0-VL-4B-Instruct-GGUF | FAIL | - | - | - | - |
+| mdnaseif/hafith | FAIL | - | - | - | - |
+| melsiddieg/deepseek_ocr_arabic_v6 | FAIL | - | - | - | - |
+| mimoha/ocr | FAIL | - | - | - | - |
+| mistralai/Voxtral-4B-TTS-2603 | PASS | mistralai/Voxtral-4B-TTS-2603 | cc-by-nc-4.0 | PASS | page-only |
+| mo1998/arabic-ocr-qwen2.5-vl | FAIL | - | - | - | - |
+| Moeeldouma/arabic-tts-xtts-v2 | PASS | Moeeldouma/arabic-tts-xtts-v2 | coqui-public-model-license | PASS | page-only |
+| mohajesmaeili/Qwen3-VL-2B-Persian-Arabic-Ocr-v1.0 | FAIL | - | - | - | - |
+| MohamedRashad/arabic-large-nougat | PASS | MohamedRashad/arabic-large-nougat | gpl-3.0 | PASS | page-only |
+| NAMAA-Space/NAMAA-Egyptian-TTS | FAIL | - | - | - | - |
+| NAMAA-Space/NAMAA-Saudi-TTS | PASS | NAMAA-Space/NAMAA-Saudi-TTS | mit | PASS | page-only |
+| NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct | PASS | NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct | apache-2.0 | PASS | page-only |
+| nineninesix/kani-tts-400m-ar | FAIL | - | - | - | - |
+| nipponjo/tts-arabic-onnx | FAIL | - | - | - | - |
+| numind/NuExtract3 | FAIL | - | - | - | - |
+| oddadmix/Katib-Qwen3.5-0.8B-0.1 | PASS | oddadmix/Katib-Qwen3.5-0.8B-0.1 | apache-2.0 | PASS | page-only |
+| oddadmix/lahgtna-chatterbox-v1 | FAIL | - | - | - | - |
+| oddadmix/lahgtna-omnivoice-v2 | FAIL | - | - | - | - |
+| oi-uae/oi-OCR | FAIL | - | - | - | - |
+| onnx-community/chatterbox-multilingual-ONNX | FAIL | - | - | - | - |
+| openbmb/VoxCPM2 | FAIL | - | - | - | - |
+| PaddlePaddle/PaddleOCR-VL-1.6 | FAIL | - | - | - | - |
+| Qwen/Qwen3-TTS-12Hz-0.6B-Base | FAIL | - | - | - | - |
+| Qwen/Qwen3-TTS-12Hz-1.7B-Base | FAIL | - | - | - | - |
+| rednote-hilab/dots.ocr | FAIL | - | - | - | - |
+| sherif1313/3arab-TTS-500M-v1 | FAIL | - | - | - | - |
+| sherif1313/3arab-TTS-500M-v1-VoiceDesign | FAIL | - | - | - | - |
+| sherif1313/Arabic-English-handwritten-OCR-Qwen3-VL-4B | FAIL | - | - | - | - |
+| sherif1313/Arabic-English-handwritten-OCR-v3 | FAIL | - | - | - | - |
+| sherif1313/Arabic-GLM-OCR-v2 | FAIL | - | - | - | - |
+| sherif1313/Arabic-handwritten-OCR-4bit-Qwen2.5-VL-3B-v3 | FAIL | - | - | - | - |
+| sherif1313/Arabic-Qwen3.5-OCR-v4 | FAIL | - | - | - | - |
+| silma-ai/silma-tts | PASS | silma-ai/silma-tts | apache-2.0 | PASS | page-only |
+| Supertone/supertonic-3 | PASS | Supertone/supertonic-3 | openrail | PASS | page-only |
+| surfiniaburger/unsloth_finetune_ocr_arabic | FAIL | - | - | - | - |
+| tawkeed-sa/tawkeed-ocr | PASS | tawkeed-sa/tawkeed-ocr | apache-2.0 | PASS | page-only |
+| tiiuae/Falcon-OCR | FAIL | - | - | - | - |
+| U4RASD/ar-ms-baseline | FAIL | - | - | - | - |
+| vadimbelsky/emirati-vits-male-1.0 | FAIL | - | - | - | - |
+| vadimbelsky/qwen3-TTS-KSA | FAIL | - | - | - | - |
+| vadimbelsky/qwen3.5-TTS-Emirati | FAIL | - | - | - | - |
+| vivooglobal/omnivoice-lora-ar | FAIL | - | - | - | - |

docs/live-deployment-checklist.md

@@ -0,0 +1,317 @@
+# Live Deployment Checklist
+
+Last checked: June 5, 2026.
+
+Use this checklist when you are ready to make the Arabic PDF Reader live for a family user. The goal is to keep the website simple while proving that the deployed worker can handle scanned Arabic OCR, create audio, and serve downloads.
+
+After deployment, give the non-technical user `docs/father-user-guide.md`.
+
+Official references:
+
+- Vercel FastAPI deployment: https://vercel.com/docs/frameworks/backend/fastapi
+- Vercel environment variables: https://vercel.com/docs/environment-variables
+- Hugging Face Docker Spaces: https://huggingface.co/docs/hub/main/en/spaces-sdks-docker
+- Hugging Face Spaces overview: https://huggingface.co/docs/hub/main/spaces-overview
+
+## 1. Local Package Check
+
+Run this before touching hosting:
+
+```powershell
+python scripts\check_deployment_readiness.py
+python scripts\audit_goal_readiness.py
+python scripts\prove_local_readiness.py --refresh-research --check-hf-metadata --hf-metadata-report outputs\hf-model-metadata.md
+python scripts\check_research_sources.py
+python scripts\check_research_sources.py --check-key-links
+python scripts\check_research_sources.py --check-representative-links
+python scripts\check_research_sources.py --check-hf-metadata --write-hf-metadata-report outputs\hf-model-metadata.md
+python scripts\export_hf_space.py --force
+```
+
+Expected result:
+
+```text
+Deployment readiness: no FAIL
+Goal audit: no FAIL; live-site and live-worker WARN entries until both reports exist
+Local readiness: ready, report written to outputs\local-readiness.json; metadata report written to outputs\hf-model-metadata.md
+Research sources: no FAIL; key and representative source links return HTTP 2xx/3xx; Hugging Face metadata reports expected model IDs and known licenses; `outputs\hf-model-metadata.md` records model freshness/license metadata
+outputs\huggingface-space exists
+```
+
+After you know the Hugging Face Space URL and Vercel production URL, generate a handoff sheet:
+
+```powershell
+python scripts\deployment_handoff.py https://your-space.hf.space --origin https://your-vercel-app.vercel.app --code 1234
+```
+
+This writes `outputs\deployment-handoff.md` with the exact worker secrets, Vercel environment variables, Hugging Face/Vercel CLI deploy commands, and final proof commands.
+It also generates a real `SECRET_KEY` for the worker and Vercel site and marks whether the URLs look real. Keep `outputs\deployment-handoff.md` private because it contains that deployment secret. If the handoff says `URLs look real: no`, replace placeholder, local, test, or reserved `example.*` URLs before running the live proof; the final audit will reject placeholder-looking evidence.
+
+To do the bundle export and handoff in one step, run:
+
+```powershell
+python scripts\prepare_live_deployment.py --worker-url https://your-space.hf.space --origin https://your-vercel-app.vercel.app --code 1234
+```
+
+This refreshes `outputs\huggingface-space`, writes `outputs\deployment-quickstart.md`, writes `outputs\deployment-handoff.md`, writes `outputs\vercel-production.env`, `outputs\worker-secrets.env`, `outputs\worker-space-settings.md`, and `outputs\apply-vercel-env.ps1`, and saves `outputs\deployment-prep.json` with the next command to run.
+Add `--secret-key <existing-secret>` only if you intentionally need to reuse a previous cookie-signing secret.
+
+If you do not know the live URLs yet, run:
+
+```powershell
+python scripts\prepare_live_deployment.py
+```
+
+This still refreshes the Hugging Face Space bundle and writes `outputs\deployment-quickstart.md`, which explains what to create on Hugging Face and Vercel before the final handoff can be generated.
+
+At any point, this command tells you the next proof step:
+
+```powershell
+python scripts\next_deployment_step.py --worker-url https://your-space.hf.space --origin https://your-vercel-app.vercel.app --code 1234
+```
+
+Use this fuller status command when you want to see whether saved reports are real live evidence or stale/test artifacts:
+
+```powershell
+python scripts\deployment_status.py --worker-url https://your-space.hf.space --origin https://your-vercel-app.vercel.app --code 1234
+```
+
+After `prepare_live_deployment.py` generates the Vercel and worker `.env` files, validate them first:
+
+```powershell
+python scripts\validate_deployment_env.py --vercel-env outputs\vercel-production.env --worker-env outputs\worker-secrets.env --worker-url https://your-space.hf.space --origin https://your-vercel-app.vercel.app
+```
+
+This catches the most common production mistake: leaving direct Hugging Face cloud TTS enabled on Vercel instead of routing downloadable audio through `WORKER_BASE_URL`.
+
+After the Hugging Face Space and Vercel production site are both deployed, run the quick Vercel worker diagnostic before uploading a large PDF:
+
+```powershell
+python scripts\hosted_preflight.py https://your-vercel-app.vercel.app --code 1234 --worker-url https://your-space.hf.space
+```
+
+The preflight writes `outputs\hosted-preflight.json` and must pass both `site worker reachable from vercel` and `site worker CORS ready`. If it says `cors-blocked`, set Hugging Face `CORS_ORIGINS` to the exact Vercel production URL, keep `COOKIE_SAMESITE=none` and `COOKIE_SECURE=1`, restart the Space, redeploy Vercel, and run the preflight again.
+
+## 2. Hugging Face Worker
+
+Create a Hugging Face Space with SDK set to **Docker**. Upload or push the generated folder:
+
+```text
+outputs\huggingface-space
+```
+
+The default Docker build installs the practical free CPU stack: SILMA, PaddleOCR Arabic, Tesseract Arabic, and eSpeak NG. For the first stronger worker, start with the smaller Arabic-trained OCR sidecars before the very heavy QARI path:
+
+```text
+INSTALL_TAWKEED_OCR=1
+INSTALL_KATIB_OCR=1
+INSTALL_ARABIC_QWEN_OCR=1
+INSTALL_ARABIC_GLM_OCR=1
+INSTALL_BASEER_OCR=1
+INSTALL_SUPERTONIC=1
+```
+
+If you only want to enable one smaller Arabic-trained OCR VLM first, use KATIB:
+
+```text
+INSTALL_KATIB_OCR=1
+```
+
+For a stronger worker that can handle the heavier Arabic-book VLM OCR, set this too:
+
+```text
+INSTALL_QARI_OCR=1
+```
+
+For a second smaller Arabic-trained OCR VLM, set this too:
+
+```text
+INSTALL_ARABIC_QWEN_OCR=1
+```
+
+For the Arabic-GLM OCR sidecar, set this too:
+
+```text
+INSTALL_ARABIC_GLM_OCR=1
+```
+
+For the Arabic-first Tawkeed/QARI v0.3 fork, set this too:
+
+```text
+INSTALL_TAWKEED_OCR=1
+```
+
+For the optional fast CPU comparison voice, set:
+
+```text
+INSTALL_SUPERTONIC=1
+```
+
+Only add heavy OCR build args on hardware with enough RAM/GPU. Leave them off for the first free CPU deployment, then enable Tawkeed, KATIB, Arabic-Qwen, Baseer, or QARI after the 5-page benchmark shows the model improves the target book. Supertonic is lighter than the OCR VLMs, but still optional because SILMA remains the Arabic-focused default.
+
+Set these Space secrets:
+
+```text
+ACCESS_CODE=1234
+SECRET_KEY=<generated by outputs\deployment-handoff.md>
+CORS_ORIGINS=https://your-vercel-app.vercel.app
+COOKIE_SAMESITE=none
+COOKIE_SECURE=1
+OCR_ENGINE=arabic-max
+DEFAULT_VOICE_ID=silma-local
+OUTPUT_RETENTION_DAYS=7
+OUTPUT_MAX_FILES=25
+AUDIO_FORMAT=mp3
+MP3_BITRATE=96k
+SILMA_ENABLE_NORMALIZER=0
+SILMA_FORCE_TASHKEEL=0
+SILMA_NORMALIZE_NUMBERS=0
+```
+
+Keep `OCR_ENGINE=arabic-max` for the first real deployment. It compares the strongest installed Arabic OCR outputs instead of trusting one engine.
+
+## 3. Vercel Website
+
+Deploy the repo on Vercel as a Python/FastAPI project. Set Vercel environment variables:
+
+```text
+ACCESS_CODE=1234
+SECRET_KEY=<generated by outputs\deployment-handoff.md>
+WORKER_BASE_URL=https://your-space.hf.space
+```
+
+Remove any temporary direct-cloud TTS variables you added during testing:
+
+```powershell
+vercel env rm ENABLE_DIRECT_CLOUD_TTS production --yes
+vercel env rm HF_API_TOKEN production --yes
+vercel env rm HF_TTS_MODEL production --yes
+vercel env rm DEFAULT_VOICE_ID production --yes
+```
+
+It is fine if Vercel says one of those variables does not exist. In production, downloadable audio should come from `WORKER_BASE_URL`, not the direct Hugging Face fallback.
+
+Temporary cloud fallback for short tests only:
+
+```text
+HF_API_TOKEN=<hugging-face-token>
+HF_TTS_MODEL=facebook/mms-tts-ara
+DEFAULT_VOICE_ID=mms-ara
+```
+
+Use Vercel's Production environment for the final public URL. Vercel must point at the worker with `WORKER_BASE_URL`; otherwise large scanned books fall back to browser OCR/cloud TTS and will be much slower.
+
+### Optional CLI Worker Upload
+
+If you have a Hugging Face write token, the repo can upload the prepared Docker Space bundle for you:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install huggingface_hub
+$env:HF_TOKEN="<your-hugging-face-write-token>"
+.\.venv\Scripts\python.exe scripts\export_hf_space.py --force
+.\.venv\Scripts\python.exe scripts\deploy_hf_space.py your-username/arabic-audio-reader-worker --json
+```
+
+The script creates or updates a Docker Space and prints the worker URL, normally `https://your-username-arabic-audio-reader-worker.hf.space`. Use that exact URL as Vercel `WORKER_BASE_URL`.
+
+After the worker URL is live, wire it into Vercel and verify the hosted shell in one step:
+
+```powershell
+.\.venv\Scripts\python.exe scripts\configure_vercel_worker.py https://your-username-arabic-audio-reader-worker.hf.space --site-url https://arabic-translator-mu.vercel.app --code 1234 --verify
+```
+
+Or run the whole remaining deployment flow after setting `HF_TOKEN`:
+
+```powershell
+.\.venv\Scripts\python.exe scripts\finish_live_deployment.py your-username/arabic-audio-reader-worker --site-url https://arabic-translator-mu.vercel.app --code 1234 --dry-run
+.\.venv\Scripts\python.exe scripts\finish_live_deployment.py your-username/arabic-audio-reader-worker --site-url https://arabic-translator-mu.vercel.app --code 1234
+```
+
+## 4. Live Worker Evidence
+
+After the worker URL is live and Vercel has a production URL, run:
+
+```powershell
+python scripts\prove_live_deployment.py https://your-space.hf.space --origin https://your-vercel-app.vercel.app --code 1234 --smoke-ocr-engine arabic-max --check-hf-metadata --hf-metadata-report outputs\hf-model-metadata.md --proof-out outputs\live-deployment-proof.json
+```
+
+Replace both placeholder URLs first. The live proof command intentionally refuses placeholder, local, non-HTTPS, swapped Hugging Face/Vercel, or same-service URLs before it makes any network calls.
+
+That command verifies the Vercel shell and worker, writes `outputs\site-verification.json`, `outputs\worker-verification.json`, and `outputs\live-deployment-proof.json`, and runs the final goal audit against the saved evidence. `outputs\live-deployment-proof.json` should contain `"complete": true` when the deployed system is proven. The manual equivalent is:
+
+```powershell
+python scripts\verify_site.py https://your-vercel-app.vercel.app --code 1234 --worker-url https://your-space.hf.space --json > outputs\site-verification.json
+python scripts\verify_worker.py https://your-space.hf.space --code 1234 --origin https://your-vercel-app.vercel.app --require-cors
+python scripts\verify_worker.py https://your-space.hf.space --code 1234 --origin https://your-vercel-app.vercel.app --require-cors --smoke-upload --smoke-scanned --smoke-ocr-engine arabic-max --json > outputs\worker-verification.json
+python scripts\audit_goal_readiness.py --worker-report outputs\worker-verification.json --site-report outputs\site-verification.json
+```
+
+The final audit is complete only when the saved Vercel site report proves login, Vercel platform mode, configured `WORKER_BASE_URL`, large-PDF readiness, disabled direct cloud fallback, and that Vercel can reach the worker diagnostics endpoint, and the saved worker report proves both embedded-text and scanned-OCR smoke checks:
+
+```text
+site login
+site platform vercel
+site worker configured
+site large PDF ready
+site production worker ready
+site hosted limits documented
+site recommended stack documented
+site direct cloud fallback disabled
+site worker diagnostics endpoint
+site worker reachable from vercel
+site worker CORS ready
+recommended stack documented
+smoke upload accepted
+smoke job complete
+smoke usable text
+smoke audio url
+smoke download url
+smoke audio bytes
+smoke audio file signature
+smoke download bytes
+smoke download file signature
+scanned smoke upload accepted
+scanned smoke job complete
+scanned smoke usable text
+scanned smoke OCR extraction
+scanned smoke audio url
+scanned smoke download url
+scanned smoke audio bytes
+scanned smoke audio file signature
+scanned smoke download bytes
+scanned smoke download file signature
+```
+
+## 5. First Real Arabic Book
+
+Before processing a 100 MB+ book, create a small representative sample:
+
+```powershell
+python scripts\select_test_pages.py C:\path\to\arabic-book.pdf --count 5 --out test_pdfs\book-best-5-pages.pdf
+python scripts\prepare_book_workflow.py test_pdfs\book-best-5-pages.pdf --sample-pages 1 --engine-preset balanced --benchmark-voices --write-report outputs\book-prep-report.md --write-env outputs\recommended-ocr.env
+```
+
+Use the report to choose the cleanest OCR and most comfortable voice. Only run the full book after:
+
+```text
+quality=good
+readyForTts=true
+the short audio sample sounds acceptable
+```
+
+If the lighter engines read badly and the worker is strong enough, add Tawkeed, Arabic-Qwen, KATIB, Baseer, and QARI-OCR to the benchmark:
+
+```powershell
+python scripts\prepare_book_workflow.py test_pdfs\book-best-5-pages.pdf --sample-pages 1 --engine-preset maximum --benchmark-voices --write-report outputs\book-prep-report.md --write-env outputs\recommended-ocr.env
+```
+
+For scanned Arabic books, QARI is the best Arabic-book OCR to try on a strong worker. Tawkeed, KATIB, Arabic-Qwen, and Baseer are better first upgrades when the worker is smaller. Keep `OCR_ENGINE=arabic-max` after installing any of them so the worker can compare Arabic-trained OCR against the practical fallbacks on the same pages.
+
+## 6. If The Free Worker Is Too Slow
+
+Free CPU workers can sleep and cold-start. Hugging Face's current free CPU Basic Space default is 2 vCPU, 16 GB RAM, and 50 GB non-persistent disk. That is acceptable for a personal demo, but long scanned books may take hours and generated audio should be treated as short-lived unless you add persistent/object storage. If the first real book is too slow:
+
+1. Keep Vercel as the website.
+2. Move only the worker to a stronger CPU/GPU host or a family computer.
+3. Keep the same `WORKER_BASE_URL` pattern.
+4. Re-run `verify_worker.py --smoke-upload --smoke-scanned --smoke-ocr-engine arabic-max --json` and `audit_goal_readiness.py --worker-report`.

docs/production-worker-architecture.md

@@ -0,0 +1,224 @@
+# Production Worker Architecture
+
+Last checked: June 2026.
+
+## Short Answer
+
+Use Vercel for the website shell and a separate worker for the heavy Arabic PDF-to-audio job.
+
+```text
+Vercel website
+  -> upload PDF or send job to worker
+  -> worker runs Arabic specialist OCR + SILMA
+  -> worker stores MP3/WAV
+  -> website shows progress and download link
+```
+
+The current local FastAPI app already behaves like that worker. `Dockerfile.worker` packages that worker for Docker hosts such as Hugging Face Spaces Docker, Render, or a small VPS.
+
+## Why Not Vercel Alone
+
+Vercel is excellent for the front door, but large Arabic scanned PDFs and neural TTS are long-running jobs. Vercel Hobby functions have limited duration, memory, and bundle size. Even when Fluid Compute is enabled, the free Hobby maximum is measured in minutes, while a 100 MB scanned book can take much longer.
+
+## Free/Low-Cost Host Reality
+
+| Host | Fit | Caveat |
+| --- | --- | --- |
+| Hugging Face Spaces CPU | Best free demo worker candidate | Free CPU Spaces sleep when unused and may cold-start slowly. |
+| Render free web service | Possible test worker | Free instances are for previews/hobby use and can suspend. |
+| Vercel Hobby | Good website host | Not a good place for EasyOCR/PaddleOCR/SILMA on large scanned PDFs. |
+| Fly.io | Good low-cost app host | New users no longer get a real always-free tier. |
+| Home PC or family mini PC | Best free always-on worker if available | Needs the computer online during jobs. |
+
+## Worker Dockerfile
+
+Build locally:
+
+```powershell
+python scripts\check_deployment_readiness.py
+docker build -f Dockerfile.worker -t arabic-audio-worker .
+docker run --rm -p 7860:7860 --env ACCESS_CODE=1234 --env SECRET_KEY=change-me arabic-audio-worker
+```
+
+For a stronger worker that actually installs the heavy Arabic-book OCR sidecar during the Docker build:
+
+```powershell
+docker build -f Dockerfile.worker --build-arg INSTALL_QARI_OCR=1 -t arabic-audio-worker:qari .
+```
+
+For a smaller Arabic-trained OCR worker, try KATIB first:
+
+```powershell
+docker build -f Dockerfile.worker --build-arg INSTALL_KATIB_OCR=1 -t arabic-audio-worker:katib .
+```
+
+For Arabic-Qwen3.5-OCR-v4:
+
+```powershell
+docker build -f Dockerfile.worker --build-arg INSTALL_ARABIC_QWEN_OCR=1 -t arabic-audio-worker:arabic-qwen .
+```
+
+For an experimental document-parser worker, add PaddleOCR-VL too:
+
+```powershell
+docker build -f Dockerfile.worker --build-arg INSTALL_QARI_OCR=1 --build-arg INSTALL_KATIB_OCR=1 --build-arg INSTALL_ARABIC_QWEN_OCR=1 --build-arg INSTALL_BASEER_OCR=1 --build-arg INSTALL_PADDLEOCR_VL=1 --build-arg INSTALL_SUPERTONIC=1 -t arabic-audio-worker:vl .
+```
+
+Do not use those build args on a small free CPU worker unless you are comfortable with much slower builds, larger images, cold starts, and possible memory failures.
+
+Then open:
+
+```text
+http://127.0.0.1:7860
+```
+
+The default image installs:
+
+- FastAPI app runtime.
+- Tesseract with Arabic language data.
+- eSpeak NG fallback voice.
+- SILMA TTS sidecar.
+- EasyOCR sidecar.
+- PaddleOCR sidecar.
+
+The worker bundle also includes setup scripts for optional heavy paths, but they are not installed by default in the free CPU image:
+
+- QARI-OCR sidecar for Arabic-native OCR on strong workers.
+- KATIB sidecar for smaller Arabic-trained OCR on workers.
+- Arabic-Qwen sidecar for 0.9B Arabic-trained OCR on workers.
+- PaddleOCR-VL sidecar for general VLM document parsing.
+- Habibi-TTS MSA sidecar for voice comparison.
+- Optional Supertonic 3 sidecar for fast CPU Arabic-capable voice comparison.
+- Surya OCR sidecar for hard scans on larger workers.
+
+`Dockerfile.worker` exposes `INSTALL_QARI_OCR=1`, `INSTALL_KATIB_OCR=1`, `INSTALL_ARABIC_QWEN_OCR=1`, `INSTALL_BASEER_OCR=1`, `INSTALL_PADDLEOCR_VL=1`, and `INSTALL_SUPERTONIC=1` build args so stronger workers can install QARI-OCR, KATIB, Arabic-Qwen, Baseer, PaddleOCR-VL, and the optional Supertonic CPU voice without editing the Dockerfile. This keeps the free CPU image practical while making the higher-quality free OCR paths and fast voice comparison path deployable.
+
+QARI-OCR 0.4 is the strongest Arabic-native OCR upgrade to test for a stronger worker. It is a 4B VLM fine-tuned for Islamic books and Arabic manuscripts, so keep it out of the default free CPU family-site worker unless a short Arabic-book benchmark proves it improves the actual pages and the worker has enough RAM/GPU. KATIB 0.8B and Arabic-Qwen3.5-OCR-v4 are the smaller Arabic-trained OCR upgrades to try when QARI is too heavy. If the worker is too small for QARI, set `QARI_OCR_MODEL=NAMAA-Space/Qari-OCR-v0.3-VL-2B-Instruct` to test the lighter older QARI path. PaddleOCR-VL-1.6 remains the main general document-parser upgrade to watch. In the website, leave the dropdown on `Maximum Arabic-trained OCR`; the worker will use whichever Arabic-trained sidecars are installed and fall back only when they are unavailable or lose the benchmark.
+
+The repo includes optional KATIB, Arabic-Qwen, QARI-OCR, and PaddleOCR-VL sidecar scripts for this evaluation path:
+
+```powershell
+.\scripts\setup_qari_ocr.ps1
+.\scripts\setup_katib_ocr.ps1
+.\scripts\setup_arabic_qwen_ocr.ps1
+.\scripts\setup_paddleocr_vl.ps1
+python scripts\benchmark_ocr.py C:\path\to\arabic-book.pdf --page-limit 1 --engines arabic arabic-qwen-ocr katib-ocr qari-ocr paddleocr paddleocr-vl tesseract
+```
+
+Do not add KATIB, Arabic-Qwen, QARI-OCR, or PaddleOCR-VL to the default free CPU Docker worker unless a real benchmark shows it improves the target book and the worker can handle the memory/runtime. For a stronger worker, set `OCR_ENGINE=arabic-max` for maximum quality comparison, or set `OCR_ENGINE=katib-ocr`, `OCR_ENGINE=arabic-qwen-ocr`, `OCR_ENGINE=qari-ocr`, or `OCR_ENGINE=paddleocr-vl` only after the short-sample benchmark wins.
+
+## Hugging Face Spaces Docker Path
+
+For the click-by-click live setup and final evidence commands, use:
+
+```text
+docs/live-deployment-checklist.md
+```
+
+Create a new Space:
+
+1. Choose **Docker** as the Space SDK.
+2. Export a clean Space bundle:
+
+   ```powershell
+   python scripts\export_hf_space.py --force
+   ```
+
+3. Upload or push the generated `outputs\huggingface-space` folder to the Space repo. It contains `Dockerfile` copied from `Dockerfile.worker`, only the needed app files, and no local `.env`, uploads, outputs, data, tests, or virtualenvs.
+4. Set secrets:
+   - `ACCESS_CODE`
+   - `SECRET_KEY`
+   - `CORS_ORIGINS=https://your-vercel-app.vercel.app`
+   - `COOKIE_SAMESITE=none`
+   - `COOKIE_SECURE=1`
+5. Keep `OCR_ENGINE=arabic-max` for quality, or switch to `OCR_ENGINE=paddleocr` only when you need a faster single-engine run.
+
+Then set this on Vercel:
+
+```text
+WORKER_BASE_URL=https://your-space.hf.space
+```
+
+The Vercel site logs into the worker with the same access code and sends large PDF uploads directly to the worker. That keeps 100 MB+ PDFs out of Vercel Functions.
+
+If the Vercel site is already unlocked but the worker is not, the app asks for the code once more. After that, both the Vercel site and the worker keep their own signed cookies.
+
+Verify the worker before using it:
+
+```powershell
+python scripts\check_deployment_readiness.py
+python scripts\validate_deployment_env.py --vercel-env outputs\vercel-production.env --worker-env outputs\worker-secrets.env --worker-url https://your-space.hf.space --origin https://your-vercel-app.vercel.app
+python scripts\verify_worker.py https://your-space.hf.space --code 1234 --origin https://your-vercel-app.vercel.app --require-cors
+python scripts\prove_live_deployment.py https://your-space.hf.space --origin https://your-vercel-app.vercel.app --code 1234 --smoke-ocr-engine arabic-max
+python scripts\verify_worker.py https://your-space.hf.space --code 1234 --origin https://your-vercel-app.vercel.app --require-cors --smoke-upload --smoke-ocr-engine arabic-max
+python scripts\verify_worker.py https://your-space.hf.space --code 1234 --origin https://your-vercel-app.vercel.app --require-cors --smoke-scanned --smoke-ocr-engine arabic-max
+python scripts\verify_worker.py https://your-space.hf.space --code 1234 --origin https://your-vercel-app.vercel.app --require-cors --smoke-upload --smoke-scanned --smoke-ocr-engine arabic-max --json > outputs\worker-verification.json
+python scripts\audit_goal_readiness.py --worker-report outputs\worker-verification.json
+```
+
+`prove_live_deployment.py` also writes `outputs\live-deployment-proof.json`; treat the live deployment as proven only when that file reports `"complete": true`.
+
+`check_deployment_readiness.py` verifies the repo packaging before deployment: required files, Vercel rewrites, no `functions`/`builds` conflict, Dockerfile copy sources, key worker packages, optional Arabic OCR sidecars, and ignore-file safety. `verify_worker.py` checks the live deployed worker after deployment, including upload limit, free storage headroom, Arabic OCR readiness, voice readiness, recommended stack metadata, and CORS. Add `--smoke-upload` when you want to prove the embedded-text path: upload PDF, poll job status, create audio, confirm usable text, check audio/download URLs, and verify audio file signatures. Add `--smoke-scanned` when you want to prove the OCR path with an image-only Arabic PDF and confirm it did not silently use embedded text. Use `--smoke-ocr-engine arabic-max` for final proof; use `--smoke-ocr-engine tesseract` only for a quick fallback-only sanity check.
+
+Free CPU Spaces sleep when idle. That is acceptable for a personal/family tool, but first jobs after sleep may be slow. Hugging Face's current free CPU Basic Space default is 2 vCPU, 16 GB RAM, and 50 GB non-persistent disk, so generated audio should remain short-lived unless you add persistent/object storage.
+
+For best SILMA pronunciation on Linux workers, you can build/setup with full normalization dependencies:
+
+```text
+SILMA_FULL_NORMALIZER_DEPS=1
+```
+
+Then set:
+
+```text
+SILMA_ENABLE_NORMALIZER=1
+SILMA_FORCE_TASHKEEL=1
+SILMA_NORMALIZE_NUMBERS=1
+```
+
+For an optional newer Arabic voice, install Habibi-TTS on the worker with `scripts/setup_habibi.sh` and select `Habibi Arabic MSA` in the website. Keep this optional because Habibi's MSA specialized model is Apache-2.0, while some unified/dialect models have non-commercial license limits. For a faster CPU comparison voice, install Supertonic 3 with `scripts/setup_supertonic.sh` or build with `INSTALL_SUPERTONIC=1`, then select `Supertonic Arabic CPU`.
+
+Leave those three values at `0` for the default Docker worker, which uses lightweight stubs for reliability.
+
+## Current Best Recommendation
+
+For the father's production site:
+
+1. Deploy the simple site on Vercel.
+2. Deploy the Docker worker on Hugging Face Spaces CPU as the free trial path.
+3. If cold starts are too frustrating, move only the worker to a cheap always-on CPU host or a family computer.
+4. Keep using `scripts/prepare_book_workflow.py` per book to select OCR settings and, when useful, compare voices from the cleaned OCR sample.
+5. Verify the winning OCR settings with `scripts/dry_run_pdf.py --from-extraction <benchmark-label>` before creating full-book audio.
+6. Try QARI-OCR when the lighter stack fails a representative 5-page Arabic sample and the worker has enough RAM/GPU.
+7. Try Surya or PaddleOCR-VL only for difficult scanned books and only on a worker that can handle the heavier model.
+8. Keep DIMI Arabic OCR v2, Loay Arabic-OCR-Qwen2.5-VL-7B, AtlasOCR, Ketaba-OCR, oi-OCR, Falcon-OCR, and Raqim-style correction on the research watchlist unless a real benchmark shows one beats the wired Arabic OCR stack on the target book. Tawkeed OCR, Arabic-GLM-OCR-v2, Arabic-Qwen3.5-OCR-v4, and Baseer are now wired optional sidecars, but still need the same short-book benchmark before full-book use.
+
+Example:
+
+```powershell
+python scripts\prepare_book_workflow.py C:\path\to\arabic-book.pdf --sample-pages 1 --engines easyocr paddleocr tesseract --verify-audio --benchmark-voices --write-env outputs\recommended-ocr.env --write-report outputs\book-prep-report.md
+python scripts\benchmark_ocr.py C:\path\to\arabic-book.pdf --page-limit 1 --engines best
+python scripts\dry_run_pdf.py C:\path\to\arabic-book.pdf --from-extraction best:tesseract@2x-psm4
+python scripts\verify_pipeline.py --pdf C:\path\to\arabic-book.pdf --from-extraction best:tesseract@2x-psm4 --voice-id espeak-ar-clear --out outputs\book-smoke.wav
+```
+
+The first command is the one-step path. With `--verify-audio`, it prefers the local SILMA voice when installed, then tries Habibi/Supertonic where available, then falls back to eSpeak NG, and synthesizes only a short cleaned sample by default so you can judge pronunciation without creating a full-page audio file. With `--benchmark-voices`, it writes short comparison files for the selected voices using the same cleaned OCR sample. With `--write-env`, it saves only the recommended OCR settings, not secrets; dry-run, external TTS sample export, and pipeline verification can read that snippet with `--env-file`. With `--write-report`, it saves a readable Markdown report for the book. Its JSON output includes `estimateFullBook`, which uses the sample to estimate OCR time, speech characters, and TTS time, `commands` with copy-pasteable follow-up commands including `export_tts_sample.py` for Mishkala/Tashkeel-350M preprocessing, 3arab/Supertonic/MOSS/OmniVoice/Arabic-LoRA/Lahgtna/NAMAA Saudi/Chatterbox/Chatterbox ONNX/tts-arabic-onnx/Spark/Sofelia/VoxCPM and personal/non-commercial Voxtral comparisons, `export_ocr_sample_images.py` for DIMI/Loay-Qwen2.5/Atlas/Ketaba/oi-OCR/Falcon OCR comparisons plus wired sidecar sample scoring when needed, and `score_external_ocr.py` for scoring external OCR text with the app's Arabic speech-readiness metrics, plus `nextSteps` for what to do before the full book run. The following three commands are the manual equivalent when you want to inspect each stage. If the dry run reports `quality=good` and `readyForTts=true`, and the pipeline smoke test creates listenable audio, copy the benchmark's recommended environment values into the worker before processing the full book.
+
+## Source Links
+
+- Vercel function limits: https://vercel.com/docs/functions/limitations
+- Render free services: https://render.com/free
+- Hugging Face Spaces overview: https://huggingface.co/docs/hub/spaces-overview
+- Hugging Face Spaces GPU/free hardware notes: https://huggingface.co/docs/hub/spaces-gpus
+- Fly.io pricing and legacy free allowances: https://fly.io/docs/about/pricing
+- QARI-OCR 0.4 model: https://huggingface.co/NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct
+- QARI-OCR v0.3 lighter model: https://huggingface.co/NAMAA-Space/Qari-OCR-v0.3-VL-2B-Instruct
+- KATIB 0.8B Arabic OCR model: https://huggingface.co/oddadmix/Katib-Qwen3.5-0.8B-0.1
+- Arabic-Qwen3.5-OCR-v4: https://huggingface.co/sherif1313/Arabic-Qwen3.5-OCR-v4
+- Ketaba-OCR LoRA: https://huggingface.co/HassanB4/Ketaba-OCR-LoRA
+- Tawkeed OCR: https://huggingface.co/tawkeed-sa/tawkeed-ocr
+- Arabic-GLM-OCR-v2: https://huggingface.co/sherif1313/Arabic-GLM-OCR-v2
+- DIMI Arabic OCR v2: https://huggingface.co/AhmedZaky1/DIMI-Arabic-OCR-V2
+- Loay Arabic-OCR-Qwen2.5-VL-7B: https://huggingface.co/loay/Arabic-OCR-Qwen2.5-VL-7B-Vision
+- PaddleOCR-VL-1.6 model: https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.6
+- PaddleOCR-VL-1.6 paper: https://arxiv.org/abs/2606.03264

docs/recommended-decision-card.json

@@ -0,0 +1,138 @@
+{
+  "title": "Recommended Free Arabic PDF To Audio Decision Card",
+  "currentDefault": {
+    "pdf": "PyMuPDF embedded text first",
+    "scannedPdfOcr": "OCR_ENGINE=arabic-max",
+    "voice": "SILMA TTS (silma-local)",
+    "audioStorage": "worker-local retained downloads",
+    "hosting": "Vercel shell plus Docker worker via WORKER_BASE_URL"
+  },
+  "whyThisDefault": [
+    "Uses free/local software by default instead of paid cloud TTS.",
+    "Avoids OCR when embedded Arabic text already exists.",
+    "Uses Arabic-trained OCR sidecars when available and keeps Tesseract/PaddleOCR fallbacks.",
+    "Uses an Arabic-focused Apache-2.0 voice first, with eSpeak NG only as a fallback.",
+    "Keeps large PDF and audio work off Vercel Functions by delegating to the worker."
+  ],
+  "installFirstOnStrongerWorker": [
+    {
+      "name": "QARI-OCR 0.4",
+      "kind": "ocr",
+      "license": "Apache-2.0",
+      "why": "Directly trained for Arabic OCR on Islamic books and Arabic manuscripts.",
+      "nextStep": "Install the sidecar or build the worker with INSTALL_QARI_OCR=1, then benchmark against arabic-max/arabic/arabic-qwen-ocr/katib-ocr/paddleocr/tesseract on the 5-page sample."
+    },
+    {
+      "name": "PaddleOCR-VL-1.6",
+      "kind": "ocr",
+      "license": "Apache-2.0",
+      "why": "Fresh Apache-2.0 PaddleOCR document parser release with a June 2026 paper signal; the model card claims SOTA document parsing/text performance and the license file is Apache-2.0, but Arabic-book quality still needs same-page scoring.",
+      "nextStep": "Build with INSTALL_PADDLEOCR_VL=1 only after the smaller Arabic OCR stack is not clean enough, then benchmark the same 5-page Arabic sample before any full-book run."
+    },
+    {
+      "name": "KATIB 0.8B",
+      "kind": "ocr",
+      "license": "Apache-2.0",
+      "why": "Fine-tuned specifically for Arabic OCR, including printed and handwritten text, while being much smaller than QARI 4B.",
+      "nextStep": "Install the sidecar or build the worker with INSTALL_KATIB_OCR=1, then benchmark against arabic-max/arabic/arabic-qwen-ocr/qari-ocr/paddleocr/tesseract on the 5-page sample."
+    },
+    {
+      "name": "Arabic-GLM-OCR-v2",
+      "kind": "ocr",
+      "license": "Apache-2.0",
+      "why": "Recent Arabic OCR model card claims strong Arabic document extraction and noise reduction; it is wired as an optional sidecar so it can be scored against QARI/KATIB/Arabic-Qwen/Baseer on the target book pages.",
+      "nextStep": "Install the sidecar or build the worker with INSTALL_ARABIC_GLM_OCR=1, then benchmark it on the same 5-page sample before any full-book run."
+    },
+    {
+      "name": "Arabic-Qwen3.5-OCR-v4",
+      "kind": "ocr",
+      "license": "Apache-2.0",
+      "why": "Recent Arabic OCR model card claims Arabic printed, handwritten, classical, and diacritic handling in a smaller 0.9B model.",
+      "nextStep": "Install the sidecar or build the worker with INSTALL_ARABIC_QWEN_OCR=1, then benchmark against arabic-max/arabic/katib-ocr/qari-ocr/paddleocr/tesseract on the 5-page sample."
+    },
+    {
+      "name": "Tawkeed OCR",
+      "kind": "ocr",
+      "license": "Apache-2.0",
+      "why": "Arabic-first OCR model forked from QARI-OCR v0.3 and fine-tuned for Arabic documents, handwriting, and scene text; useful to test when QARI 0.4 is too heavy or when edge-style deployment matters.",
+      "nextStep": "Install the sidecar or build the worker with INSTALL_TAWKEED_OCR=1, then benchmark against QARI 0.4, KATIB, Arabic-Qwen, Baseer, and Tesseract on the same 5-page sample."
+    },
+    {
+      "name": "Baseer OCR V1.0",
+      "kind": "ocr",
+      "license": "Apache-2.0",
+      "why": "Arabic-specific VLM OCR for complex legal documents, multi-column layouts, stamps, tables, and handwritten/printed Arabic.",
+      "nextStep": "Install the sidecar or build the worker with INSTALL_BASEER_OCR=1, then benchmark against arabic-max/arabic/arabic-qwen-ocr/katib-ocr/qari-ocr/paddleocr/tesseract on the 5-page sample."
+    },
+    {
+      "name": "Habibi-TTS MSA",
+      "kind": "tts",
+      "license": "Apache-2.0 for specialized MSA; other variants may be non-commercial",
+      "why": "Arabic-specific 2026 TTS family worth comparing against SILMA on MSA passages.",
+      "nextStep": "Install the optional sidecar and listen against the same cleaned OCR sample."
+    },
+    {
+      "name": "Supertonic 3",
+      "kind": "tts",
+      "license": "OpenRAIL model, MIT sample code",
+      "why": "Supertonic 3 supports Arabic, runs locally with ONNX on CPU, and is much smaller than GPU-class multilingual voices, making it a practical free benchmark voice for long-book workers.",
+      "nextStep": "Install the sidecar with scripts/setup_supertonic.ps1 or build with INSTALL_SUPERTONIC=1, then benchmark it against SILMA/Habibi on the same cleaned Arabic text."
+    }
+  ],
+  "benchmarkBeforePromoting": {
+    "ocrCount": 33,
+    "ttsCount": 32,
+    "ocrFirst": [
+      "QARI-OCR 0.4 GGUF",
+      "oi-OCR",
+      "NuExtract3",
+      "Qianfan-OCR",
+      "Chandra OCR 2",
+      "dots.ocr",
+      "olmOCR Arabic LoRA v2",
+      "Arabic Large Nougat",
+      "DocTR Arabic FAST/PARSEQ",
+      "Kraken/eScriptorium Arabic script",
+      "Kairawan/Qalamus manuscript OCR",
+      "GLM-OCR Arabic/French documents"
+    ],
+    "ttsFirst": [
+      "Mishkala Tashkeel",
+      "Tashkeel-350M",
+      "Mushkil",
+      "Thaka KSAA-2026 speech diacritization",
+      "3arab-TTS 500M",
+      "KaniTTS Arabic",
+      "Emirati VITS Male",
+      "VoxCPM2",
+      "Voxtral TTS",
+      "OmniVoice",
+      "OmniVoice Arabic LoRA",
+      "Arabic-text-to-speech OmniVoice",
+      "Lahgtna OmniVoice v2",
+      "TADA multilingual TTS",
+      "Lahgtna Chatterbox",
+      "NAMAA-Saudi-TTS"
+    ],
+    "voicePriority": "Use SILMA first, then benchmark Habibi MSA and OmniVoice on stronger hardware. Keep KaniTTS benchmark-only until its lfm1.0 Hugging Face license metadata is reconciled with the model-card Apache-2.0 text."
+  },
+  "promotionGate": {
+    "sameSample": "same selected Arabic pages or same cleaned Arabic TTS text",
+    "scoreJsonRequired": true,
+    "tool": "scripts\\model_promotion_gate.py",
+    "requires": [
+      "candidate beats the current stack",
+      "license is acceptable for the deployment",
+      "worker runtime and memory are acceptable",
+      "privacy/API terms are clear",
+      "human Arabic review confirms faithful text/audio"
+    ]
+  },
+  "commands": {
+    "refreshResearch": "python scripts\\refresh_research_evidence.py --watchlist-report docs\\research-watchlist.md --recommendation-report docs\\recommended-free-stack.md",
+    "sourceAudit": "python scripts\\check_research_sources.py --json",
+    "prepareBook": "python scripts\\prepare_book_workflow.py C:\\path\\to\\arabic-book.pdf --sample-pages 1 --engine-preset balanced --verify-audio --write-env outputs\\recommended-ocr.env --write-report outputs\\book-prep-report.md",
+    "externalOcrSample": "python scripts\\export_ocr_sample_images.py C:\\path\\to\\arabic-book.pdf --out-dir outputs\\external-ocr-sample",
+    "externalTtsSample": "python scripts\\export_tts_sample.py C:\\path\\to\\arabic-book.pdf --env-file outputs\\recommended-ocr.env --out-dir outputs\\external-tts-sample"
+  }
+}

docs/recommended-decision-card.md

@@ -0,0 +1,70 @@
+# Recommended Free Arabic PDF To Audio Decision Card
+
+## Current Default
+
+| Layer | Choice |
+| --- | --- |
+| pdf | PyMuPDF embedded text first |
+| scannedPdfOcr | OCR_ENGINE=arabic-max |
+| voice | SILMA TTS (silma-local) |
+| audioStorage | worker-local retained downloads |
+| hosting | Vercel shell plus Docker worker via WORKER_BASE_URL |
+
+## Why
+
+- Uses free/local software by default instead of paid cloud TTS.
+- Avoids OCR when embedded Arabic text already exists.
+- Uses Arabic-trained OCR sidecars when available and keeps Tesseract/PaddleOCR fallbacks.
+- Uses an Arabic-focused Apache-2.0 voice first, with eSpeak NG only as a fallback.
+- Keeps large PDF and audio work off Vercel Functions by delegating to the worker.
+
+## Benchmark Queue
+
+OCR benchmark candidates tracked: 33
+TTS benchmark candidates tracked: 32
+
+OCR first lane: QARI-OCR 0.4 GGUF, oi-OCR, NuExtract3, Qianfan-OCR, Chandra OCR 2, dots.ocr, olmOCR Arabic LoRA v2, Arabic Large Nougat, DocTR Arabic FAST/PARSEQ, Kraken/eScriptorium Arabic script, Kairawan/Qalamus manuscript OCR, GLM-OCR Arabic/French documents
+TTS first lane: Mishkala Tashkeel, Tashkeel-350M, Mushkil, Thaka KSAA-2026 speech diacritization, 3arab-TTS 500M, KaniTTS Arabic, Emirati VITS Male, VoxCPM2, Voxtral TTS, OmniVoice, OmniVoice Arabic LoRA, Arabic-text-to-speech OmniVoice, Lahgtna OmniVoice v2, TADA multilingual TTS, Lahgtna Chatterbox, NAMAA-Saudi-TTS
+
+## Promotion Gate
+
+Tool: `scripts\model_promotion_gate.py`
+Same sample: same selected Arabic pages or same cleaned Arabic TTS text
+
+- candidate beats the current stack
+- license is acceptable for the deployment
+- worker runtime and memory are acceptable
+- privacy/API terms are clear
+- human Arabic review confirms faithful text/audio
+
+## Commands
+
+refreshResearch:
+
+```powershell
+python scripts\refresh_research_evidence.py --watchlist-report docs\research-watchlist.md --recommendation-report docs\recommended-free-stack.md
+```
+
+sourceAudit:
+
+```powershell
+python scripts\check_research_sources.py --json
+```
+
+prepareBook:
+
+```powershell
+python scripts\prepare_book_workflow.py C:\path\to\arabic-book.pdf --sample-pages 1 --engine-preset balanced --verify-audio --write-env outputs\recommended-ocr.env --write-report outputs\book-prep-report.md
+```
+
+externalOcrSample:
+
+```powershell
+python scripts\export_ocr_sample_images.py C:\path\to\arabic-book.pdf --out-dir outputs\external-ocr-sample
+```
+
+externalTtsSample:
+
+```powershell
+python scripts\export_tts_sample.py C:\path\to\arabic-book.pdf --env-file outputs\recommended-ocr.env --out-dir outputs\external-tts-sample
+```

docs/recommended-free-stack.md

@@ -0,0 +1,86 @@
+# Recommended Free Arabic PDF To Audio Stack
+
+This is the compact decision report generated from the current research watchlist.
+
+## Use Now
+
+| Layer | Recommendation | Why |
+| --- | --- | --- |
+| Embedded PDFs | PyMuPDF text extraction first | It is free, fast, and avoids OCR errors when the PDF already contains usable Arabic text. |
+| Scanned PDFs | `OCR_ENGINE=arabic-max` | It compares the installed Arabic-capable OCR paths and keeps the cleanest speech-ready text. |
+| Default voice | SILMA TTS | Arabic-focused Fusha/MSA voice with normalization and tashkeel options. |
+| Download/storage | Worker-local retained audio files | Free by default and avoids Vercel's 4.5 MB function payload limit; Hugging Face free CPU disk is 50 GB but non-persistent, so downloads are short-lived. |
+| Hosted shape | Vercel shell plus Docker worker via `WORKER_BASE_URL` | Vercel serves the easy website while the worker handles large PDFs, OCR, and TTS on free CPU Space hardware when the job size is reasonable. |
+
+## Install First On A Stronger Worker
+
+| Candidate | Type | Why | Next Step |
+| --- | --- | --- | --- |
+| QARI-OCR 0.4 | ocr | Directly trained for Arabic OCR on Islamic books and Arabic manuscripts. | Install the sidecar or build the worker with INSTALL_QARI_OCR=1, then benchmark against arabic-max/arabic/arabic-qwen-ocr/katib-ocr/paddleocr/tesseract on the 5-page sample. |
+| PaddleOCR-VL-1.6 | ocr | Fresh Apache-2.0 PaddleOCR document parser release with a June 2026 paper signal; the model card claims SOTA document parsing/text performance and the license file is Apache-2.0, but Arabic-book quality still needs same-page scoring. | Build with INSTALL_PADDLEOCR_VL=1 only after the smaller Arabic OCR stack is not clean enough, then benchmark the same 5-page Arabic sample before any full-book run. |
+| KATIB 0.8B | ocr | Fine-tuned specifically for Arabic OCR, including printed and handwritten text, while being much smaller than QARI 4B. | Install the sidecar or build the worker with INSTALL_KATIB_OCR=1, then benchmark against arabic-max/arabic/arabic-qwen-ocr/qari-ocr/paddleocr/tesseract on the 5-page sample. |
+| Arabic-GLM-OCR-v2 | ocr | Recent Arabic OCR model card claims strong Arabic document extraction and noise reduction; it is wired as an optional sidecar so it can be scored against QARI/KATIB/Arabic-Qwen/Baseer on the target book pages. | Install the sidecar or build the worker with INSTALL_ARABIC_GLM_OCR=1, then benchmark it on the same 5-page sample before any full-book run. |
+| Arabic-Qwen3.5-OCR-v4 | ocr | Recent Arabic OCR model card claims Arabic printed, handwritten, classical, and diacritic handling in a smaller 0.9B model. | Install the sidecar or build the worker with INSTALL_ARABIC_QWEN_OCR=1, then benchmark against arabic-max/arabic/katib-ocr/qari-ocr/paddleocr/tesseract on the 5-page sample. |
+| Tawkeed OCR | ocr | Arabic-first OCR model forked from QARI-OCR v0.3 and fine-tuned for Arabic documents, handwriting, and scene text; useful to test when QARI 0.4 is too heavy or when edge-style deployment matters. | Install the sidecar or build the worker with INSTALL_TAWKEED_OCR=1, then benchmark against QARI 0.4, KATIB, Arabic-Qwen, Baseer, and Tesseract on the same 5-page sample. |
+| Baseer OCR V1.0 | ocr | Arabic-specific VLM OCR for complex legal documents, multi-column layouts, stamps, tables, and handwritten/printed Arabic. | Install the sidecar or build the worker with INSTALL_BASEER_OCR=1, then benchmark against arabic-max/arabic/arabic-qwen-ocr/katib-ocr/qari-ocr/paddleocr/tesseract on the 5-page sample. |
+| Habibi-TTS MSA | tts | Arabic-specific 2026 TTS family worth comparing against SILMA on MSA passages. | Install the optional sidecar and listen against the same cleaned OCR sample. |
+| Supertonic 3 | tts | Supertonic 3 supports Arabic, runs locally with ONNX on CPU, and is much smaller than GPU-class multilingual voices, making it a practical free benchmark voice for long-book workers. | Install the sidecar with scripts/setup_supertonic.ps1 or build with INSTALL_SUPERTONIC=1, then benchmark it against SILMA/Habibi on the same cleaned Arabic text. |
+
+## Benchmark Before Promoting
+
+These are promising free/open candidates, but they should not replace the default stack until they win on the same 5-page Arabic sample and same cleaned TTS text.
+
+### OCR
+
+| Candidate | License | Why It Stays Benchmark-Only |
+| --- | --- | --- |
+| QARI-OCR 0.4 GGUF | Apache-2.0 via QARI 0.4 model card; confirm GGUF packaging metadata before production | Benchmark the GGUF package externally on the same exported Arabic pages against the wired QARI sidecar, KATIB, Arabic-Qwen, Baseer, PaddleOCR, and Tesseract before considering a llama.cpp-style worker path. |
+| oi-OCR | Apache-2.0 | Export the same selected Arabic page images and compare its Markdown/text output against QARI/KATIB/Arabic-Qwen/PaddleOCR/Tesseract before considering any wiring. |
+| NuExtract3 | Apache-2.0 | Use document-to-Markdown/content mode on the exported page images and score the resulting Arabic text against QARI/KATIB/Arabic-Qwen/Baseer/PaddleOCR/Tesseract before promotion. |
+| Qianfan-OCR | Apache-2.0 | Benchmark externally only after QARI/KATIB/Arabic-Qwen/Baseer/PaddleOCR are not clean enough; score it on the same exported Arabic book pages before considering any worker wiring. |
+| Chandra OCR 2 | Apache-2.0 code; modified OpenRAIL-M model weights | Benchmark externally on the same exported page images for hard layouts, tables, forms, or mixed-language pages; keep QARI/KATIB/Arabic-Qwen/Baseer first for Arabic books unless Chandra wins same-page scoring and the license/runtime fit. |
+| dots.ocr | MIT | Run externally on the same exported Arabic page images and score the resulting text against QARI/KATIB/Arabic-Qwen/Baseer/PaddleOCR/Tesseract before considering any worker wiring. |
+| olmOCR Arabic LoRA v2 | Apache-2.0 adapter; confirm base model license/runtime before production | Run externally on the same exported full-page manuscript images and compare against Ketaba, QARI, HAFITH/Glimpse line workflows, Kraken/eScriptorium, and the wired Arabic OCR baseline before considering any sidecar work. |
+| Arabic Large Nougat | GPL-3.0 | Run externally on the same exported Arabic book page images and compare Markdown/text output against QARI, KATIB, Arabic-Qwen, Baseer, PaddleOCR, Tesseract, and the other external OCR benchmarks before considering any separate license-aware workflow. |
+| DocTR Arabic FAST/PARSEQ | Apache-2.0 detector; recognition card lacks clear metadata, confirm before production | Benchmark externally on the same exported Arabic page images and promote only if the recognition model license is confirmed and it beats PaddleOCR/Tesseract/EasyOCR on book text ordering and word preservation. |
+| Kraken/eScriptorium Arabic script | Apache-2.0 engine; model license depends on selected Kraken model | Export the same selected page images, run Kraken/eScriptorium with an Arabic-script recognition model or line-cropped workflow, then score the resulting text against the wired Arabic OCR stack before considering any sidecar work. |
+| Kairawan/Qalamus manuscript OCR | free web service; engine/package license not established | Use only as an external comparison when the source PDF is manuscript-like; do not wire it into the app unless a reusable open engine, API terms, privacy story, and same-page scoring beat QARI/KATIB/Kraken/HAFITH on the selected sample. |
+| GLM-OCR Arabic/French documents | check model card/base license before production use | Benchmark externally for administrative/form-like Arabic PDFs and compare against Arabic-GLM-OCR-v2, QARI, KATIB, Baseer, PaddleOCR, and Tesseract before wiring. |
+
+### TTS
+
+| Candidate | License | Why It Stays Benchmark-Only |
+| --- | --- | --- |
+| Mishkala Tashkeel | Apache-2.0 | Benchmark on the same cleaned speech sample before wiring. Promote only if listening tests improve pronunciation without changing meaning or adding distracting/incorrect harakat. |
+| Tashkeel-350M | Apache-2.0 | Export the same cleaned Arabic TTS sample, create a Tashkeel-350M diacritized copy, synthesize plain/Mishkala/Tashkeel-350M with the same voice, and score meaning preservation plus long-listen comfort. |
+| Mushkil | Apache-2.0 | Export the same cleaned Arabic TTS sample, create a Mushkil-diacritized copy, synthesize plain/Mishkala/Tashkeel-350M/Mushkil with the same voice, and score meaning preservation plus long-listen comfort. |
+| Thaka KSAA-2026 speech diacritization | CC BY 4.0 paper; implementation/model license not established | Track for released code/weights or a permissive checkpoint. Until then, keep website preprocessing limited to same-sample Mishkala/Tashkeel-350M/Mushkil listening tests and meaning-preservation scoring. |
+| 3arab-TTS 500M | Apache-2.0 | Export the same cleaned Arabic text used for SILMA/Habibi, then compare base and VoiceDesign variants for audiobook comfort, stability, and long-form pacing. |
+| KaniTTS Arabic | model card says Apache-2.0, but Hugging Face metadata reports lfm1.0; confirm before production | Export the same cleaned Arabic sample used for SILMA/Habibi, then benchmark naturalness, skipped words, pacing, runtime, and license fit before considering app wiring. |
+| Emirati VITS Male | Apache-2.0 | Benchmark only when the target PDF benefits from Emirati/Gulf pronunciation; keep SILMA/Habibi ahead for MSA books unless listening tests say otherwise. |
+| VoxCPM2 | Apache-2.0 | Benchmark externally with the same cleaned Arabic sample before deciding whether it is worth integrating. |
+| Voxtral TTS | CC-BY-NC-4.0 | Benchmark only as a personal/non-commercial strong-worker comparison using the same cleaned Arabic sample; do not wire it as the default public/free website voice. |
+| OmniVoice | Apache-2.0 | Export the same cleaned Arabic text used for SILMA/Habibi and compare Arabic naturalness, speed, and setup complexity before wiring it into the app. |
+| OmniVoice Arabic LoRA | Apache-2.0 | Benchmark only after the base OmniVoice command is working, using the exact same cleaned Arabic sample and reference audio. |
+| Arabic-text-to-speech OmniVoice | Apache-2.0 | Export the same cleaned Arabic sample used for SILMA/Habibi and compare naturalness, skipped words, repetition, runtime, and setup complexity before any app wiring. |
+| Lahgtna OmniVoice v2 | license not declared on model card | Benchmark externally only when dialect pronunciation matters, confirm licensing before production, and keep SILMA/Habibi ahead for MSA books until listening tests prove otherwise. |
+| TADA multilingual TTS | Llama 3.2 license | Export the same cleaned Arabic sample and benchmark with language='ar' only if the Llama 3.2 license is acceptable; keep SILMA/Habibi ahead for the permissive default. |
+| Lahgtna Chatterbox | MIT | Export the same cleaned Arabic text and listen for repetition/stability before considering app wiring. |
+| NAMAA-Saudi-TTS | MIT | Benchmark only when Saudi dialect pronunciation fits the target PDF; keep SILMA/Habibi first for MSA books and compare against Saudi Arabic Qwen3-TTS and Emirati voices before wiring. |
+
+### Current Voice Priority
+
+Use SILMA first for the practical free Arabic audiobook voice. On a stronger worker, benchmark Habibi MSA and OmniVoice next. Keep KaniTTS benchmark-only until the `lfm1.0` Hugging Face license metadata is reconciled with the model-card Apache-2.0 text.
+
+## Promotion Rule
+
+Promote a model only when all of these are true:
+
+1. It is free for the intended personal/family use.
+2. Its license is acceptable for the deployment.
+3. It beats the current stack on the same selected Arabic pages or same cleaned Arabic voice sample.
+4. It preserves Arabic reading order, words, and pronunciation better than the default.
+5. Its runtime is acceptable for the target worker.
+6. The generated JSON score passes `scripts\model_promotion_gate.py` after human review.
+
+Current practical default: PyMuPDF -> `arabic-max` OCR -> SILMA TTS -> downloadable worker audio.

docs/source-evidence.md

@@ -0,0 +1,146 @@
+# Source Evidence For The Free Arabic PDF-To-Audio Stack
+
+Last checked: June 7, 2026.
+
+This file records why each source matters to the current recommendation. It is intentionally short so it can be checked quickly before deployment.
+
+See `docs/huggingface-model-metadata.md` for the latest tracked Hugging Face model ID, license, and last-modified snapshot used by this recommendation.
+
+## OCR Sources
+
+| Source | Link | Evidence Used |
+| --- | --- | --- |
+| EasyOCR | https://github.com/JaidedAI/EasyOCR | Free local OCR engine with Arabic support; useful fallback for older scans and layouts. |
+| PaddleOCR PP-OCRv5 multilingual recognition | https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/algorithm/PP-OCRv5/PP-OCRv5_multi_languages.en.md | Documents Arabic-script recognition model support, including `arabic_PP-OCRv5_mobile_rec`. |
+| PaddleOCR OCR pipeline | https://www.paddleocr.ai/main/en/version3.x/pipeline_usage/OCR.html | Confirms the current PaddleOCR OCR pipeline interface used by the sidecar. |
+| PaddleOCR latest docs | https://www.paddleocr.ai/latest/en/index.html | Tracks current PaddleOCR releases and document parser direction. |
+| PP-OCRv5 paper | https://arxiv.org/abs/2603.24373 | Supports the lightweight OCR default choice before heavy VLM OCR. |
+| QARI-OCR 0.4 model | https://huggingface.co/NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct | Arabic-specific OCR VLM trained for Islamic books and Arabic manuscripts, Apache-2.0, used as the optional strong-worker Arabic OCR upgrade; current model card shows no hosted inference provider, so it needs a local/worker runtime. |
+| QARI-OCR 0.4 GGUF | https://huggingface.co/marwan-osama/Qari-OCR-0.4.0-VL-4B-Instruct-GGUF | Newer GGUF packaging signal for QARI-OCR 0.4; keep benchmark-only until it matches the wired QARI sidecar on the same Arabic pages and its packaging/license metadata is confirmed. |
+| QARI-OCR v0.3 lighter model | https://huggingface.co/NAMAA-Space/Qari-OCR-v0.3-VL-2B-Instruct | Smaller configurable QARI fallback for workers that cannot handle the 4B model. |
+| QARI-OCR paper | https://arxiv.org/abs/2506.02295 | Research background for QARI's Arabic OCR/document understanding role. |
+| KATIB 0.8B Arabic OCR model | https://huggingface.co/oddadmix/Katib-Qwen3.5-0.8B-0.1 | Apache-2.0 Arabic OCR VLM fine-tuned for Arabic printed and handwritten text; wired as the smaller optional Arabic-trained OCR sidecar. |
+| Ketaba-OCR LoRA | https://huggingface.co/HassanB4/Ketaba-OCR-LoRA | Apache-2.0 Arabic manuscript OCR LoRA benchmark candidate; not wired because it needs a separate base VLM plus adapter setup, but worth testing when QARI/KATIB/PaddleOCR struggle. |
+| Qari-OCR-LoRA | https://huggingface.co/HassanB4/Qari-OCR-LoRA | Apache-2.0 experimental QARI-family manuscript OCR LoRA from the NakbaNLP 2026 Arabic manuscript task; keep as a secondary external benchmark after Ketaba because the model card says Ketaba was the primary winning submission. |
+| Tawkeed OCR | https://huggingface.co/tawkeed-sa/tawkeed-ocr | Apache-2.0 Arabic-first OCR model forked from QARI-OCR v0.3 and fine-tuned for Arabic documents, handwriting, and scene text; wired as an optional sidecar for short-sample benchmarks when QARI-OCR 0.4 is too heavy or edge-style Arabic OCR matters. |
+| PaddleOCR-VL-1.6 model | https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.6 | Apache-2.0 0.9B document parser model; useful as a strong-worker OCR/layout benchmark after the smaller Arabic-specific stack is tested. |
+| PaddleOCR-VL-1.6 paper | https://arxiv.org/abs/2606.03264 | June 2026 research background for the current PaddleOCR-VL-1.6 document parsing upgrade. |
+| oi-OCR | https://huggingface.co/oi-uae/oi-OCR | Apache-2.0 English/Arabic PDF document parser with April 2026 ParseBench claims; keep as an external structured-document benchmark, not the Arabic-book default. |
+| Falcon-OCR | https://huggingface.co/tiiuae/Falcon-OCR | Apache-2.0 compact 300M document OCR VLM; useful watchlist candidate for strong-worker Arabic benchmarks, not default until it beats the Arabic-specific stack. |
+| Falcon Perception paper | https://arxiv.org/abs/2603.27365 | Research background for Falcon-OCR's early-fusion document OCR design and public benchmark claims. |
+| Baseer OCR model | https://huggingface.co/AbdoTarek/Baseer-OCR-V1.0 | Apache-2.0 Arabic document OCR VLM fine-tuned from Qwen2-VL-2B for complex Arabic legal documents, multi-column layouts, stamps, tables, and handwritten/printed Arabic; wired as an optional strong-worker sidecar. |
+| Baseer OCR paper | https://arxiv.org/abs/2509.18174 | Research background for Baseer as a future Arabic OCR comparison. |
+| Arabic-GLM-OCR-v2 | https://huggingface.co/sherif1313/Arabic-GLM-OCR-v2 | New Apache-2.0 Arabic OCR VLM; wired as an optional sidecar and still benchmarked on short samples before full-book use because claims need independent scoring on the actual book pages. |
+| Arabic-Qwen3.5-OCR-v4 | https://huggingface.co/sherif1313/Arabic-Qwen3.5-OCR-v4 | Recent Apache-2.0 0.9B Arabic OCR VLM for printed, handwritten, classical, and diacritic-heavy Arabic; wired as an optional sidecar and benchmarked before full-book use. |
+| aNS Qwen3-VL Arabic OCR v3 | https://huggingface.co/aNS2024/qwen3-vl-arabic-ocr-v3 | Fresh Qwen3-VL-2B Arabic OCR fine-tune; the public card shows no hosted inference provider and sparse OCR/license evidence, so keep it external until it beats QARI/KATIB/Arabic-Qwen/Baseer on the same selected Arabic pages. |
+| Waraqon v3 Arabic OCR HTML Qari | https://huggingface.co/FatimahEmadEldin/Waraqon-v3-Arabic-OCR-HTML-Qari | Apache-2.0 Qari-family Arabic OCR fine-tune for HTML/structured output; keep external until normalized readable text beats QARI/KATIB/Arabic-Qwen/Baseer on the same pages because audiobook generation needs faithful continuous Arabic text more than raw markup. |
+| DeepSeek-OCR-2 | https://huggingface.co/deepseek-ai/DeepSeek-OCR-2 | Official Apache-2.0 3B DeepSeek OCR successor with 2026 paper/model-card references and public document OCR benchmark results; keep external because it is not Arabic-specific and needs GPU/large-worker inference. |
+| DeepSeek Arabic OCR v6 | https://huggingface.co/melsiddieg/deepseek_ocr_arabic_v6 | Apache-2.0 Arabic-labeled DeepSeek-OCR fine-tune; newer than the v4/v5 Arabic fine-tunes, but keep benchmark-only because the card has sparse Arabic-book evidence and no inference provider deployment. |
+| Loay Arabic-OCR-DeepSeek-OCR-2 | https://huggingface.co/loay/Arabic-OCR-DeepSeek-OCR-2 | Apache-2.0 merged DeepSeek-OCR-2 Arabic fine-tune for high-precision OCR and structural layout analysis; keep benchmark-only until it beats QARI/KATIB/Arabic-Qwen/Baseer on the same selected Arabic book pages. |
+| Arabic-English handwritten OCR Qwen3-VL | https://huggingface.co/sherif1313/Arabic-English-handwritten-OCR-Qwen3-VL-4B | Apache-2.0 Qwen3-VL-4B handwritten Arabic/English OCR watchlist model; keep external because the card says it is research-oriented and not deployed by inference providers. |
+| Arabic-English handwritten OCR v3 | https://huggingface.co/sherif1313/Arabic-English-handwritten-OCR-v3 | Apache-2.0 Qwen2.5-VL 3B-class Arabic/English handwritten OCR watchlist model; keep external for handwriting/manuscript-heavy pages because it is large and not deployed by inference providers. |
+| Arabic handwritten OCR 4-bit Qwen2.5-VL | https://huggingface.co/sherif1313/Arabic-handwritten-OCR-4bit-Qwen2.5-VL-3B-v3 | Apache-2.0 4-bit Arabic handwritten OCR checkpoint with about 2.44GB of model assets; keep external as a lighter handwriting/manuscript benchmark when the full handwritten model is too heavy. |
+| NAKBA Arabic manuscript line OCR baseline | https://huggingface.co/U4RASD/ar-ms-baseline | NAKBA NLP 2026 Arabic manuscript understanding baseline fine-tuned from Qwen3-VL-8B for line-image transcription; keep external and line-level only until license fit and page-cropping workflow are proven. |
+| HAFITH | https://huggingface.co/mdnaseif/hafith | Apache-2.0 historical Arabic manuscript recognition model with Arabic-native tokenization and 5.10% CER claims; keep external and line-level only because the model card says it requires pre-segmented text lines. |
+| Glimpse RTL OCR | https://huggingface.co/surfiniaburger/unsloth_finetune_ocr_arabic | Apache-2.0 Arabic/Persian RTL text-line OCR model with 6.97% CER claims on unseen RTL text lines; keep external and line-level only until page-cropping workflow and same-book accuracy are proven. |
+| olmOCR Arabic LoRA v2 | https://huggingface.co/hastyle/olmOCR-arabic-lora-v2 | Apache-2.0 Arabic manuscript OCR LoRA for full-page manuscript images; keep external/heavy because it needs the 7B olmOCR base and base license/runtime confirmation. |
+| Arabic OCR Qwen2.5-VL GGUF | https://huggingface.co/mo1998/arabic-ocr-qwen2.5-vl | QariOCR-v0.3-trained Arabic/English OCR fine-tune on a Qwen2.5-VL 7B GGUF/Unsloth path; keep external with license confirmation because it is large and not inference-provider deployed. |
+| Qwen3-VL Persian/Arabic line OCR | https://huggingface.co/mohajesmaeili/Qwen3-VL-2B-Persian-Arabic-Ocr-v1.0 | Apache-2.0 Qwen3-VL 2B Persian/Arabic OCR watchlist model; keep external unless pages are cropped into text lines because the model card says it was trained on individual lines and is not designed for full-page OCR. |
+| DIMI Arabic OCR v2 | https://huggingface.co/AhmedZaky1/DIMI-Arabic-OCR-V2 | Apache-2.0 Arabic OCR LoRA fine-tuned from Qwen2.5-VL-7B; strong external benchmark candidate for printed Arabic and diacritics-heavy pages, but too heavy for the normal free worker default. |
+| Loay Arabic-OCR-Qwen2.5-VL-7B | https://huggingface.co/loay/Arabic-OCR-Qwen2.5-VL-7B-Vision | Arabic OCR VLM fine-tuned from Qwen2.5-VL-7B for Arabic text in images; keep as a high-capacity external benchmark because 7B-class runtime is too heavy for the normal free family-worker default. |
+| AtlasOCR | https://huggingface.co/atlasia/AtlasOCR | First open-source Darija/Moroccan Arabic OCR model; useful only for Darija-specific PDFs and needs license confirmation before production use. |
+| NuExtract3 | https://huggingface.co/numind/NuExtract3 | Apache-2.0 4B multilingual document understanding model for OCR, document-to-Markdown, tables, forms, invoices, contracts, and multi-page PDFs; benchmark externally for complex layouts but keep QARI/KATIB/Arabic-Qwen first for Arabic books. |
+| Qianfan-OCR | https://huggingface.co/baidu/Qianfan-OCR | Apache-2.0 5B multilingual document-intelligence OCR/VLM; benchmark externally only on large workers because it is not Arabic-book-specific and is too heavy for the default free family-worker path. |
+| Chandra OCR 2 | https://github.com/datalab-to/chandra | Recent 4B multilingual OCR/layout model supporting Arabic among 90+ languages, strong for structured Markdown/HTML/JSON extraction, tables, forms, and handwriting; code is Apache-2.0 but weights are modified OpenRAIL-M, so keep it external and benchmark-only. |
+| dots.ocr | https://huggingface.co/rednote-hilab/dots.ocr | MIT compact multilingual document parser that unifies layout detection and content recognition, with reading-order, table, and formula support; benchmark externally for difficult Arabic layouts but keep Arabic-trained OCR first for books. |
+| Arabic Large Nougat | https://huggingface.co/MohamedRashad/arabic-large-nougat | GPL-3.0 Arabic book-page OCR-to-Markdown model; useful as an external benchmark for structured Arabic book text, but keep out of the default public hosted worker because of GPL licensing and hallucination/context-length caveats. |
+| DocTR Arabic FAST/PARSEQ | https://huggingface.co/madskills/doctr-fast_base-arabic and https://huggingface.co/madskills/doctr-parseq-arabic | Apache-2.0 Arabic FAST detector paired with an Arabic PARSEQ recognizer; keep benchmark-only until recognizer licensing and same-page book accuracy are confirmed. |
+| Kraken/eScriptorium Arabic script | https://kraken.re/main/index.html and https://escriptorium.eu/about | Free/open-source ATR/OCR workflow for historical and non-Latin scripts. Benchmark externally for historical Arabic print or manuscript-like PDFs with an Arabic-script Kraken model, but keep it out of the default family-worker path because model choice, line segmentation, and per-book training can matter. |
+| Kairawan/Qalamus manuscript OCR | https://kairawan.org/ | Free 2026 Arabic and Islamic manuscript transcription service signal; useful as an external manuscript benchmark only because the reusable engine/package license, privacy/API terms, and worker integration path are not established. |
+| GLM-OCR Arabic/French documents | https://huggingface.co/maloukafer/GLM-OCR-finetuned-documents | Recent GLM-OCR LoRA fine-tune for Arabic/French administrative and scanned documents; useful for forms or newspapers, not the Arabic-book default. |
+| mimoha Arabic OCR | https://huggingface.co/mimoha/ocr | Apache-2.0 Arabic OCR card that says it extracts Arabic text from images, but the public card is sparse, so keep it low-priority and external. |
+| Raqim post-OCR correction | https://www.sciencedirect.com/science/article/pii/S187705092600058X | 2026 Arabic OCR correction research using dictionary and LLM correction; useful to track, but not wired because automatic correction can alter exact book or religious wording before TTS. |
+| Arabic Legal Documents OCR 1.0 | https://huggingface.co/bakrianoo/arabic-legal-documents-ocr-1.0 | Recent Gemma-licensed Arabic legal/scanned-document OCR VLM; benchmark externally only for legal or form-like PDFs because it is domain-specific and not permissive enough for the default family audiobook stack. |
+| Surya | https://github.com/datalab-to/surya | Heavy OCR/layout path to test only on strong workers. |
+
+## TTS Sources
+
+| Source | Link | Evidence Used |
+| --- | --- | --- |
+| SILMA TTS | https://huggingface.co/silma-ai/silma-tts | Best free permissive local Arabic voice baseline in this project: Arabic/English, Fusha/MSA, 150M parameters, Arabic normalization/tashkeel support, MIT code, Apache-2.0 model weights; current model card shows no hosted inference provider, so production quality needs the worker path and worker runtime. |
+| SILMA open source Arabic TTS models | https://silma.ai/open-source-arabic-tts-models | Official SILMA page confirming the open-source Arabic/English TTS model, Modern Standard Arabic support, 150M size, accepts text with or without tashkeel, voice cloning, and reported short-text latency. |
+| SILMA Hugging Face launch article | https://huggingface.co/blog/silma-ai/opensource-arabic-english-text-to-speech-model | Primary launch article describing SILMA TTS v1 as a 150M Arabic/English model released under Apache-2.0, with Arabic text handling, chunking, normalization, and robustness improvements. |
+| SILMA Arabic TTS benchmark | https://silma.ai/arabic-tts-benchmark | Confirms Arabic TTS quality still needs side-by-side listening because standard automatic metrics miss Arabic naturalness details. |
+| Habibi-TTS | https://github.com/SWivid/Habibi-TTS | Optional MSA voice comparison path; specialized MSA model is Apache-2.0, while unified/SAU/UAE variants are non-commercial. |
+| Habibi-TTS paper | https://arxiv.org/abs/2601.13802 | 2026 open-source Arabic TTS research source for the multi-dialect Habibi family and benchmark. |
+| Mishkala Tashkeel | https://huggingface.co/flokymind/mishkala | Apache-2.0 lightweight Arabic diacritization model; track as a pronunciation-preprocessor benchmark, not a default, because automatic tashkeel can change perceived meaning or sound distracting if wrong. |
+| Tashkeel-350M | https://huggingface.co/Etherll/Tashkeel-350M | Apache-2.0 350M Arabic diacritization model; benchmark beside Mishkala on the same cleaned TTS sample because better pronunciation must be proven by listening and meaning preservation, not assumed from model size. |
+| Mushkil | https://huggingface.co/riotu-lab/mushkil | Apache-2.0 AraT5V2 Arabic diacritization model; keep as another pronunciation-preprocessor benchmark beside Mishkala and Tashkeel-350M because automatic harakat can help pronunciation but must preserve meaning and listening comfort. |
+| Thaka KSAA-2026 speech diacritization | https://arxiv.org/abs/2605.25928 and https://www.codabench.org/competitions/11859/ | Late-May 2026 KSAA shared-task winning paper for Arabic speech/text diacritization; track as a research signal only because it describes a CATT-Whisper ensemble and benchmark result, not a simple permissive model to deploy in the PDF-to-audio worker. |
+| 3arab-TTS 500M | https://huggingface.co/sherif1313/3arab-TTS-500M-v1 | Apache-2.0 Arabic-only 500M text-to-speech model, updated in late May 2026; benchmark externally against SILMA/Habibi because it is new and not yet proven for long audiobook passages. |
+| 3arab-TTS-500M-v1-VoiceDesign | https://huggingface.co/sherif1313/3arab-TTS-500M-v1-VoiceDesign | Apache-2.0 VoiceDesign variant updated June 2026, with selectable voice styles; use the same cleaned Arabic sample for manual listening tests before app wiring. |
+| KaniTTS Arabic | https://huggingface.co/nineninesix/kani-tts-400m-ar | Arabic-only 400M TTS model with high-speed claims; Hugging Face metadata currently reports `lfm1.0` even though the page text describes Apache-style licensing, so benchmark externally and confirm license fit before app wiring. |
+| Emirati VITS Male | https://huggingface.co/vadimbelsky/emirati-vits-male-1.0 | Apache-2.0 bilingual Emirati Arabic/English VITS voice; useful for Gulf dialect comparison, but keep it benchmark-only for MSA books unless same-text listening tests beat SILMA/Habibi. |
+| VoxCPM2 | https://huggingface.co/openbmb/VoxCPM2 | Apache-2.0 multilingual TTS with Arabic among 30 supported languages, 2B parameters, and 48 kHz output; track as a strong-worker voice benchmark candidate. |
+| VoxCPM paper | https://arxiv.org/abs/2509.24650 | Research background for VoxCPM/VoxCPM2 tokenizer-free multilingual TTS and open Apache-2.0 release. |
+| Voxtral TTS | https://huggingface.co/mistralai/Voxtral-4B-TTS-2603 | Open-weight Mistral TTS model with Arabic among 9 supported languages, but the model card lists `cc-by-nc-4.0` and 4B GPU-oriented deployment, so keep it personal/non-commercial and external. |
+| Voxtral TTS paper | https://arxiv.org/abs/2603.25551 | Research background for Voxtral TTS quality and multilingual voice-cloning claims. |
+| MOSS-TTS-Nano | https://github.com/OpenMOSS/MOSS-TTS-Nano | Apache-2.0 multilingual 0.1B TTS model with Arabic support, packaged CLI, and ONNX CPU path; track as a CPU-friendly voice benchmark candidate before wiring into the app. |
+| Supertonic 3 | https://huggingface.co/Supertone/supertonic-3 | OpenRAIL model with 99M on-device TTS, Arabic support, and ONNX CPU inference; wired as an optional local benchmark voice, not the Arabic-first default. |
+| Kyutai Pocket TTS | https://kyutai.org/tts | Current official page is attractive for CPU real-time TTS, but its listed Pocket TTS languages are English, French, German, Spanish, Portuguese, and Italian, not Arabic, so it is excluded from the Arabic voice candidate list until Arabic support appears. |
+| OmniVoice | https://huggingface.co/k2-fsa/OmniVoice | Apache-2.0 0.6B zero-shot TTS with 646-language coverage, Arabic included, high current usage, and published 2026 OmniVoice evidence; benchmark as the priority permissive strong-worker voice after SILMA/Habibi. |
+| OmniVoice Arabic LoRA | https://huggingface.co/vivooglobal/omnivoice-lora-ar | Apache-2.0 Arabic LoRA adapter for OmniVoice intended to improve Arabic zero-shot voice cloning; benchmark after base OmniVoice works. |
+| Arabic-text-to-speech OmniVoice | https://huggingface.co/bilalRHCH/Arabic-text-to-speech | Apache-2.0 Arabic-labeled OmniVoice packaging with 646-language OmniVoice support and a demo Space signal; keep as a same-sample strong-worker benchmark until it proves long-form MSA audiobook quality against SILMA/Habibi. |
+| Lahgtna OmniVoice v2 | https://huggingface.co/oddadmix/lahgtna-omnivoice-v2 | New Arabic-dialect OmniVoice fine-tune with broad dialect tags and diacritics support; benchmark externally for dialectal content and confirm licensing before production wiring. |
+| TADA multilingual TTS | https://huggingface.co/HumeAI/tada-3b-ml | Free/open-weight multilingual TTS model under the Llama 3.2 license, with Arabic aligner support and text-acoustic alignment to reduce off-script speech; benchmark externally only after checking license fit because it is a 3B-class strong-worker option, not the practical default. |
+| Lahgtna Chatterbox | https://huggingface.co/oddadmix/lahgtna-chatterbox-v1 | MIT Arabic dialect TTS benchmark candidate based on Chatterbox; useful for dialectal speech tests, but the model card notes repetition can occur. |
+| NAMAA-Saudi-TTS | https://huggingface.co/NAMAA-Space/NAMAA-Saudi-TTS | MIT Saudi Arabic Chatterbox Multilingual fine-tune; benchmark only for Saudi/Gulf dialect fit because the card says it targets everyday Saudi speech rather than MSA books. |
+| NAMAA-Saudi-TTS-V2 | https://huggingface.co/NAMAA-Space/NAMAA-Saudi-TTS-V2 | Newer Najdi/Saudi Habibi/F5-TTS voice-cloning fine-tune; do not use as the free default because it is CC-BY-NC-SA-4.0, dialect-specific, reference-audio based, and not deployed by an inference provider. |
+| NAMAA-Egyptian-TTS | https://huggingface.co/NAMAA-Space/NAMAA-Egyptian-TTS | MIT Egyptian Arabic Chatterbox Multilingual fine-tune with local/hosted inference examples and live demo; benchmark only for Egyptian/dialectal text because it targets everyday Egyptian speech, not MSA books, and the card notes number/pronunciation limitations. |
+| Saudi Chatterbox fine-tune | https://huggingface.co/FatimahEmadEldin/saudi-tts-chatterbox-finetuned | Apache-2.0 Saudi Arabic Chatterbox Multilingual fine-tune; compare externally with NAMAA-Saudi-TTS and Saudi Qwen3-TTS for Gulf dialect material. |
+| Saudi TTS | https://huggingface.co/AhmedEladl/saudi-tts | Apache-2.0 high-quality Saudi Arabic dialect TTS candidate; benchmark externally with the same cleaned sample because it is dialect-specific and not a proven MSA audiobook voice. |
+| Egyptian Arabic Chatterbox | https://huggingface.co/AliAbdallah/egyptian-arabic-tts-chatterbox | Apache-2.0 Egyptian Arabic Chatterbox fine-tune with 120 hours of clean Egyptian Arabic data; benchmark only for Egyptian/dialectal text because it is single-speaker, GPU-oriented, and may not perform well on non-Egyptian Arabic. |
+| NileTTS-XTTS | https://huggingface.co/KickItLikeShika/NileTTS-XTTS | Apache-2.0 Egyptian Arabic XTTS fine-tune from the 2026 NileTTS paper; benchmark only for Egyptian/dialectal content because it is optimized for Egyptian Arabic rather than MSA books. |
+| Arabic XTTS-v2 Egyptian fine-tune | https://huggingface.co/Moeeldouma/arabic-tts-xtts-v2 | Recent Arabic XTTS-v2 improvement project with Egyptian speaker fine-tuning and documented same-text comparisons; benchmark only for dialectal content because the XTTS-v2 base uses the Coqui Public Model License and the setup is not the permissive default path. |
+| NileTTS paper | https://arxiv.org/abs/2602.15675 | Research source for the NileTTS dataset/model; reports 38 hours of Egyptian Arabic speech and open resources, making it useful as a dialect benchmark but not a general MSA default. |
+| Chatterbox-Multilingual | https://github.com/resemble-ai/chatterbox | MIT multilingual TTS/voice-cloning candidate that lists Arabic support; benchmark externally on the same cleaned Arabic sample before wiring. |
+| Chatterbox Arabic fine-tune | https://huggingface.co/juliardi/chatterbox-multilingual-finetuned-arabic | MIT Arabic-focused Chatterbox adapter claiming improved Arabic pronunciation, diacritics, MSA support, and common dialect support; benchmark on the same cleaned MSA book passage before considering app wiring. |
+| Chatterbox-Multilingual ONNX | https://huggingface.co/onnx-community/chatterbox-multilingual-ONNX | MIT ONNX packaging for Chatterbox-Multilingual with Arabic support; useful as a CPU/ONNX voice benchmark before wiring. |
+| tts-arabic-onnx | https://huggingface.co/nipponjo/tts-arabic-onnx | Arabic-only ONNX FastPitch/MixerTTS package with speaker, pace, vocoder, and vowelizer options; benchmark as a compact CPU candidate but confirm overall model/repo licensing before production. |
+| Spark-TTS Arabic | https://huggingface.co/azeddinShr/Spark-TTS-Arabic-Complete | Apache-2.0 Spark-TTS Arabic fine-tune on ClArTTS; promising for Classical/MSA tests but requires the Spark-TTS repo, reference workflow, and diacritized input. |
+| Sofelia-TTS | https://huggingface.co/hamdallah/Sofelia-TTS | Apache-2.0 Palestinian Arabic TTS/voice-cloning model; useful for dialect tests, not a default MSA audiobook voice. |
+| Arabic-F5-TTS-v2 | https://huggingface.co/IbrahimSalah/Arabic-F5-TTS-v2 | Arabic MSA voice candidate that is not a default because it is non-commercial and requires fully diacritized text. |
+| Qwen3-TTS 0.6B Base | https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-Base | Apache-2.0 TTS family, but current official released language list does not include Arabic, so do not promote for this Arabic reader yet. |
+| Qwen3-TTS 1.7B Base | https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-Base | Apache-2.0 larger base model in the same family; still not promoted by itself for Arabic because the official released language list excludes Arabic. |
+| Egyptian Arabic Qwen3-TTS | https://huggingface.co/itshamdi404/Egy_Arabic_Qwen3-TTS-12Hz-1.7B-Base | Apache-2.0 Qwen3-TTS fine-tune for Egyptian Arabic; benchmark externally only for Egyptian/dialectal content because it is 1.7B, not inference-provider deployed, and not the MSA default for books. |
+| Saudi Arabic Qwen3-TTS | https://huggingface.co/vadimbelsky/qwen3-TTS-KSA | Apache-2.0 Qwen3-TTS fine-tune for Saudi/KSA Arabic; benchmark externally for Saudi/Gulf dialect fit, not as the MSA default. |
+| Emirati Qwen3.5-TTS | https://huggingface.co/vadimbelsky/qwen3.5-TTS-Emirati | Apache-2.0 Qwen3-TTS-family fine-tune for Emirati Arabic; benchmark beside Emirati VITS Male when Gulf pronunciation matters. |
+| Qwen3-TTS technical report | https://arxiv.org/abs/2601.15621 | Confirms the Qwen3-TTS release and Apache-2.0 status, while the official model card remains the source for released language coverage. |
+| MMS Arabic TTS | https://huggingface.co/facebook/mms-tts-ara | Useful hosted fallback for testing, but non-commercial licensing keeps it out of the permissive local default. |
+
+## Hosting Sources
+
+| Source | Link | Evidence Used |
+| --- | --- | --- |
+| Vercel FastAPI deployment | https://vercel.com/docs/frameworks/backend/fastapi | Vercel website shell deployment shape. |
+| Vercel environment variables | https://vercel.com/docs/environment-variables | Required deployment configuration path. |
+| Vercel Functions limits | https://vercel.com/docs/functions/limitations/ | Python/Node functions are useful for the shell but have finite memory/duration and a 4.5 MB request/response body limit, so 100 MB+ PDFs and generated audio must bypass Vercel Functions. |
+| Vercel Blob usage and pricing | https://vercel.com/docs/vercel-blob/usage-and-pricing | Optional permanent hosted audio storage has a Hobby free allowance, but audio downloads consume storage, operation, transfer, and edge-request quota, so it is not the default free path. |
+| Hugging Face Docker Spaces | https://huggingface.co/docs/hub/main/en/spaces-sdks-docker | Free Docker worker packaging path. |
+| Hugging Face Spaces overview | https://huggingface.co/docs/hub/main/spaces-overview | CPU Basic Spaces are currently free with 2 vCPU, 16 GB RAM, and 50 GB non-persistent disk by default; good for demos/small jobs, but cold starts and ephemeral storage mean audio should be treated as short-lived. |
+| Hugging Face Hub storage limits | https://huggingface.co/docs/hub/main/storage-limits | Confirms generous public Hub storage but a bounded private free tier; useful context for not treating generated private audiobook files as unlimited archival storage. |
+
+## Practical Conclusion
+
+The current best free practical process is:
+
+1. Use PyMuPDF embedded text first.
+2. Use maximum Arabic OCR for scanned pages.
+3. Benchmark a representative 5-page sample before a full book.
+4. Keep QARI-OCR, QARI-OCR 0.4 GGUF, Tawkeed OCR, KATIB, Arabic-Qwen3.5-OCR-v4, aNS Qwen3-VL Arabic OCR v3, Waraqon v3 Arabic OCR HTML Qari, Arabic-GLM-OCR-v2, DeepSeek-OCR-2, DeepSeek Arabic OCR v6, Loay Arabic-OCR-DeepSeek-OCR-2, Arabic-English handwritten OCR Qwen3-VL, Arabic-English handwritten OCR v3, Arabic handwritten OCR 4-bit Qwen2.5-VL, NAKBA Arabic manuscript line OCR baseline, HAFITH, Glimpse RTL OCR, olmOCR Arabic LoRA v2, Arabic OCR Qwen2.5-VL GGUF, Baseer, Ketaba-OCR, Qari-OCR-LoRA, DIMI Arabic OCR v2, Loay Arabic-OCR-Qwen2.5-VL-7B, Arabic Legal Documents OCR 1.0, PaddleOCR-VL, oi-OCR, NuExtract3, Qianfan-OCR, Chandra OCR 2, dots.ocr, Arabic Large Nougat, DocTR Arabic FAST/PARSEQ, Kraken/eScriptorium Arabic script, Kairawan/Qalamus manuscript OCR, GLM-OCR Arabic/French documents, mimoha Arabic OCR, Falcon-OCR, AtlasOCR, and Surya optional for strong workers, external services, or short benchmarks.
+5. Use SILMA as the first local voice to test.
+6. Compare Mishkala, Tashkeel-350M, Mushkil, Habibi MSA, 3arab-TTS 500M, KaniTTS Arabic, Emirati VITS Male, Supertonic 3, MOSS-TTS-Nano, OmniVoice/Arabic LoRA, Arabic-text-to-speech OmniVoice, Lahgtna OmniVoice v2, Lahgtna Chatterbox, NAMAA-Saudi-TTS, NAMAA-Egyptian-TTS, Saudi Chatterbox fine-tune, Saudi TTS, Egyptian Arabic Chatterbox, NileTTS-XTTS, Arabic XTTS-v2 Egyptian fine-tune, Chatterbox-Multilingual, Chatterbox Arabic fine-tune, Chatterbox-Multilingual ONNX, tts-arabic-onnx, Spark-TTS Arabic, Sofelia-TTS, Egyptian Arabic Qwen3-TTS, Saudi Arabic Qwen3-TTS, Emirati Qwen3.5-TTS, VoxCPM2, Voxtral TTS, and eSpeak NG when pronunciation or runtime needs change; track Thaka KSAA-2026 speech diacritization as research only until code/weights are released; keep Kyutai Pocket TTS, NAMAA-Saudi-TTS-V2, Arabic-F5-TTS-v2, Arabic XTTS-v2 Egyptian fine-tune, and Voxtral TTS personal/license-review only or excluded until Arabic support/licensing is verified, and keep base Qwen3-TTS out until Arabic support is verified.
+7. Store generated audio on the worker as short-lived downloadable files by default; use Vercel Blob or object storage only when permanent hosted links are worth the free-tier quota tradeoff.
+8. Verify a deployed worker with both embedded-text and scanned-OCR smoke tests, usable extracted text, OCR-path proof, and real audio file signatures before treating the hosted system as complete.
+
+Run `python scripts\prove_local_readiness.py --refresh-research` to save a local readiness report before deployment. Run `python scripts\prove_live_deployment.py` after the hosted worker is live.

requirements-arabic-glm-ocr.txt

@@ -0,0 +1,4 @@
+accelerate==1.12.0
+Pillow==11.3.0
+torch==2.9.1
+transformers==4.57.3

requirements-arabic-qwen-ocr.txt

@@ -0,0 +1,5 @@
+accelerate==1.12.0
+Pillow==11.3.0
+torch==2.9.1
+transformers==4.57.3
+qwen-vl-utils==0.0.14

requirements-baseer-ocr.txt

@@ -0,0 +1,6 @@
+accelerate>=0.26.0
+qwen-vl-utils>=0.0.8
+torch>=2.2.0
+torchvision>=0.17.0
+transformers>=4.57.0
+Pillow>=10.0.0

requirements-katib-ocr.txt

@@ -0,0 +1,5 @@
+transformers>=4.57.0
+torch>=2.2.0
+torchvision>=0.17.0
+Pillow>=10.0.0
+accelerate>=0.26.0

requirements-paddleocr-vl.txt

@@ -0,0 +1,2 @@
+paddlepaddle>=3.2.1
+paddleocr[doc-parser]>=3.6.0

requirements-paddleocr.txt

@@ -0,0 +1,2 @@
+paddleocr==3.3.0
+paddlepaddle==3.2.2

requirements-qari-ocr.txt

@@ -0,0 +1,7 @@
+accelerate>=0.26.0
+peft>=0.10.0
+qwen-vl-utils>=0.0.8
+transformers>=4.57.0
+torch>=2.2.0
+torchvision>=0.17.0
+Pillow>=10.0.0

requirements-silma.txt

@@ -0,0 +1,33 @@
+cached_path==1.8.10
+click==8.4.1
+easyocr==1.7.2
+ema-pytorch==0.7.9
+hydra-core==1.3.2
+librosa==0.11.0
+matplotlib==3.10.9
+ninja==1.13.0
+numpy==1.26.4
+opencv-python-headless==4.9.0.80
+pillow==12.2.0
+pydub==0.25.1
+python-bidi==0.6.10
+PyYAML==6.0.3
+regex==2026.5.9
+requests==2.34.2
+safetensors==0.7.0
+scikit-image==0.25.2
+scikit-learn==1.7.2
+scipy==1.15.3
+soundfile==0.13.1
+tokenizers==0.22.2
+torch==2.12.0
+torchaudio==2.11.0
+torchcodec==0.14.0
+torchdiffeq==0.2.5
+torchvision==0.27.0
+tqdm==4.67.3
+transformers==5.10.2
+transformers-stream-generator==0.0.5
+Unidecode==1.4.0
+vocos==0.1.0
+x-transformers==2.19.12

requirements-supertonic.txt

@@ -0,0 +1 @@
+supertonic

requirements-tawkeed-ocr.txt

@@ -0,0 +1,6 @@
+accelerate>=0.26.0
+qwen-vl-utils>=0.0.8
+transformers>=4.57.0
+torch>=2.2.0
+torchvision>=0.17.0
+Pillow>=10.0.0

requirements.txt

@@ -0,0 +1,7 @@
+fastapi==0.115.6
+uvicorn[standard]==0.32.1
+python-multipart==0.0.19
+PyMuPDF==1.24.14
+pyttsx3==2.98
+pytest==8.3.4
+httpx==0.28.1

scripts/arabic_glm_ocr_extract.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+TAG_RE = re.compile(r"<[^>]+>")
+DEFAULT_ARABIC_GLM_OCR_MODEL = "sherif1313/Arabic-GLM-OCR-v2"
+
+
+def clean_model_text(text: str) -> str:
+    text = TAG_RE.sub("\n", text)
+    text = re.sub(r"```(?:html|markdown|text|json)?", "", text, flags=re.IGNORECASE)
+    text = text.replace("```", "")
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    return "\n".join(lines)
+
+
+def main() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(description="Extract Arabic text from page images with Arabic-GLM-OCR.")
+    parser.add_argument("--image-dir", required=True, type=Path)
+    parser.add_argument("--out", required=True, type=Path)
+    parser.add_argument("--model", default=DEFAULT_ARABIC_GLM_OCR_MODEL)
+    parser.add_argument("--max-new-tokens", type=int, default=2048)
+    args = parser.parse_args()
+
+    image_paths = sorted(args.image_dir.glob("*.png"))
+    total = max(len(image_paths), 1)
+    print(f"ARABIC_READER_PROGRESS 0 {total}", flush=True)
+
+    import torch
+    from PIL import Image
+    from transformers import AutoModelForImageTextToText, AutoProcessor
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    dtype = torch.float16 if device == "cuda" else torch.float32
+    processor = AutoProcessor.from_pretrained(args.model)
+    model = AutoModelForImageTextToText.from_pretrained(
+        args.model,
+        torch_dtype=dtype,
+        device_map="auto" if device == "cuda" else None,
+    )
+    if device == "cpu":
+        model.to(device)
+
+    prompt = (
+        "Extract the Arabic text exactly as it appears on this scanned page. "
+        "Preserve reading order. Do not summarize, translate, explain, or correct the text."
+    )
+    pieces: list[str] = []
+    image_paths = sorted(args.image_dir.glob("*.png"))
+    total = max(len(image_paths), 1)
+    for index, image_path in enumerate(image_paths, start=1):
+        image = Image.open(image_path).convert("RGB")
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": prompt},
+                ],
+            }
+        ]
+        text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+        inputs = processor(text=[text], images=[image], return_tensors="pt").to(model.device)
+        with torch.no_grad():
+            output = model.generate(**inputs, max_new_tokens=args.max_new_tokens, do_sample=False)
+        result = processor.decode(output[0][inputs["input_ids"].shape[1] :], skip_special_tokens=True)
+        page_text = clean_model_text(result)
+        if page_text:
+            pieces.append(page_text)
+        print(f"ARABIC_READER_PROGRESS {index} {total}", flush=True)
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text("\n\n".join(pieces), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

scripts/arabic_qwen_ocr_extract.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+TAG_RE = re.compile(r"<[^>]+>")
+DEFAULT_ARABIC_QWEN_OCR_MODEL = "sherif1313/Arabic-Qwen3.5-OCR-v4"
+
+
+def clean_model_text(text: str) -> str:
+    text = TAG_RE.sub("\n", text)
+    text = re.sub(r"```(?:html|markdown|text)?", "", text, flags=re.IGNORECASE)
+    text = text.replace("```", "")
+    text = re.sub(r"(.)\1{4,}", r"\1\1\1", text)
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    cleaned: list[str] = []
+    seen: dict[str, int] = {}
+    for line in lines:
+        seen[line] = seen.get(line, 0) + 1
+        if seen[line] <= 2:
+            cleaned.append(line)
+    return "\n".join(cleaned)
+
+
+def resize_for_qwen(image: Any) -> Any:
+    width, height = image.size
+    resized_width = ((width + 63) // 64) * 64
+    resized_height = ((height + 63) // 64) * 64
+    if (resized_width, resized_height) == (width, height):
+        return image
+
+    from PIL import Image
+
+    return image.resize((resized_width, resized_height), Image.Resampling.LANCZOS)
+
+
+def main() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(description="Extract Arabic text from page images with Arabic-Qwen3.5-OCR.")
+    parser.add_argument("--image-dir", required=True, type=Path)
+    parser.add_argument("--out", required=True, type=Path)
+    parser.add_argument("--model", default=DEFAULT_ARABIC_QWEN_OCR_MODEL)
+    parser.add_argument("--max-new-tokens", type=int, default=2048)
+    args = parser.parse_args()
+
+    image_paths = sorted(args.image_dir.glob("*.png"))
+    total = max(len(image_paths), 1)
+    print(f"ARABIC_READER_PROGRESS 0 {total}", flush=True)
+
+    import torch
+    from PIL import Image
+    from qwen_vl_utils import process_vision_info
+    from transformers import AutoProcessor, Qwen3_5ForConditionalGeneration
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    dtype = torch.float16 if device == "cuda" else torch.float32
+    processor = AutoProcessor.from_pretrained(args.model, trust_remote_code=True)
+    model = Qwen3_5ForConditionalGeneration.from_pretrained(
+        args.model,
+        torch_dtype=dtype,
+        device_map="auto" if device == "cuda" else None,
+        trust_remote_code=True,
+        low_cpu_mem_usage=True,
+    )
+    if device == "cpu":
+        model.to(device)
+    model.eval()
+
+    prompt = "اقرأ النص العربي في هذه الصورة كاملاً من البداية إلى النهاية بدون تلخيص أو ترجمة أو تصحيح."
+    pieces: list[str] = []
+    image_paths = sorted(args.image_dir.glob("*.png"))
+    total = max(len(image_paths), 1)
+    for index, image_path in enumerate(image_paths, start=1):
+        image = resize_for_qwen(Image.open(image_path).convert("RGB"))
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": prompt},
+                ],
+            }
+        ]
+        text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+        image_inputs, _ = process_vision_info(messages)
+        inputs = processor(text=[text], images=image_inputs, padding=True, return_tensors="pt").to(model.device)
+        with torch.inference_mode():
+            output = model.generate(
+                **inputs,
+                max_new_tokens=args.max_new_tokens,
+                do_sample=False,
+                repetition_penalty=1.2,
+                no_repeat_ngram_size=3,
+                pad_token_id=processor.tokenizer.pad_token_id,
+                eos_token_id=processor.tokenizer.eos_token_id,
+            )
+        input_len = inputs.input_ids.shape[1]
+        result = processor.batch_decode(
+            output[:, input_len:],
+            skip_special_tokens=True,
+            clean_up_tokenization_spaces=False,
+        )[0]
+        page_text = clean_model_text(result)
+        if page_text:
+            pieces.append(page_text)
+        print(f"ARABIC_READER_PROGRESS {index} {total}", flush=True)
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text("\n\n".join(pieces), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

scripts/audit_goal_readiness.py

@@ -0,0 +1,504 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Literal
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+Status = Literal["PASS", "WARN", "FAIL"]
+
+
+@dataclass
+class RequirementCheck:
+    requirement: str
+    status: Status
+    evidence: str
+
+
+REQUIRED_SCANNED_WORKER_CHECKS = {
+    "scanned smoke upload accepted",
+    "scanned smoke job complete",
+    "scanned smoke usable text",
+    "scanned smoke OCR extraction",
+    "scanned smoke audio url",
+    "scanned smoke download url",
+    "scanned smoke audio bytes",
+    "scanned smoke audio file signature",
+    "scanned smoke download bytes",
+    "scanned smoke download file signature",
+}
+REQUIRED_EMBEDDED_WORKER_CHECKS = {
+    "smoke upload accepted",
+    "smoke job complete",
+    "smoke usable text",
+    "smoke audio url",
+    "smoke download url",
+    "smoke audio bytes",
+    "smoke audio file signature",
+    "smoke download bytes",
+    "smoke download file signature",
+}
+REQUIRED_WORKER_HEALTH_CHECKS = {
+    "recommended stack documented",
+}
+REQUIRED_SITE_CHECKS = {
+    "site session endpoint",
+    "site login",
+    "site session authenticated",
+    "site health after login",
+    "site platform vercel",
+    "site worker configured",
+    "site large PDF ready",
+    "site production worker ready",
+    "site hosted limits documented",
+    "site recommended stack documented",
+    "site direct cloud fallback disabled",
+    "site worker diagnostics endpoint",
+    "site worker reachable from vercel",
+    "site worker CORS ready",
+}
+
+
+def read_text(root: Path, relative: str) -> str:
+    path = root / relative
+    if not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def has_all(text: str, markers: list[str]) -> bool:
+    return all(marker in text for marker in markers)
+
+
+def add(checks: list[RequirementCheck], requirement: str, status: Status, evidence: str) -> None:
+    checks.append(RequirementCheck(requirement, status, evidence))
+
+
+def verify_worker_report(path: Path | None) -> tuple[bool, str]:
+    if path is None:
+        return False, "no worker verification report provided"
+    if not path.exists():
+        return False, f"worker verification report not found: {path}"
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        return False, f"worker verification report is not valid JSON: {exc}"
+    if not isinstance(payload, list):
+        return False, "worker verification report must be a JSON list from scripts/verify_worker.py --json"
+
+    checks_by_name: dict[str, bool] = {}
+    failing: list[str] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name", ""))
+        ok = bool(item.get("ok"))
+        checks_by_name[name] = ok
+        if not ok:
+            failing.append(name or "<unnamed>")
+
+    required_worker_checks = REQUIRED_WORKER_HEALTH_CHECKS | REQUIRED_EMBEDDED_WORKER_CHECKS | REQUIRED_SCANNED_WORKER_CHECKS
+    missing = sorted(name for name in required_worker_checks if name not in checks_by_name)
+    not_ok = sorted(name for name in required_worker_checks if checks_by_name.get(name) is False)
+    if missing:
+        return False, f"worker report is missing smoke checks: {', '.join(missing)}"
+    if not_ok:
+        return False, f"worker smoke checks failed: {', '.join(not_ok)}"
+    if failing:
+        return False, f"worker report contains failed checks: {', '.join(failing)}"
+    return True, f"worker verification report passed recommended-stack, embedded, and scanned OCR/audio/download checks: {path}"
+
+
+def verify_site_report(path: Path | None) -> tuple[bool, str]:
+    if path is None:
+        return False, "no Vercel site verification report provided"
+    if not path.exists():
+        return False, f"Vercel site verification report not found: {path}"
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        return False, f"Vercel site verification report is not valid JSON: {exc}"
+    if not isinstance(payload, list):
+        return False, "Vercel site verification report must be a JSON list from scripts/verify_site.py --json"
+
+    checks_by_name: dict[str, bool] = {}
+    failing: list[str] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name", ""))
+        ok = bool(item.get("ok"))
+        checks_by_name[name] = ok
+        if not ok:
+            failing.append(name or "<unnamed>")
+
+    missing = sorted(name for name in REQUIRED_SITE_CHECKS if name not in checks_by_name)
+    not_ok = sorted(name for name in REQUIRED_SITE_CHECKS if checks_by_name.get(name) is False)
+    if missing:
+        return False, f"Vercel site report is missing checks: {', '.join(missing)}"
+    if not_ok:
+        return False, f"Vercel site checks failed: {', '.join(not_ok)}"
+    if failing:
+        return False, f"Vercel site report contains failed checks: {', '.join(failing)}"
+    return True, f"Vercel site verification report passed login/worker-routing checks: {path}"
+
+
+def collect_checks(
+    root: Path = ROOT_DIR,
+    live_worker_verified: bool = False,
+    worker_report: Path | None = None,
+    site_report: Path | None = None,
+) -> list[RequirementCheck]:
+    checks: list[RequirementCheck] = []
+    report_verified, report_evidence = verify_worker_report(worker_report)
+    site_verified, site_evidence = verify_site_report(site_report)
+    app = read_text(root, "app/main.py")
+    frontend = read_text(root, "static/app.js") + "\n" + read_text(root, "static/index.html")
+    readme = read_text(root, "README.md")
+    research = read_text(root, "docs/best-free-arabic-pdf-audio-stack.md")
+    source_evidence = read_text(root, "docs/source-evidence.md")
+    recommendation = read_text(root, "docs/recommended-free-stack.md")
+    hf_metadata = read_text(root, "docs/huggingface-model-metadata.md")
+    user_guide = read_text(root, "docs/father-user-guide.md")
+    production = read_text(root, "docs/production-worker-architecture.md")
+    deployment_checklist = read_text(root, "docs/live-deployment-checklist.md")
+    dockerfile = read_text(root, "Dockerfile.worker")
+    verify_worker = read_text(root, "scripts/verify_worker.py")
+    prove_local = read_text(root, "scripts/prove_local_readiness.py")
+    deployment_handoff = read_text(root, "scripts/deployment_handoff.py")
+    deployment_env_validator = read_text(root, "scripts/validate_deployment_env.py")
+    research_checker = read_text(root, "scripts/check_research_sources.py")
+    research_watchlist = read_text(root, "scripts/research_watchlist.py")
+    benchmark = read_text(root, "scripts/benchmark_ocr.py")
+    voices = read_text(root, "scripts/benchmark_voices.py")
+    voice_scorer = read_text(root, "scripts/score_voice_listening.py")
+    promotion_gate = read_text(root, "scripts/model_promotion_gate.py")
+    tts_sample_exporter = read_text(root, "scripts/export_tts_sample.py")
+    ocr_sample_exporter = read_text(root, "scripts/export_ocr_sample_images.py")
+    external_ocr_scorer = read_text(root, "scripts/score_external_ocr.py")
+
+    add(
+        checks,
+        "Code-locked access with persistent signed cookie",
+        "PASS" if has_all(app, ["ACCESS_CODE", "SECRET_KEY", "hmac.new", "set_cookie", "arabic_tts_auth"]) else "FAIL",
+        "app/main.py contains access-code login, HMAC signing, and cookie storage",
+    )
+    add(
+        checks,
+        "Large Arabic PDF upload path",
+        "PASS" if has_all(app, ['DEFAULT_MAX_UPLOAD_MB = "4" if IS_VERCEL else "512"', "MAX_UPLOAD_BYTES", "WORKER_BASE_URL"]) else "FAIL",
+        "local/worker default is 512 MB; Vercel shell can delegate to WORKER_BASE_URL",
+    )
+    add(
+        checks,
+        "Free Arabic OCR engine stack",
+        "PASS"
+        if has_all(
+            app,
+            [
+                "OCR_ENGINE_CHOICES",
+                "arabic",
+                "arabic-max",
+                "qari-ocr",
+                "tawkeed-ocr",
+                "katib-ocr",
+                "arabic-qwen-ocr",
+                "arabic-glm-ocr",
+                "paddleocr",
+                "easyocr",
+                "tesseract",
+                "paddleocr-vl",
+            ],
+        )
+        and (root / "requirements-paddleocr.txt").exists()
+        and (root / "requirements-paddleocr-vl.txt").exists()
+        and (root / "requirements-qari-ocr.txt").exists()
+        and (root / "requirements-tawkeed-ocr.txt").exists()
+        and (root / "requirements-katib-ocr.txt").exists()
+        and (root / "requirements-arabic-qwen-ocr.txt").exists()
+        and (root / "requirements-arabic-glm-ocr.txt").exists()
+        else "FAIL",
+        "Maximum Arabic OCR plus optional QARI-OCR, Tawkeed, KATIB, Arabic-Qwen, Arabic-GLM, Baseer, EasyOCR, PaddleOCR, Tesseract, and optional PaddleOCR-VL",
+    )
+    add(
+        checks,
+        "OCR quality gate before speech",
+        "PASS" if has_all(app, ["assess_text_quality", "prepare_text_for_speech", "OCR text quality is poor"]) else "FAIL",
+        "bad OCR is rejected before TTS; speech cleanup is centralized",
+    )
+    add(
+        checks,
+        "Free Arabic TTS options",
+        "PASS"
+        if has_all(app, ["silma-local", "habibi-msa", "supertonic-ar", "espeak-ar-clear"])
+        and has_all(voices, ["DEFAULT_VOICES", "RECOMMENDED_VOICE_ORDER", "choose_recommended_voice"])
+        else "FAIL",
+        "SILMA default, optional Habibi MSA, optional Supertonic CPU voice, eSpeak NG fallback, and quality-first voice recommendation are available",
+    )
+    add(
+        checks,
+        "Downloadable generated audio with local storage",
+        "PASS" if has_all(app, ["download_audio", "FileResponse", "sqlite3", "cleanup_output_storage", "AUDIO_FORMAT"]) else "FAIL",
+        "SQLite metadata, retained output files, audio streaming, and download endpoint",
+    )
+    add(
+        checks,
+        "Father-friendly workflow controls",
+        "PASS"
+        if has_all(frontend, ["voiceSelect", "pageLimitSelect", "ocrModeSelect", "downloadLink", "Use settings"])
+        and has_all(user_guide, ["Normal Use", "Quick test", "Download Audio"])
+        else "FAIL",
+        "voice, OCR, speed/page controls, download link, recent-job reuse controls, and a non-technical user guide exist",
+    )
+    add(
+        checks,
+        "Vercel plus worker deployment shape",
+        "PASS"
+        if has_all(
+            readme + production + deployment_checklist + dockerfile,
+            ["WORKER_BASE_URL", "Docker", "OCR_ENGINE=arabic-max", "AUDIO_FORMAT=mp3", "worker-verification.json"],
+        )
+        and has_all(deployment_handoff, ["WORKER_BASE_URL", "prove_live_deployment.py", "worker-verification.json"])
+        and has_all(
+            deployment_env_validator,
+            ["WORKER_BASE_URL", "ENABLE_DIRECT_CLOUD_TTS", "CORS_ORIGINS", "SECRET_KEY matches"],
+        )
+        else "FAIL",
+        "Vercel shell plus Docker worker is documented, packaged, tied to a verification report, has env validation, and has a handoff generator",
+    )
+    add(
+        checks,
+        "Live worker smoke verification command",
+        "PASS"
+        if has_all(
+            verify_worker,
+            [
+                "--smoke-upload",
+                "--smoke-scanned",
+                "create_scanned_smoke_pdf",
+                "looks_like_audio",
+                "job_has_usable_text",
+                "scanned smoke OCR extraction",
+            ],
+        )
+        else "FAIL",
+        "verify_worker.py can prove embedded-text and scanned-OCR text/audio/download paths with audio file signatures",
+    )
+    add(
+        checks,
+        "Book-specific OCR/voice benchmarking process",
+        "PASS"
+        if has_all(
+            benchmark
+            + voices
+            + voice_scorer
+            + prove_local
+            + tts_sample_exporter
+            + ocr_sample_exporter
+            + external_ocr_scorer
+            + promotion_gate
+            + readme,
+            [
+                "recommendation_for_extraction",
+                "benchmark_ocr.py",
+                "benchmark_voices.py",
+                "score_voice_listening",
+                "Arabic Voice Listening Score",
+                "export_tts_sample",
+                "arabic-tts-sample.txt",
+                "export_ocr_sample_images",
+                "External Arabic OCR Sample",
+                "oi-OCR",
+                "score_external_ocr",
+                "External Arabic OCR Score Report",
+                "model_promotion_gate",
+                "Model Promotion Gate",
+                "same-sample proof",
+                "OmniVoice",
+                "OmniVoice Arabic LoRA",
+                "Lahgtna Chatterbox",
+                "NAMAA-Saudi-TTS",
+                "Chatterbox-Multilingual",
+                "Chatterbox-Multilingual ONNX",
+                "tts-arabic-onnx",
+                "Supertonic 3",
+                "Spark-TTS Arabic",
+                "Sofelia-TTS",
+                "Baseer",
+                "Arabic-GLM-OCR-v2",
+                "Arabic-Qwen3.5-OCR-v4",
+                "recommended",
+                "local-readiness.json",
+            ],
+        )
+        else "FAIL",
+        "benchmark tools recommend OCR settings, export and score external OCR samples, compare voices, export external TTS samples, gate model promotion, and can write a local readiness report before full-book runs",
+    )
+    add(
+        checks,
+        "Current free/up-to-date research notes",
+        "PASS"
+        if has_all(
+            research,
+            [
+                "Last checked: June 7, 2026",
+                "QARI-OCR 0.4",
+                "Qari-OCR-0.4.0-VL-4B-Instruct",
+                "PaddleOCR-VL-1.6",
+                "oi-OCR",
+                "Arabic OCR Qwen2.5-VL GGUF",
+                "Arabic-Qwen3.5-OCR-v4",
+                "Baseer OCR",
+                "OmniVoice Arabic LoRA",
+                "Lahgtna Chatterbox",
+                "NAMAA-Saudi-TTS",
+                "Chatterbox-Multilingual",
+                "Chatterbox-Multilingual ONNX",
+                "tts-arabic-onnx",
+                "Supertonic 3",
+                "Spark-TTS Arabic",
+                "Sofelia-TTS",
+                "SILMA TTS",
+                "Supertone/supertonic-3",
+                "silma-ai/silma-tts",
+                "Apache-2.0 model weights",
+                "Habibi-TTS paper",
+                "Source Links",
+            ],
+        )
+        and has_all(
+            source_evidence,
+            [
+                "Source Evidence",
+                "QARI-OCR 0.4 model",
+                "oi-OCR",
+                "Arabic OCR Qwen2.5-VL GGUF",
+                "SILMA Arabic TTS benchmark",
+                "NAMAA-Saudi-TTS",
+                "huggingface-model-metadata.md",
+                "Habibi-TTS paper",
+                "MMS Arabic TTS",
+                "Hosting Sources",
+                "Vercel Functions limits",
+                "4.5 MB request/response body limit",
+                "2 vCPU",
+                "16 GB RAM",
+                "50 GB non-persistent disk",
+                "Practical Conclusion",
+            ],
+        )
+        and has_all(
+            recommendation,
+            [
+                "Recommended Free Arabic PDF To Audio Stack",
+                "PyMuPDF text extraction first",
+                "`OCR_ENGINE=arabic-max`",
+                "SILMA TTS",
+                "4.5 MB function payload limit",
+                "50 GB but non-persistent",
+                "Benchmark Before Promoting",
+                "PyMuPDF -> `arabic-max` OCR -> SILMA TTS",
+            ],
+        )
+        and has_all(
+            hf_metadata,
+            [
+                "Last refreshed:",
+                "NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct",
+                "silma-ai/silma-tts",
+                "sherif1313/Arabic-Qwen3.5-OCR-v4",
+                "sherif1313/Arabic-GLM-OCR-v2",
+                "NAMAA-Space/NAMAA-Saudi-TTS",
+                "apache-2.0",
+                "cc-by-nc-4.0",
+                "fair-noncommercial-research-license",
+                "openrail",
+            ],
+        )
+        and has_all(
+            research_checker,
+            ["REQUIRED_SOURCE_MARKERS", "KEY_SOURCE_URLS", "check_url", "--check-key-links", "--check-links", "metadata_freshness_check"],
+        )
+        and has_all(research_watchlist, ["license_policy_violations", "is_production_default_safe", "BENCHMARK_ONLY_LICENSE_MARKERS"])
+        else "FAIL",
+        "research docs record current free OCR/TTS recommendation, external OCR benchmark candidates, source evidence, and source-check command",
+    )
+    add(
+        checks,
+        "Live deployed worker verified",
+        "PASS" if live_worker_verified or report_verified else "WARN",
+        report_evidence
+        if worker_report
+        else "provide --worker-report after running verify_worker.py --json --smoke-upload --smoke-scanned --smoke-ocr-engine arabic-max against the deployed worker",
+    )
+    add(
+        checks,
+        "Live Vercel shell verified",
+        "PASS" if site_verified else "WARN",
+        site_evidence
+        if site_report
+        else "provide --site-report after running verify_site.py --json against the deployed Vercel site",
+    )
+    return checks
+
+
+def summarize(checks: list[RequirementCheck]) -> dict[str, object]:
+    counts = {"PASS": 0, "WARN": 0, "FAIL": 0}
+    for check in checks:
+        counts[check.status] += 1
+    return {
+        "ready": counts["FAIL"] == 0,
+        "complete": counts["FAIL"] == 0 and counts["WARN"] == 0,
+        "counts": counts,
+        "checks": [asdict(check) for check in checks],
+    }
+
+
+def print_table(checks: list[RequirementCheck]) -> None:
+    summary = summarize(checks)
+    print("Arabic PDF-to-clean-audio goal audit")
+    print(
+        f"Ready: {'yes' if summary['ready'] else 'no'}  "
+        f"Complete: {'yes' if summary['complete'] else 'no'}  "
+        f"PASS={summary['counts']['PASS']} WARN={summary['counts']['WARN']} FAIL={summary['counts']['FAIL']}"
+    )
+    print()
+    for check in checks:
+        print(f"[{check.status:<4}] {check.requirement}")
+        print(f"       {check.evidence}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Audit the repo against the Arabic PDF-to-clean-audio project goal.")
+    parser.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    parser.add_argument(
+        "--live-worker-verified",
+        action="store_true",
+        help="Manual override after verify_worker.py --smoke-upload --smoke-scanned --smoke-ocr-engine arabic-max succeeds. Prefer --worker-report for stronger evidence.",
+    )
+    parser.add_argument(
+        "--worker-report",
+        type=Path,
+        help="JSON output from scripts/verify_worker.py --json --smoke-upload --smoke-scanned --smoke-ocr-engine arabic-max against the deployed worker.",
+    )
+    parser.add_argument(
+        "--site-report",
+        type=Path,
+        help="JSON output from scripts/verify_site.py --json against the deployed Vercel site.",
+    )
+    args = parser.parse_args()
+
+    checks = collect_checks(live_worker_verified=args.live_worker_verified, worker_report=args.worker_report, site_report=args.site_report)
+    if args.json:
+        print(json.dumps(summarize(checks), ensure_ascii=False, indent=2))
+    else:
+        print_table(checks)
+    if any(check.status == "FAIL" for check in checks):
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/baseer_ocr_extract.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+TAG_RE = re.compile(r"<[^>]+>")
+DEFAULT_BASEER_OCR_MODEL = "AbdoTarek/Baseer-OCR-V1.0"
+
+
+def clean_model_text(text: str) -> str:
+    text = TAG_RE.sub("\n", text)
+    text = re.sub(r"```(?:json|html|markdown|text)?", "", text, flags=re.IGNORECASE)
+    text = text.replace("```", "").strip()
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        payload = None
+    if isinstance(payload, dict):
+        full_text = payload.get("full_text") or payload.get("text") or payload.get("content")
+        if isinstance(full_text, str):
+            text = full_text
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    return "\n".join(lines)
+
+
+def main() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(description="Extract Arabic text from page images with Baseer OCR.")
+    parser.add_argument("--image-dir", required=True, type=Path)
+    parser.add_argument("--out", required=True, type=Path)
+    parser.add_argument("--model", default=DEFAULT_BASEER_OCR_MODEL)
+    parser.add_argument("--max-new-tokens", type=int, default=2048)
+    args = parser.parse_args()
+
+    image_paths = sorted(args.image_dir.glob("*.png"))
+    total = max(len(image_paths), 1)
+    print(f"ARABIC_READER_PROGRESS 0 {total}", flush=True)
+
+    import torch
+    from PIL import Image
+    from qwen_vl_utils import process_vision_info
+    from transformers import AutoProcessor, Qwen2VLForConditionalGeneration
+
+    model = Qwen2VLForConditionalGeneration.from_pretrained(
+        args.model,
+        torch_dtype="auto",
+        device_map="auto",
+    ).eval()
+    processor = AutoProcessor.from_pretrained(args.model)
+    prompt = (
+        "Extract ALL visible Arabic text from the document image. "
+        "Return only JSON with a full_text field. Preserve the original reading order. "
+        "Do not summarize, translate, or add explanations."
+    )
+    pieces: list[str] = []
+    image_paths = sorted(args.image_dir.glob("*.png"))
+    total = max(len(image_paths), 1)
+    for index, image_path in enumerate(image_paths, start=1):
+        image = Image.open(image_path).convert("RGB")
+        messages = [
+            {"role": "system", "content": [{"type": "text", "text": "You are an OCR assistant."}]},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": prompt},
+                ],
+            },
+        ]
+        text = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
+        image_inputs, video_inputs = process_vision_info(messages)
+        inputs = processor(
+            text=[text],
+            images=image_inputs,
+            videos=video_inputs,
+            padding=True,
+            return_tensors="pt",
+        ).to(model.device)
+        with torch.inference_mode():
+            output_ids = model.generate(**inputs, max_new_tokens=args.max_new_tokens, do_sample=False)
+        result = processor.batch_decode(
+            output_ids[:, inputs.input_ids.shape[1] :],
+            skip_special_tokens=True,
+        )[0]
+        page_text = clean_model_text(result)
+        if page_text:
+            pieces.append(page_text)
+        print(f"ARABIC_READER_PROGRESS {index} {total}", flush=True)
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text("\n\n".join(pieces), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmark_ocr.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+import fitz
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from app import main
+
+
+EXTRACTION_RE = re.compile(r"^(?:(?P<mode>best|arabic|arabic-max):)?(?P<engine>[a-z-]+)(?:@(?P<zoom>[0-9.]+)x)?(?:-psm(?P<psm>\d+))?$")
+
+
+def make_limited_pdf(pdf_path: Path, page_limit: int | None) -> Path:
+    if not page_limit:
+        return pdf_path
+    limited = Path(tempfile.gettempdir()) / f"{pdf_path.stem}-first-{page_limit}-pages.pdf"
+    with fitz.open(pdf_path) as document:
+        output = fitz.open()
+        output.insert_pdf(document, from_page=0, to_page=min(page_limit, document.page_count) - 1)
+        output.save(limited)
+    return limited
+
+
+def text_metrics(text: str) -> dict[str, Any]:
+    speech_text = main.prepare_text_for_speech(text)
+    arabic_words = main.ARABIC_RE.findall(speech_text)
+    placeholder_count = speech_text.count("?") + speech_text.count("\ufffd")
+    common_hits = sum(1 for word in arabic_words if word in main.COMMON_ARABIC_WORDS)
+    quality = main.assess_text_quality(text, speech_text)
+    return {
+        "characters": len(text),
+        "speechCharacters": len(speech_text),
+        "arabicWords": len(arabic_words),
+        "placeholderCharacters": placeholder_count,
+        "placeholderRatio": round(placeholder_count / max(len(speech_text), 1), 4),
+        "commonArabicWords": common_hits,
+        "commonArabicWordRatio": round(common_hits / max(len(arabic_words), 1), 4),
+        "singleArabicWords": int(quality["metrics"]["singleArabicWords"]),
+        "singleArabicWordRatio": quality["metrics"]["singleArabicWordRatio"],
+        "fragmentLines": int(quality["metrics"]["fragmentLines"]),
+        "fragmentLineRatio": quality["metrics"]["fragmentLineRatio"],
+        "quality": quality["quality"],
+        "qualityScore": quality["score"],
+        "qualityReasons": quality["reasons"],
+        "preview": text[:180],
+        "speechPreview": speech_text[:180],
+    }
+
+
+def recommendation_for_extraction(extraction: str | None) -> dict[str, Any] | None:
+    if not extraction:
+        return None
+    match = EXTRACTION_RE.match(extraction)
+    if not match:
+        return None
+
+    engine = match.group("engine")
+    zoom = match.group("zoom")
+    psm = match.group("psm")
+    env: dict[str, str] = {}
+    notes: list[str] = []
+
+    if engine == "embedded":
+        return {
+            "summary": "This PDF has readable embedded text; OCR settings are not needed.",
+            "env": {},
+            "notes": ["Use the normal upload flow."],
+        }
+
+    mode = match.group("mode")
+    if mode in {"arabic", "arabic-max"}:
+        env["OCR_ENGINE"] = mode
+        if mode == "arabic-max":
+            notes.append("Use Maximum Arabic OCR for the full run only if the worker can handle the heavier OCR comparison.")
+        else:
+            notes.append("Use Arabic specialist OCR for the full run; it compares Arabic-trained OCR outputs.")
+        return {
+            "summary": f"For the full book, use OCR_ENGINE={mode}.",
+            "env": env,
+            "notes": notes,
+        }
+
+    if engine not in {
+        "easyocr",
+        "qari-ocr",
+        "tawkeed-ocr",
+        "katib-ocr",
+        "arabic-qwen-ocr",
+        "arabic-glm-ocr",
+        "baseer-ocr",
+        "paddleocr",
+        "paddleocr-vl",
+        "surya",
+        "tesseract",
+    }:
+        return None
+
+    env["OCR_ENGINE"] = engine
+    if zoom:
+        if engine == "easyocr":
+            env["EASYOCR_RENDER_ZOOM"] = zoom
+        elif engine == "qari-ocr":
+            env["QARI_OCR_RENDER_ZOOM"] = zoom
+        elif engine == "tawkeed-ocr":
+            env["TAWKEED_OCR_RENDER_ZOOM"] = zoom
+        elif engine == "katib-ocr":
+            env["KATIB_OCR_RENDER_ZOOM"] = zoom
+        elif engine == "arabic-qwen-ocr":
+            env["ARABIC_QWEN_OCR_RENDER_ZOOM"] = zoom
+        elif engine == "arabic-glm-ocr":
+            env["ARABIC_GLM_OCR_RENDER_ZOOM"] = zoom
+        elif engine == "baseer-ocr":
+            env["BASEER_OCR_RENDER_ZOOM"] = zoom
+        elif engine == "paddleocr":
+            env["PADDLEOCR_RENDER_ZOOM"] = zoom
+        elif engine == "paddleocr-vl":
+            env["PADDLEOCR_VL_RENDER_ZOOM"] = zoom
+        elif engine == "surya":
+            env["SURYA_RENDER_ZOOM"] = zoom
+        elif engine == "tesseract":
+            env["OCR_RENDER_ZOOM"] = zoom
+    if psm and engine == "tesseract":
+        env["TESSERACT_PSM"] = psm
+    if engine == "tesseract":
+        notes.append("Confirm Tesseract Arabic data is installed before the full run.")
+    elif engine == "easyocr":
+        notes.append("Use the EasyOCR/SILMA sidecar environment for the full run.")
+    elif engine == "qari-ocr":
+        notes.append("Use the QARI-OCR Arabic VLM sidecar on a GPU or strong worker; expect much higher RAM/runtime.")
+    elif engine == "tawkeed-ocr":
+        notes.append("Use the Tawkeed Arabic OCR sidecar when QARI 4B is too heavy; benchmark it on a short sample first.")
+    elif engine == "katib-ocr":
+        notes.append("Use the KATIB Arabic OCR sidecar for a smaller Arabic-trained VLM; benchmark it on a short sample first.")
+    elif engine == "arabic-qwen-ocr":
+        notes.append("Use the Arabic-Qwen3.5 OCR sidecar for a 0.9B Arabic-trained VLM; benchmark it on a short sample first.")
+    elif engine == "arabic-glm-ocr":
+        notes.append("Use the Arabic-GLM OCR sidecar for a recent Arabic-trained OCR VLM; benchmark it on a short sample first.")
+    elif engine == "baseer-ocr":
+        notes.append("Use the Baseer Arabic OCR sidecar for complex Arabic document layouts; benchmark it on a short sample first.")
+    elif engine == "paddleocr":
+        notes.append("Use the PaddleOCR sidecar environment for the full run.")
+    elif engine == "paddleocr-vl":
+        notes.append("Use the PaddleOCR-VL sidecar on a strong worker; expect much higher RAM/runtime than PaddleOCR.")
+    elif engine == "surya":
+        notes.append("Use the Surya heavy-worker sidecar; expect higher RAM/runtime than PaddleOCR.")
+
+    env_text = " ".join(f"{key}={value}" for key, value in env.items())
+    return {
+        "summary": f"For the full book, use {env_text}.",
+        "env": env,
+        "notes": notes,
+    }
+
+
+def benchmark_engine(pdf_path: Path, engine: str) -> dict[str, Any]:
+    previous_engine = main.OCR_ENGINE
+    main.OCR_ENGINE = engine
+    job = main.Job(id="dry-run", filename=pdf_path.name, ocr_engine=engine)
+    started = time.perf_counter()
+    try:
+        text = main.extract_pdf_text(pdf_path, job)
+        elapsed = round(time.perf_counter() - started, 2)
+        result = {
+            "engine": engine,
+            "ok": True,
+            "seconds": elapsed,
+            "pages": job.pages,
+            "extraction": job.extraction,
+            **text_metrics(text),
+        }
+        result["recommendation"] = recommendation_for_extraction(job.extraction)
+        return result
+    except Exception as exc:
+        elapsed = round(time.perf_counter() - started, 2)
+        return {
+            "engine": engine,
+            "ok": False,
+            "seconds": elapsed,
+            "pages": job.pages,
+            "error": str(exc),
+        }
+    finally:
+        main.OCR_ENGINE = previous_engine
+
+
+def print_table(results: list[dict[str, Any]]) -> None:
+    print("engine         ok    sec    pages  chars   words   quality  score    extraction")
+    print("-------------  ----  -----  -----  ------  ------  -------  -------  ----------")
+    for item in results:
+        print(
+            f"{item['engine']:<13}  "
+            f"{str(item['ok']):<4}  "
+            f"{item['seconds']:>5}  "
+            f"{item.get('pages', 0):>5}  "
+            f"{item.get('characters', 0):>6}  "
+            f"{item.get('arabicWords', 0):>6}  "
+            f"{item.get('quality', '-'):>7}  "
+            f"{item.get('qualityScore', 0):>7}  "
+            f"{item.get('extraction', '-')}"
+        )
+    successful = [item for item in results if item.get("ok")]
+    if successful:
+        best = max(successful, key=lambda item: (item.get("qualityScore", 0), item.get("arabicWords", 0)))
+        recommendation = best.get("recommendation")
+        if recommendation:
+            print()
+            print(f"Best full-book setting from this sample: {recommendation['summary']}")
+
+
+def main_cli() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(description="Benchmark Arabic OCR engines on the same PDF.")
+    parser.add_argument("pdf", type=Path, help="Arabic PDF to benchmark")
+    parser.add_argument(
+        "--engines",
+        nargs="+",
+        default=["easyocr", "paddleocr", "tesseract"],
+        choices=[
+            "arabic",
+            "arabic-max",
+            "qari-ocr",
+            "tawkeed-ocr",
+            "katib-ocr",
+            "arabic-qwen-ocr",
+            "arabic-glm-ocr",
+            "baseer-ocr",
+            "easyocr",
+            "paddleocr",
+            "paddleocr-vl",
+            "surya",
+            "tesseract",
+            "auto",
+            "best",
+        ],
+    )
+    parser.add_argument("--page-limit", type=int, default=1, help="Benchmark only the first N pages by default.")
+    parser.add_argument("--json", action="store_true", help="Print full JSON results instead of a compact table.")
+    args = parser.parse_args()
+
+    if not args.pdf.exists():
+        raise FileNotFoundError(f"PDF not found: {args.pdf}")
+    if args.page_limit is not None and args.page_limit < 1:
+        raise ValueError("--page-limit must be 1 or greater.")
+
+    benchmark_pdf = make_limited_pdf(args.pdf, args.page_limit)
+    try:
+        results = [benchmark_engine(benchmark_pdf, engine) for engine in args.engines]
+    finally:
+        if benchmark_pdf != args.pdf:
+            benchmark_pdf.unlink(missing_ok=True)
+
+    if args.json:
+        print(json.dumps(results, ensure_ascii=False, indent=2))
+    else:
+        print_table(results)
+        print()
+        print("Tip: use --json to inspect text previews and errors.")
+
+
+if __name__ == "__main__":
+    main_cli()

scripts/benchmark_voices.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from app import main
+from scripts.verify_voice import DEFAULT_SAMPLE_TEXT, synthesize_voice
+
+
+DEFAULT_VOICES = ["silma-local", "habibi-msa", "supertonic-ar", "espeak-ar-clear"]
+RECOMMENDED_VOICE_ORDER = ["silma-local", "habibi-msa", "supertonic-ar", "espeak-ar-clear", "espeak-ar", "espeak-ar-male"]
+
+
+def available_voice_ids() -> list[str]:
+    return list(main.LOCAL_VOICES)
+
+
+def benchmark_voice(
+    voice_id: str,
+    text: str,
+    output_dir: Path,
+    audio_format: str = "wav",
+) -> dict[str, Any]:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    destination = output_dir / f"{voice_id}.{audio_format}"
+    try:
+        result = synthesize_voice(text, voice_id, destination, audio_format)
+        return {"ok": True, **result}
+    except Exception as exc:
+        return {
+            "ok": False,
+            "voiceId": voice_id,
+            "label": main.get_local_voice(voice_id).get("label", voice_id),
+            "engine": main.get_local_voice(voice_id).get("engine", ""),
+            "error": str(exc),
+        }
+
+
+def benchmark_voices(
+    voices: list[str] | None = None,
+    text: str = DEFAULT_SAMPLE_TEXT,
+    output_dir: Path | None = None,
+    audio_format: str = "wav",
+) -> dict[str, Any]:
+    selected_voices = voices or DEFAULT_VOICES
+    output = output_dir or (ROOT_DIR / "outputs" / "voice-benchmark")
+    results = [benchmark_voice(voice_id, text, output, audio_format) for voice_id in selected_voices]
+    successful = [item for item in results if item.get("ok")]
+    fastest = min(successful, key=lambda item: item.get("elapsedSeconds", float("inf"))) if successful else None
+    recommended = choose_recommended_voice(successful)
+    return {
+        "voices": selected_voices,
+        "textCharacters": len(main.prepare_text_for_speech(text)),
+        "outputDir": str(output),
+        "audioFormat": audio_format,
+        "results": results,
+        "fastest": fastest,
+        "recommended": recommended,
+        "ready": bool(successful),
+        "nextSteps": build_next_steps(results),
+    }
+
+
+def choose_recommended_voice(successful: list[dict[str, Any]]) -> dict[str, Any] | None:
+    if not successful:
+        return None
+    by_voice_id = {str(item.get("voiceId")): item for item in successful}
+    for voice_id in RECOMMENDED_VOICE_ORDER:
+        if voice_id in by_voice_id:
+            return by_voice_id[voice_id]
+    return min(successful, key=lambda item: item.get("elapsedSeconds", float("inf")))
+
+
+def build_next_steps(results: list[dict[str, Any]]) -> list[str]:
+    steps: list[str] = []
+    successful = [item for item in results if item.get("ok")]
+    failed = [item for item in results if not item.get("ok")]
+    if successful:
+        recommended = choose_recommended_voice(successful)
+        if recommended:
+            steps.append(
+                f"Recommended starting voice: {recommended.get('voiceId')} ({recommended.get('label')}). "
+                "Listen before processing a full book."
+            )
+        steps.append("Listen to the generated files and choose the most natural Arabic voice before processing a full book.")
+        fastest = min(successful, key=lambda item: item.get("elapsedSeconds", float("inf")))
+        steps.append(f"Fastest successful voice in this run: {fastest.get('voiceId')} ({fastest.get('elapsedSeconds')}s).")
+    else:
+        steps.append("No tested voice produced audio. Run scripts/preflight_check.py and install SILMA, Habibi, Supertonic, or eSpeak NG.")
+    if any(item.get("voiceId") == "habibi-msa" and not item.get("ok") for item in failed):
+        steps.append("Habibi MSA is optional. Install it with scripts/setup_habibi.ps1 if you want to compare the newer MSA voice.")
+    if any(item.get("voiceId") == "silma-local" and not item.get("ok") for item in failed):
+        steps.append("SILMA is the preferred default voice. Install it with scripts/setup_silma.ps1 for the best current local baseline.")
+    if any(item.get("voiceId") == "supertonic-ar" and not item.get("ok") for item in failed):
+        steps.append("Supertonic 3 is optional. Install it with scripts/setup_supertonic.ps1 when you want a fast CPU Arabic-capable comparison voice.")
+    return steps
+
+
+def write_markdown_report(path: Path, result: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    rating_command = build_rating_command(result)
+    lines = [
+        "# Arabic Voice Benchmark",
+        "",
+        f"Output directory: `{result.get('outputDir', '')}`",
+        f"Text characters: {result.get('textCharacters', 0)}",
+        f"Audio format: {result.get('audioFormat', 'wav')}",
+    ]
+    recommended = result.get("recommended")
+    fastest = result.get("fastest")
+    if recommended:
+        lines.append(f"Recommended starting voice: `{recommended.get('voiceId')}` ({recommended.get('label', '-')})")
+    if fastest:
+        lines.append(f"Fastest successful voice: `{fastest.get('voiceId')}` ({fastest.get('elapsedSeconds')}s)")
+    lines.extend(
+        [
+            "",
+            "## Results",
+            "",
+            "| Voice | Label | Engine | Status | Time | Audio | Notes |",
+            "| --- | --- | --- | --- | ---: | --- | --- |",
+        ]
+    )
+    for item in result.get("results", []):
+        status = "ok" if item.get("ok") else "failed"
+        elapsed = item.get("elapsedSeconds", "-")
+        audio = item.get("path", "-")
+        notes = item.get("error", "")
+        lines.append(
+            f"| {item.get('voiceId', '-')} | {item.get('label', '-')} | {item.get('engine', '-')} | "
+            f"{status} | {elapsed} | {audio} | {notes} |"
+        )
+    lines.extend(["", "## Next Steps", ""])
+    for step in result.get("nextSteps", []):
+        lines.append(f"- {step}")
+    lines.extend(
+        [
+            "",
+            "## Listening Score",
+            "",
+            "After listening, score each successful voice from 1 to 5 for pronunciation, naturalness, pacing, long-listen comfort, and artifact-free audio.",
+            "",
+            "```powershell",
+            rating_command,
+            "```",
+        ]
+    )
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def build_rating_command(result: dict[str, Any]) -> str:
+    ratings = []
+    for item in result.get("results", []):
+        if item.get("ok"):
+            ratings.append(f"--rating {item.get('voiceId')}=5,5,5,5,5")
+    if not ratings:
+        ratings.append("--rating silma-local=5,5,5,5,5")
+    return (
+        "python scripts\\score_voice_listening.py "
+        + " ".join(ratings)
+        + " --write-report outputs\\voice-listening-score.md"
+    )
+
+
+def print_table(result: dict[str, Any]) -> None:
+    print("voice             ok    sec    engine      file")
+    print("----------------  ----  -----  ----------  ----")
+    for item in result["results"]:
+        print(
+            f"{item.get('voiceId', '-'):<16}  "
+            f"{str(item.get('ok')):<4}  "
+            f"{item.get('elapsedSeconds', '-'):>5}  "
+            f"{item.get('engine', '-'):<10}  "
+            f"{item.get('path', item.get('error', '-'))}"
+        )
+    print()
+    for step in result["nextSteps"]:
+        print(f"- {step}")
+
+
+def main_cli() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    parser = argparse.ArgumentParser(description="Compare free local Arabic TTS voices on the same text.")
+    parser.add_argument("--voices", nargs="+", default=DEFAULT_VOICES, choices=available_voice_ids())
+    parser.add_argument("--text", default=DEFAULT_SAMPLE_TEXT, help="Arabic text to synthesize for every voice.")
+    parser.add_argument("--text-file", type=Path, help="Read benchmark text from a UTF-8 file.")
+    parser.add_argument("--out-dir", type=Path, default=ROOT_DIR / "outputs" / "voice-benchmark")
+    parser.add_argument("--format", choices=["wav", "mp3"], default="wav")
+    parser.add_argument("--write-report", type=Path, help="Write a Markdown benchmark report.")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of a compact table.")
+    args = parser.parse_args()
+
+    text = args.text_file.read_text(encoding="utf-8") if args.text_file else args.text
+    result = benchmark_voices(args.voices, text, args.out_dir, args.format)
+    if args.write_report:
+        write_markdown_report(args.write_report, result)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print_table(result)
+
+
+if __name__ == "__main__":
+    main_cli()

scripts/check_deployment_readiness.py

@@ -0,0 +1,689 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+Status = Literal["PASS", "WARN", "FAIL"]
+EXPORT_MANIFEST_NAME = ".export-manifest.json"
+
+
+@dataclass
+class Check:
+    category: str
+    name: str
+    status: Status
+    detail: str
+
+
+def add(checks: list[Check], category: str, name: str, status: Status, detail: str) -> None:
+    checks.append(Check(category, name, status, detail))
+
+
+def load_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def dockerfile_copy_sources(dockerfile: str) -> list[str]:
+    sources: list[str] = []
+    for line in dockerfile.splitlines():
+        line = line.strip()
+        if not line.startswith("COPY "):
+            continue
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        sources.extend(parts[1:-1])
+    return sources
+
+
+def referenced_scripts(dockerfile: str) -> set[str]:
+    return set(re.findall(r"scripts/[A-Za-z0-9_.-]+\.sh", dockerfile))
+
+
+def file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def should_manifest_copy(path: Path) -> bool:
+    if path.name in {"__pycache__", ".pytest_cache", ".ruff_cache"}:
+        return False
+    if path.suffix in {".pyc", ".pyo", ".pyd"}:
+        return False
+    return True
+
+
+def expected_export_manifest(root: Path | None = None) -> dict[str, str]:
+    root = root or ROOT_DIR
+    files: dict[str, str] = {}
+    for relative in [
+        "requirements.txt",
+        "requirements-silma.txt",
+        "requirements-supertonic.txt",
+        "requirements-paddleocr.txt",
+        "requirements-paddleocr-vl.txt",
+        "requirements-qari-ocr.txt",
+        "requirements-tawkeed-ocr.txt",
+        "requirements-katib-ocr.txt",
+        "requirements-arabic-qwen-ocr.txt",
+        "requirements-arabic-glm-ocr.txt",
+        "requirements-baseer-ocr.txt",
+    ]:
+        path = root / relative
+        if path.exists():
+            files[relative] = file_sha256(path)
+    dockerfile = root / "Dockerfile.worker"
+    if dockerfile.exists():
+        files["Dockerfile"] = file_sha256(dockerfile)
+    for relative in ["app", "api", "docs", "static", "scripts"]:
+        base = root / relative
+        if not base.exists():
+            continue
+        for path in sorted(base.rglob("*")):
+            if path.is_file() and should_manifest_copy(path):
+                files[path.relative_to(root).as_posix()] = file_sha256(path)
+    return files
+
+
+def check_required_files(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    required = [
+        "app/main.py",
+        "api/index.py",
+        "static/index.html",
+        "static/app.js",
+        "static/styles.css",
+        "requirements.txt",
+        "vercel.json",
+        "Dockerfile.worker",
+        "requirements-silma.txt",
+        "requirements-supertonic.txt",
+        "requirements-paddleocr.txt",
+        "requirements-paddleocr-vl.txt",
+        "requirements-qari-ocr.txt",
+        "requirements-tawkeed-ocr.txt",
+        "requirements-katib-ocr.txt",
+        "requirements-arabic-qwen-ocr.txt",
+        "requirements-arabic-glm-ocr.txt",
+        "requirements-baseer-ocr.txt",
+        "scripts/setup_silma.sh",
+        "scripts/setup_supertonic.sh",
+        "scripts/setup_paddleocr.sh",
+        "scripts/setup_paddleocr_vl.sh",
+        "scripts/setup_qari_ocr.sh",
+        "scripts/setup_tawkeed_ocr.sh",
+        "scripts/setup_katib_ocr.sh",
+        "scripts/setup_arabic_qwen_ocr.sh",
+        "scripts/setup_arabic_glm_ocr.sh",
+        "scripts/setup_baseer_ocr.sh",
+        "scripts/qari_ocr_extract.py",
+        "scripts/tawkeed_ocr_extract.py",
+        "scripts/katib_ocr_extract.py",
+        "scripts/arabic_qwen_ocr_extract.py",
+        "scripts/arabic_glm_ocr_extract.py",
+        "scripts/baseer_ocr_extract.py",
+        "scripts/audit_goal_readiness.py",
+        "scripts/prove_local_readiness.py",
+        "scripts/prove_live_deployment.py",
+        "scripts/configure_vercel_worker.py",
+        "scripts/finish_live_deployment.py",
+        "scripts/deployment_handoff.py",
+        "scripts/prepare_live_deployment.py",
+        "scripts/validate_deployment_env.py",
+        "scripts/hosted_preflight.py",
+        "scripts/verify_site.py",
+        "scripts/verify_worker.py",
+        "scripts/preflight_check.py",
+        "scripts/check_research_sources.py",
+        "scripts/research_watchlist.py",
+        "scripts/refresh_research_evidence.py",
+        "scripts/export_tts_sample.py",
+        "scripts/export_ocr_sample_images.py",
+        "scripts/score_voice_listening.py",
+        "scripts/score_tts_preprocessor.py",
+        "scripts/score_external_ocr.py",
+        "scripts/model_promotion_gate.py",
+        "scripts/next_deployment_step.py",
+        "scripts/deployment_status.py",
+        "scripts/check_test_environment.py",
+        "docs/live-deployment-checklist.md",
+        "docs/father-user-guide.md",
+        "docs/source-evidence.md",
+        "docs/huggingface-model-metadata.md",
+        "docs/research-watchlist.md",
+        "docs/recommended-free-stack.md",
+        "docs/recommended-decision-card.md",
+        "docs/recommended-decision-card.json",
+    ]
+    for relative in required:
+        path = root / relative
+        add(checks, "Files", relative, "PASS" if path.exists() else "FAIL", "exists" if path.exists() else "missing")
+    return checks
+
+
+def check_vercel(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    config_path = root / "vercel.json"
+    config = load_json(config_path)
+    add(checks, "Vercel", "config readable", "PASS" if config else "FAIL", str(config_path))
+    if not config:
+        return checks
+    has_builds = "builds" in config
+    has_functions = "functions" in config
+    add(
+        checks,
+        "Vercel",
+        "functions/builds conflict",
+        "FAIL" if has_builds and has_functions else "PASS",
+        "do not use builds and functions together" if has_builds and has_functions else "ok",
+    )
+    rewrites = config.get("rewrites") or []
+    rewrite_ok = any(item.get("destination") == "/api/index.py" for item in rewrites if isinstance(item, dict))
+    add(checks, "Vercel", "FastAPI rewrite", "PASS" if rewrite_ok else "FAIL", json.dumps(rewrites))
+    functions = config.get("functions") or {}
+    api_function = functions.get("api/index.py", {})
+    max_duration = api_function.get("maxDuration", 0)
+    add(
+        checks,
+        "Vercel",
+        "function maxDuration",
+        "PASS" if isinstance(max_duration, int) and max_duration >= 60 else "WARN",
+        str(max_duration),
+    )
+    return checks
+
+
+def check_worker(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    dockerfile_path = root / "Dockerfile.worker"
+    if not dockerfile_path.exists():
+        add(checks, "Worker", "Dockerfile.worker", "FAIL", "missing")
+        return checks
+    dockerfile = dockerfile_path.read_text(encoding="utf-8")
+    add(checks, "Worker", "base image", "PASS" if "python:3.10" in dockerfile else "WARN", "Python 3.10 is expected")
+    for package in ["tesseract-ocr-ara", "espeak-ng", "ffmpeg"]:
+        add(checks, "Worker", f"apt package {package}", "PASS" if package in dockerfile else "FAIL", package)
+    for env_key in ["WORK_DIR", "DATABASE_PATH", "OCR_ENGINE=arabic-max", "AUDIO_FORMAT=mp3"]:
+        add(checks, "Worker", f"env {env_key}", "PASS" if env_key in dockerfile else "WARN", env_key)
+    for arg in [
+        "ARG INSTALL_QARI_OCR=0",
+        "ARG INSTALL_TAWKEED_OCR=0",
+        "ARG INSTALL_KATIB_OCR=0",
+        "ARG INSTALL_ARABIC_QWEN_OCR=0",
+        "ARG INSTALL_ARABIC_GLM_OCR=0",
+        "ARG INSTALL_BASEER_OCR=0",
+        "ARG INSTALL_PADDLEOCR_VL=0",
+        "ARG INSTALL_SUPERTONIC=0",
+    ]:
+        add(
+            checks,
+            "Worker",
+            f"optional build {arg.split()[1]}",
+            "PASS" if arg in dockerfile else "WARN",
+            "lets stronger workers install heavy OCR sidecars",
+        )
+    optional_scripts = {
+        "scripts/setup_supertonic.sh": "SUPERTONIC",
+        "scripts/setup_qari_ocr.sh": "QARI_OCR",
+        "scripts/setup_tawkeed_ocr.sh": "TAWKEED_OCR",
+        "scripts/setup_katib_ocr.sh": "KATIB_OCR",
+        "scripts/setup_arabic_qwen_ocr.sh": "ARABIC_QWEN_OCR",
+        "scripts/setup_arabic_glm_ocr.sh": "ARABIC_GLM_OCR",
+        "scripts/setup_baseer_ocr.sh": "BASEER_OCR",
+        "scripts/setup_paddleocr_vl.sh": "PADDLEOCR_VL",
+    }
+    for optional_script, build_arg_name in optional_scripts.items():
+        conditional_marker = f"if [ \"$INSTALL_{build_arg_name}\" = \"1\" ]"
+        add(
+            checks,
+            "Worker",
+            f"conditional {optional_script}",
+            "PASS" if optional_script in dockerfile and conditional_marker in dockerfile else "WARN",
+            "optional heavy OCR install is controlled by build arg",
+        )
+    for source in dockerfile_copy_sources(dockerfile):
+        source_path = root / source
+        add(
+            checks,
+            "Worker",
+            f"COPY source {source}",
+            "PASS" if source_path.exists() else "FAIL",
+            "exists" if source_path.exists() else "missing",
+        )
+    for script in sorted(referenced_scripts(dockerfile)):
+        script_path = root / script
+        add(checks, "Worker", f"referenced {script}", "PASS" if script_path.exists() else "FAIL", "exists" if script_path.exists() else "missing")
+    return checks
+
+
+def check_ignore_files(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    gitignore = (root / ".gitignore").read_text(encoding="utf-8") if (root / ".gitignore").exists() else ""
+    dockerignore = (root / ".dockerignore").read_text(encoding="utf-8") if (root / ".dockerignore").exists() else ""
+    vercelignore = (root / ".vercelignore").read_text(encoding="utf-8") if (root / ".vercelignore").exists() else ""
+    for name, content in [(".gitignore", gitignore), (".dockerignore", dockerignore), (".vercelignore", vercelignore)]:
+        add(checks, "Ignore", name, "PASS" if content else "WARN", "present" if content else "missing")
+        add(checks, "Ignore", f"{name} excludes .env", "PASS" if ".env" in content else "WARN", "secrets should not deploy")
+        add(
+            checks,
+            "Ignore",
+            f"{name} excludes outputs",
+            "PASS" if any(line.strip().rstrip("/") == "outputs" for line in content.splitlines()) else "WARN",
+            "generated handoffs/audio should not deploy or commit",
+        )
+    for required in ["app", "api", "static", "requirements.txt"]:
+        excluded = any(line.strip() == required for line in vercelignore.splitlines())
+        add(checks, "Ignore", f"Vercel keeps {required}", "FAIL" if excluded else "PASS", "not excluded" if not excluded else "excluded")
+    return checks
+
+
+def check_deployment_handoff(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    path = root / "scripts" / "deployment_handoff.py"
+    text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
+    markers = {
+        "deployment prep command": "prepare_live_deployment.py",
+        "Vercel CLI production deploy": "vercel --prod --yes",
+        "Vercel worker env command": "vercel env add WORKER_BASE_URL production",
+        "Hugging Face deploy helper": "deploy_hf_space.py",
+        "Hugging Face Space bundle path": "outputs/huggingface-space",
+        "deployment status command": "deployment_status.py --worker-url",
+        "Vercel worker diagnostic command": "hosted_preflight.py",
+        "Vercel worker CORS diagnostic": "site worker CORS ready",
+        "live proof command": "prove_live_deployment.py",
+        "worker verification report": "worker-verification.json",
+        "copy paste secret block": "Copy/paste secret values",
+        "copy paste build args": "Copy/paste balanced build args",
+        "copy paste Vercel env": "Copy/paste Vercel values",
+        "Vercel direct cloud fallback cleanup": "vercel env rm ENABLE_DIRECT_CLOUD_TTS production --yes",
+        "Vercel Hugging Face token cleanup": "vercel env rm HF_API_TOKEN production --yes",
+        "Vercel Hugging Face model cleanup": "vercel env rm HF_TTS_MODEL production --yes",
+        "Vercel default voice cleanup": "vercel env rm DEFAULT_VOICE_ID production --yes",
+    }
+    for name, marker in markers.items():
+        add(
+            checks,
+            "Handoff",
+            name,
+            "PASS" if marker in text else "FAIL",
+            marker if marker in text else f"missing marker: {marker}",
+        )
+    return checks
+
+
+def check_deployment_quickstart(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    path = root / "outputs" / "deployment-quickstart.md"
+    if not path.exists():
+        add(checks, "Quickstart", "deployment quickstart", "WARN", "run scripts/prepare_live_deployment.py")
+        return checks
+    text = path.read_text(encoding="utf-8", errors="replace")
+    markers = {
+        "Hugging Face new Space link": "https://huggingface.co/new-space",
+        "Hugging Face Docker docs link": "https://huggingface.co/docs/hub/main/en/spaces-sdks-docker",
+        "Vercel new project link": "https://vercel.com/new",
+        "Vercel FastAPI docs link": "https://vercel.com/docs/frameworks/backend/fastapi",
+        "handoff command": "deployment_handoff.py",
+        "hosted preflight command": "hosted_preflight.py",
+        "hosted preflight report": "hosted-preflight.json",
+        "worker CORS ready reminder": "site worker CORS ready",
+        "worker bundle path": "outputs\\huggingface-space",
+        "final proof warning": "live-deployment-proof.json",
+        "safety checklist": "Safety Checklist",
+        "shared secret reminder": "same generated `SECRET_KEY`",
+        "worker URL reminder": "`WORKER_BASE_URL` at the exact Hugging Face Space URL",
+        "direct cloud fallback disabled": "direct Hugging Face TTS disabled",
+        "temporary cloud variable cleanup": "ENABLE_DIRECT_CLOUD_TTS",
+        "current next command": "Current Next Command",
+    }
+    for name, marker in markers.items():
+        add(
+            checks,
+            "Quickstart",
+            name,
+            "PASS" if marker in text else "FAIL",
+            marker if marker in text else f"missing marker: {marker}",
+        )
+    return checks
+
+
+def check_env_validator(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    path = root / "scripts" / "validate_deployment_env.py"
+    text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
+    markers = {
+        "validator rejects Vercel as worker URL": "WORKER_BASE_URL is not Vercel site",
+        "validator prefers Hugging Face Space worker": "WORKER_BASE_URL uses free worker host",
+        "validator rejects wildcard CORS": "CORS_ORIGINS has no wildcard",
+        "validator rejects non-Vercel CORS origins": "CORS_ORIGINS are Vercel origins",
+    }
+    for name, marker in markers.items():
+        add(
+            checks,
+            "Env validator",
+            name,
+            "PASS" if marker in text else "FAIL",
+            marker if marker in text else f"missing marker: {marker}",
+        )
+    return checks
+
+
+def check_app_contract(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    app_path = root / "app" / "main.py"
+    static_path = root / "static" / "app.js"
+    verify_site_path = root / "scripts" / "verify_site.py"
+    audit_path = root / "scripts" / "audit_goal_readiness.py"
+    app_text = app_path.read_text(encoding="utf-8", errors="replace") if app_path.exists() else ""
+    static_text = static_path.read_text(encoding="utf-8", errors="replace") if static_path.exists() else ""
+    verify_text = verify_site_path.read_text(encoding="utf-8", errors="replace") if verify_site_path.exists() else ""
+    audit_text = audit_path.read_text(encoding="utf-8", errors="replace") if audit_path.exists() else ""
+    markers = {
+        "health exposes productionReady": (app_text, '"productionReady"'),
+        "health exposes nextAction": (app_text, '"nextAction"'),
+        "health blocks direct cloud fallback readiness": (app_text, "not direct_cloud_fallback"),
+        "ui shows deployment next action": (static_text, "deploymentStatus.nextAction"),
+        "ui warns when productionReady false": (static_text, "deploymentStatus.productionReady === false"),
+        "site verifier checks productionReady": (verify_text, "site production worker ready"),
+        "site verifier checks worker diagnostics": (verify_text, "site worker reachable from vercel"),
+        "site verifier checks worker CORS": (verify_text, "site worker CORS ready"),
+        "goal audit requires productionReady proof": (audit_text, "site production worker ready"),
+        "goal audit requires worker diagnostics proof": (audit_text, "site worker reachable from vercel"),
+        "goal audit requires worker CORS proof": (audit_text, "site worker CORS ready"),
+    }
+    for name, (text, marker) in markers.items():
+        add(
+            checks,
+            "App contract",
+            name,
+            "PASS" if marker in text else "FAIL",
+            marker if marker in text else f"missing marker: {marker}",
+        )
+    return checks
+
+
+def check_hf_space_export(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    export_dir = root / "outputs" / "huggingface-space"
+    if not export_dir.exists():
+        add(checks, "HF Space", "export bundle", "WARN", "run scripts/export_hf_space.py --force")
+        return checks
+    required = [
+        "Dockerfile",
+        "README.md",
+        ".dockerignore",
+        EXPORT_MANIFEST_NAME,
+        "requirements.txt",
+        "requirements-silma.txt",
+        "requirements-supertonic.txt",
+        "requirements-paddleocr.txt",
+        "requirements-paddleocr-vl.txt",
+        "requirements-qari-ocr.txt",
+        "requirements-tawkeed-ocr.txt",
+        "requirements-katib-ocr.txt",
+        "requirements-arabic-qwen-ocr.txt",
+        "requirements-arabic-glm-ocr.txt",
+        "requirements-baseer-ocr.txt",
+        ".export-complete",
+        "app/main.py",
+        "api/index.py",
+        "static/index.html",
+        "scripts/setup_silma.sh",
+        "scripts/setup_supertonic.sh",
+        "scripts/setup_paddleocr.sh",
+        "scripts/setup_paddleocr_vl.sh",
+        "scripts/setup_qari_ocr.sh",
+        "scripts/setup_tawkeed_ocr.sh",
+        "scripts/setup_katib_ocr.sh",
+        "scripts/setup_arabic_qwen_ocr.sh",
+        "scripts/setup_arabic_glm_ocr.sh",
+        "scripts/setup_baseer_ocr.sh",
+        "scripts/qari_ocr_extract.py",
+        "scripts/tawkeed_ocr_extract.py",
+        "scripts/katib_ocr_extract.py",
+        "scripts/arabic_qwen_ocr_extract.py",
+        "scripts/arabic_glm_ocr_extract.py",
+        "scripts/baseer_ocr_extract.py",
+        "scripts/audit_goal_readiness.py",
+        "scripts/prove_local_readiness.py",
+        "scripts/prove_live_deployment.py",
+        "scripts/deployment_handoff.py",
+        "scripts/prepare_live_deployment.py",
+        "scripts/validate_deployment_env.py",
+        "scripts/verify_site.py",
+        "scripts/check_research_sources.py",
+        "scripts/research_watchlist.py",
+        "scripts/refresh_research_evidence.py",
+        "scripts/export_tts_sample.py",
+        "scripts/export_ocr_sample_images.py",
+        "scripts/score_voice_listening.py",
+        "scripts/score_tts_preprocessor.py",
+        "scripts/score_external_ocr.py",
+        "scripts/model_promotion_gate.py",
+        "scripts/next_deployment_step.py",
+        "scripts/deployment_status.py",
+        "docs/live-deployment-checklist.md",
+        "docs/father-user-guide.md",
+        "docs/source-evidence.md",
+        "docs/huggingface-model-metadata.md",
+        "docs/research-watchlist.md",
+        "docs/recommended-free-stack.md",
+        "docs/recommended-decision-card.md",
+        "docs/recommended-decision-card.json",
+    ]
+    forbidden = [".env", "uploads", "outputs", "data", "test_pdfs", ".venv", ".venv-silma", ".venv-ocr"]
+    for relative in required:
+        path = export_dir / relative
+        add(checks, "HF Space", f"bundle has {relative}", "PASS" if path.exists() else "FAIL", "exists" if path.exists() else "missing")
+    manifest_path = export_dir / EXPORT_MANIFEST_NAME
+    manifest = load_json(manifest_path)
+    manifest_files = manifest.get("files") if isinstance(manifest, dict) else None
+    expected_manifest = expected_export_manifest(root)
+    if isinstance(manifest_files, dict):
+        missing_manifest = sorted(path for path in expected_manifest if path not in manifest_files)
+        changed_manifest = sorted(
+            path for path, digest in expected_manifest.items() if manifest_files.get(path) != digest
+        )
+        extra_manifest = sorted(path for path in manifest_files if path not in expected_manifest)
+        stale_detail = (
+            f"missing={len(missing_manifest)} changed={len(changed_manifest)} extra={len(extra_manifest)}"
+        )
+        add(
+            checks,
+            "HF Space",
+            "bundle manifest matches source",
+            "PASS" if not missing_manifest and not changed_manifest else "FAIL",
+            stale_detail,
+        )
+    else:
+        add(checks, "HF Space", "bundle manifest matches source", "FAIL", "missing or invalid manifest")
+    app_text = (export_dir / "app" / "main.py").read_text(encoding="utf-8", errors="replace") if (export_dir / "app" / "main.py").exists() else ""
+    static_text = (
+        (export_dir / "static" / "app.js").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "static" / "app.js").exists()
+        else ""
+    )
+    verify_site_text = (
+        (export_dir / "scripts" / "verify_site.py").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "scripts" / "verify_site.py").exists()
+        else ""
+    )
+    qari_text = (
+        (export_dir / "scripts" / "qari_ocr_extract.py").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "scripts" / "qari_ocr_extract.py").exists()
+        else ""
+    )
+    qari_default = "Qari-OCR-0.4.0-VL-4B-Instruct"
+    tawkeed_text = (
+        (export_dir / "scripts" / "tawkeed_ocr_extract.py").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "scripts" / "tawkeed_ocr_extract.py").exists()
+        else ""
+    )
+    tawkeed_default = "tawkeed-sa/tawkeed-ocr"
+    katib_text = (
+        (export_dir / "scripts" / "katib_ocr_extract.py").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "scripts" / "katib_ocr_extract.py").exists()
+        else ""
+    )
+    katib_default = "Katib-Qwen3.5-0.8B-0.1"
+    arabic_qwen_text = (
+        (export_dir / "scripts" / "arabic_qwen_ocr_extract.py").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "scripts" / "arabic_qwen_ocr_extract.py").exists()
+        else ""
+    )
+    arabic_qwen_requirements = (
+        (export_dir / "requirements-arabic-qwen-ocr.txt").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "requirements-arabic-qwen-ocr.txt").exists()
+        else ""
+    )
+    arabic_qwen_default = "Arabic-Qwen3.5-OCR-v4"
+    arabic_glm_text = (
+        (export_dir / "scripts" / "arabic_glm_ocr_extract.py").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "scripts" / "arabic_glm_ocr_extract.py").exists()
+        else ""
+    )
+    arabic_glm_default = "Arabic-GLM-OCR-v2"
+    baseer_text = (
+        (export_dir / "scripts" / "baseer_ocr_extract.py").read_text(encoding="utf-8", errors="replace")
+        if (export_dir / "scripts" / "baseer_ocr_extract.py").exists()
+        else ""
+    )
+    baseer_default = "Baseer-OCR-V1.0"
+    add(
+        checks,
+        "HF Space",
+        "bundle uses QARI-OCR 0.4 default",
+        "PASS" if qari_default in app_text and qari_default in qari_text else "FAIL",
+        qari_default,
+    )
+    add(
+        checks,
+        "HF Space",
+        "bundle uses Tawkeed Arabic OCR default",
+        "PASS" if tawkeed_default in app_text and tawkeed_default in tawkeed_text else "FAIL",
+        tawkeed_default,
+    )
+    add(
+        checks,
+        "HF Space",
+        "bundle uses KATIB Arabic OCR default",
+        "PASS" if katib_default in app_text and katib_default in katib_text else "FAIL",
+        katib_default,
+    )
+    add(
+        checks,
+        "HF Space",
+        "bundle uses Arabic-Qwen3.5 OCR default",
+        "PASS" if arabic_qwen_default in app_text and arabic_qwen_default in arabic_qwen_text else "FAIL",
+        arabic_qwen_default,
+    )
+    add(
+        checks,
+        "HF Space",
+        "bundle has Arabic-Qwen3.5 model-specific runner",
+        "PASS"
+        if all(
+            marker in arabic_qwen_text
+            for marker in ["Qwen3_5ForConditionalGeneration", "process_vision_info", "trust_remote_code=True"]
+        )
+        and "qwen-vl-utils" in arabic_qwen_requirements
+        else "FAIL",
+        "Qwen3_5 loader plus qwen-vl-utils",
+    )
+    add(
+        checks,
+        "HF Space",
+        "bundle uses Arabic-GLM OCR default",
+        "PASS" if arabic_glm_default in app_text and arabic_glm_default in arabic_glm_text else "FAIL",
+        arabic_glm_default,
+    )
+    add(
+        checks,
+        "HF Space",
+        "bundle uses Baseer OCR default",
+        "PASS" if baseer_default in app_text and baseer_default in baseer_text else "FAIL",
+        baseer_default,
+    )
+    bundle_contract_markers = {
+        "bundle health exposes productionReady": (app_text, '"productionReady"'),
+        "bundle health exposes nextAction": (app_text, '"nextAction"'),
+        "bundle health rejects direct cloud fallback readiness": (app_text, "not direct_cloud_fallback"),
+        "bundle UI shows deployment next action": (static_text, "deploymentStatus.nextAction"),
+        "bundle UI warns when productionReady false": (static_text, "deploymentStatus.productionReady === false"),
+        "bundle verifier checks productionReady": (verify_site_text, "site production worker ready"),
+        "bundle verifier checks worker diagnostics": (verify_site_text, "site worker reachable from vercel"),
+        "bundle verifier checks worker CORS": (verify_site_text, "site worker CORS ready"),
+    }
+    for name, (text, marker) in bundle_contract_markers.items():
+        add(
+            checks,
+            "HF Space",
+            name,
+            "PASS" if marker in text else "FAIL",
+            marker if marker in text else f"missing marker: {marker}",
+        )
+    for relative in forbidden:
+        path = export_dir / relative
+        add(checks, "HF Space", f"bundle excludes {relative}", "PASS" if not path.exists() else "FAIL", "excluded" if not path.exists() else "present")
+    return checks
+
+
+def collect_checks(root: Path = ROOT_DIR) -> list[Check]:
+    checks: list[Check] = []
+    checks.extend(check_required_files(root))
+    checks.extend(check_vercel(root))
+    checks.extend(check_worker(root))
+    checks.extend(check_ignore_files(root))
+    checks.extend(check_deployment_handoff(root))
+    checks.extend(check_deployment_quickstart(root))
+    checks.extend(check_env_validator(root))
+    checks.extend(check_app_contract(root))
+    checks.extend(check_hf_space_export(root))
+    return checks
+
+
+def summarize(checks: list[Check]) -> dict[str, object]:
+    counts = {"PASS": 0, "WARN": 0, "FAIL": 0}
+    for check in checks:
+        counts[check.status] += 1
+    return {
+        "ready": counts["FAIL"] == 0,
+        "counts": counts,
+        "checks": [check.__dict__ for check in checks],
+    }
+
+
+def print_table(checks: list[Check]) -> None:
+    for check in checks:
+        print(f"{check.status:<4}  {check.category:<8}  {check.name:<36}  {check.detail}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Check Vercel and Docker worker deployment files before deploying.")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of a compact table.")
+    args = parser.parse_args()
+
+    checks = collect_checks()
+    if args.json:
+        print(json.dumps(summarize(checks), indent=2))
+    else:
+        print_table(checks)
+    if any(check.status == "FAIL" for check in checks):
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/check_research_sources.py

@@ -0,0 +1,1213 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+from dataclasses import asdict, dataclass
+from datetime import date, datetime
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_DOCS = [
+    ROOT_DIR / "docs" / "best-free-arabic-pdf-audio-stack.md",
+    ROOT_DIR / "docs" / "source-evidence.md",
+    ROOT_DIR / "docs" / "huggingface-model-metadata.md",
+    ROOT_DIR / "docs" / "live-deployment-checklist.md",
+    ROOT_DIR / "docs" / "production-worker-architecture.md",
+    ROOT_DIR / "docs" / "research-watchlist.md",
+    ROOT_DIR / "docs" / "recommended-free-stack.md",
+    ROOT_DIR / "docs" / "recommended-decision-card.md",
+    ROOT_DIR / "docs" / "recommended-decision-card.json",
+]
+
+
+def load_env_file(path: Path) -> None:
+    if not path.exists():
+        return
+    for raw_line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+load_env_file(ROOT_DIR / ".env")
+URL_RE = re.compile(r"https?://[^\s)\]>`]+")
+REQUIRED_SOURCE_MARKERS = [
+    "QARI-OCR",
+    "QARI-OCR 0.4",
+    "Qari-OCR-0.4.0-VL-4B-Instruct",
+    "no hosted inference provider",
+    "worker runtime",
+    "QARI-OCR 0.4 GGUF",
+    "marwan-osama/Qari-OCR-0.4.0-VL-4B-Instruct-GGUF",
+    "KATIB 0.8B",
+    "Katib-Qwen3.5-0.8B-0.1",
+    "Ketaba-OCR LoRA",
+    "HassanB4/Ketaba-OCR-LoRA",
+    "Qari-OCR-LoRA",
+    "HassanB4/Qari-OCR-LoRA",
+    "Tawkeed OCR",
+    "tawkeed-sa/tawkeed-ocr",
+    "PaddleOCR-VL",
+    "PaddlePaddle/PaddleOCR-VL-1.6",
+    "oi-OCR",
+    "oi-uae/oi-OCR",
+    "SILMA TTS",
+    "silma-ai/silma-tts",
+    "Apache-2.0 model weights",
+    "SILMA open source Arabic TTS models",
+    "SILMA Arabic TTS benchmark",
+    "SILMA Hugging Face launch article",
+    "Habibi-TTS",
+    "Habibi-TTS paper",
+    "2601.13802",
+    "specialized MSA model is Apache-2.0",
+    "Mishkala Tashkeel",
+    "flokymind/mishkala",
+    "Tashkeel-350M",
+    "Etherll/Tashkeel-350M",
+    "Mushkil",
+    "riotu-lab/mushkil",
+    "Thaka KSAA-2026 speech diacritization",
+    "2605.25928",
+    "KSAA-2026",
+    "research signal only",
+    "3arab-TTS 500M",
+    "sherif1313/3arab-TTS-500M-v1",
+    "3arab-TTS-500M-v1-VoiceDesign",
+    "KaniTTS Arabic",
+    "nineninesix/kani-tts-400m-ar",
+    "Emirati VITS Male",
+    "vadimbelsky/emirati-vits-male-1.0",
+    "VoxCPM2",
+    "openbmb/VoxCPM2",
+    "Voxtral TTS",
+    "mistralai/Voxtral-4B-TTS-2603",
+    "cc-by-nc-4.0",
+    "MOSS-TTS-Nano",
+    "OpenMOSS/MOSS-TTS-Nano",
+    "Supertonic 3",
+    "Supertone/supertonic-3",
+    "OpenRAIL model",
+    "Kyutai Pocket TTS",
+    "kyutai.org/tts",
+    "not Arabic",
+    "Falcon-OCR",
+    "tiiuae/Falcon-OCR",
+    "Baseer OCR",
+    "AbdoTarek/Baseer-OCR-V1.0",
+    "Arabic-GLM-OCR-v2",
+    "sherif1313/Arabic-GLM-OCR-v2",
+    "Arabic-Qwen3.5-OCR-v4",
+    "sherif1313/Arabic-Qwen3.5-OCR-v4",
+    "aNS Qwen3-VL Arabic OCR v3",
+    "aNS2024/qwen3-vl-arabic-ocr-v3",
+    "Waraqon v3 Arabic OCR HTML Qari",
+    "FatimahEmadEldin/Waraqon-v3-Arabic-OCR-HTML-Qari",
+    "DeepSeek-OCR-2",
+    "deepseek-ai/DeepSeek-OCR-2",
+    "DeepSeek Arabic OCR v6",
+    "melsiddieg/deepseek_ocr_arabic_v6",
+    "Loay Arabic-OCR-DeepSeek-OCR-2",
+    "loay/Arabic-OCR-DeepSeek-OCR-2",
+    "Arabic-English handwritten OCR Qwen3-VL",
+    "sherif1313/Arabic-English-handwritten-OCR-Qwen3-VL-4B",
+    "Arabic-English handwritten OCR v3",
+    "sherif1313/Arabic-English-handwritten-OCR-v3",
+    "Arabic handwritten OCR 4-bit Qwen2.5-VL",
+    "sherif1313/Arabic-handwritten-OCR-4bit-Qwen2.5-VL-3B-v3",
+    "NAKBA Arabic manuscript line OCR baseline",
+    "U4RASD/ar-ms-baseline",
+    "HAFITH",
+    "mdnaseif/hafith",
+    "Glimpse RTL OCR",
+    "surfiniaburger/unsloth_finetune_ocr_arabic",
+    "Arabic OCR Qwen2.5-VL GGUF",
+    "mo1998/arabic-ocr-qwen2.5-vl",
+    "Qwen3-VL Persian/Arabic line OCR",
+    "mohajesmaeili/Qwen3-VL-2B-Persian-Arabic-Ocr-v1.0",
+    "DIMI Arabic OCR v2",
+    "AhmedZaky1/DIMI-Arabic-OCR-V2",
+    "Raqim post-OCR correction",
+    "Arabic Legal Documents OCR 1.0",
+    "bakrianoo/arabic-legal-documents-ocr-1.0",
+    "Loay Arabic-OCR-Qwen2.5-VL-7B",
+    "loay/Arabic-OCR-Qwen2.5-VL-7B-Vision",
+    "AtlasOCR",
+    "atlasia/AtlasOCR",
+    "NuExtract3",
+    "numind/NuExtract3",
+    "Qianfan-OCR",
+    "baidu/Qianfan-OCR",
+    "Chandra OCR 2",
+    "datalab-to/chandra",
+    "dots.ocr",
+    "rednote-hilab/dots.ocr",
+    "olmOCR Arabic LoRA v2",
+    "hastyle/olmOCR-arabic-lora-v2",
+    "Arabic Large Nougat",
+    "MohamedRashad/arabic-large-nougat",
+    "DocTR Arabic FAST/PARSEQ",
+    "madskills/doctr-fast_base-arabic",
+    "madskills/doctr-parseq-arabic",
+    "Kraken/eScriptorium Arabic script",
+    "kraken.re/main/index.html",
+    "escriptorium.eu/about",
+    "Kairawan/Qalamus manuscript OCR",
+    "kairawan.org",
+    "GLM-OCR Arabic/French documents",
+    "maloukafer/GLM-OCR-finetuned-documents",
+    "mimoha Arabic OCR",
+    "mimoha/ocr",
+    "OmniVoice",
+    "k2-fsa/OmniVoice",
+    "OmniVoice Arabic LoRA",
+    "vivooglobal/omnivoice-lora-ar",
+    "Arabic-text-to-speech OmniVoice",
+    "bilalRHCH/Arabic-text-to-speech",
+    "Lahgtna OmniVoice v2",
+    "oddadmix/lahgtna-omnivoice-v2",
+    "TADA multilingual TTS",
+    "HumeAI/tada-3b-ml",
+    "Lahgtna Chatterbox",
+    "oddadmix/lahgtna-chatterbox-v1",
+    "NAMAA-Saudi-TTS",
+    "NAMAA-Space/NAMAA-Saudi-TTS",
+    "NAMAA-Egyptian-TTS",
+    "NAMAA-Space/NAMAA-Egyptian-TTS",
+    "Saudi Chatterbox fine-tune",
+    "FatimahEmadEldin/saudi-tts-chatterbox-finetuned",
+    "Saudi TTS",
+    "AhmedEladl/saudi-tts",
+    "Egyptian Arabic Chatterbox",
+    "AliAbdallah/egyptian-arabic-tts-chatterbox",
+    "NileTTS-XTTS",
+    "KickItLikeShika/NileTTS-XTTS",
+    "Arabic XTTS-v2 Egyptian fine-tune",
+    "Moeeldouma/arabic-tts-xtts-v2",
+    "Coqui Public Model License",
+    "Chatterbox-Multilingual",
+    "resemble-ai/chatterbox",
+    "Chatterbox Arabic fine-tune",
+    "juliardi/chatterbox-multilingual-finetuned-arabic",
+    "Chatterbox-Multilingual ONNX",
+    "onnx-community/chatterbox-multilingual-ONNX",
+    "tts-arabic-onnx",
+    "nipponjo/tts-arabic-onnx",
+    "Spark-TTS Arabic",
+    "azeddinShr/Spark-TTS-Arabic-Complete",
+    "Sofelia-TTS",
+    "hamdallah/Sofelia-TTS",
+    "Arabic-F5-TTS-v2",
+    "IbrahimSalah/Arabic-F5-TTS-v2",
+    "Qwen3-TTS",
+    "Qwen3-TTS-12Hz-0.6B-Base",
+    "Qwen3-TTS-12Hz-1.7B-Base",
+    "Egyptian Arabic Qwen3-TTS",
+    "itshamdi404/Egy_Arabic_Qwen3-TTS-12Hz-1.7B-Base",
+    "Saudi Arabic Qwen3-TTS",
+    "vadimbelsky/qwen3-TTS-KSA",
+    "Emirati Qwen3.5-TTS",
+    "vadimbelsky/qwen3.5-TTS-Emirati",
+    "MMS Arabic TTS",
+    "Vercel FastAPI",
+    "Vercel Blob usage and pricing",
+    "Vercel Functions limits",
+    "4.5 MB request/response body limit",
+    "Hugging Face Docker Spaces",
+    "Hugging Face Hub storage limits",
+    "2 vCPU",
+    "16 GB RAM",
+    "50 GB non-persistent disk",
+]
+MAX_METADATA_AGE_DAYS = 30
+REQUIRED_METADATA_MARKERS = [
+    "NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct",
+    "silma-ai/silma-tts",
+    "sherif1313/Arabic-Qwen3.5-OCR-v4",
+    "deepseek-ai/DeepSeek-OCR-2",
+    "melsiddieg/deepseek_ocr_arabic_v6",
+    "sherif1313/Arabic-GLM-OCR-v2",
+    "sherif1313/Arabic-English-handwritten-OCR-Qwen3-VL-4B",
+    "sherif1313/Arabic-English-handwritten-OCR-v3",
+    "mohajesmaeili/Qwen3-VL-2B-Persian-Arabic-Ocr-v1.0",
+    "bakrianoo/arabic-legal-documents-ocr-1.0",
+    "oi-uae/oi-OCR",
+    "NAMAA-Space/NAMAA-Saudi-TTS",
+    "AhmedEladl/saudi-tts",
+    "AliAbdallah/egyptian-arabic-tts-chatterbox",
+    "KickItLikeShika/NileTTS-XTTS",
+    "Moeeldouma/arabic-tts-xtts-v2",
+    "onnx-community/chatterbox-multilingual-ONNX",
+    "itshamdi404/Egy_Arabic_Qwen3-TTS-12Hz-1.7B-Base",
+    "vadimbelsky/qwen3-TTS-KSA",
+    "vadimbelsky/qwen3.5-TTS-Emirati",
+    "sherif1313/3arab-TTS-500M-v1-VoiceDesign",
+    "numind/NuExtract3",
+    "baidu/Qianfan-OCR",
+    "datalab-to/chandra",
+    "rednote-hilab/dots.ocr",
+    "MohamedRashad/arabic-large-nougat",
+    "apache-2.0",
+    "gpl-3.0",
+    "cc-by-nc-4.0",
+    "fair-noncommercial-research-license",
+    "coqui-public-model-license",
+    "openrail",
+    "Rows marked `page-only` use verified public model-page evidence",
+]
+REQUIRED_RECOMMENDATION_MARKERS = [
+    "Recommended Free Arabic PDF To Audio Stack",
+    "PyMuPDF text extraction first",
+    "`OCR_ENGINE=arabic-max`",
+    "SILMA TTS",
+    "Vercel shell plus Docker worker",
+    "Benchmark Before Promoting",
+    "model_promotion_gate.py",
+    "PyMuPDF -> `arabic-max` OCR -> SILMA TTS",
+]
+REQUIRED_DECISION_CARD_MARKERS = [
+    "Recommended Free Arabic PDF To Audio Decision Card",
+    "PyMuPDF embedded text first",
+    "OCR_ENGINE=arabic-max",
+    "SILMA TTS",
+    "worker-local retained downloads",
+    "Vercel shell plus Docker worker",
+    "model_promotion_gate.py",
+    "scoreJsonRequired",
+]
+REQUIRED_WATCHLIST_COMMAND_MARKERS = [
+    "model_promotion_gate.py",
+    "score_external_ocr.py",
+    "score_voice_listening.py",
+    "score_tts_preprocessor.py",
+    "--write-json outputs\\external-ocr-sample\\external-ocr-score.json",
+    "--write-json outputs\\external-tts-sample\\voice-listening-score.json",
+    "--write-json outputs\\external-tts-sample\\tts-preprocessor-score.json",
+    "--candidate oi-ocr=outputs\\external-ocr-sample\\oi-ocr.txt",
+    "--kind ocr",
+    "--kind tts",
+    "--kind preprocessor",
+]
+WORKFLOW_DOC_PATHS = [
+    ROOT_DIR / "README.md",
+    ROOT_DIR / "docs" / "best-free-arabic-pdf-audio-stack.md",
+]
+REQUIRED_WORKFLOW_MARKERS = [
+    "QARI-OCR 0.4 GGUF",
+    "Loay Arabic-OCR-DeepSeek-OCR-2",
+    "NAMAA-Egyptian-TTS",
+    "Chatterbox Arabic fine-tune",
+    "not served as a simple hosted Hugging Face inference route",
+    "not deployed by a hosted inference provider",
+    "--candidate qari-gguf=outputs\\external-ocr-sample\\qari-gguf.txt",
+    "--candidate loay-deepseek-ocr-2=outputs\\external-ocr-sample\\loay-deepseek-ocr-2.txt",
+    "outputs\\external-tts-sample\\arabic-tts-sample.txt",
+    "model_promotion_gate.py",
+]
+KEY_SOURCE_URLS = {
+    "QARI-OCR 0.4 model": "https://huggingface.co/NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct",
+    "QARI-OCR 0.4 GGUF model": "https://huggingface.co/marwan-osama/Qari-OCR-0.4.0-VL-4B-Instruct-GGUF",
+    "KATIB Arabic OCR model": "https://huggingface.co/oddadmix/Katib-Qwen3.5-0.8B-0.1",
+    "Ketaba-OCR LoRA model": "https://huggingface.co/HassanB4/Ketaba-OCR-LoRA",
+    "Qari-OCR-LoRA model": "https://huggingface.co/HassanB4/Qari-OCR-LoRA",
+    "Tawkeed Arabic OCR model": "https://huggingface.co/tawkeed-sa/tawkeed-ocr",
+    "PaddleOCR-VL 1.6 model": "https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.6",
+    "oi-OCR model": "https://huggingface.co/oi-uae/oi-OCR",
+    "Qianfan-OCR model": "https://huggingface.co/baidu/Qianfan-OCR",
+    "PaddleOCR latest docs": "https://www.paddleocr.ai/latest/en/index.html",
+    "SILMA TTS model": "https://huggingface.co/silma-ai/silma-tts",
+    "SILMA open source Arabic TTS models": "https://silma.ai/open-source-arabic-tts-models",
+    "SILMA Arabic TTS benchmark": "https://silma.ai/arabic-tts-benchmark",
+    "SILMA Hugging Face launch article": "https://huggingface.co/blog/silma-ai/opensource-arabic-english-text-to-speech-model",
+    "Habibi-TTS repository": "https://github.com/SWivid/Habibi-TTS",
+    "Habibi-TTS paper": "https://arxiv.org/abs/2601.13802",
+    "Mishkala Tashkeel model": "https://huggingface.co/flokymind/mishkala",
+    "Tashkeel 350M model": "https://huggingface.co/Etherll/Tashkeel-350M",
+    "Mushkil model": "https://huggingface.co/riotu-lab/mushkil",
+    "Thaka KSAA 2026 speech diacritization paper": "https://arxiv.org/abs/2605.25928",
+    "KSAA 2026 shared task": "https://www.codabench.org/competitions/11859/",
+    "3arab-TTS 500M model": "https://huggingface.co/sherif1313/3arab-TTS-500M-v1",
+    "3arab-TTS 500M VoiceDesign model": "https://huggingface.co/sherif1313/3arab-TTS-500M-v1-VoiceDesign",
+    "KaniTTS Arabic model": "https://huggingface.co/nineninesix/kani-tts-400m-ar",
+    "Emirati VITS Male model": "https://huggingface.co/vadimbelsky/emirati-vits-male-1.0",
+    "VoxCPM2 model": "https://huggingface.co/openbmb/VoxCPM2",
+    "VoxCPM paper": "https://arxiv.org/abs/2509.24650",
+    "Voxtral TTS model": "https://huggingface.co/mistralai/Voxtral-4B-TTS-2603",
+    "Voxtral TTS paper": "https://arxiv.org/abs/2603.25551",
+    "MOSS-TTS-Nano repository": "https://github.com/OpenMOSS/MOSS-TTS-Nano",
+    "Supertonic 3 model": "https://huggingface.co/Supertone/supertonic-3",
+    "Kyutai TTS official page": "https://kyutai.org/tts",
+    "Falcon OCR model": "https://huggingface.co/tiiuae/Falcon-OCR",
+    "Falcon Perception paper": "https://arxiv.org/abs/2603.27365",
+    "Baseer OCR model": "https://huggingface.co/AbdoTarek/Baseer-OCR-V1.0",
+    "Arabic GLM OCR v2 model": "https://huggingface.co/sherif1313/Arabic-GLM-OCR-v2",
+    "Arabic Qwen3.5 OCR v4 model": "https://huggingface.co/sherif1313/Arabic-Qwen3.5-OCR-v4",
+    "aNS Qwen3 VL Arabic OCR v3 model": "https://huggingface.co/aNS2024/qwen3-vl-arabic-ocr-v3",
+    "Waraqon v3 Arabic OCR HTML Qari model": "https://huggingface.co/FatimahEmadEldin/Waraqon-v3-Arabic-OCR-HTML-Qari",
+    "DeepSeek OCR 2 model": "https://huggingface.co/deepseek-ai/DeepSeek-OCR-2",
+    "DeepSeek Arabic OCR v6 model": "https://huggingface.co/melsiddieg/deepseek_ocr_arabic_v6",
+    "Loay Arabic DeepSeek OCR 2 model": "https://huggingface.co/loay/Arabic-OCR-DeepSeek-OCR-2",
+    "Arabic-English handwritten OCR Qwen3-VL model": "https://huggingface.co/sherif1313/Arabic-English-handwritten-OCR-Qwen3-VL-4B",
+    "Arabic-English handwritten OCR v3 model": "https://huggingface.co/sherif1313/Arabic-English-handwritten-OCR-v3",
+    "Arabic handwritten OCR 4-bit Qwen2.5 VL model": "https://huggingface.co/sherif1313/Arabic-handwritten-OCR-4bit-Qwen2.5-VL-3B-v3",
+    "NAKBA Arabic manuscript line OCR baseline": "https://huggingface.co/U4RASD/ar-ms-baseline",
+    "HAFITH model": "https://huggingface.co/mdnaseif/hafith",
+    "Glimpse RTL OCR model": "https://huggingface.co/surfiniaburger/unsloth_finetune_ocr_arabic",
+    "Arabic OCR Qwen2.5 VL GGUF model": "https://huggingface.co/mo1998/arabic-ocr-qwen2.5-vl",
+    "Qwen3-VL Persian Arabic line OCR model": "https://huggingface.co/mohajesmaeili/Qwen3-VL-2B-Persian-Arabic-Ocr-v1.0",
+    "DIMI Arabic OCR v2 model": "https://huggingface.co/AhmedZaky1/DIMI-Arabic-OCR-V2",
+    "Loay Arabic OCR Qwen2.5 VL 7B model": "https://huggingface.co/loay/Arabic-OCR-Qwen2.5-VL-7B-Vision",
+    "Arabic Legal Documents OCR 1.0 model": "https://huggingface.co/bakrianoo/arabic-legal-documents-ocr-1.0",
+    "AtlasOCR model": "https://huggingface.co/atlasia/AtlasOCR",
+    "NuExtract3 model": "https://huggingface.co/numind/NuExtract3",
+    "Chandra OCR repository": "https://github.com/datalab-to/chandra",
+    "dots.ocr model": "https://huggingface.co/rednote-hilab/dots.ocr",
+    "olmOCR Arabic LoRA v2 model": "https://huggingface.co/hastyle/olmOCR-arabic-lora-v2",
+    "Arabic Large Nougat model": "https://huggingface.co/MohamedRashad/arabic-large-nougat",
+    "DocTR Arabic FAST detector": "https://huggingface.co/madskills/doctr-fast_base-arabic",
+    "DocTR Arabic PARSEQ recognizer": "https://huggingface.co/madskills/doctr-parseq-arabic",
+    "Kraken OCR documentation": "https://kraken.re/main/index.html",
+    "eScriptorium overview": "https://escriptorium.eu/about",
+    "Kairawan manuscript OCR": "https://kairawan.org/",
+    "GLM-OCR Arabic French documents model": "https://huggingface.co/maloukafer/GLM-OCR-finetuned-documents",
+    "mimoha Arabic OCR model": "https://huggingface.co/mimoha/ocr",
+    "OmniVoice model": "https://huggingface.co/k2-fsa/OmniVoice",
+    "OmniVoice Arabic LoRA": "https://huggingface.co/vivooglobal/omnivoice-lora-ar",
+    "Arabic text to speech OmniVoice model": "https://huggingface.co/bilalRHCH/Arabic-text-to-speech",
+    "Lahgtna OmniVoice v2 model": "https://huggingface.co/oddadmix/lahgtna-omnivoice-v2",
+    "TADA multilingual TTS model": "https://huggingface.co/HumeAI/tada-3b-ml",
+    "Lahgtna Chatterbox model": "https://huggingface.co/oddadmix/lahgtna-chatterbox-v1",
+    "NAMAA Saudi TTS model": "https://huggingface.co/NAMAA-Space/NAMAA-Saudi-TTS",
+    "NAMAA Egyptian TTS model": "https://huggingface.co/NAMAA-Space/NAMAA-Egyptian-TTS",
+    "Saudi Chatterbox fine-tune model": "https://huggingface.co/FatimahEmadEldin/saudi-tts-chatterbox-finetuned",
+    "Saudi TTS model": "https://huggingface.co/AhmedEladl/saudi-tts",
+    "Egyptian Arabic Chatterbox model": "https://huggingface.co/AliAbdallah/egyptian-arabic-tts-chatterbox",
+    "NileTTS XTTS model": "https://huggingface.co/KickItLikeShika/NileTTS-XTTS",
+    "Arabic XTTS v2 Egyptian fine-tune model": "https://huggingface.co/Moeeldouma/arabic-tts-xtts-v2",
+    "NileTTS paper": "https://arxiv.org/abs/2602.15675",
+    "Chatterbox repository": "https://github.com/resemble-ai/chatterbox",
+    "Chatterbox Arabic fine-tune model": "https://huggingface.co/juliardi/chatterbox-multilingual-finetuned-arabic",
+    "Chatterbox Multilingual ONNX model": "https://huggingface.co/onnx-community/chatterbox-multilingual-ONNX",
+    "tts-arabic-onnx model": "https://huggingface.co/nipponjo/tts-arabic-onnx",
+    "tts_arabic repository": "https://github.com/nipponjo/tts_arabic",
+    "Spark-TTS Arabic model": "https://huggingface.co/azeddinShr/Spark-TTS-Arabic-Complete",
+    "Sofelia-TTS model": "https://huggingface.co/hamdallah/Sofelia-TTS",
+    "Arabic F5 TTS v2 model": "https://huggingface.co/IbrahimSalah/Arabic-F5-TTS-v2",
+    "Qwen3-TTS 0.6B Base": "https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-Base",
+    "Qwen3-TTS 1.7B Base": "https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-Base",
+    "Egyptian Arabic Qwen3-TTS model": "https://huggingface.co/itshamdi404/Egy_Arabic_Qwen3-TTS-12Hz-1.7B-Base",
+    "Saudi Arabic Qwen3-TTS model": "https://huggingface.co/vadimbelsky/qwen3-TTS-KSA",
+    "Emirati Qwen3.5-TTS model": "https://huggingface.co/vadimbelsky/qwen3.5-TTS-Emirati",
+    "Qwen3-TTS technical report": "https://arxiv.org/abs/2601.15621",
+    "Vercel FastAPI deployment": "https://vercel.com/docs/frameworks/backend/fastapi",
+    "Vercel Functions limits": "https://vercel.com/docs/functions/limitations/",
+    "Vercel Blob usage and pricing": "https://vercel.com/docs/vercel-blob/usage-and-pricing",
+    "Hugging Face Docker Spaces": "https://huggingface.co/docs/hub/main/en/spaces-sdks-docker",
+    "Hugging Face Hub storage limits": "https://huggingface.co/docs/hub/main/storage-limits",
+}
+HF_EXPECTED_LICENSES = {
+    "NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct": "apache-2.0",
+    "marwan-osama/Qari-OCR-0.4.0-VL-4B-Instruct-GGUF": "apache-2.0",
+    "oddadmix/Katib-Qwen3.5-0.8B-0.1": "apache-2.0",
+    "HassanB4/Ketaba-OCR-LoRA": "apache-2.0",
+    "HassanB4/Qari-OCR-LoRA": "apache-2.0",
+    "tawkeed-sa/tawkeed-ocr": "apache-2.0",
+    "PaddlePaddle/PaddleOCR-VL-1.6": "apache-2.0",
+    "oi-uae/oi-OCR": "apache-2.0",
+    "madskills/doctr-fast_base-arabic": "apache-2.0",
+    "mimoha/ocr": "apache-2.0",
+    "silma-ai/silma-tts": "apache-2.0",
+    "flokymind/mishkala": "apache-2.0",
+    "Etherll/Tashkeel-350M": "apache-2.0",
+    "riotu-lab/mushkil": "apache-2.0",
+    "sherif1313/3arab-TTS-500M-v1": "apache-2.0",
+    "sherif1313/3arab-TTS-500M-v1-VoiceDesign": "apache-2.0",
+    "vadimbelsky/emirati-vits-male-1.0": "apache-2.0",
+    "openbmb/VoxCPM2": "apache-2.0",
+    "mistralai/Voxtral-4B-TTS-2603": "cc-by-nc-4.0",
+    "Supertone/supertonic-3": "openrail",
+    "baidu/Qianfan-OCR": "apache-2.0",
+    "tiiuae/Falcon-OCR": "apache-2.0",
+    "AbdoTarek/Baseer-OCR-V1.0": "apache-2.0",
+    "sherif1313/Arabic-GLM-OCR-v2": "apache-2.0",
+    "sherif1313/Arabic-Qwen3.5-OCR-v4": "apache-2.0",
+    "FatimahEmadEldin/Waraqon-v3-Arabic-OCR-HTML-Qari": "apache-2.0",
+    "deepseek-ai/DeepSeek-OCR-2": "apache-2.0",
+    "melsiddieg/deepseek_ocr_arabic_v6": "apache-2.0",
+    "loay/Arabic-OCR-DeepSeek-OCR-2": "apache-2.0",
+    "sherif1313/Arabic-English-handwritten-OCR-Qwen3-VL-4B": "apache-2.0",
+    "sherif1313/Arabic-English-handwritten-OCR-v3": "apache-2.0",
+    "sherif1313/Arabic-handwritten-OCR-4bit-Qwen2.5-VL-3B-v3": "apache-2.0",
+    "mdnaseif/hafith": "apache-2.0",
+    "surfiniaburger/unsloth_finetune_ocr_arabic": "apache-2.0",
+    "mohajesmaeili/Qwen3-VL-2B-Persian-Arabic-Ocr-v1.0": "apache-2.0",
+    "AhmedZaky1/DIMI-Arabic-OCR-V2": "apache-2.0",
+    "hastyle/olmOCR-arabic-lora-v2": "apache-2.0",
+    "MohamedRashad/arabic-large-nougat": "gpl-3.0",
+    "bakrianoo/arabic-legal-documents-ocr-1.0": "gemma",
+    "k2-fsa/OmniVoice": "apache-2.0",
+    "bilalRHCH/Arabic-text-to-speech": "apache-2.0",
+    "vivooglobal/omnivoice-lora-ar": "apache-2.0",
+    "HumeAI/tada-3b-ml": "llama3.2",
+    "oddadmix/lahgtna-chatterbox-v1": "mit",
+    "NAMAA-Space/NAMAA-Saudi-TTS": "mit",
+    "NAMAA-Space/NAMAA-Egyptian-TTS": "mit",
+    "FatimahEmadEldin/saudi-tts-chatterbox-finetuned": "apache-2.0",
+    "AhmedEladl/saudi-tts": "apache-2.0",
+    "AliAbdallah/egyptian-arabic-tts-chatterbox": "apache-2.0",
+    "juliardi/chatterbox-multilingual-finetuned-arabic": "mit",
+    "KickItLikeShika/NileTTS-XTTS": "apache-2.0",
+    "Moeeldouma/arabic-tts-xtts-v2": "coqui-public-model-license",
+    "onnx-community/chatterbox-multilingual-ONNX": "mit",
+    "azeddinShr/Spark-TTS-Arabic-Complete": "apache-2.0",
+    "hamdallah/Sofelia-TTS": "apache-2.0",
+    "Qwen/Qwen3-TTS-12Hz-0.6B-Base": "apache-2.0",
+    "Qwen/Qwen3-TTS-12Hz-1.7B-Base": "apache-2.0",
+    "itshamdi404/Egy_Arabic_Qwen3-TTS-12Hz-1.7B-Base": "apache-2.0",
+    "vadimbelsky/qwen3-TTS-KSA": "apache-2.0",
+    "vadimbelsky/qwen3.5-TTS-Emirati": "apache-2.0",
+}
+HF_PAGE_ONLY_METADATA = {
+    "NAMAA-Space/Qari-OCR-0.4.0-VL-4B-Instruct": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only so restricted local sockets do not erase the core Arabic-book OCR evidence.",
+    },
+    "oddadmix/Katib-Qwen3.5-0.8B-0.1": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only because it is a wired optional Arabic OCR sidecar.",
+    },
+    "HassanB4/Ketaba-OCR-LoRA": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only because it is an external Arabic manuscript benchmark candidate.",
+    },
+    "HassanB4/Qari-OCR-LoRA": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only because it is a secondary external QARI-family manuscript benchmark.",
+    },
+    "silma-ai/silma-tts": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only so restricted local sockets do not erase the core Arabic TTS evidence.",
+    },
+    "NAMAA-Space/NAMAA-Saudi-TTS": {
+        "license": "mit",
+        "reason": "Hugging Face model page was verified in research, but raw metadata may not be available in restricted environments.",
+    },
+    "tawkeed-sa/tawkeed-ocr": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page is public, but raw API/HTTP requests can return 401/404 for this namespace.",
+    },
+    "MohamedRashad/arabic-large-nougat": {
+        "license": "gpl-3.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only because the public model card is enough for license/status tracking and the model is benchmark-only.",
+    },
+    "baidu/Qianfan-OCR": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only because this large benchmark-only model does not need local metadata fetches to block/promote the default stack.",
+    },
+    "AhmedEladl/saudi-tts": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only because it is a dialect benchmark candidate, not a default production voice.",
+    },
+    "Moeeldouma/arabic-tts-xtts-v2": {
+        "license": "coqui-public-model-license",
+        "reason": "Hugging Face model page was verified in research; keep page-only because it is an XTTS-v2 dialect benchmark and inherits CPML base-license caution.",
+    },
+    "datalab-to/chandra": {
+        "license": "openrail",
+        "reason": "Hugging Face/official project metadata was verified in research; keep page-only because Chandra is benchmark-only and the weights are not the permissive default path.",
+    },
+    "mistralai/Voxtral-4B-TTS-2603": {
+        "license": "cc-by-nc-4.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only because this voice is explicitly non-commercial and external-only.",
+    },
+    "IbrahimSalah/Arabic-F5-TTS-v2": {
+        "license": "fair-noncommercial-research-license",
+        "reason": "Hugging Face model page was verified in research; keep page-only because it is non-commercial and requires diacritized Arabic.",
+    },
+    "Supertone/supertonic-3": {
+        "license": "openrail",
+        "reason": "Hugging Face model page was verified in research; keep page-only so the optional CPU voice benchmark remains tracked when live metadata fetches are blocked.",
+    },
+    "bilalRHCH/Arabic-text-to-speech": {
+        "license": "apache-2.0",
+        "reason": "Hugging Face model page was verified in research; keep page-only because this Arabic-focused OmniVoice package is benchmark-only and raw metadata fetches can fail locally.",
+    }
+}
+
+WATCHLIST_POLICY_PATH = ROOT_DIR / "docs" / "research-watchlist.md"
+WATCHLIST_ALLOWED_DEFAULTS = {
+    "SILMA TTS",
+}
+WATCHLIST_ALLOWED_WIRED_OPTIONAL = {
+    "QARI-OCR 0.4",
+    "PaddleOCR-VL-1.6",
+    "KATIB 0.8B",
+    "Arabic-GLM-OCR-v2",
+    "Arabic-Qwen3.5-OCR-v4",
+    "Ketaba-OCR LoRA",
+    "Tawkeed OCR",
+    "Baseer OCR V1.0",
+    "Habibi-TTS MSA",
+    "Supertonic 3",
+}
+WATCHLIST_BENCHMARK_ONLY_REASONS = {
+    "DeepSeek-OCR-2": "external general OCR benchmark",
+    "aNS Qwen3-VL Arabic OCR v3": "fresh Qwen3-VL Arabic OCR benchmark with sparse production evidence",
+    "Waraqon v3 Arabic OCR HTML Qari": "external Qari-family structured HTML OCR benchmark",
+    "DeepSeek Arabic OCR v6": "external Arabic OCR benchmark",
+    "Loay Arabic-OCR-DeepSeek-OCR-2": "external Arabic DeepSeek-OCR-2 layout benchmark",
+    "Arabic-English handwritten OCR v3": "external handwriting/manuscript benchmark",
+    "Arabic handwritten OCR 4-bit Qwen2.5-VL": "external quantized handwriting/manuscript benchmark",
+    "NAKBA Arabic manuscript line OCR baseline": "line-level manuscript OCR benchmark with license confirmation",
+    "HAFITH": "historical Arabic manuscript line OCR benchmark",
+    "Glimpse RTL OCR": "Arabic/Persian RTL text-line OCR benchmark",
+    "Arabic OCR Qwen2.5-VL GGUF": "external GGUF Arabic OCR benchmark with license confirmation",
+    "Qwen3-VL Persian/Arabic line OCR": "line-level OCR benchmark",
+    "Loay Arabic-OCR-Qwen2.5-VL-7B": "large external Arabic OCR benchmark",
+    "DIMI Arabic OCR v2": "large external Arabic OCR benchmark",
+    "AtlasOCR": "license/content-specific OCR watchlist",
+    "NuExtract3": "external multilingual document OCR benchmark",
+    "Qianfan-OCR": "large external multilingual document OCR benchmark",
+    "Chandra OCR 2": "modified OpenRAIL structured-document OCR benchmark",
+    "dots.ocr": "external multilingual document-layout OCR benchmark",
+    "olmOCR Arabic LoRA v2": "full-page Arabic manuscript OCR benchmark with base-license/runtime confirmation",
+    "Arabic Large Nougat": "GPL Arabic book OCR-to-Markdown benchmark",
+    "DocTR Arabic FAST/PARSEQ": "classic Arabic OCR benchmark with recognition license confirmation",
+    "Kraken/eScriptorium Arabic script": "historical Arabic-script OCR benchmark with model-license confirmation",
+    "Kairawan/Qalamus manuscript OCR": "service-only Arabic manuscript OCR benchmark signal",
+    "GLM-OCR Arabic/French documents": "external Arabic/French document OCR benchmark",
+    "mimoha Arabic OCR": "sparse-card Arabic OCR watchlist",
+    "oi-OCR": "external document parser benchmark",
+    "Falcon-OCR": "external OCR benchmark",
+    "Raqim post-OCR correction": "correction-risk OCR caution",
+    "Arabic Legal Documents OCR 1.0": "Gemma-licensed domain-specific OCR caution",
+    "Mishkala Tashkeel": "pronunciation preprocessor benchmark",
+    "Tashkeel-350M": "larger pronunciation preprocessor benchmark",
+    "Mushkil": "AraT5V2 pronunciation preprocessor benchmark",
+    "Thaka KSAA-2026 speech diacritization": "research signal only",
+    "3arab-TTS 500M": "new Arabic voice benchmark",
+    "KaniTTS Arabic": "metadata/license uncertainty",
+    "Emirati VITS Male": "dialect voice benchmark",
+    "VoxCPM2": "large strong-worker voice benchmark",
+    "Voxtral TTS": "non-commercial license",
+    "OmniVoice": "external multilingual voice benchmark",
+    "OmniVoice Arabic LoRA": "external Arabic adapter benchmark",
+    "Arabic-text-to-speech OmniVoice": "external Arabic-focused OmniVoice benchmark",
+    "Lahgtna OmniVoice v2": "dialect and license-uncertain voice benchmark",
+    "TADA multilingual TTS": "Llama-licensed strong-worker voice benchmark",
+    "Lahgtna Chatterbox": "dialect voice benchmark",
+    "NAMAA-Saudi-TTS": "Saudi dialect voice benchmark",
+    "NAMAA-Egyptian-TTS": "Egyptian dialect voice benchmark",
+    "Saudi Chatterbox fine-tune": "Saudi dialect voice benchmark",
+    "Saudi TTS": "Saudi dialect voice benchmark",
+    "Egyptian Arabic Chatterbox": "Egyptian dialect voice benchmark",
+    "NileTTS-XTTS": "Egyptian dialect voice benchmark",
+    "Arabic XTTS-v2 Egyptian fine-tune": "CPML/base-license dialect XTTS benchmark",
+    "Chatterbox-Multilingual": "external multilingual voice benchmark",
+    "Chatterbox Arabic fine-tune": "MSA-focused Chatterbox Arabic adapter benchmark",
+    "Chatterbox-Multilingual ONNX": "external CPU/ONNX multilingual voice benchmark",
+    "tts-arabic-onnx": "license-unclear compact Arabic ONNX voice benchmark",
+    "Spark-TTS Arabic": "external Arabic voice-cloning benchmark",
+    "Sofelia-TTS": "Palestinian dialect voice benchmark",
+    "Arabic-F5-TTS-v2": "non-commercial voice caution",
+    "MOSS-TTS-Nano": "external CPU-friendly multilingual benchmark",
+    "Qwen3-TTS": "not Arabic-ready from official released model cards",
+    "Saudi Arabic Qwen3-TTS": "Saudi/Gulf dialect voice benchmark",
+    "Emirati Qwen3.5-TTS": "Emirati/Gulf dialect voice benchmark",
+}
+WATCHLIST_BENCHMARK_STATUS_MARKERS = (
+    "not wired",
+    "benchmark",
+    "research signal",
+    "not default",
+    "not arabic-ready",
+    "correction can alter",
+)
+WATCHLIST_PROHIBITED_DEFAULT_MARKERS = (
+    "wired default",
+    "default local",
+    "production default",
+)
+
+
+@dataclass
+class SourceCheck:
+    name: str
+    ok: bool
+    detail: str
+
+
+def format_report_date(value: date | None = None) -> str:
+    value = value or date.today()
+    return value.strftime("%B %d, %Y").replace(" 0", " ")
+
+
+def parse_report_date(value: str) -> date | None:
+    try:
+        return datetime.strptime(value.strip().rstrip("."), "%B %d, %Y").date()
+    except ValueError:
+        return None
+
+
+def metadata_refresh_date(text: str) -> date | None:
+    match = re.search(r"^Last refreshed:\s*(.+)$", text, re.MULTILINE)
+    if not match:
+        return None
+    return parse_report_date(match.group(1))
+
+
+def metadata_freshness_check(text: str, max_age_days: int = MAX_METADATA_AGE_DAYS) -> SourceCheck:
+    refreshed = metadata_refresh_date(text)
+    if refreshed is None:
+        return SourceCheck("metadata freshness", False, "missing or invalid Last refreshed date")
+    today = date.today()
+    age_days = (today - refreshed).days
+    if age_days < 0:
+        return SourceCheck("metadata freshness", False, f"future refresh date {refreshed.isoformat()}")
+    return SourceCheck(
+        "metadata freshness",
+        age_days <= max_age_days,
+        f"refreshed={refreshed.isoformat()} ageDays={age_days} maxAgeDays={max_age_days}",
+    )
+
+
+def parse_detail_fields(detail: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for part in detail.split():
+        if "=" not in part:
+            continue
+        key, value = part.split("=", 1)
+        fields[key] = value
+    return fields
+
+
+def extract_urls(paths: list[Path]) -> list[str]:
+    urls: list[str] = []
+    seen: set[str] = set()
+    for path in paths:
+        if not path.exists():
+            continue
+        for match in URL_RE.findall(path.read_text(encoding="utf-8", errors="replace")):
+            url = match.rstrip(".,")
+            if url not in seen:
+                seen.add(url)
+                urls.append(url)
+    return urls
+
+
+def check_required_markers(path: Path = ROOT_DIR / "docs" / "source-evidence.md") -> list[SourceCheck]:
+    text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
+    checks: list[SourceCheck] = []
+    for marker in REQUIRED_SOURCE_MARKERS:
+        checks.append(SourceCheck(f"source marker: {marker}", marker in text, "present" if marker in text else "missing"))
+    return checks
+
+
+def check_metadata_snapshot(path: Path = ROOT_DIR / "docs" / "huggingface-model-metadata.md") -> list[SourceCheck]:
+    text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
+    checks = [SourceCheck("metadata snapshot exists", bool(text), str(path) if text else "missing")]
+    checks.append(metadata_freshness_check(text))
+    for marker in REQUIRED_METADATA_MARKERS:
+        checks.append(SourceCheck(f"metadata marker: {marker}", marker in text, "present" if marker in text else "missing"))
+    return checks
+
+
+def check_recommendation_report(path: Path = ROOT_DIR / "docs" / "recommended-free-stack.md") -> list[SourceCheck]:
+    text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
+    checks = [SourceCheck("recommendation report exists", bool(text), str(path) if text else "missing")]
+    for marker in REQUIRED_RECOMMENDATION_MARKERS:
+        checks.append(
+            SourceCheck(
+                f"recommendation marker: {marker}",
+                marker in text,
+                "present" if marker in text else "missing",
+            )
+        )
+    return checks
+
+
+def check_decision_card(
+    markdown_path: Path = ROOT_DIR / "docs" / "recommended-decision-card.md",
+    json_path: Path = ROOT_DIR / "docs" / "recommended-decision-card.json",
+) -> list[SourceCheck]:
+    markdown = markdown_path.read_text(encoding="utf-8", errors="replace") if markdown_path.exists() else ""
+    json_text = json_path.read_text(encoding="utf-8", errors="replace") if json_path.exists() else ""
+    combined = f"{markdown}\n{json_text}"
+    checks = [
+        SourceCheck("decision card markdown exists", bool(markdown), str(markdown_path) if markdown else "missing"),
+        SourceCheck("decision card json exists", bool(json_text), str(json_path) if json_text else "missing"),
+    ]
+    for marker in REQUIRED_DECISION_CARD_MARKERS:
+        checks.append(
+            SourceCheck(
+                f"decision card marker: {marker}",
+                marker in combined,
+                "present" if marker in combined else "missing",
+            )
+        )
+    return checks
+
+
+def check_watchlist_command_markers(path: Path = WATCHLIST_POLICY_PATH) -> list[SourceCheck]:
+    text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
+    checks = [SourceCheck("watchlist command section exists", "## Benchmark Steps" in text, str(path) if text else "missing")]
+    for marker in REQUIRED_WATCHLIST_COMMAND_MARKERS:
+        checks.append(
+            SourceCheck(
+                f"watchlist command marker: {marker}",
+                marker in text,
+                "present" if marker in text else "missing",
+            )
+        )
+    return checks
+
+
+def check_workflow_doc_markers(paths: list[Path] | None = None) -> list[SourceCheck]:
+    docs = paths or WORKFLOW_DOC_PATHS
+    checks: list[SourceCheck] = []
+    for path in docs:
+        text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
+        checks.append(SourceCheck(f"workflow doc exists: {path.name}", bool(text), str(path) if text else "missing"))
+        for marker in REQUIRED_WORKFLOW_MARKERS:
+            checks.append(
+                SourceCheck(
+                    f"workflow doc marker: {path.name}: {marker}",
+                    marker in text,
+                    "present" if marker in text else "missing",
+                )
+            )
+    return checks
+
+
+def parse_markdown_table_rows(text: str) -> list[dict[str, str]]:
+    headers: list[str] = []
+    rows: list[dict[str, str]] = []
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line.startswith("|") or not line.endswith("|"):
+            continue
+        cells = [cell.strip() for cell in line.strip("|").split("|")]
+        if not cells:
+            continue
+        if all(re.fullmatch(r":?-{3,}:?", cell) for cell in cells):
+            continue
+        if not headers:
+            headers = [cell.lower() for cell in cells]
+            continue
+        if len(cells) != len(headers):
+            continue
+        rows.append(dict(zip(headers, cells)))
+    return rows
+
+
+def status_is_benchmark_only(status: str) -> bool:
+    normalized = status.lower()
+    prohibited = any(marker in normalized for marker in WATCHLIST_PROHIBITED_DEFAULT_MARKERS)
+    allowed = any(marker in normalized for marker in WATCHLIST_BENCHMARK_STATUS_MARKERS)
+    return allowed and not prohibited
+
+
+def check_watchlist_policy(path: Path = WATCHLIST_POLICY_PATH) -> list[SourceCheck]:
+    text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
+    rows = parse_markdown_table_rows(text)
+    checks = [SourceCheck("research watchlist table parsed", bool(rows), f"{len(rows)} rows")]
+    by_candidate = {row.get("candidate", ""): row for row in rows}
+
+    for candidate, reason in WATCHLIST_BENCHMARK_ONLY_REASONS.items():
+        row = by_candidate.get(candidate)
+        if row is None:
+            checks.append(SourceCheck(f"watchlist policy: {candidate}", False, f"missing; reason={reason}"))
+            continue
+        status = row.get("status", "")
+        checks.append(
+            SourceCheck(
+                f"watchlist policy: {candidate}",
+                status_is_benchmark_only(status),
+                f"reason={reason} status={status or '-'}",
+            )
+        )
+
+    for candidate in WATCHLIST_ALLOWED_DEFAULTS:
+        row = by_candidate.get(candidate)
+        status = row.get("status", "") if row else ""
+        checks.append(
+            SourceCheck(
+                f"watchlist default allowed: {candidate}",
+                row is not None and "wired default" in status.lower(),
+                f"status={status or '-'}",
+            )
+        )
+
+    for candidate in WATCHLIST_ALLOWED_WIRED_OPTIONAL:
+        row = by_candidate.get(candidate)
+        status = row.get("status", "") if row else ""
+        normalized = status.lower()
+        ok = row is not None and ("wired optional" in normalized or status_is_benchmark_only(status))
+        checks.append(
+            SourceCheck(
+                f"watchlist optional/default policy: {candidate}",
+                ok,
+                f"status={status or '-'}",
+            )
+        )
+
+    return checks
+
+
+def check_url(url: str, timeout: float = 12.0) -> SourceCheck:
+    request = Request(url, headers={"User-Agent": "ArabicAudioReaderSourceCheck/1.0"})
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            status = getattr(response, "status", 200)
+            ok = 200 <= int(status) < 400
+            return SourceCheck(url, ok, f"HTTP {status}")
+    except HTTPError as exc:
+        return SourceCheck(url, False, f"HTTP {exc.code}")
+    except URLError as exc:
+        return SourceCheck(url, False, f"URL error: {exc.reason}")
+    except TimeoutError:
+        return SourceCheck(url, False, "timeout")
+
+
+def huggingface_model_id(url: str) -> str | None:
+    prefix = "https://huggingface.co/"
+    if not url.startswith(prefix):
+        return None
+    rest = url[len(prefix) :].strip("/")
+    parts = rest.split("/")
+    if len(parts) < 2 or parts[0] in {"docs", "datasets", "spaces"}:
+        return None
+    return "/".join(parts[:2])
+
+
+def model_license(metadata: dict[str, object]) -> str:
+    card_data = metadata.get("cardData")
+    if isinstance(card_data, dict):
+        license_value = card_data.get("license")
+        if isinstance(license_value, str) and license_value.strip():
+            return license_value.strip().lower()
+    tags = metadata.get("tags")
+    if isinstance(tags, list):
+        for tag in tags:
+            if isinstance(tag, str) and tag.startswith("license:"):
+                return tag.split(":", 1)[1].strip().lower()
+    return ""
+
+
+def fetch_huggingface_model(model_id: str, timeout: float = 12.0) -> dict[str, object]:
+    url = f"https://huggingface.co/api/models/{model_id}"
+    headers = {"User-Agent": "ArabicAudioReaderSourceCheck/1.0"}
+    token = os.getenv("HF_API_TOKEN") or os.getenv("HUGGINGFACE_API_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    request = Request(url, headers=headers)
+    with urlopen(request, timeout=timeout) as response:
+        raw = response.read().decode("utf-8", errors="replace")
+    data = json.loads(raw)
+    return data if isinstance(data, dict) else {}
+
+
+def fetch_huggingface_model_page_metadata(model_id: str, timeout: float = 12.0) -> dict[str, object]:
+    url = f"https://huggingface.co/{model_id}"
+    request = Request(url, headers={"User-Agent": "ArabicAudioReaderSourceCheck/1.0"})
+    with urlopen(request, timeout=timeout) as response:
+        html = response.read().decode("utf-8", errors="replace")
+    license_match = re.search(r"License:\s*</span>\s*<span[^>]*>\s*([^<\s]+)", html, re.IGNORECASE)
+    if license_match is None:
+        license_match = re.search(r"License:\s*([A-Za-z0-9_.+-]+)", html, re.IGNORECASE)
+    license_value = license_match.group(1).strip().lower() if license_match else ""
+    return {
+        "id": model_id,
+        "private": False,
+        "disabled": False,
+        "lastModified": "page-fallback",
+        "cardData": {"license": license_value} if license_value else {},
+    }
+
+
+def collect_huggingface_metadata_checks(timeout: float = 12.0) -> list[SourceCheck]:
+    model_ids: list[str] = []
+    for url in KEY_SOURCE_URLS.values():
+        model_id = huggingface_model_id(url)
+        if model_id and model_id not in model_ids:
+            model_ids.append(model_id)
+
+    checks: list[SourceCheck] = []
+    for model_id in model_ids:
+        if model_id in HF_PAGE_ONLY_METADATA:
+            fallback = HF_PAGE_ONLY_METADATA[model_id]
+            license_value = str(fallback.get("license") or "")
+            checks.append(
+                SourceCheck(
+                    f"huggingface metadata: {model_id}",
+                    True,
+                    f"id={model_id} license={license_value or '-'} lastModified=page-only",
+                )
+            )
+            expected_license = HF_EXPECTED_LICENSES.get(model_id)
+            if expected_license:
+                checks.append(
+                    SourceCheck(
+                        f"huggingface license: {model_id}",
+                        license_value == expected_license,
+                        f"expected={expected_license} actual={license_value or '-'}",
+                    )
+                )
+            continue
+        try:
+            metadata = fetch_huggingface_model(model_id, timeout=timeout)
+        except HTTPError as exc:
+            if exc.code in {401, 404}:
+                try:
+                    metadata = fetch_huggingface_model_page_metadata(model_id, timeout=timeout)
+                except Exception:
+                    checks.append(SourceCheck(f"huggingface metadata: {model_id}", False, f"HTTP {exc.code}"))
+                    continue
+            else:
+                checks.append(SourceCheck(f"huggingface metadata: {model_id}", False, f"HTTP {exc.code}"))
+                continue
+        except (URLError, TimeoutError) as exc:
+            checks.append(SourceCheck(f"huggingface metadata: {model_id}", False, str(exc)))
+            continue
+        except json.JSONDecodeError:
+            checks.append(SourceCheck(f"huggingface metadata: {model_id}", False, "invalid JSON"))
+            continue
+
+        reported_id = str(metadata.get("id") or metadata.get("modelId") or "")
+        private = bool(metadata.get("private"))
+        disabled = bool(metadata.get("disabled"))
+        last_modified = str(metadata.get("lastModified") or metadata.get("createdAt") or "unknown")
+        license_value = model_license(metadata)
+        checks.append(
+            SourceCheck(
+                f"huggingface metadata: {model_id}",
+                reported_id == model_id and not private and not disabled,
+                f"id={reported_id or '-'} license={license_value or '-'} lastModified={last_modified}",
+            )
+        )
+
+        expected_license = HF_EXPECTED_LICENSES.get(model_id)
+        if expected_license:
+            checks.append(
+                SourceCheck(
+                    f"huggingface license: {model_id}",
+                    license_value == expected_license,
+                    f"expected={expected_license} actual={license_value or '-'}",
+                )
+            )
+    return checks
+
+
+def collect_checks(
+    paths: list[Path] | None = None,
+    check_links: bool = False,
+    timeout: float = 12.0,
+    metadata_path: Path | None = None,
+) -> list[SourceCheck]:
+    docs = paths or DEFAULT_DOCS
+    checks = check_required_markers()
+    checks.extend(check_metadata_snapshot(metadata_path or ROOT_DIR / "docs" / "huggingface-model-metadata.md"))
+    checks.extend(check_recommendation_report())
+    checks.extend(check_decision_card())
+    checks.extend(check_watchlist_policy())
+    checks.extend(check_watchlist_command_markers())
+    checks.extend(check_workflow_doc_markers())
+    urls = extract_urls(docs)
+    checks.append(SourceCheck("source urls found", bool(urls), f"{len(urls)} unique URLs"))
+    if check_links:
+        checks.extend(check_url(url, timeout=timeout) for url in urls)
+    return checks
+
+
+def collect_command_checks(
+    *,
+    check_links: bool = False,
+    check_key_links: bool = False,
+    check_representative_links: bool = False,
+    check_hf_metadata: bool = False,
+    write_hf_metadata_report: Path | None = None,
+    timeout: float = 12.0,
+) -> list[SourceCheck]:
+    hf_checks: list[SourceCheck] | None = None
+    if check_hf_metadata or write_hf_metadata_report:
+        hf_checks = collect_huggingface_metadata_checks(timeout=timeout)
+        if write_hf_metadata_report:
+            write_huggingface_metadata_report(write_hf_metadata_report, hf_checks)
+
+    checks = collect_checks(
+        check_links=check_links,
+        timeout=timeout,
+        metadata_path=write_hf_metadata_report,
+    )
+    checks.extend(collect_key_source_checks(check_links=check_key_links, timeout=timeout))
+    if check_representative_links:
+        checks.extend(collect_representative_link_checks(timeout=timeout))
+    if hf_checks is not None:
+        checks.extend(hf_checks)
+    return checks
+
+
+def representative_source_urls(urls: list[str]) -> list[str]:
+    preferred_hosts = ["huggingface.co", "github.com", "paddleocr.ai", "arxiv.org", "vercel.com"]
+    selected: list[str] = []
+    for host in preferred_hosts:
+        match = next((url for url in urls if host in url), None)
+        if match and match not in selected:
+            selected.append(match)
+    return selected
+
+
+def collect_representative_link_checks(timeout: float = 8.0) -> list[SourceCheck]:
+    urls = representative_source_urls(extract_urls(DEFAULT_DOCS))
+    checks = [SourceCheck("representative source urls selected", bool(urls), f"{len(urls)} URLs")]
+    checks.extend(check_url(url, timeout=timeout) for url in urls)
+    return checks
+
+
+def collect_key_source_checks(paths: list[Path] | None = None, timeout: float = 8.0, check_links: bool = False) -> list[SourceCheck]:
+    docs = paths or DEFAULT_DOCS
+    urls = set(extract_urls(docs))
+    checks: list[SourceCheck] = []
+    for name, url in KEY_SOURCE_URLS.items():
+        present = url in urls
+        checks.append(SourceCheck(f"key source listed: {name}", present, url if present else f"missing {url}"))
+        if present and check_links:
+            link_check = check_url(url, timeout=timeout)
+            checks.append(SourceCheck(f"key source reachable: {name}", link_check.ok, link_check.detail))
+    return checks
+
+
+def summarize(checks: list[SourceCheck]) -> dict[str, object]:
+    passed = sum(1 for check in checks if check.ok)
+    failed = len(checks) - passed
+    return {
+        "ready": failed == 0,
+        "counts": {"PASS": passed, "FAIL": failed},
+        "checks": [asdict(check) for check in checks],
+    }
+
+
+def build_huggingface_metadata_report(checks: list[SourceCheck], refreshed_at: date | None = None) -> str:
+    model_rows: dict[str, dict[str, str]] = {}
+    for check in checks:
+        if check.name.startswith("huggingface metadata: "):
+            model_id = check.name.removeprefix("huggingface metadata: ")
+            fields = parse_detail_fields(check.detail)
+            model_rows[model_id] = {
+                "model": model_id,
+                "status": "PASS" if check.ok else "FAIL",
+                "reportedId": fields.get("id", "-"),
+                "license": fields.get("license", "-"),
+                "lastModified": fields.get("lastModified", "-"),
+                "licenseCheck": "-",
+            }
+        elif check.name.startswith("huggingface license: "):
+            model_id = check.name.removeprefix("huggingface license: ")
+            row = model_rows.setdefault(
+                model_id,
+                {
+                    "model": model_id,
+                    "status": "-",
+                    "reportedId": "-",
+                    "license": "-",
+                    "lastModified": "-",
+                    "licenseCheck": "-",
+                },
+            )
+            row["licenseCheck"] = "PASS" if check.ok else f"FAIL ({check.detail})"
+
+    for model_id, fallback in HF_PAGE_ONLY_METADATA.items():
+        existing = model_rows.get(model_id)
+        if existing and existing.get("status") != "FAIL":
+            continue
+        license_value = str(fallback.get("license") or "-")
+        expected_license = HF_EXPECTED_LICENSES.get(model_id)
+        model_rows[model_id] = {
+            "model": model_id,
+            "status": "PASS",
+            "reportedId": model_id,
+            "license": license_value,
+            "lastModified": "page-only",
+            "licenseCheck": "PASS" if expected_license == license_value else "-",
+        }
+
+    lines = [
+        "# Hugging Face Model Metadata",
+        "",
+        f"Last refreshed: {format_report_date(refreshed_at)}.",
+        "",
+        "Generated by `scripts/check_research_sources.py --check-hf-metadata`.",
+        "",
+        "Rows marked `page-only` use verified public model-page evidence when live Hugging Face API/socket metadata is unavailable in the local environment.",
+        "",
+        "| Model | Status | Reported ID | License | License Check | Last Modified |",
+        "| --- | --- | --- | --- | --- | --- |",
+    ]
+    for row in sorted(model_rows.values(), key=lambda item: item["model"].lower()):
+        lines.append(
+            f"| {row['model']} | {row['status']} | {row['reportedId']} | {row['license']} | "
+            f"{row['licenseCheck']} | {row['lastModified']} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def write_huggingface_metadata_report(path: Path, checks: list[SourceCheck]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(build_huggingface_metadata_report(checks), encoding="utf-8")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Check research source coverage for the Arabic audio reader.")
+    parser.add_argument("--check-links", action="store_true", help="Fetch each source URL and require HTTP 2xx/3xx.")
+    parser.add_argument(
+        "--check-representative-links",
+        action="store_true",
+        help="Fetch one representative URL from the major source domains.",
+    )
+    parser.add_argument(
+        "--check-key-links",
+        action="store_true",
+        help="Fetch the exact key OCR/TTS/hosting source URLs used by the recommendation.",
+    )
+    parser.add_argument(
+        "--check-hf-metadata",
+        action="store_true",
+        help="Fetch Hugging Face model metadata for key source URLs and verify known licenses/private/disabled state.",
+    )
+    parser.add_argument(
+        "--write-hf-metadata-report",
+        type=Path,
+        help="Write a Markdown table of Hugging Face model IDs, licenses, and last-modified dates.",
+    )
+    parser.add_argument("--timeout", type=float, default=12.0, help="Per-link timeout in seconds.")
+    parser.add_argument("--json", action="store_true", help="Print JSON.")
+    args = parser.parse_args()
+
+    checks = collect_command_checks(
+        check_links=args.check_links,
+        check_key_links=args.check_key_links,
+        check_representative_links=args.check_representative_links,
+        check_hf_metadata=args.check_hf_metadata,
+        write_hf_metadata_report=args.write_hf_metadata_report,
+        timeout=args.timeout,
+    )
+    summary = summarize(checks)
+    if args.json:
+        print(json.dumps(summary, indent=2))
+    else:
+        for check in checks:
+            status = "PASS" if check.ok else "FAIL"
+            print(f"{status:<4} {check.name} {check.detail}")
+    if not summary["ready"]:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/check_test_environment.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+
+
+REQUIRED_MODULES = {
+    "pytest": "pytest",
+    "fastapi": "fastapi",
+    "httpx": "httpx",
+    "fitz": "PyMuPDF",
+}
+
+
+def missing_modules() -> list[str]:
+    return [package for module, package in REQUIRED_MODULES.items() if importlib.util.find_spec(module) is None]
+
+
+def main() -> int:
+    missing = missing_modules()
+    if not missing:
+        print("Test environment ready.")
+        return 0
+    print("Test environment is missing: " + ", ".join(missing))
+    print("Install project test dependencies with:")
+    print("python -m pip install -r requirements.txt")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/cleanup_outputs.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from app import main
+
+
+def main_cli() -> None:
+    parser = argparse.ArgumentParser(description="Delete old generated audio files and abandoned temp folders.")
+    parser.add_argument("--days", type=int, default=main.OUTPUT_RETENTION_DAYS, help="Delete files older than this many days.")
+    parser.add_argument("--max-files", type=int, default=main.OUTPUT_MAX_FILES, help="Keep only the newest N audio files.")
+    parser.add_argument("--output-dir", type=Path, default=main.OUTPUT_DIR, help="Directory containing generated audio files.")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of a compact summary.")
+    args = parser.parse_args()
+
+    result = main.cleanup_output_storage(args.output_dir, args.days, args.max_files)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        mb = result["bytes"] / 1024 / 1024
+        print(
+            f"Deleted {result['files']} audio file(s), {result['directories']} temp folder(s), "
+            f"freed {mb:.1f} MB."
+        )
+
+
+if __name__ == "__main__":
+    main_cli()

scripts/configure_vercel_worker.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from dataclasses import dataclass
+from typing import Sequence
+
+from scripts.verify_site import verify_site
+
+
+DEFAULT_SITE_URL = "https://arabic-translator-mu.vercel.app"
+DIRECT_CLOUD_ENV_KEYS = ["ENABLE_DIRECT_CLOUD_TTS", "HF_API_TOKEN", "HF_TTS_MODEL", "DEFAULT_VOICE_ID"]
+
+
+@dataclass
+class CommandResult:
+    command: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+def normalize_url(value: str) -> str:
+    return value.rstrip("/")
+
+
+def looks_like_hf_space(url: str) -> bool:
+    host = url.split("://", 1)[-1].split("/", 1)[0].lower()
+    return host == "hf.space" or host.endswith(".hf.space")
+
+
+def validate_worker_url(worker_url: str) -> str:
+    worker_url = normalize_url(worker_url.strip())
+    if not worker_url.startswith("https://"):
+        raise ValueError("WORKER_BASE_URL must start with https://")
+    if "localhost" in worker_url or "127.0.0.1" in worker_url:
+        raise ValueError("WORKER_BASE_URL must be public, not localhost")
+    if ".vercel.app" in worker_url:
+        raise ValueError("WORKER_BASE_URL must point at the worker, not the Vercel site")
+    if not looks_like_hf_space(worker_url):
+        raise ValueError("WORKER_BASE_URL should be a Hugging Face Space URL ending in .hf.space")
+    return worker_url
+
+
+def run_command(command: Sequence[str], input_text: str | None = None, check: bool = True) -> CommandResult:
+    completed = subprocess.run(
+        list(command),
+        input=input_text,
+        text=True,
+        capture_output=True,
+    )
+    result = CommandResult(
+        command=list(command),
+        returncode=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+    )
+    if check and completed.returncode != 0:
+        message = completed.stderr.strip() or completed.stdout.strip() or f"command failed with {completed.returncode}"
+        raise RuntimeError(f"{' '.join(command)} failed: {message}")
+    return result
+
+
+def remove_vercel_env(name: str, environment: str) -> CommandResult:
+    result = run_command(["vercel", "env", "rm", name, environment, "--yes"], check=False)
+    combined = f"{result.stdout}\n{result.stderr}"
+    if result.returncode != 0 and "env_not_found" not in combined and "was not found" not in combined:
+        message = result.stderr.strip() or result.stdout.strip() or f"command failed with {result.returncode}"
+        raise RuntimeError(f"vercel env rm {name} failed: {message}")
+    return result
+
+
+def add_vercel_env(name: str, value: str, environment: str) -> CommandResult:
+    return run_command(["vercel", "env", "add", name, environment], input_text=f"{value}\n")
+
+
+def configure_vercel_worker(
+    worker_url: str,
+    site_url: str = DEFAULT_SITE_URL,
+    code: str = "1234",
+    environment: str = "production",
+    redeploy: bool = True,
+    verify: bool = False,
+    timeout: float = 60,
+) -> dict[str, object]:
+    worker_url = validate_worker_url(worker_url)
+    site_url = normalize_url(site_url)
+    commands: list[CommandResult] = []
+
+    commands.append(remove_vercel_env("WORKER_BASE_URL", environment))
+    commands.append(add_vercel_env("WORKER_BASE_URL", worker_url, environment))
+    for key in DIRECT_CLOUD_ENV_KEYS:
+        commands.append(remove_vercel_env(key, environment))
+    if redeploy:
+        commands.append(run_command(["vercel", "deploy", "--prod", "--yes"]))
+
+    site_checks = None
+    if verify:
+        site_checks = [check.__dict__ for check in verify_site(site_url, code, worker_url, timeout=timeout)]
+
+    return {
+        "workerUrl": worker_url,
+        "siteUrl": site_url,
+        "environment": environment,
+        "redeployed": redeploy,
+        "verified": verify,
+        "commands": [
+            {
+                "command": result.command,
+                "returncode": result.returncode,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+            }
+            for result in commands
+        ],
+        "siteChecks": site_checks,
+        "nextCommand": (
+            f"python scripts\\prove_live_deployment.py {worker_url} --origin {site_url} "
+            f"--code {code} --smoke-ocr-engine arabic-max"
+        ),
+    }
+
+
+def main_with_args(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Set Vercel WORKER_BASE_URL, redeploy, and optionally verify the site.")
+    parser.add_argument("worker_url", help="Public Hugging Face Space worker URL, e.g. https://user-space.hf.space")
+    parser.add_argument("--site-url", default=DEFAULT_SITE_URL)
+    parser.add_argument("--code", default="1234")
+    parser.add_argument("--environment", default="production")
+    parser.add_argument("--no-redeploy", action="store_true")
+    parser.add_argument("--verify", action="store_true", help="Run scripts.verify_site after redeploy.")
+    parser.add_argument("--timeout", type=float, default=60)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    result = configure_vercel_worker(
+        args.worker_url,
+        site_url=args.site_url,
+        code=args.code,
+        environment=args.environment,
+        redeploy=not args.no_redeploy,
+        verify=args.verify,
+        timeout=args.timeout,
+    )
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Configured WORKER_BASE_URL={result['workerUrl']}")
+        if result["redeployed"]:
+            print("Redeployed Vercel production.")
+        print("Next:")
+        print(result["nextCommand"])
+    site_checks = result.get("siteChecks")
+    if site_checks is not None and not all(check["ok"] for check in site_checks):
+        return 1
+    return 0
+
+
+def main() -> int:
+    return main_with_args()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/deploy_hf_space.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_BUNDLE_DIR = ROOT_DIR / "outputs" / "huggingface-space"
+
+
+def load_env_file(path: Path) -> None:
+    if not path.exists():
+        return
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+def require_huggingface_hub():
+    try:
+        from huggingface_hub import HfApi, create_repo, upload_folder
+    except ImportError as exc:
+        raise SystemExit(
+            "huggingface_hub is not installed. Run: .\\.venv\\Scripts\\python.exe -m pip install huggingface_hub"
+        ) from exc
+    return HfApi, create_repo, upload_folder
+
+
+def run_export(bundle_dir: Path, force_export: bool) -> None:
+    if bundle_dir.exists() and not force_export:
+        return
+    command = [
+        sys.executable,
+        str(ROOT_DIR / "scripts" / "export_hf_space.py"),
+        "--out",
+        str(bundle_dir),
+    ]
+    if force_export:
+        command.append("--force")
+    subprocess.run(command, cwd=ROOT_DIR, check=True)
+
+
+def get_token(explicit_token: str | None) -> str:
+    load_env_file(ROOT_DIR / ".env")
+    token = explicit_token or os.getenv("HF_TOKEN") or os.getenv("HF_API_TOKEN") or os.getenv("HUGGINGFACE_API_TOKEN")
+    if not token:
+        raise SystemExit(
+            "Missing Hugging Face token. Set HF_TOKEN, HF_API_TOKEN, or HUGGINGFACE_API_TOKEN, "
+            "or pass --token. Create a write token at https://huggingface.co/settings/tokens."
+        )
+    return token
+
+
+def token_available(explicit_token: str | None = None) -> bool:
+    load_env_file(ROOT_DIR / ".env")
+    return bool(explicit_token or os.getenv("HF_TOKEN") or os.getenv("HF_API_TOKEN") or os.getenv("HUGGINGFACE_API_TOKEN"))
+
+
+def split_repo_id(repo_id: str) -> tuple[str, str]:
+    if "/" not in repo_id:
+        raise ValueError("Hugging Face Space repo id must look like username/space-name")
+    owner, space_name = repo_id.split("/", 1)
+    if not owner or not space_name:
+        raise ValueError("Hugging Face Space repo id must include both owner and space name")
+    return owner, space_name
+
+
+def worker_url_for_repo(repo_id: str) -> str:
+    owner, space_name = split_repo_id(repo_id)
+    return f"https://{owner}-{space_name}.hf.space".lower()
+
+
+def deploy_hf_space(
+    repo_id: str,
+    bundle_dir: Path = DEFAULT_BUNDLE_DIR,
+    token: str | None = None,
+    private: bool = False,
+    force_export: bool = False,
+    commit_message: str = "Deploy Arabic Audio Reader worker",
+) -> dict[str, object]:
+    bundle_dir = bundle_dir.resolve()
+    run_export(bundle_dir, force_export)
+    hf_token = get_token(token)
+    _hf_api, create_repo, upload_folder = require_huggingface_hub()
+
+    create_repo(
+        repo_id=repo_id,
+        repo_type="space",
+        space_sdk="docker",
+        private=private,
+        exist_ok=True,
+        token=hf_token,
+    )
+    commit_info = upload_folder(
+        repo_id=repo_id,
+        repo_type="space",
+        folder_path=str(bundle_dir),
+        path_in_repo=".",
+        commit_message=commit_message,
+        token=hf_token,
+    )
+    worker_url = worker_url_for_repo(repo_id)
+    return {
+        "repoId": repo_id,
+        "workerUrl": worker_url,
+        "bundleDir": str(bundle_dir),
+        "commitUrl": getattr(commit_info, "commit_url", None),
+        "nextCommand": (
+            f"python scripts\\deployment_handoff.py {worker_url} "
+            "--origin https://arabic-translator-mu.vercel.app --code 1234"
+        ),
+    }
+
+
+def main_with_args(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create or update the Hugging Face Docker Space worker.")
+    parser.add_argument(
+        "repo_id",
+        help="Hugging Face Space repo id, for example username/arabic-audio-reader-worker.",
+    )
+    parser.add_argument("--bundle-dir", type=Path, default=DEFAULT_BUNDLE_DIR)
+    parser.add_argument("--token", help="Hugging Face write token. Prefer setting HF_TOKEN instead.")
+    parser.add_argument("--private", action="store_true", help="Create the Space as private.")
+    parser.add_argument("--force-export", action="store_true", help="Rebuild the worker bundle before upload.")
+    parser.add_argument("--commit-message", default="Deploy Arabic Audio Reader worker")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    result = deploy_hf_space(
+        repo_id=args.repo_id,
+        bundle_dir=args.bundle_dir,
+        token=args.token,
+        private=args.private,
+        force_export=args.force_export,
+        commit_message=args.commit_message,
+    )
+    if args.json:
+        import json
+
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Uploaded worker bundle to https://huggingface.co/spaces/{args.repo_id}")
+        print(f"Worker URL: {worker_url}")
+        print("Next:")
+        print(result["nextCommand"])
+    return 0
+
+
+def main() -> int:
+    return main_with_args()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/deployment_handoff.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import argparse
+import json
+import secrets
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from scripts.next_deployment_step import deployment_url_warnings
+
+DEFAULT_OUT = ROOT_DIR / "outputs" / "deployment-handoff.md"
+
+
+def normalize_origin(value: str) -> str:
+    return value.rstrip("/")
+
+
+def generate_secret_key() -> str:
+    return secrets.token_urlsafe(48)
+
+
+@dataclass
+class DeploymentHandoff:
+    worker_url: str
+    vercel_origin: str
+    access_code: str
+    urls_look_real: bool
+    warnings: list[str]
+    recommended_build_args: dict[str, str]
+    maximum_quality_build_args: dict[str, str]
+    worker_secrets: dict[str, str]
+    vercel_env: dict[str, str]
+    commands: dict[str, str]
+    vercel_cli_commands: list[str]
+    vercel_cleanup_commands: list[str]
+    huggingface_cli_commands: list[str]
+
+
+def build_handoff(
+    worker_url: str,
+    vercel_origin: str,
+    access_code: str = "1234",
+    secret_key: str | None = None,
+) -> DeploymentHandoff:
+    worker_url = normalize_origin(worker_url)
+    vercel_origin = normalize_origin(vercel_origin)
+    secret_key = secret_key or generate_secret_key()
+    warnings = deployment_url_warnings(worker_url, vercel_origin)
+    urls_look_real = not warnings
+    recommended_build_args = {
+        "INSTALL_TAWKEED_OCR": "1",
+        "INSTALL_KATIB_OCR": "1",
+        "INSTALL_ARABIC_QWEN_OCR": "1",
+        "INSTALL_ARABIC_GLM_OCR": "1",
+        "INSTALL_BASEER_OCR": "1",
+        "INSTALL_SUPERTONIC": "1",
+    }
+    maximum_quality_build_args = {
+        **recommended_build_args,
+        "INSTALL_QARI_OCR": "1",
+        "INSTALL_PADDLEOCR_VL": "1",
+    }
+    worker_secrets = {
+        "ACCESS_CODE": access_code,
+        "SECRET_KEY": secret_key,
+        "CORS_ORIGINS": vercel_origin,
+        "COOKIE_SAMESITE": "none",
+        "COOKIE_SECURE": "1",
+        "OCR_ENGINE": "arabic-max",
+        "DEFAULT_VOICE_ID": "silma-local",
+        "OUTPUT_RETENTION_DAYS": "7",
+        "OUTPUT_MAX_FILES": "25",
+        "AUDIO_FORMAT": "mp3",
+        "MP3_BITRATE": "96k",
+        "SILMA_ENABLE_NORMALIZER": "0",
+        "SILMA_FORCE_TASHKEEL": "0",
+        "SILMA_NORMALIZE_NUMBERS": "0",
+    }
+    vercel_env = {
+        "ACCESS_CODE": access_code,
+        "SECRET_KEY": secret_key,
+        "WORKER_BASE_URL": worker_url,
+    }
+    commands = {
+        "localReadiness": "python scripts\\prove_local_readiness.py --refresh-research",
+        "refreshResearch": "python scripts\\refresh_research_evidence.py",
+        "licensePolicy": "python scripts\\research_watchlist.py --check-license-policy --json",
+        "researchSources": (
+            "python scripts\\check_research_sources.py "
+            "--check-hf-metadata --write-hf-metadata-report outputs\\hf-model-metadata.md"
+        ),
+        "exportWorker": "python scripts\\export_hf_space.py --force",
+        "prepareDeployment": (
+            f"python scripts\\prepare_live_deployment.py --worker-url {worker_url} "
+            f"--origin {vercel_origin} --code {access_code}"
+        ),
+        "validateEnv": (
+            "python scripts\\validate_deployment_env.py "
+            "--vercel-env outputs\\vercel-production.env "
+            "--worker-env outputs\\worker-secrets.env "
+            f"--worker-url {worker_url} --origin {vercel_origin}"
+        ),
+        "deploymentStatus": (
+            f"python scripts\\deployment_status.py --worker-url {worker_url} "
+            f"--origin {vercel_origin} --code {access_code}"
+        ),
+        "diagnoseVercelWorker": (
+            f"python scripts\\hosted_preflight.py {vercel_origin} "
+            f"--code {access_code} --worker-url {worker_url}"
+        ),
+        "configureVercelWorker": (
+            f"python scripts\\configure_vercel_worker.py {worker_url} "
+            f"--site-url {vercel_origin} --code {access_code} --verify"
+        ),
+        "verifyLive": (
+            f"python scripts\\prove_live_deployment.py {worker_url} "
+            f"--origin {vercel_origin} --code {access_code} "
+            "--smoke-ocr-engine arabic-max "
+            "--check-hf-metadata --hf-metadata-report outputs\\hf-model-metadata.md "
+            "--proof-out outputs\\live-deployment-proof.json"
+        ),
+        "finalAudit": (
+            "python scripts\\audit_goal_readiness.py "
+            "--worker-report outputs\\worker-verification.json "
+            "--site-report outputs\\site-verification.json"
+        ),
+    }
+    vercel_cli_commands = [
+        "npm i -g vercel",
+        "vercel login",
+        "vercel link --yes",
+        f'cmd /c "echo {access_code}| vercel env add ACCESS_CODE production"',
+        f'cmd /c "echo {secret_key}| vercel env add SECRET_KEY production"',
+        f'cmd /c "echo {worker_url}| vercel env add WORKER_BASE_URL production"',
+        f"python scripts\\configure_vercel_worker.py {worker_url} --site-url {vercel_origin} --code {access_code} --verify",
+        "vercel --prod --yes",
+    ]
+    vercel_cleanup_commands = [
+        "vercel env rm ENABLE_DIRECT_CLOUD_TTS production --yes",
+        "vercel env rm HF_API_TOKEN production --yes",
+        "vercel env rm HF_TTS_MODEL production --yes",
+        "vercel env rm DEFAULT_VOICE_ID production --yes",
+    ]
+    huggingface_cli_commands = [
+        "python -m pip install -U huggingface_hub",
+        "python scripts\\export_hf_space.py --force",
+        "python scripts\\deploy_hf_space.py <your-hf-username>/<your-space-name> --bundle-dir outputs/huggingface-space --json",
+    ]
+    return DeploymentHandoff(
+        worker_url=worker_url,
+        vercel_origin=vercel_origin,
+        access_code=access_code,
+        urls_look_real=urls_look_real,
+        warnings=warnings,
+        recommended_build_args=recommended_build_args,
+        maximum_quality_build_args=maximum_quality_build_args,
+        worker_secrets=worker_secrets,
+        vercel_env=vercel_env,
+        commands=commands,
+        vercel_cli_commands=vercel_cli_commands,
+        vercel_cleanup_commands=vercel_cleanup_commands,
+        huggingface_cli_commands=huggingface_cli_commands,
+    )
+
+
+def format_env_table(values: dict[str, str]) -> str:
+    lines = ["| Name | Value |", "| --- | --- |"]
+    lines.extend(f"| `{key}` | `{value}` |" for key, value in values.items())
+    return "\n".join(lines)
+
+
+def format_key_value_block(values: dict[str, str]) -> str:
+    return "\n".join(f"{key}={value}" for key, value in values.items())
+
+
+def write_markdown(path: Path, handoff: DeploymentHandoff) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "\n".join(
+            [
+                "# Arabic Audio Reader Deployment Handoff",
+                "",
+                "Use this after the Hugging Face worker URL and Vercel production URL exist.",
+                "",
+                "## URLs",
+                "",
+                f"- Worker: {handoff.worker_url}",
+                f"- Vercel site: {handoff.vercel_origin}",
+                f"- URLs look real: {'yes' if handoff.urls_look_real else 'no'}",
+                "",
+                *(
+                    [
+                        "## URL Warnings",
+                        "",
+                        *[f"- {warning}" for warning in handoff.warnings],
+                        "",
+                        "Replace placeholder/local/test URLs before running live proof. The final audit will not treat placeholder reports as completed deployment evidence.",
+                        "",
+                    ]
+                    if handoff.warnings
+                    else []
+                ),
+                "## Hugging Face Space Secrets",
+                "",
+                format_env_table(handoff.worker_secrets),
+                "",
+                "Copy/paste secret values:",
+                "",
+                "```text",
+                format_key_value_block(handoff.worker_secrets),
+                "```",
+                "",
+                "## Safety Checklist",
+                "",
+                "- Set the same `ACCESS_CODE` and `SECRET_KEY` on both Hugging Face and Vercel.",
+                "- Set Hugging Face `CORS_ORIGINS` to the exact Vercel production origin shown above.",
+                "- Set Vercel `WORKER_BASE_URL` to the exact Hugging Face worker URL shown above.",
+                "- After both deployments finish, run the Vercel worker diagnostic command below before uploading a large PDF. It must show `site worker reachable from vercel` and `site worker CORS ready`.",
+                "- Remove Vercel's temporary direct Hugging Face TTS fallback variables for production: `ENABLE_DIRECT_CLOUD_TTS`, `HF_API_TOKEN`, `HF_TTS_MODEL`, and `DEFAULT_VOICE_ID`.",
+                "- Keep `OCR_ENGINE=arabic-max` for scanned Arabic books unless a 5-page benchmark says another engine wins.",
+                "- Do not commit this handoff; it contains the deployment `SECRET_KEY`.",
+                "",
+                "## Hugging Face Docker Build Args",
+                "",
+                "Balanced Arabic OCR worker for the first strong-worker deployment:",
+                "",
+                format_env_table(handoff.recommended_build_args),
+                "",
+                "Copy/paste balanced build args:",
+                "",
+                "```text",
+                format_key_value_block(handoff.recommended_build_args),
+                "```",
+                "",
+                "Maximum quality worker for a GPU or larger paid/owned worker after a 5-page benchmark proves the heavier models help:",
+                "",
+                format_env_table(handoff.maximum_quality_build_args),
+                "",
+                "Copy/paste maximum-quality build args:",
+                "",
+                "```text",
+                format_key_value_block(handoff.maximum_quality_build_args),
+                "```",
+                "",
+                "## Vercel Environment Variables",
+                "",
+                format_env_table(handoff.vercel_env),
+                "",
+                "Copy/paste Vercel values:",
+                "",
+                "```text",
+                format_key_value_block(handoff.vercel_env),
+                "```",
+                "",
+                "## Deploy Worker With Hugging Face CLI",
+                "",
+                "Create a Hugging Face Space with SDK **Docker**, then run these from the repo root. Replace `<your-hf-username>/<your-space-name>` with the Space repo id:",
+                "",
+                "```powershell",
+                *handoff.huggingface_cli_commands,
+                "```",
+                "",
+                "Set the Hugging Face Space secrets and Docker build args from the tables above in the Space settings before the final smoke test.",
+                "The `SECRET_KEY` value in this handoff is generated for this deployment; keep it private and do not commit the handoff output.",
+                "",
+                "## Deploy Vercel Site With CLI",
+                "",
+                "Run these from the repo root after the worker URL is known:",
+                "",
+                "```powershell",
+                *handoff.vercel_cli_commands,
+                "```",
+                "",
+                "If you previously tested direct Hugging Face cloud TTS on Vercel, remove those temporary variables before or after setting `WORKER_BASE_URL`. It is normal if a remove command says the variable does not exist:",
+                "",
+                "```powershell",
+                *handoff.vercel_cleanup_commands,
+                "vercel --prod --yes",
+                "```",
+                "",
+                "## Commands",
+                "",
+                "Run these from the repo root:",
+                "",
+                "```powershell",
+                handoff.commands["localReadiness"],
+                handoff.commands["refreshResearch"],
+                handoff.commands["licensePolicy"],
+                handoff.commands["researchSources"],
+                handoff.commands["exportWorker"],
+                handoff.commands["prepareDeployment"],
+                handoff.commands["validateEnv"],
+                handoff.commands["deploymentStatus"],
+                handoff.commands["diagnoseVercelWorker"],
+                handoff.commands["verifyLive"],
+                handoff.commands["finalAudit"],
+                "```",
+                "",
+                "The hosted preflight command checks the hosted site's `/api/worker-diagnostics` endpoint and writes `outputs\\hosted-preflight.json`. If it says `cors-blocked`, set Hugging Face `CORS_ORIGINS` to the exact Vercel production URL, keep `COOKIE_SAMESITE=none` and `COOKIE_SECURE=1`, restart the Space, redeploy Vercel, and run the preflight again.",
+                "",
+                "The goal audit is complete only after `outputs\\site-verification.json` proves the Vercel shell login, worker routing, large-PDF readiness, hosted provider limits, recommended stack, disabled direct cloud fallback, worker diagnostics reachability, and worker CORS readiness; `outputs\\worker-verification.json` proves the worker recommended stack plus embedded-text and scanned-OCR smoke jobs, usable extracted text, scanned OCR extraction, audio URLs, download URLs, audio bytes, download bytes, and audio file signatures; and `outputs\\live-deployment-proof.json` records `complete: true`.",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Create a deployment handoff file with exact worker/Vercel settings and proof commands.")
+    parser.add_argument("worker_url", help="Worker URL, for example https://your-space.hf.space")
+    parser.add_argument("--origin", required=True, help="Vercel production origin, for example https://your-app.vercel.app")
+    parser.add_argument("--code", default="1234", help="Access code for the site and worker.")
+    parser.add_argument("--secret-key", help="Optional fixed cookie-signing secret. Omit to generate a random deployment secret.")
+    parser.add_argument("--out", type=Path, default=DEFAULT_OUT, help="Markdown handoff destination.")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of a short summary.")
+    args = parser.parse_args()
+
+    handoff = build_handoff(args.worker_url, args.origin, args.code, args.secret_key)
+    write_markdown(args.out, handoff)
+    result = {"out": str(args.out), **asdict(handoff)}
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"Wrote deployment handoff to {args.out}")
+        print(handoff.commands["verifyLive"])
+
+
+if __name__ == "__main__":
+    main()

scripts/deployment_status.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from scripts.next_deployment_step import (
+    LIVE_PROOF,
+    LOCAL_REPORT,
+    SITE_REPORT,
+    WORKER_REPORT,
+    choose_next_step,
+    deployment_urls_look_real,
+    load_json,
+    local_ready,
+)
+
+
+@dataclass
+class ReportStatus:
+    path: str
+    exists: bool
+    valid_json: bool
+    summary: str
+
+
+@dataclass
+class DeploymentStatus:
+    ready_for_live_urls: bool
+    live_urls_look_real: bool
+    live_complete: bool
+    reports_are_real_live_evidence: bool
+    local_report: ReportStatus
+    site_report: ReportStatus
+    worker_report: ReportStatus
+    live_proof: ReportStatus
+    missing_site_checks: list[str]
+    missing_worker_checks: list[str]
+    next_status: str
+    next_title: str
+    next_detail: str
+    next_command: str
+
+
+def _report_status(path: Path) -> ReportStatus:
+    payload = load_json(path)
+    if payload is None:
+        return ReportStatus(str(path), path.exists(), False, "missing or invalid JSON")
+    return ReportStatus(str(path), True, True, summarize_payload(path, payload))
+
+
+def _list_checks_ok(payload: Any, names: set[str]) -> bool:
+    if not isinstance(payload, list):
+        return False
+    checks = {str(item.get("name", "")): bool(item.get("ok")) for item in payload if isinstance(item, dict)}
+    return all(checks.get(name) is True for name in names)
+
+
+def _missing_checks(payload: Any, names: set[str]) -> list[str]:
+    if not isinstance(payload, list):
+        return sorted(names)
+    checks = {str(item.get("name", "")): bool(item.get("ok")) for item in payload if isinstance(item, dict)}
+    return sorted(name for name in names if checks.get(name) is not True)
+
+
+def _looks_like_test_artifact(payload: Any) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    text = json.dumps(payload, ensure_ascii=False).lower()
+    return "pytest-" in text or "your-space.hf.space" in text or "your-vercel-app.vercel.app" in text
+
+
+def _url_evidence_matches(live_payload: Any, worker_url: str | None, vercel_origin: str | None) -> bool:
+    if not isinstance(live_payload, dict):
+        return False
+    proof_worker = str(live_payload.get("workerUrl") or "").rstrip("/")
+    proof_origin = str(live_payload.get("origin") or "").rstrip("/")
+    expected_worker = (worker_url or proof_worker).rstrip("/")
+    expected_origin = (vercel_origin or proof_origin).rstrip("/")
+    if not deployment_urls_look_real(expected_worker, expected_origin):
+        return False
+    return proof_worker == expected_worker and proof_origin == expected_origin
+
+
+def summarize_payload(path: Path, payload: Any) -> str:
+    if isinstance(payload, dict):
+        if "ready" in payload or "complete" in payload:
+            return f"ready={payload.get('ready')} complete={payload.get('complete')}"
+        if "counts" in payload:
+            return f"counts={payload.get('counts')}"
+        return f"object keys={','.join(sorted(str(key) for key in payload.keys())[:6])}"
+    if isinstance(payload, list):
+        passed = sum(1 for item in payload if isinstance(item, dict) and item.get("ok") is True)
+        failed = sum(1 for item in payload if isinstance(item, dict) and item.get("ok") is False)
+        return f"checks={len(payload)} pass={passed} fail={failed}"
+    return type(payload).__name__
+
+
+def build_status(
+    worker_url: str | None = None,
+    vercel_origin: str | None = None,
+    code: str = "1234",
+    local_report: Path = LOCAL_REPORT,
+    site_report: Path = SITE_REPORT,
+    worker_report: Path = WORKER_REPORT,
+    live_proof: Path = LIVE_PROOF,
+) -> DeploymentStatus:
+    site_required = {
+        "site login",
+        "site platform vercel",
+        "site worker configured",
+        "site large PDF ready",
+        "site production worker ready",
+        "site hosted limits documented",
+        "site recommended stack documented",
+        "site direct cloud fallback disabled",
+        "site worker diagnostics endpoint",
+        "site worker reachable from vercel",
+        "site worker CORS ready",
+    }
+    worker_required = {
+        "recommended stack documented",
+        "smoke upload accepted",
+        "smoke job complete",
+        "smoke usable text",
+        "smoke audio url",
+        "smoke download url",
+        "smoke audio bytes",
+        "smoke audio file signature",
+        "smoke download bytes",
+        "smoke download file signature",
+        "scanned smoke upload accepted",
+        "scanned smoke job complete",
+        "scanned smoke usable text",
+        "scanned smoke OCR extraction",
+        "scanned smoke audio url",
+        "scanned smoke download url",
+        "scanned smoke audio bytes",
+        "scanned smoke audio file signature",
+        "scanned smoke download bytes",
+        "scanned smoke download file signature",
+    }
+    live_payload = load_json(live_proof)
+    site_payload = load_json(site_report)
+    worker_payload = load_json(worker_report)
+    missing_site_checks = _missing_checks(site_payload, site_required)
+    missing_worker_checks = _missing_checks(worker_payload, worker_required)
+    live_complete = isinstance(live_payload, dict) and bool(live_payload.get("complete"))
+    live_urls_look_real = deployment_urls_look_real(worker_url, vercel_origin)
+    reports_are_real_live_evidence = bool(
+        live_complete
+        and not missing_site_checks
+        and not missing_worker_checks
+        and not _looks_like_test_artifact(live_payload)
+        and _url_evidence_matches(live_payload, worker_url, vercel_origin)
+    )
+    next_step = choose_next_step(
+        worker_url=worker_url,
+        vercel_origin=vercel_origin,
+        code=code,
+        local_report=local_report,
+        site_report=site_report,
+        worker_report=worker_report,
+        live_proof=live_proof,
+    )
+    if live_complete and not reports_are_real_live_evidence:
+        next_status = "live-proof"
+        next_title = "Re-run live proof against real deployed URLs"
+        next_detail = (
+            "A complete live proof file exists, but it does not look like trustworthy live evidence. "
+            "Re-run the proof after replacing placeholder/test URLs with the real Hugging Face worker and Vercel site."
+        )
+        next_command = (
+            f"python scripts\\prove_live_deployment.py {worker_url or 'https://your-space.hf.space'} "
+            f"--origin {vercel_origin or 'https://your-vercel-app.vercel.app'} --code {code} "
+            "--smoke-ocr-engine arabic-max "
+            "--check-hf-metadata --hf-metadata-report outputs\\hf-model-metadata.md "
+            "--proof-out outputs\\live-deployment-proof.json"
+        )
+    else:
+        next_status = next_step.status
+        next_title = next_step.title
+        next_detail = next_step.detail
+        next_command = next_step.command
+    return DeploymentStatus(
+        ready_for_live_urls=local_ready(local_report) and live_urls_look_real,
+        live_urls_look_real=live_urls_look_real,
+        live_complete=live_complete,
+        reports_are_real_live_evidence=reports_are_real_live_evidence,
+        local_report=_report_status(local_report),
+        site_report=_report_status(site_report),
+        worker_report=_report_status(worker_report),
+        live_proof=_report_status(live_proof),
+        missing_site_checks=missing_site_checks,
+        missing_worker_checks=missing_worker_checks,
+        next_status=next_status,
+        next_title=next_title,
+        next_detail=next_detail,
+        next_command=next_command,
+    )
+
+
+def print_status(status: DeploymentStatus) -> None:
+    print(f"Ready for live URLs: {status.ready_for_live_urls}")
+    print(f"Live URLs look real: {status.live_urls_look_real}")
+    print(f"Live proof complete: {status.live_complete}")
+    print(f"Reports are real live evidence: {status.reports_are_real_live_evidence}")
+    print()
+    for label, report in [
+        ("Local", status.local_report),
+        ("Site", status.site_report),
+        ("Worker", status.worker_report),
+        ("Live proof", status.live_proof),
+    ]:
+        print(f"{label}: {report.summary} ({report.path})")
+    if status.missing_site_checks:
+        print()
+        print("Missing site proof checks:")
+        for name in status.missing_site_checks:
+            print(f"- {name}")
+    if status.missing_worker_checks:
+        print()
+        print("Missing worker proof checks:")
+        for name in status.missing_worker_checks:
+            print(f"- {name}")
+    print()
+    print(status.next_title)
+    print(status.next_detail)
+    print()
+    print(status.next_command)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Show the current deployment proof status and next command.")
+    parser.add_argument("--worker-url", help="Live worker URL, for example https://your-space.hf.space")
+    parser.add_argument("--origin", help="Live Vercel origin, for example https://your-app.vercel.app")
+    parser.add_argument("--code", default="1234", help="Access code for live verification.")
+    parser.add_argument("--json", action="store_true", help="Print JSON.")
+    args = parser.parse_args()
+
+    status = build_status(worker_url=args.worker_url, vercel_origin=args.origin, code=args.code)
+    if args.json:
+        print(json.dumps(asdict(status), ensure_ascii=False, indent=2))
+    else:
+        print_status(status)
+
+
+if __name__ == "__main__":
+    main()

scripts/dry_run_pdf.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import argparse
+from contextlib import contextmanager
+import json
+import sys
+from pathlib import Path
+from typing import Iterator
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from app import main
+from scripts.benchmark_ocr import recommendation_for_extraction
+
+
+OCR_ENV_KEYS = {
+    "OCR_ENGINE",
+    "OCR_RENDER_ZOOM",
+    "EASYOCR_RENDER_ZOOM",
+    "QARI_OCR_RENDER_ZOOM",
+    "TAWKEED_OCR_RENDER_ZOOM",
+    "KATIB_OCR_RENDER_ZOOM",
+    "ARABIC_QWEN_OCR_RENDER_ZOOM",
+    "ARABIC_GLM_OCR_RENDER_ZOOM",
+    "BASEER_OCR_RENDER_ZOOM",
+    "PADDLEOCR_RENDER_ZOOM",
+    "PADDLEOCR_VL_RENDER_ZOOM",
+    "SURYA_RENDER_ZOOM",
+    "TESSERACT_PSM",
+}
+
+
+def load_ocr_env_file(path: Path | None) -> dict[str, str]:
+    if path is None:
+        return {}
+    if not path.exists():
+        raise FileNotFoundError(f"OCR env file not found: {path}")
+    values: dict[str, str] = {}
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if key in OCR_ENV_KEYS:
+            values[key] = value.strip().strip('"').strip("'")
+    return values
+
+
+@contextmanager
+def temporary_ocr_settings(
+    ocr_engine: str | None = None,
+    ocr_render_zoom: str | None = None,
+    easyocr_render_zoom: str | None = None,
+    qari_ocr_render_zoom: str | None = None,
+    tawkeed_ocr_render_zoom: str | None = None,
+    katib_ocr_render_zoom: str | None = None,
+    arabic_qwen_ocr_render_zoom: str | None = None,
+    arabic_glm_ocr_render_zoom: str | None = None,
+    baseer_ocr_render_zoom: str | None = None,
+    paddleocr_render_zoom: str | None = None,
+    paddleocr_vl_render_zoom: str | None = None,
+    surya_render_zoom: str | None = None,
+    tesseract_psm: str | None = None,
+    from_extraction: str | None = None,
+    env_file: Path | None = None,
+) -> Iterator[None]:
+    file_env = load_ocr_env_file(env_file)
+    extraction_env: dict[str, str] = {}
+    if from_extraction:
+        recommendation = recommendation_for_extraction(from_extraction)
+        extraction_env = recommendation.get("env", {}) if recommendation else {}
+    ocr_engine = ocr_engine or extraction_env.get("OCR_ENGINE") or file_env.get("OCR_ENGINE")
+    ocr_render_zoom = ocr_render_zoom or extraction_env.get("OCR_RENDER_ZOOM") or file_env.get("OCR_RENDER_ZOOM")
+    easyocr_render_zoom = easyocr_render_zoom or extraction_env.get("EASYOCR_RENDER_ZOOM") or file_env.get("EASYOCR_RENDER_ZOOM")
+    qari_ocr_render_zoom = qari_ocr_render_zoom or extraction_env.get("QARI_OCR_RENDER_ZOOM") or file_env.get("QARI_OCR_RENDER_ZOOM")
+    tawkeed_ocr_render_zoom = (
+        tawkeed_ocr_render_zoom
+        or extraction_env.get("TAWKEED_OCR_RENDER_ZOOM")
+        or file_env.get("TAWKEED_OCR_RENDER_ZOOM")
+    )
+    katib_ocr_render_zoom = (
+        katib_ocr_render_zoom or extraction_env.get("KATIB_OCR_RENDER_ZOOM") or file_env.get("KATIB_OCR_RENDER_ZOOM")
+    )
+    arabic_qwen_ocr_render_zoom = (
+        arabic_qwen_ocr_render_zoom
+        or extraction_env.get("ARABIC_QWEN_OCR_RENDER_ZOOM")
+        or file_env.get("ARABIC_QWEN_OCR_RENDER_ZOOM")
+    )
+    arabic_glm_ocr_render_zoom = (
+        arabic_glm_ocr_render_zoom
+        or extraction_env.get("ARABIC_GLM_OCR_RENDER_ZOOM")
+        or file_env.get("ARABIC_GLM_OCR_RENDER_ZOOM")
+    )
+    baseer_ocr_render_zoom = (
+        baseer_ocr_render_zoom or extraction_env.get("BASEER_OCR_RENDER_ZOOM") or file_env.get("BASEER_OCR_RENDER_ZOOM")
+    )
+    paddleocr_render_zoom = paddleocr_render_zoom or extraction_env.get("PADDLEOCR_RENDER_ZOOM") or file_env.get("PADDLEOCR_RENDER_ZOOM")
+    paddleocr_vl_render_zoom = (
+        paddleocr_vl_render_zoom
+        or extraction_env.get("PADDLEOCR_VL_RENDER_ZOOM")
+        or file_env.get("PADDLEOCR_VL_RENDER_ZOOM")
+    )
+    surya_render_zoom = surya_render_zoom or extraction_env.get("SURYA_RENDER_ZOOM") or file_env.get("SURYA_RENDER_ZOOM")
+    tesseract_psm = tesseract_psm or extraction_env.get("TESSERACT_PSM") or file_env.get("TESSERACT_PSM")
+
+    previous_engine = main.OCR_ENGINE
+    previous_env = {
+        "OCR_RENDER_ZOOM": main.os.getenv("OCR_RENDER_ZOOM"),
+        "EASYOCR_RENDER_ZOOM": main.os.getenv("EASYOCR_RENDER_ZOOM"),
+        "QARI_OCR_RENDER_ZOOM": main.os.getenv("QARI_OCR_RENDER_ZOOM"),
+        "TAWKEED_OCR_RENDER_ZOOM": main.os.getenv("TAWKEED_OCR_RENDER_ZOOM"),
+        "KATIB_OCR_RENDER_ZOOM": main.os.getenv("KATIB_OCR_RENDER_ZOOM"),
+        "ARABIC_QWEN_OCR_RENDER_ZOOM": main.os.getenv("ARABIC_QWEN_OCR_RENDER_ZOOM"),
+        "ARABIC_GLM_OCR_RENDER_ZOOM": main.os.getenv("ARABIC_GLM_OCR_RENDER_ZOOM"),
+        "BASEER_OCR_RENDER_ZOOM": main.os.getenv("BASEER_OCR_RENDER_ZOOM"),
+        "PADDLEOCR_RENDER_ZOOM": main.os.getenv("PADDLEOCR_RENDER_ZOOM"),
+        "PADDLEOCR_VL_RENDER_ZOOM": main.os.getenv("PADDLEOCR_VL_RENDER_ZOOM"),
+        "SURYA_RENDER_ZOOM": main.os.getenv("SURYA_RENDER_ZOOM"),
+        "TESSERACT_PSM": main.os.getenv("TESSERACT_PSM"),
+    }
+    try:
+        if ocr_engine is not None:
+            main.OCR_ENGINE = main.normalize_ocr_engine(ocr_engine)
+        for key, value in {
+            "OCR_RENDER_ZOOM": ocr_render_zoom,
+            "EASYOCR_RENDER_ZOOM": easyocr_render_zoom,
+            "QARI_OCR_RENDER_ZOOM": qari_ocr_render_zoom,
+            "TAWKEED_OCR_RENDER_ZOOM": tawkeed_ocr_render_zoom,
+            "KATIB_OCR_RENDER_ZOOM": katib_ocr_render_zoom,
+            "ARABIC_QWEN_OCR_RENDER_ZOOM": arabic_qwen_ocr_render_zoom,
+            "ARABIC_GLM_OCR_RENDER_ZOOM": arabic_glm_ocr_render_zoom,
+            "BASEER_OCR_RENDER_ZOOM": baseer_ocr_render_zoom,
+            "PADDLEOCR_RENDER_ZOOM": paddleocr_render_zoom,
+            "PADDLEOCR_VL_RENDER_ZOOM": paddleocr_vl_render_zoom,
+            "SURYA_RENDER_ZOOM": surya_render_zoom,
+            "TESSERACT_PSM": tesseract_psm,
+        }.items():
+            if value is not None:
+                main.os.environ[key] = value
+        yield
+    finally:
+        main.OCR_ENGINE = previous_engine
+        for key, value in previous_env.items():
+            if value is None:
+                main.os.environ.pop(key, None)
+            else:
+                main.os.environ[key] = value
+
+
+def dry_run_pdf(
+    pdf_path: Path,
+    chunk_size: int,
+    ocr_engine: str | None = None,
+    ocr_render_zoom: str | None = None,
+    easyocr_render_zoom: str | None = None,
+    qari_ocr_render_zoom: str | None = None,
+    tawkeed_ocr_render_zoom: str | None = None,
+    katib_ocr_render_zoom: str | None = None,
+    arabic_qwen_ocr_render_zoom: str | None = None,
+    arabic_glm_ocr_render_zoom: str | None = None,
+    baseer_ocr_render_zoom: str | None = None,
+    paddleocr_render_zoom: str | None = None,
+    paddleocr_vl_render_zoom: str | None = None,
+    surya_render_zoom: str | None = None,
+    tesseract_psm: str | None = None,
+    from_extraction: str | None = None,
+    env_file: Path | None = None,
+    include_speech_text: bool = False,
+    speech_sample_chars: int | None = 1200,
+) -> dict[str, object]:
+    if not pdf_path.exists():
+        raise FileNotFoundError(f"PDF not found: {pdf_path}")
+    if pdf_path.suffix.lower() != ".pdf":
+        raise ValueError("Dry run input must be a PDF file.")
+
+    with temporary_ocr_settings(
+        ocr_engine=ocr_engine,
+        ocr_render_zoom=ocr_render_zoom,
+        easyocr_render_zoom=easyocr_render_zoom,
+        qari_ocr_render_zoom=qari_ocr_render_zoom,
+        tawkeed_ocr_render_zoom=tawkeed_ocr_render_zoom,
+        katib_ocr_render_zoom=katib_ocr_render_zoom,
+        arabic_qwen_ocr_render_zoom=arabic_qwen_ocr_render_zoom,
+        arabic_glm_ocr_render_zoom=arabic_glm_ocr_render_zoom,
+        baseer_ocr_render_zoom=baseer_ocr_render_zoom,
+        paddleocr_render_zoom=paddleocr_render_zoom,
+        paddleocr_vl_render_zoom=paddleocr_vl_render_zoom,
+        surya_render_zoom=surya_render_zoom,
+        tesseract_psm=tesseract_psm,
+        from_extraction=from_extraction,
+        env_file=env_file,
+    ):
+        job = main.Job(id="dry-run", filename=pdf_path.name, ocr_engine=ocr_engine or main.OCR_ENGINE)
+        text = main.extract_pdf_text(pdf_path, job)
+    speech_text = main.prepare_text_for_speech(text)
+    chunks = main.chunk_text(speech_text, chunk_size=chunk_size)
+    quality = main.assess_text_quality(text, speech_text)
+    placeholder_count = speech_text.count("?") + speech_text.count("\ufffd")
+    speech_sample = speech_text
+    if speech_sample_chars is not None and speech_sample_chars > 0:
+        speech_sample = speech_text[:speech_sample_chars].rstrip()
+    result: dict[str, object] = {
+        "pdf": str(pdf_path),
+        "pages": job.pages,
+        "characters": len(text),
+        "speechCharacters": len(speech_text),
+        "arabicWords": quality["arabicWords"],
+        "placeholderCharacters": placeholder_count,
+        "placeholderRatio": quality["placeholderRatio"],
+        "singleArabicWords": int(quality["metrics"]["singleArabicWords"]),
+        "singleArabicWordRatio": quality["metrics"]["singleArabicWordRatio"],
+        "fragmentLines": int(quality["metrics"]["fragmentLines"]),
+        "fragmentLineRatio": quality["metrics"]["fragmentLineRatio"],
+        "quality": quality["quality"],
+        "qualityScore": quality["score"],
+        "qualityReasons": quality["reasons"],
+        "extraction": job.extraction,
+        "ocrEngine": job.ocr_engine,
+        "chunks": len(chunks),
+        "chunkSize": chunk_size,
+        "largestChunkCharacters": max((len(chunk) for chunk in chunks), default=0),
+        "textPreview": text[:160],
+        "speechPreview": speech_text[:160],
+        "speechSampleText": speech_sample,
+        "readyForTts": bool(chunks and quality["readyForTts"]),
+        "ttsWasCalled": False,
+    }
+    if include_speech_text:
+        result["speechText"] = speech_text
+    return result
+
+
+def main_cli() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(description="Dry-run Arabic PDF extraction without calling TTS.")
+    parser.add_argument("pdf", type=Path, help="Path to the PDF to test")
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=main.CLOUD_TTS_MAX_CHARS,
+        help="Maximum characters per simulated TTS chunk",
+    )
+    parser.add_argument("--ocr-engine", choices=sorted(main.OCR_ENGINE_CHOICES), help="OCR engine to test.")
+    parser.add_argument("--ocr-render-zoom", help="Render zoom for Tesseract or shared OCR fallback.")
+    parser.add_argument("--easyocr-render-zoom", help="Render zoom for EasyOCR.")
+    parser.add_argument("--qari-ocr-render-zoom", help="Render zoom for QARI-OCR.")
+    parser.add_argument("--tawkeed-ocr-render-zoom", help="Render zoom for Tawkeed Arabic OCR.")
+    parser.add_argument("--katib-ocr-render-zoom", help="Render zoom for KATIB Arabic OCR.")
+    parser.add_argument("--arabic-qwen-ocr-render-zoom", help="Render zoom for Arabic-Qwen3.5 OCR.")
+    parser.add_argument("--arabic-glm-ocr-render-zoom", help="Render zoom for Arabic-GLM OCR.")
+    parser.add_argument("--baseer-ocr-render-zoom", help="Render zoom for Baseer Arabic OCR.")
+    parser.add_argument("--paddleocr-render-zoom", help="Render zoom for PaddleOCR.")
+    parser.add_argument("--paddleocr-vl-render-zoom", help="Render zoom for PaddleOCR-VL.")
+    parser.add_argument("--surya-render-zoom", help="Render zoom for Surya OCR.")
+    parser.add_argument("--tesseract-psm", help="Tesseract page segmentation mode, for example 4 or 6.")
+    parser.add_argument(
+        "--from-extraction",
+        help="Apply settings from a benchmark extraction label, for example best:tesseract@2x-psm4.",
+    )
+    parser.add_argument("--env-file", type=Path, help="Load OCR settings from a generated OCR .env snippet.")
+    parser.add_argument(
+        "--include-speech-text",
+        action="store_true",
+        help="Include the full cleaned speech text in JSON output.",
+    )
+    parser.add_argument(
+        "--speech-sample-chars",
+        type=int,
+        default=1200,
+        help="Maximum cleaned speech characters to include as speechSampleText. Use 0 for no limit.",
+    )
+    args = parser.parse_args()
+    result = dry_run_pdf(
+        args.pdf,
+        args.chunk_size,
+        ocr_engine=args.ocr_engine,
+        ocr_render_zoom=args.ocr_render_zoom,
+        easyocr_render_zoom=args.easyocr_render_zoom,
+        qari_ocr_render_zoom=args.qari_ocr_render_zoom,
+        tawkeed_ocr_render_zoom=args.tawkeed_ocr_render_zoom,
+        katib_ocr_render_zoom=args.katib_ocr_render_zoom,
+        arabic_qwen_ocr_render_zoom=args.arabic_qwen_ocr_render_zoom,
+        arabic_glm_ocr_render_zoom=args.arabic_glm_ocr_render_zoom,
+        baseer_ocr_render_zoom=args.baseer_ocr_render_zoom,
+        paddleocr_render_zoom=args.paddleocr_render_zoom,
+        paddleocr_vl_render_zoom=args.paddleocr_vl_render_zoom,
+        surya_render_zoom=args.surya_render_zoom,
+        tesseract_psm=args.tesseract_psm,
+        from_extraction=args.from_extraction,
+        env_file=args.env_file,
+        include_speech_text=args.include_speech_text,
+        speech_sample_chars=args.speech_sample_chars,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    if not result["readyForTts"]:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main_cli()

scripts/easyocr_extract.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(description="Extract Arabic text from page images with EasyOCR.")
+    parser.add_argument("--image-dir", required=True, type=Path)
+    parser.add_argument("--out", required=True, type=Path)
+    args = parser.parse_args()
+
+    image_paths = sorted(args.image_dir.glob("*.png"))
+    total = max(len(image_paths), 1)
+    print(f"ARABIC_READER_PROGRESS 0 {total}", flush=True)
+
+    import easyocr
+
+    reader = easyocr.Reader(["ar"], gpu=False, verbose=False)
+    pieces: list[str] = []
+    for index, image_path in enumerate(image_paths, start=1):
+        lines = reader.readtext(str(image_path), detail=0, paragraph=True)
+        page_text = "\n".join(str(line).strip() for line in lines if str(line).strip())
+        if page_text:
+            pieces.append(page_text)
+        print(f"ARABIC_READER_PROGRESS {index} {total}", flush=True)
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text("\n\n".join(pieces), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

scripts/export_hf_space.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import shutil
+import uuid
+from pathlib import Path
+from typing import Iterable
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_OUTPUT = ROOT_DIR / "outputs" / "huggingface-space"
+
+FILES = [
+    "requirements.txt",
+    "requirements-silma.txt",
+    "requirements-supertonic.txt",
+    "requirements-paddleocr.txt",
+    "requirements-paddleocr-vl.txt",
+    "requirements-qari-ocr.txt",
+    "requirements-tawkeed-ocr.txt",
+    "requirements-katib-ocr.txt",
+    "requirements-arabic-qwen-ocr.txt",
+    "requirements-arabic-glm-ocr.txt",
+    "requirements-baseer-ocr.txt",
+]
+DIRECTORIES = [
+    "app",
+    "api",
+    "docs",
+    "static",
+    "scripts",
+]
+EXCLUDE_NAMES = {
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+}
+EXCLUDE_SUFFIXES = {
+    ".pyc",
+    ".pyo",
+    ".pyd",
+}
+MANIFEST_NAME = ".export-manifest.json"
+
+
+def should_copy(path: Path) -> bool:
+    if path.name in EXCLUDE_NAMES:
+        return False
+    if path.suffix in EXCLUDE_SUFFIXES:
+        return False
+    return True
+
+
+def copy_tree(source: Path, destination: Path) -> None:
+    if destination.exists():
+        shutil.rmtree(destination)
+    shutil.copytree(source, destination, ignore=lambda _dir, names: [name for name in names if not should_copy(Path(name))])
+
+
+def iter_manifest_source_files(root: Path | None = None) -> Iterable[Path]:
+    root = root or ROOT_DIR
+    for relative in FILES:
+        path = root / relative
+        if path.exists():
+            yield path
+    dockerfile = root / "Dockerfile.worker"
+    if dockerfile.exists():
+        yield dockerfile
+    for relative in DIRECTORIES:
+        base = root / relative
+        if not base.exists():
+            continue
+        for path in sorted(base.rglob("*")):
+            if path.is_file() and should_copy(path):
+                yield path
+
+
+def file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_export_manifest(root: Path | None = None) -> dict[str, object]:
+    root = root or ROOT_DIR
+    files: dict[str, str] = {}
+    for path in iter_manifest_source_files(root):
+        relative = path.relative_to(root).as_posix()
+        if relative == "Dockerfile.worker":
+            relative = "Dockerfile"
+        files[relative] = file_sha256(path)
+    return {
+        "version": 1,
+        "source": "ArabicTranslator",
+        "files": files,
+    }
+
+
+def build_hf_space_bundle(output_dir: Path) -> list[str]:
+    output_dir.mkdir(parents=True)
+    copied: list[str] = []
+    for relative in FILES:
+        source = ROOT_DIR / relative
+        destination = output_dir / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, destination)
+        copied.append(relative)
+
+    shutil.copy2(ROOT_DIR / "Dockerfile.worker", output_dir / "Dockerfile")
+    copied.append("Dockerfile")
+
+    for relative in DIRECTORIES:
+        source = ROOT_DIR / relative
+        destination = output_dir / relative
+        copy_tree(source, destination)
+        copied.append(relative)
+
+    (output_dir / ".dockerignore").write_text(
+        "\n".join(
+            [
+                ".git",
+                ".env",
+                ".venv",
+                ".venv-*",
+                "__pycache__",
+                ".pytest_cache",
+                "outputs",
+                "uploads",
+                "data",
+                "test_pdfs",
+                "tests",
+                "*.pyc",
+                "*.pyo",
+                "*.pyd",
+                "*.log",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    copied.append(".dockerignore")
+
+    write_space_readme(output_dir / "README.md")
+    copied.append("README.md")
+    (output_dir / MANIFEST_NAME).write_text(
+        json.dumps(build_export_manifest(), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    copied.append(MANIFEST_NAME)
+    (output_dir / ".export-complete").write_text("ready\n", encoding="utf-8")
+    copied.append(".export-complete")
+    return copied
+
+
+def export_hf_space(output_dir: Path = DEFAULT_OUTPUT, force: bool = False) -> dict[str, object]:
+    output_dir = output_dir.resolve()
+    if output_dir.exists() and not force:
+        raise FileExistsError(f"{output_dir} already exists. Use --force to replace it.")
+
+    parent = output_dir.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    staging_dir = parent / f".{output_dir.name}.staging-{uuid.uuid4().hex}"
+    backup_dir = parent / f".{output_dir.name}.previous-{uuid.uuid4().hex}"
+    copied: list[str] = []
+    try:
+        copied = build_hf_space_bundle(staging_dir)
+        issues = validate_export(staging_dir)
+        if issues:
+            raise ValueError(f"Staged Hugging Face Space bundle is invalid: {', '.join(issues)}")
+        if output_dir.exists():
+            output_dir.rename(backup_dir)
+        staging_dir.rename(output_dir)
+    except Exception:
+        shutil.rmtree(staging_dir, ignore_errors=True)
+        if backup_dir.exists() and not output_dir.exists():
+            backup_dir.rename(output_dir)
+        raise
+    finally:
+        shutil.rmtree(backup_dir, ignore_errors=True)
+    return {"outputDir": str(output_dir), "copied": copied}
+
+
+def write_space_readme(path: Path) -> None:
+    path.write_text(
+        """# Arabic Audio Reader Worker
+
+This is the Docker worker bundle for the Arabic PDF Reader.
+
+## Hugging Face Space Settings
+
+- SDK: Docker
+- Hardware: free CPU is acceptable for demos, but cold starts and long books can be slow
+- Free CPU Basic currently provides 2 vCPU, 16 GB RAM, and 50 GB non-persistent disk by default; treat generated audio as short-lived unless you add persistent/object storage
+- Port: 7860
+- Default build: installs SILMA, PaddleOCR Arabic, Tesseract Arabic, and eSpeak NG
+- Optional fast CPU voice: set Docker build arg `INSTALL_SUPERTONIC=1` to add Supertonic 3 Arabic-capable local TTS
+- Stronger OCR build: set Docker build arg `INSTALL_TAWKEED_OCR=1`, `INSTALL_KATIB_OCR=1`, `INSTALL_ARABIC_QWEN_OCR=1`, `INSTALL_ARABIC_GLM_OCR=1`, or `INSTALL_BASEER_OCR=1` for Arabic-trained models, or `INSTALL_QARI_OCR=1` for the heavier Arabic-book model
+
+Set these Space secrets:
+
+```text
+ACCESS_CODE=1234
+SECRET_KEY=<generated by outputs\\deployment-handoff.md>
+CORS_ORIGINS=https://your-vercel-app.vercel.app
+COOKIE_SAMESITE=none
+COOKIE_SECURE=1
+OCR_ENGINE=arabic-max
+DEFAULT_VOICE_ID=silma-local
+OUTPUT_RETENTION_DAYS=7
+OUTPUT_MAX_FILES=25
+AUDIO_FORMAT=mp3
+MP3_BITRATE=96k
+```
+
+Generate the deployment handoff from the main repo to get the exact `SECRET_KEY`, worker secrets, Vercel environment variables, and final proof command:
+
+```powershell
+python scripts\\deployment_handoff.py https://your-space.hf.space --origin https://your-vercel-app.vercel.app --code 1234
+```
+
+Keep `outputs\\deployment-handoff.md` private because it contains deployment secrets.
+
+The compact process recommendation is included at `docs/recommended-free-stack.md`, with the machine-readable deployment decision card at `docs/recommended-decision-card.json` and its readable companion at `docs/recommended-decision-card.md`. The current practical default is PyMuPDF embedded text first, `OCR_ENGINE=arabic-max` for scanned Arabic pages, SILMA TTS for the first clean voice, and downloadable worker audio.
+
+Optional stronger-worker build args:
+
+```text
+INSTALL_QARI_OCR=1
+INSTALL_TAWKEED_OCR=1
+INSTALL_KATIB_OCR=1
+INSTALL_ARABIC_QWEN_OCR=1
+INSTALL_ARABIC_GLM_OCR=1
+INSTALL_BASEER_OCR=1
+INSTALL_PADDLEOCR_VL=1
+INSTALL_SUPERTONIC=1
+```
+
+Use `INSTALL_TAWKEED_OCR=1`, `INSTALL_KATIB_OCR=1`, `INSTALL_ARABIC_QWEN_OCR=1`, `INSTALL_ARABIC_GLM_OCR=1`, or `INSTALL_BASEER_OCR=1` first when you want an Arabic-trained OCR model. Use `INSTALL_QARI_OCR=1` when you want the strongest Arabic-book OCR and the worker has enough memory/GPU. Leave heavy options at `0` on free CPU Spaces unless a short benchmark proves the stronger model is worth the cold start, build time, memory, and runtime.
+
+After the Space builds, verify it from your main repo:
+
+```powershell
+python scripts\\verify_worker.py https://your-space.hf.space --code 1234 --origin https://your-vercel-app.vercel.app --require-cors --smoke-upload --smoke-scanned --smoke-ocr-engine arabic-max
+```
+""",
+        encoding="utf-8",
+    )
+
+
+def validate_export(output_dir: Path) -> list[str]:
+    required = [
+        "Dockerfile",
+        "README.md",
+        ".dockerignore",
+        MANIFEST_NAME,
+        "requirements.txt",
+        "requirements-silma.txt",
+        "requirements-supertonic.txt",
+        "requirements-paddleocr.txt",
+        "requirements-paddleocr-vl.txt",
+        "requirements-qari-ocr.txt",
+        "requirements-tawkeed-ocr.txt",
+        "requirements-katib-ocr.txt",
+        "requirements-arabic-qwen-ocr.txt",
+        "requirements-arabic-glm-ocr.txt",
+        "requirements-baseer-ocr.txt",
+        ".export-complete",
+        "app/main.py",
+        "api/index.py",
+        "static/index.html",
+        "scripts/setup_silma.sh",
+        "scripts/setup_supertonic.sh",
+        "scripts/setup_paddleocr.sh",
+        "scripts/setup_paddleocr_vl.sh",
+        "scripts/setup_qari_ocr.sh",
+        "scripts/setup_tawkeed_ocr.sh",
+        "scripts/setup_katib_ocr.sh",
+        "scripts/setup_arabic_qwen_ocr.sh",
+        "scripts/setup_arabic_glm_ocr.sh",
+        "scripts/setup_baseer_ocr.sh",
+        "scripts/qari_ocr_extract.py",
+        "scripts/tawkeed_ocr_extract.py",
+        "scripts/katib_ocr_extract.py",
+        "scripts/arabic_qwen_ocr_extract.py",
+        "scripts/arabic_glm_ocr_extract.py",
+        "scripts/baseer_ocr_extract.py",
+        "scripts/configure_vercel_worker.py",
+        "scripts/deploy_hf_space.py",
+        "scripts/finish_live_deployment.py",
+        "scripts/prepare_live_deployment.py",
+        "scripts/validate_deployment_env.py",
+        "scripts/refresh_research_evidence.py",
+        "scripts/score_voice_listening.py",
+        "scripts/score_tts_preprocessor.py",
+        "docs/recommended-free-stack.md",
+        "docs/recommended-decision-card.md",
+        "docs/recommended-decision-card.json",
+    ]
+    missing = [relative for relative in required if not (output_dir / relative).exists()]
+    forbidden = [".env", "uploads", "outputs", "data", "test_pdfs", ".venv", ".venv-silma", ".venv-ocr"]
+    present_forbidden = [relative for relative in forbidden if (output_dir / relative).exists()]
+    return [f"missing:{item}" for item in missing] + [f"forbidden:{item}" for item in present_forbidden]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Export a clean Hugging Face Spaces Docker worker bundle.")
+    parser.add_argument("--out", type=Path, default=DEFAULT_OUTPUT, help="Destination folder for the Space bundle.")
+    parser.add_argument("--force", action="store_true", help="Replace the destination folder if it already exists.")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of a compact summary.")
+    args = parser.parse_args()
+
+    result = export_hf_space(args.out, force=args.force)
+    issues = validate_export(args.out)
+    result["ready"] = not issues
+    result["issues"] = issues
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Exported Hugging Face Space bundle to {result['outputDir']}")
+        if issues:
+            print("Issues:")
+            for issue in issues:
+                print(f"- {issue}")
+        else:
+            print("Bundle is ready to push to a Docker Space.")
+    if issues:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/export_ocr_sample_images.py

@@ -0,0 +1,456 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+import fitz
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from scripts.select_test_pages import PageScore, select_pages
+
+
+DEFAULT_OUT_DIR = ROOT_DIR / "outputs" / "external-ocr-sample"
+
+
+def quote_path(path: Path) -> str:
+    text = str(path)
+    if any(char.isspace() for char in text):
+        return f'"{text}"'
+    return text
+
+
+def render_page_images(pdf_path: Path, selected: list[PageScore], out_dir: Path, zoom: float = 2.0) -> list[dict[str, Any]]:
+    if zoom <= 0:
+        raise ValueError("zoom must be greater than 0")
+    out_dir.mkdir(parents=True, exist_ok=True)
+    images: list[dict[str, Any]] = []
+    with fitz.open(pdf_path) as document:
+        for item in selected:
+            page = document[item.page - 1]
+            pixmap = page.get_pixmap(matrix=fitz.Matrix(zoom, zoom), alpha=False)
+            image_path = out_dir / f"page-{item.page:04d}.png"
+            pixmap.save(image_path)
+            images.append(
+                {
+                    "page": item.page,
+                    "path": str(image_path),
+                    "width": pixmap.width,
+                    "height": pixmap.height,
+                    "score": item.score,
+                    "characters": item.characters,
+                    "arabicWords": item.arabic_words,
+                    "inkRatio": item.ink_ratio,
+                }
+            )
+    return images
+
+
+def build_external_ocr_commands(image_dir: Path) -> dict[str, str]:
+    image_glob = quote_path(image_dir / "page-*.png")
+    return {
+        "wiredOcrBenchmark": (
+            "python scripts\\benchmark_ocr.py C:\\path\\to\\book-best-5-pages.pdf "
+            "--page-limit 5 --engines arabic-max arabic tawkeed-ocr baseer-ocr arabic-glm-ocr arabic-qwen-ocr katib-ocr qari-ocr paddleocr tesseract"
+        ),
+        "arabicGlmExternal": (
+            f"If the Arabic-GLM sidecar is not installed, run Arabic-GLM-OCR-v2 externally against {image_glob}, "
+            "then compare its cleaned Arabic text against QARI/KATIB and the wired OCR benchmark."
+        ),
+        "arabicQwen35External": (
+            f"If the Arabic-Qwen sidecar is not installed, run Arabic-Qwen3.5-OCR-v4 externally against {image_glob}, "
+            "then compare printed, handwritten, and diacritic-heavy Arabic output against the wired OCR benchmark."
+        ),
+        "loayQwen25External": (
+            f"Run loay/Arabic-OCR-Qwen2.5-VL-7B-Vision externally against {image_glob} only on a strong worker, "
+            "then compare its Arabic OCR output against QARI, KATIB, Arabic-Qwen3.5, Baseer, and the wired OCR benchmark."
+        ),
+        "dimiArabicOcrExternal": (
+            f"Run DIMI Arabic OCR v2 externally against {image_glob} only on a strong worker, then compare printed Arabic, "
+            "diacritics-heavy text, and formatting preservation against the wired OCR benchmark."
+        ),
+        "baseerExternal": (
+            f"If the Baseer sidecar is not installed, run Baseer OCR externally against {image_glob}, then compare "
+            "complex-layout Arabic output against the wired OCR benchmark."
+        ),
+        "atlasOcrExternal": (
+            f"Run AtlasOCR externally against {image_glob} only for Darija/Moroccan Arabic PDFs, then compare "
+            "against the wired OCR benchmark and confirm licensing before production wiring."
+        ),
+        "ketabaExternal": (
+            f"Run Ketaba-OCR LoRA externally against {image_glob}, then compare its cleaned Arabic text "
+            "against the wired OCR benchmark before adding a sidecar."
+        ),
+        "oiOcrExternal": (
+            f"Run oi-OCR externally against {image_glob}, then compare structured Markdown/text extraction, "
+            "Arabic reading order, and speech-readiness against the wired OCR benchmark."
+        ),
+        "nuExtract3External": (
+            f"Run numind/NuExtract3 externally in document-to-Markdown or content mode against {image_glob}, "
+            "then compare Arabic text preservation, layout cleanup, tables/forms, and speech-readiness against the wired OCR benchmark."
+        ),
+        "chandraExternal": (
+            f"Run Chandra OCR 2 externally against {image_glob} for complex layouts, tables, forms, or mixed-language pages, "
+            "then compare Arabic reading order and speech-readiness against the wired Arabic OCR benchmark before considering any hosted use."
+        ),
+        "dotsOcrExternal": (
+            f"Run rednote-hilab/dots.ocr externally against {image_glob} for document layout, reading order, tables, formulas, "
+            "or mixed-language pages, then compare Arabic word preservation and speech-readiness against the wired Arabic OCR benchmark."
+        ),
+        "olmocrArabicLoraExternal": (
+            f"Run hastyle/olmOCR-arabic-lora-v2 externally against {image_glob} only for full-page Arabic manuscript scans "
+            "on a large worker; compare it against Ketaba, QARI, line-cropped HAFITH/Glimpse, and the wired OCR benchmark."
+        ),
+        "arabicLargeNougatExternal": (
+            f"Run MohamedRashad/arabic-large-nougat externally against {image_glob} for Arabic book-page OCR-to-Markdown, "
+            "then compare text preservation, reading order, hallucination risk, and speech-readiness against the wired OCR benchmark."
+        ),
+        "doctrArabicExternal": (
+            f"Run the DocTR Arabic FAST detector plus Arabic PARSEQ recognizer externally against {image_glob}, "
+            "then compare classic OCR text ordering, Arabic word preservation, and recognizer license fit before any wiring."
+        ),
+        "krakenExternal": (
+            f"Run Kraken/eScriptorium externally against {image_glob} with an Arabic-script recognition model or "
+            "line-cropped workflow when pages look like historical print/manuscripts; then compare Arabic word "
+            "preservation and reading order against the wired OCR benchmark before any sidecar work."
+        ),
+        "glmDocsExternal": (
+            f"Run maloukafer/GLM-OCR-finetuned-documents externally against {image_glob} only for form-like, "
+            "administrative, newspaper, or official-document PDFs; compare it against Arabic-GLM-OCR-v2 and the wired benchmark."
+        ),
+        "mimohaOcrExternal": (
+            f"Run mimoha/ocr externally against {image_glob} only as a low-priority sparse-card check, then compare "
+            "the resulting Arabic text with the same speech-readiness score."
+        ),
+        "handwritten4bitExternal": (
+            f"Run sherif1313/Arabic-handwritten-OCR-4bit-Qwen2.5-VL-3B-v3 externally against {image_glob} when the "
+            "PDF has handwriting or manuscript pages, then compare the smaller 4-bit output against handwritten-v3 and the wired OCR benchmark."
+        ),
+        "nakbaManuscriptLineExternal": (
+            f"Run U4RASD/ar-ms-baseline externally only on line-cropped manuscript images from {image_glob}; keep it "
+            "as a NAKBA 2026 manuscript-line benchmark unless a separate layout step crops pages into text lines."
+        ),
+        "hafithExternal": (
+            f"Run mdnaseif/hafith externally only after cropping {image_glob} into text-line images; use it for "
+            "historical Arabic manuscript or archival-print pages, then merge line outputs before scoring speech-readiness."
+        ),
+        "glimpseRtlExternal": (
+            f"Run surfiniaburger/unsloth_finetune_ocr_arabic externally only after cropping {image_glob} into "
+            "Arabic/Persian text-line images; compare the merged RTL line text against HAFITH, NAKBA line OCR, and the wired benchmark."
+        ),
+        "qwen25GgufExternal": (
+            f"Run mo1998/arabic-ocr-qwen2.5-vl externally against {image_glob} as a QariOCR-trained GGUF/Unsloth "
+            "benchmark, then compare scanned-book, religious-text, handwriting, and mixed Arabic-English output against QARI 0.4 and the wired OCR benchmark."
+        ),
+        "tawkeedExternal": (
+            f"If the Tawkeed sidecar is not installed, run Tawkeed OCR externally against {image_glob}, then compare "
+            "Arabic document, handwriting, and scene-text output against QARI 0.4, KATIB, Arabic-Qwen, Baseer, and the wired OCR benchmark."
+        ),
+        "falconExternal": (
+            f"Run Falcon-OCR externally against {image_glob}, then compare Arabic word count, reading order, "
+            "and speech-readiness against KATIB/QARI/PaddleOCR."
+        ),
+        "scoreExternalText": (
+            "python scripts\\score_external_ocr.py "
+            "--candidate arabic-glm=outputs\\external-ocr-sample\\arabic-glm.txt "
+            "--candidate arabic-qwen35=outputs\\external-ocr-sample\\arabic-qwen35.txt "
+            "--candidate loay-qwen25=outputs\\external-ocr-sample\\loay-qwen25.txt "
+            "--candidate dimi-v2=outputs\\external-ocr-sample\\dimi-v2.txt "
+            "--candidate atlasocr=outputs\\external-ocr-sample\\atlasocr.txt "
+            "--candidate ketaba=outputs\\external-ocr-sample\\ketaba.txt "
+            "--candidate oi-ocr=outputs\\external-ocr-sample\\oi-ocr.txt "
+            "--candidate nuextract3=outputs\\external-ocr-sample\\nuextract3.txt "
+            "--candidate chandra=outputs\\external-ocr-sample\\chandra.txt "
+            "--candidate dots-ocr=outputs\\external-ocr-sample\\dots-ocr.txt "
+            "--candidate olmocr-arabic-lora=outputs\\external-ocr-sample\\olmocr-arabic-lora.txt "
+            "--candidate arabic-large-nougat=outputs\\external-ocr-sample\\arabic-large-nougat.txt "
+            "--candidate doctr-arabic=outputs\\external-ocr-sample\\doctr-arabic.txt "
+            "--candidate kraken=outputs\\external-ocr-sample\\kraken.txt "
+            "--candidate glm-docs=outputs\\external-ocr-sample\\glm-docs.txt "
+            "--candidate mimoha-ocr=outputs\\external-ocr-sample\\mimoha-ocr.txt "
+            "--candidate handwritten-4bit=outputs\\external-ocr-sample\\handwritten-4bit.txt "
+            "--candidate nakba-ms-line=outputs\\external-ocr-sample\\nakba-ms-line.txt "
+            "--candidate hafith=outputs\\external-ocr-sample\\hafith.txt "
+            "--candidate glimpse-rtl=outputs\\external-ocr-sample\\glimpse-rtl.txt "
+            "--candidate qwen25-gguf=outputs\\external-ocr-sample\\qwen25-gguf.txt "
+            "--candidate tawkeed=outputs\\external-ocr-sample\\tawkeed.txt "
+            "--candidate falcon=outputs\\external-ocr-sample\\falcon.txt "
+            "--candidate baseer=outputs\\external-ocr-sample\\baseer.txt "
+            "--baseline-json outputs\\external-ocr-sample\\wired-ocr-baseline.json "
+            "--write-report outputs\\external-ocr-sample\\external-ocr-score.md "
+            "--write-json outputs\\external-ocr-sample\\external-ocr-score.json"
+        ),
+        "promotionGate": (
+            "python scripts\\model_promotion_gate.py "
+            "--candidate-name \"External OCR winner\" --kind ocr --license Apache-2.0 "
+            "--score-json outputs\\external-ocr-sample\\external-ocr-score.json "
+            "--same-sample --runtime-ok --privacy-ok --human-reviewed "
+            "--write-report outputs\\external-ocr-sample\\model-promotion-gate.md"
+        ),
+    }
+
+
+def write_ocr_sample_report(path: Path, result: dict[str, Any]) -> None:
+    commands = result["commands"]
+    lines = [
+        "# External Arabic OCR Sample",
+        "",
+        f"PDF: {result['pdf']}",
+        f"Image directory: {result['imageDir']}",
+        f"Pages: {', '.join(str(image['page']) for image in result['images'])}",
+        f"Render zoom: {result['zoom']}",
+        "",
+        "Use these exact page images for every external OCR model. Do not compare models on different pages or different render scales.",
+        "",
+        "## Images",
+        "",
+        "| Page | PNG | Size | Score | Arabic Words | Ink Ratio |",
+        "| --- | --- | --- | --- | --- | --- |",
+    ]
+    for image in result["images"]:
+        lines.append(
+            f"| {image['page']} | {image['path']} | {image['width']}x{image['height']} | "
+            f"{image['score']} | {image['arabicWords']} | {image['inkRatio']} |"
+        )
+    lines.extend(
+        [
+            "",
+            "## Comparison Commands",
+            "",
+            "Wired OCR benchmark:",
+            "",
+            "```powershell",
+            commands["wiredOcrBenchmark"],
+            "```",
+            "",
+            "Arabic-GLM-OCR-v2:",
+            "",
+            "```text",
+            commands["arabicGlmExternal"],
+            "```",
+            "",
+            "Arabic-Qwen3.5-OCR-v4:",
+            "",
+            "```text",
+            commands["arabicQwen35External"],
+            "```",
+            "",
+            "Loay Arabic-OCR-Qwen2.5-VL-7B:",
+            "",
+            "```text",
+            commands["loayQwen25External"],
+            "```",
+            "",
+            "DIMI Arabic OCR v2:",
+            "",
+            "```text",
+            commands["dimiArabicOcrExternal"],
+            "```",
+            "",
+            "AtlasOCR:",
+            "",
+            "```text",
+            commands["atlasOcrExternal"],
+            "```",
+            "",
+            "Ketaba-OCR LoRA:",
+            "",
+            "```text",
+            commands["ketabaExternal"],
+            "```",
+            "",
+            "oi-OCR:",
+            "",
+            "```text",
+            commands["oiOcrExternal"],
+            "```",
+            "",
+            "NuExtract3:",
+            "",
+            "```text",
+            commands["nuExtract3External"],
+            "```",
+            "",
+            "Chandra OCR 2:",
+            "",
+            "```text",
+            commands["chandraExternal"],
+            "```",
+            "",
+            "dots.ocr:",
+            "",
+            "```text",
+            commands["dotsOcrExternal"],
+            "```",
+            "",
+            "olmOCR Arabic LoRA v2:",
+            "",
+            "```text",
+            commands["olmocrArabicLoraExternal"],
+            "```",
+            "",
+            "Arabic Large Nougat:",
+            "",
+            "```text",
+            commands["arabicLargeNougatExternal"],
+            "```",
+            "",
+            "DocTR Arabic FAST/PARSEQ:",
+            "",
+            "```text",
+            commands["doctrArabicExternal"],
+            "```",
+            "",
+            "Kraken/eScriptorium Arabic script:",
+            "",
+            "```text",
+            commands["krakenExternal"],
+            "```",
+            "",
+            "GLM-OCR Arabic/French documents:",
+            "",
+            "```text",
+            commands["glmDocsExternal"],
+            "```",
+            "",
+            "mimoha Arabic OCR:",
+            "",
+            "```text",
+            commands["mimohaOcrExternal"],
+            "```",
+            "",
+            "Arabic handwritten OCR 4-bit Qwen2.5-VL:",
+            "",
+            "```text",
+            commands["handwritten4bitExternal"],
+            "```",
+            "",
+            "NAKBA Arabic manuscript line OCR baseline:",
+            "",
+            "```text",
+            commands["nakbaManuscriptLineExternal"],
+            "```",
+            "",
+            "HAFITH:",
+            "",
+            "```text",
+            commands["hafithExternal"],
+            "```",
+            "",
+            "Glimpse RTL OCR:",
+            "",
+            "```text",
+            commands["glimpseRtlExternal"],
+            "```",
+            "",
+            "Arabic OCR Qwen2.5-VL GGUF:",
+            "",
+            "```text",
+            commands["qwen25GgufExternal"],
+            "```",
+            "",
+            "Tawkeed OCR:",
+            "",
+            "```text",
+            commands["tawkeedExternal"],
+            "```",
+            "",
+            "Falcon-OCR:",
+            "",
+            "```text",
+            commands["falconExternal"],
+            "```",
+            "",
+            "Baseer OCR:",
+            "",
+            "```text",
+            commands["baseerExternal"],
+            "```",
+            "",
+            "Score external OCR text outputs:",
+            "",
+            "```powershell",
+            commands["scoreExternalText"],
+            "```",
+            "",
+            "Promotion gate for the winning OCR candidate:",
+            "",
+            "```powershell",
+            commands["promotionGate"],
+            "```",
+            "",
+            "## Promotion Rule",
+            "",
+            "Replace the candidate name and license in the promotion-gate command with the real winning model. Promote an external OCR model only if it beats the wired Arabic OCR stack on these same pages, has an acceptable license, and the worker can handle its memory, cold start, and runtime.",
+        ]
+    )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+
+
+def export_ocr_sample_images(
+    pdf_path: Path,
+    out_dir: Path = DEFAULT_OUT_DIR,
+    count: int = 5,
+    skip_first: int = 0,
+    zoom: float = 2.0,
+) -> dict[str, Any]:
+    if not pdf_path.exists():
+        raise FileNotFoundError(f"PDF not found: {pdf_path}")
+    if pdf_path.suffix.lower() != ".pdf":
+        raise ValueError("Input must be a PDF file.")
+    if count < 1:
+        raise ValueError("count must be at least 1")
+
+    selected = select_pages(pdf_path, count=count, skip_first=skip_first)
+    image_dir = out_dir / "images"
+    images = render_page_images(pdf_path, selected, image_dir, zoom=zoom)
+    commands = build_external_ocr_commands(image_dir)
+    result = {
+        "pdf": str(pdf_path),
+        "imageDir": str(image_dir),
+        "reportPath": str(out_dir / "external-ocr-sample.md"),
+        "zoom": zoom,
+        "pages": [item.page for item in selected],
+        "scores": [asdict(item) for item in selected],
+        "images": images,
+        "commands": commands,
+    }
+    write_ocr_sample_report(Path(result["reportPath"]), result)
+    return result
+
+
+def main_cli() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    parser = argparse.ArgumentParser(description="Export selected Arabic PDF page images for external OCR benchmarking.")
+    parser.add_argument("pdf", type=Path, help="Source Arabic PDF")
+    parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT_DIR, help="Output directory")
+    parser.add_argument("--count", type=int, default=5, help="Number of pages to export")
+    parser.add_argument("--skip-first", type=int, default=0, help="Ignore the first N pages before scoring")
+    parser.add_argument("--zoom", type=float, default=2.0, help="Render zoom for PNG images")
+    parser.add_argument("--json", action="store_true", help="Print JSON details")
+    args = parser.parse_args()
+
+    result = export_ocr_sample_images(
+        args.pdf,
+        out_dir=args.out_dir,
+        count=args.count,
+        skip_first=args.skip_first,
+        zoom=args.zoom,
+    )
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"Wrote OCR image sample report: {result['reportPath']}")
+        print(f"Rendered pages: {', '.join(str(page) for page in result['pages'])}")
+
+
+if __name__ == "__main__":
+    main_cli()

scripts/export_tts_sample.py

@@ -0,0 +1,387 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from app import main
+from scripts.dry_run_pdf import dry_run_pdf
+
+
+def safe_command_path(path: Path) -> str:
+    text = str(path)
+    return f'"{text}"' if " " in text else text
+
+
+def build_external_commands(text_path: Path, output_dir: Path) -> dict[str, str]:
+    text_arg = safe_command_path(text_path)
+    output_arg = safe_command_path(output_dir)
+    return {
+        "localVoiceBenchmark": (
+            f"python scripts\\benchmark_voices.py --text-file {text_arg} "
+            f"--out-dir {output_arg}\\local-voices --write-report {output_arg}\\local-voices.md"
+        ),
+        "mossTtsNanoOnnx": (
+            "moss-tts-nano generate --backend onnx --language ar "
+            f"--text-file {text_arg} --prompt-speech C:\\path\\to\\arabic-reference.wav"
+        ),
+        "mossTtsNanoServer": "moss-tts-nano serve --backend onnx",
+        "supertonicLocal": (
+            f"python scripts\\benchmark_voices.py --voices supertonic-ar --text-file {text_arg} "
+            f"--out-dir {output_arg}\\supertonic --write-report {output_arg}\\supertonic.md"
+        ),
+        "mishkalaTashkeelExternal": (
+            "Diacritize the same cleaned sample with flokymind/mishkala and save it beside the plain sample, "
+            f"for example {output_arg}\\arabic-tts-sample-mishkala.txt. Then synthesize both files with the same voice."
+        ),
+        "mishkalaVoiceBenchmark": (
+            f"python scripts\\benchmark_voices.py --text-file {output_arg}\\arabic-tts-sample-mishkala.txt "
+            f"--out-dir {output_arg}\\mishkala-local-voices --write-report {output_arg}\\mishkala-local-voices.md"
+        ),
+        "tashkeel350External": (
+            "Diacritize the same cleaned sample with Etherll/Tashkeel-350M and save it beside the plain sample, "
+            f"for example {output_arg}\\arabic-tts-sample-tashkeel350.txt. Then synthesize plain, Mishkala, "
+            "and Tashkeel-350M samples with the same voice before choosing a preprocessor."
+        ),
+        "tashkeel350VoiceBenchmark": (
+            f"python scripts\\benchmark_voices.py --text-file {output_arg}\\arabic-tts-sample-tashkeel350.txt "
+            f"--out-dir {output_arg}\\tashkeel350-local-voices --write-report {output_arg}\\tashkeel350-local-voices.md"
+        ),
+        "preprocessorListeningScore": (
+            "python scripts\\score_tts_preprocessor.py "
+            "--rating plain=4,5,5,4,4 --rating mishkala=5,4,4,4,4 --rating tashkeel350=5,4,4,4,4 "
+            f"--write-report {output_arg}\\tts-preprocessor-score.md "
+            f"--write-json {output_arg}\\tts-preprocessor-score.json"
+        ),
+        "voiceListeningScore": (
+            "python scripts\\score_voice_listening.py "
+            "--rating silma-local=5,4,4,5,5 --rating espeak-ar-clear=3,2,4,3,5 "
+            f"--write-report {output_arg}\\voice-listening-score.md "
+            f"--write-json {output_arg}\\voice-listening-score.json"
+        ),
+        "voicePromotionGate": (
+            "python scripts\\model_promotion_gate.py "
+            "--candidate-name \"External voice winner\" --kind tts --license Apache-2.0 "
+            f"--score-json {output_arg}\\voice-listening-score.json "
+            "--same-sample --runtime-ok --privacy-ok --human-reviewed "
+            f"--write-report {output_arg}\\voice-promotion-gate.md"
+        ),
+        "preprocessorPromotionGate": (
+            "python scripts\\model_promotion_gate.py "
+            "--candidate-name \"TTS preprocessor winner\" --kind preprocessor --license Apache-2.0 "
+            f"--score-json {output_arg}\\tts-preprocessor-score.json "
+            "--same-sample --runtime-ok --privacy-ok --human-reviewed "
+            f"--write-report {output_arg}\\preprocessor-promotion-gate.md"
+        ),
+        "omniVoiceExternal": (
+            "python -m omnivoice.cli "
+            f"--model k2-fsa/OmniVoice --language ar --text-file {text_arg} "
+            "--ref-audio C:\\path\\to\\arabic-reference.wav --ref-text \"Arabic reference transcript\""
+        ),
+        "omniVoiceArabicLoraExternal": (
+            "Run OmniVoice with the Arabic LoRA adapter vivooglobal/omnivoice-lora-ar on the same text and "
+            "reference audio after the base OmniVoice benchmark works."
+        ),
+        "tadaExternal": (
+            "Benchmark HumeAI/tada-3b-ml externally with language=\"ar\" on the same cleaned sample "
+            f"{text_arg}. It is designed to reduce off-script speech, but it reports the Llama 3.2 "
+            "license and is a 3B-class strong-worker path, so keep it outside the permissive default."
+        ),
+        "lahgtnaChatterboxExternal": (
+            "python -m chatterbox.tts "
+            f"--model oddadmix/lahgtna-chatterbox-v1 --text-file {text_arg} "
+            "--audio-prompt-path C:\\path\\to\\arabic-reference.wav --repetition-penalty 1.25"
+        ),
+        "namaaSaudiTtsExternal": (
+            "Use ChatterboxMultilingualTTS with the NAMAA-Space/NAMAA-Saudi-TTS safetensors on "
+            f"{text_arg}, language_id=\"ar\", and the same optional reference audio. Benchmark only for "
+            "Saudi/Gulf dialect fit, then compare against SILMA, Habibi, Saudi Arabic Qwen3-TTS, and Emirati voices."
+        ),
+        "saudiChatterboxFineTuneExternal": (
+            "Use ChatterboxMultilingualTTS with FatimahEmadEldin/saudi-tts-chatterbox-finetuned T3 weights on "
+            f"{text_arg}, language_id=\"ar\", and the same optional reference audio. Benchmark only for "
+            "Saudi/Gulf dialect fit, then compare against NAMAA-Saudi-TTS, SILMA, Habibi, Saudi Arabic Qwen3-TTS, "
+            "and Emirati voices."
+        ),
+        "nileTtsExternal": (
+            "Benchmark KickItLikeShika/NileTTS-XTTS only for Egyptian/dialectal Arabic using this same cleaned "
+            f"sample {text_arg}. It is Apache-2.0, but not an MSA book default."
+        ),
+        "chatterboxMultilingualExternal": (
+            "Use ChatterboxMultilingualTTS.from_pretrained(...).generate(text, language_id=\"ar\", "
+            "audio_prompt_path=\"C:\\path\\to\\arabic-reference.wav\") against "
+            f"{text_arg}; compare pacing and pronunciation against SILMA and Habibi."
+        ),
+        "chatterboxMultilingualOnnxExternal": (
+            "Benchmark onnx-community/chatterbox-multilingual-ONNX with language_id=\"ar\" against "
+            f"{text_arg}; compare CPU/ONNX runtime, repetition, pacing, and pronunciation against SILMA, "
+            "Habibi, and the regular Chatterbox-Multilingual path."
+        ),
+        "ttsArabicOnnxExternal": (
+            "Benchmark nipponjo/tts-arabic-onnx with the same cleaned sample "
+            f"{text_arg}; try FastPitch, MixerTTS, speaker IDs, pace, and vowelizer options, then compare "
+            "CPU runtime and pronunciation against SILMA, Supertonic, MOSS-TTS-Nano, and Chatterbox ONNX. "
+            "Confirm model/repo licensing before production use."
+        ),
+        "sparkTtsArabicExternal": (
+            "Spark-TTS Arabic requires the Spark-TTS repo plus diacritized Arabic/reference audio; benchmark it "
+            f"externally with {text_arg} only after preparing that reference workflow."
+        ),
+        "sofeliaTtsExternal": (
+            "Sofelia-TTS is a Palestinian Arabic/MiraTTS voice-cloning path; benchmark it only for dialectal text "
+            f"using the same sample {text_arg}."
+        ),
+        "arabicF5TtsCaution": (
+            "Arabic-F5-TTS-v2 is non-commercial and requires fully diacritized Arabic; keep it to personal "
+            "experiments unless that license and input requirement are acceptable."
+        ),
+        "threeArabTtsExternal": (
+            "Benchmark sherif1313/3arab-TTS-500M-v1 and the VoiceDesign variant on this same cleaned Arabic "
+            f"sample: {text_arg}. It is Apache-2.0 and Arabic-only, but new enough that listenability and "
+            "long-form stability need manual checks before app wiring."
+        ),
+        "voxcpm2External": f"Use {text_arg} as the exact Arabic text sample when testing VoxCPM2 externally.",
+        "voxtralTtsCaution": (
+            "Voxtral TTS supports Arabic on its model card, but it is CC-BY-NC-4.0 and GPU-heavy; "
+            f"use {text_arg} only for personal/non-commercial strong-worker listening comparisons."
+        ),
+        "qwen3TtsCaution": (
+            "Do not promote Qwen3-TTS for this Arabic reader until an official Arabic-capable checkpoint "
+            "or Arabic fine-tune is verified on this same sample."
+        ),
+    }
+
+
+def write_markdown_report(path: Path, result: dict[str, Any]) -> None:
+    commands = result["commands"]
+    lines = [
+        "# External Arabic TTS Sample",
+        "",
+        f"PDF: `{result.get('pdf', '-')}`",
+        f"Text file: `{result['textPath']}`",
+        f"Characters: {result['characters']}",
+        f"Arabic words: {result['arabicWords']}",
+        f"OCR extraction: `{result.get('extraction', '-')}`",
+        f"Quality: `{result['quality']}`",
+        "",
+        "Use this same cleaned Arabic text for every voice/model comparison. Do not compare voices with different OCR text.",
+        "",
+        "## Commands",
+        "",
+        "Local installed voices:",
+        "",
+        f"```powershell\n{commands['localVoiceBenchmark']}\n```",
+        "",
+        "MOSS-TTS-Nano ONNX external benchmark:",
+        "",
+        f"```powershell\n{commands['mossTtsNanoOnnx']}\n```",
+        "",
+        "MOSS-TTS-Nano local server:",
+        "",
+        f"```powershell\n{commands['mossTtsNanoServer']}\n```",
+        "",
+        "Supertonic 3 local CPU benchmark:",
+        "",
+        f"```powershell\n{commands['supertonicLocal']}\n```",
+        "",
+        "Mishkala Tashkeel pronunciation preprocessor:",
+        "",
+        f"```text\n{commands['mishkalaTashkeelExternal']}\n```",
+        "",
+        "Mishkala local voice benchmark:",
+        "",
+        f"```powershell\n{commands['mishkalaVoiceBenchmark']}\n```",
+        "",
+        "Tashkeel-350M pronunciation preprocessor:",
+        "",
+        f"```text\n{commands['tashkeel350External']}\n```",
+        "",
+        "Tashkeel-350M local voice benchmark:",
+        "",
+        f"```powershell\n{commands['tashkeel350VoiceBenchmark']}\n```",
+        "",
+        "Plain vs Mishkala vs Tashkeel-350M listening score:",
+        "",
+        f"```powershell\n{commands['preprocessorListeningScore']}\n```",
+        "",
+        "Preprocessor promotion gate:",
+        "",
+        f"```powershell\n{commands['preprocessorPromotionGate']}\n```",
+        "",
+        "Voice listening score:",
+        "",
+        f"```powershell\n{commands['voiceListeningScore']}\n```",
+        "",
+        "Voice promotion gate:",
+        "",
+        f"```powershell\n{commands['voicePromotionGate']}\n```",
+        "",
+        "OmniVoice external benchmark:",
+        "",
+        f"```powershell\n{commands['omniVoiceExternal']}\n```",
+        "",
+        "OmniVoice Arabic LoRA external benchmark:",
+        "",
+        f"```text\n{commands['omniVoiceArabicLoraExternal']}\n```",
+        "",
+        "TADA multilingual external benchmark:",
+        "",
+        f"```text\n{commands['tadaExternal']}\n```",
+        "",
+        "Lahgtna Chatterbox external benchmark:",
+        "",
+        f"```powershell\n{commands['lahgtnaChatterboxExternal']}\n```",
+        "",
+        "NAMAA-Saudi-TTS external benchmark:",
+        "",
+        f"```text\n{commands['namaaSaudiTtsExternal']}\n```",
+        "",
+        "Saudi Chatterbox fine-tune external benchmark:",
+        "",
+        f"```text\n{commands['saudiChatterboxFineTuneExternal']}\n```",
+        "",
+        "NileTTS-XTTS Egyptian Arabic benchmark:",
+        "",
+        f"```text\n{commands['nileTtsExternal']}\n```",
+        "",
+        "Chatterbox-Multilingual external benchmark:",
+        "",
+        f"```text\n{commands['chatterboxMultilingualExternal']}\n```",
+        "",
+        "Chatterbox-Multilingual ONNX external benchmark:",
+        "",
+        f"```text\n{commands['chatterboxMultilingualOnnxExternal']}\n```",
+        "",
+        "tts-arabic-onnx external benchmark:",
+        "",
+        f"```text\n{commands['ttsArabicOnnxExternal']}\n```",
+        "",
+        "Spark-TTS Arabic external benchmark:",
+        "",
+        f"```text\n{commands['sparkTtsArabicExternal']}\n```",
+        "",
+        "Sofelia-TTS external benchmark:",
+        "",
+        f"```text\n{commands['sofeliaTtsExternal']}\n```",
+        "",
+        "Arabic-F5-TTS-v2 caution:",
+        "",
+        f"```text\n{commands['arabicF5TtsCaution']}\n```",
+        "",
+        "3arab-TTS 500M external benchmark:",
+        "",
+        f"```text\n{commands['threeArabTtsExternal']}\n```",
+        "",
+        "VoxCPM2 external benchmark:",
+        "",
+        f"```text\n{commands['voxcpm2External']}\n```",
+        "",
+        "Voxtral TTS caution:",
+        "",
+        f"```text\n{commands['voxtralTtsCaution']}\n```",
+        "",
+        "Qwen3-TTS caution:",
+        "",
+        f"```text\n{commands['qwen3TtsCaution']}\n```",
+        "",
+        "## Listening Checklist",
+        "",
+        "- Arabic pronunciation is clear and not robotic.",
+        "- Pauses are comfortable for long book passages.",
+        "- Numbers, Quranic symbols, and punctuation are not read strangely.",
+        "- Runtime is acceptable before processing a full book.",
+        "- Replace placeholder candidate names and licenses in promotion-gate commands before changing the production default.",
+    ]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def export_tts_sample(
+    pdf_path: Path,
+    out_dir: Path = ROOT_DIR / "outputs" / "external-tts-sample",
+    max_chars: int = 1200,
+    chunk_size: int = main.CLOUD_TTS_MAX_CHARS,
+    ocr_engine: str | None = None,
+    from_extraction: str | None = None,
+    env_file: Path | None = None,
+    write_report: bool = True,
+) -> dict[str, Any]:
+    dry_run = dry_run_pdf(
+        pdf_path,
+        chunk_size=chunk_size,
+        ocr_engine=ocr_engine,
+        from_extraction=from_extraction,
+        env_file=env_file,
+        include_speech_text=True,
+        speech_sample_chars=max_chars,
+    )
+    if not dry_run["readyForTts"]:
+        reasons = "; ".join(str(reason) for reason in dry_run.get("qualityReasons", []))
+        raise RuntimeError(f"OCR text is not ready for TTS. {reasons}".strip())
+
+    sample_text = str(dry_run["speechSampleText"]).strip()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    text_path = out_dir / "arabic-tts-sample.txt"
+    text_path.write_text(sample_text + "\n", encoding="utf-8")
+    commands = build_external_commands(text_path, out_dir)
+    result: dict[str, Any] = {
+        "ready": True,
+        "pdf": str(pdf_path),
+        "textPath": str(text_path),
+        "reportPath": str(out_dir / "external-tts-sample.md"),
+        "characters": len(sample_text),
+        "fullSpeechCharacters": dry_run["speechCharacters"],
+        "arabicWords": dry_run["arabicWords"],
+        "quality": dry_run["quality"],
+        "qualityScore": dry_run["qualityScore"],
+        "qualityReasons": dry_run["qualityReasons"],
+        "ocrEngine": dry_run["ocrEngine"],
+        "extraction": dry_run["extraction"],
+        "commands": commands,
+    }
+    if write_report:
+        write_markdown_report(out_dir / "external-tts-sample.md", result)
+    return result
+
+
+def main_cli() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    parser = argparse.ArgumentParser(description="Export the same cleaned Arabic text sample for external TTS benchmarking.")
+    parser.add_argument("pdf", type=Path, help="Arabic PDF to extract a cleaned speech sample from.")
+    parser.add_argument("--out-dir", type=Path, default=ROOT_DIR / "outputs" / "external-tts-sample")
+    parser.add_argument("--max-chars", type=int, default=1200, help="Maximum cleaned characters to export.")
+    parser.add_argument("--chunk-size", type=int, default=main.CLOUD_TTS_MAX_CHARS)
+    parser.add_argument("--ocr-engine", choices=sorted(main.OCR_ENGINE_CHOICES), help="OCR engine to test.")
+    parser.add_argument("--from-extraction", help="Apply settings from a benchmark extraction label.")
+    parser.add_argument("--env-file", type=Path, help="Load OCR settings from a generated OCR .env snippet.")
+    parser.add_argument("--no-report", action="store_true", help="Only write the text file.")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of a compact summary.")
+    args = parser.parse_args()
+
+    result = export_tts_sample(
+        args.pdf,
+        out_dir=args.out_dir,
+        max_chars=args.max_chars,
+        chunk_size=args.chunk_size,
+        ocr_engine=args.ocr_engine,
+        from_extraction=args.from_extraction,
+        env_file=args.env_file,
+        write_report=not args.no_report,
+    )
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"Wrote Arabic TTS sample: {result['textPath']}")
+        if not args.no_report:
+            print(f"Wrote benchmark handoff: {result['reportPath']}")
+
+
+if __name__ == "__main__":
+    main_cli()

scripts/finish_live_deployment.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from scripts.configure_vercel_worker import DEFAULT_SITE_URL, configure_vercel_worker
+from scripts.deploy_hf_space import DEFAULT_BUNDLE_DIR, deploy_hf_space, token_available, worker_url_for_repo
+from scripts.prove_live_deployment import prove_live_deployment
+
+
+def finish_live_deployment(
+    repo_id: str,
+    site_url: str = DEFAULT_SITE_URL,
+    code: str = "1234",
+    bundle_dir: Path = DEFAULT_BUNDLE_DIR,
+    token: str | None = None,
+    private: bool = False,
+    force_export: bool = True,
+    verify_site_after_vercel: bool = True,
+    run_proof: bool = True,
+    smoke_ocr_engine: str = "arabic-max",
+    smoke_voice_id: str = "espeak-ar-clear",
+    smoke_timeout: float = 180,
+) -> dict[str, object]:
+    deploy_result = deploy_hf_space(
+        repo_id=repo_id,
+        bundle_dir=bundle_dir,
+        token=token,
+        private=private,
+        force_export=force_export,
+    )
+    worker_url = str(deploy_result["workerUrl"])
+    vercel_result = configure_vercel_worker(
+        worker_url,
+        site_url=site_url,
+        code=code,
+        redeploy=True,
+        verify=verify_site_after_vercel,
+    )
+    proof_result = None
+    if run_proof:
+        proof_result = prove_live_deployment(
+            worker_url,
+            site_url,
+            code=code,
+            smoke_voice_id=smoke_voice_id,
+            smoke_ocr_engine=smoke_ocr_engine,
+            smoke_timeout=smoke_timeout,
+        )
+    return {
+        "repoId": repo_id,
+        "siteUrl": site_url.rstrip("/"),
+        "workerUrl": worker_url,
+        "workerDeploy": deploy_result,
+        "vercel": vercel_result,
+        "proof": proof_result,
+        "complete": bool(proof_result and proof_result.get("complete")),
+        "nextCommand": (
+            f"python scripts\\prove_live_deployment.py {worker_url} --origin {site_url.rstrip('/')} "
+            f"--code {code} --smoke-ocr-engine {smoke_ocr_engine}"
+        ),
+    }
+
+
+def dry_run_finish_live_deployment(
+    repo_id: str,
+    site_url: str = DEFAULT_SITE_URL,
+    code: str = "1234",
+    bundle_dir: Path = DEFAULT_BUNDLE_DIR,
+    token: str | None = None,
+    smoke_ocr_engine: str = "arabic-max",
+) -> dict[str, object]:
+    worker_url = worker_url_for_repo(repo_id)
+    site_url = site_url.rstrip("/")
+    return {
+        "dryRun": True,
+        "repoId": repo_id,
+        "siteUrl": site_url,
+        "workerUrl": worker_url,
+        "bundleDir": str(bundle_dir),
+        "tokenAvailable": token_available(token),
+        "willUploadWorker": True,
+        "willConfigureVercel": True,
+        "willRunProof": True,
+        "commands": {
+            "setToken": '$env:HF_TOKEN="<your-hugging-face-write-token>"',
+            "finish": (
+                f"python scripts\\finish_live_deployment.py {repo_id} "
+                f"--site-url {site_url} --code {code} --smoke-ocr-engine {smoke_ocr_engine}"
+            ),
+            "configureVercelOnly": (
+                f"python scripts\\configure_vercel_worker.py {worker_url} "
+                f"--site-url {site_url} --code {code} --verify"
+            ),
+            "proofOnly": (
+                f"python scripts\\prove_live_deployment.py {worker_url} "
+                f"--origin {site_url} --code {code} --smoke-ocr-engine {smoke_ocr_engine}"
+            ),
+        },
+    }
+
+
+def main_with_args(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Upload the HF worker, configure Vercel WORKER_BASE_URL, redeploy, and run live proof."
+    )
+    parser.add_argument("repo_id", help="Hugging Face Space repo id, e.g. username/arabic-audio-reader-worker.")
+    parser.add_argument("--site-url", default=DEFAULT_SITE_URL)
+    parser.add_argument("--code", default="1234")
+    parser.add_argument("--bundle-dir", type=Path, default=DEFAULT_BUNDLE_DIR)
+    parser.add_argument("--token", help="Hugging Face write token. Prefer HF_TOKEN in the environment.")
+    parser.add_argument("--private", action="store_true")
+    parser.add_argument("--no-force-export", action="store_true")
+    parser.add_argument("--skip-site-verify", action="store_true")
+    parser.add_argument("--skip-proof", action="store_true")
+    parser.add_argument("--dry-run", action="store_true", help="Print the planned deployment without changing HF or Vercel.")
+    parser.add_argument("--smoke-ocr-engine", default="arabic-max")
+    parser.add_argument("--smoke-voice-id", default="espeak-ar-clear")
+    parser.add_argument("--smoke-timeout", type=float, default=180)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    if args.dry_run:
+        result = dry_run_finish_live_deployment(
+            args.repo_id,
+            site_url=args.site_url,
+            code=args.code,
+            bundle_dir=args.bundle_dir,
+            token=args.token,
+            smoke_ocr_engine=args.smoke_ocr_engine,
+        )
+        if args.json:
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        else:
+            print(f"Predicted worker URL: {result['workerUrl']}")
+            print(f"Hugging Face token available: {'yes' if result['tokenAvailable'] else 'no'}")
+            print("Command:")
+            print(result["commands"]["finish"])
+        return 0
+
+    result = finish_live_deployment(
+        args.repo_id,
+        site_url=args.site_url,
+        code=args.code,
+        bundle_dir=args.bundle_dir,
+        token=args.token,
+        private=args.private,
+        force_export=not args.no_force_export,
+        verify_site_after_vercel=not args.skip_site_verify,
+        run_proof=not args.skip_proof,
+        smoke_ocr_engine=args.smoke_ocr_engine,
+        smoke_voice_id=args.smoke_voice_id,
+        smoke_timeout=args.smoke_timeout,
+    )
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"Worker URL: {result['workerUrl']}")
+        print(f"Vercel site: {result['siteUrl']}")
+        if result["complete"]:
+            print("Live deployment proof is complete.")
+        else:
+            print("Live deployment still needs proof:")
+            print(result["nextCommand"])
+    return 0 if result["complete"] or args.skip_proof else 1
+
+
+def main() -> int:
+    return main_with_args()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/hosted_preflight.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from scripts.next_deployment_step import deployment_url_warnings
+from scripts.verify_site import Check, print_table, verify_site
+
+
+DEFAULT_OUT = ROOT_DIR / "outputs" / "hosted-preflight.json"
+
+
+def next_action_for_checks(checks: list[Check], worker_url: str, site_url: str) -> str:
+    failed = {check.name: check.detail for check in checks if not check.ok}
+    if not failed:
+        return (
+            "Hosted route is ready. Upload a 5-page Arabic sample first, then run the full book only after "
+            "the OCR text and audio sample sound good."
+        )
+    if "site worker CORS ready" in failed:
+        return (
+            "Fix Hugging Face CORS before uploading: set CORS_ORIGINS to the exact Vercel URL, keep "
+            "COOKIE_SAMESITE=none and COOKIE_SECURE=1, restart the Space, redeploy Vercel, then rerun "
+            f"python scripts\\hosted_preflight.py {site_url} --worker-url {worker_url}."
+        )
+    if "site worker reachable from vercel" in failed or "site worker diagnostics endpoint" in failed:
+        return (
+            "Fix worker routing before uploading: confirm Vercel WORKER_BASE_URL is the public Hugging Face "
+            "Space URL, confirm the Space is awake/public, redeploy Vercel, then rerun hosted preflight."
+        )
+    if "site direct cloud fallback disabled" in failed:
+        return (
+            "Remove Vercel direct-cloud fallback variables before production: ENABLE_DIRECT_CLOUD_TTS, "
+            "HF_API_TOKEN, HF_TTS_MODEL, and DEFAULT_VOICE_ID. Keep WORKER_BASE_URL, then redeploy."
+        )
+    if "site login" in failed or "site session authenticated" in failed:
+        return "Fix ACCESS_CODE and SECRET_KEY matching between Vercel and the worker, then rerun hosted preflight."
+    return "Fix the failed Vercel site checks, redeploy, then rerun hosted preflight before uploading a PDF."
+
+
+def run_hosted_preflight(
+    site_url: str,
+    worker_url: str,
+    code: str = "1234",
+    out: Path = DEFAULT_OUT,
+    timeout: float = 60,
+) -> dict[str, object]:
+    site_url = site_url.rstrip("/")
+    worker_url = worker_url.rstrip("/")
+    warnings = deployment_url_warnings(worker_url, site_url)
+    if warnings:
+        result: dict[str, object] = {
+            "readyToUpload": False,
+            "siteUrl": site_url,
+            "workerUrl": worker_url,
+            "urlWarnings": warnings,
+            "checks": [],
+            "nextAction": (
+                "Replace placeholder, local, non-HTTPS, or swapped URLs with the real Vercel production URL "
+                "and Hugging Face Space worker URL, then rerun hosted preflight."
+            ),
+        }
+    else:
+        checks = verify_site(site_url, code, worker_url, timeout=timeout)
+        ready = all(check.ok for check in checks)
+        result = {
+            "readyToUpload": ready,
+            "siteUrl": site_url,
+            "workerUrl": worker_url,
+            "urlWarnings": [],
+            "checks": [check.__dict__ for check in checks],
+            "nextAction": next_action_for_checks(checks, worker_url, site_url),
+        }
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+    result["report"] = str(out)
+    return result
+
+
+def print_result(result: dict[str, object]) -> None:
+    print(f"Hosted preflight: {'ready' if result['readyToUpload'] else 'not ready'}")
+    print(f"Site: {result['siteUrl']}")
+    print(f"Worker: {result['workerUrl']}")
+    warnings = result.get("urlWarnings") or []
+    if warnings:
+        print()
+        print("URL warnings")
+        for warning in warnings:
+            print(f"- {warning}")
+    checks = result.get("checks") or []
+    if checks:
+        print()
+        print_table([Check(str(item["name"]), bool(item["ok"]), str(item["detail"])) for item in checks])
+    print()
+    print(f"Next action: {result['nextAction']}")
+    print(f"Report: {result['report']}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run a quick hosted Vercel-to-worker preflight before uploading a large PDF.")
+    parser.add_argument("site_url", help="Vercel production URL, for example https://your-app.vercel.app")
+    parser.add_argument("--worker-url", required=True, help="Expected Hugging Face Space worker URL.")
+    parser.add_argument("--code", default="1234", help="Access code used by the site.")
+    parser.add_argument("--out", type=Path, default=DEFAULT_OUT, help="JSON report output path.")
+    parser.add_argument("--timeout", type=float, default=60, help="HTTP timeout in seconds.")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of a readable summary.")
+    args = parser.parse_args()
+
+    result = run_hosted_preflight(args.site_url, args.worker_url, code=args.code, out=args.out, timeout=args.timeout)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print_result(result)
+    if not result["readyToUpload"]:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()