mathcraft-ocr 0.2.7__tar.gz → 0.2.9__tar.gz

{mathcraft_ocr-0.2.7/mathcraft_ocr.egg-info → mathcraft_ocr-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mathcraft-ocr
-Version: 0.2.7
+Version: 0.2.9
 Summary: ONNX-only OCR runtime for mathematical documents
 Author: SakuraMathcraft
 License-Expression: GPL-3.0-only
@@ -21,21 +21,25 @@ 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
+Requires-Python: <3.14,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy<3,>=1.26
-Requires-Dist: pillow<12,>=10
+Requires-Dist: numpy<3,>=2
+Requires-Dist: pillow<13,>=12
 Requires-Dist: opencv-python<5,>=4.10
 Requires-Dist: rapidocr==3.5.0
 Requires-Dist: transformers==4.55.4
 Requires-Dist: tokenizers==0.21.4
 Provides-Extra: cpu
-Requires-Dist: onnxruntime<1.26,>=1.19.2; python_version < "3.13" and extra == "cpu"
-Requires-Dist: onnxruntime<1.26,>=1.20; python_version >= "3.13" and extra == "cpu"
+Requires-Dist: onnxruntime<1.30,>=1.20; extra == "cpu"
 Provides-Extra: gpu
-Requires-Dist: onnxruntime-gpu<1.26,>=1.19.2; python_version < "3.13" and extra == "gpu"
-Requires-Dist: onnxruntime-gpu<1.26,>=1.20; python_version >= "3.13" and extra == "gpu"
+Requires-Dist: onnxruntime-gpu<1.30,>=1.27; extra == "gpu"
+Provides-Extra: gpu-cu12
+Requires-Dist: onnxruntime-gpu<1.27,>=1.21; extra == "gpu-cu12"
+Provides-Extra: directml
+Requires-Dist: onnxruntime-directml<1.30,>=1.20; platform_system == "Windows" and extra == "directml"
+Provides-Extra: openvino
+Requires-Dist: onnxruntime-openvino<1.30,>=1.20; (platform_system == "Windows" or platform_system == "Linux") and extra == "openvino"
 Provides-Extra: dev
 Requires-Dist: ruff>=0.8; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
@@ -76,9 +80,27 @@ GPU backend:
 pip install "mathcraft-ocr[gpu]"
 ```
 
-Install only one backend extra in a clean environment. `onnxruntime` and `onnxruntime-gpu` should not be mixed in the same environment.
+CUDA 12 backend:
 
-LaTeXSnipper's dependency wizard selects the ONNX Runtime GPU wheel line from the detected CUDA toolkit. CUDA 11.x uses the ONNX Runtime CUDA 11 package feed, CUDA 12.x uses the stable PyPI GPU wheels, and CUDA 13.x uses the ONNX Runtime CUDA 13 nightly feed. Static `mathcraft-ocr[gpu]` package metadata cannot inspect the local CUDA toolkit, so it keeps a broad stable PyPI range; CUDA 11.x users installing manually should use the CUDA 11 feed shown by the wizard.
+```powershell
+pip install "mathcraft-ocr[gpu-cu12]"
+```
+
+Windows DirectML backend:
+
+```powershell
+pip install "mathcraft-ocr[directml]"
+```
+
+Intel OpenVINO backend on Windows or Linux:
+
+```powershell
+pip install "mathcraft-ocr[openvino]"
+```
+
+Install only one backend extra in a clean environment. The CPU, CUDA/TensorRT, DirectML, and OpenVINO ONNX Runtime distributions must not be mixed in the same environment. The standard `onnxruntime` macOS wheel includes CoreML EP support.
+
+LaTeXSnipper's dependency wizard selects the ONNX Runtime GPU line from the detected CUDA toolkit: CUDA 11.x uses ONNX Runtime 1.20 from the official CUDA 11 feed, CUDA 12.x uses ONNX Runtime 1.21-1.26 from PyPI, and CUDA 13.x uses ONNX Runtime 1.27-1.29 from PyPI. The static `mathcraft-ocr[gpu]` extra follows the current PyPI default (CUDA 13 and Python 3.11+); use `gpu-cu12` for CUDA 12. CUDA 11 installations must also select the official CUDA 11 package feed, so LaTeXSnipper's dependency wizard is recommended for that configuration.
 
 ## Quick Start
 
@@ -190,11 +212,36 @@ Model artifacts are downloaded from the MathCraft-Models release assets declared
 
 `provider_preference` accepts:
 
-- `auto`: prefer CUDA when available and valid, otherwise CPU.
+- `auto`: prefer CUDA, then a platform accelerator, and finally CPU; TensorRT remains explicit because of its first-use engine build cost.
 - `cpu`: force CPU.
-- `gpu`: request CUDA-capable ONNX Runtime.
+- `gpu`: request the first available supported accelerator.
+- `cuda`: request CUDA.
+- `tensorrt` or `trt`: request TensorRT, followed by CUDA and CPU for unsupported nodes.
+- `directml` or `dml`: request DirectML.
+- `coreml`: request CoreML.
+- `openvino`: request OpenVINO.
+
+Advanced callers can pass an explicit ordered provider list and provider options:
+
+```python
+runtime = MathCraftRuntime(
+    providers=[
+        (
+            "TensorrtExecutionProvider",
+            {
+                "device_id": 0,
+                "trt_engine_cache_enable": True,
+                "trt_engine_cache_path": "./trt-cache",
+            },
+        ),
+        ("CUDAExecutionProvider", {"device_id": 0}),
+    ]
+)
+```
+
+`auto` deliberately prefers CUDA over TensorRT because TensorRT can spend substantial time building an engine on first use. Select `tensorrt` explicitly when its native runtime is installed; enable its engine cache for repeated startup performance.
 
-The actual provider is available on results through the `provider` field.
+The actual provider is available on recognition results through the `provider` field. Doctor and warmup reports also expose `device_id`, `device_name`, `device_uuid`, and `device_verified` under `provider_info`. GPU sessions bind the reported `device_id` explicitly; `device_verified` becomes true only after the runtime confirms the device used by initialized inference sessions.
 
 ## Development
 

{mathcraft_ocr-0.2.7 → mathcraft_ocr-0.2.9}/README_MATHCRAFT_OCR.md

@@ -30,9 +30,27 @@ GPU backend:
 pip install "mathcraft-ocr[gpu]"
 ```
 
-Install only one backend extra in a clean environment. `onnxruntime` and `onnxruntime-gpu` should not be mixed in the same environment.
+CUDA 12 backend:
 
-LaTeXSnipper's dependency wizard selects the ONNX Runtime GPU wheel line from the detected CUDA toolkit. CUDA 11.x uses the ONNX Runtime CUDA 11 package feed, CUDA 12.x uses the stable PyPI GPU wheels, and CUDA 13.x uses the ONNX Runtime CUDA 13 nightly feed. Static `mathcraft-ocr[gpu]` package metadata cannot inspect the local CUDA toolkit, so it keeps a broad stable PyPI range; CUDA 11.x users installing manually should use the CUDA 11 feed shown by the wizard.
+```powershell
+pip install "mathcraft-ocr[gpu-cu12]"
+```
+
+Windows DirectML backend:
+
+```powershell
+pip install "mathcraft-ocr[directml]"
+```
+
+Intel OpenVINO backend on Windows or Linux:
+
+```powershell
+pip install "mathcraft-ocr[openvino]"
+```
+
+Install only one backend extra in a clean environment. The CPU, CUDA/TensorRT, DirectML, and OpenVINO ONNX Runtime distributions must not be mixed in the same environment. The standard `onnxruntime` macOS wheel includes CoreML EP support.
+
+LaTeXSnipper's dependency wizard selects the ONNX Runtime GPU line from the detected CUDA toolkit: CUDA 11.x uses ONNX Runtime 1.20 from the official CUDA 11 feed, CUDA 12.x uses ONNX Runtime 1.21-1.26 from PyPI, and CUDA 13.x uses ONNX Runtime 1.27-1.29 from PyPI. The static `mathcraft-ocr[gpu]` extra follows the current PyPI default (CUDA 13 and Python 3.11+); use `gpu-cu12` for CUDA 12. CUDA 11 installations must also select the official CUDA 11 package feed, so LaTeXSnipper's dependency wizard is recommended for that configuration.
 
 ## Quick Start
 
@@ -144,11 +162,36 @@ Model artifacts are downloaded from the MathCraft-Models release assets declared
 
 `provider_preference` accepts:
 
-- `auto`: prefer CUDA when available and valid, otherwise CPU.
+- `auto`: prefer CUDA, then a platform accelerator, and finally CPU; TensorRT remains explicit because of its first-use engine build cost.
 - `cpu`: force CPU.
-- `gpu`: request CUDA-capable ONNX Runtime.
+- `gpu`: request the first available supported accelerator.
+- `cuda`: request CUDA.
+- `tensorrt` or `trt`: request TensorRT, followed by CUDA and CPU for unsupported nodes.
+- `directml` or `dml`: request DirectML.
+- `coreml`: request CoreML.
+- `openvino`: request OpenVINO.
+
+Advanced callers can pass an explicit ordered provider list and provider options:
 
-The actual provider is available on results through the `provider` field.
+```python
+runtime = MathCraftRuntime(
+    providers=[
+        (
+            "TensorrtExecutionProvider",
+            {
+                "device_id": 0,
+                "trt_engine_cache_enable": True,
+                "trt_engine_cache_path": "./trt-cache",
+            },
+        ),
+        ("CUDAExecutionProvider", {"device_id": 0}),
+    ]
+)
+```
+
+`auto` deliberately prefers CUDA over TensorRT because TensorRT can spend substantial time building an engine on first use. Select `tensorrt` explicitly when its native runtime is installed; enable its engine cache for repeated startup performance.
+
+The actual provider is available on recognition results through the `provider` field. Doctor and warmup reports also expose `device_id`, `device_name`, `device_uuid`, and `device_verified` under `provider_info`. GPU sessions bind the reported `device_id` explicitly; `device_verified` becomes true only after the runtime confirms the device used by initialized inference sessions.
 
 ## Development
 

{mathcraft_ocr-0.2.7 → mathcraft_ocr-0.2.9}/mathcraft_ocr/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.7"
+__version__ = "0.2.9"
 
 __all__ = [
     "DoctorReport",
@@ -12,6 +12,8 @@ __all__ = [
     "MathCraftRuntime",
     "MixedRecognitionResult",
     "OCRRegion",
+    "ProviderInfo",
+    "ProviderSpec",
     "__version__",
     "run_doctor",
 ]
@@ -32,6 +34,10 @@ def __getattr__(name: str) -> object:
         from . import doctor
 
         return getattr(doctor, name)
+    if name in {"ProviderInfo", "ProviderSpec"}:
+        from . import providers
+
+        return getattr(providers, name)
     if name == "MathCraftError":
         from .errors import MathCraftError
 

mathcraft_ocr-0.2.9/mathcraft_ocr/adapters/common.py

@@ -0,0 +1,129 @@
+# coding: utf-8
+
+from __future__ import annotations
+
+import importlib
+from functools import lru_cache
+from pathlib import Path
+
+from ..providers import ACCELERATOR_PROVIDER_NAMES, ProviderInfo
+
+
+ProviderOptions = tuple[tuple[str, str], ...]
+ProviderConfig = tuple[str, ProviderOptions]
+
+
+def _ort():
+    return importlib.import_module("onnxruntime")
+
+
+def session_providers(provider_info: ProviderInfo) -> list[str | tuple[str, dict[str, object]]]:
+    if provider_info.provider_specs:
+        return [spec.as_ort_provider() for spec in provider_info.provider_specs]
+    available = list(provider_info.available_providers)
+    active = provider_info.active_provider
+    if active and active in ACCELERATOR_PROVIDER_NAMES and "CPUExecutionProvider" in available:
+        return [(active, {"device_id": int(provider_info.device_id or 0)}), "CPUExecutionProvider"]
+    if active and active in ACCELERATOR_PROVIDER_NAMES:
+        return [(active, {"device_id": int(provider_info.device_id or 0)})]
+    if "CPUExecutionProvider" in available:
+        return ["CPUExecutionProvider"]
+    return available
+
+
+def create_session(model_path: str | Path, provider_info: ProviderInfo):
+    model_path = str(Path(model_path).resolve())
+    provider_config = _freeze_provider_config(session_providers(provider_info))
+    session = _create_session_cached(model_path, provider_config)
+    enforce_session_provider(session, provider_info)
+    return session
+
+
+@lru_cache(maxsize=16)
+def _create_session_cached(model_path: str, providers: tuple[ProviderConfig, ...]):
+    ort = _ort()
+    configured = [
+        (name, {key: value for key, value in options}) if options else name
+        for name, options in providers
+    ]
+    kwargs = {
+        "providers": configured,
+        "enable_fallback": False,
+    }
+    session_options = _session_options(ort, providers)
+    if session_options is not None:
+        kwargs["sess_options"] = session_options
+    return ort.InferenceSession(model_path, **kwargs)
+
+
+def _session_options(ort, providers: tuple[ProviderConfig, ...]):
+    create_options = getattr(ort, "SessionOptions", None)
+    if not callable(create_options):
+        return None
+    session_options = create_options()
+    session_options.log_severity_level = 4
+    names = {name for name, _options in providers}
+    if "DmlExecutionProvider" not in names:
+        return session_options
+    session_options.enable_mem_pattern = False
+    execution_mode = getattr(getattr(ort, "ExecutionMode", None), "ORT_SEQUENTIAL", None)
+    if execution_mode is not None:
+        session_options.execution_mode = execution_mode
+    return session_options
+
+
+def _freeze_provider_config(
+    providers: list[str | tuple[str, dict[str, object]]],
+) -> tuple[ProviderConfig, ...]:
+    frozen: list[ProviderConfig] = []
+    for item in providers:
+        if isinstance(item, str):
+            frozen.append((item, ()))
+            continue
+        name, options = item
+        frozen.append((name, tuple(sorted((str(key), str(value)) for key, value in options.items()))))
+    return tuple(frozen)
+
+
+def enforce_session_provider(session, provider_info: ProviderInfo) -> None:
+    validate_session_provider(
+        session,
+        str(provider_info.active_provider or ""),
+        int(provider_info.device_id or 0),
+    )
+
+
+def validate_session_provider(
+    session,
+    active_provider: str,
+    device_id: int = 0,
+    *,
+    runtime_name: str = "ONNX Runtime",
+) -> None:
+    actual = list(session.get_providers() or [])
+    active = str(active_provider or "")
+    if not actual or actual[0] != active:
+        provider_kind = "ONNX accelerator provider" if active in ACCELERATOR_PROVIDER_NAMES else "ONNX provider"
+        raise RuntimeError(
+            f"requested {provider_kind} {active or '<none>'}, "
+            f"but {runtime_name} session providers are {actual}"
+        )
+    if active in {"CUDAExecutionProvider", "TensorrtExecutionProvider", "DmlExecutionProvider"}:
+        get_options = getattr(session, "get_provider_options", None)
+        if callable(get_options):
+            options_by_provider = get_options() or {}
+            active_options = options_by_provider.get(active, {}) if isinstance(options_by_provider, dict) else {}
+            actual_device_id = active_options.get("device_id") if isinstance(active_options, dict) else None
+            if actual_device_id not in (None, "") and int(actual_device_id) != int(device_id):
+                raise RuntimeError(
+                    f"requested ONNX provider {active} device_id={int(device_id)}, "
+                    f"but {runtime_name} session uses device_id={actual_device_id}"
+                )
+    disable_fallback = getattr(session, "disable_fallback", None)
+    if not callable(disable_fallback):
+        raise RuntimeError(f"{runtime_name} session cannot disable provider fallback")
+    disable_fallback()
+
+
+def clear_session_cache() -> None:
+    _create_session_cached.cache_clear()

{mathcraft_ocr-0.2.7 → mathcraft_ocr-0.2.9}/mathcraft_ocr/adapters/text_recognizer.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from functools import lru_cache
 from pathlib import Path
 
@@ -10,6 +11,12 @@ from rapidocr import EngineType, LangRec, ModelType, OCRVersion
 from rapidocr.ch_ppocr_rec import TextRecInput, TextRecognizer
 from rapidocr.utils.typings import TaskType
 
+from .common import create_session
+from ..providers import ProviderInfo
+
+
+logging.getLogger("RapidOCR").setLevel(logging.WARNING)
+
 
 class _Config(dict):
     def __init__(self, *args, **kwargs):
@@ -54,23 +61,13 @@ def recognize_pp_text_lines(
 
 def _create_pp_text_recognizer(model_dir: Path, provider_info) -> TextRecognizer:
     model_dir = model_dir.resolve()
-    active_provider = str(getattr(provider_info, "active_provider", "") or "")
-    use_cuda = active_provider in {"CUDAExecutionProvider", "TensorrtExecutionProvider"}
-    use_dml = active_provider == "DmlExecutionProvider"
-    return _create_pp_text_recognizer_cached(
-        str(model_dir),
-        active_provider,
-        use_cuda,
-        use_dml,
-    )
+    return _create_pp_text_recognizer_cached(str(model_dir), provider_info)
 
 
 @lru_cache(maxsize=8)
 def _create_pp_text_recognizer_cached(
     model_dir: str,
-    active_provider: str,
-    use_cuda: bool,
-    use_dml: bool,
+    provider_info: ProviderInfo,
 ) -> TextRecognizer:
     model_dir = Path(model_dir)
     model_candidates = sorted(model_dir.glob("**/*rec*.onnx"))
@@ -84,6 +81,7 @@ def _create_pp_text_recognizer_cached(
     is_server = "server" in model_name or "server" in model_dir.name
     is_v5 = "v5" in model_name or "v5" in model_dir.name
     is_english = dict_path.name == "en_dict.txt"
+    session = create_session(model_path, provider_info)
     config = _Config({
         "engine_type": EngineType.ONNXRUNTIME,
         "lang_type": LangRec.EN if is_english else LangRec.CH,
@@ -96,51 +94,10 @@ def _create_pp_text_recognizer_cached(
         "rec_img_shape": [3, 48, 320],
         "rec_batch_num": 6,
         "font_path": None,
-        "engine_cfg": {
-            "intra_op_num_threads": -1,
-            "inter_op_num_threads": -1,
-            "enable_cpu_mem_arena": False,
-            "cpu_ep_cfg": {"arena_extend_strategy": "kSameAsRequested"},
-            "use_cuda": use_cuda,
-            "cuda_ep_cfg": {
-                "device_id": 0,
-                "arena_extend_strategy": "kNextPowerOfTwo",
-                "cudnn_conv_algo_search": "EXHAUSTIVE",
-                "do_copy_in_default_stream": True,
-            },
-            "use_dml": use_dml,
-            "dm_ep_cfg": None,
-            "use_cann": False,
-            "cann_ep_cfg": {
-                "device_id": 0,
-                "arena_extend_strategy": "kNextPowerOfTwo",
-                "npu_mem_limit": 21474836480,
-                "op_select_impl_mode": "high_performance",
-                "optypelist_for_implmode": "Gelu",
-                "enable_cann_graph": True,
-            },
-        },
+        "session": session,
+        "engine_cfg": {},
     })
-    recognizer = TextRecognizer(config)
-    _enforce_strict_provider(recognizer, active_provider)
-    return recognizer
-
-
-def _enforce_strict_provider(recognizer: TextRecognizer, active_provider: str) -> None:
-    engine = getattr(recognizer, "session", None)
-    session = getattr(engine, "session", None)
-    if session is None:
-        raise RuntimeError("RapidOCR did not expose its ONNX Runtime session")
-    actual = list(session.get_providers() or [])
-    if not active_provider or not actual or actual[0] != active_provider:
-        raise RuntimeError(
-            f"requested ONNX provider {active_provider or '<none>'}, "
-            f"but RapidOCR session providers are {actual}"
-        )
-    disable_fallback = getattr(session, "disable_fallback", None)
-    if not callable(disable_fallback):
-        raise RuntimeError("RapidOCR ONNX Runtime session cannot disable provider fallback")
-    disable_fallback()
+    return TextRecognizer(config)
 
 
 def clear_text_recognizer_cache() -> None:

{mathcraft_ocr-0.2.7 → mathcraft_ocr-0.2.9}/mathcraft_ocr/cli.py

@@ -16,6 +16,9 @@ from .serialization import (
 )
 
 
+_PROVIDER_HELP = "auto, cpu, gpu, cuda, tensorrt, directml, coreml, or openvino"
+
+
 def _resolve_ocr_output_path(args: argparse.Namespace) -> Path | None:
     output = str(getattr(args, "output", "") or "").strip()
     output_dir = str(getattr(args, "output_dir", "") or "").strip()
@@ -45,22 +48,22 @@ def build_parser() -> argparse.ArgumentParser:
     models_sub.add_parser("check")
 
     doctor = sub.add_parser("doctor")
-    doctor.add_argument("--provider", default="auto")
+    doctor.add_argument("--provider", default="auto", help=_PROVIDER_HELP)
 
     warmup = sub.add_parser("warmup")
     warmup.add_argument("--profile", default="formula")
-    warmup.add_argument("--provider", default="auto")
+    warmup.add_argument("--provider", default="auto", help=_PROVIDER_HELP)
 
     ocr = sub.add_parser("ocr")
     ocr.add_argument("image")
     ocr.add_argument("--profile", choices=("formula", "text", "mixed"), default="mixed")
-    ocr.add_argument("--provider", default="auto")
+    ocr.add_argument("--provider", default="auto", help=_PROVIDER_HELP)
     ocr.add_argument("--output", "-o", default="")
     ocr.add_argument("--output-dir", default="")
     ocr.add_argument("--json", action="store_true", dest="as_json")
 
     worker = sub.add_parser("worker")
-    worker.add_argument("--provider", default="auto")
+    worker.add_argument("--provider", default="auto", help=_PROVIDER_HELP)
     return parser