README.md

---
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

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

Response:

```json
{
  "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

```bash
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:

```bash
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:

```bash
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:

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

FastAPI docs are available at:

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