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 engine cannot be resolved, the backend/vision model is unreachable, mmdc or an SVG rasteriser is absent, every image degrades to the plain scraped PNG — exactly what the deterministic core would have produced. The backend and vision model come entirely from md2star’s resolved engine descriptor (md2star._engine, the committed llm.brief.yaml → per-machine llm.engine.yaml contract); 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.

A light “can we resolve an engine?” probe: md2star’s brief -> engine contract must resolve to a descriptor that carries a usable vlm model. Resolution happens once and is cached, so this is cheap enough to call before offering the feature in a UI or CLI --diagrams flag. Any failure (missing brief, no reachable backend/model) → False, and the twin keeps plain PNGs.

The model argument is accepted for signature compatibility with the CLI’s --model override; the concrete tag otherwise comes from the engine.

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 override. When None the tag comes from md2star’s resolved engine descriptor.

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

  • vlm (optional) – Injectable transport/renderer seams (defaults route the vision calls through the resolved engine and Mermaid through mmdc). Supplying fakes makes the whole layer unit-testable offline.

  • render (optional) – Injectable transport/renderer seams (defaults route the vision calls through the resolved engine and Mermaid through 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