docmd-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/ARCHITECTURE.md

@@ -3,6 +3,31 @@
 ## The pitch (keep this pinned above your desk)
 We are not competing on conversion quality. We are selling **"hit an endpoint, get clean Markdown back"** — no Python env, no 8GB+ RAM, no GPU, no dependency hell. The open-source core proves the engine works and builds trust. The hosted API sells convenience.
 
+## Real dependency gap found by testing (2026-09-18)
+The pitch above says "no dependency hell." That held for text-layer PDFs, DOCX, and
+PPTX when actually tested against real downloaded documents (an arXiv paper, an IMF
+report). It did **not** hold for OCR: Marker's current recognition model (used for
+both scanned-PDF OCR and equation recognition) is a VLM served through either `vllm`
+or llama.cpp's `llama-server` binary - no plain-transformers/CPU fallback exists in
+this version. Neither ships via pip, so `pip install docmd-cli[full]` alone cannot
+actually OCR a scanned document or handle a PDF with equations, despite the README
+previously implying "OCR - bundled by Marker, free" meant it worked out of the box.
+
+Confirmed via a real test: converting a genuinely scanned PDF (downloaded from
+archive.org) raised a missing-binary error on this dev machine (no Homebrew). Fixed
+two ways: (1) a real fix - download a prebuilt `llama-server` binary directly from
+llama.cpp's GitHub releases (no package manager needed) and set `LLAMA_CPP_BINARY`,
+which then produced correct real OCR output; (2) a docmd fix - a dedicated
+`MissingSystemDependencyError` with install instructions instead of a raw stack trace
+when the binary is missing (see `docmd/errors.py`).
+
+**Implications to carry into Stage 2/3 (`api/`)**: the hosted API's Docker image
+does not currently install `llama-server` either - meaning a customer uploading a
+scanned PDF or an equation-heavy document to the live API would hit this same error
+today. This needs a fix in `docmd-api`'s Dockerfile before OCR can be honestly
+advertised as working end-to-end there. Not yet fixed as of this note - flagged here
+so it isn't lost.
+
 ## Positioning risk (checked 2026-09-18)
 Marker's *code* is Apache-2.0 (no restriction). Marker's *model weights* use a modified
 Open RAIL-M license: free for research, personal use, and organizations under $5M in
@@ -128,7 +153,9 @@ Treat this folder as the actual differentiator. A thin wrapper is a weekend proj
 
 - `pip install docmd-cli` -> core PDF conversion (Marker bundles OCR here already; there is
   no separate lean/no-OCR base install, since Marker's own base dependencies include
-  `surya-ocr`)
+  `surya-ocr`) - but actually *running* OCR (or equation recognition) on top of that
+  also needs the `llama-server` native binary, which no `pip install` variant can
+  provide - see "Real dependency gap found by testing" above
 - `pip install docmd-cli[full]` -> adds DOCX/PPTX/EPUB/XLSX support via Marker's `full` extra
 
 ## License clarity

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docmd-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Convert PDFs, DOCX, and PPTX to clean, structure-preserving Markdown.
 Project-URL: Homepage, https://github.com/taherzribi/docmd
 Project-URL: Issues, https://github.com/taherzribi/docmd/issues
@@ -67,7 +67,7 @@ core, usable standalone today.
 | Input | Output |
 |---|---|
 | PDF (text-based) | Markdown with preserved headings, lists, tables |
-| PDF (scanned) | Markdown via OCR — bundled by Marker, free |
+| PDF (scanned) | Markdown via OCR — bundled by Marker, free, but needs [one extra native binary](#ocr-and-equations-need-one-native-binary) |
 | DOCX | Markdown with formatting preserved (`pip install docmd-cli[full]`) |
 | PPTX | Markdown, one section per slide (`pip install docmd-cli[full]`) |
 
@@ -107,12 +107,75 @@ native Pango/GObject/Cairo libraries, which `pip` cannot install for you:
 # macOS
 brew install pango
 
-# Debian/Ubuntu
+# Debian/Ubuntu (24.04 and older)
 sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
+
+# Debian trixie (13) and newer: libgdk-pixbuf2.0-0 was renamed
+sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 libffi-dev shared-mime-info
 ```
 
 PDF conversion (the base install) does not need this.
 
+## OCR and equations need one native binary
+
+Found by testing docmd against a real scanned document, not documented anywhere
+upstream at the time of writing: Marker's current OCR and equation-recognition model
+is a vision-language model served through either `vllm` (GPU/Linux-oriented) or
+[llama.cpp](https://github.com/ggml-org/llama.cpp)'s `llama-server` binary - there is
+no plain-CPU/transformers fallback. `pip install docmd-cli` cannot provide either one,
+since neither ships as a normal Python wheel.
+
+This only matters for **scanned PDFs** (no embedded text layer) and PDFs with
+**equations** - a normal text-layer PDF never touches this code path, and everything
+else in this README works with just `pip install`.
+
+```bash
+# macOS / Linux with Homebrew
+brew install llama.cpp
+
+# No Homebrew: download a prebuilt binary directly, no package manager needed
+# (pick the archive matching your OS/arch from the releases page)
+curl -LO https://github.com/ggml-org/llama.cpp/releases/latest/download/llama-<version>-bin-macos-arm64.tar.gz
+tar xzf llama-<version>-bin-macos-arm64.tar.gz
+export LLAMA_CPP_BINARY=$PWD/llama-<version>/llama-server
+```
+
+Without it, converting a scanned PDF or one with equations raises a
+`MissingSystemDependencyError` with these same instructions - not a raw stack trace.
+First real OCR run also downloads the model's GGUF weights from Hugging Face
+(a few GB), separate from the PyTorch weights Marker already downloaded.
+
+## Image handling
+
+Images default to a text placeholder (`*[... omitted]*`) - no binary data, nothing to
+resolve, safe for RAG chunking:
+
+```python
+markdown = convert("report.pdf")  # image_mode="placeholder" by default
+```
+
+To keep real image links instead, use `image_mode="alt-text"` and pass `output_dir` so
+the image files actually get saved somewhere the links can resolve to:
+
+```python
+from docmd import convert_document
+from docmd.config import ConvertConfig
+
+result = convert_document(
+    "report.pdf",
+    config=ConvertConfig(image_mode="alt-text"),
+    output_dir="output/",
+)
+```
+
+From the CLI, `--image-dir` defaults to the output file's directory when `-o` is given:
+
+```bash
+docmd convert report.pdf -o output/report.md --image-mode alt-text
+```
+
+`image_mode="skip"` drops images entirely - no placeholder, no files.
+
 ## How it works
 
 `docmd` wraps [Marker](https://github.com/datalab-to/marker) with sane defaults and a

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/README.md

@@ -40,7 +40,7 @@ core, usable standalone today.
 | Input | Output |
 |---|---|
 | PDF (text-based) | Markdown with preserved headings, lists, tables |
-| PDF (scanned) | Markdown via OCR — bundled by Marker, free |
+| PDF (scanned) | Markdown via OCR — bundled by Marker, free, but needs [one extra native binary](#ocr-and-equations-need-one-native-binary) |
 | DOCX | Markdown with formatting preserved (`pip install docmd-cli[full]`) |
 | PPTX | Markdown, one section per slide (`pip install docmd-cli[full]`) |
 
@@ -80,12 +80,75 @@ native Pango/GObject/Cairo libraries, which `pip` cannot install for you:
 # macOS
 brew install pango
 
-# Debian/Ubuntu
+# Debian/Ubuntu (24.04 and older)
 sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
+
+# Debian trixie (13) and newer: libgdk-pixbuf2.0-0 was renamed
+sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 libffi-dev shared-mime-info
 ```
 
 PDF conversion (the base install) does not need this.
 
+## OCR and equations need one native binary
+
+Found by testing docmd against a real scanned document, not documented anywhere
+upstream at the time of writing: Marker's current OCR and equation-recognition model
+is a vision-language model served through either `vllm` (GPU/Linux-oriented) or
+[llama.cpp](https://github.com/ggml-org/llama.cpp)'s `llama-server` binary - there is
+no plain-CPU/transformers fallback. `pip install docmd-cli` cannot provide either one,
+since neither ships as a normal Python wheel.
+
+This only matters for **scanned PDFs** (no embedded text layer) and PDFs with
+**equations** - a normal text-layer PDF never touches this code path, and everything
+else in this README works with just `pip install`.
+
+```bash
+# macOS / Linux with Homebrew
+brew install llama.cpp
+
+# No Homebrew: download a prebuilt binary directly, no package manager needed
+# (pick the archive matching your OS/arch from the releases page)
+curl -LO https://github.com/ggml-org/llama.cpp/releases/latest/download/llama-<version>-bin-macos-arm64.tar.gz
+tar xzf llama-<version>-bin-macos-arm64.tar.gz
+export LLAMA_CPP_BINARY=$PWD/llama-<version>/llama-server
+```
+
+Without it, converting a scanned PDF or one with equations raises a
+`MissingSystemDependencyError` with these same instructions - not a raw stack trace.
+First real OCR run also downloads the model's GGUF weights from Hugging Face
+(a few GB), separate from the PyTorch weights Marker already downloaded.
+
+## Image handling
+
+Images default to a text placeholder (`*[... omitted]*`) - no binary data, nothing to
+resolve, safe for RAG chunking:
+
+```python
+markdown = convert("report.pdf")  # image_mode="placeholder" by default
+```
+
+To keep real image links instead, use `image_mode="alt-text"` and pass `output_dir` so
+the image files actually get saved somewhere the links can resolve to:
+
+```python
+from docmd import convert_document
+from docmd.config import ConvertConfig
+
+result = convert_document(
+    "report.pdf",
+    config=ConvertConfig(image_mode="alt-text"),
+    output_dir="output/",
+)
+```
+
+From the CLI, `--image-dir` defaults to the output file's directory when `-o` is given:
+
+```bash
+docmd convert report.pdf -o output/report.md --image-mode alt-text
+```
+
+`image_mode="skip"` drops images entirely - no placeholder, no files.
+
 ## How it works
 
 `docmd` wraps [Marker](https://github.com/datalab-to/marker) with sane defaults and a

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/docmd/__init__.py

@@ -18,7 +18,7 @@ from docmd.postprocess.image_handling import apply_image_handling
 from docmd.postprocess.table_cleanup import clean_tables
 
 __all__ = ["convert", "convert_document", "ConvertConfig", "ConversionResult"]
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 
 def convert_document(
@@ -26,6 +26,7 @@ def convert_document(
     *,
     filename: str | None = None,
     config: ConvertConfig | None = None,
+    output_dir: str | Path | None = None,
 ) -> ConversionResult:
     """Convert `source` and return the full result (markdown + page count +
     metadata), after docmd's post-processing pass has run.
@@ -33,6 +34,14 @@ def convert_document(
     `source` is either a path to a file, or raw bytes - in which case
     `filename` is required so docmd knows the format (its extension is used
     to pick a converter; the content itself is what gets converted).
+
+    `output_dir`: only meaningful with `config.image_mode == "alt-text"`,
+    which keeps real image links in the output Markdown - those links only
+    resolve if the image files actually exist somewhere, so pass the
+    directory to save them into (typically wherever the output .md file is
+    going). Without it, `alt-text` mode's links point to image filenames
+    that were never written anywhere. `placeholder` (the default) and
+    `skip` modes ignore this - they never reference image files at all.
     """
     config = config or ConvertConfig()
 
@@ -44,11 +53,11 @@ def convert_document(
         try:
             with os.fdopen(fd, "wb") as tmp:
                 tmp.write(source)
-            result = _convert_path(tmp_path, config)
+            result = _convert_path(tmp_path, config, output_dir)
         finally:
             os.unlink(tmp_path)
     else:
-        result = _convert_path(str(source), config)
+        result = _convert_path(str(source), config, output_dir)
 
     return result
 
@@ -58,13 +67,16 @@ def convert(
     *,
     filename: str | None = None,
     config: ConvertConfig | None = None,
+    output_dir: str | Path | None = None,
 ) -> str:
     """Convert `source` (a file path, or bytes + filename) and return the
-    resulting Markdown as a string."""
-    return convert_document(source, filename=filename, config=config).markdown
+    resulting Markdown as a string. See `convert_document` re: `output_dir`."""
+    return convert_document(source, filename=filename, config=config, output_dir=output_dir).markdown
 
 
-def _convert_path(filepath: str, config: ConvertConfig) -> ConversionResult:
+def _convert_path(
+    filepath: str, config: ConvertConfig, output_dir: str | Path | None
+) -> ConversionResult:
     converter = get_converter(filepath)
     result = converter.convert(filepath, config)
 
@@ -73,7 +85,7 @@ def _convert_path(filepath: str, config: ConvertConfig) -> ConversionResult:
         markdown = clean_tables(markdown)
     if config.normalize_headings:
         markdown = normalize_headings(markdown)
-    markdown = apply_image_handling(markdown, result.images, config.image_mode)
+    markdown = apply_image_handling(markdown, result.images, config.image_mode, output_dir)
 
     return ConversionResult(
         markdown=markdown,

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/docmd/cli.py

@@ -47,12 +47,39 @@ def main() -> None:
     show_default=True,
     help="How to represent images in the output.",
 )
-def convert(file: Path, output: Path | None, force_ocr: bool, use_llm: bool, image_mode: str) -> None:
+@click.option(
+    "--image-dir",
+    "image_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Where to save image files in --image-mode alt-text. Defaults to "
+    "the output file's directory when -o is given; without -o, images "
+    "won't be saved unless this is set explicitly.",
+)
+def convert(
+    file: Path,
+    output: Path | None,
+    force_ocr: bool,
+    use_llm: bool,
+    image_mode: str,
+    image_dir: Path | None,
+) -> None:
     """Convert FILE to Markdown."""
     config = ConvertConfig(force_ocr=force_ocr, use_llm=use_llm, image_mode=image_mode)
 
+    if image_mode == "alt-text" and image_dir is None:
+        if output is not None:
+            image_dir = output.parent
+        else:
+            click.echo(
+                "warning: --image-mode alt-text with no -o/--image-dir - "
+                "image links in the output won't resolve to real files. "
+                "Pass --image-dir to save images somewhere.",
+                err=True,
+            )
+
     try:
-        result = convert_document(str(file), config=config)
+        result = convert_document(str(file), config=config, output_dir=image_dir)
     except DocmdError as exc:
         click.echo(f"error: {exc}", err=True)
         sys.exit(1)

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/docmd/converters/marker_converter.py

@@ -13,7 +13,12 @@ from typing import Any
 
 from docmd.config import ConvertConfig
 from docmd.converters.base import ConversionResult
-from docmd.errors import ConversionError, EncryptedDocumentError, MissingExtraError
+from docmd.errors import (
+    ConversionError,
+    EncryptedDocumentError,
+    MissingExtraError,
+    MissingSystemDependencyError,
+)
 
 # Marker loads its models (a few hundred MB to ~1GB of weights, downloaded
 # from Hugging Face on first use) lazily and caches them at module scope, so
@@ -21,6 +26,11 @@ from docmd.errors import ConversionError, EncryptedDocumentError, MissingExtraEr
 _model_dict: dict[str, Any] | None = None
 
 _PASSWORD_HINTS = ("password", "encrypt")
+# Raised as surya.inference.backends.spawn.SpawnError when OCR/equation
+# recognition needs the llama-server binary and it isn't on PATH - matched
+# by message/type name rather than importing surya's internal exception
+# class, so this doesn't break if that module path moves.
+_MISSING_BINARY_HINTS = ("llama-server", "spawnerror")
 
 
 def _get_model_dict() -> dict[str, Any]:
@@ -39,6 +49,18 @@ def _build_config_dict(config: ConvertConfig):
         "output_format": "markdown",
         "force_ocr": config.force_ocr,
         "use_llm": config.use_llm,
+        # Marker's own default (4) spins up a multiprocessing.ProcessPoolExecutor
+        # for page-text extraction on any sufficiently multi-page PDF. On
+        # spawn-based platforms (macOS, Windows) that crashes with
+        # "An attempt has been made to start a new process before the
+        # current process has finished its bootstrapping phase" whenever the
+        # caller isn't wrapped in `if __name__ == "__main__":` - an easy trap
+        # for a library used from a plain script, a notebook, or a web
+        # server's request handler. Marker's own bundled server.py sets this
+        # to 1 for exactly this reason; docmd does the same as a library
+        # default, trading a bit of extraction parallelism for not crashing
+        # on arbitrary callers.
+        "pdftext_workers": 1,
     }
     if config.image_mode == "skip":
         options["disable_image_extraction"] = True
@@ -71,8 +93,11 @@ class MarkerConverter:
             rendered = converter(filepath)
         except Exception as exc:
             message = str(exc).lower()
+            exc_type_name = type(exc).__name__.lower()
             if any(hint in message for hint in _PASSWORD_HINTS):
                 raise EncryptedDocumentError() from exc
+            if any(hint in message or hint in exc_type_name for hint in _MISSING_BINARY_HINTS):
+                raise MissingSystemDependencyError(str(exc)) from exc
             raise ConversionError(
                 f"Marker failed to convert '{filepath}': {exc}", cause=exc
             ) from exc

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/docmd/errors.py

@@ -35,6 +35,30 @@ class MissingExtraError(DocmdError):
         )
 
 
+class MissingSystemDependencyError(DocmdError):
+    """Raised when Marker's OCR/equation recognition needs a native binary
+    that isn't installed - not a pip package, so `pip install docmd[full]`
+    can't provide it. See ARCHITECTURE.md "OCR and equation recognition need
+    a native binary" for why this exists."""
+
+    def __init__(self, detail: str) -> None:
+        super().__init__(
+            "OCR/equation recognition needs the `llama-server` binary from "
+            "llama.cpp, which pip cannot install. This only matters for "
+            "scanned PDFs or documents with equations - a normal text-layer "
+            "PDF doesn't hit this path.\n\n"
+            "Install it with:\n"
+            "  macOS:  brew install llama.cpp\n"
+            "  Linux:  brew install llama.cpp, or download a release from\n"
+            "          https://github.com/ggml-org/llama.cpp/releases\n"
+            "No Homebrew? Download the right archive from that releases "
+            "page directly (llama-<version>-bin-macos-arm64.tar.gz etc.), "
+            "then either put `llama-server` on your PATH or set "
+            "LLAMA_CPP_BINARY to its full path.\n\n"
+            f"Underlying error: {detail}"
+        )
+
+
 class EncryptedDocumentError(DocmdError):
     """Raised when the input is a password-protected / encrypted document."""
 

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/docmd/postprocess/image_handling.py

@@ -18,7 +18,7 @@ import re
 from pathlib import Path
 from typing import Any
 
-_IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^)]+)\)")
+_IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^)]*)\)")
 
 
 def apply_image_handling(
@@ -32,6 +32,16 @@ def apply_image_handling(
     def _replace(match: re.Match[str]) -> str:
         nonlocal counter
         alt_text, ref = match.group(1), match.group(2)
+
+        if not ref.strip():
+            # `![]()` with no reference at all - real Marker output on some
+            # scanned pages (an OCR'd region with no recoverable image data).
+            # No mode should keep this: a placeholder/skip has nothing to
+            # describe, and alt-text mode would otherwise emit a link to
+            # nowhere (an empty href renders as a broken image for no
+            # legitimate reason, since there was never a file to begin with).
+            return ""
+
         filename = Path(ref).name
 
         if mode == "skip":

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docmd-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "Convert PDFs, DOCX, and PPTX to clean, structure-preserving Markdown."
 readme = "README.md"
 license = { text = "MIT" }

docmd_cli-0.1.2/tests/fixtures/generate_stress_fixtures.py

@@ -0,0 +1,110 @@
+"""Regenerates the stress-test PDF fixtures used to prove post-processing
+fixes real Marker defects, not just hand-crafted markdown strings. See
+tests/test_postprocess_integration.py for stress.pdf, and
+tests/test_postprocess_more_integration.py for the ones generated here.
+
+    python tests/fixtures/generate_stress_fixtures.py
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image as PILImage
+from reportlab.lib import colors
+from reportlab.lib.pagesizes import LETTER
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+from reportlab.lib.units import inch
+from reportlab.platypus import (
+    Image,
+    PageBreak,
+    Paragraph,
+    SimpleDocTemplate,
+    Spacer,
+    Table,
+    TableStyle,
+)
+
+FIXTURES_DIR = Path(__file__).parent
+styles = getSampleStyleSheet()
+body = styles["BodyText"]
+h_title = ParagraphStyle("H0", fontSize=28, leading=32, fontName="Helvetica-Bold")
+h_big = ParagraphStyle("H1", fontSize=22, leading=26, fontName="Helvetica-Bold")
+
+
+def generate_running_header() -> None:
+    """4-page document with a bold header drawn at a fixed position on every
+    page (not a flowable heading) - tests whether that gets misdetected as a
+    duplicate heading, and whether structurally identical section headings
+    get assigned consistent levels throughout."""
+
+    def draw_header(canvas, _doc):
+        canvas.saveState()
+        canvas.setFont("Helvetica-Bold", 14)
+        canvas.drawString(72, 740, "CONFIDENTIAL - INTERNAL REPORT")
+        canvas.restoreState()
+
+    doc = SimpleDocTemplate(str(FIXTURES_DIR / "running_header.pdf"), pagesize=LETTER)
+    story = [Paragraph("Quarterly Risk Review", h_title), Spacer(1, 20)]
+    for section in range(1, 5):
+        story.append(Paragraph(f"Section {section}: Findings", h_big))
+        story.append(
+            Paragraph(
+                (f"This is body paragraph content for section {section}. ") * 20,
+                body,
+            )
+        )
+        story.append(PageBreak())
+    doc.build(story, onFirstPage=draw_header, onLaterPages=draw_header)
+
+
+def generate_merged_cells() -> None:
+    """A table with a spanned header cell (merged columns) - tests whether
+    that breaks raw column-count reconstruction."""
+    rows = [
+        ["", "Q1 2026", "", "Q2 2026", ""],
+        ["Region", "Revenue", "Growth", "Revenue", "Growth"],
+        ["West", "$1.2M", "+5%", "$1.4M", "+17%"],
+        ["East", "$0.9M", "+2%", "$1.0M", "+11%"],
+    ]
+    doc = SimpleDocTemplate(str(FIXTURES_DIR / "merged_cells.pdf"), pagesize=LETTER)
+    table = Table(
+        rows,
+        style=TableStyle(
+            [
+                ("GRID", (0, 0), (-1, -1), 0.5, colors.black),
+                ("SPAN", (1, 0), (2, 0)),
+                ("SPAN", (3, 0), (4, 0)),
+                ("BACKGROUND", (0, 0), (-1, 1), colors.lightgrey),
+            ]
+        ),
+    )
+    doc.build([Paragraph("Regional Revenue", h_big), Spacer(1, 10), table])
+
+
+def generate_with_image() -> None:
+    """A PDF with a real embedded image, to test image_handling.py against
+    real Marker image extraction rather than a synthetic dict."""
+    img_path = FIXTURES_DIR / "_gen_chart.png"
+    PILImage.new("RGB", (300, 200), color=(70, 130, 180)).save(img_path)
+
+    doc = SimpleDocTemplate(str(FIXTURES_DIR / "with_image.pdf"), pagesize=LETTER)
+    doc.build(
+        [
+            Paragraph("Revenue Chart", h_big),
+            Spacer(1, 10),
+            Paragraph("See the chart below for regional performance.", body),
+            Spacer(1, 10),
+            Image(str(img_path), width=3 * inch, height=2 * inch),
+            Spacer(1, 10),
+            Paragraph("Chart data is preliminary and subject to revision.", body),
+        ]
+    )
+    img_path.unlink()  # embedded in the PDF now, don't need the source file
+
+
+if __name__ == "__main__":
+    generate_running_header()
+    generate_merged_cells()
+    generate_with_image()
+    print(f"wrote stress fixtures to {FIXTURES_DIR}")

docmd_cli-0.1.2/tests/fixtures/merged_cells.pdf

@@ -0,0 +1,74 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/Contents 8 0 R /MediaBox [ 0 0 612 792 ] /Parent 7 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+5 0 obj
+<<
+/PageMode /UseNone /Pages 7 0 R /Type /Catalog
+>>
+endobj
+6 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20260918162747+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260918162747+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+7 0 obj
+<<
+/Count 1 /Kids [ 4 0 R ] /Type /Pages
+>>
+endobj
+8 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 500
+>>
+stream
+GasalbAP0N&A70Vp-9o2Wp=eD-b`WU86("e7cKB,5`9lcPa:4qq@P(tY`O,]Za6u")iVSsT_nZ>!'F9Npl'_)WWf&+&uo"M<S;SNJQ\51bEBr"EJNqJ)3nW0U7)Oj#S9a"BWKOQf#t8QG.r]FrE!oel[,R2:^sN$K[+:a_DUPO=;K+'BWcc!<f03nK_'+#AkN:2FjDq_&fu'&q\g6&PA-RZmS&LGZ/\-&1=ej\YEP*'kqZfH'*Q.*mPsGb;(?2K8/2H2#)SB%GBB864%J<+%_J8lZD(cfpUfJE1HFGhRYKCsD@tF+GXn4Q5DPJg5jKR,D^co^2cOum(Tj4?-KdNKH<=DaUo3YuUNtRDBD"5?an\):.+7.VApU&?5,]WJjm4jMU%^&7a/@sV.6'4E@FO!8MV%@c@,@XU"QV-bjt@#hftnF^0\s/C;r#1\/&LrLYfuJQXh9^h\l#gnMn:+3@rCY5Ca+P;!Y*lN\<ILke\iKLrW,hE#lt~>endstream
+endobj
+xref
+0 9
+0000000000 65535 f 
+0000000061 00000 n 
+0000000102 00000 n 
+0000000209 00000 n 
+0000000321 00000 n 
+0000000514 00000 n 
+0000000582 00000 n 
+0000000862 00000 n 
+0000000921 00000 n 
+trailer
+<<
+/ID 
+[<04e44ee2661fab79030feb6409b489d5><04e44ee2661fab79030feb6409b489d5>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 6 0 R
+/Root 5 0 R
+/Size 9
+>>
+startxref
+1511
+%%EOF

docmd_cli-0.1.2/tests/fixtures/running_header.pdf

@@ -0,0 +1,131 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/Contents 11 0 R /MediaBox [ 0 0 612 792 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+5 0 obj
+<<
+/Contents 12 0 R /MediaBox [ 0 0 612 792 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+6 0 obj
+<<
+/Contents 13 0 R /MediaBox [ 0 0 612 792 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+7 0 obj
+<<
+/Contents 14 0 R /MediaBox [ 0 0 612 792 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+8 0 obj
+<<
+/PageMode /UseNone /Pages 10 0 R /Type /Catalog
+>>
+endobj
+9 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20260918162747+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260918162747+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+10 0 obj
+<<
+/Count 4 /Kids [ 4 0 R 5 0 R 6 0 R 7 0 R ] /Type /Pages
+>>
+endobj
+11 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 361
+>>
+stream
+Gb"/chbJeX'ZTTeMXM0P7+reOn,*7oahf$h(I5uBe\Nf8g"T^lL:@V#9Xn<\1sL5>cgPXF;?g>7VUonlg^u.@#0&qZ0ZS3!1\bLn)`kj$VB`8*[1T7A[`F\ClI_a=bklZ"KF`N"iU%$i#UAp#88Vl:E?<RHkQQ(b*+,Ymh0BO6a-@13fijSb^V1/T.Gi_8?=RK^)\_An,E[*qhfafEonka+'\V(k`\GH_P[ejqrf+$%LV'#RPbkc9$a:QQU0*9sYD1,"I.2U:hB&CP@-`$n?]`j5Jst$IEeeKUP?]Hh2:Ae/Z_GI>Pc,'U/Gqa0i7o<7nWVeV7V).t45PdP??V)cFmmhn5t:`K_"\,!^:87~>endstream
+endobj
+12 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 319
+>>
+stream
+Gb"/c]5E6T(km1*if#]lM/Bf]AEsCEUklDMIfVkK6D^%P=Sh_K/toX>L.Z9E/^*uDk<$*uF"fD[?1T<17$pIa>_)P+dZ^==6?:A3bm4uh);eA@`l*-U&dSW'JW=]Af1?[kKF,VY/)2@E-qk;\9uGS*8p?p=d&_#41X\Y*K!1F/@:II#l=-j@+?T,=L9Ll9hjJH@GBmCn)IeQ%eD!k;bqHpU`^:lP0c'$n@W$bMZO.)66eT9!9ssr<.BBeLc;"W*Q#:fW`P/A">^UekJ+^dk4!EX^HD"!R(fq6\#oTN'!I&n(gZr-VoH+7,0.TP^h#~>endstream
+endobj
+13 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 320
+>>
+stream
+Gb"/c:JZTs(rl#lMW]dB@Tt?^Dn85$Z7okY(I5D`9NEKZn_77t6el+*-/=eE:%S@0IS\^o*6\h/f6e+A'(-tS/jNW[kt05'+ZWnibm4uh);eA@`l*-U&dSW'JbF%qb9Vu.@7'M-!dBG6$Icq0e*q4BdLGCRFPF4<)sO&'_,neS0JR0LFYVH[OI^W/6WeuXmnC6l:#;2$`ksU,;Qi`!2#dh/N5n2T@m$_tLq*\$cRLK!G%Cb35H=B8%U#>;F`uC\YB7D(/[eZ=k30_#jjclamY$P6l@Ci:@pD1d-=i(8#Mf"FY-3&8d=2jLIK3B<S+6~>endstream
+endobj
+14 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 319
+>>
+stream
+Gb"/c]5E6T(km1*if#]lM/Bf]AEsCEUklDMIfVkK6D^%P=Sh_K/toX>L.Z9E/^*uDk<$*uF"fD[?1T<17$pIa>_)P+dZ^==6?:A3bm4uh);eA@`l*-U&dSW'JW=]Af1?[kKF,VY/)2@E-qk;\9uGS*8p?p=d&_#41X\Y*K!1F/@:II#l=-j@+?T,=L9Ll9hjJH@GBmCn)KL\5eD!k;bqHpU`^:lP0c'$n@W$bMZO.)66eT9!9ssr<.BBeLc;"W*Q#:fW`P/A">^UekJ+^dk4!EX^HD"!R(fq6\#oTN'!I&n(gZr-VoH+7,07WM^#6~>endstream
+endobj
+xref
+0 15
+0000000000 65535 f 
+0000000061 00000 n 
+0000000102 00000 n 
+0000000209 00000 n 
+0000000321 00000 n 
+0000000516 00000 n 
+0000000711 00000 n 
+0000000906 00000 n 
+0000001101 00000 n 
+0000001170 00000 n 
+0000001450 00000 n 
+0000001528 00000 n 
+0000001980 00000 n 
+0000002390 00000 n 
+0000002801 00000 n 
+trailer
+<<
+/ID 
+[<71bc982e6efde47f41d5e095c3f3e0e4><71bc982e6efde47f41d5e095c3f3e0e4>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 9 0 R
+/Root 8 0 R
+/Size 15
+>>
+startxref
+3211
+%%EOF

docmd_cli-0.1.2/tests/fixtures/stress.pdf

@@ -0,0 +1,99 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R /F3 4 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/BaseFont /Helvetica-BoldOblique /Encoding /WinAnsiEncoding /Name /F3 /Subtype /Type1 /Type /Font
+>>
+endobj
+5 0 obj
+<<
+/Contents 10 0 R /MediaBox [ 0 0 612 792 ] /Parent 9 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+6 0 obj
+<<
+/Contents 11 0 R /MediaBox [ 0 0 612 792 ] /Parent 9 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+7 0 obj
+<<
+/PageMode /UseNone /Pages 9 0 R /Type /Catalog
+>>
+endobj
+8 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20260918161648+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260918161648+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+9 0 obj
+<<
+/Count 2 /Kids [ 5 0 R 6 0 R ] /Type /Pages
+>>
+endobj
+10 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1689
+>>
+stream
+Gat%d>AkH>&;B$?/,6=ZDEt88?QOPc$5>dYfE1p9`bWVGCq6k<+TK1:mL7&l`"<A%M7E/F_m<"-*3E`qrQ+6l0+X$?\n40VOA%.4^1G`o$sS3ln(24PSk1&Q?nSG^Ve]bQ[_"Uo^F%,tl$"2s/;hQ2B2L/)+a%&/OK.UcG5f\Fj3.+M?!VBgB6H:!D0PlLf_QOk^LJ';Ql:HL5Ki3GjQ:BagAep`o1uRMme)&,NkLL^dtX;nbnI!:-Dij_:]00_ZXGe&P.93%Z.nZ+mD"\JpAXk\](BLFhJr88&%3GGm^J6-ZFa")`7jE9etgJfSC[=Z?I$UY?*g(1FsT!R0_[%FDldJfs%V;j'5rS5b/dS/)AhY8mZP5,MtO`r.B-[^9#jViH(F,bdp8nQ<DceuPci**j&f"Pe/'YD4jHX"<d!HSnaU0QN[eI<:)3J;J%^>W5)uKX]q21sf?\eA#]N?@PGAlmZ]khH6j!WV!"Y3-j(UN(rjLKDO#Kcnf$:#!0DhrK*WWMf7Hsmboe^('"7RErGL=chJ3>&Hqhb/"q$\h\^ar$?JcJ2)%2]3K4=J7(Bfo$&"RN%aZ#M,=Hns!Aa2e.][F[\UTNP+O:4aSg;,@?!5l_GLE#f!3#T$,u+YfUq^W.!88/*R^QII/?6;I[f4TH!^EN^<0l2d4%UI1Xu+IDa\8e6NPVZG+i&0@q6+uBcKkWtNgE8#FQ!eOQM_hgX=>8fg1"uuYo2KGQ:/][N$6Lr5^6U3=5C@$!QA<qtsJ3aa^KCdmq`hPpf^n)+5\h*s1/?*VB6'>DT63@E`!"[q+W>]r9P(4jfSEr$7jJMrT"Xuqo*2*Og*.WfP\FC"BjiAK5:pJ=YOIHB8+TY.K7"tht#K;=k6NWu0o_;0W5]@?(V?A/A&=F.B*i.lFd4#*!C;VLTBaG&?HH;1u,jHO?!lBSKgpWe#lENLDTQIXj+?F3\ErqN'M9H83&'FKOl'tRN95@FR[Xd-YL^XV]U*)3>+?X>X<@_"@+CN;c-TXsf<2MqC"=-hSR1g,QN8`@93<<:Zq5!J@IBJ+YUkjs:8>7:`.Ngk+jE$HD$HSf8j>q\i_+>6,'p(gPA6(s?E0;_=B*DhF/LO9%.j-l%,,54&W/-B>#S/OJ?)45^=Y9T2FIt'+2go$Z_ZGuDW!.erJ-YOg1iuhbp4ORAk6o@*K#k0H,RPa5!l@;q2AbSaJ1S+k@](Znl?*/r']QtB>3mdEfYMO)l'N$/r4mO1JNpY1.h9m/r5&kGm&\097Sl2O3[=EkLg[j.^`KRBOTE9NS=mjHE\,34agIl'JN`ss_0!CXW'#TZKs7oaq@*KcJ;W.X'/'p.^+FHhK'N-[Z!_kRku7Y<?O,FM=s^QKCpLdm?_)U#%kNc*R0N0A40BTp"ce$raKNV`9RjdmHgT!@c;p6Z0<`,4n-+%XCtR9;&F$L!XoK["F<U.J$1;am%naZlWfRF]@&o.TTG4c5$>E<DZ<D`!?pVi5Goi3%YF=W?.CcC'*gD8URccscW2b+aP_,j'MaMP#WoeS'$GL8H#Gkh/k'9c1\n[fAV')i$H%6&9X6+\($DD4+#Gp@Yk'9c1VJ;\-V4ajNGu+jBDCuFDA(<X^>5P>+5;]hAG-,Y,ID;h[F\cgf9Ko>alhp"OO$gtn1KW^7LPdo@S\n^#5?3sco"gefo1,m1Spo>FImINnLB~>endstream
+endobj
+11 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1195
+>>
+stream
+Gasb[>E9FX&4YRK/,[a)J=<RCD>SI"fp,SD"@V6p"?cj#/hiJlr]\%qg$U#d=<j3ClQhaZEITDF`l!j.s*qUgm*>e2iuc*jA;<f)oNnlAC\I%tqlpf"$>9'!0kFp@6FaaRdV:#Ze)0n$]A)fXV'V=/m&akQKk'j-]6pmDl*USDm<E@nTinm_h%ll`B87H"m/;8'p$VN64+(On(JcHspJNm0pX>K?5.4jKY8>fg3FV!_D>aE[qm`4e-.i#_(A>Z9iqW:f)@`ku7&&Pnh&jCn-3+5`-64N;A<_?gGRk!'J1%+).i-hEfY=TX*nJY#,O&4*f%]55n)MVeLaFKF3?a5S*B6,(4=t=1M^"_7];;("8^tfRiCF:V(PNPNKn'<"*Xk@8:KG\CFANYQp?hU^F(^0X1H$tk0$`Y\QZNA0"!m/R@*eq!Z@97%dQ518q>2SMfBs^E]*Q5`,Y96B2b"f)Mu]H>Rg%EN&[5o,jBsS_R#F(Q*K9&+(O@bP!B_rT88_T::iaVHnPJ.$'NF7j"<kJcKcUXh!)FdASaU)5)Y&qd#iBqqTn$A\16`?5.+EgS&AjW1Zd9^,KTJ>A[#Ds*E_35$PlX4p2AS>-#Q[&eOE/'V^S)4Ce=I>"0GG'l5+OY7+2&,;%LbN$:Wh!YFhY--7ur=T:kPHl?nrp]"XMKO*#9*WFGMqI%h$IM0bVC7J7rsILBSsNM&[9BT$/sZ?7)B[YgfiIA"hgr->7Ern=)u4Z.T<5C!j8.oU+Q,!l9oYJZWpbaXP&Dd\+Wm(Q1)$R\cfm"?S@_R)(I12%)6$+IGk;o[k^)E'+]<Z1N8@.(.%d?jc*9!h,VfoHjZdCfUR[Edm_F*Xq\fEFF5KW;"'(kCUtGhd^YH".`RIB82##R:,CDDsi$o*n]?Gj>6j\^0'Mdd'LO0j$>fNrtkZ_K6-hbIs67WI[9$j%3F0^igP;:"fXk?Dm&VX,ujFMHs/jdHO[L#Rp((aD_L]09n/qGcH#lcKZBpIF8:b:C[ej`KO3*;51\Y3Xa-6Dnu2nQet4V?>6tZg8EX_2/kWr<:2s,<VYQ22U(gS%)],=nRc\U@L%%QI+YHC'29k0U'UGVA>a0hXR`@iGaJO5fPQGcmo@htY]mXa7S'JH#2GIOWgT'u=DOS!sh.B%D\fJpoa]j;Ibtom8"7Wl:C*ioQH*\*Up+H<Jh(LG8*K^~>endstream
+endobj
+xref
+0 12
+0000000000 65535 f 
+0000000061 00000 n 
+0000000112 00000 n 
+0000000219 00000 n 
+0000000331 00000 n 
+0000000450 00000 n 
+0000000644 00000 n 
+0000000838 00000 n 
+0000000906 00000 n 
+0000001186 00000 n 
+0000001251 00000 n 
+0000003032 00000 n 
+trailer
+<<
+/ID 
+[<363e53a615617ff0e3d5d99a726c39b8><363e53a615617ff0e3d5d99a726c39b8>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 8 0 R
+/Root 7 0 R
+/Size 12
+>>
+startxref
+4319
+%%EOF

docmd_cli-0.1.2/tests/fixtures/with_image.pdf

@@ -0,0 +1,85 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/BitsPerComponent 8 /ColorSpace /DeviceRGB /Filter [ /ASCII85Decode /FlateDecode ] /Height 200 /Length 255 /Subtype /Image 
+  /Type /XObject /Width 300
+>>
+stream
+Gb"0<!=8`+$j3/G$ar_:p`'OXFAZ%<<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3&lcN@.'qUP~>endstream
+endobj
+5 0 obj
+<<
+/Contents 9 0 R /MediaBox [ 0 0 612 792 ] /Parent 8 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ] /XObject <<
+/FormXob.33833d909d83ea6c265a8c21bc2adfc1 4 0 R
+>>
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+6 0 obj
+<<
+/PageMode /UseNone /Pages 8 0 R /Type /Catalog
+>>
+endobj
+7 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20260918162747+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260918162747+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+8 0 obj
+<<
+/Count 1 /Kids [ 5 0 R ] /Type /Pages
+>>
+endobj
+9 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 341
+>>
+stream
+Gas2Dc#/.f&;9L7`>mVRLi'qpCYIq#93Vn>)RC\Wr1o(ClJ'pXW)@>_<jLf6mPgp"?uEK(9abcYCj$e'+KrT@0Ll%nk</MJpiSAmO@m&pV_PC.IGiEG0?N%WNZoT.7EC=*pI5tac@j5j[c9OA,P$VHr9EDt4n\HD.bU8gQp"_qk*$2Aq+cV55VSBL$>TDj<5"!^IGK+Y_258j\%4@0Y%C;Y1)%tJ&gld<K$.;Wj(jprB'6rOI1\r2MP;k9=fEUndKl7SAHXZFct-cJT)/JAE@,Ug&>uSJh_)_]N`(oVomi7&VJb]pgMc;Y`,I>hA4DNkCZSG)Y*W]5#^uc+qh+V~>endstream
+endobj
+xref
+0 10
+0000000000 65535 f 
+0000000061 00000 n 
+0000000102 00000 n 
+0000000209 00000 n 
+0000000321 00000 n 
+0000000766 00000 n 
+0000001022 00000 n 
+0000001090 00000 n 
+0000001370 00000 n 
+0000001429 00000 n 
+trailer
+<<
+/ID 
+[<a37d360f94bbcb79be8c654f5f762036><a37d360f94bbcb79be8c654f5f762036>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 7 0 R
+/Root 6 0 R
+/Size 10
+>>
+startxref
+1860
+%%EOF

docmd_cli-0.1.2/tests/test_marker_converter_errors.py

@@ -0,0 +1,49 @@
+"""Unit tests for MarkerConverter's exception classification - mocked so
+these run fast and don't depend on whether llama-server happens to be
+installed on the machine running the tests. See
+docmd/converters/marker_converter.py for the real (slow, environment-
+dependent) version of this failure, found via real OCR testing on a
+genuinely scanned PDF from archive.org.
+"""
+
+from __future__ import annotations
+
+import docmd.converters.marker_converter as marker_converter_module
+from docmd.config import ConvertConfig
+from docmd.converters.marker_converter import MarkerConverter
+from docmd.errors import MissingSystemDependencyError
+
+
+class _FakeSpawnError(Exception):
+    """Stands in for surya.inference.backends.spawn.SpawnError without
+    importing surya's internal exception class directly."""
+
+
+class _FakePdfConverterMissingBinary:
+    def __init__(self, **_kwargs) -> None:
+        pass
+
+    def __call__(self, _filepath: str):
+        raise _FakeSpawnError(
+            "llama-server binary not found. Install with:\n"
+            "  macOS:  brew install llama.cpp"
+        )
+
+
+def test_missing_llama_server_binary_raises_clear_error(monkeypatch, tmp_path):
+    monkeypatch.setattr(marker_converter_module, "_get_model_dict", lambda: {})
+    monkeypatch.setattr(
+        "marker.converters.pdf.PdfConverter", _FakePdfConverterMissingBinary
+    )
+
+    dummy_pdf = tmp_path / "dummy.pdf"
+    dummy_pdf.write_bytes(b"%PDF-1.4\n%%EOF")
+
+    try:
+        MarkerConverter().convert(str(dummy_pdf), ConvertConfig())
+        raise AssertionError("expected MissingSystemDependencyError")
+    except MissingSystemDependencyError as exc:
+        message = str(exc)
+        assert "llama.cpp" in message
+        assert "brew install llama.cpp" in message
+        assert "LLAMA_CPP_BINARY" in message

{docmd_cli-0.1.0 → docmd_cli-0.1.2}/tests/test_postprocess.py

@@ -9,6 +9,30 @@ def test_heading_normalize_fixes_level_skip():
     assert out == "# Title\n## Subsection\n"
 
 
+def test_heading_normalize_fixes_level_skip_then_leaves_recovered_depth_alone():
+    """The exact pattern found in a real 27-page IMF report while stress-
+    testing against downloaded (not synthetic) documents: an H1 jumps
+    straight to H4 (skipping H2/H3), gets clamped to H2 - but a *later*
+    heading that's also originally H4 is left alone, because an H3 heading
+    in between legitimately re-establishes the depth. Never reproduced
+    synthetically (see skip_headings.pdf in git history, removed after
+    Marker's own layout model wouldn't cooperate) - this encodes the real
+    structure without redistributing the copyrighted source PDF."""
+    md = (
+        "# Summary of the Economy Classification\n"
+        "#### General Features and Composition of Groups\n"
+        "### Advanced Economies\n"
+        "#### Emerging Market and Developing Economies\n"
+    )
+    out = normalize_headings(md)
+    assert out == (
+        "# Summary of the Economy Classification\n"
+        "## General Features and Composition of Groups\n"
+        "### Advanced Economies\n"
+        "#### Emerging Market and Developing Economies\n"
+    )
+
+
 def test_heading_normalize_drops_empty_heading():
     md = "# Title\n##\nBody text.\n"
     out = normalize_headings(md)
@@ -98,3 +122,16 @@ def test_image_handling_alt_text_mode_fills_empty_alt():
     md = "![](img.png)"
     out = apply_image_handling(md, images={}, mode="alt-text")
     assert out == "![Image 1](img.png)"
+
+
+def test_image_handling_drops_fully_empty_image_reference():
+    """Real Marker output on a scanned page: `![]()` with no href at all,
+    directly adjacent to a real image reference with no separator between
+    them - found while OCR-testing a genuinely scanned PDF. The old regex
+    required at least one character inside the parens, so `![]()` never
+    matched and leaked through every mode unprocessed."""
+    md = "![]()![](real.jpeg)"
+
+    assert apply_image_handling(md, images={}, mode="placeholder") == "*[image omitted]*"
+    assert apply_image_handling(md, images={}, mode="skip") == ""
+    assert apply_image_handling(md, images={}, mode="alt-text") == "![Image 1](real.jpeg)"

docmd_cli-0.1.2/tests/test_postprocess_integration.py

@@ -0,0 +1,68 @@
+"""Integration test proving post-processing fixes a *real* Marker bug, not
+just hand-crafted markdown strings (see tests/test_postprocess.py for those -
+useful for fast unit coverage, but circular as evidence of real-world value,
+since the input was written to match what the regex expects).
+
+fixtures/stress.pdf has a 45-row table that spans a PDF page break
+(reportlab's repeatRows=1, matching how real multi-page business reports are
+laid out). Marker processes pages independently, so it renders this as two
+separate Markdown tables with a duplicated header row in between - this test
+converts the real PDF through real Marker, confirms that split actually
+happens (so this test fails loudly if a future Marker version stops doing
+it, rather than silently testing nothing), then confirms docmd's full
+convert() pipeline merges them back into one continuous table.
+"""
+
+from pathlib import Path
+
+from docmd import convert_document
+from docmd.config import ConvertConfig
+from docmd.converters.marker_converter import MarkerConverter
+
+FIXTURE = Path(__file__).parent / "fixtures" / "stress.pdf"
+
+
+def test_marker_really_does_split_a_page_spanning_table():
+    """Documents the real upstream behavior this feature exists to fix."""
+    raw = MarkerConverter().convert(str(FIXTURE), ConvertConfig())
+    # Raw Marker output pads cell widths with extra spaces for column
+    # alignment (e.g. "| Region  | Rep    |"), so match loosely rather than
+    # on an exact literal string.
+    header_count = sum(
+        1
+        for line in raw.markdown.splitlines()
+        if "Region" in line and "Revenue" in line and line.strip().startswith("|")
+    )
+    assert header_count >= 2, (
+        "expected Marker to render the page-spanning table as 2+ blocks "
+        "with a repeated header - if this fails, Marker's behavior changed "
+        "and test_docmd_merges_the_split_table's premise needs revisiting"
+    )
+
+
+def test_docmd_merges_the_split_table():
+    result = convert_document(str(FIXTURE))
+    markdown = result.markdown
+
+    # One continuous table: header appears exactly once, not once per page.
+    assert markdown.count("| Region | Rep | Deal | Revenue | Status |") == 1
+
+    # All 45 data rows survived the merge - none silently dropped, including
+    # the ones on both sides of where the original page-break duplicate
+    # header used to sit (rows 27 and 28 of 45).
+    for i in range(1, 46):
+        assert f"Deal-{1000 + i}" in markdown
+
+    # The row right after the original page-break duplicate header is still
+    # present as a *data* row, not swallowed along with the header.
+    assert "North | Rep 28 | Deal-1028" in markdown
+
+
+def test_docmd_promotes_first_heading_to_h1():
+    """Source PDF's title paragraph rendered as H2 in raw Marker output (its
+    font size wasn't visually distinct enough for Marker's heading-level
+    detection) - docmd promotes a document's opening heading to H1 rather
+    than leaving it start at H2 with no root."""
+    result = convert_document(str(FIXTURE))
+    first_line = result.markdown.splitlines()[0]
+    assert first_line.startswith("# ") and "Annual Sales Report" in first_line

docmd_cli-0.1.2/tests/test_postprocess_more_integration.py

@@ -0,0 +1,105 @@
+"""More real-Marker-bug regression tests, generated by "do many more tests" -
+each one converts a real PDF through real Marker and checks docmd's output,
+not hand-written markdown. See test_postprocess_integration.py for the
+first one (page-spanning table). Honest negative results are included too,
+not just wins - see test_merged_header_cells_survive_cleanly.
+"""
+
+from pathlib import Path
+
+from docmd import convert_document
+from docmd.config import ConvertConfig
+from docmd.converters.marker_converter import MarkerConverter
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def test_inconsistent_heading_levels_get_normalized_to_match():
+    """running_header.pdf has 4 structurally identical section headings
+    (same paragraph style). On the machine this was first written on (macOS,
+    MPS), raw Marker assigned them *different* levels - Section 1 came back
+    H3, Sections 2-4 came back H2 - a genuine model inconsistency, not a
+    deliberately constructed skip.
+
+    That specific raw output isn't portable, though: CI (Linux, CPU) ran the
+    exact same PDF through the exact same pinned Marker version and got all
+    four sections back as H2 from the start - a real platform-dependent
+    difference in the underlying ML model's inference, not something our
+    code controls. Hard-pinning the raw "bug" broke CI twice for that
+    reason. So this only *asserts* the thing docmd actually guarantees -
+    consistent heading levels across all four sections, however Marker
+    happened to render them - and reports (without failing) whether this
+    particular run's raw output shows the original inconsistency."""
+    raw = MarkerConverter().convert(str(FIXTURES / "running_header.pdf"), ConvertConfig())
+    if "### **Section 1: Findings**" in raw.markdown:
+        print("raw Marker output reproduced the H3-vs-H2 inconsistency on this run")
+    else:
+        print("raw Marker output did not reproduce the inconsistency on this run/platform")
+
+    result = convert_document(str(FIXTURES / "running_header.pdf"))
+    levels = {
+        n: "###" if f"### **Section {n}: Findings**" in result.markdown else "##"
+        for n in range(1, 5)
+    }
+    assert len(set(levels.values())) == 1, f"inconsistent levels in docmd output: {levels}"
+
+
+def test_running_header_does_not_leak_into_output():
+    """The bold text drawn at a fixed position on every page ("CONFIDENTIAL
+    - INTERNAL REPORT") never appears in Marker's raw markdown at all -
+    Marker's own PageHeaderProcessor already strips repeated page headers.
+    This is an honest negative result: docmd's duplicate-heading dedup
+    wasn't needed here because Marker solved it upstream. Pinned as a
+    regression test so a future Marker version silently changing this
+    doesn't go unnoticed."""
+    raw = MarkerConverter().convert(str(FIXTURES / "running_header.pdf"), ConvertConfig())
+    assert "CONFIDENTIAL" not in raw.markdown
+
+
+def test_merged_header_cells_survive_cleanly():
+    """merged_cells.pdf has a spanned header cell (colspan). Honest negative
+    result: Marker already renders this as a clean, consistent 5-column
+    table (blank cells for the spanned columns) with no ragged rows -
+    nothing for table_cleanup.py to fix here. Pinned so this doesn't
+    silently regress, and so nobody assumes this case needs a fix it
+    doesn't need."""
+    raw = MarkerConverter().convert(str(FIXTURES / "merged_cells.pdf"), ConvertConfig())
+    table_lines = [l for l in raw.markdown.splitlines() if l.strip().startswith("|")]
+    # spanned quarter-label row, column-label row, separator, 2 data rows.
+    assert len(table_lines) == 5
+    assert all(line.count("|") == 6 for line in table_lines)  # 5 columns, consistent
+
+    result = convert_document(str(FIXTURES / "merged_cells.pdf"))
+    assert "West" in result.markdown and "$1.2M" in result.markdown
+
+
+def test_alt_text_mode_actually_saves_the_image(tmp_path):
+    """Regression test for a real bug found while doing this testing:
+    `output_dir` was accepted by apply_image_handling() but never actually
+    threaded through from convert()/convert_document(), so alt-text mode
+    produced a markdown image link pointing to a file that was never
+    written anywhere. Fixed in docmd/__init__.py and docmd/cli.py."""
+    result = convert_document(
+        str(FIXTURES / "with_image.pdf"),
+        config=ConvertConfig(image_mode="alt-text"),
+        output_dir=tmp_path,
+    )
+    assert "![Image 1](" in result.markdown
+
+    saved_images = list(tmp_path.glob("*.jpeg"))
+    assert len(saved_images) == 1
+    assert saved_images[0].name in result.markdown
+    # A real, valid JPEG - not an empty/placeholder file.
+    assert saved_images[0].read_bytes()[:2] == b"\xff\xd8"
+
+
+def test_placeholder_mode_never_writes_image_files(tmp_path):
+    """The default mode should never touch the filesystem, even if an
+    output_dir happens to be passed."""
+    result = convert_document(
+        str(FIXTURES / "with_image.pdf"),
+        config=ConvertConfig(image_mode="placeholder"),
+        output_dir=tmp_path,
+    )
+    assert "omitted" in result.markdown
+    assert list(tmp_path.iterdir()) == []