everalgo-parser 0.1.0__py3-none-any.whl

everalgo/parser/document.py

@@ -0,0 +1,428 @@
+"""Document parser — handles PDF / HTML / EMAIL / Office modalities.
+
+Per ``AGENTS.md`` and the engineering alignment for the parser migration, the
+``document`` submodule covers every non-image / non-audio file shape:
+
+- ``Modality.PDF`` — sent as a single ``application/pdf`` data URI to the
+  multimodal LLM (mirrors the path used in
+  ``evermemos-multimodal/src/parser/pdf/gemini_parser.py``).
+- ``Modality.HTML`` — bs4-cleaned (``_utils.clean_html_for_llm``) before
+  sending the structured HTML to the LLM with the HTML prompt.
+- ``Modality.EMAIL`` — pure-python ``email`` stdlib parsing; when inline
+  images are attached and an ``LLMClient`` is available, each image is
+  OCR'd via ``image.aparse`` and the result substitutes the original
+  ``<img src="cid:...">`` references (now ``[image:N]`` placeholders).
+- ``Modality.DOCUMENT`` — Office / iWork / ODF; LibreOffice subprocess to
+  convert to PDF, then reuse the PDF path. Requires ``soffice`` on PATH.
+
+This module is stateless: callers hydrate ``RawFile.content`` upstream and
+pass it in. Retry, rate-limit, fallback are caller / deployment concerns.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import email
+import email.policy
+import logging
+import re
+import shutil
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from asgiref.sync import async_to_sync
+
+from everalgo.llm import ChatMessage, LLMClient, TextPart, image_url_part_from_bytes
+from everalgo.parser._utils import clean_html_content, clean_html_for_llm
+from everalgo.parser.prompts.en import PROMPT_FOR_FILE, PROMPT_FOR_HTML, PROMPT_FOR_PICTURE
+from everalgo.types import Modality, ParsedContent, RawFile, get_modality
+
+if TYPE_CHECKING:
+    from email.message import EmailMessage
+
+__all__ = ["aparse", "parse"]
+
+logger = logging.getLogger(__name__)
+
+
+_PDF_MIME = "application/pdf"
+_HTML_MAX_INPUT_CHARS = 1_000_000
+_MACOS_SOFFICE = "/Applications/LibreOffice.app/Contents/MacOS/soffice"
+
+# Verbatim from ``evermemos-multimodal/src/parser/email/eml_parser.py``:
+# inline image OCR caps at 8K tokens (single-image scope, no need for the
+# 32K merge budget used by the long-image stitcher).
+_INLINE_OCR_MAX_TOKENS = 8_000
+_INLINE_IMAGE_MIMETYPES = frozenset(
+    {
+        "image/png",
+        "image/jpeg",
+        "image/jpg",
+        "image/webp",
+        "image/bmp",
+        "image/tiff",
+        "image/svg+xml",
+    }
+)
+_MIME_TO_EXTENSION = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/webp": "webp",
+    "image/bmp": "bmp",
+    "image/tiff": "tiff",
+    "image/svg+xml": "svg",
+}
+
+
+async def aparse(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
+    """Parse a document-shaped ``RawFile`` into ``ParsedContent``."""
+    if not raw_file.content:
+        raise ValueError("RawFile.content is empty; cannot parse document")
+
+    modality = get_modality(raw_file.extension)
+    if modality is Modality.PDF:
+        return await _aparse_pdf(raw_file, llm=llm)
+    if modality is Modality.HTML:
+        return await _aparse_html(raw_file, llm=llm)
+    if modality is Modality.EMAIL:
+        return await _aparse_email(raw_file, llm=llm)
+    if modality is Modality.DOCUMENT:
+        return await _aparse_office(raw_file, llm=llm)
+    raise ValueError(f"document.aparse does not handle modality {modality.value!r} (extension={raw_file.extension!r})")
+
+
+parse = async_to_sync(aparse)
+"""Sync bridge for non-event-loop callers (CLI scripts, plain unit tests)."""
+
+
+# ---- per-modality handlers (private) ----
+
+
+async def _aparse_pdf(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
+    """PDF → ``ParsedContent`` via a single multimodal LLM call."""
+    message = ChatMessage(
+        role="user",
+        content=[
+            TextPart(text=PROMPT_FOR_FILE),
+            image_url_part_from_bytes(raw_file.content, _PDF_MIME),
+        ],
+    )
+    logger.debug("parsing PDF, bytes=%d", len(raw_file.content))
+    response = await llm.chat([message])
+    return ParsedContent(
+        text=response.content,
+        modality=Modality.PDF,
+        mime=raw_file.mime or _PDF_MIME,
+        metadata={
+            "model": response.model,
+            "finish_reason": response.finish_reason,
+        },
+    )
+
+
+async def _aparse_html(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
+    """HTML → ``ParsedContent`` via bs4 cleanup + LLM extraction."""
+    html_text = _decode_bytes(raw_file.content)
+    cleaned = clean_html_for_llm(html_text)
+    if not cleaned:
+        logger.warning("HTML content is empty after cleaning")
+        return ParsedContent(
+            text="",
+            modality=Modality.HTML,
+            mime=raw_file.mime or "text/html",
+            metadata={"warning": "empty after html cleanup"},
+        )
+    if len(cleaned) > _HTML_MAX_INPUT_CHARS:
+        logger.warning("HTML truncated from %d to %d chars", len(cleaned), _HTML_MAX_INPUT_CHARS)
+        cleaned = cleaned[:_HTML_MAX_INPUT_CHARS]
+
+    message = ChatMessage(
+        role="user",
+        content=[TextPart(text=f"{PROMPT_FOR_HTML}\n\n---\n{cleaned}")],
+    )
+    logger.debug("parsing HTML, raw_chars=%d cleaned_chars=%d", len(html_text), len(cleaned))
+    response = await llm.chat([message])
+    return ParsedContent(
+        text=response.content,
+        modality=Modality.HTML,
+        mime=raw_file.mime or "text/html",
+        metadata={
+            "model": response.model,
+            "finish_reason": response.finish_reason,
+            "raw_chars": len(html_text),
+            "cleaned_chars": len(cleaned),
+        },
+    )
+
+
+async def _aparse_email(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
+    """EML → ``ParsedContent`` via stdlib ``email`` + inline-image OCR.
+
+    Mirrors evermemos-multimodal/src/parser/email/eml_parser.py:
+
+    1. Extract headers.
+    2. Collect inline images (Content-ID → bytes).
+    3. Extract body: prefer ``text/plain`` when there are no cid images
+       (cheaper); prefer ``text/html`` when cid images are present so we can
+       substitute placeholders at their original positions.
+    4. If inline images exist, OCR each one via the LLM and substitute the placeholders.
+       Images without a cid get appended at end.
+    """
+    msg = email.message_from_bytes(raw_file.content, policy=email.policy.default)
+    parts: list[str] = []
+
+    headers = _extract_email_headers(msg)
+    if headers:
+        parts.append(headers)
+
+    inline_images = _collect_inline_images(msg)
+    has_cid = any(cid for cid, _, _, _ in inline_images.values())
+    body = _extract_email_body(msg, inline_images, prefer_html=has_cid)
+    if body:
+        parts.append(body)
+
+    metadata: dict[str, object] = {
+        "from": msg.get("From", ""),
+        "subject": msg.get("Subject", ""),
+        "inline_image_count": len(inline_images),
+    }
+
+    if not inline_images:
+        return ParsedContent(
+            text="\n\n".join(parts),
+            modality=Modality.EMAIL,
+            mime=raw_file.mime or "message/rfc822",
+            metadata=metadata,
+        )
+
+    ocr_results = await _ocr_inline_images(inline_images, client=llm)
+    result = "\n\n".join(parts)
+    appended: list[str] = []
+    for idx, ocr_text in ocr_results.items():
+        placeholder = f"[image:{idx}]"
+        if placeholder in result:
+            result = result.replace(placeholder, ocr_text)
+        else:
+            appended.append(ocr_text)
+    if appended:
+        result = result + "\n\n" + "\n\n".join(appended)
+
+    metadata["inline_image_ocr"] = "ok"
+    return ParsedContent(
+        text=result,
+        modality=Modality.EMAIL,
+        mime=raw_file.mime or "message/rfc822",
+        metadata=metadata,
+    )
+
+
+async def _aparse_office(
+    raw_file: RawFile, *, llm: LLMClient
+) -> ParsedContent:  # pragma: no cover  (libreoffice binary, not in CI)
+    """Office docs (docx / xlsx / pptx / ...) → convert to PDF → reuse PDF path."""
+    soffice = _find_soffice()  # pragma: no cover
+    pdf_bytes = await _convert_to_pdf_via_soffice(raw_file.content, raw_file.extension, soffice)  # pragma: no cover
+    if not pdf_bytes:  # pragma: no cover
+        return ParsedContent(  # pragma: no cover
+            text="",
+            modality=Modality.DOCUMENT,
+            mime=raw_file.mime,
+            metadata={"warning": "LibreOffice conversion returned empty bytes"},
+        )
+
+    message = ChatMessage(  # pragma: no cover
+        role="user",
+        content=[
+            TextPart(text=PROMPT_FOR_FILE),
+            image_url_part_from_bytes(pdf_bytes, _PDF_MIME),
+        ],
+    )
+    logger.debug(  # pragma: no cover
+        "parsing Office doc extension=%s converted_pdf_bytes=%d",
+        raw_file.extension,
+        len(pdf_bytes),
+    )
+    response = await llm.chat([message])  # pragma: no cover
+    return ParsedContent(  # pragma: no cover
+        text=response.content,
+        modality=Modality.DOCUMENT,
+        mime=raw_file.mime,
+        metadata={
+            "model": response.model,
+            "finish_reason": response.finish_reason,
+            "intermediate_pdf_bytes": len(pdf_bytes),
+        },
+    )
+
+
+# ---- email helpers ----
+
+
+def _extract_email_headers(msg: EmailMessage) -> str:
+    lines = []
+    for field in ("Subject", "From", "To", "Cc", "Date"):
+        value = msg.get(field)
+        if value:
+            lines.append(f"{field}: {value}")
+    return "\n".join(lines)
+
+
+def _collect_inline_images(msg: EmailMessage) -> dict[int, tuple[str, bytes, str, str]]:
+    """Return ``{idx: (cid, image_bytes, mime, filename)}`` for inline images."""
+    images: dict[int, tuple[str, bytes, str, str]] = {}
+    idx = 1
+    for part in msg.walk():
+        content_type = part.get_content_type()
+        if content_type not in _INLINE_IMAGE_MIMETYPES:
+            continue
+        image_bytes = part.get_content()
+        if not isinstance(image_bytes, bytes) or not image_bytes:
+            continue
+        cid = part.get("Content-ID", "")
+        if cid:
+            cid = cid.strip("<>")
+        filename = part.get_filename() or f"image_{idx}"
+        images[idx] = (cid, image_bytes, content_type, filename)
+        idx += 1
+    return images
+
+
+def _extract_email_body(
+    msg: EmailMessage,
+    inline_images: dict[int, tuple[str, bytes, str, str]],
+    *,
+    prefer_html: bool = False,
+) -> str:
+    """Extract body text, optionally replacing ``<img cid:>`` with placeholders."""
+    if not prefer_html:
+        body = msg.get_body(preferencelist=("plain",))
+        if body is not None:
+            content = body.get_content()
+            if isinstance(content, str) and content.strip():
+                return content.strip()
+
+    body = msg.get_body(preferencelist=("html",))
+    if body is not None:
+        content = body.get_content()
+        if isinstance(content, str) and content.strip():
+            cid_to_placeholder = {cid: f"[image:{idx}]" for idx, (cid, _, _, _) in inline_images.items() if cid}
+            html_with_placeholders = _replace_cid_images(content, cid_to_placeholder)
+            cleaned = clean_html_content(html_with_placeholders)
+            if cleaned:
+                return cleaned
+
+    if prefer_html:
+        # Fallback: prefer-html mode but HTML was empty/missing.
+        body = msg.get_body(preferencelist=("plain",))
+        if body is not None:
+            content = body.get_content()
+            if isinstance(content, str) and content.strip():
+                return content.strip()
+
+    return ""
+
+
+def _replace_cid_images(html: str, cid_to_placeholder: dict[str, str]) -> str:
+    """Substitute ``<img src="cid:xxx">`` references with ``[image:N]`` markers."""
+    if not cid_to_placeholder:
+        return html
+
+    def _replace_match(match: re.Match[str]) -> str:
+        cid = match.group(1)
+        return cid_to_placeholder.get(cid, match.group(0))
+
+    return re.sub(
+        r'<img\b[^>]*\bsrc=["\']cid:([^"\']+)["\'][^>]*/?>',
+        _replace_match,
+        html,
+        flags=re.IGNORECASE,
+    )
+
+
+async def _ocr_inline_images(
+    inline_images: dict[int, tuple[str, bytes, str, str]],
+    *,
+    client: LLMClient,
+) -> dict[int, str]:
+    """OCR every inline image with the same client; wrap results in markers."""
+    results: dict[int, str] = {}
+    for idx, (_, image_bytes, mime_type, filename) in inline_images.items():
+        logger.debug("OCR inline email image: %s (%s)", filename, mime_type)
+        try:
+            message = ChatMessage(
+                role="user",
+                content=[
+                    TextPart(text=PROMPT_FOR_PICTURE),
+                    image_url_part_from_bytes(image_bytes, mime_type),
+                ],
+            )
+            response = await client.chat([message], max_tokens=_INLINE_OCR_MAX_TOKENS)
+            text = (response.content or "").strip()
+            if text:
+                results[idx] = f"[image: {filename}, content follows]\n{text}\n[end of image]"
+            else:
+                results[idx] = f"[image: {filename}, no content recognised]"
+        except Exception as exc:
+            # Best-effort per-image: a single OCR failure should not abort the
+            # whole email parse — log and continue with a placeholder marker.
+            logger.warning("OCR failed for inline image %s: %s", filename, exc)
+            results[idx] = f"[image: {filename}, OCR failed]"
+    return results
+
+
+# ---- generic helpers ----
+
+
+def _decode_bytes(content: bytes) -> str:
+    """Try several encodings; fall back to utf-8 with replace."""
+    for encoding in ("utf-8", "gbk", "gb2312", "latin-1"):
+        try:
+            return content.decode(encoding)
+        except (UnicodeDecodeError, LookupError):
+            continue
+    return content.decode("utf-8", errors="replace")
+
+
+def _find_soffice() -> str:  # pragma: no cover  (libreoffice binary, not in CI)
+    """Locate the LibreOffice ``soffice`` binary."""
+    path = shutil.which("soffice")  # pragma: no cover
+    if path:  # pragma: no cover
+        return path  # pragma: no cover
+    if Path(_MACOS_SOFFICE).exists():  # pragma: no cover
+        return _MACOS_SOFFICE  # pragma: no cover
+    raise RuntimeError(  # pragma: no cover
+        "LibreOffice not found on PATH. Install it: "
+        "macOS: `brew install --cask libreoffice`, "
+        "Linux: `apt install libreoffice`."
+    )
+
+
+async def _convert_to_pdf_via_soffice(
+    content: bytes, extension: str, soffice: str
+) -> bytes:  # pragma: no cover  (libreoffice binary, not in CI)
+    """Run LibreOffice headless to convert bytes → PDF bytes."""
+    with tempfile.TemporaryDirectory() as tmpdir:  # pragma: no cover
+        in_path = Path(tmpdir) / f"input.{extension}"  # pragma: no cover
+        in_path.write_bytes(content)  # pragma: no cover
+        proc = await asyncio.create_subprocess_exec(  # pragma: no cover
+            soffice,
+            "--headless",
+            "--convert-to",
+            "pdf",
+            "--outdir",
+            tmpdir,
+            str(in_path),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        _, stderr = await proc.communicate()  # pragma: no cover
+        if proc.returncode != 0:  # pragma: no cover
+            raise RuntimeError(  # pragma: no cover
+                f"LibreOffice conversion failed (code={proc.returncode}): {stderr.decode(errors='replace')[:500]}"
+            )
+        pdf_path = Path(tmpdir) / "input.pdf"  # pragma: no cover
+        if not pdf_path.exists():  # pragma: no cover
+            return b""  # pragma: no cover
+        return pdf_path.read_bytes()  # pragma: no cover

everalgo/parser/image.py

@@ -0,0 +1,266 @@
+"""Image parser — multimodal LLM OCR with tall-image splitting.
+
+Mirrors ``evermemos-multimodal/src/parser/image/gemini_parser.py``:
+
+- Normal-ratio images go through a single LLM call.
+- Tall screenshots (height/width > 10) are split into overlapping slices
+  via ``_utils.split_image_with_overlap``; each slice is OCR'd independently
+  and the per-slice results are merged with a second LLM call using
+  ``PROMPT_FOR_MERGE`` to dedupe the overlap regions.
+- BMP / TIFF are transcoded to PNG via Pillow (Gemini does not accept those
+  MIMEs natively).
+- SVG is rasterised to PNG via ``cairosvg`` (optional extra ``everalgo-parser[svg]``).
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+from typing import TYPE_CHECKING
+
+from asgiref.sync import async_to_sync
+from PIL import Image
+
+from everalgo.llm import ChatMessage, LLMClient, TextPart, image_url_part_from_bytes
+from everalgo.parser._utils import check_aspect_ratio, split_image_with_overlap
+from everalgo.parser.prompts.en import PROMPT_FOR_MERGE, PROMPT_FOR_PICTURE
+from everalgo.types import Modality, ParsedContent
+
+if TYPE_CHECKING:
+    from everalgo.types import RawFile
+
+__all__ = ["aparse", "parse"]
+
+logger = logging.getLogger(__name__)
+
+
+_MIME_MAP: dict[str, str] = {
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "webp": "image/webp",
+    "bmp": "image/bmp",
+    "svg": "image/svg+xml",
+    "tif": "image/tiff",
+    "tiff": "image/tiff",
+}
+
+# Formats Gemini multimodal does not accept natively. We transcode to PNG via
+# Pillow before sending.
+_TRANSCODE_TO_PNG: frozenset[str] = frozenset({"bmp", "tif", "tiff"})
+
+# SVG is vector; rasterise via cairosvg before sending.
+_SVG_EXTENSIONS: frozenset[str] = frozenset({"svg"})
+
+_TALL_IMAGE_RATIO_THRESHOLD = 10.0
+
+# Token budgets — verbatim from
+# ``evermemos-multimodal/src/parser/image/gemini_parser.py``. Per-slice OCR
+# caps at 8K; the merge step gets 4x because it joins multiple OCR'd chunks
+# and the merged text is longer than any individual slice.
+_MAX_OCR_OUTPUT_TOKENS = 8_000
+_MAX_MERGE_OUTPUT_TOKENS = 32_000
+
+
+async def aparse(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
+    """Parse an image ``RawFile`` into ``ParsedContent`` via multimodal LLM.
+
+    Tall images (height/width > 10) are split into overlapping vertical
+    slices and OCR'd in parallel; per-slice results are then merged with a
+    second LLM call. Normal-ratio images go through a single OCR call.
+    """
+    if not raw_file.content:
+        raise ValueError("RawFile.content is empty; cannot parse image")
+
+    extension = raw_file.extension.lower().lstrip(".")
+    mime = _MIME_MAP.get(extension)
+    if mime is None:
+        raise ValueError(
+            f"image.aparse: unsupported image extension {raw_file.extension!r}. Supported: {sorted(_MIME_MAP)}"
+        )
+
+    payload_bytes = raw_file.content
+    payload_mime = mime
+    if extension in _TRANSCODE_TO_PNG:
+        payload_bytes = _transcode_to_png(raw_file.content)
+        payload_mime = "image/png"
+    elif extension in _SVG_EXTENSIONS:
+        payload_bytes = _rasterise_svg_to_png(raw_file.content)
+        payload_mime = "image/png"
+
+    needs_split, ratio = check_aspect_ratio(payload_bytes, max_ratio=_TALL_IMAGE_RATIO_THRESHOLD)
+    if needs_split:
+        return await _aparse_tall(payload_bytes, payload_mime, raw_file, ratio, llm)
+    return await _aparse_single(payload_bytes, payload_mime, raw_file, llm)
+
+
+parse = async_to_sync(aparse)
+"""Sync bridge — see ``document.parse`` for details."""
+
+
+# ---- internals ----
+
+
+async def _aparse_single(
+    payload_bytes: bytes,
+    payload_mime: str,
+    raw_file: RawFile,
+    client: LLMClient,
+) -> ParsedContent:
+    """Single-shot OCR call for normal-ratio images."""
+    message = ChatMessage(
+        role="user",
+        content=[
+            TextPart(text=PROMPT_FOR_PICTURE),
+            image_url_part_from_bytes(payload_bytes, payload_mime),
+        ],
+    )
+    logger.debug("parsing image (single) bytes=%d mime=%s", len(payload_bytes), payload_mime)
+    response = await client.chat([message], max_tokens=_MAX_OCR_OUTPUT_TOKENS)
+    return ParsedContent(
+        text=response.content,
+        modality=Modality.IMAGE,
+        mime=raw_file.mime or payload_mime,
+        metadata={
+            "model": response.model,
+            "finish_reason": response.finish_reason,
+            "tall_image_parts": 1,
+        },
+    )
+
+
+async def _aparse_tall(
+    payload_bytes: bytes,
+    payload_mime: str,
+    raw_file: RawFile,
+    ratio: float,
+    client: LLMClient,
+) -> ParsedContent:
+    r"""Split-then-merge OCR for tall screenshots.
+
+    Mirrors ``evermemos-multimodal/src/parser/image/base.py:parse`` +
+    ``gemini_parser._merge_parts``:
+
+    1. Split into N overlapping vertical slices.
+    2. OCR each slice; **drop empty results** so the merge step sees only
+       real text (an all-empty slice from a blank PDF region would otherwise
+       confuse the merge LLM).
+    3. ≤ 1 non-empty result → return that single text (or empty string when
+       all slices came back blank).
+    4. Otherwise call the merge LLM with ``temperature=0.0`` and a 4x token
+       cap; on merge failure fall back to a deterministic ``\n\n`` join so
+       the caller at least gets the raw OCR rather than an exception.
+    """
+    parts = split_image_with_overlap(payload_bytes, max_ratio=_TALL_IMAGE_RATIO_THRESHOLD)
+    logger.info("tall image detected: ratio=%.2f, splitting into %d parts", ratio, len(parts))
+
+    ocr_results: list[str] = []
+    last_response = None
+    for i, part_bytes in enumerate(parts, 1):
+        message = ChatMessage(
+            role="user",
+            content=[
+                TextPart(text=PROMPT_FOR_PICTURE),
+                image_url_part_from_bytes(part_bytes, payload_mime),
+            ],
+        )
+        logger.debug("OCR tall image part %d/%d, bytes=%d", i, len(parts), len(part_bytes))
+        resp = await client.chat([message], max_tokens=_MAX_OCR_OUTPUT_TOKENS)
+        last_response = resp
+        # Drop empty per-slice OCR so merge prompt isn't padded with blank parts.
+        text = (resp.content or "").strip()
+        if text:
+            ocr_results.append(text)
+
+    # All slices came back empty — return an empty ParsedContent rather than
+    # call the merge LLM with no content (matches original ``parse()`` bailout).
+    if not ocr_results:
+        assert last_response is not None  # at least one chat() call was made above
+        return ParsedContent(
+            text="",
+            modality=Modality.IMAGE,
+            mime=raw_file.mime or payload_mime,
+            metadata={
+                "model": last_response.model,
+                "finish_reason": last_response.finish_reason,
+                "tall_image_parts": len(parts),
+                "aspect_ratio": round(ratio, 2),
+                "warning": "all OCR slices returned empty",
+            },
+        )
+
+    # Single non-empty result — skip the merge LLM, return as-is (saves 1 call).
+    if len(ocr_results) == 1:
+        assert last_response is not None
+        return ParsedContent(
+            text=ocr_results[0],
+            modality=Modality.IMAGE,
+            mime=raw_file.mime or payload_mime,
+            metadata={
+                "model": last_response.model,
+                "finish_reason": last_response.finish_reason,
+                "tall_image_parts": len(parts),
+                "aspect_ratio": round(ratio, 2),
+            },
+        )
+
+    # Multi-slice merge via LLM. Algorithm-layer fallback (NOT engineering
+    # retry/fallback per ADR-012): if the merge call itself throws, fall back
+    # to a deterministic join so the caller never loses the raw OCR.
+    parts_text = "\n\n".join(f"=== Part {i} ===\n{p}" for i, p in enumerate(ocr_results, 1))
+    merge_prompt = PROMPT_FOR_MERGE.replace("{parts_text}", parts_text)
+    merge_message = ChatMessage(role="user", content=merge_prompt)
+    logger.debug("merging %d OCR parts", len(ocr_results))
+    merge_fallback_used = False
+    try:
+        merge_resp = await client.chat(
+            [merge_message],
+            temperature=0.0,
+            max_tokens=_MAX_MERGE_OUTPUT_TOKENS,
+        )
+        merged_text = merge_resp.content or "\n\n".join(ocr_results)
+        if not merge_resp.content:
+            merge_fallback_used = True
+        last_response = merge_resp
+    except Exception as exc:
+        logger.warning("LLM merge of tall-image OCR parts failed (%s); falling back to deterministic join", exc)
+        merged_text = "\n\n".join(ocr_results)
+        merge_fallback_used = True
+
+    assert last_response is not None, "tall-image OCR produced no responses"
+    metadata: dict[str, object] = {
+        "model": last_response.model,
+        "finish_reason": last_response.finish_reason,
+        "tall_image_parts": len(parts),
+        "aspect_ratio": round(ratio, 2),
+    }
+    if merge_fallback_used:
+        metadata["merge_fallback"] = "deterministic_join"
+    return ParsedContent(
+        text=merged_text,
+        modality=Modality.IMAGE,
+        mime=raw_file.mime or payload_mime,
+        metadata=metadata,
+    )
+
+
+def _transcode_to_png(data: bytes) -> bytes:
+    """Decode arbitrary Pillow-readable bytes and re-encode as PNG."""
+    with Image.open(io.BytesIO(data)) as src:
+        img: Image.Image = (
+            src.convert("RGBA" if "A" in src.mode else "RGB") if src.mode not in ("RGB", "RGBA") else src.copy()
+        )
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        return buf.getvalue()
+
+
+def _rasterise_svg_to_png(data: bytes) -> bytes:  # pragma: no cover  (cairosvg native, not in CI)
+    """Rasterise SVG bytes to PNG via cairosvg (optional extra)."""
+    try:
+        import cairosvg  # type: ignore[import-not-found]  # pragma: no cover
+    except ImportError as exc:  # pragma: no cover
+        raise RuntimeError(  # pragma: no cover
+            "SVG support requires the optional `cairosvg` dependency. Install via: pip install 'everalgo-parser[svg]'"
+        ) from exc
+    return cairosvg.svg2png(bytestring=data)  # type: ignore[no-any-return]  # pragma: no cover