Metadata-Version: 2.4
Name: churro-ocr
Version: 0.3.0
Summary: OCR and page detection for historical documents
Author: History Genie
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/stanford-oval/Churro
Project-URL: Documentation, https://stanford-oval.github.io/Churro/
Project-URL: Repository, https://github.com/stanford-oval/Churro
Project-URL: Issues, https://github.com/stanford-oval/Churro/issues
Keywords: ocr,layout-detection,historical-documents,llm
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: loguru<1,>=0.7.2
Requires-Dist: Pillow<12,>=10.4.0
Requires-Dist: rich<14,>=13.9.2
Requires-Dist: tenacity<10,>=9.0.0
Requires-Dist: typer<1,>=0.12.3
Provides-Extra: llm
Requires-Dist: google-auth<3,>=2.41.1; extra == "llm"
Requires-Dist: litellm[caching]==1.82.3; extra == "llm"
Provides-Extra: azure
Requires-Dist: azure-ai-documentintelligence==1.0.2; extra == "azure"
Provides-Extra: hf
Requires-Dist: qwen-vl-utils; extra == "hf"
Requires-Dist: transformers<6,>=5; extra == "hf"
Provides-Extra: mistral
Requires-Dist: mistralai<2,>=1.6.0; extra == "mistral"
Provides-Extra: local
Requires-Dist: litellm[caching]==1.82.3; extra == "local"
Provides-Extra: pdf
Requires-Dist: pypdfium2<6,>=5; extra == "pdf"
Provides-Extra: all
Requires-Dist: google-auth<3,>=2.41.1; extra == "all"
Requires-Dist: litellm[caching]==1.82.3; extra == "all"
Requires-Dist: azure-ai-documentintelligence==1.0.2; extra == "all"
Requires-Dist: qwen-vl-utils; extra == "all"
Requires-Dist: transformers<6,>=5; extra == "all"
Requires-Dist: mistralai<2,>=1.6.0; extra == "all"
Requires-Dist: pypdfium2<6,>=5; extra == "all"
Dynamic: license-file

# churro-ocr

`churro-ocr` is a Python toolkit for OCR and page detection on historical documents.

Full documentation and project overview live at https://stanford-oval.github.io/Churro/.

## Install

For the CLI-first workflow used in the docs, install Churro with UV as a tool.

```bash
uv tool install churro-ocr
```

If you are adding `churro-ocr` to a project instead, use `uv add churro-ocr` and prefix CLI commands with `uv run`.

Runtime setup and provider-specific install commands are in
[Getting Started](https://stanford-oval.github.io/Churro/getting-started.html)
and
[Providers And Configuration](https://stanford-oval.github.io/Churro/guides/providers.html).

## Which API Should You Use?

| Goal | API |
| --- | --- |
| OCR one page or one image | `OCRClient` |
| Detect page crops only | `DocumentPageDetector` |
| Run an end-to-end image or PDF OCR workflow | `DocumentOCRPipeline` |
| Tune backend/provider options directly | `build_ocr_backend(...)` + `OCRBackendSpec` |

## Quick Start

This example assumes you already installed the runtime for the provider you want to use.

```python
from churro_ocr.ocr import OCRClient
from churro_ocr.providers import OCRBackendSpec, build_ocr_backend

backend = build_ocr_backend(
    OCRBackendSpec(
        provider="litellm",
        model="vertex_ai/gemini-2.5-flash",
    )
)

page = OCRClient(backend).ocr_image(image_path="scan.png")

print(page.text)
```

## More

- Overview: https://stanford-oval.github.io/Churro/
- Getting started: https://stanford-oval.github.io/Churro/getting-started.html
- Benchmark leaderboard: https://stanford-oval.github.io/Churro/leaderboard.html
- Provider setup: https://stanford-oval.github.io/Churro/guides/providers.html
- CLI docs: https://stanford-oval.github.io/Churro/cli.html
- API reference: https://stanford-oval.github.io/Churro/api/index.html
