md2star.reverse module

Reverse conversion: DOCX / PPTX / PDF → Markdown.

md2star’s main direction is Markdown → polished document. This module is the other direction: take an existing .docx, .pptx or .pdf and read it back into Markdown, so a user can drop a finished document into the GUI and recover an editable Markdown source of truth.

The extraction is delegated to Kreuzberg, a document-understanding engine that already backs md2star’s round-trip OCR test. Kreuzberg can emit Markdown directly (ExtractionConfig(output_format=OutputFormat.MARKDOWN)), including OCR of scanned/image-only PDFs, so md2star adds only a thin, well-guarded wrapper.

Kreuzberg is an optional runtime dependency (heavy: a Rust core plus OCR). It is not in md2star’s base install; enable this feature with:

pip install 'md2star[ocr]'

Every entry point degrades gracefully when it is absent: reverse_available() returns False and to_markdown() raises a clear ReverseUnavailable with the install hint, so callers (CLI, API, GUI) can surface a helpful message instead of crashing.

Author

[Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui/)

exception md2star.reverse.ReverseUnavailable[source]

Bases: RuntimeError

Raised when reverse conversion is requested but Kreuzberg is not installed.

class md2star.reverse.TwinExtraction(markdown, images=<factory>)[source]

Bases: object

Raw result of reading a document back: Markdown body + scraped images.

This is the pre-assembly view — the Markdown still carries Kreuzberg’s ![](image_N.ext) placeholders. to_markdown_twin() resolves those against images and the active image handler.

Parameters:

markdown (str)
images (list[TwinImage])

images: list[TwinImage]

markdown: str

class md2star.reverse.TwinImage(data, format, image_index, page_number=0, width=0, height=0, colorspace='')[source]

Bases: object

One raster scraped from the source document.

Mirrors the dict Kreuzberg returns for an extracted image, typed so callers (and the ImageHandler seam) get attribute access and editor tooling.

Parameters:

data (bytes)
format (str)
image_index (int)
page_number (int)
width (int)
height (int)
colorspace (str)

colorspace: str = ''

data: bytes

format: str

height: int = 0

image_index: int

page_number: int = 0

property suggested_name: str

Deterministic, collision-free asset filename for this image.

Keyed on page + index so two runs over the same document produce the same asset paths (stable git diffs — the whole point of the twin).

width: int = 0

md2star.reverse.extract_twin(path)[source]

Read path back into Markdown plus its scraped rasters.

Unlike to_markdown(), this asks Kreuzberg to extract embedded images (with in-text placeholders) and to recover document structure, so tables come back as GFM pipe tables and every figure is available for re-embedding or reconstruction. Non-native inputs are normalized to PDF first.

Parameters:

path (str or Path) – Any PDF, or a document LibreOffice can convert to one.

Returns:

The Markdown body (still carrying ![](image_N.ext) placeholders) and the list of TwinImage rasters.

Return type:

TwinExtraction

Raises:

ReverseUnavailable – When the optional Kreuzberg dependency is not installed.
FileNotFoundError – When path does not exist.
MissingDependencyError – When a non-native input needs LibreOffice and it is absent.
RuntimeError – When Kreuzberg (or the soffice pre-convert) fails.

md2star.reverse.is_supported(path)[source]

Return True when path’s extension is one md2star reads back.

Parameters:: path (str | Path)
Return type:: bool

md2star.reverse.reverse_available()[source]

Return True when the optional Kreuzberg engine can be imported.

Cheap and side-effect-free: it only checks importability (no extraction, no subprocess), so callers can use it to show/hide the feature in a UI or in doctor output without paying Kreuzberg’s runtime cost.

Return type:: bool

md2star.reverse.to_markdown(path)[source]

Extract path (a DOCX/PPTX/PDF) to Markdown text.

Parameters:

path (str or Path) – The document to read back. Its extension must be one of SUPPORTED_REVERSE_EXTENSIONS.

Returns:

The document’s content rendered as Markdown (headings, bold/italic, lists and tables preserved as far as Kreuzberg can recover them).

Return type:

str

Raises:

ReverseUnavailable – When the optional Kreuzberg dependency is not installed.
FileNotFoundError – When path does not exist.
ValueError – When path’s extension is not a supported input format.
RuntimeError – When Kreuzberg fails to extract the document.

md2star.reverse.to_markdown_twin(path, out_dir, *, extract_images=True, image_handler=None, assets_dirname='assets')[source]

Write path’s Markdown twin (<stem>.md + assets/) into out_dir.

Parameters:

path (str or Path) – The document to recover — a PDF or anything convertible to one.
out_dir (str or Path) – Destination folder. Created if absent; the .md and the assets directory are written directly inside it.
extract_images (bool, default True) – When False, scraped rasters are dropped and only prose + tables are kept (equivalent to the classic text-only reverse, but via the twin config).
image_handler (ImageHandler, optional) – Override how each scraped raster becomes Markdown. Defaults to _default_image_handler() (write PNG + link). The AI diagram layer injects its classifier/reconstructor here.
assets_dirname (str, default "assets") – Name of the sub-folder that holds scraped/reconstructed image assets.

Returns:

The written <stem>.md file.

Return type:

Path