ocrcontext 0.1.2__tar.gz → 0.1.4__tar.gz

{ocrcontext-0.1.2 → ocrcontext-0.1.4}/CHANGELOG.md

@@ -1,79 +1,103 @@
-# Changelog
-
-All notable changes to **ocrcontext** are documented here.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.1.2] - 2026-06-26
-
-### Fixed
-- CI: disable Rich markup mode in typer (`rich_markup_mode=None`) so help output
-  is plain text on all platforms — Rich's panel renderer produced ANSI escape
-  codes that CliRunner could not strip on Linux, causing `--help` tests to fail.
-- Replace `typing.List` with built-in `list` in schemas for Python 3.12
-  compatibility and to avoid deprecation warnings.
-
-## [0.1.1] - 2026-06-26
-
-### Added
-- **`OCRContextLoader`** — LangChain `BaseLoader` integration. Drop-in loader for
-  any LangChain pipeline: `OCRContextLoader("file.pdf").load()` returns a
-  `Document` with OCR text and metadata (`source`, `text_source`, `pages`,
-  `confidence`, `refined`).
-- **Built-in extraction schemas** — four new ready-to-use Pydantic schemas with
-  system prompts, importable from `ocrcontext.schemas`:
-  - `Receipt` / `ReceiptItem` — store name, date, items, subtotal, tax, total,
-    payment method.
-  - `Contract` / `ContractParty` — parties, effective/expiry dates, value,
-    governing law, key obligations.
-  - `IdCard` — national_id / passport / driver_license / residence_permit with
-    ICD-standard date normalisation and ISO 3166-1 nationality codes.
-  - `MedicalReport` / `Medication` — diagnosis, ICD codes, prescriptions, notes.
-- **CLI** (`ocrcontext extract`) — terminal-first developer experience via the
-  new `[cli]` extra (`pip install "ocrcontext[cli]"`):
-  - `ocrcontext extract invoice.pdf` — plain OCR to stdout.
-  - `ocrcontext extract scan.pdf --schema receipt --output json` — structured
-    extraction as JSON.
-  - `--provider openai|anthropic|ollama|google --model <name>` — bring-your-own
-    LLM provider.
-  - `--handwriting`, `--lang`, `--refine auto|yes|no` flags.
-
-## [0.1.0] - 2026-06-25
-
-Initial release — the document extraction core, decoupled from its web stack
-into a standalone, LLM-agnostic library.
-
-### Added
-- **`Analyzer` facade** — 3-line developer experience:
-  `Analyzer().analyze("file.pdf").text`.
-- **Routing ladder** (`pipeline.py`):
-  - Digital PDFs → PyMuPDF text-layer extraction (no OCR); LLM refine is
-    auto-skipped so exact text/identifiers are never altered.
-  - Images / scanned PDFs → PaddleOCR with image preprocessing, multi-language
-    *coverage-first* candidate selection, and a line-band recovery fallback.
-  - Handwriting (explicit or auto on insufficient text) → Google Vision primary,
-    Microsoft TrOCR fallback.
-  - Multi-page documents joined with `--- Page N ---` separators.
-- **LLM-agnostic LLM layer** — works with any LangChain `BaseChatModel`
-  (`langchain-openai`, `langchain-anthropic`, `langchain-ollama`, ...). Only
-  `langchain-core` is required at the core.
-  - `Refiner` — fidelity-first OCR refinement (4 modes) with literal/contact
-    preservation (`{{OCRLITn}}` masking) and drift/hallucination rejection.
-  - `StructuredExtractor` + `Analyzer.extract()` / `Analyzer.extract_text()` —
-    structured extraction into any Pydantic schema via `with_structured_output`.
-  - Built-in `Invoice` / `LineItem` schemas and prompt.
-- **Resource efficiency** — `EngineRegistry` singleton caches PaddleOCR/TrOCR
-  engines (and per-language models) so they load at most once per process.
-- **Windows robustness** — model cache and temp files are routed through ASCII
-  8.3 short paths to survive non-ASCII usernames; oneDNN is disabled on CPU to
-  avoid the PaddlePaddle 3.x PIR/oneDNN `NotImplementedError`.
-- **Packaging** — optional extras `[paddle]`, `[trocr]`, `[vision]`, `[all]`;
-  PEP 561 typed (`py.typed`); examples and a GPU/network-free test suite.
-
-[Unreleased]: https://github.com/bahadirkarsli/ocrcontext/compare/v0.1.2...HEAD
-[0.1.2]: https://github.com/bahadirkarsli/ocrcontext/compare/v0.1.1...v0.1.2
-[0.1.1]: https://github.com/bahadirkarsli/ocrcontext/compare/v0.1.0...v0.1.1
-[0.1.0]: https://github.com/bahadirkarsli/ocrcontext/releases/tag/v0.1.0
+# Changelog
+
+All notable changes to **ocrcontext** are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.4] - 2026-06-27
+
+### Added
+- **GPU acceleration** — `Analyzer(use_gpu=True)` routes PaddleOCR inference to a
+  CUDA-capable GPU. Requires the GPU build of PaddlePaddle (`pip install paddlepaddle-gpu`).
+  CPU remains the default (`use_gpu=False`) so existing code needs no changes.
+  The `use_gpu` flag is forwarded through `EngineRegistry` → `PaddleEngine` →
+  all `PaddleOCR` constructor profiles, including the version-pinned fallback ladder
+  (PP-OCRv6 → PP-OCRv5 → PP-OCRv4 → legacy 2.x).
+- **Vision→Paddle fallback** — when `handwriting=True` and Google Vision returns
+  insufficient text (e.g. no credentials, unsupported language), PaddleOCR is tried
+  automatically. Users no longer need TrOCR for a handwriting safety net.
+
+### Changed
+- **Removed TrOCR engine** — Microsoft TrOCR (`[trocr]` extra) is removed from the
+  project. PaddleOCR outperforms TrOCR on printed text; Google Vision outperforms it
+  on handwriting. The `[trocr]` extra and its heavy deps (torch, transformers, etc.)
+  are gone. The extras table is now `[paddle]`, `[vision]`, `[cli]`, `[all]`.
+- **`auto_handwriting_fallback` default changed to `False`** — PaddleOCR is now the
+  sole default engine. Set `AnalyzerConfig(auto_handwriting_fallback=True)` to enable
+  automatic Vision retry on insufficient printed OCR output.
+
+## [0.1.2] - 2026-06-26
+
+### Fixed
+- CI: disable Rich markup mode in typer (`rich_markup_mode=None`) so help output
+  is plain text on all platforms — Rich's panel renderer produced ANSI escape
+  codes that CliRunner could not strip on Linux, causing `--help` tests to fail.
+- Replace `typing.List` with built-in `list` in schemas for Python 3.12
+  compatibility and to avoid deprecation warnings.
+
+## [0.1.1] - 2026-06-26
+
+### Added
+- **`OCRContextLoader`** — LangChain `BaseLoader` integration. Drop-in loader for
+  any LangChain pipeline: `OCRContextLoader("file.pdf").load()` returns a
+  `Document` with OCR text and metadata (`source`, `text_source`, `pages`,
+  `confidence`, `refined`).
+- **Built-in extraction schemas** — four new ready-to-use Pydantic schemas with
+  system prompts, importable from `ocrcontext.schemas`:
+  - `Receipt` / `ReceiptItem` — store name, date, items, subtotal, tax, total,
+    payment method.
+  - `Contract` / `ContractParty` — parties, effective/expiry dates, value,
+    governing law, key obligations.
+  - `IdCard` — national_id / passport / driver_license / residence_permit with
+    ICD-standard date normalisation and ISO 3166-1 nationality codes.
+  - `MedicalReport` / `Medication` — diagnosis, ICD codes, prescriptions, notes.
+- **CLI** (`ocrcontext extract`) — terminal-first developer experience via the
+  new `[cli]` extra (`pip install "ocrcontext[cli]"`):
+  - `ocrcontext extract invoice.pdf` — plain OCR to stdout.
+  - `ocrcontext extract scan.pdf --schema receipt --output json` — structured
+    extraction as JSON.
+  - `--provider openai|anthropic|ollama|google --model <name>` — bring-your-own
+    LLM provider.
+  - `--handwriting`, `--lang`, `--refine auto|yes|no` flags.
+
+## [0.1.0] - 2026-06-25
+
+Initial release — the document extraction core, decoupled from its web stack
+into a standalone, LLM-agnostic library.
+
+### Added
+- **`Analyzer` facade** — 3-line developer experience:
+  `Analyzer().analyze("file.pdf").text`.
+- **Routing ladder** (`pipeline.py`):
+  - Digital PDFs → PyMuPDF text-layer extraction (no OCR); LLM refine is
+    auto-skipped so exact text/identifiers are never altered.
+  - Images / scanned PDFs → PaddleOCR with image preprocessing, multi-language
+    *coverage-first* candidate selection, and a line-band recovery fallback.
+  - Handwriting (explicit or auto on insufficient text) → Google Vision primary,
+    Microsoft TrOCR fallback.
+  - Multi-page documents joined with `--- Page N ---` separators.
+- **LLM-agnostic LLM layer** — works with any LangChain `BaseChatModel`
+  (`langchain-openai`, `langchain-anthropic`, `langchain-ollama`, ...). Only
+  `langchain-core` is required at the core.
+  - `Refiner` — fidelity-first OCR refinement (4 modes) with literal/contact
+    preservation (`{{OCRLITn}}` masking) and drift/hallucination rejection.
+  - `StructuredExtractor` + `Analyzer.extract()` / `Analyzer.extract_text()` —
+    structured extraction into any Pydantic schema via `with_structured_output`.
+  - Built-in `Invoice` / `LineItem` schemas and prompt.
+- **Resource efficiency** — `EngineRegistry` singleton caches PaddleOCR/TrOCR
+  engines (and per-language models) so they load at most once per process.
+- **Windows robustness** — model cache and temp files are routed through ASCII
+  8.3 short paths to survive non-ASCII usernames; oneDNN is disabled on CPU to
+  avoid the PaddlePaddle 3.x PIR/oneDNN `NotImplementedError`.
+- **Packaging** — optional extras `[paddle]`, `[trocr]`, `[vision]`, `[all]`;
+  PEP 561 typed (`py.typed`); examples and a GPU/network-free test suite.
+
+[Unreleased]: https://github.com/bahadirkarsli/ocrcontext/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/bahadirkarsli/ocrcontext/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/bahadirkarsli/ocrcontext/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/bahadirkarsli/ocrcontext/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/bahadirkarsli/ocrcontext/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/bahadirkarsli/ocrcontext/releases/tag/v0.1.0

{ocrcontext-0.1.2 → ocrcontext-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ocrcontext
-Version: 0.1.2
+Version: 0.1.4
 Summary: Decoupled, LLM-agnostic document OCR + structured extraction. Vision and LLM parsing in 3 lines of code.
 Project-URL: Homepage, https://github.com/BahadirKarsli/OCRContext
 Project-URL: Repository, https://github.com/BahadirKarsli/OCRContext
@@ -30,15 +30,10 @@ Requires-Dist: pillow>=9.0
 Requires-Dist: pydantic>=2.5
 Requires-Dist: pymupdf>=1.23
 Provides-Extra: all
-Requires-Dist: accelerate>=0.27; extra == 'all'
 Requires-Dist: google-cloud-vision>=3.8.1; extra == 'all'
 Requires-Dist: opencv-python-headless>=4.8; extra == 'all'
 Requires-Dist: paddleocr>=2.7.0.3; extra == 'all'
 Requires-Dist: paddlepaddle>=2.6; extra == 'all'
-Requires-Dist: sentencepiece>=0.1.99; extra == 'all'
-Requires-Dist: torch>=2.1; extra == 'all'
-Requires-Dist: torchvision>=0.16; extra == 'all'
-Requires-Dist: transformers>=4.40; extra == 'all'
 Requires-Dist: typer>=0.12; extra == 'all'
 Provides-Extra: cli
 Requires-Dist: typer>=0.12; extra == 'cli'
@@ -53,13 +48,6 @@ Provides-Extra: paddle
 Requires-Dist: opencv-python-headless>=4.8; extra == 'paddle'
 Requires-Dist: paddleocr>=2.7.0.3; extra == 'paddle'
 Requires-Dist: paddlepaddle>=2.6; extra == 'paddle'
-Provides-Extra: trocr
-Requires-Dist: accelerate>=0.27; extra == 'trocr'
-Requires-Dist: opencv-python-headless>=4.8; extra == 'trocr'
-Requires-Dist: sentencepiece>=0.1.99; extra == 'trocr'
-Requires-Dist: torch>=2.1; extra == 'trocr'
-Requires-Dist: torchvision>=0.16; extra == 'trocr'
-Requires-Dist: transformers>=4.40; extra == 'trocr'
 Provides-Extra: vision
 Requires-Dist: google-cloud-vision>=3.8.1; extra == 'vision'
 Requires-Dist: opencv-python-headless>=4.8; extra == 'vision'
@@ -81,6 +69,16 @@ Decoupled, LLM-agnostic document OCR + structured extraction. No web server, no
 
 </div>
 
+**Try it in 30 seconds — no Python script needed:**
+
+```bash
+pip install 'ocrcontext[paddle,cli]'
+ocrcontext extract invoice.pdf
+ocrcontext extract receipt.jpg --output json
+```
+
+**Or use the Python API:**
+
 ```python
 from ocrcontext import Analyzer
 
@@ -92,11 +90,23 @@ print(result.text)
 
 `ocrcontext` is the extraction core of a production document-analysis platform, lifted out of its FastAPI/Next.js stack into a pure, pip-installable library. It handles OCR engine routing, fidelity-first LLM cleanup, and schema-based structured extraction — and gets out of your way.
 
+## Demo
+
+**Structured invoice extraction from an image:**
+
+<img width="100%" alt="Invoice extraction demo" src="https://github.com/user-attachments/assets/8e77ab83-fff3-4929-9a54-7f4a75acc16f" />
+
+**Digital PDF text extraction:**
+
+<img width="100%" alt="PDF extraction demo" src="https://github.com/user-attachments/assets/84437bd0-9d24-4a2e-8e0c-0014c9e85820" />
+
 ## Contents
 
+- [Demo](#demo)
 - [Install](#install)
-- [Quick start](#quick-start)
 - [CLI](#cli)
+- [Quick start (Python API)](#quick-start-python-api)
+  - [GPU acceleration](#gpu-acceleration)
 - [LangChain integration](#langchain-integration)
 - [Built-in schemas](#built-in-schemas)
 - [How it routes a document](#how-it-routes-a-document)
@@ -115,8 +125,7 @@ Engines are opt-in so your base install stays small:
 |---|---|
 | `pip install ocrcontext` | Digital PDFs only (PyMuPDF text-layer — no OCR, no GPU, no API key) |
 | `pip install 'ocrcontext[paddle]'` | + printed images & scanned PDFs (PaddleOCR, CPU/GPU) |
-| `pip install 'ocrcontext[trocr]'` | + handwriting fallback (Microsoft TrOCR) |
-| `pip install 'ocrcontext[vision]'` | + handwriting primary (Google Cloud Vision) |
+| `pip install 'ocrcontext[vision]'` | + handwriting (Google Cloud Vision) |
 | `pip install 'ocrcontext[cli]'` | + terminal CLI (`ocrcontext extract`) |
 | `pip install 'ocrcontext[all]'` | everything above |
 
@@ -141,7 +150,61 @@ $env:GOOGLE_APPLICATION_CREDENTIALS = "C:\path\to\key.json" # PowerShell
 
 ---
 
-## Quick start
+## CLI
+
+Install the `[cli]` extra to use `ocrcontext` straight from the terminal — no Python script needed.
+
+```bash
+pip install 'ocrcontext[paddle,cli]'
+```
+
+**Extract plain text:**
+
+```bash
+ocrcontext extract invoice.pdf
+ocrcontext extract scan.png --output json
+```
+
+**Extract structured data with a built-in schema:**
+
+```bash
+ocrcontext extract invoice.pdf    --schema invoice
+ocrcontext extract receipt.jpg    --schema receipt
+ocrcontext extract contract.pdf   --schema contract
+ocrcontext extract passport.jpg   --schema idcard
+ocrcontext extract lab_report.pdf --schema medical
+```
+
+**Choose your LLM provider:**
+
+```bash
+ocrcontext extract invoice.pdf --schema invoice \
+  --provider openai --model gpt-4o-mini
+
+ocrcontext extract invoice.pdf --schema invoice \
+  --provider anthropic --model claude-haiku-4-5-20251001
+
+ocrcontext extract invoice.pdf --schema invoice \
+  --provider ollama --model llama3.1
+```
+
+**All options:**
+
+```
+ocrcontext extract FILE [OPTIONS]
+
+  --schema    -s   invoice | receipt | contract | idcard | medical
+  --lang      -l   Language code (default: en)
+  --handwriting    Force handwriting engine
+  --refine         auto (default) | yes | no
+  --output    -o   text (default) | json
+  --provider  -p   openai | anthropic | ollama | google
+  --model     -m   Model name (default: gpt-4o-mini)
+```
+
+---
+
+## Quick start (Python API)
 
 ### Digital PDF
 
@@ -167,6 +230,26 @@ result = Analyzer().analyze("scan.png")
 print(result.text, result.confidence)
 ```
 
+### GPU acceleration
+
+If you have a CUDA-capable GPU, swap the CPU PaddlePaddle build for the GPU one and pass `use_gpu=True`:
+
+```bash
+pip install 'ocrcontext[paddle]'
+pip install paddlepaddle-gpu   # replaces the CPU build; pick the wheel that matches your CUDA version
+```
+
+```python
+from ocrcontext import Analyzer
+
+analyzer = Analyzer(use_gpu=True)
+result = analyzer.analyze("scan.png")
+print(result.text, result.confidence)
+```
+
+> PaddleOCR is typically 5–10× faster on GPU for large documents or batch workloads.
+> CPU (`use_gpu=False`, the default) works out of the box with no extra steps.
+
 ### LLM-refined OCR
 
 Refinement fixes character-level OCR errors without paraphrasing, translating, or inventing.
@@ -233,60 +316,6 @@ print(result.text)
 
 ---
 
-## CLI
-
-Install the `[cli]` extra to use `ocrcontext` straight from the terminal — no Python script needed.
-
-```bash
-pip install 'ocrcontext[cli]'
-```
-
-**Extract plain text:**
-
-```bash
-ocrcontext extract invoice.pdf
-ocrcontext extract scan.png --output json
-```
-
-**Extract structured data with a built-in schema:**
-
-```bash
-ocrcontext extract invoice.pdf   --schema invoice
-ocrcontext extract receipt.jpg   --schema receipt
-ocrcontext extract contract.pdf  --schema contract
-ocrcontext extract passport.jpg  --schema idcard
-ocrcontext extract lab_report.pdf --schema medical
-```
-
-**Choose your LLM provider:**
-
-```bash
-ocrcontext extract invoice.pdf --schema invoice \
-  --provider openai --model gpt-4o-mini
-
-ocrcontext extract invoice.pdf --schema invoice \
-  --provider anthropic --model claude-haiku-4-5-20251001
-
-ocrcontext extract invoice.pdf --schema invoice \
-  --provider ollama --model llama3.1
-```
-
-**All options:**
-
-```
-ocrcontext extract FILE [OPTIONS]
-
-  --schema    -s   invoice | receipt | contract | idcard | medical
-  --lang      -l   Language code (default: en)
-  --handwriting    Force handwriting engine
-  --refine         auto (default) | yes | no
-  --output    -o   text (default) | json
-  --provider  -p   openai | anthropic | ollama | google
-  --model     -m   Model name (default: gpt-4o-mini)
-```
-
----
-
 ## LangChain integration
 
 `OCRContextLoader` is a drop-in LangChain `BaseLoader`. It slots into any LangChain pipeline — RAG, document Q&A, chain-of-thought — without glue code.
@@ -416,7 +445,7 @@ report = analyzer.extract("lab_report.pdf", schema=MedicalReport)
       │                                       │
       │ 3. Handwriting (explicit or auto)?    │
       │    └─▶ Google Cloud Vision            │
-      │        → TrOCR fallback               │
+      │        → PaddleOCR if Vision empty    │
       │                                       │
       │ 4. (optional) LLM refine              │
       │    fidelity-first · literal-safe      │
@@ -427,7 +456,7 @@ report = analyzer.extract("lab_report.pdf", schema=MedicalReport)
 ```
 
 Multi-page documents are joined with `--- Page N ---` separators.
-Handwriting kicks in automatically when printed OCR returns too little text.
+Handwriting step 3 is explicit-only by default; set `auto_handwriting_fallback=True` to enable automatic retry.
 
 ---
 
@@ -460,10 +489,10 @@ from ocrcontext import Analyzer, AnalyzerConfig
 cfg = AnalyzerConfig(
     lang="tr",                        # default document language
     prefer_pdf_text_layer=True,       # skip OCR when a text layer exists
-    auto_handwriting_fallback=True,   # retry with handwriting if OCR returns too little
+    auto_handwriting_fallback=False,  # keep PaddleOCR as sole engine (default); set True to enable Vision fallback
     refine_by_default=True,           # auto-refine whenever an LLM is configured
 )
-analyzer = Analyzer(llm=..., config=cfg)
+analyzer = Analyzer(llm=..., config=cfg, use_gpu=False)  # set use_gpu=True for CUDA-capable devices
 ```
 
 ---