---
title: Rukopys OCR
emoji: ✍️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.11.0
app_file: app.py
python_version: 3.12.12
suggested_hardware: zero-a10g
models:
  - ebinan92/Rukopys-OCR-4B
preload_from_hub:
  - ebinan92/Rukopys-OCR-4B
---

# Rukopys OCR Space

A ZeroGPU Gradio demo for [Rukopys-OCR-4B](https://huggingface.co/ebinan92/Rukopys-OCR-4B), an open vision-language model for Ukrainian handwritten document OCR.

Upload a scanned or photographed page, select a page from a PDF, or paste a public image/PDF URL to receive:

- an annotated preview of detected document regions;
- structured JSON with normalized bounding boxes, region types, and transcriptions;
- the unmodified model response for inspection.

PDFs are rendered at 180 DPI using Poppler. Choose a page with the PDF page control and run OCR; processing one page at a time keeps ZeroGPU requests within practical queue and runtime limits.

Images are dynamically bounded to the model's recommended 256–4096 visual-token range. After each request, the app reports preparation, preprocessing/transfer, generation, and output-processing times along with input, vision, and generated token counts. These measurements start after ZeroGPU grants the GPU, so they do not include queue wait.

The model uses PyTorch SDPA for attention. PyTorch's generated kernels are cached under writable runtime storage because ZeroGPU's default cache is read-only.

Remote files are limited to 25 MB. URL loading accepts only public HTTP(S) destinations and rejects private, loopback, and reserved network addresses.

## Deployment

Create a Gradio Space, upload these files, and select **Settings → Hardware → ZeroGPU**. The `suggested_hardware` field documents the intended hardware but does not assign it automatically.

The model is loaded on CUDA at startup and inference is wrapped with `@spaces.GPU`, following the ZeroGPU execution model. Model files are preloaded during the Space build to avoid downloading the checkpoint after startup.

## API

The named Gradio endpoint is `/recognize`. Once deployed, Gradio exposes its input and output schema through the Space's **Use via API** link.

## License

The upstream model is released under the Apache License 2.0. See the [model card](https://huggingface.co/ebinan92/Rukopys-OCR-4B) for training-data licenses and attribution.