md2star.preprocessing.alt_text module

Opt-in alt-text drafting for empty image alts via a local vision model.

Gated by the same --lint flag as md2star.preprocessing.lint:

  • No flag, or --no-lint → skip the pass entirely.

  • --lint → describe each ![](src) whose alt is empty

    and whose src resolves to a readable local file; URLs / data URIs / missing files / non-empty alts pass through untouched.

  • Any failure (engine unresolved, model unreachable, empty generation) → the affected image is left untouched; the pass is never load-bearing.

Language + context (aligned with the suite’s front-vision skill):

  • The alt text is written in the document’s own language, auto-detected from the surrounding prose (any language, not a hardcoded EN/FR toggle) — a French document gets French alt text. English is the fallback when detection fails.

  • Each image’s surrounding text (nearest heading + nearby prose) is passed to the model so it describes what the image means in place, not just its pixels.

The vision model and backend come entirely from md2star’s resolved engine descriptor (md2star._engine): the committed llm.brief.yaml is resolved to a per-machine llm.engine.yaml on first use, and the request goes through best_engine_ai_helper.llm.chat() (kind="vlm"). Nothing is hard-coded here, and the transport owns the daemon/serving lifecycle.

Per-image results are cached in $XDG_CACHE_HOME/md2star/alt-text/ keyed by <image-md5>_<model>_<lang+context-hash>.txt so a re-run in a different language or surrounding context re-drafts rather than serving a stale caption.

Author

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

md2star.preprocessing.alt_text.fill_empty_alt_text(content, base_dir='.', model=None)[source]

Replace ![](src) empty-alt images with an LLM-generated description.

Mirrors md2star.preprocessing.lint.lint_with_llm()’s safety net: the model call in _generate_alt() swallows every failure (engine unresolvable, backend/model unreachable, transport error) into None, and each such image is left untouched. The pass is never load-bearing. model is an optional per-call vision-model tag override; when None the tag comes from md2star’s resolved engine descriptor.

Parameters:

  • content (str)

  • base_dir (str)

  • model (str | None)

Return type:

str