pyocrust-gpu 0.1.0__cp310-abi3-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pyocrust/__init__.py ADDED
@@ -0,0 +1,74 @@
1
+ """pyocrust — wrapper nativo unificado de OCR y análisis de estructura documental.
2
+
3
+ La implementación vive en Rust (crate ``pyocrust_core``, backend ``oar-ocr``)
4
+ y se expone a Python mediante el módulo nativo ``pyocrust._pyocrust_core``,
5
+ construido con Maturin. Este paquete es solo la fachada pública de alto nivel.
6
+
7
+ Fases del proyecto (ver ``PLANNING.md``): ``VeloceOCR`` devuelve ``OcrResult``
8
+ en los presets de texto (``pp_ocrv6*``) y ``StructureResult`` —con
9
+ ``to_markdown()``, tablas HTML y fórmulas LaTeX— en ``pp_structurev3``
10
+ (ADR-003).
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from typing import Final
16
+
17
+ try:
18
+ from pyocrust._pyocrust_core import (
19
+ BoundingBox,
20
+ LayoutRegion,
21
+ OcrResult,
22
+ PyOcrError,
23
+ PyOcrRuntimeError,
24
+ PyOcrValueError,
25
+ StructureResult,
26
+ TaskPredictor,
27
+ TextRegion,
28
+ VeloceOCR,
29
+ native_version as _native_version,
30
+ resolve_models_dir,
31
+ models_status,
32
+ )
33
+ except ImportError as exc: # pragma: no cover - solo si el binario no está construido
34
+ raise ImportError(
35
+ "El módulo nativo 'pyocrust._pyocrust_core' no está construido. "
36
+ "Ejecuta 'maturin develop' en la raíz del proyecto antes de importar pyocrust."
37
+ ) from exc
38
+
39
+ __version__: Final[str] = _native_version()
40
+
41
+ from pyocrust._pyocrust_core import model_catalog, pipeline_profiles
42
+ from pyocrust.gpu import enable_cuda
43
+ from pyocrust.hardware import GpuInfo, HardwareProfile, detect_hardware
44
+ from pyocrust.multifeature import FEATURE_ALIASES, recognize
45
+ from pyocrust.resolver import TaskSpec, PipelineChoice, resolve_pipeline
46
+ from pyocrust._pyocrust_core import available_providers
47
+
48
+ __all__: Final[list[str]] = [
49
+ "__version__",
50
+ "BoundingBox",
51
+ "LayoutRegion",
52
+ "OcrResult",
53
+ "PyOcrError",
54
+ "PyOcrRuntimeError",
55
+ "PyOcrValueError",
56
+ "StructureResult",
57
+ "TaskPredictor",
58
+ "TextRegion",
59
+ "VeloceOCR",
60
+ "resolve_models_dir",
61
+ "models_status",
62
+ "model_catalog",
63
+ "pipeline_profiles",
64
+ "available_providers",
65
+ "enable_cuda",
66
+ "GpuInfo",
67
+ "HardwareProfile",
68
+ "detect_hardware",
69
+ "TaskSpec",
70
+ "PipelineChoice",
71
+ "resolve_pipeline",
72
+ "FEATURE_ALIASES",
73
+ "recognize",
74
+ ]
pyocrust/__init__.pyi ADDED
@@ -0,0 +1,278 @@
1
+ """Stubs de tipos de pyocrust.
2
+
3
+ Refleja el contrato PyO3 real: ``VeloceOCR.recognize`` devuelve ``OcrResult``
4
+ en los presets de texto (``pp_ocrv6*``) y ``StructureResult`` en
5
+ ``pp_structurev3`` (ADR-003) e ``indra`` (S2.2 parcial): tres familias de presets.
6
+
7
+ S3 re-exports (immutable dataclasses, defined in hardware/resolver):
8
+ GpuInfo(name: str | None=None, vram_bytes: int | None=None).
9
+ HardwareProfile(cpu_count: int, ram_bytes: int | None, gpu: GpuInfo | None=None).
10
+ CPU is a positive int; RAM/VRAM are positive ints or None (not bool).
11
+ Invalid numeric values raise ValueError; invalid gpu type raises TypeError.
12
+ detect_hardware() returns physical inventory, not wheel CUDA capability;
13
+ unknown RAM/VRAM remain None. CUDA_VISIBLE_DEVICES filters NVIDIA inventory.
14
+
15
+ TaskSpec(document_kind='digital', ocr_only=True, formulas='none', tables=False,
16
+ quality='speed', output_format='text', license_commercial_use=True,
17
+ license_acknowledge=False). Allowed enums: scanned/digital/mixed;
18
+ none/with_text/only; speed/balanced/accuracy; text/markdown/html/json.
19
+ Invalid enums raise ValueError; ocr_only/tables and both license flags must be
20
+ bool (TypeError). `license_commercial_use` and `license_acknowledge` are USER
21
+ declarations (commercial intent / acceptance of attribution), not the model's
22
+ terms: `license_commercial_use=True` keeps restricted models (Indra,
23
+ OpenRAIL-M-Mod) out of the recommendation, and a restricted model also
24
+ requires `license_acknowledge=True` (Indra §7).
25
+ PipelineChoice has preset: str, size: str | None, tasks: tuple[str, ...],
26
+ models_dir: str, offline: bool; id is pp_ocrv6_{size} or the structure preset.
27
+ resolve_pipeline(task: TaskSpec, hardware: HardwareProfile | None=None):
28
+ formulas/tables/Markdown/HTML/not ocr_only take precedence -> pp_structurev3,
29
+ size=None. Otherwise speed/unknown RAM/<4 GiB -> tiny; balanced/<8 GiB ->
30
+ small; otherwise medium. Scanned/mixed adds orientation/rectification;
31
+ accuracy with >=8 GiB physical VRAM adds Indra as an alternative, not execution.
32
+ Explicit hardware bypasses discovery; incorrect argument types raise TypeError.
33
+ No models/download/preflight; native models_dir resolution can normalize and
34
+ re-export relative OAR_HOME. PYOCRUST_OFFLINE is false for unset/empty/0/false/no
35
+ (case-insensitive, no whitespace trimming). Tasks are recommendations only;
36
+ output_format selects a preset, not a conversion. No GPU/availability guarantee.
37
+
38
+ Multi-feature: ``recognize(image, features=[...])`` runs one or more feature ids
39
+ from ``pipeline_profiles()`` (or an alias of ``FEATURE_ALIASES``) over the same
40
+ image. One feature returns today's object unwrapped (``OcrResult`` /
41
+ ``StructureResult`` / the task dictionary); several return ``{label: output}``
42
+ keyed by the label the caller used, keeping each feature's schema (never
43
+ flattened). Unknown/duplicate/empty features, or a bare ``str`` instead of a
44
+ sequence, raise ``PyOcrValueError`` before any model loads. Sequential by
45
+ default (ADR-008); ``parallel=True`` runs the features in threads, overlapping
46
+ the native GIL-free inferences.
47
+ """
48
+
49
+ from __future__ import annotations
50
+
51
+ from os import PathLike
52
+ from typing import Sequence
53
+ from .hardware import GpuInfo as GpuInfo, HardwareProfile as HardwareProfile, detect_hardware as detect_hardware
54
+ from .multifeature import FEATURE_ALIASES as FEATURE_ALIASES, recognize as recognize
55
+ from .resolver import TaskSpec as TaskSpec, PipelineChoice as PipelineChoice, resolve_pipeline as resolve_pipeline
56
+
57
+ def model_catalog() -> dict[str, dict]:
58
+ """Metadata by artifact name, without filesystem scan, network or inference.
59
+
60
+ Rows: name/task/description: str, params: int | None, size_bytes: int | None,
61
+ env_vars: list[str], license: str, license_commercial_use: bool,
62
+ license_acknowledge: bool, license_restricted: bool, license_notes: str,
63
+ license_url: str | None. params is always None; upstream sizes use
64
+ find(name), Indra sizes remain None. Includes dictionaries/tokenizers.
65
+ license_commercial_use is False for Indra (OpenRAIL-M-Mod) and Unknown.
66
+ env_vars: OAR_HOME, OCR_MODELS_CACHE_DIR, PYOCRUST_OFFLINE,
67
+ CUDA_LAUNCH_BLOCKING, RUST_LOG; no OAR_VL_* controls for Indra ONNX.
68
+ """
69
+ ...
70
+ def pipeline_profiles() -> dict[str, dict]:
71
+ """Registered presets/tasks by ID, without disk scan, network or inference.
72
+
73
+ Rows: id/family/quality/output_format/description: str, artifacts: list[str],
74
+ disk_bytes: int | None, ram_bytes: int | None, license: str,
75
+ license_commercial_use: bool, license_acknowledge: bool,
76
+ license_restricted: bool, license_notes: str, license_url: str | None.
77
+ Five presets plus eleven tasks;
78
+ exact artifacts come from registry. disk_bytes sums upstream sizes, None if
79
+ any entry is missing or sum overflows (Indra: None); ram_bytes always None.
80
+ File size is not parameters, measured RAM or proof of local availability.
81
+ """
82
+ ...
83
+
84
+ __version__: str
85
+
86
+ class BoundingBox:
87
+ x1: float
88
+ y1: float
89
+ x2: float
90
+ y2: float
91
+ def __init__(self, x1: float, y1: float, x2: float, y2: float) -> None: ...
92
+ @property
93
+ def width(self) -> float: ...
94
+ @property
95
+ def height(self) -> float: ...
96
+
97
+ class TextRegion:
98
+ text: str
99
+ confidence: float
100
+ box: BoundingBox
101
+ def __init__(self, text: str, confidence: float, box: BoundingBox) -> None: ...
102
+
103
+ class OcrResult:
104
+ regions: Sequence[TextRegion]
105
+ def __init__(self, regions: Sequence[TextRegion]) -> None: ...
106
+ @property
107
+ def text(self) -> str: ...
108
+ @property
109
+ def confidence(self) -> float: ...
110
+ def __len__(self) -> int: ...
111
+
112
+ class LayoutRegion:
113
+ """Elemento de PP-StructureV3 o Indra; en ``formula``, ``text`` es LaTeX.
114
+
115
+ En bloques Indra, ``confidence=0.0`` indica score no disponible.
116
+ """
117
+
118
+ kind: str
119
+ text: str
120
+ confidence: float
121
+ box: BoundingBox
122
+ def __init__(
123
+ self, kind: str, text: str, confidence: float, box: BoundingBox
124
+ ) -> None: ...
125
+
126
+ class StructureResult:
127
+ """Salida de PP-StructureV3 o Indra, sin aplanar (ADR-003).
128
+
129
+ Indra conserva LaTeX inline en Markdown/regiones; ``formulas=[]`` indica
130
+ ausencia de registros separados, no ausencia de matemáticas.
131
+ """
132
+
133
+ elements: Sequence[LayoutRegion]
134
+ regions: Sequence[TextRegion]
135
+ def to_markdown(self) -> str: ...
136
+ formulas: Sequence[str]
137
+ def __len__(self) -> int: ...
138
+
139
+ class PyOcrError(Exception): ...
140
+ class PyOcrValueError(PyOcrError): ...
141
+ class PyOcrRuntimeError(PyOcrError): ...
142
+
143
+ class TaskPredictor:
144
+ """Eleven standalone tasks; schemas list every returned key (S2.4).
145
+
146
+ ``text_detection`` and ``seal_text_detection``: ``{detections: list[dict]}``,
147
+ items ``{bbox: list[list[float]], score: float}`` (four [x, y] points).
148
+ ``text_recognition``: ``{text: str, score: float}``.
149
+ ``layout_detection``: ``{elements: list[dict], is_reading_order_sorted: bool}``,
150
+ items ``{bbox: list[list[float]], element_type: str, score: float}``.
151
+ ``table_classification``: ``{classifications: list[dict]}``, items
152
+ ``{class_id: int, label: str, score: float}``.
153
+ ``table_structure_recognition``: ``{structures: list[str], bboxes: list[list[float]]}``;
154
+ structure tokens and geometry, NOT reconstructed HTML.
155
+ ``table_cell_detection``: ``{cells: list[dict]}``, items
156
+ ``{bbox: list[list[float]], label: str, score: float}``.
157
+ Layout/cell boxes also contain four [x, y] points.
158
+ ``document_orientation`` and ``text_line_orientation``: ``{orientations: list[dict]}``,
159
+ items ``{class_id: int, label: str, score: float}``.
160
+ ``document_rectification``: ``{image: bytes, width: int, height: int}`` (PNG).
161
+ ``formula_recognition``: ``{formula: str, score: float | None}``;
162
+ unavailable score is None; fixed model ``PP-FormulaNet-S``.
163
+
164
+ Exact option whitelist/defaults:
165
+ text_detection: score_threshold=0.3, box_threshold=0.6, unclip_ratio=1.5,
166
+ max_candidates=1000.
167
+ text_recognition: score_threshold=0.0, dict_path (priority below).
168
+ layout_detection: score_threshold=0.5, model_name='pp_doclayoutv3'.
169
+ table_classification: score_threshold=0.5, topk=2, input_shape=(224, 224).
170
+ table_structure_recognition: dict_path, model_name, input_shape; omitted
171
+ model_name/shape leave upstream path/ONNX detection (wired fallback).
172
+ Local (512, 512) fallback is NOT forwarded when shape is omitted.
173
+ table_cell_detection: score_threshold=0.3, model_name detected from path,
174
+ fallback 'rt-detr-l_wired_table_cell_det'.
175
+ document_orientation: score_threshold=0.5, topk=4.
176
+ text_line_orientation: score_threshold=0.5, topk=2, input_shape=(80, 160).
177
+ seal_text_detection: score_threshold=0.5 only.
178
+ document_rectification/formula_recognition: no options.
179
+ input_shape is (H, W), positive u32 integers. Unknown task/option or zero
180
+ shape raises PyOcrValueError; whitelist is checked before model resolution.
181
+
182
+ models=None ensures registered artifacts. Explicit str is a model file,
183
+ not a directory; dict requires 'model', with optional 'dict'/'tokenizer'.
184
+ Explicit paths bypass downloads. Text/table dictionary priority:
185
+ options['dict_path'] > models['dict'] > lazy canonical-model sibling
186
+ (ppocrv6_tiny_dict.txt / table_structure_dict_ch.txt).
187
+ Formula tokenizer: models['tokenizer'] > pp-formulanet-tokenizer.json sibling.
188
+ All selected model/dict/tokenizer assets must be existing local files and
189
+ are canonicalized before upstream; invalid overrides never fall back.
190
+ Missing/directory/canonicalization failures raise PyOcrRuntimeError with
191
+ path/cause, without implicit upstream downloads. Registered model filenames
192
+ are documented in DESIGN.md section 3.1.2, sourced from storage/registry.rs.
193
+
194
+ predict_batch preserves input order and returns [] for empty input.
195
+ Inference releases the GIL; decoding and Python mapping retain it.
196
+
197
+ ``device`` is opt-in (default ``"cpu"``) and selects the ONNX Runtime
198
+ execution provider *before* the predictor is built, via
199
+ ``core::device::resolve_device``. ``provider_effective`` reports what really
200
+ runs. ``available_providers()`` lists the accelerators that actually register.
201
+ Approval covers code/contracts, not eleven real inferences or GPU validation.
202
+ """
203
+ def __init__(self, task: str, models: str | dict[str, str] | None = None, device: str = "cpu", license_commercial_use: bool = True, license_acknowledge: bool = False, **options: object) -> None: ...
204
+ @property
205
+ def provider_effective(self) -> str: ...
206
+ @property
207
+ def license(self) -> dict[str, object]:
208
+ """Resolved license for this task's registered artifacts; ``Unknown``
209
+ when explicit ``models`` paths are used (provenance cannot be verified)."""
210
+ ...
211
+ def predict(self, image: str | bytes | PathLike[str]) -> dict[str, object]: ...
212
+ def predict_batch(self, images: Sequence[str | bytes | PathLike[str]]) -> list[dict[str, object]]: ...
213
+
214
+ def available_providers() -> list[str]:
215
+ """Accelerator execution providers that really register in this host, or ``[]``.
216
+
217
+ Probes the compiled candidates (``cuda``/``directml``) through ONNX Runtime;
218
+ a physical GPU (``detect_hardware``) is not proof that an EP exists here.
219
+ """
220
+ ...
221
+
222
+ def resolve_models_dir(custom_path: str | None = None) -> str: ...
223
+
224
+ def models_status(
225
+ custom_path: str | None = None,
226
+ ) -> dict[str, object]:
227
+ """Estado en disco: ``models_dir``, ``offline``, ``presets``, ``indra``.
228
+
229
+ ``['indra']`` es el catálogo (``required=false``); ``['presets']['indra']``
230
+ son los nueve requisitos efectivos (``required=true``) en ``models_dir/indra``.
231
+ """
232
+
233
+ class VeloceOCR:
234
+ def __init__(self, preset: str = "pp_ocrv6", custom_path: str | None = None, device: str = "cpu", license_commercial_use: bool = True, license_acknowledge: bool = False) -> None: ...
235
+ @property
236
+ def models_dir(self) -> str: ...
237
+ @property
238
+ def license(self) -> dict[str, object]:
239
+ """Resolved license for this preset's artifacts (six fields)."""
240
+ ...
241
+ @property
242
+ def provider_effective(self) -> str:
243
+ """EP that really ran (``cpu``/``cuda``/``directml``/...); never faked.
244
+
245
+ Requesting ``device="cuda"`` with no registered CUDA EP raises at
246
+ construction instead of labelling CPU as GPU.
247
+ """
248
+ ...
249
+ def recognize(
250
+ self, image: str | bytes | PathLike[str]
251
+ ) -> OcrResult | StructureResult: ...
252
+
253
+ __all__: list[str] = [
254
+ "__version__",
255
+ "BoundingBox",
256
+ "LayoutRegion",
257
+ "OcrResult",
258
+ "PyOcrError",
259
+ "PyOcrRuntimeError",
260
+ "PyOcrValueError",
261
+ "StructureResult",
262
+ "TaskPredictor",
263
+ "TextRegion",
264
+ "VeloceOCR",
265
+ "resolve_models_dir",
266
+ "models_status",
267
+ "model_catalog",
268
+ "pipeline_profiles",
269
+ "available_providers",
270
+ "GpuInfo",
271
+ "HardwareProfile",
272
+ "detect_hardware",
273
+ "TaskSpec",
274
+ "PipelineChoice",
275
+ "resolve_pipeline",
276
+ "FEATURE_ALIASES",
277
+ "recognize",
278
+ ]
@@ -0,0 +1,4 @@
1
+ [diffend] Oversized file quarantined before diffing.
2
+ name: pyocrust/_pyocrust_core.pyd
3
+ size: 37424640 bytes
4
+ sha256: b7d7c36920acef544b2e6e439f34d104dacfb43cdfc78478dca43481d54cd916
pyocrust/gpu.py ADDED
@@ -0,0 +1,57 @@
1
+ """Habilitar en runtime el execution provider CUDA de ``pyocrust``.
2
+
3
+ ``onnxruntime_providers_cuda.dll`` (el provider que ONNX Runtime carga aparte)
4
+ importa ``cublas64_13.dll`` y ``cublasLt64_13.dll``. Esas DLL **están** en el
5
+ entorno (las trae ``nvidia-cublas-cu13`` o ``torch``), pero en directorios que el
6
+ proceso no mira: desde Python 3.8 ``LoadLibrary`` **ignora ``PATH``** en Windows.
7
+
8
+ ``enable_cuda()`` añade esos directorios al *search path* (``os.add_dll_directory``)
9
+ de forma *best-effort* e idempotente, sin descargar ni instalar nada, y devuelve
10
+ los EPs que registran. En Linux/macOS el cargador respeta ``RPATH``/``LD_LIBRARY_PATH``,
11
+ así que allí es un no-op.
12
+
13
+ Uso (antes de construir el motor, ver ``GPU.md``)::
14
+
15
+ import pyocrust
16
+ pyocrust.enable_cuda() # -> ['cuda', 'directml'] p.ej.
17
+ ocr = pyocrust.VeloceOCR("pp_ocrv6", device="cuda")
18
+ """
19
+ from __future__ import annotations
20
+
21
+ import os
22
+ import site
23
+ from pathlib import Path
24
+
25
+ _HERE = Path(__file__).resolve().parent # el provider puede viajar junto al .pyd
26
+
27
+
28
+ def _candidate_dirs() -> list[Path]:
29
+ """Directorios donde puede vivir el runtime CUDA, en orden de preferencia."""
30
+ dirs: list[Path] = [_HERE]
31
+ for key in ("CUDA_PATH", "CUDA_HOME"):
32
+ if (venv := os.environ.get(key)):
33
+ dirs += [Path(venv) / "bin", Path(venv) / "bin" / "x86_64"]
34
+ bases = {*site.getsitepackages(), site.getusersitepackages()}
35
+ for base in bases:
36
+ b = Path(base)
37
+ dirs += sorted(b.glob("nvidia/*/bin*")) # nvidia-cublas-cu13, nvidia-cudnn-cu13…
38
+ dirs.append(b / "torch" / "lib") # torch trae cublas/cudnn/cudart
39
+ return [d for d in dirs if d.is_dir()]
40
+
41
+
42
+ def enable_cuda() -> list[str]:
43
+ """Añade al search path las DLL del runtime CUDA presentes en el entorno.
44
+
45
+ Best-effort e idempotente: un directorio que no exista o no se deje abrir se
46
+ ignora. Devuelve ``available_providers()`` tras intentarlo, para que el
47
+ llamante compruebe si ``'cuda'`` quedó registrado.
48
+ """
49
+ if hasattr(os, "add_dll_directory"): # solo Windows
50
+ for d in _candidate_dirs():
51
+ try:
52
+ os.add_dll_directory(str(d))
53
+ except OSError:
54
+ pass # ponytail: se ignora el fallo; el diagnóstico lo da available_providers()
55
+ from pyocrust import available_providers
56
+
57
+ return available_providers()
pyocrust/hardware.py ADDED
@@ -0,0 +1,119 @@
1
+ """Hardware discovery using only stdlib; unknown memory stays None.
2
+
3
+ A detected GPU is physical inventory, not proof that the native wheel supports
4
+ CUDA. CUDA_VISIBLE_DEVICES filters inventory; it never fabricates a GPU.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import csv
9
+ import ctypes
10
+ from dataclasses import dataclass
11
+ import os
12
+ import shutil
13
+ import subprocess
14
+ import sys
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class GpuInfo:
19
+ name: str | None = None
20
+ vram_bytes: int | None = None
21
+
22
+ def __post_init__(self):
23
+ if self.vram_bytes is not None and (type(self.vram_bytes) is not int or self.vram_bytes <= 0):
24
+ raise ValueError("vram_bytes must be a positive integer or None")
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class HardwareProfile:
29
+ cpu_count: int
30
+ ram_bytes: int | None
31
+ gpu: GpuInfo | None = None
32
+
33
+ def __post_init__(self):
34
+ if type(self.cpu_count) is not int or self.cpu_count < 1:
35
+ raise ValueError("cpu_count must be a positive integer")
36
+ if self.ram_bytes is not None and (type(self.ram_bytes) is not int or self.ram_bytes <= 0):
37
+ raise ValueError("ram_bytes must be a positive integer or None")
38
+ if self.gpu is not None and not isinstance(self.gpu, GpuInfo):
39
+ raise TypeError("gpu must be GpuInfo or None")
40
+
41
+
42
+ def _ram_bytes() -> int | None:
43
+ try:
44
+ if sys.platform.startswith("win"):
45
+ from ctypes import wintypes
46
+
47
+ class MemoryStatus(ctypes.Structure):
48
+ _fields_ = [("length", wintypes.DWORD), ("load", wintypes.DWORD)] + [
49
+ (name, ctypes.c_ulonglong) for name in (
50
+ "total_phys", "avail_phys", "total_page_file", "avail_page_file",
51
+ "total_virtual", "avail_virtual", "avail_extended_virtual",
52
+ )
53
+ ]
54
+
55
+ status = MemoryStatus()
56
+ status.length = ctypes.sizeof(status)
57
+ if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(status)):
58
+ return int(status.total_phys) or None
59
+ elif sys.platform == "darwin":
60
+ result = subprocess.run(["sysctl", "-n", "hw.memsize"], capture_output=True, text=True, timeout=2, check=True)
61
+ total = int(result.stdout.strip())
62
+ return total if total > 0 else None
63
+ else:
64
+ pages, page_size = os.sysconf("SC_PHYS_PAGES"), os.sysconf("SC_PAGE_SIZE")
65
+ return int(pages * page_size) if pages > 0 and page_size > 0 else None
66
+ except (AttributeError, ValueError, OSError, subprocess.SubprocessError):
67
+ pass
68
+ return None
69
+
70
+
71
+ def _gpu() -> GpuInfo | None:
72
+ visible = os.environ.get("CUDA_VISIBLE_DEVICES")
73
+ if visible is not None and visible.strip() in ("", "-1"):
74
+ return None
75
+ executable = shutil.which("nvidia-smi")
76
+ if not executable:
77
+ return None
78
+ try:
79
+ result = subprocess.run(
80
+ [executable, "--query-gpu=index,uuid,name,memory.total", "--format=csv,noheader,nounits"],
81
+ capture_output=True, text=True, timeout=2, check=True,
82
+ )
83
+ rows = [row for row in csv.reader(result.stdout.splitlines(), skipinitialspace=True) if len(row) == 4]
84
+ if visible is not None:
85
+ selected = []
86
+ for device in visible.split(","):
87
+ device = device.strip()
88
+ if device.isascii() and device.isdigit():
89
+ matches = [row for row in rows if row[0].strip() == device]
90
+ elif device.startswith("GPU-") and len(device) > 4:
91
+ matches = [row for row in rows if row[1].strip().startswith(device)]
92
+ else:
93
+ break
94
+ # CUDA stops at an invalid/ambiguous or repeated identifier.
95
+ if len(matches) != 1 or matches[0] in selected:
96
+ break
97
+ selected.append(matches[0])
98
+ rows = selected
99
+ for row in rows:
100
+ if len(row) == 4:
101
+ try:
102
+ memory = int(row[3].strip()) * 1024**2
103
+ if memory <= 0:
104
+ memory = None
105
+ except ValueError:
106
+ memory = None
107
+ return GpuInfo(name=row[2].strip(), vram_bytes=memory)
108
+ except (ValueError, OSError, subprocess.SubprocessError):
109
+ pass
110
+ return None
111
+
112
+
113
+ def detect_hardware() -> HardwareProfile:
114
+ """Return host inventory without importing inference libraries or loading models.
115
+
116
+ Use HardwareProfile directly for overrides; resolve_pipeline never detects
117
+ hardware when an explicit profile is supplied.
118
+ """
119
+ return HardwareProfile(cpu_count=os.cpu_count() or 1, ram_bytes=_ram_bytes(), gpu=_gpu())
@@ -0,0 +1,143 @@
1
+ """Un único punto de entrada para una o varias features sobre la misma imagen.
2
+
3
+ ``pipeline_profiles()`` es la fuente de verdad de las features válidas: cinco
4
+ presets de documento (``pp_ocrv6_tiny|small|medium``, ``pp_structurev3``,
5
+ ``indra`` y, con la feature ``vl``, ``glm_ocr``) y once tareas independientes
6
+ (``text_detection``, ``layout_detection``, ``formula_recognition``, ...).
7
+
8
+ Cada feature **conserva su esquema**: un preset devuelve ``OcrResult`` /
9
+ ``StructureResult`` y una tarea el ``dict`` documentado de
10
+ ``TaskPredictor.predict``. Con **varias** features el resultado es un
11
+ ``dict[label, salida]`` (etiquetado por feature, sin aplanar); con **una sola**
12
+ es exactamente la salida de hoy, sin envolver.
13
+
14
+ La inferencia es nativa y libera el GIL (``py.detach``, el antiguo
15
+ ``py.allow_threads``), así que con ``parallel=True`` las features corren en
16
+ hilos y esos tramos se solapan de verdad. Por defecto es **secuencial**:
17
+ ADR-008 evita la sobre-suscripción de CPU entre sesiones ORT multihilo.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ from concurrent.futures import ThreadPoolExecutor
23
+ from os import PathLike
24
+ from typing import Any, Callable, Sequence
25
+
26
+ from ._pyocrust_core import (
27
+ PyOcrValueError,
28
+ TaskPredictor,
29
+ VeloceOCR,
30
+ pipeline_profiles,
31
+ )
32
+
33
+ #: Alias cortos (los nombres con los que se cita cada feature) -> id canónico
34
+ #: de ``pipeline_profiles()``. Solo se listan los que no son ambiguos.
35
+ FEATURE_ALIASES: dict[str, str] = {
36
+ "text": "text_recognition",
37
+ "layout": "layout_detection",
38
+ "table": "table_structure_recognition",
39
+ "formula": "formula_recognition",
40
+ "structure": "pp_structurev3",
41
+ "full_page": "pp_structurev3",
42
+ }
43
+
44
+ __all__ = ["FEATURE_ALIASES", "recognize"]
45
+
46
+
47
+ def _resolve(features: Sequence[str]) -> tuple[list[str], list[str]]:
48
+ """Etiquetas de la llamada y sus ids canónicos, sin cargar ningún modelo."""
49
+ if features is None or isinstance(features, (str, bytes)):
50
+ raise PyOcrValueError(
51
+ "features must be a sequence of feature names "
52
+ "(a single string is ambiguous; wrap it in a list)"
53
+ )
54
+ try:
55
+ labels = list(features)
56
+ except TypeError as exc:
57
+ raise PyOcrValueError(
58
+ f"features must be a sequence of feature names: {exc}"
59
+ ) from exc
60
+ if not labels:
61
+ raise PyOcrValueError("features must name at least one feature")
62
+ profiles = pipeline_profiles()
63
+ ids: list[str] = []
64
+ for label in labels:
65
+ if not isinstance(label, str):
66
+ raise PyOcrValueError(
67
+ f"feature name must be str, got {type(label).__name__}"
68
+ )
69
+ feature_id = FEATURE_ALIASES.get(label, label)
70
+ if feature_id not in profiles:
71
+ raise PyOcrValueError(
72
+ f"unknown feature '{label}'. Valid features: "
73
+ f"{', '.join(sorted(profiles))}. "
74
+ f"Aliases: {', '.join(sorted(FEATURE_ALIASES))}"
75
+ )
76
+ ids.append(feature_id)
77
+ repeated = sorted({i for i in ids if ids.count(i) > 1})
78
+ if repeated:
79
+ raise PyOcrValueError(f"duplicate feature(s): {', '.join(repeated)}")
80
+ return labels, ids
81
+
82
+
83
+ def _runner(
84
+ feature_id: str,
85
+ profile: dict,
86
+ *,
87
+ device: str,
88
+ custom_path: str | None,
89
+ license_commercial_use: bool,
90
+ license_acknowledge: bool,
91
+ ) -> Callable[[Any], Any]:
92
+ """Inferencia de una feature: ``predict`` (tarea) o ``recognize`` (preset)."""
93
+ license_kwargs = {
94
+ "license_commercial_use": license_commercial_use,
95
+ "license_acknowledge": license_acknowledge,
96
+ }
97
+ if profile["family"] == "task":
98
+ predictor = TaskPredictor(feature_id, device=device, **license_kwargs)
99
+ return predictor.predict
100
+ engine = VeloceOCR(
101
+ feature_id, custom_path=custom_path, device=device, **license_kwargs
102
+ )
103
+ return engine.recognize
104
+
105
+
106
+ def recognize(
107
+ image: str | bytes | PathLike[str],
108
+ features: Sequence[str],
109
+ *,
110
+ device: str = "cpu",
111
+ custom_path: str | None = None,
112
+ parallel: bool = False,
113
+ max_workers: int | None = None,
114
+ license_commercial_use: bool = True,
115
+ license_acknowledge: bool = False,
116
+ ) -> Any:
117
+ """Aplica una o varias features de ``pipeline_profiles()`` a la misma imagen.
118
+
119
+ Con una sola feature devuelve **exactamente** lo de hoy (``OcrResult`` /
120
+ ``StructureResult`` / el ``dict`` de la tarea), sin envolver; con varias,
121
+ ``{label: salida}`` con la etiqueta que pidió el llamante, en su orden.
122
+ """
123
+ labels, ids = _resolve(features)
124
+ profiles = pipeline_profiles()
125
+ runners = [
126
+ _runner(
127
+ feature_id,
128
+ profiles[feature_id],
129
+ device=device,
130
+ custom_path=custom_path,
131
+ license_commercial_use=license_commercial_use,
132
+ license_acknowledge=license_acknowledge,
133
+ )
134
+ for feature_id in ids
135
+ ]
136
+ if len(runners) == 1:
137
+ return runners[0](image)
138
+ if parallel:
139
+ with ThreadPoolExecutor(max_workers=max_workers or len(runners)) as pool:
140
+ outputs = list(pool.map(lambda runner: runner(image), runners))
141
+ else:
142
+ outputs = [runner(image) for runner in runners]
143
+ return dict(zip(labels, outputs))
pyocrust/py.typed ADDED
@@ -0,0 +1 @@
1
+ py.typed