pro-ledin-ocr 0.1.0__tar.gz

pro_ledin_ocr-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env
+*.env
+
+uv.lock

pro_ledin_ocr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mxl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pro_ledin_ocr-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+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

pro_ledin_ocr-0.1.0/README.md

@@ -0,0 +1,78 @@
+# 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

pro_ledin_ocr-0.1.0/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: ocr
+description: >
+  Extract text from scanned PDFs and images (PNG/JPG/TIFF/HEIC) using OCR. Use
+  this skill whenever a PDF's text cannot be selected or copied, the document is a
+  scan or photo, text is rendered as images rather than a selectable layer, or the
+  file is a receipt, screenshot, fax, ID card, form, or presentation slide image.
+  Also use for non-English and Cyrillic-language scans, when pdftotext or pypdf
+  return empty or garbled output, or when a user says "this PDF has no text" or
+  "I can't copy from this file". Handles language auto-detection, deskew and
+  denoise for messy scans, tables and charts via vision escalation, and produces
+  Markdown plus plain-text output. Always reach for this skill before giving up on
+  a document that appears to have no readable text.
+---
+
+# OCR Skill
+
+Extracts text from scanned PDFs and images using a layered engine stack.
+The baseline path runs with zero additional installs (poppler + tesseract are
+assumed present). Heavier tools are added only when a page needs them.
+
+## Installation
+
+```bash
+pip install pro-ledin-ocr            # baseline (tesseract + poppler on PATH)
+pip install "pro-ledin-ocr[vision]"  # + OpenAI-compatible vision-api engine
+pip install "pro-ledin-ocr[all]"     # + pymupdf, opencv, easyocr, paddleocr
+```
+
+System binaries still required for the local path: `poppler` (pdftoppm,
+pdftotext, pdfinfo) and `tesseract`. Installs the `ocr` and `ocr-probe`
+console scripts.
+
+## When to use this skill
+
+- PDF where text cannot be selected/copied in a viewer
+- PDF produced by scanning a paper document or photographing a page
+- Office-generated PDF where text is rasterized into image masks (common with
+  some Word/PowerPoint exports — `pdftotext` returns near-empty output)
+- Any standalone image file containing text (PNG, JPG, TIFF, HEIC, WEBP)
+- Non-English documents, especially Cyrillic/Russian
+- Receipts, invoices, forms, ID cards, screenshots of documents
+- When a previous attempt with `pdftotext`, `pypdf`, or `pdfplumber` failed
+
+## Decision tree
+
+Work through this in order. Stop at the first successful step.
+
+```
+1. Is input an image (png/jpg/tiff/heic/webp)?
+   └─ Yes → OCR directly (skip probe). Go to step 3.
+
+2. PDF input: run ocr-probe FILE
+   ├─ needs_ocr = false  → real text layer exists.
+   │   Run: pdftotext -layout FILE -  (or PyMuPDF get_text())
+   │   Done — fast, free, no OCR needed.
+   └─ needs_ocr = true   → continue to step 3.
+
+3. Baseline OCR:
+   ocr FILE --format all
+   (auto-detects language via OSD, DPI from page size, preprocessing level)
+   Emits: FILE.md  FILE.txt  FILE_ocr.json
+   quality report on stderr: per-page confidence, flagged pages.
+
+4. Review quality report. Escalate flagged pages only:
+   ├─ low confidence OR tables/charts/forms
+   │   → ocr FILE --engine vision --pages <flagged>
+   │     Renders persistent PNGs and hands them to the current multimodal agent
+   │     to read (Claude, GPT, or another model with image/file reading).
+   │     Agent produces Markdown (use Markdown table syntax for tables).
+   ├─ CJK / multilingual / angled dense text
+   │   → ocr FILE --engine paddleocr
+   │     (opt-in; installs paddleocr+paddlepaddle, downloads models on first run)
+   ├─ handwriting detected (very low conf, cursive)
+   │   → ocr FILE --engine easyocr
+   └─ skewed/noisy scan (scanned paper, phone photo)
+       → ocr FILE --preprocess full
+
+5. Need a selectable/searchable PDF?
+   → ocr FILE --searchable-pdf OUT.pdf
+     (requires: brew install ocrmypdf)
+
+6. Processing a folder or re-running repeatedly?
+   → ocr FILE1 FILE2 … --cache ocr_cache.json
+     Add --skip-ocr to triage-only mode (skip OCR, text-layer files only).
+     Add --force to ignore cache and re-process.
+```
+
+## Quick start (90% of cases)
+
+```bash
+# Probe first to confirm OCR is needed
+ocr-probe myfile.pdf
+
+# Extract everything (md + txt + json quality report)
+ocr myfile.pdf --format all
+
+# Image input
+ocr scan.png --format all
+
+# Russian/Cyrillic doc — language auto-detected, but can be forced
+ocr russian_doc.pdf --lang rus+eng --format md
+
+# Messy scan (skewed, noisy)
+ocr scan.pdf --preprocess full --format all
+
+# Table-heavy slide / complex layout → vision tier
+ocr slides.pdf --engine vision
+
+# CJK / multilingual doc → PaddleOCR (opt-in)
+ocr doc.png --engine paddleocr
+
+# Headless vision via an OpenAI-compatible endpoint (all config via flags)
+ocr slides.pdf --engine vision-api \
+  --vision-api-url https://api.example.com/v1 \
+  --vision-api-key "$MY_KEY" --vision-model my-vision-model
+```
+
+For `vision-api`, page images over ~7.5 MB are auto-re-encoded to JPEG (full
+resolution first, dimensions reduced only if still too large) to stay under
+the API's 10 MB per-image cap; this re-encode path requires Pillow. Images
+already under the limit are sent untouched with their detected media type.
+
+## Engine tiers (summary)
+
+| Tier | Engine | Best for | Cost |
+|------|--------|----------|------|
+| 0 | pdftotext / PyMuPDF | Real text layers | Free, instant |
+| 1 | tesseract (default) | Clean scans, typed text, 160+ languages | Free, ~3–4s/page |
+| 2 | easyocr | Handwriting, degraded scans | Free, heavy (~2 GB) |
+| 2.5 | paddleocr (opt-in) | CJK, multilingual (100+), angled text | Free, models on first run |
+| 3 | vision (agent reads PNGs) | Tables, charts, complex layouts | Agent/model tokens |
+| 4 | cloud APIs | High-volume, max accuracy | Paid + key |
+
+See `references/engines.md` for full details, escalation thresholds, language
+maps, DPI guidance, preprocessing levels, and install commands.
+
+## Output formats
+
+| Flag | Output |
+|------|--------|
+| `--format md` | `# filename` + `## Page N` headers, prose text |
+| `--format txt` | pages separated by `----- Page N -----` |
+| `--format json` | per-page text + word confidence + bboxes + quality report |
+| `--format all` | all three formats written to disk |
+| `--searchable-pdf OUT` | invisible text layer overlaid on original PDF |
+
+## All CLI flags
+
+```
+ocr INPUT [INPUT ...]
+  --engine   auto|tesseract|easyocr|paddleocr|vision|vision-api   default: auto
+  --lang     auto|<tesseract codes>           default: auto (OSD detection)
+  --format   md|txt|json|all                 default: md
+  --out      PATH                            default: stdout (md/txt) or ./
+  --dpi      N|auto                          default: auto (300 A4, 150 wide)
+  --preprocess  none|basic|enhanced|full|auto  default: auto
+  --pages    RANGE  (e.g. 1-3,5)
+  --max-pages N
+  --psm      N      (default 3; use 6 for dense single-block pages)
+  --min-conf F      (default 60.0 — flag pages below this for review)
+  --cache    PATH   --force   --skip-ocr
+  --no-cleanup      (skip whitespace / ligature cleanup)
+  --vision-api-url  URL   (OpenAI-compatible base URL for vision-api)
+  --vision-api-key  KEY   (required for vision-api; env vars are NOT read)
+  --vision-model    NAME  (required for vision-api; no default)
+  --searchable-pdf OUT.pdf
+  --json-report PATH
+  --verbose
+```
+
+## Library usage
+
+The package also works as an importable library for other skills/scripts that
+want structured OCR results in-process instead of shelling out to the CLI:
+
+```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(path, options=None, *, caps=None, cache=None)` is the entry
+  point: it manages a throwaway render directory and returns the same
+  per-page dicts the CLI builds internally. Format the result with
+  `to_markdown()`, `to_text()`, or `to_json()`.
+- `RecognizeOptions` mirrors the CLI's recognition flags (`engine`, `lang`,
+  `dpi`, `preprocess`, `pages`, `max_pages`, `psm`, `min_conf`, `no_cleanup`,
+  `force`, `vision_api_url`, `vision_api_key`, `vision_model`, `timeout`,
+  `verbose`). Output-only flags (`--out`, `--format`, `--json-report`,
+  `--searchable-pdf`) are CLI-only and have no library equivalent.
+- `--engine vision` is an interactive agent handoff (renders pages and prints
+  a manifest for a multimodal agent to read) and is not usable via
+  `recognize()`; it raises `OcrError` if requested. Use another engine or the
+  CLI directly.
+- Catch `OcrError` for recoverable failures (unsupported input, missing
+  binaries/packages, vision-api config/request errors) — the library never
+  calls `sys.exit()`, unlike the CLI.
+- For `engine="vision-api"`, `RecognizeOptions.timeout` (seconds) bounds the
+  HTTP request via the openai SDK's own client timeout. Local engines
+  (tesseract/easyocr/paddleocr) run in-process with no external kill switch,
+  since there is no longer a subprocess to terminate on timeout.
+- The `healthos` skill uses this API (via `import`) to recognize family medical
+  documents without spawning a subprocess per file.
+
+## Troubleshooting
+
+See `references/troubleshooting.md` for: rasterized-text PDFs, garbled Cyrillic,
+rotated pages, table/chart handling, handwriting, multi-column layouts, and
+large-folder batch jobs.

pro_ledin_ocr-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pro-ledin-ocr"
+version = "0.1.0"
+description = "Layered OCR workhorse: extract text from scanned PDFs and images (tesseract, PyMuPDF, easyocr, paddleocr, vision-api)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "mxl" }]
+keywords = ["ocr", "pdf", "tesseract", "vision", "text-extraction", "cyrillic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Topic :: Text Processing",
+]
+dependencies = []
+
+[project.optional-dependencies]
+vision = ["openai>=1.0"]
+pdf = ["pymupdf"]
+cv = ["opencv-python", "numpy"]
+pytesseract = ["pytesseract"]
+easyocr = ["easyocr"]
+paddle = ["paddleocr", "paddlepaddle"]
+all = ["openai>=1.0", "pymupdf", "opencv-python", "numpy", "pytesseract", "easyocr", "paddleocr", "paddlepaddle"]
+dev = ["pytest>=8.0", "pillow"]
+
+[project.scripts]
+ocr = "pro.ledin.ocr.cli:main"
+ocr-probe = "pro.ledin.ocr.cli:probe_main"
+
+[project.urls]
+Homepage = "https://github.com/ledin-pro/ocr"
+Repository = "https://github.com/ledin-pro/ocr"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pro"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/pro/ledin/ocr/probe.sh" = "pro/ledin/ocr/probe.sh"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pro",
+    "tests",
+    "references",
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]