md2star.twin_cli module

md2star twin: read any document back into an editable Markdown twin.

The forward path turns Markdown into a polished DOCX/PPTX/PDF. This is the inverse as a document, not just as text: given a PDF (or anything LibreOffice can convert to one), it recovers prose + GFM tables, scrapes every embedded raster back out as PNGs, and (with --diagrams) re-authors node-and-edge figures as Mermaid via the target-matching eyeball loop. The result is a <stem>.md plus an assets/ folder you can edit and re-render.

Thin adapter over md2star.reverse.to_markdown_twin() and md2star.reverse_diagrams.make_diagram_handler(); kept out of md2star.cli so the reverse feature imports lazily and the md2star twin command stays a one-liner. The flags are parsed by click, there, once — this module receives them typed.

Author

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

md2star.twin_cli.run(input_path, *, out_dir=None, no_images=False, diagrams=False, model=None, max_iterations=3, verbose=False, quiet=False)[source]

Recover input_path as an editable Markdown twin. Returns an exit code.

Parameters:

  • input_path (str) – Document to recover: a PDF, or anything LibreOffice can print to one.

  • out_dir (str or None, optional) – Where <stem>.md + assets/ are written. An output folder rather than a file, because the twin is two things. None puts them next to the input.

  • no_images (bool, optional) – Recover prose + tables only, dropping the scraped rasters.

  • diagrams (bool, optional) – Re-author figures through the local VLM eyeball loop — node-and-edge diagrams as Mermaid, other vector figures as SVG. The one option that pulls in the AI stack, hence off by default.

  • model (str or None, optional) – Vision model tag for diagrams. None lets best-engine-ai-helper pick per host.

  • max_iterations (int, optional) – Cap on render→compare→revise cycles, so a stubborn diagram cannot spin forever.

  • verbose (bool, optional) – Logging threshold, wired through the shared configuration.

  • quiet (bool, optional) – Logging threshold, wired through the shared configuration.

Returns:

0 and the twin’s path on stdout; 2 for a missing input, 127 for a missing system tool, 1 for any other recovery failure.

Return type:

int