dot-parser 2.0.0__py3-none-any.whl

dot_parser/backends/mistral.py

@@ -0,0 +1,622 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import inspect
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+from dot_parser.image_utils import (
+    dedupe_titles,
+    guess_mime_type,
+    parse_image_annotation,
+    strip_data_url_prefix,
+)
+from dot_parser.images import ExtractedImage, PageInfo, ParseResult
+from dot_parser.markdown_utils import strip_markdown_tables
+
+if TYPE_CHECKING:
+    from mistralai.client.models import BatchJob, OCRPageObject, ResponseFormat
+
+_BATCH_TERMINAL = {"SUCCESS", "FAILED", "TIMEOUT_EXCEEDED", "CANCELLED"}
+_BATCH_POLL_INTERVAL_S = 5
+
+_log = logging.getLogger(__name__)
+
+# JSON schema passed as `bbox_annotation_format` so each detected image
+# is annotated by Mistral OCR in the same call. Kept intentionally small:
+# a `title` slug for UI display and a free-form `description` for RAG —
+# a tight schema avoids burning tokens on speculative fields.
+_IMAGE_ANNOTATION_SCHEMA: dict = {
+    "type": "object",
+    "properties": {
+        "title": {
+            "type": "string",
+            "description": (
+                "Short kebab-case slug (3-8 words, lowercase, "
+                "hyphen-separated, no file extension) naming what the "
+                "image depicts, e.g. 'system-architecture-diagram' or "
+                "'monthly-revenue-bar-chart'."
+            ),
+        },
+        "description": {
+            "type": "string",
+            "description": (
+                "Concise description of the image content, including any "
+                "text visible in the image and the relationship to "
+                "surrounding document context."
+            ),
+        },
+    },
+    "required": ["title", "description"],
+    "additionalProperties": False,
+}
+
+
+def _annotation_schema(language: str | None) -> dict:
+    """Image-annotation JSON schema, optionally fixing the output language.
+
+    When ``language`` is set, the ``description`` field instruction is
+    extended to demand prose in that language while leaving verbatim
+    transcribed text in its original language. Returns a fresh dict so the
+    module-level ``_IMAGE_ANNOTATION_SCHEMA`` is never mutated.
+    """
+    if not language:
+        return _IMAGE_ANNOTATION_SCHEMA
+    schema = json.loads(json.dumps(_IMAGE_ANNOTATION_SCHEMA))
+    schema["properties"]["description"]["description"] += (
+        f" Write this description in {language}; keep any text "
+        "transcribed from the image in its original language."
+    )
+    return schema
+
+
+def _sdk_supports(param: str) -> bool:
+    """Whether the installed `mistralai` exposes `param` on `ocr.process`.
+
+    Block extraction (`include_blocks`) landed in mistralai 2.8; the
+    package floor here is `>=2.0`, so a client can legitimately be on a
+    release that predates it. Feature-detecting keeps that client working
+    — the corresponding enrichment is skipped rather than the call
+    failing — and avoids forcing a dependency bump on everyone.
+
+    Imported lazily and tolerant of any failure: an inspection problem
+    must degrade to "unsupported", never break parsing.
+    """
+    try:
+        from mistralai.client.ocr import Ocr
+
+        return param in inspect.signature(Ocr.process).parameters
+    except Exception:
+        return False
+
+
+def _caption_by_image_id(page: "OCRPageObject") -> dict[str, str]:
+    """Map ``image_id`` -> caption text, from a page's block list.
+
+    Requires ``include_blocks``; returns empty when blocks are absent
+    (older SDK, older OCR model, or the option switched off).
+
+    Blocks arrive in reading order, so a figure's caption is the nearest
+    `caption` block to its `image` block. We prefer the one immediately
+    after (captions typically sit below the figure) and fall back to the
+    one immediately before (some layouts put them above). Neighbours are
+    only considered when directly adjacent, so an unrelated caption
+    further down the page is never attached to the wrong image.
+    """
+    blocks = getattr(page, "blocks", None) or []
+    captions: dict[str, str] = {}
+    for i, block in enumerate(blocks):
+        if getattr(block, "type", None) != "image":
+            continue
+        image_id = getattr(block, "image_id", None)
+        if not image_id:
+            continue
+        for neighbour in (i + 1, i - 1):
+            if not 0 <= neighbour < len(blocks):
+                continue
+            candidate = blocks[neighbour]
+            if getattr(candidate, "type", None) == "caption":
+                text = (getattr(candidate, "content", "") or "").strip()
+                if text:
+                    captions[image_id] = text
+                    break
+    return captions
+
+
+def _page_info(page: "OCRPageObject") -> PageInfo:
+    """Collect the optional per-page extras OCR returned for one page.
+
+    Every field stays None when the matching option wasn't requested, so
+    this is safe to call unconditionally.
+    """
+    scores = getattr(page, "confidence_scores", None)
+    return PageInfo(
+        page=page.index + 1,
+        header=(getattr(page, "header", None) or None),
+        footer=(getattr(page, "footer", None) or None),
+        average_confidence=getattr(scores, "average_page_confidence_score", None),
+        minimum_confidence=getattr(scores, "minimum_page_confidence_score", None),
+    )
+
+
+def _build_bbox_annotation_format(language: str | None = None) -> "ResponseFormat":
+    """Build the Mistral `bbox_annotation_format` for per-image descriptions.
+
+    Imported lazily so the module remains importable without `mistralai`
+    installed; callers reach this only via `Mistral.parse_pdf_with_images`.
+    """
+    from mistralai.client.models import JSONSchema, ResponseFormat
+
+    return ResponseFormat(
+        type="json_schema",
+        json_schema=JSONSchema(
+            name="ImageAnnotation",
+            schema_definition=_annotation_schema(language),
+            strict=True,
+        ),
+    )
+
+
+class Mistral:
+    """Mistral OCR backend (cloud).
+
+    Calls the Mistral OCR API. Robust on image-only and broken-encoding PDFs,
+    preserves LaTeX equations and structured tables in Markdown.
+
+    Requires a Mistral API key. Reads ``MISTRAL_API_KEY`` from environment
+    by default, or accepts it as the ``api_key`` argument.
+
+    Single-PDF: ``parse_pdf(source)`` calls the sync OCR endpoint
+    (~$4/1k pages).
+
+    Multi-PDF: ``parse_pdfs(sources)`` uses the Batch API in a single
+    optimized job (50%% off, ~$2/1k pages). Blocks until the batch completes
+    (typically tens of seconds for small batches; can be longer under load).
+    Failed items are returned as ``None`` in input order.
+
+    Three optional enrichments are available on the ``*_with_images``
+    methods, all off by default so the returned markdown is unchanged
+    unless asked for:
+
+    ``extract_headers_footers``
+        Pull running page furniture out of the page markdown and into
+        ``ParseResult.pages[i].header`` / ``.footer``. Useful before
+        chunking for retrieval, where a repeated "page 4 of 27" is noise.
+        Note this *removes* that text from the markdown.
+
+    ``confidence_scores``
+        ``"page"`` or ``"word"``. Populates the confidence fields on
+        ``ParseResult.pages``. Thresholds need calibrating per corpus —
+        on the benchmark PDFs these scores did not separate clean
+        documents from degraded ones (see ``PageInfo``).
+
+    ``extract_captions``
+        Fill ``ExtractedImage.original_caption`` with the figure caption
+        printed next to each image. Requires OCR 4+ and ``mistralai>=2.8``;
+        on older SDKs it logs a warning and leaves captions None.
+
+    Install with::
+
+        pip install dot-parser[mistral]
+    """
+
+    # Class-level defaults so an instance built without ``__init__`` still
+    # behaves: ``Mistral.__new__(Mistral)`` (used to skip the API-key check)
+    # and instances unpickled from a version predating these options would
+    # otherwise raise AttributeError mid-parse.
+    _language: str | None = None
+    _extract_headers_footers: bool = False
+    _confidence_scores: "Literal['page', 'word'] | None" = None
+    _extract_captions: bool = False
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        model: str = "mistral-ocr-4-0",
+        language: str | None = None,
+        extract_headers_footers: bool = False,
+        confidence_scores: Literal["page", "word"] | None = None,
+        extract_captions: bool = False,
+    ) -> None:
+        try:
+            from mistralai.client import Mistral as _Mistral
+        except ImportError as e:
+            raise ImportError(
+                "Mistral backend requires `mistralai`. "
+                "Install with: pip install dot-parser[mistral]"
+            ) from e
+
+        key = api_key or os.environ.get("MISTRAL_API_KEY")
+        if not key:
+            raise ValueError(
+                "Mistral backend requires an API key. Set MISTRAL_API_KEY or pass api_key=..."
+            )
+        self._client = _Mistral(api_key=key)
+        self._model = model
+        # When set (e.g. "French"), per-image annotations are requested in
+        # this language via the bbox_annotation schema; None keeps Mistral's
+        # default (English-leaning) behaviour.
+        self._language = language
+        # The three options below all default to today's behaviour: each
+        # one adds a field to the OCR request, so leaving them off keeps
+        # the request — and therefore the response — byte-identical to
+        # what callers got before they existed.
+        self._extract_headers_footers = extract_headers_footers
+        self._confidence_scores = confidence_scores
+        # Captions need block extraction, which requires both OCR 4+ and
+        # mistralai>=2.8. Resolved once here so an old SDK degrades to
+        # "no captions" instead of erroring on every call.
+        self._extract_captions = extract_captions and _sdk_supports("include_blocks")
+        if extract_captions and not self._extract_captions:
+            _log.warning(
+                "extract_captions=True ignored: the installed `mistralai` has no "
+                "include_blocks support on ocr.process (needs >=2.8). Image "
+                "captions will stay None."
+            )
+
+    def parse_pdf(self, source: str | Path | bytes) -> str:
+        if isinstance(source, bytes):
+            content = source
+            file_name = "document.pdf"
+        else:
+            path = Path(source)
+            content = path.read_bytes()
+            file_name = path.name
+
+        uploaded = self._client.files.upload(
+            file={"file_name": file_name, "content": content},
+            purpose="ocr",
+        )
+        signed = self._client.files.get_signed_url(file_id=uploaded.id)
+        resp = self._client.ocr.process(
+            model=self._model,
+            document={"type": "document_url", "document_url": signed.url},
+        )
+        return "\n\n".join(p.markdown for p in resp.pages)
+
+    def parse_pdf_with_images(
+        self,
+        source: str | Path | bytes,
+        *,
+        annotate_images: bool = True,
+        include_tables: bool = True,
+    ) -> ParseResult:
+        """Parse a PDF and return markdown together with extracted images.
+
+        Each image is requested with `include_image_base64=True` and, when
+        `annotate_images` is True, with a structured `bbox_annotation_format`
+        so Mistral writes a short description per image in the same OCR call
+        (no separate VLM round-trip). If that annotated call fails the
+        method automatically retries once without the annotation schema,
+        salvaging the markdown + raw images (interpretations stay None).
+
+        The returned markdown preserves Mistral's native `![id](id)`
+        placeholders at image positions; `ExtractedImage.name` matches
+        the `id` in those placeholders so callers can correlate text and
+        image without re-parsing the markdown.
+
+        When ``include_tables`` is False, GFM-style tables are stripped
+        from the resulting markdown — Mistral OCR has no native flag to
+        suppress them, so this is a post-processing pass.
+        """
+        content, file_name = self._read_source(source, default_name="document.pdf")
+        return self._ocr_document_with_images(
+            content,
+            file_name,
+            annotate_images=annotate_images,
+            include_tables=include_tables,
+        )
+
+    def parse_docx_with_images(
+        self,
+        source: str | Path | bytes,
+        *,
+        annotate_images: bool = True,
+        include_tables: bool = True,
+    ) -> ParseResult:
+        """Parse a DOCX directly through Mistral OCR (no markitdown / VLM).
+
+        Mirrors :meth:`parse_pdf_with_images` — the OCR API accepts ``.docx``
+        natively via ``document_url`` (Mistral rasters the document to pages
+        before OCR). The returned shape is identical to the PDF path: markdown
+        with ``![id](id)`` placeholders at image positions, plus one
+        :class:`ExtractedImage` per detected image with optional per-image
+        annotation when ``annotate_images=True``.
+
+        Exists as an A/B alternative to
+        :func:`dot_parser.docx_images.parse_docx_with_images` (markitdown +
+        VLM). Both paths are selectable from :func:`parse_with_images` —
+        pass ``backend=Mistral()`` for this OCR path, or pass ``vlm=...`` for
+        the markitdown path.
+        """
+        content, file_name = self._read_source(source, default_name="document.docx")
+        return self._ocr_document_with_images(
+            content,
+            file_name,
+            annotate_images=annotate_images,
+            include_tables=include_tables,
+        )
+
+    def parse_pptx_with_images(
+        self,
+        source: str | Path | bytes,
+        *,
+        annotate_images: bool = True,
+        include_tables: bool = True,
+    ) -> ParseResult:
+        """Parse a PPTX directly through Mistral OCR (no markitdown / VLM).
+
+        Same pipeline as :meth:`parse_docx_with_images`. Because the OCR
+        API rasters the deck page by page, one OCR page = one slide:
+        ``ExtractedImage.page`` is the slide number, and the per-page
+        markdowns are joined with ``<!-- Slide number: N -->`` markers —
+        the same markers markitdown emits for PPTX — so slide-aware
+        chunkers see an identical surface on both paths.
+
+        Unlike the markitdown+VLM path, rasterising the slide means
+        diagrams *drawn* in PowerPoint (shapes, arrows, SmartArt) are
+        seen and annotated, not just embedded picture files.
+        """
+        content, file_name = self._read_source(source, default_name="document.pptx")
+        return self._ocr_document_with_images(
+            content,
+            file_name,
+            annotate_images=annotate_images,
+            include_tables=include_tables,
+            page_marker_template="<!-- Slide number: {n} -->",
+        )
+
+    @staticmethod
+    def _read_source(source: str | Path | bytes, *, default_name: str) -> tuple[bytes, str]:
+        if isinstance(source, bytes):
+            return source, default_name
+        path = Path(source)
+        return path.read_bytes(), path.name
+
+    def _ocr_document_with_images(
+        self,
+        content: bytes,
+        file_name: str,
+        *,
+        annotate_images: bool,
+        include_tables: bool,
+        page_marker_template: str | None = None,
+    ) -> ParseResult:
+        """Shared OCR-with-images pipeline for any document_url-accepting input.
+
+        Mistral OCR's behavior is the same whether the source is PDF, DOCX,
+        PPTX, etc.: it rasters the document to pages, then runs text + image
+        + (optional) annotation extraction. This helper centralises the
+        upload → process → assemble flow so the per-format entry points
+        differ only in default filename and, optionally, a
+        ``page_marker_template`` (containing ``{n}``) emitted before each
+        page's markdown — used by the PPTX path to mark slide boundaries.
+        """
+        uploaded = self._client.files.upload(
+            file={"file_name": file_name, "content": content},
+            purpose="ocr",
+        )
+        signed = self._client.files.get_signed_url(file_id=uploaded.id)
+
+        base_kwargs: dict = {
+            "model": self._model,
+            "document": {"type": "document_url", "document_url": signed.url},
+            "include_image_base64": True,
+        }
+
+        # Everything beyond markdown + raw images is opt-in and grouped
+        # here, because they share one failure policy: any of them can be
+        # rejected by an older OCR model, and none is worth losing the
+        # document over.
+        optional_kwargs: dict = {}
+        if annotate_images:
+            optional_kwargs["bbox_annotation_format"] = _build_bbox_annotation_format(
+                self._language
+            )
+        if self._extract_headers_footers:
+            optional_kwargs["extract_header"] = True
+            optional_kwargs["extract_footer"] = True
+        if self._confidence_scores:
+            optional_kwargs["confidence_scores_granularity"] = self._confidence_scores
+        if self._extract_captions:
+            optional_kwargs["include_blocks"] = True
+
+        if optional_kwargs:
+            try:
+                resp = self._client.ocr.process(**base_kwargs, **optional_kwargs)
+            except Exception as exc:
+                # Retry once with the extras dropped so one unsupported or
+                # flaky enrichment doesn't lose the whole document. The
+                # caller still gets markdown + raw images, minus the
+                # annotations / headers / confidence / captions.
+                _log.warning(
+                    "Mistral OCR failed with optional features %s (%s); retrying without them",
+                    sorted(optional_kwargs),
+                    exc,
+                )
+                resp = self._client.ocr.process(**base_kwargs)
+        else:
+            resp = self._client.ocr.process(**base_kwargs)
+
+        if page_marker_template is None:
+            markdown = "\n\n".join(p.markdown for p in resp.pages)
+        else:
+            markdown = "\n\n".join(
+                f"{page_marker_template.format(n=p.index + 1)}\n{p.markdown}" for p in resp.pages
+            )
+        if not include_tables:
+            markdown = strip_markdown_tables(markdown)
+
+        # Two-pass: gather raw fields, then dedupe titles document-wide so
+        # repeated diagrams ("workflow-diagram" twice) get -2/-3 suffixes.
+        raw_records: list[tuple[ExtractedImage, str | None]] = []
+        pages: list[PageInfo] = []
+        for page in resp.pages:
+            if self._extract_headers_footers or self._confidence_scores:
+                pages.append(_page_info(page))
+            captions = _caption_by_image_id(page) if self._extract_captions else {}
+            for img in page.images or []:
+                if not img.image_base64:
+                    continue
+                annotation = parse_image_annotation(img.image_annotation)
+                raw_records.append(
+                    (
+                        ExtractedImage(
+                            name=img.id,
+                            base64=strip_data_url_prefix(img.image_base64),
+                            mime_type=guess_mime_type(img.id),
+                            page=page.index + 1,
+                            original_caption=captions.get(img.id),
+                            interpretation=annotation.interpretation or None,
+                            title=None,
+                        ),
+                        annotation.title,
+                    )
+                )
+
+        final_titles = dedupe_titles([t for _, t in raw_records])
+        images: list[ExtractedImage] = []
+        for (record, _), title in zip(raw_records, final_titles, strict=True):
+            images.append(
+                ExtractedImage(
+                    name=record.name,
+                    base64=record.base64,
+                    mime_type=record.mime_type,
+                    page=record.page,
+                    original_caption=record.original_caption,
+                    interpretation=record.interpretation,
+                    title=title,
+                )
+            )
+        return ParseResult(markdown=markdown, images=images, pages=pages)
+
+    def _log_batch_error_file(self, job: "BatchJob") -> None:
+        """Log the batch job's ``error_file`` (Mistral's per-request failure
+        details), if it produced one. Best-effort: never raises into the caller,
+        and caps the dump so a large batch can't flood the logs."""
+        err_file = getattr(job, "error_file", None)
+        if not err_file:
+            return
+        try:
+            content = self._client.files.download(file_id=err_file).read().decode()
+        except Exception as exc:
+            _log.warning("could not download Mistral batch error_file %s: %s", err_file, exc)
+            return
+        for line in content.strip().splitlines()[:20]:
+            _log.error("Mistral batch error_file: %s", line)
+
+    def parse_pdfs(self, sources: list[str | Path | bytes]) -> list[str | None]:
+        """Parse multiple PDFs in a single Batch API job (50% off vs sync).
+
+        Returns markdowns in input order. Failed items are ``None``.
+        """
+        if not sources:
+            return []
+
+        # 1. Upload each PDF + get signed URL.
+        signed_urls: list[str] = []
+        for i, src in enumerate(sources):
+            if isinstance(src, bytes):
+                content = src
+                file_name = f"document_{i}.pdf"
+            else:
+                path = Path(src)
+                content = path.read_bytes()
+                file_name = path.name
+            uploaded = self._client.files.upload(
+                file={"file_name": file_name, "content": content},
+                purpose="ocr",
+            )
+            signed = self._client.files.get_signed_url(file_id=uploaded.id)
+            signed_urls.append(signed.url)
+
+        # 2. Build JSONL with one request per PDF, indexed by position.
+        lines = []
+        for i, url in enumerate(signed_urls):
+            lines.append(
+                json.dumps(
+                    {
+                        "custom_id": str(i),
+                        "body": {
+                            "model": self._model,
+                            "document": {"type": "document_url", "document_url": url},
+                        },
+                    }
+                )
+            )
+        jsonl_bytes = ("\n".join(lines) + "\n").encode()
+
+        # 3. Upload JSONL + create batch job.
+        batch_file = self._client.files.upload(
+            file={"file_name": "batch_ocr.jsonl", "content": jsonl_bytes},
+            purpose="batch",
+        )
+        job = self._client.batch.jobs.create(
+            endpoint="/v1/ocr",
+            input_files=[batch_file.id],
+            model=self._model,
+        )
+
+        # 4. Poll until terminal.
+        while job.status not in _BATCH_TERMINAL:
+            time.sleep(_BATCH_POLL_INTERVAL_S)
+            job = self._client.batch.jobs.get(job_id=job.id)
+
+        results: list[str | None] = [None] * len(sources)
+        # A job yields no usable output if it didn't succeed, or if it "succeeded"
+        # but has no output_file (every request errored — the details are then in
+        # the error_file). Guard the download: calling it with output_file=None
+        # raises a cryptic SDK ValidationError that hides the real reason.
+        output_file = getattr(job, "output_file", None)
+        if job.status != "SUCCESS" or not output_file:
+            _log.error(
+                "Mistral batch job %s ended in %s with no usable output "
+                "(output_file=%s); all %d PDF(s) failed. job.errors=%s",
+                job.id,
+                job.status,
+                output_file,
+                len(sources),
+                getattr(job, "errors", None),
+            )
+            self._log_batch_error_file(job)
+            return results
+
+        # 5. Download output JSONL + map back to input order via custom_id.
+        output_bytes = self._client.files.download(file_id=output_file).read()
+        for line in output_bytes.decode().strip().splitlines():
+            rec = json.loads(line)
+            try:
+                idx = int(rec["custom_id"])
+            except (KeyError, ValueError):
+                _log.warning("Mistral batch output line has no valid custom_id: %.200s", line)
+                continue
+            if not (0 <= idx < len(sources)):
+                continue
+            # A per-item OCR failure comes back as an error on the record rather
+            # than pages; surface it instead of silently leaving a None.
+            error = rec.get("error") or (rec.get("response") or {}).get("body", {}).get("error")
+            if error is not None:
+                _log.error("Mistral OCR failed for PDF #%d: %s", idx, error)
+                continue
+            try:
+                pages = rec["response"]["body"]["pages"]
+                results[idx] = "\n\n".join(p["markdown"] for p in pages)
+            except (KeyError, TypeError):
+                _log.error("Mistral OCR returned no pages for PDF #%d: %.300s", idx, line)
+
+        missing = [i for i, md in enumerate(results) if md is None]
+        if missing:
+            self._log_batch_error_file(job)
+            _log.warning(
+                "Mistral batch %s: %d/%d PDF(s) produced no markdown (indices %s)",
+                job.id,
+                len(missing),
+                len(sources),
+                missing,
+            )
+        return results

dot_parser/backends/pymu.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import tempfile
+from pathlib import Path
+from types import ModuleType
+
+
+class Pymu:
+    """Default backend: pymupdf4llm.
+
+    Fast, CPU-only, lightweight. Works on natively-text PDFs. Fails on
+    image-only PDFs and PDFs with broken ToUnicode CMaps unless an OCR
+    engine (tesseract, rapidocr or paddleocr) is available — pymupdf4llm
+    auto-detects and falls back to OCR for problematic pages.
+
+    Args:
+        ocr_fallback: when True (default), pymupdf4llm uses its built-in
+            OCR fallback if an engine is available. When False, force the
+            no-OCR code path (matches a runtime image without tesseract,
+            useful for reproducing production where OCR is not installed).
+    """
+
+    def __init__(self, *, ocr_fallback: bool = True) -> None:
+        self._ocr_fallback = ocr_fallback
+
+    def parse_pdf(self, source: str | Path | bytes) -> str:
+        import pymupdf4llm
+
+        if self._ocr_fallback:
+            return self._call(pymupdf4llm, source)
+
+        # Reproduce a runtime without an OCR engine available (le-lab
+        # production). pymupdf4llm gates OCR on the result of
+        # ``select_ocr_function()`` — when it returns None, ``document.use_ocr``
+        # is forced to ``OCRMode.NEVER`` and neither full-page nor text-only
+        # OCR is invoked.
+        from pymupdf4llm.helpers import document_layout as _dl
+
+        original = _dl.select_ocr_function
+        # Deliberate monkeypatch of a third-party module function; returning
+        # None is precisely the signal pymupdf4llm reads to disable OCR.
+        _dl.select_ocr_function = lambda: None  # ty: ignore[invalid-assignment]
+        try:
+            return self._call(pymupdf4llm, source)
+        finally:
+            _dl.select_ocr_function = original
+
+    @staticmethod
+    def _call(pymupdf4llm: ModuleType, source: str | Path | bytes) -> str:
+        if isinstance(source, bytes):
+            with tempfile.NamedTemporaryFile(suffix=".pdf", delete=True) as tmp:
+                tmp.write(source)
+                tmp.flush()
+                return pymupdf4llm.to_markdown(tmp.name)
+        return pymupdf4llm.to_markdown(str(source))