Module ai 

VLM-based image understanding and AI-assisted markdown refine — active only when a caller supplies an AiConfig. Neither capability touches the network unless called explicitly; there is no ambient behavior change for a caller that never constructs a config.

The two capabilities

Capability	Input → output	Where a caller wires it
understand_image	image bytes → structured content or a description	The parsing stage, for an image whose surrounding text extraction produced nothing (or, at a caller’s option, every embedded image)
refine_markdown	markdown → markdown	Render post-processing, after crate::refine::refine (feature refine) if that runs too

Why this lives here and not in crate::refine or the crate root

The crate root (crate::ffi, crate::kind, crate::scaffold) is linked unconditionally by three published cdylibs and stays dependency-free by design — an HTTP client and JSON serialization do not belong there. crate::refine guarantees losslessness and idempotence for a deterministic pass; a generative call cannot honor either invariant, so it is a separate feature rather than a mode of that one.

Native only

This feature is not available on wasm32-unknown-unknown: its HTTP client (ureq) does not build for that target. A browser caller would need fetch JS interop, which is not implemented here — see the crate’s CI, which checks refine on wasm32 but does not attempt ai there.

What this module does not do

It does not decide which images to send, or when a page’s extracted text counts as “nothing” — those are domain judgments that belong to a caller (unpdf’s wiring, say), not to this crate. AiConfig::image_scope exists so a caller can carry that decision alongside the rest of the configuration; this module never reads it.

Structs

AiConfig

Configuration for super::understand_image and super::refine_markdown.

ImageContext

Text surrounding the image, for understand_image’s description branch — a caption-less photo described with “a bar chart” is far less useful than one described with the surrounding paragraph’s subject folded in.

RefineAiOptions

Options for refine_markdown.

TableBlock

A table extracted from a ImageUnderstanding::Structured image.

TableCellBlock

One cell of a TableBlock.

Enums

ContentBlock

One block of content extracted from a ImageUnderstanding::Structured image.

Error

Why a call to super::understand_image or super::refine_markdown failed.

ImageScope

Which images super::understand_image is meant to be called for.

ImageUnderstanding

What understand_image judged the image to be.

Functions

refine_markdown

Rewrites markdown with a generative pass, per options.

understand_image

Judges image as a document scan or a general image, and extracts or describes it accordingly, in a single call.