docmd-cli 0.1.0__py3-none-any.whl

docmd/__init__.py

@@ -0,0 +1,83 @@
+"""docmd: convert PDF/DOCX/PPTX to clean, structure-preserving Markdown.
+
+    from docmd import convert
+    markdown = convert("report.pdf")
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from docmd.config import ConvertConfig
+from docmd.converters.base import ConversionResult
+from docmd.converters.registry import get_converter
+from docmd.postprocess.heading_normalize import normalize_headings
+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"
+
+
+def convert_document(
+    source: str | Path | bytes,
+    *,
+    filename: str | None = None,
+    config: ConvertConfig | None = None,
+) -> ConversionResult:
+    """Convert `source` and return the full result (markdown + page count +
+    metadata), after docmd's post-processing pass has run.
+
+    `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).
+    """
+    config = config or ConvertConfig()
+
+    if isinstance(source, (bytes, bytearray)):
+        if not filename:
+            raise ValueError("filename is required when passing bytes")
+        suffix = Path(filename).suffix
+        fd, tmp_path = tempfile.mkstemp(suffix=suffix)
+        try:
+            with os.fdopen(fd, "wb") as tmp:
+                tmp.write(source)
+            result = _convert_path(tmp_path, config)
+        finally:
+            os.unlink(tmp_path)
+    else:
+        result = _convert_path(str(source), config)
+
+    return result
+
+
+def convert(
+    source: str | Path | bytes,
+    *,
+    filename: str | None = None,
+    config: ConvertConfig | 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
+
+
+def _convert_path(filepath: str, config: ConvertConfig) -> ConversionResult:
+    converter = get_converter(filepath)
+    result = converter.convert(filepath, config)
+
+    markdown = result.markdown
+    if config.clean_tables:
+        markdown = clean_tables(markdown)
+    if config.normalize_headings:
+        markdown = normalize_headings(markdown)
+    markdown = apply_image_handling(markdown, result.images, config.image_mode)
+
+    return ConversionResult(
+        markdown=markdown,
+        page_count=result.page_count,
+        images=result.images,
+        metadata=result.metadata,
+    )

docmd/cli.py

@@ -0,0 +1,68 @@
+"""`docmd convert <file> [-o output.md]`"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from docmd import convert_document
+from docmd.config import ConvertConfig
+from docmd.errors import DocmdError
+
+
+@click.group()
+@click.version_option(package_name="docmd")
+def main() -> None:
+    """docmd: convert PDF/DOCX/PPTX to clean, structure-preserving Markdown."""
+
+
+@main.command()
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "-o",
+    "--output",
+    "output",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Write Markdown to this file instead of stdout.",
+)
+@click.option(
+    "--force-ocr",
+    is_flag=True,
+    default=False,
+    help="Force OCR even on pages that already have a text layer.",
+)
+@click.option(
+    "--use-llm",
+    is_flag=True,
+    default=False,
+    help="Use an LLM pass for higher-fidelity table/form extraction (needs a provider API key set for Marker; has a real marginal cost).",
+)
+@click.option(
+    "--image-mode",
+    type=click.Choice(["placeholder", "alt-text", "skip"]),
+    default="placeholder",
+    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:
+    """Convert FILE to Markdown."""
+    config = ConvertConfig(force_ocr=force_ocr, use_llm=use_llm, image_mode=image_mode)
+
+    try:
+        result = convert_document(str(file), config=config)
+    except DocmdError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+
+    if output is not None:
+        output.write_text(result.markdown, encoding="utf-8")
+        click.echo(f"wrote {output} ({result.page_count} page(s))", err=True)
+    else:
+        click.echo(result.markdown)
+
+
+if __name__ == "__main__":
+    main()

docmd/config.py

@@ -0,0 +1,51 @@
+"""Conversion configuration for docmd.
+
+Kept small and explicit. This is *not* the hosted API's config (rate limits,
+billing thresholds, etc.) - see ARCHITECTURE.md, that lives in `api/` in a
+later stage. This is just what controls a single conversion.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_VALID_IMAGE_MODES = {"placeholder", "alt-text", "skip"}
+
+
+@dataclass
+class ConvertConfig:
+    """Options for a single conversion.
+
+    Attributes:
+        use_llm: Ask Marker to use an LLM pass for higher-fidelity extraction
+            of tricky tables/forms. Off by default: it requires an API key
+            for an LLM provider and has a real marginal cost, so it should be
+            an explicit opt-in rather than a surprise dependency.
+        force_ocr: Force OCR even on PDFs that already have a text layer.
+            Useful for PDFs with a broken/garbled embedded text layer.
+        normalize_headings: Run docmd's own heading-normalization
+            post-processing pass (see postprocess/heading_normalize.py).
+        clean_tables: Run docmd's own table-cleanup post-processing pass
+            (see postprocess/table_cleanup.py).
+        image_mode: How to represent images in the output Markdown.
+            - "placeholder" (default): RAG-friendly. No binary image data is
+              written; each image becomes a short, consistent placeholder
+              line so downstream chunking/embedding code has something
+              predictable to key off (or skip) rather than a dangling link.
+            - "alt-text": images are saved next to the output file and kept
+              as real Markdown image links with non-empty alt text.
+            - "skip": images are dropped entirely, no placeholder either.
+    """
+
+    use_llm: bool = False
+    force_ocr: bool = False
+    normalize_headings: bool = True
+    clean_tables: bool = True
+    image_mode: str = "placeholder"
+
+    def __post_init__(self) -> None:
+        if self.image_mode not in _VALID_IMAGE_MODES:
+            raise ValueError(
+                f"image_mode must be one of {sorted(_VALID_IMAGE_MODES)}, "
+                f"got {self.image_mode!r}"
+            )

docmd/converters/base.py

@@ -0,0 +1,36 @@
+"""Converter interface.
+
+Every converter (currently just Marker; the registry exists so a second
+engine could be added later without touching callers) implements this
+protocol: take a filepath, return a ConversionResult.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+from docmd.config import ConvertConfig
+
+
+@dataclass
+class ConversionResult:
+    """The raw result of running a document through a conversion engine,
+    before docmd's own post-processing pass runs on top of it.
+    """
+
+    markdown: str
+    page_count: int
+    images: dict[str, Any] = field(default_factory=dict)
+    """Maps an image filename referenced in `markdown` (e.g.
+    '_page_0_Figure_1.jpeg') to a PIL.Image.Image instance."""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Converter(Protocol):
+    """A document -> Markdown conversion engine."""
+
+    def convert(self, filepath: str | Path, config: ConvertConfig) -> ConversionResult:
+        """Convert the file at `filepath` into a ConversionResult."""
+        ...

docmd/converters/marker_converter.py

@@ -0,0 +1,89 @@
+"""Wraps `marker-pdf` (https://github.com/datalab-to/marker) as a docmd Converter.
+
+Uses Marker's Python API directly (not its CLI/server) so we control input and
+output cleanly. `PdfConverter` is Marker's general-purpose converter despite
+the name: it dispatches to the right internal provider (PDF, DOCX, PPTX, ...)
+based on the file's actual content, via `provider_from_filepath`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from docmd.config import ConvertConfig
+from docmd.converters.base import ConversionResult
+from docmd.errors import ConversionError, EncryptedDocumentError, MissingExtraError
+
+# 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
+# repeated conversions within one process don't reload them.
+_model_dict: dict[str, Any] | None = None
+
+_PASSWORD_HINTS = ("password", "encrypt")
+
+
+def _get_model_dict() -> dict[str, Any]:
+    global _model_dict
+    if _model_dict is None:
+        from marker.models import create_model_dict
+
+        _model_dict = create_model_dict()
+    return _model_dict
+
+
+def _build_config_dict(config: ConvertConfig):
+    from marker.config.parser import ConfigParser
+
+    options: dict[str, Any] = {
+        "output_format": "markdown",
+        "force_ocr": config.force_ocr,
+        "use_llm": config.use_llm,
+    }
+    if config.image_mode == "skip":
+        options["disable_image_extraction"] = True
+
+    return ConfigParser(options)
+
+
+class MarkerConverter:
+    """Converter implementation backed by Marker."""
+
+    def convert(self, filepath: str | Path, config: ConvertConfig) -> ConversionResult:
+        filepath = str(filepath)
+        try:
+            from marker.converters.pdf import PdfConverter
+            from marker.output import text_from_rendered
+        except ImportError as exc:
+            raise MissingExtraError(Path(filepath).suffix) from exc
+
+        config_parser = _build_config_dict(config)
+        config_dict = config_parser.generate_config_dict()
+
+        try:
+            converter = PdfConverter(
+                config=config_dict,
+                artifact_dict=_get_model_dict(),
+                processor_list=config_parser.get_processors(),
+                renderer=config_parser.get_renderer(),
+                llm_service=config_parser.get_llm_service(),
+            )
+            rendered = converter(filepath)
+        except Exception as exc:
+            message = str(exc).lower()
+            if any(hint in message for hint in _PASSWORD_HINTS):
+                raise EncryptedDocumentError() from exc
+            raise ConversionError(
+                f"Marker failed to convert '{filepath}': {exc}", cause=exc
+            ) from exc
+
+        markdown, _, images = text_from_rendered(rendered)
+        metadata = dict(getattr(rendered, "metadata", {}) or {})
+        page_count = len(metadata.get("page_stats", [])) or 1
+
+        return ConversionResult(
+            markdown=markdown,
+            page_count=page_count,
+            images=images,
+            metadata=metadata,
+        )

docmd/converters/registry.py

@@ -0,0 +1,43 @@
+"""Maps a file extension to the converter (and required extras) that handle it.
+
+Kept as a registry rather than hardcoding checks in the CLI/library entrypoint
+so a second conversion engine could be added later without touching callers.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+from docmd.converters.base import Converter
+from docmd.converters.marker_converter import MarkerConverter
+from docmd.errors import MissingExtraError, UnsupportedFormatError
+
+# suffix -> module that must be importable for that format to work.
+# None means "supported by the base install, no extra needed".
+_SUPPORTED_SUFFIXES: dict[str, str | None] = {
+    ".pdf": None,
+    ".docx": "mammoth",
+    ".pptx": "pptx",
+}
+
+_marker_converter = MarkerConverter()
+
+
+def get_converter(filepath: str | Path) -> Converter:
+    """Return the Converter that should handle `filepath`.
+
+    Raises:
+        UnsupportedFormatError: the extension isn't one docmd knows about.
+        MissingExtraError: the extension needs `pip install docmd[full]`.
+    """
+    suffix = Path(filepath).suffix.lower()
+
+    if suffix not in _SUPPORTED_SUFFIXES:
+        raise UnsupportedFormatError(suffix)
+
+    required_module = _SUPPORTED_SUFFIXES[suffix]
+    if required_module and importlib.util.find_spec(required_module) is None:
+        raise MissingExtraError(suffix)
+
+    return _marker_converter

docmd/errors.py

@@ -0,0 +1,60 @@
+"""Error taxonomy for docmd.
+
+Kept flat and explicit (see ARCHITECTURE.md "Error handling") so callers -
+CLI, library, and eventually the hosted API - can catch a small, well-known
+set of exceptions instead of guessing at what a bare Exception means.
+"""
+
+from __future__ import annotations
+
+
+class DocmdError(Exception):
+    """Base class for all docmd errors."""
+
+
+class UnsupportedFormatError(DocmdError):
+    """Raised when the input file extension isn't handled by any converter."""
+
+    def __init__(self, suffix: str) -> None:
+        self.suffix = suffix
+        super().__init__(
+            f"Unsupported file format: '{suffix}'. "
+            "docmd currently supports: .pdf, .docx, .pptx "
+            "(.docx/.pptx require `pip install docmd[full]`)."
+        )
+
+
+class MissingExtraError(DocmdError):
+    """Raised when a format needs the `full` extra and it isn't installed."""
+
+    def __init__(self, suffix: str) -> None:
+        self.suffix = suffix
+        super().__init__(
+            f"'{suffix}' files require the optional dependencies for "
+            "DOCX/PPTX support. Install them with: pip install 'docmd[full]'"
+        )
+
+
+class EncryptedDocumentError(DocmdError):
+    """Raised when the input is a password-protected / encrypted document."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "This document is encrypted or password-protected. "
+            "Remove the password before converting."
+        )
+
+
+class FileTooLargeError(DocmdError):
+    """Raised when a file exceeds a caller-supplied hard size/page limit."""
+
+    def __init__(self, limit_description: str) -> None:
+        super().__init__(f"File too large: exceeds {limit_description}.")
+
+
+class ConversionError(DocmdError):
+    """Raised when the underlying conversion engine fails."""
+
+    def __init__(self, message: str, *, cause: Exception | None = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause

docmd/postprocess/heading_normalize.py

@@ -0,0 +1,76 @@
+"""Heading normalization: docmd's fix for Marker's most common structural
+quirks in raw output - headings that skip levels (H1 -> H3), the same
+section header repeated verbatim right after itself (Marker sometimes turns
+a running page header into a heading on every page), and stray '#' markers
+with no text. None of this is Marker's fault exactly - it's an artifact of
+reconstructing structure from visual layout - but it's exactly the kind of
+thing that makes raw conversion output bad for RAG chunking, where heading
+level is often used to decide chunk boundaries.
+"""
+
+from __future__ import annotations
+
+import re
+
+_ATX_RE = re.compile(r"^(#{1,6})\s*(.*?)\s*$")
+_FENCE_RE = re.compile(r"^\s*(```|~~~)")
+
+
+def normalize_headings(markdown: str) -> str:
+    """Return `markdown` with heading levels and duplicates cleaned up.
+
+    Rules applied, line by line (skipping the contents of fenced code blocks,
+    since a '#' there is a comment/directive, not a heading):
+      1. A heading with no text after the '#'s is dropped.
+      2. A heading level may increase by at most 1 relative to the deepest
+         heading seen so far (H1 -> H3 becomes H1 -> H2), preventing
+         orphaned levels. Decreasing back to any shallower level is always
+         allowed.
+      3. A heading whose text exactly repeats the immediately preceding
+         heading's text (ignoring blank lines between them) is dropped,
+         regardless of level - this is Marker turning a repeated running
+         page header into a heading on every page.
+      4. Spacing after '#' is normalized to exactly one space.
+    """
+    lines = markdown.splitlines()
+    out: list[str] = []
+    last_level = 0
+    last_heading_text: str | None = None
+    in_fence = False
+
+    for line in lines:
+        if _FENCE_RE.match(line):
+            in_fence = not in_fence
+            out.append(line)
+            continue
+        if in_fence:
+            out.append(line)
+            continue
+
+        match = _ATX_RE.match(line)
+        if not match:
+            out.append(line)
+            if line.strip():
+                # Any real content resets "last heading" adjacency, so a
+                # heading appearing after body text is never treated as a
+                # duplicate of one seen much earlier.
+                last_heading_text = None
+            continue
+
+        level = len(match.group(1))
+        text = match.group(2).strip(" \t#")
+
+        if not text:
+            continue  # drop orphaned '#' with no content
+
+        if text == last_heading_text:
+            continue  # drop immediate duplicate heading
+
+        if level > last_level + 1:
+            level = last_level + 1
+
+        last_level = level
+        last_heading_text = text
+        out.append("#" * level + " " + text)
+
+    return "\n".join(out) + ("\n" if markdown.endswith("\n") else "")

docmd/postprocess/image_handling.py

@@ -0,0 +1,54 @@
+"""Image handling: gives RAG pipelines a single, predictable convention for
+what to do with images instead of Marker's raw behavior (an `![](file.jpeg)`
+reference plus a separate dict of image bytes that most callers have no
+plumbing for at all).
+
+Three modes (see docmd.config.ConvertConfig.image_mode):
+  - "placeholder": no binary data anywhere. Each image reference becomes a
+    short, consistent text placeholder - safe to embed/chunk, nothing to
+    resolve.
+  - "alt-text": images are written to disk next to the output and kept as
+    real Markdown image links with guaranteed non-empty alt text.
+  - "skip": the image reference is removed entirely, no placeholder either.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+_IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^)]+)\)")
+
+
+def apply_image_handling(
+    markdown: str,
+    images: dict[str, Any],
+    mode: str,
+    output_dir: str | Path | None = None,
+) -> str:
+    counter = 0
+
+    def _replace(match: re.Match[str]) -> str:
+        nonlocal counter
+        alt_text, ref = match.group(1), match.group(2)
+        filename = Path(ref).name
+
+        if mode == "skip":
+            return ""
+
+        if mode == "placeholder":
+            label = alt_text.strip() or "image"
+            return f"*[{label} omitted]*"
+
+        # mode == "alt-text"
+        counter += 1
+        image = images.get(filename)
+        if image is not None and output_dir is not None:
+            out_path = Path(output_dir) / filename
+            out_path.parent.mkdir(parents=True, exist_ok=True)
+            image.save(out_path)
+        final_alt = alt_text.strip() or f"Image {counter}"
+        return f"![{final_alt}]({ref})"
+
+    return _IMAGE_RE.sub(_replace, markdown)

docmd/postprocess/table_cleanup.py

@@ -0,0 +1,129 @@
+"""Table cleanup: fixes the two most common ways Marker's tables come out
+mangled for complex layouts:
+
+  1. Ragged / malformed structure - a missing or malformed separator row,
+     or data rows with more or fewer cells than the header.
+  2. A single logical table split into two because it spans a page break -
+     Marker (reasonably) treats each page independently, so a table that
+     continues onto the next page comes out as two separate tables, each
+     with its own repeated header row.
+
+Operates on already-rendered Markdown text rather than Marker's internal
+block tree, so it works standalone on any Markdown, not just docmd's own
+output - and keeps this module decoupled from Marker's internals.
+"""
+
+from __future__ import annotations
+
+import re
+
+_FENCE_RE = re.compile(r"^\s*(```|~~~)")
+_SEP_CELL_RE = re.compile(r"^:?-+:?$")
+_PAGE_SEPARATOR = "-" * 48
+
+
+def _is_row(line: str) -> bool:
+    stripped = line.strip()
+    return bool(stripped) and "|" in stripped
+
+
+def _split_cells(line: str) -> list[str]:
+    stripped = line.strip()
+    if stripped.startswith("|"):
+        stripped = stripped[1:]
+    if stripped.endswith("|"):
+        stripped = stripped[:-1]
+    return [cell.strip() for cell in stripped.split("|")]
+
+
+def _is_separator_row(line: str) -> bool:
+    cells = _split_cells(line)
+    return bool(cells) and all(_SEP_CELL_RE.match(c) for c in cells)
+
+
+def _render_row(cells: list[str]) -> str:
+    return "| " + " | ".join(cells) + " |"
+
+
+def _normalize_block(header: list[str], data_rows: list[list[str]]) -> list[str]:
+    """Pad/truncate every row to the header's column count and re-render
+    with a clean separator row."""
+    col_count = len(header)
+    out = [_render_row(header), _render_row(["---"] * col_count)]
+    for row in data_rows:
+        if len(row) < col_count:
+            row = row + [""] * (col_count - len(row))
+        elif len(row) > col_count:
+            row = row[:col_count]
+        out.append(_render_row(row))
+    return out
+
+
+def _headers_match(a: list[str], b: list[str]) -> bool:
+    norm = lambda cells: [c.strip().lower() for c in cells]
+    return norm(a) == norm(b)
+
+
+def clean_tables(markdown: str) -> str:
+    """Return `markdown` with pipe-table structure fixed up, including
+    re-joining tables that were split across a page break."""
+    lines = markdown.splitlines()
+    out: list[str] = []
+    i = 0
+    in_fence = False
+
+    while i < len(lines):
+        line = lines[i]
+
+        if _FENCE_RE.match(line):
+            in_fence = not in_fence
+            out.append(line)
+            i += 1
+            continue
+        if in_fence:
+            out.append(line)
+            i += 1
+            continue
+
+        if not (_is_row(line) and i + 1 < len(lines) and _is_row(lines[i + 1])):
+            out.append(line)
+            i += 1
+            continue
+
+        # Found the start of a table block: header + at least one more row.
+        header = _split_cells(line)
+        j = i + 1
+        if _is_separator_row(lines[j]):
+            j += 1
+        block_end = j
+        while block_end < len(lines) and _is_row(lines[block_end]):
+            block_end += 1
+        data_rows = [_split_cells(l) for l in lines[j:block_end]]
+
+        # Look ahead past blank lines / Marker's page separator for a
+        # continuation: another table block whose header repeats this one.
+        k = block_end
+        while True:
+            probe = k
+            while probe < len(lines) and (
+                not lines[probe].strip() or lines[probe].strip() == _PAGE_SEPARATOR
+            ):
+                probe += 1
+            if not (probe < len(lines) and _is_row(lines[probe]) and probe + 1 < len(lines) and _is_row(lines[probe + 1])):
+                break
+            next_header = _split_cells(lines[probe])
+            if not _headers_match(header, next_header):
+                break
+            p = probe + 1
+            if _is_separator_row(lines[p]):
+                p += 1
+            next_block_end = p
+            while next_block_end < len(lines) and _is_row(lines[next_block_end]):
+                next_block_end += 1
+            data_rows.extend(_split_cells(l) for l in lines[p:next_block_end])
+            k = next_block_end
+
+        out.extend(_normalize_block(header, data_rows))
+        i = k
+
+    return "\n".join(out) + ("\n" if markdown.endswith("\n") else "")

docmd_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: docmd-cli
+Version: 0.1.0
+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
+Author: taherzribi
+License: MIT
+License-File: LICENSE
+Keywords: document-conversion,docx,markdown,pdf,pptx,rag
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: <4,>=3.10
+Requires-Dist: click<9,>=8.2.0
+Requires-Dist: marker-pdf==2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: python-docx>=1.1.0; extra == 'dev'
+Requires-Dist: reportlab>=4.0.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: marker-pdf[full]==2.0.0; extra == 'full'
+Description-Content-Type: text/markdown
+
+# docmd
+
+**Convert PDFs, DOCX, and PPTX to clean, structure-preserving Markdown — from the CLI or a Python library.**
+
+Built for feeding documents into LLM and RAG pipelines, where clean Markdown beats raw text extraction.
+
+*(Published on PyPI as `docmd-cli` since `docmd` was already taken by an unrelated
+package — the import (`import docmd`) and CLI command (`docmd convert ...`) are
+unaffected.)*
+
+```bash
+pip install docmd-cli
+docmd convert report.pdf
+```
+
+```python
+from docmd import convert
+
+markdown = convert("report.pdf")
+print(markdown)
+```
+
+## Why docmd
+
+Great open-source document-to-Markdown converters already exist (docmd is built on
+[Marker](https://github.com/datalab-to/marker)). The problem isn't quality — it's that
+running them yourself means a Python environment, several GB of RAM, ideally a GPU, and
+a non-trivial setup process before you convert your first file.
+
+`docmd` wraps that engine with sane defaults and adds real post-processing on top
+(table cleanup, heading normalization) so the output is closer to what a RAG pipeline
+actually wants, not just raw model output.
+
+A hosted API (`POST` a file, get Markdown back, no local setup) is planned — see
+[ARCHITECTURE.md](ARCHITECTURE.md). It is not live yet; this repo is the open-source
+core, usable standalone today.
+
+## What it handles
+
+| Input | Output |
+|---|---|
+| PDF (text-based) | Markdown with preserved headings, lists, tables |
+| PDF (scanned) | Markdown via OCR — bundled by Marker, free |
+| DOCX | Markdown with formatting preserved (`pip install docmd-cli[full]`) |
+| PPTX | Markdown, one section per slide (`pip install docmd-cli[full]`) |
+
+## Quickstart
+
+**CLI**
+```bash
+pip install docmd-cli
+docmd convert my-file.pdf -o output.md
+```
+
+**Python**
+```python
+from docmd import convert
+
+# From a file path
+markdown = convert("my-file.pdf")
+
+# From bytes
+with open("my-file.pdf", "rb") as f:
+    markdown = convert(f.read(), filename="my-file.pdf")
+```
+
+## Installing DOCX/PPTX support
+
+The base install (`pip install docmd-cli`) covers PDF only and stays lean. DOCX and
+PPTX need Marker's own additional dependencies:
+
+```bash
+pip install "docmd-cli[full]"
+```
+
+DOCX/PPTX conversion also needs [weasyprint](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation)'s
+native Pango/GObject/Cairo libraries, which `pip` cannot install for you:
+
+```bash
+# macOS
+brew install pango
+
+# Debian/Ubuntu
+sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
+```
+
+PDF conversion (the base install) does not need this.
+
+## How it works
+
+`docmd` wraps [Marker](https://github.com/datalab-to/marker) with sane defaults and a
+clean output format, then runs its own post-processing pass
+(`docmd/postprocess/`) to fix table structure and normalize heading levels — see
+[ARCHITECTURE.md](ARCHITECTURE.md) for why this is the actual differentiation, not
+just a thin wrapper.
+
+## License
+
+The `docmd` wrapper code is MIT — see [LICENSE](LICENSE).
+
+`docmd` depends on [Marker](https://github.com/datalab-to/marker), whose *code* is
+Apache-2.0 and whose *model weights* are licensed under a modified Open RAIL-M license:
+free for research, personal use, and organizations under $5M in funding or revenue.
+Commercial use beyond that threshold requires a license from
+[Datalab](https://www.datalab.to/pricing). This applies to you if you deploy `docmd`
+commercially at scale — check Marker's current license terms directly before doing so.
+
+## Roadmap
+
+- [x] PDF, DOCX, PPTX → Markdown
+- [x] Table cleanup / heading normalization post-processing
+- [ ] Hosted API
+- [ ] OCR quality tuning for scanned documents
+- [ ] Batch conversion endpoint
+- [ ] HTML output option
+
+## Contributing
+
+Issues and PRs welcome. If you're hitting a conversion quality issue, please include a
+sample file (or a minimal reproduction) — it makes fixes much faster.
+
+---
+
+*If docmd saves you the trouble of setting up your own PDF-parsing pipeline, consider starring the repo — it's how other people find it.*

docmd_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+docmd/__init__.py,sha256=TZrcYqGJGN0U5ah1pxkxm4k2gM5p4ES-yk7jXq0oGgA,2667
+docmd/cli.py,sha256=UGi_LwInWEbjxRitWgBNZyDsH1Cho4vAH2MxGZj_meI,1889
+docmd/config.py,sha256=0pwnoaLYkjcUFLSJnoWisXkiCQDmEIDcTKlGg3W9Rj0,2183
+docmd/errors.py,sha256=td3wxA2zVz550Ug-a8sp_VjSz9wZM_rCkiY6BZ4Xj5M,1954
+docmd/converters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docmd/converters/base.py,sha256=JE0-r59-WpAjWEBgXgeDUO6fQl3CzD-nrRpstl4cgxk,1113
+docmd/converters/marker_converter.py,sha256=8BgrHce1THHD-0WuvjJMagDaxisjxXbDKbU-KG_A9xg,3126
+docmd/converters/registry.py,sha256=T1jGdnkjRMwusH7LJQ4ilgPeS7_EvlMvJksmzXBEra4,1397
+docmd/postprocess/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docmd/postprocess/heading_normalize.py,sha256=Wlx5vm6pgv95QloqtndTaiVSqJEIJ1HOUe79WnM3vbI,2843
+docmd/postprocess/image_handling.py,sha256=VMI_QCApXjGVrED74HKPQza9M1iOEQwrMn2oatQD0yg,1766
+docmd/postprocess/table_cleanup.py,sha256=3WcV7zPhMIhkqe6VXJbJYvDWLyet6oZOOjPW-SH-tIk,4355
+docmd_cli-0.1.0.dist-info/METADATA,sha256=NasQeeBhGM0PZBcRH4TGXkExNVWPwUJNQppYIkPhEaY,5098
+docmd_cli-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+docmd_cli-0.1.0.dist-info/entry_points.txt,sha256=f555Z7tM7TIhR9s4k-JRR1JoN45V0Kfom7WYvVkWcQ4,41
+docmd_cli-0.1.0.dist-info/licenses/LICENSE,sha256=yj7qe5Hn99la3ZFCwiZ9iL-gPqfdU2h39dbJsRtj0zU,1067
+docmd_cli-0.1.0.dist-info/RECORD,,

docmd_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

docmd_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docmd = docmd.cli:main

docmd_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 taherzribi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.