md2star.reverse_diagrams module

AI diagram layer for the Markdown twin: classify, then reconstruct.

The deterministic twin core (md2star.reverse) scrapes every raster a document carries and, by default, re-embeds each one verbatim as a PNG. This module is the opt-in layer that makes the twin editable: it looks at each scraped raster with a local vision model and decides what it really is —

  • a photo (a screenshot, a portrait, a product shot): keep the PNG as-is;

  • a diagram expressible as a graph (a flowchart, a sequence/box-and-arrow schematic): re-author it as Mermaid so it lives in the twin as code, round-trips through md2star’s forward path, and diffs cleanly in git;

  • a figure that is not a node-and-edge graph but is still clean vector art (a chart, plot, logo, icon, line drawing): re-author it as an editable SVG written alongside the scraped PNG, so the figure becomes a first-class, hand-tweakable vector asset instead of a flattened raster.

Reconstruction is verified, not trusted. Each candidate — Mermaid or SVG — is put through a target-matching Ralph Eyeball Loop: render the candidate (the vendored mmdc for Mermaid, a detected SVG rasteriser for SVG), show both the candidate render and the original scraped image to the vision model, ask what differs, and feed the discrepancies back to the text model to revise the source. The loop repeats until the model reports a match or the iteration budget is spent. On anything short of a confident match the twin keeps the scraped PNG as a caption fallback, so a poor reconstruction never loses the ground truth.

Everything here is best-effort and never load-bearing: if the [ai] stack, the Ollama daemon, the vision model, mmdc or an SVG rasteriser is absent, every image degrades to the plain scraped PNG — exactly what the deterministic core would have produced. Models are chosen by the suite picker (best_engine_ai_helper); nothing is hard-coded.

The public entry point is make_diagram_handler(), which returns an md2star.reverse.ImageHandler ready to hand to md2star.reverse.to_markdown_twin(). All model/render calls are threaded through injectable seams (vlm / render) so the loop is unit-testable offline with fakes, no live daemon required.

Author

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

class md2star.reverse_diagrams.DiagramHandler(vlm, render, max_iterations=3)[source]

Bases: object

Stateful ImageHandler that classifies and reconstructs rasters.

Instances are callables compatible with md2star.reverse.to_markdown_twin()’s image_handler seam. The scraped PNG is always written (it is the fallback and the ground truth); the Markdown returned is a Mermaid block for a reconstructed diagram, a link to a re-authored .svg for a reconstructed figure (each with a commented PNG fallback), or a plain image link for a photo / anything that could not be reconstructed.

Parameters:
max_iterations: int = 3
render: Callable[[str, str], str | None]
vlm: Callable[[str, list[str]], str | None]
md2star.reverse_diagrams.diagrams_available(model=None)[source]

Return True when diagram reconstruction can actually run.

Checks the same pre-flight gates the alt-text pass uses (Ollama installed, daemon reachable, model pulled). Cheap enough to call before offering the feature in a UI or CLI --diagrams flag.

Parameters:

model (str | None)

Return type:

bool

md2star.reverse_diagrams.make_diagram_handler(*, model=None, max_iterations=3, vlm=None, render=None)[source]

Return an ImageHandler that classifies and reconstructs diagrams.

Parameters:

  • model (str, optional) – Vision model tag. Defaults to the suite picker’s choice.

  • max_iterations (int, default 3) – Eyeball-loop budget per diagram.

  • vlm (optional) – Injectable transport/renderer seams (defaults talk to Ollama + mmdc). Supplying fakes makes the whole layer unit-testable offline.

  • render (optional) – Injectable transport/renderer seams (defaults talk to Ollama + mmdc). Supplying fakes makes the whole layer unit-testable offline.

Returns:

A callable ready for md2star.reverse.to_markdown_twin().

Return type:

ImageHandler

md2star.reverse_diagrams.reconstruct_mermaid(target_png, *, vlm, render, max_iterations=3)[source]

Re-author target_png as Mermaid via the target-matching eyeball loop.

Thin wrapper over _reconstruct() with the Mermaid prompts/extractor. Returns the best Mermaid source, or None when nothing usable was drafted.

Parameters:
Return type:

str | None

md2star.reverse_diagrams.reconstruct_svg(target_png, *, vlm, render, max_iterations=3)[source]

Re-author target_png as an SVG figure via the target-matching loop.

Thin wrapper over _reconstruct() with the SVG prompts/extractor. Returns the best <svg>...</svg> source, or None when nothing usable was drafted (or no <svg> element could be parsed from the reply).

Parameters:
Return type:

str | None