dot-parser 2.0.0__py3-none-any.whl

dot_parser/docx_images.py

@@ -0,0 +1,633 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Office documents (DOCX/PPTX) → Markdown with per-image interpretation.
+
+Runs markitdown to produce the markdown body — which already inlines
+each embedded image as ``![alt](data:image/<mime>;base64,...)`` at the
+correct document position — then walks those data URLs in order,
+rewriting them into stable ``![name](name)`` anchors and emitting one
+:class:`ExtractedImage` per match. Each image is then handed to the
+caller-supplied VLM for a textual interpretation.
+
+Going through markitdown (instead of the previous hand-written
+python-docx walker) means the text rendering matches the text-only
+``parse(format='docx')`` path exactly — same markdown surface with or
+without ``parse_images=True`` — and we inherit markitdown's handling of
+formatting, lists, tables, headers, and footers for free.
+
+The pipeline is format-agnostic: markitdown dispatches on the file
+extension and both its DOCX and PPTX converters honour
+``keep_data_uris=True``. For PPTX, markitdown additionally emits a
+``<!-- Slide number: N -->`` comment before each slide and the slide
+title as an ``#`` heading. Note that the PPTX path only sees *embedded
+pictures* — diagrams drawn natively in PowerPoint (shapes, arrows,
+SmartArt) have no image payload and surface as text fragments only;
+use the Mistral OCR path (``backend=Mistral()``) when those matter.
+"""
+
+import base64
+import io
+import logging
+import re
+import tempfile
+import time
+from pathlib import Path
+
+from dot_parser.image_utils import dedupe_titles
+from dot_parser.images import (
+    VLM,
+    ExtractedImage,
+    ImageDescription,
+    ParseResult,
+)
+from dot_parser.markdown_utils import strip_markdown_tables
+from dot_parser.models import ParseError
+
+_logger = logging.getLogger(__name__)
+
+# Markdown blocks around each image anchor that we feed back to the VLM
+# as context. We look both before and after the anchor: French/EU
+# technical documents place figure captions ("Figure 1: …") directly
+# *below* the image, so a preceding-only window would miss them.
+# TODO: ENH since I did not really optimize these numbers, maybe we should adapt them
+# based on some parameters and the multimodel model of choice.)
+_CONTEXT_BLOCKS_BEFORE = 3
+_CONTEXT_BLOCKS_AFTER = 2
+
+
+# Reported in `unsupported_reason` for images the deadline cut short.
+# Deliberately reuses the "why is there no interpretation" channel that
+# undecodable formats already populate, so existing consumers render it
+# with no change.
+SKIPPED_DEADLINE_REASON = (
+    "Not interpreted: the document's image-analysis time budget ran out "
+    "before this image was reached."
+)
+
+# MIME types Mistral's chat-vision models currently accept (Mistral
+# Large 3 / Medium 3.1 / Small 3.2 / Ministral 3 — Pixtral is
+# deprecated). Anything outside this set is first handed to Pillow for a
+# rescue conversion (see the interpretation loop); only if Pillow can't
+# decode it do we surface it as unsupported.
+_VLM_SUPPORTED_MIMES = frozenset(
+    {
+        "image/png",
+        "image/jpeg",
+        "image/jpg",
+        "image/webp",
+        "image/gif",
+    }
+)
+
+# Aliases for the canonical MIME types above. Data URLs don't use a
+# single canonical spelling — the same bytes show up as "image/x-png",
+# "image/x-ms-bmp", etc. depending on the producer. We normalise these
+# before the membership / conversion decisions so a non-canonical
+# spelling never gets misrouted to the unsupported branch.
+_MIME_ALIASES: dict[str, str] = {
+    "image/x-png": "image/png",
+    "image/pjpeg": "image/jpeg",
+    "image/x-ms-bmp": "image/bmp",
+    "image/x-bmp": "image/bmp",
+    "image/x-tiff": "image/tiff",
+}
+
+
+def _normalize_mime(mime_type: str) -> str:
+    """Collapse known MIME aliases to their canonical spelling."""
+    return _MIME_ALIASES.get(mime_type.lower(), mime_type.lower())
+
+
+# Per-format messages surfaced as ExtractedImage.unsupported_reason
+# so downstream consumers can explain to end-users why an image was
+# not interpreted, and what external tool could recover it.
+#
+# Each comment below records (a) when this MIME actually appears in
+# real DOCX files and (b) the recommended fix if we ever decide to
+# add full support. Every non-VLM-native image is first attempted via
+# Pillow (_convert_raster_to_png); this dict is only consulted when that
+# decode returns None — so raster formats (BMP, TIFF, and any
+# plugin-registered format) only land here on an actual decode failure.
+_UNSUPPORTED_REASONS: dict[str, str] = {
+    # Seen in: Word docs containing Visio drawings, SmartArt, grouped
+    # shapes, or charts — Word inlines an EMF as a fallback raster of
+    # the vector content. The "real" source often lives in
+    # word/embeddings/*.bin (OLE-embedded Visio), which is a separate
+    # extraction problem.
+    # Fix: shell out to `soffice --headless --convert-to png`
+    "image/x-emf": (
+        "Windows Enhanced Metafile (.emf): vector instruction stream "
+        "embedded by Word as a fallback preview for Visio drawings, "
+        "SmartArt or grouped shapes. Not accepted by the vision API. "
+        "Rendering requires an external tool such as LibreOffice "
+        "(`soffice --headless --convert-to png`) or Inkscape. The raw "
+        "base64 bytes are still returned for download or external "
+        "processing."
+    ),
+    # Seen in: legacy/old Office documents (pre-2007 era) and content
+    # copy-pasted from older applications. Much rarer than EMF today.
+    # Fix: same toolchain as EMF — both LibreOffice and Inkscape read
+    # WMF. No separate code path needed if EMF support lands.
+    "image/x-wmf": (
+        "Windows Metafile (.wmf): legacy Windows vector format, often "
+        "carried inside older Office documents. Not accepted by the "
+        "vision API. Convert via LibreOffice or Inkscape to render."
+    ),
+    # Seen in: modern Word (Office 365 inserts SVG natively when you
+    # paste icons or vector graphics) and exports from Figma /
+    # Illustrator / draw.io. Browsers already render SVG data-URLs
+    # directly, so the frontend visual is fine without us — the only
+    # gain from local conversion is the VLM caption.
+    # Fix: `resvg-py` (Rust binding, ships with wheels, no system
+    # libs) is the low-friction option; `cairosvg` has broader SVG
+    # feature coverage but pulls in cairo/pango as OS libs.
+    "image/svg+xml": (
+        "Scalable Vector Graphics: browser-renderable but not accepted "
+        "by the vision API. Convert to PNG (e.g. cairosvg) for "
+        "interpretation, or render client-side from the base64 bytes."
+    ),
+    # Reached only when _convert_raster_to_png() fails on a TIFF
+    # payload — typically unsupported compression (e.g. CCITT G4 from
+    # scanners without libtiff support in the wheel) or multi-page
+    # documents where we currently keep only the first frame.
+    # Fix: extend _convert_raster_to_png to iterate `n_frames` and
+    # emit one ExtractedImage per page; install Pillow with full
+    # libtiff support for exotic compressions.
+    "image/tiff": (
+        "TIFF: automatic conversion to PNG via Pillow failed for this "
+        "image (e.g. unsupported compression or multi-page payload). The "
+        "raw base64 bytes are still returned for external recovery."
+    ),
+    # Reached only when _convert_raster_to_png() fails on a BMP — very
+    # rare in practice; mostly indicates a corrupt or truncated
+    # payload extracted from a damaged DOCX. No code change needed
+    # beyond surfacing this reason.
+    "image/bmp": (
+        "BMP: automatic conversion to PNG via Pillow failed for this "
+        "image. The raw base64 bytes are still returned for external "
+        "recovery."
+    ),
+    # Seen in: almost never in real DOCX files — AVIF is a web format
+    # (Chrome/Safari era), not something Office tooling produces.
+    # Listed defensively in case a user pastes web content.
+    # Fix: add `pillow-avif-plugin` to deps and import it once at
+    # startup; the plugin auto-registers a Pillow decoder, after which
+    # the rescue-conversion path picks AVIF up with no other changes.
+    "image/avif": (
+        "AVIF: not accepted by the vision API. Convert to PNG or "
+        "WebP using Pillow (with pillow-avif-plugin) for interpretation."
+    ),
+}
+
+# Formats not in _UNSUPPORTED_REASONS yet (they fall through to the
+# generic message in _unsupported_reason). Because the rescue path now
+# tries Pillow on anything non-native, "adding support" for a raster
+# format is purely a matter of making Pillow able to decode it — no
+# MIME-set edit is needed:
+#
+#   image/heic, image/heif
+#     Seen in: iPhone screenshots and photos pasted into Word — rising
+#     fast as a real-world source.
+#     Fix: add `pillow-heif` dep + import it once at startup. The plugin
+#     registers a Pillow decoder and the rescue path handles the rest.
+#
+#   image/jp2 (JPEG 2000)
+#     Seen in: scientific/archival pipelines; vanishingly rare in
+#     Office documents.
+#     Fix: works out of the box if the Pillow wheel was built with
+#     OpenJPEG support (most modern wheels are) — nothing to add.
+#
+#   image/x-icon (favicons / Windows ICO)
+#     Seen in: occasional paste from a browser into Word.
+#     Fix: Pillow has native ICO support, so the rescue path already
+#     handles it. Multi-resolution ICOs collapse to the largest frame,
+#     which is what we want for VLM interpretation.
+#
+#   image/eps (encapsulated PostScript)
+#     Seen in: academic/print-publishing pipelines, very rare in
+#     modern Office.
+#     Fix: Pillow can decode EPS but only if Ghostscript is installed
+#     on the host. Better treated like EMF (optional extra + binary
+#     probe).
+
+
+def _convert_raster_to_png(b64: str) -> tuple[str, str] | None:
+    """Re-encode a raster image (BMP/TIFF) as PNG via Pillow.
+
+    Returns ``(new_b64, "image/png")`` on success, or ``None`` if the
+    payload can't be decoded (corrupt bytes, unsupported TIFF
+    compression, missing Pillow). Multi-page TIFFs collapse to the
+    first frame — good enough for document images, where TIFFs are
+    almost always single-page scans.
+    """
+    try:
+        from PIL import Image
+    except ImportError:
+        _logger.warning("Pillow not installed; skipping raster→PNG conversion.")
+        return None
+    try:
+        raw = base64.b64decode(b64)
+        with Image.open(io.BytesIO(raw)) as im:
+            im.load()
+            if im.mode not in ("RGB", "RGBA", "L", "LA", "P"):
+                im = im.convert("RGBA")
+            out = io.BytesIO()
+            im.save(out, format="PNG")
+        return base64.b64encode(out.getvalue()).decode("ascii"), "image/png"
+    except Exception as exc:
+        _logger.warning("Raster→PNG conversion failed: %s", exc)
+        return None
+
+
+def _unsupported_reason(mime_type: str) -> str:
+    """Return a human-readable explanation for an unsupported MIME.
+
+    Looks up a per-format message; falls back to a generic one
+    pointing at the offending MIME so consumers always get *some*
+    actionable detail rather than a bare None.
+    """
+    if mime_type in _UNSUPPORTED_REASONS:
+        return _UNSUPPORTED_REASONS[mime_type]
+    return (
+        f"Image format '{mime_type}' is not currently supported by "
+        "the image interpretation pipeline. The raw base64 bytes are "
+        "still returned for download or external processing."
+    )
+
+
+# Matches markitdown's inline data-URL images. markitdown emits them
+# on a single line so we don't need DOTALL. Alt text is captured so
+# we can carry it through as `original_caption` for the title fallback.
+_DATA_URL_IMG_RE = re.compile(
+    r"!\[(?P<alt>[^\]]*)\]"
+    r"\(data:image/(?P<subtype>[A-Za-z0-9.+\-]+);base64,(?P<b64>[A-Za-z0-9+/=]+)\)"
+)
+
+_MIME_SUBTYPE_TO_EXT: dict[str, str] = {
+    "png": "png",
+    "x-png": "png",
+    "jpeg": "jpg",
+    "jpg": "jpg",
+    "webp": "webp",
+    "gif": "gif",
+    "bmp": "bmp",
+    "tiff": "tiff",
+    "svg+xml": "svg",
+}
+
+
+def _ext_for_subtype(subtype: str) -> str:
+    return _MIME_SUBTYPE_TO_EXT.get(subtype.lower(), "png")
+
+
+def _extract_data_url_images(
+    raw_md: str,
+) -> tuple[str, list[ExtractedImage]]:
+    """Rewrite markitdown's inline data-URL images as stable anchors.
+
+    Walks data-URL matches in document order, mints ``img-NNN.<ext>``
+    names, and returns the rewritten markdown alongside one
+    :class:`ExtractedImage` per match (carrying the raw base64). The
+    image's alt text is preserved as ``original_caption`` so it remains
+    available as a title fallback in :func:`_interpret_images`.
+    """
+    images: list[ExtractedImage] = []
+
+    def _sub(match: re.Match) -> str:
+        alt = match.group("alt") or None
+        subtype = match.group("subtype")
+        b64 = match.group("b64")
+        mime = f"image/{subtype}"
+        ext = _ext_for_subtype(subtype)
+        name = f"img-{len(images) + 1:03d}.{ext}"
+        images.append(
+            ExtractedImage(
+                name=name,
+                base64=b64,
+                mime_type=mime,
+                original_caption=alt,
+            )
+        )
+        return f"![{name}]({name})"
+
+    rewritten = _DATA_URL_IMG_RE.sub(_sub, raw_md)
+    return rewritten, images
+
+
+def _slugify_caption(caption: str | None) -> str | None:
+    """Derive a kebab-case slug from a free-form caption string.
+
+    Returns None for empty / unusable captions. Caps length at 8 words so
+    captions like "Figure 3: The full bill-of-materials of the assembly,
+    including..." produce something compact rather than a sentence-long
+    filename.
+    """
+    if not caption:
+        return None
+    # Strip common "Figure N:" / "Fig. N -" prefixes Word users type.
+    stripped = re.sub(
+        r"^\s*(figure|fig\.?|table|image|img\.?|exhibit)\s*\d*[:.\-]?\s*",
+        "",
+        caption,
+        flags=re.IGNORECASE,
+    )
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", stripped).strip("-").lower()
+    if not slug:
+        return None
+    parts = slug.split("-")
+    return "-".join(parts[:8])
+
+
+def _interpret_images(
+    markdown: str,
+    images: list[ExtractedImage],
+    vlm: VLM,
+    *,
+    caption_in_context: bool = False,
+    deadline: float | None = None,
+) -> list[ExtractedImage]:
+    """Call ``vlm.describe_image`` for each image and assign titles.
+
+    When ``caption_in_context`` is True, an image's ``original_caption``
+    is prepended to the VLM context, explicitly labelled. The caption is
+    the strongest grounding available — it is the author's own statement
+    of what the figure shows — so it is passed explicitly rather than
+    relying on it happening to appear in the sliced markdown
+    neighbourhood. Both production call sites (the DOCX markitdown path
+    and :func:`dot_parser.parsers.interpret_images`) enable it; the flag
+    exists so images without captions cost nothing and so the grounding
+    can be switched off in isolation if it ever misbehaves.
+
+    ``deadline`` is an absolute :func:`time.monotonic` timestamp bounding
+    the interpretation phase. Calls are issued one at a time, each taking
+    a few seconds, so a document with many figures can otherwise run for
+    longer than any caller is willing to wait — an image-heavy report
+    carries 100-200 of them. Once the deadline passes, the images not yet
+    reached are returned with their raw bytes intact and
+    :data:`SKIPPED_DEADLINE_REASON` in ``unsupported_reason``, the same
+    channel already used for undecodable formats, so consumers need no
+    new branch. That makes an oversized document a partial result rather
+    than a failed request. The deadline is checked before each call, so
+    at most one in-progress call overruns it; bound that with a per-call
+    timeout on the VLM itself.
+
+    Title resolution order per image:
+      1. VLM-generated kebab-case slug (preferred)
+      2. Slug derived from the document's original caption, if any
+      3. None (leave it to consumers to display the technical ``name``)
+
+    Duplicate titles across the document are disambiguated with
+    ``-2``, ``-3``, ... suffixes so that the title is safe to use as a
+    display label.
+
+    Backwards-compatible with VLM implementations that return a plain
+    ``str``: those simply produce ``interpretation`` with no title.
+    Per-image VLM failures are absorbed (interpretation stays None).
+    """
+    blocks = markdown.split("\n\n")
+    # Locate each anchor block once to slice surrounding context cheaply.
+    anchor_positions: dict[str, int] = {}
+    for i, block in enumerate(blocks):
+        for img in images:
+            anchor = f"![{img.name}]({img.name})"
+            if anchor in block and img.name not in anchor_positions:
+                anchor_positions[img.name] = i
+
+    interpretations: list[str | None] = []
+    raw_titles: list[str | None] = []
+    unsupported_reasons: list[str | None] = []
+    effective_b64s: list[str | None] = []
+    effective_mimes: list[str | None] = []
+    for index, img in enumerate(images):
+        if deadline is not None and time.monotonic() >= deadline:
+            # Out of time: hand back everything still untouched rather
+            # than letting the caller's request run over.
+            remaining = len(images) - index
+            _logger.warning(
+                "image interpretation deadline reached: %d of %d image(s) left uninterpreted",
+                remaining,
+                len(images),
+            )
+            for _ in range(remaining):
+                interpretations.append(None)
+                raw_titles.append(None)
+                unsupported_reasons.append(SKIPPED_DEADLINE_REASON)
+                effective_b64s.append(None)
+                effective_mimes.append(None)
+            break
+
+        vlm_b64 = img.base64
+        vlm_mime = img.mime_type
+        converted: tuple[str, str] | None = None
+
+        # Anything the VLM doesn't natively accept is handed to Pillow
+        # for a rescue conversion to PNG — BMP/TIFF and any raster format
+        # Pillow can decode (incl. plugin-registered HEIC/AVIF) come back
+        # as PNG and enter the regular VLM path. We let Pillow be the
+        # judge rather than gating on a hardcoded MIME set: a successful
+        # decode *is* the support signal, so non-canonical spellings
+        # (image/x-ms-bmp, …) and future formats work without code
+        # changes. Formats Pillow can't decode (EMF/WMF/SVG/…) return
+        # None and fall through to the unsupported branch below, with the
+        # original bytes preserved for download or external processing.
+        if _normalize_mime(vlm_mime) not in _VLM_SUPPORTED_MIMES:
+            converted = _convert_raster_to_png(img.base64)
+            if converted is not None:
+                vlm_b64, vlm_mime = converted
+            else:
+                interpretations.append(None)
+                raw_titles.append(None)
+                unsupported_reasons.append(_unsupported_reason(img.mime_type))
+                effective_b64s.append(None)
+                effective_mimes.append(None)
+                continue
+
+        pos = anchor_positions.get(img.name)
+        context_parts: list[str] = []
+        if caption_in_context and img.original_caption:
+            context_parts.append(f"Figure caption from the document: {img.original_caption}")
+        if pos is not None:
+            start = max(0, pos - _CONTEXT_BLOCKS_BEFORE)
+            end = pos + 1 + _CONTEXT_BLOCKS_AFTER
+            before = [b for b in blocks[start:pos] if b.strip()]
+            after = [b for b in blocks[pos + 1 : end] if b.strip()]
+            context_parts.extend(before + after)
+        context: str | None = "\n\n".join(context_parts) or None
+        try:
+            result = vlm.describe_image(
+                vlm_b64,
+                mime_type=vlm_mime,
+                context=context,
+            )
+        except Exception:
+            result = None
+
+        if isinstance(result, ImageDescription):
+            interpretations.append(result.interpretation or None)
+            raw_titles.append(result.title)
+        elif isinstance(result, str):
+            interpretations.append(result or None)
+            raw_titles.append(None)
+        else:
+            interpretations.append(None)
+            raw_titles.append(None)
+        unsupported_reasons.append(None)
+        # Surface the converted PNG bytes on the emitted ExtractedImage
+        # so the frontend can render the image without browser-side
+        # decoder support for the original format.
+        effective_b64s.append(converted[0] if converted else None)
+        effective_mimes.append(converted[1] if converted else None)
+
+    # Apply caption fallback for any image whose VLM didn't supply a title.
+    resolved_titles: list[str | None] = [
+        rt if rt else _slugify_caption(img.original_caption)
+        for rt, img in zip(raw_titles, images, strict=True)
+    ]
+    final_titles = dedupe_titles(resolved_titles)
+
+    return [
+        ExtractedImage(
+            name=img.name,
+            base64=eff_b64 or img.base64,
+            mime_type=eff_mime or img.mime_type,
+            page=img.page,
+            original_caption=img.original_caption,
+            interpretation=interp,
+            title=title,
+            unsupported_reason=reason,
+        )
+        for img, interp, title, reason, eff_b64, eff_mime in zip(
+            images,
+            interpretations,
+            final_titles,
+            unsupported_reasons,
+            effective_b64s,
+            effective_mimes,
+            strict=True,
+        )
+    ]
+
+
+def _office_to_markdown_via_markitdown(file_path: str) -> str:
+    """Convert an office document (DOCX/PPTX) to markdown via markitdown.
+
+    markitdown dispatches on the file extension and emits embedded
+    images inline as ``![alt](data:image/<mime>;base64,<b64>)`` at the
+    correct document position; we hand that off to
+    :func:`_extract_data_url_images` to rewrite the anchors and pull
+    the bytes out.
+
+    ``keep_data_uris=True`` is required: by default markitdown's
+    ``_CustomMarkdownify.convert_img`` truncates ``data:`` URLs at the
+    first comma (replacing the base64 payload with ``...``) to keep
+    markdown small for the LLM-summarisation use case it was designed
+    for. We need the full payload to extract the image bytes.
+    """
+    try:
+        import markitdown
+    except ImportError as e:
+        raise ParseError(
+            "Office image extraction requires markitdown. Install with: pip install dot-parser"
+        ) from e
+    return markitdown.MarkItDown().convert(file_path, keep_data_uris=True).text_content
+
+
+def _parse_office_with_images(
+    source: str | Path | bytes,
+    vlm: VLM,
+    *,
+    suffix: str,
+    include_tables: bool,
+    deadline: float | None = None,
+) -> ParseResult:
+    """Shared markitdown+VLM pipeline for DOCX and PPTX sources."""
+    if isinstance(source, bytes):
+        with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+            tmp.write(source)
+            tmp.flush()
+            path = Path(tmp.name)
+        try:
+            raw_md = _office_to_markdown_via_markitdown(str(path))
+        finally:
+            path.unlink(missing_ok=True)
+    else:
+        raw_md = _office_to_markdown_via_markitdown(str(source))
+
+    markdown, images = _extract_data_url_images(raw_md)
+    if not include_tables:
+        markdown = strip_markdown_tables(markdown)
+    if images:
+        images = _interpret_images(
+            markdown,
+            images,
+            vlm,
+            caption_in_context=True,
+            deadline=deadline,
+        )
+    return ParseResult(markdown=markdown, images=images)
+
+
+def parse_docx_with_images(
+    source: str | Path | bytes,
+    vlm: VLM,
+    *,
+    include_tables: bool = True,
+    deadline: float | None = None,
+) -> ParseResult:
+    """Parse a DOCX into markdown + interpreted images.
+
+    Text rendering matches the text-only ``parse(format='docx')`` path
+    because both routes go through markitdown. Image bytes are surfaced
+    out of markitdown's inline data URLs and rewritten as stable
+    ``![name](name)`` anchors at the same document positions.
+
+    ``vlm`` is invoked once per image with surrounding markdown context
+    (±3 blocks before, ±2 after), one image at a time.
+    Per-image VLM failures are absorbed (interpretation stays None) so
+    that a single bad image cannot fail the whole document; ``deadline``
+    bounds the interpretation phase and leaves any images it cuts short
+    uninterpreted rather than failing. See :func:`_interpret_images`.
+
+    When ``include_tables`` is False, GFM-style tables are stripped from
+    the resulting markdown — markitdown has no native flag to suppress
+    them, so this is a post-processing pass shared with the PDF path.
+    """
+    return _parse_office_with_images(
+        source,
+        vlm,
+        suffix=".docx",
+        include_tables=include_tables,
+        deadline=deadline,
+    )
+
+
+def parse_pptx_with_images(
+    source: str | Path | bytes,
+    vlm: VLM,
+    *,
+    include_tables: bool = True,
+    deadline: float | None = None,
+) -> ParseResult:
+    """Parse a PPTX into markdown + interpreted embedded pictures.
+
+    Same pipeline and guarantees as :func:`parse_docx_with_images`. The
+    markdown carries markitdown's ``<!-- Slide number: N -->`` markers
+    and slide titles as ``#`` headings, so slide-aware chunkers can key
+    on them.
+
+    Only *embedded picture files* are extracted and interpreted —
+    shapes, SmartArt and other content drawn natively in PowerPoint
+    have no image payload on this path (their text fragments still
+    appear in the markdown; charts come out as data tables). For decks
+    where drawn diagrams matter, prefer the OCR path
+    (``parse_with_images(..., backend=Mistral())``), which rasterises
+    each slide.
+    """
+    return _parse_office_with_images(
+        source,
+        vlm,
+        suffix=".pptx",
+        include_tables=include_tables,
+        deadline=deadline,
+    )