md2star.preprocessing.lint module
Opt-in LLM-powered Markdown syntax linter (via Ollama).
Resolution policy (off by default):
No flag, or
--no-lint→ skip the lint entirely.--lint+ Ollama installed → run the lint, spawningollama serveand
ollama pull-ing the default model on demand if either is missing.
--lint+ Ollama missing → print a one-line warning on stderr andfall back to the original Markdown so the overall conversion still succeeds.
The opt-in default keeps conversions deterministic and side-effect-free.
Pass --lint explicitly when you want the LLM to fix obvious syntax
issues (broken image links, unclosed code fences, malformed table pipes)
before Pandoc parses the file.
When enabled, lint_with_llm() sends the document to Ollama and keeps
the response only if it passes a coarse length-sanity check (0.5×–2× of
the original). Any failure (network error, suspicious output, pull failure)
falls back to the original content unchanged — the lint is never
load-bearing for a successful conversion.
The default model is chosen by the suite’s model picker,
best_engine_ai_helper.text_model() — it returns the text model persisted by
best-engine-ai-helper pull for this machine, or a safe multimodal default
(qwen3-vl:8b) when detection has never run. Set the MD2STAR_LINT_MODEL
env variable to override the default tag without editing code (useful on
private registries or for trying a larger model).
Transport is transparent: with the optional md2star[ai] extra installed
the request goes through the official ollama Python client (via
md2star.preprocessing._ollama_client); without it the same request is
sent with a hand-rolled urllib.request POST. Behaviour is identical
either way — the extra only buys the ergonomic typed client, never a
different result.
- md2star.preprocessing.lint.is_ollama_installed()[source]
True iff the
ollamabinary is reachable onPATH.Used as the auto-enable gate for lint: if the user does not have Ollama installed at all, we stay completely silent. If they do, we take care of starting the daemon and pulling the model on demand — the rationale being “the tool is here, so use it without asking”.
- Return type:
- md2star.preprocessing.lint.lint_with_llm(content, model=None)[source]
Send content to Ollama for syntax-only fixes; return original on any failure.
The 0.5×–2× length guard is a coarse hallucination/truncation check; if the response strays outside that band, the original is kept. The full resolution path is: Ollama missing → warn + fall back to original; daemon down → spawn it; model missing →
ollama pullit; then run the request. model defaults toDEFAULT_LINT_MODEL(which honors theMD2STAR_LINT_MODELenv override).