ocrcontext 0.1.0__tar.gz

ocrcontext-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Models / caches
+.cache/
+*.onnx
+*.pdmodel
+*.pdiparams
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

ocrcontext-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# 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.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.0...HEAD
+[0.1.0]: https://github.com/bahadirkarsli/ocrcontext/releases/tag/v0.1.0

ocrcontext-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bahadır Karslı
+
+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.

ocrcontext-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: ocrcontext
+Version: 0.1.0
+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
+Project-URL: Issues, https://github.com/bahadirkarsli/ocrcontext/issues
+Project-URL: Changelog, https://github.com/bahadirkarsli/ocrcontext/blob/main/CHANGELOG.md
+Author-email: Bahadır Karslı <bahadrkrsl@outlook.com>
+Maintainer-email: Bahadır Karslı <bahadrkrsl@outlook.com>
+License: MIT
+License-File: LICENSE
+Keywords: document-ai,langchain,ocr,paddleocr,pdf,structured-extraction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: numpy>=1.24
+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'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+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'
+Description-Content-Type: text/markdown
+
+# ocrcontext
+
+**Decoupled, LLM-agnostic document OCR + structured extraction.** Turn a PDF or
+image into clean text — or a typed Pydantic model — in three lines.
+
+`ocrcontext` is the extraction core of a document-analysis platform, lifted out
+of its web stack into a pure, pip-installable library. No FastAPI, no servers,
+no hardcoded model providers.
+
+```python
+from ocrcontext import Analyzer
+
+result = Analyzer().analyze("invoice.pdf")
+print(result.text)
+```
+
+## Why
+
+- **3-line DX** — instantiate, pass a file, get a result.
+- **LLM-agnostic** — inject any LangChain chat model (OpenAI, Anthropic, Ollama,
+  local). Only `langchain-core` is required; you bring the provider.
+- **Resource-efficient** — heavy OCR models (PaddleOCR, TrOCR) load lazily and
+  are cached as process-wide singletons, so they never reload per call.
+- **Lightweight base install** — engines are opt-in extras.
+
+## Install
+
+```bash
+pip install ocrcontext              # core only (PDF text layer + the API surface)
+pip install 'ocrcontext[paddle]'    # printed text + scanned PDFs (PaddleOCR)
+pip install 'ocrcontext[trocr]'     # handwriting fallback (Microsoft TrOCR)
+pip install 'ocrcontext[vision]'    # handwriting primary (Google Cloud Vision)
+pip install 'ocrcontext[all]'       # everything
+```
+
+Pick an LLM provider for refinement / extraction:
+
+```bash
+pip install langchain-openai        # or langchain-anthropic, langchain-ollama, ...
+```
+
+## Usage
+
+### Raw OCR (no LLM, no API key)
+
+```python
+from ocrcontext import Analyzer
+
+result = Analyzer().analyze("scan.png")
+print(result.text, result.confidence, result.pages, result.text_source)
+```
+
+### LLM-refined OCR
+
+Refinement fixes OCR errors **without** paraphrasing, translating, or inventing
+text. Emails/URLs/IBANs are frozen so the model can't "correct" them, and output
+that drifts too far from the source is rejected in favour of the raw text.
+
+```python
+from langchain_openai import ChatOpenAI
+from ocrcontext import Analyzer
+
+analyzer = Analyzer(llm=ChatOpenAI(model="gpt-4o"), lang="tr")
+result = analyzer.analyze("handwritten_note.jpg", handwriting=True)
+print(result.text)          # refined
+print(result.raw_text)      # original OCR, kept alongside
+```
+
+### Structured extraction
+
+```python
+from langchain_openai import ChatOpenAI
+from ocrcontext import Analyzer
+from ocrcontext.schemas import Invoice
+
+analyzer = Analyzer(llm=ChatOpenAI(model="gpt-4o-mini", temperature=0))
+invoice = analyzer.extract("invoice.pdf", schema=Invoice)   # -> Invoice instance
+print(invoice.total_amount, invoice.currency)
+```
+
+Define your own schema with plain Pydantic:
+
+```python
+from pydantic import BaseModel, Field
+
+class Receipt(BaseModel):
+    merchant: str | None = Field(None, description="Store name")
+    total: float | None = Field(None, description="Grand total")
+
+receipt = analyzer.extract("receipt.jpg", schema=Receipt)
+```
+
+### Same code, local model (no API key)
+
+```python
+from langchain_ollama import ChatOllama
+from ocrcontext import Analyzer
+
+analyzer = Analyzer(llm=ChatOllama(model="llama3.1"))
+print(analyzer.analyze("scan.png").text)
+```
+
+## How it routes a document
+
+1. **Digital PDF** → embedded text-layer extraction (exact text; LLM refine is
+   skipped so identifiers aren't altered).
+2. **Image / scanned PDF** → PaddleOCR with preprocessing (deskew, denoise,
+   CLAHE), multi-language *coverage-first* selection, and a line-band recovery
+   fallback.
+3. **Handwriting** (`handwriting=True`, or auto when printed OCR yields too
+   little text) → Google Vision primary, TrOCR fallback.
+4. **Optional LLM refine** → fidelity-first, literal-preserved, drift-guarded.
+5. **Optional `extract(schema=...)`** → typed Pydantic model.
+
+## Refinement modes
+
+`RefinementMode`: `conservative` (scans), `layout` (digital PDFs),
+`handwriting_prose`, `handwriting_layout`. The handwriting mode is auto-selected
+based on whether the text looks like a DIKW/pyramid diagram. Modes and prompts
+are ported verbatim from the production pipeline.
+
+## Configuration
+
+```python
+from ocrcontext import Analyzer, AnalyzerConfig
+
+cfg = AnalyzerConfig(
+    lang="tr",
+    prefer_pdf_text_layer=True,
+    auto_handwriting_fallback=True,
+)
+analyzer = Analyzer(llm=..., config=cfg)
+```
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest            # runs without GPU/network — engines and LLM are faked
+```
+
+## License
+
+MIT

ocrcontext-0.1.0/README.md

@@ -0,0 +1,144 @@
+# ocrcontext
+
+**Decoupled, LLM-agnostic document OCR + structured extraction.** Turn a PDF or
+image into clean text — or a typed Pydantic model — in three lines.
+
+`ocrcontext` is the extraction core of a document-analysis platform, lifted out
+of its web stack into a pure, pip-installable library. No FastAPI, no servers,
+no hardcoded model providers.
+
+```python
+from ocrcontext import Analyzer
+
+result = Analyzer().analyze("invoice.pdf")
+print(result.text)
+```
+
+## Why
+
+- **3-line DX** — instantiate, pass a file, get a result.
+- **LLM-agnostic** — inject any LangChain chat model (OpenAI, Anthropic, Ollama,
+  local). Only `langchain-core` is required; you bring the provider.
+- **Resource-efficient** — heavy OCR models (PaddleOCR, TrOCR) load lazily and
+  are cached as process-wide singletons, so they never reload per call.
+- **Lightweight base install** — engines are opt-in extras.
+
+## Install
+
+```bash
+pip install ocrcontext              # core only (PDF text layer + the API surface)
+pip install 'ocrcontext[paddle]'    # printed text + scanned PDFs (PaddleOCR)
+pip install 'ocrcontext[trocr]'     # handwriting fallback (Microsoft TrOCR)
+pip install 'ocrcontext[vision]'    # handwriting primary (Google Cloud Vision)
+pip install 'ocrcontext[all]'       # everything
+```
+
+Pick an LLM provider for refinement / extraction:
+
+```bash
+pip install langchain-openai        # or langchain-anthropic, langchain-ollama, ...
+```
+
+## Usage
+
+### Raw OCR (no LLM, no API key)
+
+```python
+from ocrcontext import Analyzer
+
+result = Analyzer().analyze("scan.png")
+print(result.text, result.confidence, result.pages, result.text_source)
+```
+
+### LLM-refined OCR
+
+Refinement fixes OCR errors **without** paraphrasing, translating, or inventing
+text. Emails/URLs/IBANs are frozen so the model can't "correct" them, and output
+that drifts too far from the source is rejected in favour of the raw text.
+
+```python
+from langchain_openai import ChatOpenAI
+from ocrcontext import Analyzer
+
+analyzer = Analyzer(llm=ChatOpenAI(model="gpt-4o"), lang="tr")
+result = analyzer.analyze("handwritten_note.jpg", handwriting=True)
+print(result.text)          # refined
+print(result.raw_text)      # original OCR, kept alongside
+```
+
+### Structured extraction
+
+```python
+from langchain_openai import ChatOpenAI
+from ocrcontext import Analyzer
+from ocrcontext.schemas import Invoice
+
+analyzer = Analyzer(llm=ChatOpenAI(model="gpt-4o-mini", temperature=0))
+invoice = analyzer.extract("invoice.pdf", schema=Invoice)   # -> Invoice instance
+print(invoice.total_amount, invoice.currency)
+```
+
+Define your own schema with plain Pydantic:
+
+```python
+from pydantic import BaseModel, Field
+
+class Receipt(BaseModel):
+    merchant: str | None = Field(None, description="Store name")
+    total: float | None = Field(None, description="Grand total")
+
+receipt = analyzer.extract("receipt.jpg", schema=Receipt)
+```
+
+### Same code, local model (no API key)
+
+```python
+from langchain_ollama import ChatOllama
+from ocrcontext import Analyzer
+
+analyzer = Analyzer(llm=ChatOllama(model="llama3.1"))
+print(analyzer.analyze("scan.png").text)
+```
+
+## How it routes a document
+
+1. **Digital PDF** → embedded text-layer extraction (exact text; LLM refine is
+   skipped so identifiers aren't altered).
+2. **Image / scanned PDF** → PaddleOCR with preprocessing (deskew, denoise,
+   CLAHE), multi-language *coverage-first* selection, and a line-band recovery
+   fallback.
+3. **Handwriting** (`handwriting=True`, or auto when printed OCR yields too
+   little text) → Google Vision primary, TrOCR fallback.
+4. **Optional LLM refine** → fidelity-first, literal-preserved, drift-guarded.
+5. **Optional `extract(schema=...)`** → typed Pydantic model.
+
+## Refinement modes
+
+`RefinementMode`: `conservative` (scans), `layout` (digital PDFs),
+`handwriting_prose`, `handwriting_layout`. The handwriting mode is auto-selected
+based on whether the text looks like a DIKW/pyramid diagram. Modes and prompts
+are ported verbatim from the production pipeline.
+
+## Configuration
+
+```python
+from ocrcontext import Analyzer, AnalyzerConfig
+
+cfg = AnalyzerConfig(
+    lang="tr",
+    prefer_pdf_text_layer=True,
+    auto_handwriting_fallback=True,
+)
+analyzer = Analyzer(llm=..., config=cfg)
+```
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest            # runs without GPU/network — engines and LLM are faked
+```
+
+## License
+
+MIT

ocrcontext-0.1.0/examples/01_quickstart.py

@@ -0,0 +1,12 @@
+"""Raw OCR in 3 lines — no LLM, no API key required.
+
+    pip install 'ocrcontext[paddle]'
+"""
+
+from ocrcontext import Analyzer
+
+result = Analyzer().analyze("invoice.pdf")
+print(result.text)
+
+# `result` is a Pydantic model with extra metadata:
+print("source:", result.text_source, "| pages:", result.pages, "| conf:", result.confidence)

ocrcontext-0.1.0/examples/02_refine_openai.py

@@ -0,0 +1,19 @@
+"""LLM-refined OCR with OpenAI.
+
+    pip install 'ocrcontext[paddle]' langchain-openai
+    export OPENAI_API_KEY=sk-...
+"""
+
+from langchain_openai import ChatOpenAI
+
+from ocrcontext import Analyzer
+
+analyzer = Analyzer(llm=ChatOpenAI(model="gpt-4o"), lang="tr")
+
+# refine=None (default) auto-refines OCR output (but never an exact PDF text layer).
+result = analyzer.analyze("handwritten_note.jpg", handwriting=True)
+
+print("Refined:", result.refined)
+print(result.text)
+if result.raw_text:
+    print("\n--- raw OCR (before refine) ---\n", result.raw_text)

ocrcontext-0.1.0/examples/03_structured_invoice.py

@@ -0,0 +1,32 @@
+"""Structured extraction into a Pydantic model.
+
+    pip install 'ocrcontext[paddle]' langchain-openai
+    export OPENAI_API_KEY=sk-...
+"""
+
+from langchain_openai import ChatOpenAI
+
+from ocrcontext import Analyzer
+from ocrcontext.schemas import Invoice
+
+analyzer = Analyzer(llm=ChatOpenAI(model="gpt-4o-mini", temperature=0), lang="tr")
+
+invoice = analyzer.extract("invoice.pdf", schema=Invoice)
+
+print(invoice.supplier_name, invoice.total_amount, invoice.currency)
+for item in invoice.line_items:
+    print(f"  - {item.description}: {item.quantity} x {item.unit_price} = {item.total}")
+
+
+# --- Or define your own schema -------------------------------------------------
+from pydantic import BaseModel, Field  # noqa: E402
+
+
+class Receipt(BaseModel):
+    merchant: str | None = Field(None, description="Store / merchant name")
+    date: str | None = Field(None, description="Purchase date, YYYY-MM-DD")
+    total: float | None = Field(None, description="Grand total")
+
+
+receipt = analyzer.extract("receipt.jpg", schema=Receipt)
+print(receipt)

ocrcontext-0.1.0/examples/04_local_ollama.py

@@ -0,0 +1,15 @@
+"""LLM-agnostic: the exact same code with a local Ollama model — no API key.
+
+    pip install 'ocrcontext[paddle]' langchain-ollama
+    ollama pull llama3.1
+"""
+
+from langchain_ollama import ChatOllama
+
+from ocrcontext import Analyzer
+
+# Swap ChatOpenAI -> ChatOllama; nothing else changes.
+analyzer = Analyzer(llm=ChatOllama(model="llama3.1"))
+
+result = analyzer.analyze("scan.png")
+print(result.text)

ocrcontext-0.1.0/examples/image_smoke_test.py

@@ -0,0 +1,107 @@
+"""End-to-end smoke test: raw OCR on a single image — no LLM, no schemas.
+
+This exercises the *pure* PaddleOCR path:
+    load image -> preprocess -> candidate-language OCR -> coverage-first text.
+
+Usage
+-----
+    python examples/image_smoke_test.py                 # auto-find a sample image
+    python examples/image_smoke_test.py path/to/img.png # explicit path
+
+Setup
+-----
+    pip install -e '.[paddle]'      # installs PaddleOCR + OpenCV
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+from ocrcontext import Analyzer, AnalyzerConfig
+from ocrcontext.exceptions import MissingDependencyError, UnsupportedFileError
+
+# Common sample names / extensions to look for when no path is given.
+_SAMPLE_NAMES = ["sample", "test", "image", "ocr", "smoke"]
+_IMAGE_EXTS = [".png", ".jpg", ".jpeg", ".bmp", ".tif", ".tiff", ".webp"]
+
+
+def _find_sample_image() -> Path | None:
+    """Look for an image next to this script and in the project root."""
+    here = Path(__file__).resolve().parent
+    search_dirs = [here, here.parent]  # examples/ then ocrcontext_lib/
+    # 1) Prefer files whose name hints they're samples.
+    for d in search_dirs:
+        for stem in _SAMPLE_NAMES:
+            for ext in _IMAGE_EXTS:
+                candidate = d / f"{stem}{ext}"
+                if candidate.exists():
+                    return candidate
+    # 2) Otherwise, the first image we can find in those dirs.
+    for d in search_dirs:
+        for ext in _IMAGE_EXTS:
+            matches = sorted(d.glob(f"*{ext}"))
+            if matches:
+                return matches[0]
+    return None
+
+
+def main() -> int:
+    if len(sys.argv) > 1:
+        image_path = Path(sys.argv[1]).expanduser()
+    else:
+        found = _find_sample_image()
+        if found is None:
+            print(
+                "No image given and none found automatically.\n"
+                "Drop an image (e.g. sample.png) into the examples/ folder, or run:\n"
+                "    python examples/image_smoke_test.py path/to/your/image.png"
+            )
+            return 2
+        image_path = found
+        print(f"[i] No path given — using discovered image: {image_path.name}")
+
+    if not image_path.exists():
+        print(f"[x] File not found: {image_path}")
+        return 2
+
+    print(f"[i] OCR target : {image_path}")
+    print("[i] Engine     : PaddleOCR (raw OCR, no LLM)\n")
+
+    # Pure PaddleOCR: disable the handwriting fallback so a sparse image doesn't try
+    # to load the Vision/TrOCR extras during this smoke test.
+    analyzer = Analyzer(config=AnalyzerConfig(lang="en", auto_handwriting_fallback=False))
+
+    try:
+        t0 = time.perf_counter()
+        result = analyzer.analyze(image_path)
+        elapsed = time.perf_counter() - t0
+    except MissingDependencyError as exc:
+        print(f"[x] {exc}")
+        return 1
+    except UnsupportedFileError as exc:
+        print(f"[x] {exc}")
+        return 2
+
+    print("=" * 60)
+    print("EXTRACTED TEXT")
+    print("=" * 60)
+    print(result.text if result.text else "(no text detected)")
+    print("=" * 60)
+    print(
+        f"source={result.text_source}  pages={result.pages}  "
+        f"confidence={result.confidence}  chars={len(result.text)}  "
+        f"time={elapsed:.2f}s"
+    )
+
+    # Show the singleton in action: a second call reuses the loaded model (fast).
+    t0 = time.perf_counter()
+    analyzer.analyze(image_path)
+    print(f"[i] 2nd run (warm model): {time.perf_counter() - t0:.2f}s")
+
+    return 0 if result.text.strip() else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())