README.md

metadata

title: Screener OCR API
emoji: 🔎
colorFrom: blue
colorTo: gray
sdk: docker
app_port: 7860
suggested_hardware: cpu-basic

Screener OCR API

Public CPU-only OCR API for scanned PDFs/images. It returns the same pages_text style array expected by Screener's current PDF pipeline.

API

curl -F "file=@annual-report.pdf" https://YOUR-SPACE.hf.space/ocr

Response:

{
  "pages_text": ["page 1 text", "page 2 text"],
  "page_count": 2,
  "processing_ms": 1234
}

The caller can read only pages_text if it wants to match the existing pipeline exactly.

Local run

docker build -t screener-ocr .
docker run --rm -p 7860:7860 screener-ocr
./scripts/smoke_test.sh http://localhost:7860/ocr tilted_test.pdf

Without Docker:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 7860

You also need the tesseract binary installed locally.

Query options

• dpi: render DPI, default 220. Higher is often more accurate but slower.
• psm: Tesseract page segmentation mode, default 6. Try 4 or 11 for difficult layouts.
• deskew: default true.
• workers: parallel OCR workers, capped by OCR_MAX_WORKERS if set, otherwise by the container CPU quota/cpuset count.
• first_page / last_page: useful for debugging a subset of a large PDF.

Environment variables

• OCR_DPI=220
• OCR_PSM=6
• OCR_LANG=eng
• OCR_MAX_WORKERS: optional override. Defaults to the container CPU quota/cpuset count, falling back to visible host CPU cores.
• OCR_PAGE_TIMEOUT_SECONDS=120
• MAX_UPLOAD_MB=300

Notes

This service intentionally does OCR only. Regular embedded PDF text extraction should stay in the main Screener app.

Deploy to Hugging Face Space

1. Create a new Space on Hugging Face.
2. Choose:
   • Visibility: Public
   • SDK: Docker
   • Hardware: CPU Basic to start; CPU Upgrade if annual reports are too slow.
3. Push this repository to the Space repo:

git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
git add .
git commit -m "Initial OCR API"
git push hf main

Once the Space is running, the OCR endpoint will be:

https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/ocr

FastAPI docs are available at:

https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs