README.md

---
title: Hebrew OCR Document Comparator
emoji: 🧾
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.30.0
app_file: app.py
pinned: false
license: mit
---

# Hebrew/English OCR Document Comparator (Zero-GPU)

This Space is configured specifically for **Hebrew document OCR** (printed + handwritten),
with an optional English fallback when mixed language pages include English strings.

The scheduler is designed for ZeroGPU safety: by default it runs only the maximum number of selected models that fit in memory headroom and will queue the rest in automatic batches. All model inference runs locally inside your ZeroGPU runtime.

## What this space includes

- Checkbox-controlled model runner (unchecked models are skipped).
- Per-model configuration file: `model_registry.json` (easy to add/remove models).
- Ground-truth textbox for quick CER/WER scoring.
- Local OCR inference for all listed models (Transformers runtime + Tesseract fallback).
- Per-run preflight now validates each model’s config before execution. Any selected model that is not
  loadable in this Space’s local Transformers environment is marked as `unsupported` immediately and skipped,
  which prevents internal errors from unsupported repositories (for example ONNX/GGUF-only repos).
- `requirements.txt` and `apt.txt` already include OCR dependencies, plus updated transformer runtime dependencies that improve model compatibility.
- `.huggingface/metadata` preset for Gradio spaces.

## Make it a private Zero-GPU Hugging Face Space

1. In your Hugging Face account, create a new Space.
2. Set **Visibility: Private**.
3. Set **Space SDK: Gradio**.
4. Choose **Zero GPU / a10g** hardware (`zero-a10g`).
5. Upload all files from this directory (`app.py`, `model_registry.json`, `requirements.txt`, `apt.txt`, `.huggingface/metadata`, `README.md`).
6. On first run, use `HF_TOKEN` from environment only if a selected model is private/gated and needs authenticated download.
7. ZeroGPU spaces do not currently support changing `sleep-time`, so the runtime keeps its platform default idle behavior.
8. The app keeps GPU work scoped to active runs by using a short activation hook during processing (instead of continuous warmup).

### CLI flow (your current machine is already logged in)

If you want CLI-only deploy, run:

```bash
HF_SPACE=ssdataanalysis/hebrew-ocr-comparator
hf repos create $HF_SPACE --type space --sdk gradio --private --flavor zero-a10g --exist-ok
hf upload $HF_SPACE /Users/alexanders/ocr-document-ocr-comparison-space . --type space --commit-message "Initial upload"
```

The same repo is already created and uploaded from this machine in this folder:

`https://huggingface.co/spaces/ssdataanalysis/hebrew-ocr-comparator`

## Model list provided

The following models are preloaded in `model_registry.json`:

- Qwen3-VL-8B-Instruct
- Qwen3-VL-8B-Thinking
- Qwen3-VL-4B-Instruct
- Qwen3-VL-4B-Thinking
- Qwen3-VL-30B-A3B-Instruct
- Qwen3-VL-30B-A3B-Thinking
- Nemotron-OCR-v2
- Gemma4 0.4B (E4B) Instruct
- Gemma4 0.4B (E4B) Thinking
- Gemma4 12B Instruct
- Gemma4 12B Thinking
- Gemma4 26B-A4B Instruct
- Gemma4 26B-A4B Thinking
- Gemma4 31B Instruct
- Gemma4 31B Thinking
- chandra2 (`datalab-to/chandra-ocr-2`)
- ronylicha/gigapdf-ocr-hebrew
- Qunie-V7-mini
- OpenMLKitOCR
- Tzefa-Word-OCR-TrOCR
- Qunie-V7-Pico
- aya-vision-32b
- aya-vision-8b
- Phi-4-multimodal-instruct
- surya2 (`datalab-to/surya-ocr-2`)
- PaddleOCR-VL
- PaddleOCR-VL 1.5
- PaddleOCR-VL 1.6
- DeepSeek OCR-1 (`deepseek-ai/DeepSeek-OCR`)
- DeepSeek OCR-2 (`deepseek-ai/DeepSeek-OCR-2`)
- cyttic/exp10-trocr-hebrew-matan-full
- cyttic/exp23-directfit-unfrozen
- cyttic/heb-verifier17-connected
- cyttic/exp26-composed1m
- Tesseract (local)

Model outputs now request a high `max_new_tokens` budget by default (`4096`) for stronger coverage of long documents.

## Add/remove models in the future

Edit `model_registry.json`:

- Set `"enabled": false` to hide a model from the checkbox list.
- Remove an entry entirely to delete it from the UI.
- Add a new entry with:
  - `id` (unique stable ID)
  - `name` (UI label)
  - `model_id` (Hugging Face model path)
  - `provider`:
    - `hf_chat` or `hf_image_to_text`: both are mapped to local Transformers execution in this Space
    - `tesseract` (local OCR fallback)
  - Optional per-entry compatibility overrides:
    - `pipeline_task`: set explicit task string when auto-task probing is insufficient.
    - `trust_remote_code`: `true` when the repository needs custom loading code.
  - `parameters` and `prompt` (model-specific tuning)

## Notes and caveats

- Some large or gated models may be unavailable without a token.
- Some checkpoint/config combinations can still be unsupported by the available local Transformers runtime and will show an error row instead of returning output.
- This version enables `trust_remote_code=True` where required for model families that rely on remote loading code.
- Tesseract output depends on the `tesseract` binary; this Space now requests `tesseract-ocr`, `tesseract-ocr-eng`, and `tesseract-ocr-heb` in `apt.txt`.
- For strict production benchmarks, keep an optional fixed random seed in each entry if the model honors it.
- This app logs only per-run outputs and derived metrics; it does not persist user images.
- In the UI, use **Compute mode**:
  - **Safe (recommended, avoid overrun)**: conservative concurrency based on free GPU memory.
  - **Max compute (faster)**: more parallelism when runtime headroom is available.
  - **Sequential only**: one model at a time.

## What changed for your requested OCR behavior

- Prompts and UI text are aligned to document OCR with an explicit emphasis on **printed + handwritten Hebrew** pages.
- Run only the models you check in the checkbox list to prevent unnecessary inference calls.
- README and upload steps are prepared for CLI deployment under your logged-in account.
- Local inference now uses CUDA-first strict mode by default, with CPU fallback disabled unless `ALLOW_CPU_FALLBACK=1`.