arjuna-ocr 1.2.1__tar.gz

arjuna_ocr-1.2.1/LICENSE

@@ -0,0 +1,3 @@
+Apache License 2.0 — see https://www.apache.org/licenses/LICENSE-2.0
+
+Copyright 2026 Chethan (anandkaman). Base models: PaddleOCR (Apache-2.0), OpenOCR SVTRv2 (Apache-2.0).

arjuna_ocr-1.2.1/MANIFEST.in

@@ -0,0 +1,8 @@
+# the wheel is code only: the models (~170 MB) are downloaded from the Hugging Face repo on first use
+include LICENSE
+include README.md
+exclude kanen.yaml VERSION handler.py serve.py run_ocr.py Dockerfile Dockerfile.cuda
+prune models
+prune samples
+prune tests
+prune trt_cache

arjuna_ocr-1.2.1/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: arjuna-ocr
+Version: 1.2.1
+Summary: Arjuna-OCR [Kn&En]: layout-aware Kannada + English document OCR (ONNX Runtime, optional TensorRT)
+Author: Chethan (anandkaman)
+License: Apache-2.0
+Project-URL: Homepage, https://huggingface.co/anandkaman/arjuna-ocr
+Project-URL: Models, https://huggingface.co/anandkaman/arjuna-ocr
+Project-URL: Releases, https://huggingface.co/anandkaman/arjuna-ocr-kn-en
+Project-URL: Demo, https://huggingface.co/spaces/anandkaman/arjuna_ocr_demo
+Keywords: ocr,kannada,document-ai,layout-analysis,onnx,tensorrt,indic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: onnxruntime>=1.20
+Requires-Dist: numpy
+Requires-Dist: opencv-python-headless
+Requires-Dist: pyclipper
+Requires-Dist: shapely
+Requires-Dist: pyyaml
+Requires-Dist: regex
+Requires-Dist: onnx
+Requires-Dist: huggingface_hub>=0.23
+Provides-Extra: gpu
+Requires-Dist: onnxruntime-gpu>=1.20; extra == "gpu"
+Provides-Extra: trt
+Requires-Dist: onnxruntime-gpu>=1.20; extra == "trt"
+Requires-Dist: tensorrt>=10.0; extra == "trt"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.29; extra == "server"
+Requires-Dist: python-multipart; extra == "server"
+Provides-Extra: pdf
+Requires-Dist: pypdfium2>=4.0; extra == "pdf"
+Provides-Extra: cpu
+Requires-Dist: onnxruntime>=1.20; extra == "cpu"
+Provides-Extra: all
+Requires-Dist: onnxruntime-gpu>=1.20; extra == "all"
+Requires-Dist: tensorrt>=10.0; extra == "all"
+Requires-Dist: fastapi>=0.110; extra == "all"
+Requires-Dist: uvicorn>=0.29; extra == "all"
+Requires-Dist: python-multipart; extra == "all"
+Requires-Dist: pypdfium2>=4.0; extra == "all"
+Dynamic: license-file
+
+# Arjuna-OCR [Kn&En]
+
+Layout-aware **Kannada + English** document OCR: a layout model, a text detector and a CTC recognizer in ONNX, with
+tables, reading order, per-line confidence and review flags. No language model, no GPU required.
+
+```bash
+pip install arjuna-ocr          # CPU, works anywhere
+
+
+arjuna doctor                   # what this machine can do and what the pipeline will use
+arjuna ocr page.pdf -o out/     # files, folders, globs or PDFs -> JSON / Markdown / hOCR / ALTO / TSV
+arjuna serve --port 8080        # HTTP server
+```
+
+```python
+from kanen_infer import KanEnOCR
+ocr = KanEnOCR()            # detects hardware, configures itself
+doc = ocr.page("page.png")  # kanen-ocr/1.0 JSON
+print(ocr.render(doc, "md"))
+```
+
+The models (~170 MB) download once from [anandkaman/arjuna-ocr](https://huggingface.co/anandkaman/arjuna-ocr) at the
+revision matching this package version, and are cached. Point `ARJUNA_MODELS` at a local copy for air-gapped installs.
+
+**Speed and accuracy.** 12.8 pages/s on an RTX 5060 Ti with TensorRT, ~4.6 on the CUDA provider, seconds per page on CPU.
+On a frozen 40-page private-document set: word F1 0.967, page CER 3.1 %; 96.3 % word accuracy on Mozhi, 93.7 % on MILE.
+TensorRT engines are built in the background on first use — the pipeline serves immediately on CUDA and swaps each engine
+in only after it reproduces the output of the session it replaces.
+
+Full documentation, hosted-inference instructions and the evaluation record: the model repositories linked above.
+**Licences**: code, recognizer and detector Apache-2.0; the layout model is AGPL-3.0 (see its NOTICE).

arjuna_ocr-1.2.1/PYPI_README.md

@@ -0,0 +1,31 @@
+# Arjuna-OCR [Kn&En]
+
+Layout-aware **Kannada + English** document OCR: a layout model, a text detector and a CTC recognizer in ONNX, with
+tables, reading order, per-line confidence and review flags. No language model, no GPU required.
+
+```bash
+pip install arjuna-ocr          # CPU, works anywhere
+
+
+arjuna doctor                   # what this machine can do and what the pipeline will use
+arjuna ocr page.pdf -o out/     # files, folders, globs or PDFs -> JSON / Markdown / hOCR / ALTO / TSV
+arjuna serve --port 8080        # HTTP server
+```
+
+```python
+from kanen_infer import KanEnOCR
+ocr = KanEnOCR()            # detects hardware, configures itself
+doc = ocr.page("page.png")  # kanen-ocr/1.0 JSON
+print(ocr.render(doc, "md"))
+```
+
+The models (~170 MB) download once from [anandkaman/arjuna-ocr](https://huggingface.co/anandkaman/arjuna-ocr) at the
+revision matching this package version, and are cached. Point `ARJUNA_MODELS` at a local copy for air-gapped installs.
+
+**Speed and accuracy.** 12.8 pages/s on an RTX 5060 Ti with TensorRT, ~4.6 on the CUDA provider, seconds per page on CPU.
+On a frozen 40-page private-document set: word F1 0.967, page CER 3.1 %; 96.3 % word accuracy on Mozhi, 93.7 % on MILE.
+TensorRT engines are built in the background on first use — the pipeline serves immediately on CUDA and swaps each engine
+in only after it reproduces the output of the session it replaces.
+
+Full documentation, hosted-inference instructions and the evaluation record: the model repositories linked above.
+**Licences**: code, recognizer and detector Apache-2.0; the layout model is AGPL-3.0 (see its NOTICE).

arjuna_ocr-1.2.1/README.md

@@ -0,0 +1,149 @@
+---
+license: apache-2.0
+language:
+  - kn
+  - en
+pipeline_tag: image-to-text
+tags:
+  - ocr
+  - kannada
+  - document-ai
+  - layout-analysis
+  - onnx
+  - tensorrt
+library_name: onnxruntime
+---
+
+# Arjuna-OCR [Kn&En] — inference
+
+**Kannada + English document OCR that runs anywhere and configures itself.** This repository is the *deployment* package:
+one supported version (v1.2.1), the three models, the inference code, an HTTP server, a Hugging Face Inference Endpoints
+handler and Docker files. Every release, the full evaluation record and the training story live in the archive repository
+[anandkaman/arjuna-ocr-kn-en](https://huggingface.co/anandkaman/arjuna-ocr-kn-en).
+
+```bash
+pip install arjuna-ocr            # CPU everywhere
+
+
+arjuna doctor                     # what this machine can do, and what the pipeline will use
+arjuna ocr page.pdf -o out/       # OCR files, folders, globs or PDFs
+arjuna serve --port 8080          # HTTP server
+```
+
+Or without installing anything:
+
+```bash
+docker run --rm -p 8080:8080 arjuna-ocr:cpu                 # CPU
+docker run --rm --gpus all -p 8080:8080 arjuna-ocr:cuda     # NVIDIA
+```
+
+## It configures itself
+
+On start it detects the GPU, driver, CUDA and TensorRT, picks the fastest provider it can actually load, and scales batch
+sizes and thread counts to the machine's VRAM and cores. **Only speed settings change — canvases, thresholds, padding and
+the models are exactly as shipped, so results do not depend on the hardware** (beyond fp16 rounding).
+
+TensorRT engines are specific to the GPU and TensorRT version, so they cannot be shipped for every machine. Instead of
+making you wait for a build, the pipeline **starts serving immediately on the CUDA provider and builds the engines in the
+background**; each engine is swapped in only after it reproduces the output of the session it replaces (for the layout
+model, the reference blocks on the bundled page). If a build fails or produces a wrong engine, the pipeline keeps running
+on what it had and says so. Cold start on an unseen GPU: **~1.5 s to first request**, full speed a minute or two later.
+
+`arjuna doctor` prints all of it: hardware, driver, usable providers, the plan, every auto-configuration change, and the
+reason for any fallback.
+
+## What runs where
+
+| provider | hardware | status |
+|---|---|---|
+| TensorRT (fp16) | NVIDIA + TensorRT | supported — 12.8 pages/s on an RTX 5060 Ti |
+| CUDA | any NVIDIA with a working driver | supported — ~4.6 pages/s, and the path used while engines build |
+| CPU | x86-64 / ARM64, no GPU needed | supported — seconds per page, scales with cores |
+| DirectML, CoreML, OpenVINO | Windows, Apple Silicon, Intel | planned; the graphs are ordinary CNNs, so these are provider swaps |
+| ROCm | AMD | best-effort only (ONNX Runtime support ends after ROCm 7.0) |
+
+**Not supported, by design:** vLLM, Ollama / llama.cpp, TGI and the Hugging Face serverless Inference API or Inference
+Providers catalogue. These serve autoregressive language models; Arjuna is three CNN/CTC vision models with their own
+pre- and post-processing. Use the Docker image, the HTTP server, Inference Endpoints or Triton instead.
+
+## NVIDIA
+
+`pip install arjuna-ocr` installs the CPU runtime, which works everywhere. For GPU speed, replace the runtime with a
+build that matches your CUDA — `onnxruntime` and `onnxruntime-gpu` share an import name, so only one may be installed:
+
+```bash
+# CUDA 13 (current default wheels)
+pip uninstall -y onnxruntime && pip install "arjuna-ocr[trt]"
+
+# CUDA 12
+pip uninstall -y onnxruntime onnxruntime-gpu
+pip install onnxruntime-gpu --index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-12/pypi/simple/
+pip install tensorrt-cu12 nvidia-cublas-cu12 nvidia-cudnn-cu12 nvidia-cuda-runtime-cu12
+
+# or skip all of it
+docker run --rm --gpus all -p 8080:8080 arjuna-ocr:cuda
+```
+
+`arjuna doctor` tells you which providers actually load on your machine and why any of them was rejected. If it reports
+CPU while you expect GPU, the CUDA libraries the runtime wants are missing or belong to a different CUDA major version.
+
+## Hosted inference
+
+**Hugging Face Inference Endpoints** — this repo ships `handler.py`, so *Deploy → Inference Endpoints* works directly.
+Pick a CPU or GPU instance; engines build in the background on GPU instances.
+
+```python
+import base64, requests
+img = base64.b64encode(open("page.png", "rb").read()).decode()
+r = requests.post(URL, headers={"Authorization": f"Bearer {TOKEN}"},
+                  json={"inputs": img, "parameters": {"format": "json"}})
+doc = r.json()["documents"][0]
+```
+
+**Anywhere that runs a container** — Modal, RunPod, Replicate, fal, Kubernetes, your own server: use the Docker images.
+**Multi-model serving** — the three ONNX graphs drop into NVIDIA Triton with the pre/post-processing as a Python backend.
+
+## Python
+
+```python
+from kanen_infer import KanEnOCR
+ocr = KanEnOCR()          # auto-detects hardware
+ocr.optimize()            # optional: build TensorRT engines in the background
+doc = ocr.page("page.png")            # kanen-ocr/1.0 JSON
+md  = ocr.render(doc, "md")           # json | md | txt | hocr | alto | tsv
+docs = ocr.pages(["a.png", "b.pdf"])  # batched
+```
+
+Every line carries `text`, `confidence`, `min_conf` (weakest character), `bbox`, `script` and review `flags`
+(`low_conf`, `check`, `weak_char`, `script_mix`, `oversize`, `in_seal`, `in_figure`, `in_id_panel`, `in_handwriting`).
+Blocks are `text`, `title`, `table`, `figure`, `seal`, `id_panel`, `handwriting`, `header`, `footer`; tables carry
+`rows[].cells[]`. **Nothing is filtered or rewritten** — low-confidence lines are flagged, never dropped.
+
+## Accuracy (v1.2.1)
+
+| set | measure | result |
+|---|---|---|
+| private documents, 40 frozen pages | word F1 end-to-end / page CER | **0.967** / 3.11 % |
+| private document lines (1,324) | word accuracy / CER | **98.8 %** / 0.17 |
+| Mozhi test (IIIT-H, public) | word accuracy | **96.3 %** |
+| MILE (IISc, public) | word accuracy | **93.7 %** |
+| English PDF text | word accuracy | **97.2 %** |
+| vs Surya OCR 1, clean pages / unseen MILE pages | word F1 | **0.991 / 0.872** vs 0.929 / 0.751 |
+
+Method, per-benchmark analysis and the full history: see the archive repo's `docs/`.
+
+## Known limitations
+
+- Very small or fax-quality English text (≤ 11 px x-height) and thermal/dot-matrix receipts lose accuracy.
+- Historical Kannada is strong but below modern print; line splitting on letter-spaced or letterpress faces is much
+  reduced in v1.2.1 but not gone.
+- Dense multi-column tables (10+ columns) and unruled form boxes come out as text lines without cell structure.
+- Handwriting, stamps and seals produce low-confidence flagged output rather than nothing.
+- The layout model was trained on 174 pages of the target document families; other families are typed less reliably.
+
+## Licences
+
+Package code, recognizer and text detector: Apache-2.0. **The layout model `models/layout/kanen_layout_v12.onnx` is
+AGPL-3.0** — see `models/layout/NOTICE.md`. Run with `layout.mode: never` if that does not suit your deployment.
+
+Contact: kamananand98@gmail.com

arjuna_ocr-1.2.1/arjuna_ocr.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: arjuna-ocr
+Version: 1.2.1
+Summary: Arjuna-OCR [Kn&En]: layout-aware Kannada + English document OCR (ONNX Runtime, optional TensorRT)
+Author: Chethan (anandkaman)
+License: Apache-2.0
+Project-URL: Homepage, https://huggingface.co/anandkaman/arjuna-ocr
+Project-URL: Models, https://huggingface.co/anandkaman/arjuna-ocr
+Project-URL: Releases, https://huggingface.co/anandkaman/arjuna-ocr-kn-en
+Project-URL: Demo, https://huggingface.co/spaces/anandkaman/arjuna_ocr_demo
+Keywords: ocr,kannada,document-ai,layout-analysis,onnx,tensorrt,indic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: onnxruntime>=1.20
+Requires-Dist: numpy
+Requires-Dist: opencv-python-headless
+Requires-Dist: pyclipper
+Requires-Dist: shapely
+Requires-Dist: pyyaml
+Requires-Dist: regex
+Requires-Dist: onnx
+Requires-Dist: huggingface_hub>=0.23
+Provides-Extra: gpu
+Requires-Dist: onnxruntime-gpu>=1.20; extra == "gpu"
+Provides-Extra: trt
+Requires-Dist: onnxruntime-gpu>=1.20; extra == "trt"
+Requires-Dist: tensorrt>=10.0; extra == "trt"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.29; extra == "server"
+Requires-Dist: python-multipart; extra == "server"
+Provides-Extra: pdf
+Requires-Dist: pypdfium2>=4.0; extra == "pdf"
+Provides-Extra: cpu
+Requires-Dist: onnxruntime>=1.20; extra == "cpu"
+Provides-Extra: all
+Requires-Dist: onnxruntime-gpu>=1.20; extra == "all"
+Requires-Dist: tensorrt>=10.0; extra == "all"
+Requires-Dist: fastapi>=0.110; extra == "all"
+Requires-Dist: uvicorn>=0.29; extra == "all"
+Requires-Dist: python-multipart; extra == "all"
+Requires-Dist: pypdfium2>=4.0; extra == "all"
+Dynamic: license-file
+
+# Arjuna-OCR [Kn&En]
+
+Layout-aware **Kannada + English** document OCR: a layout model, a text detector and a CTC recognizer in ONNX, with
+tables, reading order, per-line confidence and review flags. No language model, no GPU required.
+
+```bash
+pip install arjuna-ocr          # CPU, works anywhere
+
+
+arjuna doctor                   # what this machine can do and what the pipeline will use
+arjuna ocr page.pdf -o out/     # files, folders, globs or PDFs -> JSON / Markdown / hOCR / ALTO / TSV
+arjuna serve --port 8080        # HTTP server
+```
+
+```python
+from kanen_infer import KanEnOCR
+ocr = KanEnOCR()            # detects hardware, configures itself
+doc = ocr.page("page.png")  # kanen-ocr/1.0 JSON
+print(ocr.render(doc, "md"))
+```
+
+The models (~170 MB) download once from [anandkaman/arjuna-ocr](https://huggingface.co/anandkaman/arjuna-ocr) at the
+revision matching this package version, and are cached. Point `ARJUNA_MODELS` at a local copy for air-gapped installs.
+
+**Speed and accuracy.** 12.8 pages/s on an RTX 5060 Ti with TensorRT, ~4.6 on the CUDA provider, seconds per page on CPU.
+On a frozen 40-page private-document set: word F1 0.967, page CER 3.1 %; 96.3 % word accuracy on Mozhi, 93.7 % on MILE.
+TensorRT engines are built in the background on first use — the pipeline serves immediately on CUDA and swaps each engine
+in only after it reproduces the output of the session it replaces.
+
+Full documentation, hosted-inference instructions and the evaluation record: the model repositories linked above.
+**Licences**: code, recognizer and detector Apache-2.0; the layout model is AGPL-3.0 (see its NOTICE).

arjuna_ocr-1.2.1/arjuna_ocr.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+LICENSE
+MANIFEST.in
+PYPI_README.md
+README.md
+pyproject.toml
+arjuna_ocr.egg-info/PKG-INFO
+arjuna_ocr.egg-info/SOURCES.txt
+arjuna_ocr.egg-info/dependency_links.txt
+arjuna_ocr.egg-info/entry_points.txt
+arjuna_ocr.egg-info/requires.txt
+arjuna_ocr.egg-info/top_level.txt
+kanen_infer/__init__.py
+kanen_infer/api.py
+kanen_infer/arjuna_cli.py
+kanen_infer/assemble.py
+kanen_infer/batch_pipeline.py
+kanen_infer/charset.py
+kanen_infer/cli.py
+kanen_infer/config.py
+kanen_infer/formats.py
+kanen_infer/geometry.py
+kanen_infer/hardware.py
+kanen_infer/io.py
+kanen_infer/models.py
+kanen_infer/pipeline_base.py
+kanen_infer/providers.py
+kanen_infer/rec_onnx.py

arjuna_ocr-1.2.1/arjuna_ocr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

arjuna_ocr-1.2.1/arjuna_ocr.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+arjuna = kanen_infer.arjuna_cli:main
+arjuna-ocr = kanen_infer.cli:main
+kanen-ocr = kanen_infer.cli:main

arjuna_ocr-1.2.1/arjuna_ocr.egg-info/requires.txt

@@ -0,0 +1,35 @@
+onnxruntime>=1.20
+numpy
+opencv-python-headless
+pyclipper
+shapely
+pyyaml
+regex
+onnx
+huggingface_hub>=0.23
+
+[all]
+onnxruntime-gpu>=1.20
+tensorrt>=10.0
+fastapi>=0.110
+uvicorn>=0.29
+python-multipart
+pypdfium2>=4.0
+
+[cpu]
+onnxruntime>=1.20
+
+[gpu]
+onnxruntime-gpu>=1.20
+
+[pdf]
+pypdfium2>=4.0
+
+[server]
+fastapi>=0.110
+uvicorn>=0.29
+python-multipart
+
+[trt]
+onnxruntime-gpu>=1.20
+tensorrt>=10.0

arjuna_ocr-1.2.1/arjuna_ocr.egg-info/top_level.txt

@@ -0,0 +1 @@
+kanen_infer

arjuna_ocr-1.2.1/kanen_infer/__init__.py

@@ -0,0 +1,9 @@
+"""Arjuna-OCR [Kn&En] inference package (Kannada + English document OCR): ONNX Runtime + optional TensorRT, no PyTorch."""
+from pathlib import Path as _P
+try: __version__ = (_P(__file__).resolve().parent.parent / "VERSION").read_text(encoding="utf-8").strip()
+except Exception: __version__ = "1.2.1"
+NAME = "Arjuna-OCR [Kn&En]"   # product display name — also `name:` in kanen.yaml (the config value wins at run time)
+from .config import load_config, PKG_ROOT          # noqa: E402
+from .api import KanEnOCR                          # noqa: E402
+from .formats import to_json, to_markdown, to_text, to_hocr, to_alto, to_tsv, render   # noqa: E402
+__all__ = ["KanEnOCR", "load_config", "PKG_ROOT", "NAME", "__version__", "to_json", "to_markdown", "to_text", "to_hocr", "to_alto", "to_tsv", "render"]

arjuna_ocr-1.2.1/kanen_infer/api.py

@@ -0,0 +1,119 @@
+"""Arjuna-OCR [Kn&En] Python API.
+
+    from kanen_infer import KanEnOCR
+    ocr = KanEnOCR()                       # loads kanen.yaml, builds/validates engines (warm-up), see ocr.ready()
+    doc = ocr.page("scan.png")             # one kanen-ocr/1.0 document (dict)
+    docs = ocr.pages(["a.png", "b.pdf"])   # batched; ocr.stream(...) yields documents as they finish
+    boxes = ocr.detect(img)                # text-line polygons only
+    texts = ocr.recognize(crops)           # [(text, conf, min_conf)] for line images
+    blocks = ocr.layout(img)               # layout blocks only
+    ocr.render(doc, "hocr")                # json | md | txt | hocr | alto | tsv
+
+Inputs: file path, bytes, numpy BGR array, PIL image, file object; PDFs through `pages()`/`stream()` (pypdfium2 or pdftoppm,
+optional). The output document never depends on the provider or the batch composition beyond fp16 noise on garbage lines;
+no confidence filtering, no text rewriting, no re-ordering happens here."""
+import logging, time
+import numpy as np, cv2
+from pathlib import Path
+from .config import load_config, PKG_ROOT
+from .providers import Providers
+from .rec_onnx import KanEnRecognizer
+from .pipeline_base import Detector, Layout, crop
+from .batch_pipeline import BatchOCR
+from .io import to_bgr, expand_inputs, iter_page_sources
+from . import formats
+
+LOG = logging.getLogger("kanen")
+
+class KanEnOCR:
+    def __init__(self, config=None, providers=None, layout_mode=None, workers=None, warmup=True, **overrides):
+        """config: path to a kanen.yaml/json, a dict, or None (package default). providers: 'trt' | 'cuda' | 'cpu' | 'auto'
+        (overrides config provider.policy). Other keyword overrides use dotted section names, e.g. layout={'mode': 'auto'}."""
+        ov = dict(overrides)
+        if providers: ov.setdefault("provider", {})["policy"] = providers
+        if layout_mode: ov.setdefault("layout", {})["mode"] = layout_mode
+        if workers: ov.setdefault("runtime", {})["workers"] = workers
+        self.cfg = load_config(config, ov); self.name = self.cfg.get("name", "Arjuna-OCR [Kn&En]"); self.version = str(self.cfg.get("version", "1.0.0"))
+        t0 = time.time(); self.prov = Providers(self.cfg)
+        self.rec = KanEnRecognizer(cfg=self.cfg, providers=self.prov); self.det = Detector(self.cfg, self.prov)
+        self.lay = Layout(self.cfg, self.prov) if self.cfg["layout"].get("mode", "always") != "never" else None
+        self.batch = BatchOCR(self.rec, cfg=self.cfg, providers=self.prov, det=self.det, lay=self.lay)
+        self._load_s = round(time.time() - t0, 1); self._warm = None
+        if warmup: self.warmup()
+
+    # ---- status --------------------------------------------------------------------------------------------------
+    def warmup(self):
+        """Run the bundled self-test page through the full pipeline once: builds/validates TensorRT engines for the
+        default shapes (layout self-test, detector canvas, recognizer profile) so the first real page is not slow."""
+        t0 = time.time(); p = self.cfg.path("models", "layout_selftest")
+        if p.exists():
+            img = to_bgr(str(p)); self.batch.run([img], page_batch=1, loader=lambda x: x)
+        self._warm = round(time.time() - t0, 1); return self.ready()
+
+    def optimize(self, wait=False, timeout=None):
+        """Build the TensorRT engines for this machine in the background and swap them in once each one is validated
+        against the session it replaces. Safe to call at any time; returns immediately unless `wait` is set.
+        Long-lived processes (server, endpoint handler, batch jobs) should call this at startup: the pipeline keeps
+        serving on the CUDA provider meanwhile, and gets 2-3x faster when the engines are ready."""
+        n = self.prov.start_background_builds() if hasattr(self.prov, "start_background_builds") else 0
+        if wait and n: return self.prov.wait_for_engines(timeout)
+        return {"builds_started": n}
+
+    def ready(self):
+        """Provider each model ended on, fallbacks that happened, engine-cache state, model hashes."""
+        st = self.prov.summary()
+        if self.lay is not None: st.setdefault("layout", {})["engine"] = self.lay.stage
+        return {"name": self.name, "version": self.version, "config": self.cfg.source, "gpu": self.prov.gpu, "tensorrt": self.prov.trt_ver,
+                "providers": st, "events": list(self.prov.events), "engine_cache": str(self.prov.cache_root), "load_s": self._load_s, "warmup_s": self._warm,
+                "model": dict(self.batch.model_ids)}
+
+    # ---- full documents -------------------------------------------------------------------------------------------
+    def page(self, image, polygons=None, dpi=None):
+        """Single page (latency path): one kanen-ocr/1.0 document."""
+        img = to_bgr(image); docs, _ = self.batch.process([img], dpi=dpi, with_polygons=self._poly(polygons)); d = docs[0]
+        if isinstance(image, (str, Path)): d["page"]["file"] = Path(image).name
+        return d
+
+    def pages(self, inputs, page_batch=None, polygons=None, pdf_dpi=200):
+        """Batched: list/dir/glob of image or PDF paths, or a list of arrays / PIL images / bytes -> list of documents."""
+        return [d for d in self.stream(inputs, page_batch, polygons, pdf_dpi)]
+
+    def stream(self, inputs, page_batch=None, polygons=None, pdf_dpi=200):
+        """Generator variant of pages(): yields documents in input order as each page batch completes."""
+        sources = self._sources(inputs, pdf_dpi); labels = [s[0] for s in sources]; items = [s[1] for s in sources]
+        page_batch = page_batch or self.cfg["runtime"].get("page_batch", 8); k = 0
+        for doc, st in self.batch.stream(items, page_batch=page_batch, loader=to_bgr, with_polygons=self._poly(polygons)):
+            if labels[k]: doc["page"]["file"] = labels[k]
+            self.last_stats = st; k += 1; yield doc
+
+    def _sources(self, inputs, pdf_dpi):
+        if isinstance(inputs, (str, Path)) or (isinstance(inputs, (list, tuple)) and inputs and all(isinstance(x, (str, Path)) for x in inputs)):
+            return list(iter_page_sources(expand_inputs(inputs), dpi=pdf_dpi))
+        if isinstance(inputs, (list, tuple)): return [(getattr(x, "name", None) or "", x) for x in inputs]
+        return [("", inputs)]
+
+    def _poly(self, polygons): return bool(self.cfg["runtime"].get("polygons", False)) if polygons is None else bool(polygons)
+
+    # ---- single stages --------------------------------------------------------------------------------------------
+    def detect(self, image):
+        """Text-line detection only -> list of (polygon 4x2 float32 in page pixels, score)."""
+        return self.det(to_bgr(image))
+
+    def recognize(self, crops, batch=None):
+        """Recognition only on a list of line images (any size, BGR or gray) -> [(text, confidence, min_conf)]."""
+        res = self.rec([to_bgr(c) for c in crops], bs=batch)
+        return [(t, float(c), float(getattr(c, "min_char", c))) for t, c in res]
+
+    def layout(self, image):
+        """Layout blocks only -> [{type, score, bbox, order}] (labels: title, text, table, figure, seal, id_panel, header, footer, handwriting)."""
+        if self.lay is None: self.lay = Layout(self.cfg, self.prov); self.batch.lay = self.lay
+        return self.lay(to_bgr(image))[0]
+
+    def crops(self, image, boxes=None):
+        """Perspective line crops for detect() boxes (helper for recognize())."""
+        img = to_bgr(image); boxes = self.detect(img) if boxes is None else boxes
+        return [crop(img, b) for b, _ in boxes]
+
+    # ---- serialisation --------------------------------------------------------------------------------------------
+    def render(self, doc, fmt="json"):
+        return formats.render(doc, fmt)