structx 0.6.4__tar.gz → 0.6.5__tar.gz

{structx-0.6.4/structx.egg-info → structx-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structx
-Version: 0.6.4
+Version: 0.6.5
 Summary: Structured data extraction from text using LLMs and dynamic model generation
 Author-email: blacksuan19 <py@aolabs.dev>
 Classifier: Development Status :: 5 - Production/Stable
@@ -70,7 +70,7 @@ Advanced structured data extraction from any document using LLMs with multimodal
 support.
 
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg?style=for-the-badge)](https://structx.aolabs.dev "Documentation")
-[![PyPI](https://img.shields.io/badge/PyPi-0.6.4-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.5-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
 [![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)](# "Build with GitHub Actions")
 
 See the [project roadmap](docs/ROADMAP.md) for planned portable business rules

{structx-0.6.4 → structx-0.6.5}/README.md

@@ -4,7 +4,7 @@ Advanced structured data extraction from any document using LLMs with multimodal
 support.
 
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg?style=for-the-badge)](https://structx.aolabs.dev "Documentation")
-[![PyPI](https://img.shields.io/badge/PyPi-0.6.4-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.5-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
 [![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)](# "Build with GitHub Actions")
 
 See the [project roadmap](docs/ROADMAP.md) for planned portable business rules

{structx-0.6.4 → structx-0.6.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "structx"
-version = "0.6.4"
+version = "0.6.5"
 description = "Structured data extraction from text using LLMs and dynamic model generation"
 authors = [{ name = "blacksuan19", email = "py@aolabs.dev" }]
 license-files = ["LICENSE"]
@@ -106,7 +106,7 @@ torchvision = [
 ]
 
 [tool.bumpver]
-current_version = "0.6.4"
+current_version = "0.6.5"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "chore(release): bump version {old_version} -> {new_version}"
 commit = true

{structx-0.6.4 → structx-0.6.5}/structx/__init__.py

@@ -22,7 +22,7 @@ from structx.schema import (
     model_to_extraction_request,
 )
 
-__version__ = "0.6.4"
+__version__ = "0.6.5"
 __all__ = [
     "Extractor",
     "ExtractionConfig",

{structx-0.6.4 → structx-0.6.5}/structx/measurement.py

@@ -21,6 +21,7 @@ Example:
 """
 
 import threading
+from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field
 from math import ceil, sqrt
 from pathlib import Path
@@ -118,6 +119,17 @@ class DocumentMeasurement:
         return tuple(codes)
 
 
+@dataclass
+class _PagePlan:
+    """Work-in-progress state for one page, used between rendering and OCR."""
+
+    page_number: int
+    native_text: str = ""
+    native_failed: bool = False
+    image: Any = None
+    measurement: Optional[PageMeasurement] = None
+
+
 def _positive_int(value: Any, name: str) -> int:
     """Validate a positive integer setting."""
     if isinstance(value, bool) or not isinstance(value, int) or value < 1:
@@ -167,6 +179,11 @@ class DocumentMeasurer:
         render_dpi: Resolution used when rendering a page for OCR.
         max_render_pixels: Upper bound on rendered pixels per page. Larger
             pages are rendered at a reduced scale rather than skipped.
+        ocr_workers: Pages recognized at once. The default of 1 keeps OCR
+            serial. Higher values give each worker thread its own engine and
+            bound how many page images are held in memory at once.
+        ocr_engine_params: Parameters for the built-in OCR engine. Ignored when
+            ``ocr_reader`` is supplied.
     """
 
     def __init__(
@@ -174,6 +191,8 @@ class DocumentMeasurer:
         *,
         ocr_mode: str = "never",
         ocr_reader: Optional[Callable[[Any], str]] = None,
+        ocr_workers: int = 1,
+        ocr_engine_params: Optional[dict] = None,
         max_pages: int = MEASUREMENT_PAGE_LIMIT,
         max_input_bytes: int = MEASUREMENT_BYTES_LIMIT,
         render_dpi: float = MEASUREMENT_RENDER_DPI,
@@ -183,17 +202,27 @@ class DocumentMeasurer:
             raise ConfigurationError(f"ocr_mode must be one of {', '.join(OCR_MODES)}")
         if ocr_reader is not None and not callable(ocr_reader):
             raise ConfigurationError("ocr_reader must be callable")
+        if ocr_engine_params is not None and not isinstance(ocr_engine_params, dict):
+            raise ConfigurationError("ocr_engine_params must be a dict")
 
         self.ocr_mode = ocr_mode
+        self.ocr_workers = _positive_int(ocr_workers, "ocr_workers")
+        self.ocr_engine_params = dict(ocr_engine_params or {})
         self.max_pages = _positive_int(max_pages, "max_pages")
         self.max_input_bytes = _positive_int(max_input_bytes, "max_input_bytes")
         self.render_dpi = _positive_real(render_dpi, "render_dpi")
         self.max_render_pixels = _positive_int(max_render_pixels, "max_render_pixels")
         self._ocr_reader = ocr_reader
+        self._ocr_pool: Optional[ThreadPoolExecutor] = None
+        self._reader_lock = threading.Lock()
 
     def measure(self, file_path: Union[str, Path]) -> DocumentMeasurement:
         """Measure one PDF document.
 
+        PDF reading and rendering are serialized because the PDF backend is not
+        thread-safe. OCR runs outside that lock, so a slow scanned document does
+        not block other documents measured at the same time.
+
         Args:
             file_path: Path to an existing PDF file.
 
@@ -207,8 +236,7 @@ class DocumentMeasurer:
         """
         path = self._validated_path(file_path)
         pdfium = _import_pdfium()
-        with _PDFIUM_LOCK:
-            pages = self._measure_pages(pdfium, path)
+        pages = self._measure_pages(pdfium, path)
         return DocumentMeasurement(
             pages=tuple(pages),
             ocr_mode=self.ocr_mode,
@@ -243,108 +271,178 @@ class DocumentMeasurer:
         return path
 
     def _measure_pages(self, pdfium: Any, path: Path) -> list:
-        """Open the document once and measure every page in order."""
-        try:
-            document = pdfium.PdfDocument(path)
-        except Exception as error:
-            raise FileError(f"Could not open PDF for measurement: {path}") from error
-
-        try:
-            if _is_encrypted(pdfium, document):
-                raise FileError(f"Encrypted PDFs cannot be measured: {path}")
-
-            page_count = len(document)
-            if page_count < 1:
-                raise FileError(f"The PDF contains no pages: {path}")
-            if page_count > self.max_pages:
+        """Measure every page in order, in batches bounded by the worker count."""
+        with _PDFIUM_LOCK:
+            try:
+                document = pdfium.PdfDocument(path)
+            except Exception as error:
                 raise FileError(
-                    f"PDF exceeds the {self.max_pages} page measurement limit: {path}"
-                )
-            return [self._measure_page(document, index) for index in range(page_count)]
+                    f"Could not open PDF for measurement: {path}"
+                ) from error
+            try:
+                if _is_encrypted(pdfium, document):
+                    raise FileError(f"Encrypted PDFs cannot be measured: {path}")
+                page_count = len(document)
+                if page_count < 1:
+                    raise FileError(f"The PDF contains no pages: {path}")
+                if page_count > self.max_pages:
+                    raise FileError(
+                        f"PDF exceeds the {self.max_pages} page measurement "
+                        f"limit: {path}"
+                    )
+            except FileError:
+                document.close()
+                raise
+
+        measurements: list = []
+        try:
+            # Only the pages of one batch are rendered at a time, so a long
+            # document does not hold every page image in memory at once.
+            for start in range(0, page_count, self.ocr_workers):
+                end = min(start + self.ocr_workers, page_count)
+                with _PDFIUM_LOCK:
+                    plans = [self._prepare_page(document, i) for i in range(start, end)]
+                measurements.extend(self._recognize_batch(plans))
         finally:
-            document.close()
+            with _PDFIUM_LOCK:
+                document.close()
+        return measurements
+
+    def _prepare_page(self, document: Any, index: int) -> _PagePlan:
+        """Read a page's text layer and render it only when OCR is needed.
 
-    def _measure_page(self, document: Any, index: int) -> PageMeasurement:
-        """Measure one page without letting a page failure end the document."""
+        This runs under the PDF lock. Recognition itself happens afterwards.
+        """
         page_number = index + 1
         try:
             page = document[index]
         except Exception:
-            return PageMeasurement(
-                page_number, 0, "none", "partial", "page_load_failed"
+            return _PagePlan(
+                page_number,
+                measurement=PageMeasurement(
+                    page_number, 0, "none", "partial", "page_load_failed"
+                ),
             )
 
         try:
             native_text, native_failed = _native_text(page)
+            plan = _PagePlan(
+                page_number, native_text=native_text, native_failed=native_failed
+            )
 
-            if self.ocr_mode == "always":
-                return self._ocr_page(page, page_number, native_text, native_failed)
-
-            if native_failed:
-                if self.ocr_mode == "auto":
-                    return self._ocr_page(page, page_number, "", True)
-                return PageMeasurement(
-                    page_number, 0, "none", "partial", "native_text_failed"
-                )
-
-            if native_text.strip():
-                return PageMeasurement(
+            if self.ocr_mode == "never":
+                plan.measurement = self._without_ocr(plan)
+                return plan
+            if self.ocr_mode == "auto" and not native_failed and native_text.strip():
+                plan.measurement = PageMeasurement(
                     page_number, len(native_text), "native", "complete"
                 )
-
-            if self.ocr_mode == "auto":
-                return self._ocr_page(page, page_number, "", False)
-
-            # Without OCR, an empty text layer cannot be distinguished from a
-            # scanned page, so the page is reported as incomplete.
-            return PageMeasurement(page_number, 0, "none", "partial", "ocr_skipped")
+                return plan
+            if self.ocr_mode == "auto" and native_failed:
+                # A failed text layer says nothing about the page, so the
+                # native text is not reused as a fallback count.
+                plan.native_text = ""
+
+            try:
+                plan.image = self._rendered_image(page)
+            except Exception:
+                plan.measurement = self._ocr_unavailable(plan, "page_render_failed")
+            return plan
         finally:
             page.close()
 
-    def _ocr_page(
-        self,
-        page: Any,
-        page_number: int,
-        native_text: str,
-        native_failed: bool,
-    ) -> PageMeasurement:
-        """Measure a page with OCR, falling back to any usable native count."""
-        text, error_code = self._recognized_text(page)
-        if error_code is None:
-            return PageMeasurement(page_number, len(text), "ocr", "complete")
-        if not native_failed and native_text.strip():
+    def _without_ocr(self, plan: _PagePlan) -> PageMeasurement:
+        """Resolve a page that will not be sent to OCR."""
+        if plan.native_failed:
             return PageMeasurement(
-                page_number, len(native_text), "native", "partial", error_code
+                plan.page_number, 0, "none", "partial", "native_text_failed"
             )
-        return PageMeasurement(page_number, 0, "none", "partial", error_code)
-
-    def _recognized_text(self, page: Any) -> Tuple[str, Optional[str]]:
-        """Render one page and recognize its text, reporting bounded failures."""
+        if plan.native_text.strip():
+            return PageMeasurement(
+                plan.page_number, len(plan.native_text), "native", "complete"
+            )
+        # Without OCR, an empty text layer cannot be distinguished from a
+        # scanned page, so the page is reported as incomplete.
+        return PageMeasurement(plan.page_number, 0, "none", "partial", "ocr_skipped")
+
+    def _recognize_batch(self, plans: list) -> list:
+        """Recognize the rendered pages of one batch, in page order."""
+        pending = [plan for plan in plans if plan.measurement is None]
+        if pending:
+            if len(pending) > 1 and self.ocr_workers > 1:
+                # Created before fan-out so workers share one reader object.
+                self._resolve_reader()
+                results = list(self._pool().map(self._recognized_text, pending))
+            else:
+                results = [self._recognized_text(plan) for plan in pending]
+            for plan, (text, error_code) in zip(pending, results):
+                plan.measurement = self._from_recognition(plan, text, error_code)
+        return [plan.measurement for plan in plans]
+
+    def _recognized_text(self, plan: _PagePlan) -> Tuple[str, Optional[str]]:
+        """Recognize one rendered page, reporting bounded failures."""
         reader = self._resolve_reader()
-        if reader is None:
-            return "", "ocr_unavailable"
-
         try:
-            image = self._rendered_image(page)
-        except Exception:
-            return "", "page_render_failed"
-
-        try:
-            text = reader(image)
+            text = reader(plan.image)
         except OcrEngineUnavailableError:
             return "", "ocr_unavailable"
         except Exception:
             return "", "ocr_failed"
+        finally:
+            plan.image = None
 
         if not isinstance(text, str):
             return "", "ocr_failed"
         return _normalized(text), None
 
-    def _resolve_reader(self) -> Optional[Callable[[Any], str]]:
+    def _from_recognition(
+        self, plan: _PagePlan, text: str, error_code: Optional[str]
+    ) -> PageMeasurement:
+        """Build a page result, falling back to any usable native count."""
+        if error_code is None:
+            return PageMeasurement(plan.page_number, len(text), "ocr", "complete")
+        return self._ocr_unavailable(plan, error_code)
+
+    def _ocr_unavailable(self, plan: _PagePlan, error_code: str) -> PageMeasurement:
+        """Report a page OCR could not measure, keeping a usable native count."""
+        if not plan.native_failed and plan.native_text.strip():
+            return PageMeasurement(
+                plan.page_number,
+                len(plan.native_text),
+                "native",
+                "partial",
+                error_code,
+            )
+        return PageMeasurement(plan.page_number, 0, "none", "partial", error_code)
+
+    def _resolve_reader(self) -> Callable[[Any], str]:
         """Return the configured reader, creating the built-in one on demand."""
-        if self._ocr_reader is None:
-            self._ocr_reader = create_default_ocr_reader()
-        return self._ocr_reader
+        with self._reader_lock:
+            if self._ocr_reader is None:
+                self._ocr_reader = create_default_ocr_reader(
+                    workers=self.ocr_workers, **self.ocr_engine_params
+                )
+            return self._ocr_reader
+
+    def _pool(self) -> ThreadPoolExecutor:
+        """Return this measurer's OCR worker pool, creating it on demand."""
+        with self._reader_lock:
+            if self._ocr_pool is None:
+                self._ocr_pool = ThreadPoolExecutor(
+                    max_workers=self.ocr_workers,
+                    thread_name_prefix="structx-measure-ocr",
+                )
+            return self._ocr_pool
+
+    def close(self) -> None:
+        """Release worker threads held for parallel OCR.
+
+        Measuring again after closing recreates them.
+        """
+        with self._reader_lock:
+            pool, self._ocr_pool = self._ocr_pool, None
+        if pool is not None:
+            pool.shutdown(wait=True)
 
     def _rendered_image(self, page: Any) -> Any:
         """Render a page to pixels within the configured pixel budget."""

{structx-0.6.4 → structx-0.6.5}/structx/utils/measurement_ocr.py

@@ -17,6 +17,18 @@ class OcrEngineUnavailableError(StructXError):
     pass
 
 
+PARALLEL_ENGINE_PARAMS: Dict[str, Any] = {
+    "params": {"EngineConfig.onnxruntime.intra_op_num_threads": 1}
+}
+"""Engine parameters used when several reader threads run at once.
+
+ONNX Runtime already spreads a single recognition call across CPU cores, so
+parallel workers only help when each engine is limited to one inference thread.
+This applies to the built-in onnxruntime engine; pass explicit engine parameters
+for other backends.
+"""
+
+
 def _joined_text(result: Any) -> str:
     """Join recognized text lines from a RapidOCR result."""
     lines = getattr(result, "txts", None)
@@ -80,13 +92,47 @@ class RapidOcrReader:
             return _joined_text(engine(image))
 
 
-def create_default_ocr_reader(**engine_params: Any) -> Callable[[Any], str]:
+class ThreadLocalRapidOcrReader:
+    """Reader that gives every worker thread its own OCR engine.
+
+    ``RapidOCR`` updates instance state on each call, so one engine cannot be
+    shared across threads. This reader creates an engine per thread instead,
+    which is what makes page-level parallel OCR safe.
+
+    Attributes:
+        engine_params: Parameters forwarded to ``RapidOCR`` on creation.
+    """
+
+    def __init__(self, **engine_params: Any) -> None:
+        self.engine_params: Dict[str, Any] = dict(engine_params)
+        self._local = threading.local()
+
+    def __call__(self, image: Any) -> str:
+        """Recognize text using this thread's engine, creating it on demand."""
+        reader = getattr(self._local, "reader", None)
+        if reader is None:
+            reader = RapidOcrReader(**self.engine_params)
+            self._local.reader = reader
+        return reader(image)
+
+
+def create_default_ocr_reader(
+    *, workers: int = 1, **engine_params: Any
+) -> Callable[[Any], str]:
     """Create the built-in RapidOCR reader without initializing the engine.
 
     Args:
+        workers: Number of threads that may call the reader at once. Values
+            above one create one engine per thread and, unless the caller
+            overrides engine parameters, limit each engine to a single
+            inference thread so workers do not oversubscribe the CPU.
         **engine_params: Optional parameters forwarded to ``RapidOCR``.
 
     Returns:
         A callable that accepts rendered page pixels and returns text.
     """
-    return RapidOcrReader(**engine_params)
+    if workers <= 1:
+        return RapidOcrReader(**engine_params)
+    if not engine_params:
+        engine_params = dict(PARALLEL_ENGINE_PARAMS)
+    return ThreadLocalRapidOcrReader(**engine_params)

{structx-0.6.4 → structx-0.6.5/structx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structx
-Version: 0.6.4
+Version: 0.6.5
 Summary: Structured data extraction from text using LLMs and dynamic model generation
 Author-email: blacksuan19 <py@aolabs.dev>
 Classifier: Development Status :: 5 - Production/Stable
@@ -70,7 +70,7 @@ Advanced structured data extraction from any document using LLMs with multimodal
 support.
 
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg?style=for-the-badge)](https://structx.aolabs.dev "Documentation")
-[![PyPI](https://img.shields.io/badge/PyPi-0.6.4-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.5-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
 [![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)](# "Build with GitHub Actions")
 
 See the [project roadmap](docs/ROADMAP.md) for planned portable business rules

{structx-0.6.4 → structx-0.6.5}/tests/test_measurement.py

@@ -1,4 +1,5 @@
 import sys
+import threading
 import types
 from pathlib import Path
 
@@ -7,8 +8,10 @@ import pytest
 from structx.core.exceptions import ConfigurationError, FileError
 from structx.measurement import DocumentMeasurer, DocumentMeasurement
 from structx.utils.measurement_ocr import (
+    PARALLEL_ENGINE_PARAMS,
     OcrEngineUnavailableError,
     RapidOcrReader,
+    ThreadLocalRapidOcrReader,
     create_default_ocr_reader,
 )
 
@@ -266,6 +269,9 @@ def test_extraction_input_preparation_is_unaffected_by_measurement(native_pdf):
         lambda: DocumentMeasurer(ocr_mode="sometimes"),
         lambda: DocumentMeasurer(ocr_reader="not callable"),
         lambda: DocumentMeasurer(max_pages=0),
+        lambda: DocumentMeasurer(ocr_workers=0),
+        lambda: DocumentMeasurer(ocr_workers=True),
+        lambda: DocumentMeasurer(ocr_engine_params="params"),
         lambda: DocumentMeasurer(max_pages=True),
         lambda: DocumentMeasurer(max_input_bytes=-1),
         lambda: DocumentMeasurer(render_dpi=0),
@@ -427,6 +433,138 @@ def _import_failing_on(missing_name):
     return guarded_import
 
 
+def test_parallel_workers_recognize_pages_concurrently_and_in_order(tmp_path):
+    scanned = build_pdf(tmp_path / "scan.pdf", [None] * 4)
+    barrier = threading.Barrier(2, timeout=10)
+    worker_threads = set()
+
+    def reader(image):
+        worker_threads.add(threading.current_thread().name)
+        barrier.wait()
+        return "page text"
+
+    measurer = DocumentMeasurer(ocr_mode="auto", ocr_reader=reader, ocr_workers=2)
+    try:
+        measurement = measurer.measure(scanned)
+    finally:
+        measurer.close()
+
+    assert [page.page_number for page in measurement.pages] == [1, 2, 3, 4]
+    assert all(page.method == "ocr" for page in measurement.pages)
+    assert measurement.character_count == 4 * len("page text")
+    assert len(worker_threads) >= 2
+
+
+def test_only_one_batch_of_pages_is_rendered_at_a_time(tmp_path):
+    scanned = build_pdf(tmp_path / "scan.pdf", [None] * 6)
+    in_flight = 0
+    peak = 0
+    guard = threading.Lock()
+    ready = threading.Barrier(2, timeout=10)
+
+    def reader(image):
+        nonlocal in_flight, peak
+        with guard:
+            in_flight += 1
+            peak = max(peak, in_flight)
+        ready.wait()
+        with guard:
+            in_flight -= 1
+        return "text"
+
+    measurer = DocumentMeasurer(ocr_mode="auto", ocr_reader=reader, ocr_workers=2)
+    try:
+        measurement = measurer.measure(scanned)
+    finally:
+        measurer.close()
+
+    assert measurement.page_count == 6
+    assert peak <= 2
+
+
+def test_ocr_does_not_hold_the_pdf_lock(tmp_path, native_pdf):
+    scanned = build_pdf(tmp_path / "scan.pdf", [None])
+    recognizing = threading.Event()
+    release = threading.Event()
+
+    def blocking_reader(image):
+        recognizing.set()
+        assert release.wait(10)
+        return "slow page"
+
+    slow = DocumentMeasurer(ocr_mode="auto", ocr_reader=blocking_reader)
+    worker = threading.Thread(target=slow.measure, args=(scanned,))
+    worker.start()
+    try:
+        assert recognizing.wait(10)
+        # Another document must still be measurable while OCR is running.
+        quick = DocumentMeasurer().measure(native_pdf)
+        assert quick.status == "complete"
+    finally:
+        release.set()
+        worker.join(10)
+    assert not worker.is_alive()
+
+
+def test_serial_measurement_does_not_create_worker_threads(blank_pdf):
+    measurer = DocumentMeasurer(ocr_mode="auto", ocr_reader=RecordingReader())
+    measurer.measure(blank_pdf)
+
+    assert measurer._ocr_pool is None
+
+
+def test_measuring_again_after_close_still_works(tmp_path):
+    scanned = build_pdf(tmp_path / "scan.pdf", [None, None])
+    measurer = DocumentMeasurer(
+        ocr_mode="auto", ocr_reader=RecordingReader(), ocr_workers=2
+    )
+    try:
+        first = measurer.measure(scanned)
+        measurer.close()
+        second = measurer.measure(scanned)
+    finally:
+        measurer.close()
+
+    assert first == second
+    assert first.status == "complete"
+
+
+def test_parallel_default_reader_uses_one_engine_per_thread(monkeypatch):
+    calls = install_fake_rapidocr(monkeypatch)
+    reader = create_default_ocr_reader(workers=2)
+    assert isinstance(reader, ThreadLocalRapidOcrReader)
+    assert reader.engine_params == PARALLEL_ENGINE_PARAMS
+
+    results = []
+    threads = [
+        threading.Thread(target=lambda: results.append(reader("image")))
+        for _ in range(2)
+    ]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join(10)
+
+    assert results == ["first line\nsecond line"] * 2
+    assert calls["init"] == 2
+    assert calls["kwargs"] == PARALLEL_ENGINE_PARAMS
+
+
+def test_serial_default_reader_keeps_engine_defaults(monkeypatch):
+    install_fake_rapidocr(monkeypatch)
+    reader = create_default_ocr_reader(workers=1)
+
+    assert isinstance(reader, RapidOcrReader)
+    assert reader.engine_params == {}
+
+
+def test_explicit_engine_parameters_survive_parallel_readers(monkeypatch):
+    calls = install_fake_rapidocr(monkeypatch)
+    create_default_ocr_reader(workers=4, params={"Rec.model_type": "tiny"})("image")
+
+    assert calls["kwargs"] == {"params": {"Rec.model_type": "tiny"}}
+
+
 @pytest.mark.integration
 def test_real_ocr_measures_a_rasterized_page(tmp_path, native_pdf):
     scanned = tmp_path / "scanned.pdf"