Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
58 commits
Select commit Hold shift + click to select a range
0cede2e
refactor(churro-ocr)!: stop re-exporting template types
s-jse Apr 12, 2026
d1269a6
docs(churro-ocr): clarify setup and provider guidance
s-jse Apr 12, 2026
4089edb
docs(churro-ocr): reorganize CLI-first onboarding
s-jse Apr 12, 2026
acd721e
docs(repo): clarify AGENTS workflow guidance
s-jse Apr 12, 2026
0280bf0
docs(benchmark): add icons for Nanonets and PaddleOCR models
s-jse Apr 13, 2026
bdcc271
docs(benchmark): add Qwen 3.5 9B model results to benchmark leaderboard
s-jse Apr 13, 2026
6b60e34
docs(benchmark): add DeepSeek OCR 2 model icon
s-jse Apr 13, 2026
1fe2f5d
docs: update documentation to include llama.cpp alongside vLLM for mo…
s-jse Apr 13, 2026
44d6c50
feat(providers): add MinerU2.5 OCR backends
s-jse Apr 13, 2026
759a706
test(retry): add tests for retryable connection errors
s-jse Apr 13, 2026
cf8a9b3
docs(benchmark): add GPT-5.4 model to benchmarking example commands
s-jse Apr 13, 2026
f32f783
docs(benchmark): update score formatting to one decimal place
s-jse Apr 13, 2026
40f51e1
docs(benchmark): add GPT-5.4 model to benchmark results
s-jse Apr 13, 2026
18854d1
docs(benchmark): add icons for various models in benchmark results
s-jse Apr 13, 2026
7a3cfa0
feat(retry): implement total timeout budget for retryable API calls
s-jse Apr 13, 2026
d7cf581
docs(benchmark): add icons for Skywork R1V3 and R models
s-jse Apr 13, 2026
3f2b069
docs(benchmark): add GPT-5.4 Mini and MinerU 2.5 models to benchmark …
s-jse Apr 13, 2026
f22bbef
feat(benchmark): add reasoning effort option for litellm and openai-c…
s-jse Apr 13, 2026
3c47e98
feat(providers): add Infinity-Parser 7B support
s-jse Apr 13, 2026
27cc7c5
fix(benchmark): handle timed-out OCR pages gracefully
s-jse Apr 13, 2026
768270b
chore(leaderboard): add GPT-5.4 Nano entry
s-jse Apr 13, 2026
f172755
docs(benchmark): update GPT-5.4 model entries with reasoning=medium
s-jse Apr 13, 2026
9a296a5
feat(benchmark): add Infinity Parser 7B model with logo
s-jse Apr 13, 2026
15e1c18
fix(litellm): stabilize retries and add async cleanup
s-jse Apr 13, 2026
e5b8971
fix(benchmark): close cached LiteLLM clients
s-jse Apr 13, 2026
b8bd19e
fix(evaluation): avoid non-fork multiprocessing pools
s-jse Apr 13, 2026
471e939
fix(providers): harden OCR defaults and Infinity parsing
s-jse Apr 13, 2026
b3f7262
refactor(types): centralize shared OCR structural aliases
s-jse Apr 13, 2026
bb87492
refactor(metadata): reuse shared OCR metadata aliases
s-jse Apr 13, 2026
6587169
test(types): centralize shared fixture helper protocols
s-jse Apr 13, 2026
0fa1147
build(typecheck): tighten lint and package check typing
s-jse Apr 13, 2026
26b20f2
refactor(core): tighten CLI and helper typing
s-jse Apr 13, 2026
2c47a35
refactor(evaluation): tighten OCR API and tooling typing
s-jse Apr 13, 2026
b42f03b
refactor(providers): tighten provider backend typing
s-jse Apr 13, 2026
24c7605
refactor(providers): extract shared OCR processing helpers
s-jse Apr 13, 2026
f1ff519
refactor(page-detection): split provider helper modules
s-jse Apr 13, 2026
a1f4317
refactor(hf): split backend helper modules
s-jse Apr 13, 2026
b2b471a
chore(dependencies): update ruff and ty versions in dev-tooling
s-jse Apr 13, 2026
01a09ac
docs: improve README
s-jse Apr 13, 2026
e2fba9e
refactor(core): simplify complexity hotspots
s-jse Apr 13, 2026
b808cbe
chore(ruff): enable complexity checks
s-jse Apr 13, 2026
988480c
docs: improve README layout
s-jse Apr 13, 2026
e338576
feat(providers): add GLM-OCR support
s-jse Apr 13, 2026
4c1981b
fix(internal): handle unmapped LiteLLM models
s-jse Apr 13, 2026
3aa0ada
style(repo): apply formatting cleanup
s-jse Apr 13, 2026
ff7d323
docs(leaderboard): add GLM OCR entry and logo
s-jse Apr 13, 2026
8918b2e
feat(leaderboard): enhance benchmark leaderboard with expandable per-…
s-jse Apr 13, 2026
588e4cd
feat(providers): add FireRed-OCR support
s-jse Apr 14, 2026
4004778
docs(api): document canonical reference modules
s-jse Apr 14, 2026
b483623
docs(leaderboard): add FireRed results and simplify icons
s-jse Apr 14, 2026
bda01c5
feat(providers): add Nanonets OCR2 support
s-jse Apr 14, 2026
ddd5dc7
docs(leaderboard): add Nanonets OCR 2 benchmark result
s-jse Apr 14, 2026
59b36a5
feat(providers): add Qianfan OCR support
s-jse Apr 14, 2026
51a5c3d
docs(leaderboard): add Qianfan OCR benchmark result
s-jse Apr 14, 2026
93be7c6
docs(benchmark): add Step 3 VL benchmark results
s-jse Apr 15, 2026
7586317
docs(benchmark): add icon for Step 3 VL model
s-jse Apr 15, 2026
926096f
docs(benchmark): add Gemma 4 (E2B) model results
s-jse Apr 15, 2026
b1e9475
docs(benchmark): add Gemma 4 (E4B) model results
s-jse Apr 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# AGENTS

This repo is `churro-ocr`, a Python 3.12 OCR and page-detection toolkit for historical documents.
This repo is `churro-ocr`, a Python 3.12+ OCR and page-detection toolkit for historical documents.

## Repo Layout

Expand All @@ -23,6 +23,8 @@ pixi run docs-build
pixi run package-check
```

After each change, review docs to see if it needs updating and run the relevant Pixi tasks to check your work.

## Guardrails

- Prefer the Pixi tasks above over ad hoc commands.
Expand Down
58 changes: 43 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,55 @@
# <img src="static/churro.png" alt="CHURRO logo" width="40" /> CHURRO
<div align="center">

[![Model](https://img.shields.io/badge/Model-CHURRO%203B-8A4FFF)](https://huggingface.co/stanford-oval/churro-3B)
[![Dataset](https://img.shields.io/badge/Dataset-CHURRO--DS-0A7BBB)](https://huggingface.co/datasets/stanford-oval/churro-dataset)
[![Paper](https://img.shields.io/badge/Paper-arXiv-B31B1B)](https://arxiv.org/abs/2509.19768)
[![Docs](https://img.shields.io/badge/Docs-Documentation-8B451F)](https://stanford-oval.github.io/Churro/)
[![Leaderboard](https://img.shields.io/badge/Leaderboard-Benchmark%20Snapshot-6B7280)](https://stanford-oval.github.io/Churro/leaderboard.html)
[![GitHub Stars](https://img.shields.io/github/stars/stanford-oval/churro?style=social)](https://github.com/stanford-oval/churro/stargazers)
# <img src="static/churro.png" alt="CHURRO logo" width="40" /> Churro

CHURRO is an OCR toolkit for historical document transcription, built to make handwritten and printed sources readable at high accuracy and lower cost.
</div>

It works with all major OCR providers and vision-language models, and provides first-party support for the CHURRO 3B model and CHURRO-DS dataset.
<p align="center">
<a href="https://huggingface.co/stanford-oval/churro-3B">🤗 Model</a> •
<a href="https://huggingface.co/datasets/stanford-oval/churro-dataset">🗂️ Dataset</a> •
<a href="https://arxiv.org/abs/2509.19768">📄 Paper</a>
<br/><br/>
<a href="https://stanford-oval.github.io/Churro/">📚 Docs</a> •
<a href="https://stanford-oval.github.io/Churro/leaderboard.html">🏆 Leaderboard</a> •
<a href="https://github.com/stanford-oval/churro/stargazers">
<img src="https://img.shields.io/github/stars/stanford-oval/churro?style=social" alt="GitHub Stars badge" />
</a>
</p>

Churro is the fastest way to turn hard-to-read historical scans into reliable text. It gives researchers, libraries, archives, and product teams a unified OCR toolkit for handwritten and printed sources, combining high accuracy, low operating cost, and a clean Python API and CLI workflow.

## Supported OCR Models and Backends

Churro includes built-in profiles, templates, and post-processing for many OCR models and integrations, including:

- Hosted vision-language models, including Gemini, GPT, Claude, and more, through LiteLLM integration
- OpenAI-compatible servers, including vLLM, Ollama, TGI, and more
- Azure Document Intelligence
- Mistral OCR
- `Chandra OCR`
- `DeepSeek OCR`
- `Dots OCR`
- `MinerU`
- `Infinity Parser`
- `PaddleOCR VL`
- `LFM VL`

- CHURRO 3B exceeds the accuracy of Gemini 2.5 Pro at 15.5x lower cost.
- CHURRO-DS contains ~100K pages from 155 historical collections spanning 22 centuries and 46 language clusters.
## Churro Model and Dataset

We also provide first-party support for a purpose-trained model and dataset for historical OCR:

- Churro 3B VLM exceeds the accuracy of Gemini 2.5 Pro at 15.5x lower cost.
- Churro-DS dataset contains ~100K pages from 155 historical collections spanning 22 centuries and 46 language clusters.

<p align="center">
<img src="static/performance_cost.png" alt="Cost vs Performance comparison showing CHURRO's accuracy advantage at significantly lower cost" width="75%" />
<img src="static/performance_cost.png" alt="Cost vs Performance comparison showing Churro's accuracy advantage at significantly lower cost" width="75%" />
<br/>
<sub><i>Cost vs. accuracy: CHURRO (3B) achieves higher accuracy than much larger commercial and open-weight VLMs while being substantially cheaper.</i></sub>
<sub><i>Cost vs. accuracy: Churro (3B) achieves higher accuracy than much larger commercial and open-weight VLMs while being substantially cheaper.</i></sub>
</p>

## Quick Try
## Quick Start

Python 3.12+ and `uv` are required.

```bash
uv tool install churro-ocr
Expand All @@ -46,6 +74,6 @@ If you use CHURRO or CHURRO-DS, please cite:

## License

- Code: Apache 2.0
- Model weights: Qwen research license
- Dataset: research use only because of the underlying source licenses
- Code: Apache 2.0
Loading