dot-parser 2.0.0__py3-none-any.whl

dot_parser/image_utils.py

@@ -0,0 +1,152 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Shared helpers for image-aware parsing.
+
+Lives outside `backends/` because both the PDF (Mistral OCR) and the
+DOCX (markitdown + VLM) paths need the same primitives:
+
+- Title normalisation into a safe kebab-case slug (``clean_slug``).
+- Cross-document title disambiguation (``dedupe_titles``) — two images
+  with the same model-supplied title get ``-2``, ``-3`` suffixes.
+- MIME type / data-URL helpers for parsing Mistral OCR's image payloads
+  (``guess_mime_type``, ``strip_data_url_prefix``).
+- A single robust parser for ``{title, description}`` JSON annotations
+  (``parse_image_annotation``) — used both for Mistral OCR's
+  ``image_annotation`` field and for the chat-vision response in
+  :class:`dot_parser.vlms.MistralVLM`.
+
+Keeping these here avoids three near-identical copies drifting in
+``backends/mistral.py``, ``vlms.py``, and ``docx_images.py``.
+"""
+
+import json
+import re
+
+from dot_parser.images import ImageDescription
+
+_SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+){0,15}$")
+
+
+def clean_slug(value: object) -> str | None:
+    """Normalise a model-supplied title into a safe kebab-case slug.
+
+    Accepts the title even if it includes spaces, underscores, title-case
+    or trailing punctuation: lowercases and collapses any run of
+    non-alphanumerics into a single hyphen. Returns None when the result
+    is empty or would exceed the kebab-case length cap — better no title
+    than an unwieldy filename-like string in the UI.
+    """
+    if not isinstance(value, str):
+        return None
+    candidate = value.strip().lower()
+    if not candidate:
+        return None
+    candidate = re.sub(r"[^a-z0-9]+", "-", candidate).strip("-")
+    if not candidate or not _SLUG_RE.match(candidate):
+        return None
+    return candidate
+
+
+def dedupe_titles(titles: list[str | None]) -> list[str | None]:
+    """Append ``-2``, ``-3``, ... to repeated titles, preserving Nones.
+
+    Two images that the model labelled ``workflow-diagram`` come back as
+    ``workflow-diagram`` and ``workflow-diagram-2`` so the title remains
+    safe to use as a display label or filename.
+    """
+    seen: dict[str, int] = {}
+    out: list[str | None] = []
+    for t in titles:
+        if t is None:
+            out.append(None)
+            continue
+        seen[t] = seen.get(t, 0) + 1
+        out.append(t if seen[t] == 1 else f"{t}-{seen[t]}")
+    return out
+
+
+def guess_mime_type(image_id: str) -> str:
+    """Infer MIME type from a Mistral OCR image id like ``img-0.jpeg``.
+
+    Mistral encodes the format in the id's extension. Defaults to
+    ``image/png`` when the extension is missing or unrecognised.
+    """
+    ext = image_id.rsplit(".", 1)[-1].lower() if "." in image_id else ""
+    if ext in ("jpg", "jpeg"):
+        return "image/jpeg"
+    if ext == "webp":
+        return "image/webp"
+    if ext == "gif":
+        return "image/gif"
+    return "image/png"
+
+
+def strip_data_url_prefix(b64: str) -> str:
+    """Strip an optional ``data:image/...;base64,`` prefix.
+
+    Mistral OCR sometimes returns the image as a full data URL rather
+    than bare base64. Callers always want the raw payload.
+    """
+    if b64.startswith("data:") and "," in b64:
+        return b64.split(",", 1)[1]
+    return b64
+
+
+def parse_image_annotation(raw: str | None) -> ImageDescription:
+    """Parse a ``{title, description}`` JSON annotation into a record.
+
+    Used for two distinct input flavours:
+
+    - Mistral OCR's ``OCRImageObject.image_annotation`` field, which is
+      strict JSON when ``bbox_annotation_format`` is set.
+    - The content of a chat-vision response with a JSON schema
+      ``response_format`` — generally strict JSON, but the model
+      occasionally emits ``"description":`` followed by unescaped
+      multi-line text that breaks ``json.loads``.
+
+    Tries strict ``json.loads`` first; on failure, falls back to regex
+    extraction so a usable title is still surfaced. Non-JSON input is
+    returned as ``interpretation=raw, title=None`` (legacy passthrough).
+    Empty / None input yields an empty :class:`ImageDescription`.
+    """
+    if not raw:
+        return ImageDescription(interpretation="", title=None)
+
+    fenced = re.match(r"^```(?:json)?\s*(.*?)\s*```$", raw, flags=re.DOTALL)
+    candidate = fenced.group(1) if fenced else raw
+
+    start = candidate.find("{")
+    end = candidate.rfind("}")
+    if start != -1 and end > start:
+        snippet = candidate[start : end + 1]
+        try:
+            parsed = json.loads(snippet)
+        except (json.JSONDecodeError, ValueError):
+            parsed = None
+        if isinstance(parsed, dict):
+            desc_raw = parsed.get("description") or parsed.get("interpretation")
+            description = desc_raw.strip() if isinstance(desc_raw, str) else ""
+            title = clean_slug(parsed.get("title"))
+            # Surface any structured signal we got. When only a title
+            # comes back, interpretation is "" so callers can `or None`
+            # coerce uniformly without leaking the raw JSON blob.
+            if description or title:
+                return ImageDescription(interpretation=description, title=title)
+
+        # JSON looked promising but didn't yield usable fields — recover
+        # via regex. Title is always a short single-line string;
+        # description is whatever sits between ``"description":`` and
+        # the closing brace.
+        title_match = re.search(r'"title"\s*:\s*"([^"\n]*)"', snippet)
+        desc_match = re.search(
+            r'"description"\s*:\s*"?(.*?)"?\s*\}\s*$',
+            snippet,
+            flags=re.DOTALL,
+        )
+        recovered_title = clean_slug(title_match.group(1)) if title_match else None
+        recovered_desc = desc_match.group(1).strip() if desc_match else ""
+        if recovered_title or recovered_desc:
+            return ImageDescription(interpretation=recovered_desc, title=recovered_title)
+
+    return ImageDescription(interpretation=raw, title=None)

dot_parser/images.py

@@ -0,0 +1,125 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Public types for image-aware parsing.
+
+`parse_with_images()` returns a `ParseResult` that pairs the markdown text
+(with `![name](name)` anchors at each image position) with a list of
+`ExtractedImage` records carrying the image bytes and, when available,
+a textual interpretation.
+
+The `VLM` protocol lets callers inject a vision-language model for the
+DOCX path; the PDF path uses Mistral OCR's native per-image annotations
+instead, so no VLM is required there.
+"""
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class ExtractedImage:
+    """A single image extracted from a document.
+
+    `name` matches the `![name](name)` placeholder embedded at the
+    image's position inside the markdown returned alongside it; it
+    is a stable technical identifier (e.g. `img-003.png`).
+
+    `title` is a short human-readable label describing what the image
+    *depicts* (e.g. `gear-assembly-exploded-view`) — produced by the
+    VLM in the same call as `interpretation`. Use it for display and
+    `name` for cross-referencing with anchors / chunks.
+
+    `unsupported_reason` is populated when the extraction pipeline
+    deliberately did not call a VLM on this image because its
+    `mime_type` is outside the supported allowlist (e.g. EMF, WMF,
+    SVG, TIFF). The string carries a human-readable explanation of
+    the format and a hint at what external tool could recover it.
+    When set, `interpretation` and `title` will both be None; the
+    raw `base64` bytes are still populated so consumers can offer a
+    download or run their own conversion.
+    """
+
+    name: str
+    base64: str
+    mime_type: str
+    page: int | None = None
+    original_caption: str | None = None
+    interpretation: str | None = None
+    title: str | None = None
+    unsupported_reason: str | None = None
+
+
+@dataclass(frozen=True)
+class ImageDescription:
+    """Structured VLM response for a single image.
+
+    `title` is a short kebab-case label (4–8 words max) describing
+    what the image depicts. `interpretation` is the long-form
+    RAG-oriented description. `title` may be None when the VLM
+    cannot produce one (e.g. failure to parse a structured response).
+    """
+
+    interpretation: str
+    title: str | None = None
+
+
+@dataclass(frozen=True)
+class PageInfo:
+    """Per-page metadata a backend can report alongside the markdown.
+
+    Populated only when the caller opts in — see the ``Mistral``
+    backend's ``extract_headers_footers`` and ``confidence_scores``
+    options. Fields left None mean "not requested" rather than "not
+    present in the document", so an empty ``ParseResult.pages`` is the
+    default and carries no information either way.
+
+    ``header`` / ``footer`` hold the running page furniture (e.g.
+    "Confidential -- page 4 of 27") that OCR pulled out of the main
+    content, so it can be excluded from RAG chunks.
+
+    ``average_confidence`` / ``minimum_confidence`` are OCR self-reported
+    scores for the page. Calibrate thresholds against your own corpus:
+    measured across the benchmark PDFs, ``average_confidence`` stayed in
+    0.985-0.989 and ``minimum_confidence`` in 0.23-0.46 regardless of
+    document quality. ``minimum_confidence`` reflects the single worst
+    region on the page, so it reads low even on clean pages and is not
+    on its own a signal that the page went badly.
+    """
+
+    page: int
+    header: str | None = None
+    footer: str | None = None
+    average_confidence: float | None = None
+    minimum_confidence: float | None = None
+
+
+@dataclass(frozen=True)
+class ParseResult:
+    """Markdown plus the images extracted from the source document."""
+
+    markdown: str
+    images: list[ExtractedImage] = field(default_factory=list)
+    pages: list[PageInfo] = field(default_factory=list)
+
+
+@runtime_checkable
+class VLM(Protocol):
+    """Vision-language model used to interpret images extracted from DOCX.
+
+    Implementations should return either a plain description string
+    (legacy) or a structured :class:`ImageDescription` carrying both
+    a short title and the longer interpretation. `context` is the
+    surrounding markdown text (e.g. the paragraph immediately before
+    the image) that the implementation may use to ground its
+    description; treat it as optional context, not as part of the
+    prompt's instructions.
+    """
+
+    def describe_image(
+        self,
+        image_base64: str,
+        *,
+        mime_type: str = "image/png",
+        context: str | None = None,
+    ) -> "str | ImageDescription": ...

dot_parser/markdown_utils.py

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Shared markdown post-processing utilities used across backends.
+
+Lives outside `backends/` because both the PDF (Mistral OCR) and the
+DOCX (markitdown) paths need the same table-stripping pass: neither
+underlying tool exposes a native "drop tables" flag, so the caller is
+responsible for removing them after the fact when ``include_tables``
+is False.
+"""
+
+import re
+
+_TABLE_ROW_RE = re.compile(r"^\s*\|.*\|\s*$")
+_TABLE_SEP_RE = re.compile(r"^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$")
+
+
+def strip_markdown_tables(markdown: str) -> str:
+    """Drop GFM-style markdown tables from a body of text.
+
+    A table block here means: two or more consecutive lines where the
+    first matches a pipe-row and the second is a ``| --- | --- |``
+    separator. Operates line-by-line so it survives tables that aren't
+    surrounded by blank lines (Mistral OCR sometimes packs them tight
+    against surrounding prose; markitdown leaves a blank line, but the
+    same code path handles both).
+
+    Heuristic by design — we don't try to parse the full GFM table
+    grammar — but it cleanly removes the structures both Mistral OCR
+    and markitdown produce today and leaves non-table pipe lines alone.
+    """
+    lines = markdown.split("\n")
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        if (
+            i + 1 < len(lines)
+            and _TABLE_ROW_RE.match(lines[i])
+            and _TABLE_SEP_RE.match(lines[i + 1])
+        ):
+            i += 2
+            while i < len(lines) and _TABLE_ROW_RE.match(lines[i]):
+                i += 1
+            continue
+        out.append(lines[i])
+        i += 1
+    return re.sub(r"\n{3,}", "\n\n", "\n".join(out)).strip("\n")

dot_parser/models.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import re
+from dataclasses import dataclass, field
+
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.+)$")
+
+
+class ParseError(Exception):
+    """Raised when a document cannot be parsed."""
+
+
+@dataclass(frozen=True)
+class Chunk:
+    content: str
+    section_path: list[str] = field(default_factory=list)
+
+    @property
+    def heading(self) -> str | None:
+        first_line = self.content.split("\n", 1)[0]
+        return first_line if _HEADING_RE.match(first_line) else None

dot_parser/parsers.py

@@ -0,0 +1,325 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import logging
+import tempfile
+from pathlib import Path
+
+import markitdown
+
+from dot_parser.backends import (
+    Backend,
+    BatchBackend,
+    DocxImageBackend,
+    ImageBackend,
+    Mistral,
+    PptxImageBackend,
+    Pymu,
+)
+from dot_parser.images import VLM, ParseResult
+from dot_parser.models import ParseError
+
+_log = logging.getLogger(__name__)
+
+PDF_EXTENSIONS = {".pdf"}
+PASSTHROUGH_EXTENSIONS = {".md", ".txt"}
+MARKITDOWN_EXTENSIONS = {".docx", ".pptx", ".html", ".xhtml", ".htm", ".xlsx", ".csv"}
+ALL_EXTENSIONS = PDF_EXTENSIONS | PASSTHROUGH_EXTENSIONS | MARKITDOWN_EXTENSIONS
+
+_EXTENSION_MAP: dict[str, str] = {
+    "pdf": ".pdf",
+    "md": ".md",
+    "markdown": ".md",
+    "txt": ".txt",
+    "text": ".txt",
+    "docx": ".docx",
+    "pptx": ".pptx",
+    "html": ".html",
+    "xhtml": ".xhtml",
+    "htm": ".htm",
+    "xlsx": ".xlsx",
+    "csv": ".csv",
+}
+
+
+def _resolve_extension(source: str | Path | bytes, format: str | None) -> str:
+    if format is not None:
+        ext = _EXTENSION_MAP.get(format.lower())
+        if ext is None:
+            raise ParseError(f"Unknown format: {format!r}")
+        return ext
+
+    if isinstance(source, bytes):
+        raise ParseError("format is required when source is bytes")
+
+    ext = Path(source).suffix.lower()
+    if not ext:
+        raise ParseError(f"Cannot determine format for {source!r}: no file extension")
+    if ext not in ALL_EXTENSIONS:
+        raise ParseError(f"Unsupported file extension: {ext!r}")
+    return ext
+
+
+def _read_text(source: str | Path | bytes) -> str:
+    if isinstance(source, bytes):
+        return source.decode("utf-8")
+    return Path(source).read_text(encoding="utf-8")
+
+
+def _parse_with_markitdown(source: str | Path | bytes, ext: str) -> str:
+    md = markitdown.MarkItDown()
+    if isinstance(source, bytes):
+        with tempfile.NamedTemporaryFile(suffix=ext, delete=True) as tmp:
+            tmp.write(source)
+            tmp.flush()
+            result = md.convert(tmp.name)
+    else:
+        result = md.convert(str(source))
+    return result.text_content
+
+
+def parse(
+    source: str | Path | bytes,
+    format: str | None = None,
+    backend: Backend | None = None,
+) -> str:
+    """Convert a document to Markdown.
+
+    Args:
+        source: file path (str or Path) or raw bytes.
+        format: explicit format hint (e.g. "pdf"). Required when source is bytes.
+        backend: optional PDF backend (Pymu, Docling, Mistral, Llama). When None,
+            uses Pymu (pymupdf4llm) for PDFs. Backends only apply to PDF input;
+            passing one for a non-PDF format raises ParseError.
+
+    Returns:
+        Markdown string.
+
+    Raises:
+        ParseError: on unsupported format, missing file, or backend mismatch.
+    """
+    ext = _resolve_extension(source, format)
+
+    if backend is not None and ext not in PDF_EXTENSIONS:
+        raise ParseError(f"backend= is only supported for PDF input (got {ext!r})")
+
+    try:
+        if ext in PDF_EXTENSIONS:
+            return (backend or Pymu()).parse_pdf(source)
+        elif ext in PASSTHROUGH_EXTENSIONS:
+            return _read_text(source)
+        else:
+            return _parse_with_markitdown(source, ext)
+    except ParseError:
+        raise
+    except Exception as e:
+        label = "<bytes>" if isinstance(source, bytes) else str(source)
+        raise ParseError(f"Could not parse {label}: {e}") from e
+
+
+def parse_with_images(
+    source: str | Path | bytes,
+    format: str | None = None,
+    *,
+    backend: ImageBackend | DocxImageBackend | PptxImageBackend | None = None,
+    vlm: VLM | None = None,
+    annotate_images: bool = True,
+    include_tables: bool = True,
+    deadline: float | None = None,
+) -> ParseResult:
+    """Convert a document to Markdown and extract its images.
+
+    Args:
+        source: file path or raw bytes. Only ``.pdf``, ``.docx`` and
+            ``.pptx`` are supported by this function; other formats
+            raise ParseError.
+        format: explicit format hint. Required when source is bytes.
+        backend: optional image-capable backend. For PDF, defaults to a
+            fresh ``Mistral()`` instance and must expose
+            ``parse_pdf_with_images``. For DOCX/PPTX, when a backend
+            exposing ``parse_docx_with_images`` /
+            ``parse_pptx_with_images`` is passed (e.g. ``Mistral()``),
+            the document goes through OCR end-to-end — no VLM needed.
+        vlm: vision-language model used to interpret each DOCX/PPTX
+            image in the markitdown path. Required for DOCX/PPTX when
+            no format-capable backend is provided; ignored for PDF and
+            for the OCR path (Mistral OCR annotates images inline via
+            ``annotate_images``).
+        annotate_images: Applies to any OCR-backed path (PDF, or
+            DOCX/PPTX with ``backend=Mistral()``). When True (default),
+            Mistral OCR is asked to return a short description per
+            image in the same call. Set False to receive raw images
+            without interpretation. Ignored on the markitdown+VLM path
+            (the VLM is always invoked there).
+        include_tables: When False, drop tabular content from the
+            returned markdown.
+        deadline: absolute ``time.monotonic()`` timestamp bounding
+            per-image interpretation on the markitdown+VLM path. Images
+            not reached in time come back uninterpreted with
+            ``unsupported_reason`` set, instead of the call overrunning.
+            Ignored on OCR-backed paths.
+
+    Returns:
+        A :class:`ParseResult` with the markdown (containing
+        ``![name](name)`` anchors at image positions) and an
+        :class:`ExtractedImage` per image, in document order.
+
+    Raises:
+        ParseError: on unsupported format, missing backend/vlm, or when
+            a backend doesn't expose the relevant image-extraction
+            method for the input format.
+    """
+    ext = _resolve_extension(source, format)
+
+    if ext == ".pdf":
+        be = backend or Mistral()
+        if not isinstance(be, ImageBackend):
+            raise ParseError(
+                "Selected backend does not support image extraction. "
+                "Use Mistral() or another ImageBackend implementation."
+            )
+        try:
+            return be.parse_pdf_with_images(
+                source,
+                annotate_images=annotate_images,
+                include_tables=include_tables,
+            )
+        except ParseError:
+            raise
+        except Exception as e:
+            label = "<bytes>" if isinstance(source, bytes) else str(source)
+            raise ParseError(f"Could not parse {label}: {e}") from e
+
+    if ext in (".docx", ".pptx"):
+        # DOCX and PPTX each have two interchangeable paths. The OCR
+        # path wins when a backend that supports the format is passed
+        # in; otherwise we fall back to the markitdown + per-image VLM
+        # path.
+        fmt = ext[1:]
+        backend_method = f"parse_{fmt}_with_images"
+        if backend is not None and hasattr(backend, backend_method):
+            try:
+                return getattr(backend, backend_method)(
+                    source,
+                    annotate_images=annotate_images,
+                    include_tables=include_tables,
+                )
+            except ParseError:
+                raise
+            except Exception as e:
+                label = "<bytes>" if isinstance(source, bytes) else str(source)
+                raise ParseError(f"Could not parse {label}: {e}") from e
+
+        if vlm is None:
+            raise ParseError(
+                f"{fmt.upper()} image extraction requires either a "
+                f"{fmt.upper()}-capable backend (e.g. backend=Mistral()) "
+                "or a VLM (e.g. vlm=MistralVLM()) for the markitdown path."
+            )
+        # Imported lazily so importing dot_parser.parsers doesn't pull
+        # in python-docx for callers that only use the text-only API.
+        from dot_parser import docx_images as _office_images
+
+        _parse_office = getattr(_office_images, f"parse_{fmt}_with_images")
+        try:
+            return _parse_office(
+                source,
+                vlm=vlm,
+                include_tables=include_tables,
+                deadline=deadline,
+            )
+        except ParseError:
+            raise
+        except Exception as e:
+            label = "<bytes>" if isinstance(source, bytes) else str(source)
+            raise ParseError(f"Could not parse {label}: {e}") from e
+
+    raise ParseError(f"parse_with_images only supports .pdf, .docx and .pptx (got {ext!r})")
+
+
+def interpret_images(
+    result: ParseResult,
+    vlm: VLM,
+    *,
+    deadline: float | None = None,
+) -> ParseResult:
+    """Second-pass VLM interpretation of a ``ParseResult``'s images.
+
+    Fills ``interpretation`` (and ``title``) on each image by calling
+    ``vlm.describe_image`` once per image, grounding the call with the
+    image's ``original_caption`` (explicitly labelled) plus the markdown
+    surrounding its ``![name](name)`` anchor.
+
+    This exists because Mistral OCR's inline annotations
+    (``annotate_images=True``) are produced from the cropped image alone —
+    the annotating model sees no caption and no page text, which on
+    domain-specific figures produces confidently wrong descriptions. The
+    grounded recipe is::
+
+        result = parse_with_images(
+            "doc.pdf",
+            backend=Mistral(extract_captions=True),
+            annotate_images=False,  # skip the ungrounded inline pass
+        )
+        result = interpret_images(result, MistralVLM())
+
+    Same number of VLM calls as ``annotate_images=True`` (one per image,
+    just client-side), but each call carries the figure's own caption.
+    Note the latency shape differs even though the count matches:
+    ``annotate_images=True`` annotates every image inside the single
+    ``ocr.process`` request, whereas this pass issues its own calls one
+    after another — so on image-heavy documents pass a ``deadline``.
+
+    Returns a new ``ParseResult``; markdown and pages are unchanged.
+    Per-image VLM failures are absorbed (that image's interpretation
+    stays None), as are images the ``deadline`` cuts short — those carry
+    ``unsupported_reason`` instead. Existing interpretations are
+    overwritten.
+    """
+    from dot_parser.docx_images import _interpret_images
+
+    images = _interpret_images(
+        result.markdown,
+        result.images,
+        vlm,
+        caption_in_context=True,
+        deadline=deadline,
+    )
+    return ParseResult(markdown=result.markdown, images=images, pages=result.pages)
+
+
+def parse_pdfs(
+    sources: list[str | Path | bytes],
+    backend: Backend | None = None,
+) -> list[str | None]:
+    """Convert multiple PDFs to Markdown, in input order.
+
+    Backends that implement a ``parse_pdfs`` method (e.g. ``Mistral`` via the
+    Batch API) handle the whole list in one optimized call. For backends
+    without that method, falls back to looping ``parse()`` on each source.
+
+    Args:
+        sources: list of PDF file paths or raw bytes.
+        backend: optional PDF backend. Defaults to Pymu().
+
+    Returns:
+        A list of Markdown strings, same length and order as ``sources``.
+        Failed items are returned as ``None`` (no exception raised).
+    """
+    be = backend or Pymu()
+    if isinstance(be, BatchBackend):
+        return be.parse_pdfs(sources)
+    results: list[str | None] = []
+    for src in sources:
+        try:
+            # parse_pdfs is PDF-only, so pin format="pdf": callers pass raw bytes
+            # (in-memory PDFs) which parse() can't infer an extension from, and
+            # would otherwise reject with "format is required when source is bytes".
+            results.append(parse(src, format="pdf", backend=be))
+        except ParseError as exc:
+            # Loop-fallback backends (e.g. Pymu) fail per file; log why before
+            # dropping to None so the caller isn't left with an unexplained gap.
+            label = "<bytes>" if isinstance(src, bytes) else str(src)
+            _log.error("parse_pdfs: could not parse %s: %s", label, exc)
+            results.append(None)
+    return results