CleanOCR

Turn scans of old books into clean, reviewable text — on your own machine.

This tool runs marker (and optionally five other OCR engines) over a PDF, shows you the result next to the original scan, lets a local LLM propose corrections that you accept or reject page by page, measures error rates against a reference transcription, and typesets the result back into a clean PDF. It was built to digitize an 1890 French printing manual, which ships with the repo as a working sample.

Everything runs locally except the optional Mistral cloud engine. No accounts, no telemetry.

What you need

• macOS or Windows (Linux works too, using the manual install). On macOS, Apple Silicon runs marker on the GPU; on Windows, an NVIDIA GPU is used if present, otherwise CPU (slower but fine for a few pages).
• ~10 GB of disk for the Python environment and marker's models (~3 GB, downloaded on the first run).
• Optional, for LLM corrections and cleanup: Ollama and a vision model. The default, qwen3.5:27b, is a ~20 GB download and wants ~24 GB of RAM or VRAM. Everything else works without it.

Install and run

macOS — in Terminal, from the project folder:

./install.sh
./start.sh

Windows — in PowerShell, from the project folder:

powershell -ExecutionPolicy Bypass -File install.ps1

then double-click start.cmd.

The installer checks for its two tools (uv and Node) and offers to install anything missing. The big optional downloads (Ollama models, Tesseract, PDF-export libraries on Windows) are asked about one by one, with sizes — nothing large is downloaded silently. Rerun the installer anytime to add an extra you skipped.

start launches the app at http://localhost:8000 and opens your browser. Pick the sample book, launch a marker run on pages 20–30, and you'll see results in a couple of minutes.

Manual install (if you'd rather not run a script)

uv sync --extra ocr                       # Python deps, several GB (torch)
(cd ui && npm ci && npm run build)        # build the frontend, needs Node 20.19+
uv run python scripts/fetch_reference.py  # reference text for the Benchmark tab
cp .env.example .env
uv run uvicorn server.main:app --port 8000

Optional extras: ollama pull qwen3.5:27b (LLM corrections), ollama pull deepseek-ocr, Tesseract with French data (brew install tesseract tesseract-lang on macOS).

What's in the app

The Help tab inside the app carries the full user guide. In short:

• Viewer — each OCR'd page rendered beside the original scan, with PDF export.
• Review — a local LLM checks each page against the scan and proposes corrections; you accept, reject, edit, or retry, page by page. Decisions are saved and resumable; the original text is never touched.
• Benchmark — CER/WER/similarity of a run against a reference transcription or another run, with an inline word diff.
• Models — the same pages run through several engines, compared side by side.

OCR engines

Engine	What it is	Setup
marker	surya OCR pipeline, the default	none — installed with the app
marker + LLM	marker plus per-page corrections from a local vision model	Ollama + ollama pull qwen3.5:27b
DeepSeek-OCR	small dedicated vision OCR model	Ollama + ollama pull deepseek-ocr
docling	IBM's document conversion pipeline	none — installed with the app
Tesseract	the classic OCR baseline	macOS: brew install tesseract tesseract-lang · Windows: installer prompt
qwen3.5 direct	page image straight to the vision model, no OCR pipeline	uses the pulled qwen model
Mistral OCR	cloud API — pages leave your machine	MISTRAL_API_KEY in .env

Every engine writes the same output format, so the whole app works identically whichever you pick. Configuration (Ollama address, model names, torch device) is in .env — see .env.example.

Known limitations

• The LLM correction prompts and the running-header detection are tuned to the bundled 1890 French manual. Other books get a more generic correction quality — audit the auto-accepted pages before trusting them.
• The bundled reference text is the Internet Archive's own OCR, so Benchmark scores against it measure agreement, not absolute accuracy.
• PDF export needs WeasyPrint's native libraries. The installers set this up (Homebrew's Pango on macOS, MSYS2's on Windows); if you skipped that step the Export button is greyed out and the WeasyPrint install docs are the fix. With MSYS2 in a non-default location, set WEASYPRINT_DLL_DIRECTORIES to its mingw64\bin folder.
• CPU-only OCR of a full book is slow — try a page range first.

Development

Backend: FastAPI (server/), one subprocess per OCR run. Frontend: Svelte 5 + Vite (ui/). Tests: uv run pytest — they run without the heavy OCR deps (uv sync alone is enough). Dev servers with hot reload: scripts/dev.sh or scripts/dev.ps1.

Architecture, the engine-driver contract, API reference, and how to add an engine: docs/development.md. Contributions: CONTRIBUTING.md.

License

MIT.