Metadata-Version: 2.4
Name: pro-ledin-ocr
Version: 0.1.0
Summary: Layered OCR workhorse: extract text from scanned PDFs and images (tesseract, PyMuPDF, easyocr, paddleocr, vision-api).
Project-URL: Homepage, https://github.com/ledin-pro/ocr
Project-URL: Repository, https://github.com/ledin-pro/ocr
Author: mxl
License-Expression: MIT
License-File: LICENSE
Keywords: cyrillic,ocr,pdf,tesseract,text-extraction,vision
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: easyocr; extra == 'all'
Requires-Dist: numpy; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: opencv-python; extra == 'all'
Requires-Dist: paddleocr; extra == 'all'
Requires-Dist: paddlepaddle; extra == 'all'
Requires-Dist: pymupdf; extra == 'all'
Requires-Dist: pytesseract; extra == 'all'
Provides-Extra: cv
Requires-Dist: numpy; extra == 'cv'
Requires-Dist: opencv-python; extra == 'cv'
Provides-Extra: dev
Requires-Dist: pillow; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: easyocr
Requires-Dist: easyocr; extra == 'easyocr'
Provides-Extra: paddle
Requires-Dist: paddleocr; extra == 'paddle'
Requires-Dist: paddlepaddle; extra == 'paddle'
Provides-Extra: pdf
Requires-Dist: pymupdf; extra == 'pdf'
Provides-Extra: pytesseract
Requires-Dist: pytesseract; extra == 'pytesseract'
Provides-Extra: vision
Requires-Dist: openai>=1.0; extra == 'vision'
Description-Content-Type: text/markdown

# pro-ledin-ocr

Layered OCR workhorse: extract text from scanned PDFs and images (PNG/JPG/TIFF/
HEIC/WEBP) using a tiered engine stack. The baseline path (poppler + tesseract)
needs zero extra Python installs; heavier engines are opt-in extras.

- Import name: `pro.ledin.ocr`
- Console scripts: `ocr`, `ocr-probe`
- PyPI: `pro-ledin-ocr`

## Install

```bash
pip install pro-ledin-ocr            # baseline
pip install "pro-ledin-ocr[vision]"  # + OpenAI-compatible vision-api engine
pip install "pro-ledin-ocr[all]"     # + pymupdf, opencv, easyocr, paddleocr
```

System binaries required for the local path: `poppler` (pdftoppm, pdftotext,
pdfinfo) and `tesseract` (with language packs).

```bash
brew install poppler tesseract tesseract-lang      # macOS
sudo apt install poppler-utils tesseract-ocr-all   # Debian/Ubuntu
```

## CLI

```bash
ocr-probe myfile.pdf                          # triage: does it need OCR?
ocr myfile.pdf --format all                   # md + txt + json
ocr scan.png --format md
ocr russian_doc.pdf --lang rus+eng --format md
ocr scan.pdf --preprocess full                # deskew + denoise
ocr slides.pdf --engine vision --pages 9,12   # hand pages to a multimodal agent
ocr slides.pdf --engine vision-api \
  --vision-api-url https://api.example.com/v1 \
  --vision-api-key "$KEY" --vision-model my-vision-model
```

See `ocr --help` for the full flag reference.

## Library

```python
from pro.ledin import ocr

pages = ocr.recognize("scan.pdf", ocr.RecognizeOptions(engine="tesseract", lang="rus+eng"))
markdown = ocr.to_markdown(pages, "scan.pdf")
```

`recognize()` never calls `sys.exit()`; catch `ocr.OcrError` for recoverable
failures (unsupported input, missing binaries/packages, vision-api config).

## Engine tiers

| Tier | Engine | Best for | Cost |
|------|--------|----------|------|
| 0 | pdftotext / PyMuPDF | Real text layers | Free, instant |
| 1 | tesseract (default) | Clean scans, typed text, 160+ languages | Free |
| 2 | easyocr | Handwriting, degraded scans | Free, heavy |
| 2.5 | paddleocr | CJK, multilingual, angled text | Free |
| 3 | vision (agent reads PNGs) | Tables, charts, complex layouts | Agent tokens |
| 3.5 | vision-api (OpenAI-compatible) | Headless batch, complex layouts | API cost |

Full docs: `SKILL.md`, `references/engines.md`, `references/troubleshooting.md`.

## Development

```bash
uv sync --extra dev
uv run --extra dev pytest
uv build
```

## License

MIT
