Metadata-Version: 2.4
Name: ocrroute
Version: 0.8.0
Summary: OCR gateway: one API in front of 56 OCR engines (Tesseract, PaddleOCR, EasyOCR, Surya, Mistral OCR, Google Vision, OCR.Space, Claude/GPT/Gemini and other vision models) with routing, automatic fallback, a web dashboard, a desktop app and multi-server clusters.
Author: Usama (Usama01TN)
Maintainer: Usama (Usama01TN)
License-Expression: MIT
Project-URL: Homepage, https://github.com/Usama01TN/OcrRoute
Project-URL: Repository, https://github.com/Usama01TN/OcrRoute
Project-URL: Documentation, https://github.com/Usama01TN/OcrRoute/tree/main/docs
Project-URL: Changelog, https://github.com/Usama01TN/OcrRoute/blob/main/docs/CHANGELOG.md
Project-URL: Issues, https://github.com/Usama01TN/OcrRoute/issues
Project-URL: Releases, https://github.com/Usama01TN/OcrRoute/releases
Project-URL: Funding, https://ko-fi.com/usamatn
Keywords: ocr,gateway,routing,fallback,fastapi,tesseract,paddleocr,easyocr,vision-language-model,self-hosted
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: FastAPI
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Text Processing
Classifier: Environment :: Web Environment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: alembic>=1.13
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13
Requires-Dist: structlog>=24
Requires-Dist: cryptography<49,>=42; sys_platform == "darwin" and platform_machine == "x86_64"
Requires-Dist: cryptography>=42; sys_platform != "darwin" or platform_machine != "x86_64"
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: jinja2>=3.1
Requires-Dist: itsdangerous>=2.1
Requires-Dist: argon2-cffi>=23
Requires-Dist: httpx>=0.26
Requires-Dist: requests>=2.31
Requires-Dist: pillow>=10
Requires-Dist: numpy>=1.24
Requires-Dist: openpyxl>=3.1
Requires-Dist: prometheus-client>=0.19
Requires-Dist: pypdfium2>=4.20
Provides-Extra: api
Requires-Dist: requests>=2.31; extra == "api"
Requires-Dist: mistralai>=1.0; extra == "api"
Provides-Extra: local
Requires-Dist: pytesseract>=0.3.10; extra == "local"
Requires-Dist: opencv-python-headless>=4.8; extra == "local"
Provides-Extra: easyocr
Requires-Dist: easyocr>=1.7; extra == "easyocr"
Provides-Extra: surya
Requires-Dist: surya-ocr<0.20,>=0.17; extra == "surya"
Requires-Dist: transformers<5,>=4.56.1; extra == "surya"
Provides-Extra: surya2
Requires-Dist: surya-ocr>=0.20; extra == "surya2"
Provides-Extra: transformers
Requires-Dist: transformers>=4.45; extra == "transformers"
Requires-Dist: torch>=2.4; extra == "transformers"
Requires-Dist: accelerate>=0.33; extra == "transformers"
Provides-Extra: olmocr
Requires-Dist: olmocr>=0.4; extra == "olmocr"
Requires-Dist: transformers>=4.45; extra == "olmocr"
Requires-Dist: torch>=2.4; extra == "olmocr"
Requires-Dist: pypdf>=4; extra == "olmocr"
Provides-Extra: paddle
Requires-Dist: paddleocr>=3.0; extra == "paddle"
Requires-Dist: paddlepaddle>=3.0; extra == "paddle"
Provides-Extra: calamari
Requires-Dist: calamari-ocr>=2.3; extra == "calamari"
Requires-Dist: tensorflow>=2.15; extra == "calamari"
Provides-Extra: keras
Requires-Dist: keras-ocr>=0.9; extra == "keras"
Provides-Extra: vlm
Requires-Dist: ocrroute[transformers]; extra == "vlm"
Provides-Extra: torch
Requires-Dist: ocrroute[easyocr,surya,transformers]; extra == "torch"
Provides-Extra: desktop
Requires-Dist: ManyQt>=0.4.5; extra == "desktop"
Requires-Dist: PyQt5>=5.15; extra == "desktop"
Requires-Dist: keyring>=24; extra == "desktop"
Provides-Extra: all
Requires-Dist: ocrroute[api,desktop,local]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: respx>=0.20; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Dynamic: license-file

# OcrRoute

**OcrRoute is an OCR gateway for multi-engine text extraction: one HTTP endpoint in front of local
and cloud OCR engines, with routing, load balancing, retries and fallbacks - plus quotas, caching,
cost tracking and observability for reliable, cost-aware document understanding.**
It imports the given `AioOCR` engine library **unchanged** (55 `OCRPlugin` classes: Tesseract, RapidOCR, PaddleOCR, Surya,
GOT-OCR, DeepSeek-OCR, Nougat, OCR.Space, Google Vision, Mistral OCR, Gemini/Claude/OpenAI-style VLM
OCR, …) in a FastAPI gateway with a web control panel, a desktop app (ManyQt: PyQt5 / PyQt6 / PySide2 / PySide6) and a CLI. Persistence is
a single SQLite file.

```
pip install "ocrroute[local,desktop]"   # from PyPI: core + Tesseract/OpenCV extras + the desktop app
# or, from a clone:
pip install -e ".[local,desktop,dev]"   # core + Tesseract/OpenCV extras + ManyQt + PyQt5 + tests
ocrroute setup                          # admin user, first provider, default route, API key
ocrroute serve                          # API  http://127.0.0.1:20256/v1/docs
                                        # panel http://127.0.0.1:20256/panel/
ocrroute ocr scan.png                   # zero-config OCR through the built-in auto route
ocrroute desktop                        # PyQt5 app (embedded server or remote)
```

```bash
curl -X POST http://127.0.0.1:20256/v1/ocr \
  -H "Authorization: Bearer ocrr_…" \
  -F file=@invoice.pdf \
  -F 'json={"route":"invoices","language":"en","pages":"1-3","output":["json","text","pdf"]}'
```

The response keeps the engine library's unified result **verbatim** under `result` and adds gateway
metadata beside it (`routing.attempts`, `routing.explain`, `usage`, `artifacts`). See
[docs/API.md](docs/API.md).

## Screenshots:

**Playground**: run any engine or route on an image or PDF and inspect the result as text, lines, JSON, routing or
ready-to-use code, with the recognised words drawn over the input.

![OcrRoute Playground: OCR.Space result with word boxes over the input and the JSON result](docs/screenshots/playground.png)

**Engines**: every detected OCR engine, cloud and local, with availability, capabilities, pricing model, per-engine
options, one-click provider creation and a probe button.

![OcrRoute Engines page: cards for each detected engine with availability, capabilities and actions](docs/screenshots/engines.png)

## What you get:

| Area | Highlights |
|---|---|
| Routing | Built-in `auto/*` catalog (balanced, fast, accurate, cheapest, free, private, handwriting, tables, pdf, multilingual, consensus, best-of-two) plus named **Routes** (fallback chains) with 18 strategies: priority, round-robin, weighted, fill-first, least-used, least-latency, P2C, random, cost-optimised, local-first, quality-first, language-aware, ensemble-vote, auto (explainable). |
| Reliability | Bounded retries, per-provider circuit breaker with escalating cooldown, deadlines, credential rotation on auth/quota errors, terminal-error short-circuit, degraded partial results. |
| Control | Providers, encrypted credentials (Fernet), client API keys with scopes/RPM/RPD/budgets, panel users with roles (admin / operator / viewer), runtime settings, audit log, graceful restart / shutdown. |
| Cost & quotas | Per-engine price table, per-run cost estimate, monthly budgets per provider and per key, sliding-window limits. |
| Cache & dedupe | Result cache keyed by input hash + target + options, idempotency keys, in-flight single-flight. |
| Inputs / outputs | Path, URL (SSRF-guarded), base64, upload, PDF page ranges; exports: json, text, md, hOCR, ALTO, csv, xlsx, docx, searchable PDF, overlay PNG. |
| Observability | Runs & attempts in SQLite, live SSE feed, Prometheus `/metrics`, `doctor` diagnostics with copyable system report. |
| UIs | Web control panel (12 pages, **Bootstrap 5** + Bootstrap Icons vendored for offline use, mobile-first with an offcanvas sidebar) · PyQt5 desktop (10 pages, embedded/remote, region capture, overlay viewer, tray) · Typer CLI. Both UIs: **light / dark / system themes**, **English · Français · Español · Deutsch · Italiano · Português · Русский · 中文 · العربية (RTL)**, onboarding checklist, humanised times. |
| Endpoints | Active endpoints with copy, all LAN URLs, tunnels (Cloudflare / Tailscale / ngrok) with install / enable / disable, public URL, global OCR prompt, server restart / shutdown. |
| Auto-detection | Every `OCRPlugin` in `AioOCR` is discovered by the library's own discovery, seeded as a provider, and re-detected live when modules are added or dependencies installed (file watcher + periodic rescan). |
| Tools | Reserved, intentionally empty extension point (`/v1/tools`, `ocrroute/tools`, empty-state pages). See [docs/TOOLS.md](docs/TOOLS.md). |

## Several servers:

Run one **leader** and any number of **followers**: followers mirror the leader's providers, credentials, routes,
API keys and users. Set it up from the web panel (**System > Cluster sync**) or with `.env`; see `docs/CLUSTER.md`.

## Editions and more engines:

The stand-alone executables come in two editions:

| Edition | Files | Engines | Unpacked size |
|---|---|---|---|
| **Lean** | `ocrroute-server-*`, `ocrroute-desktop-*` | 49 of 56: every engine without a deep-learning framework (Tesseract, RapidOCR, Mistral OCR, all cloud engines) | ~150 MB |
| **Full** | `ocrroute-server-full-*`, `ocrroute-desktop-full-*` | Lean + **EasyOCR** and **Surya** (PyTorch, CPU) + **PaddleOCR** (PaddlePaddle) | ~1.7 GB |

On Intel Macs the Full edition includes PaddleOCR but not EasyOCR or Surya: PyTorch publishes no Intel-Mac build newer
than 2.2, which predates NumPy 2. EasyOCR, Surya and PaddleOCR download their model weights on first use.

**Surya** is bundled as 0.17.1, the last release that runs OCR entirely in PyTorch; Surya 2 (0.20+) needs a vLLM or
llama.cpp server (`pip install "ocrroute[surya2]"`). Surya's code is Apache-2.0, but its **model weights** use a
modified AI Pubs Open Rail-M license: free for research, personal use and startups under $5M in funding or revenue;
other commercial use needs a license from Datalab.

The remaining deep-learning engines (Calamari, keras-ocr, GLM, olmOCR) install on demand in a pip
installation: click **Install** in the Engines page, run `ocrroute engines install SuryaOcr`, or
`pip install "ocrroute[surya]"`. See `docs/ENGINES.md`.

## Documentation:

`docs/ARCHITECTURE.md` · `docs/ROUTING.md` · `docs/API.md` · `docs/ENGINES.md` · `docs/DEPLOYMENT.md` ·
`docs/SECURITY.md` · `docs/TOOLS.md` · `docs/DECISIONS.md` · `docs/CHANGELOG.md`

## Independence note:

Design patterns for gateway routing (fallback chains, balancing strategies, key management, dashboards)
are widely used in the ecosystem; OcrRoute applies them to OCR. OcrRoute is an independent Python project
with its own namespace (`ocrroute`, `~/.ocrroute`, `OCRROUTE_*`), its own default port (**20256**; it
refuses to bind 20128), and no chat/completions, LLM proxying or agent-protocol surface. It is not a fork,
plugin or companion of any other gateway.

## Desktop app and Qt:

The desktop app is written against [ManyQt](https://github.com/Usama01TN/ManyQt), one API over PyQt4/5/6 and
PySide/2/6. The executables ship PyQt5; from source, `pip install "ocrroute[desktop]"` installs ManyQt with PyQt5, and
any other installed binding works too (`QT_API=pyqt6`, `QT_API=pyside6`...). ManyQt is GPL-3.0, like PyQt5.

## Support the project:

OcrRoute is free and open source. If it saves you time or money, you can support its development:

[![Support on ba9chich](https://img.shields.io/badge/Support-ba9chich-2ea44f?style=for-the-badge)](https://ba9chich.com/fr/IninouUsama)
[![Support on Ko-fi](https://img.shields.io/badge/Support-Ko--fi-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/usamatn)

- **ba9chich:** https://ba9chich.com/fr/IninouUsama
- **Ko-fi:** https://ko-fi.com/usamatn

Stars, bug reports and pull requests help too. Thank you!

## Third-party assets:

`ocrroute/assets/fonts/DejaVuSans.ttf` is DejaVu Sans (Bitstream Vera license; see `LICENSE-DejaVu.txt` next to it),
used by PaddleOCR for visualisations.

## License:

MIT - see `LICENSE`.
