Skip to main content

docling/
converter.rs

1//! The top-level `DocumentConverter`.
2
3use std::collections::HashSet;
4use std::path::PathBuf;
5
6use crate::backend::{
7    is_deepseek_markdown, AbwBackend, AsciiDocBackend, CsvBackend, DeclarativeBackend,
8    DeepSeekBackend, DocBackend, DoclingJsonBackend, DocxBackend, EbcdicBackend, EmailBackend,
9    EpubBackend, InterchangeBackend, JatsBackend, LatexBackend, LotusBackend, MarkdownBackend,
10    MhtmlBackend, PptBackend, PptxBackend, QuattroBackend, RtfBackend, StarOffice5Backend,
11    UsptoBackend, VisioBackend, WebVttBackend, WpdBackend, WpsBackend, XlsBackend, XlsxBackend,
12};
13
14/// Drop the embedded image bytes from every picture — the flat nodes and the
15/// item tree alike — for [`DocumentConverter::keep_picture_images`]`(false)`.
16/// The picture items stay (caption, OCR text, classification, geometry);
17/// only their payload goes, so the JSON writes no `image` and Markdown's
18/// embedded mode prints the placeholder.
19fn strip_picture_images(document: &mut docling_core::DoclingDocument) {
20    document.for_each_picture_mut(&mut |node| {
21        if let docling_core::Node::Picture { image, .. } = node {
22            *image = None;
23        }
24    });
25    if let Some(tree) = document.tree.as_mut() {
26        for item in tree.items.iter_mut() {
27            if let docling_core::tree::TreeKind::Picture { image, .. } = &mut item.kind {
28                *image = None;
29            }
30        }
31    }
32}
33
34/// The picture-OCR reader (#645): the OCR models behind the size floor and
35/// the classifier filter, with a by-bytes cache so the same image embedded
36/// twice is read once. Built by [`DocumentConverter::picture_reader`].
37#[cfg(feature = "pdf")]
38struct PictureReader {
39    pipeline: docling_pdf::Pipeline,
40    min_side: u32,
41    classes: Vec<String>,
42    cache: std::collections::HashMap<u64, Option<docling_core::PictureDescription>>,
43}
44
45#[cfg(feature = "pdf")]
46impl PictureReader {
47    /// The text read off `img`, as the picture's description annotation;
48    /// `None` when the picture is skipped (too small, filtered out by its
49    /// class) or carries no text.
50    fn read(
51        &mut self,
52        img: &docling_core::PictureImage,
53    ) -> Option<docling_core::PictureDescription> {
54        use std::hash::{Hash, Hasher};
55        let mut h = std::collections::hash_map::DefaultHasher::new();
56        img.data.hash(&mut h);
57        let key = h.finish();
58        if let Some(hit) = self.cache.get(&key) {
59            return hit.clone();
60        }
61        let text = self.read_uncached(img);
62        self.cache.insert(key, text.clone());
63        text
64    }
65
66    fn read_uncached(
67        &mut self,
68        img: &docling_core::PictureImage,
69    ) -> Option<docling_core::PictureDescription> {
70        // The declared size is a hint; the decoded one is the truth
71        // (a 16 × 16 icon is skipped before any inference).
72        if img.width.min(img.height) < self.min_side && img.width * img.height > 0 {
73            return None;
74        }
75        let decoded = match self.pipeline.decode_picture(&img.data) {
76            Ok(d) => d,
77            Err(e) => {
78                docling_core::debug_log!("docling: picture OCR: undecodable image: {e}");
79                return None;
80            }
81        };
82        if decoded.width().min(decoded.height()) < self.min_side {
83            return None;
84        }
85        // The loader warned once when the classifier is missing; an
86        // unclassifiable picture is read rather than silently skipped.
87        if !self.classes.is_empty() {
88            if let Some(preds) = self.pipeline.classify_picture(&decoded) {
89                let top = preds.first().map(|p| p.class_name.as_str());
90                if !top.is_some_and(|t| self.classes.iter().any(|c| c == t)) {
91                    return None;
92                }
93            }
94        }
95        match self.pipeline.ocr_picture(&decoded) {
96            Ok(Some(t)) => Some(docling_core::PictureDescription {
97                text: t.text,
98                provenance: t.provenance.to_string(),
99            }),
100            Ok(None) => None,
101            Err(e) => {
102                eprintln!("warning: picture OCR failed: {e}");
103                None
104            }
105        }
106    }
107}
108
109/// Without the `pdf` feature there is no reader; the type exists so the
110/// callers compile unchanged.
111#[cfg(not(feature = "pdf"))]
112struct PictureReader;
113
114#[cfg(not(feature = "pdf"))]
115impl PictureReader {
116    fn read(
117        &mut self,
118        _img: &docling_core::PictureImage,
119    ) -> Option<docling_core::PictureDescription> {
120        None
121    }
122}
123
124/// The image type by its magic bytes, for the four the vision endpoints
125/// take (OpenAI's `image_url` set: PNG, JPEG, GIF, WebP) plus BMP and TIFF,
126/// which [`endpoint_image`] re-encodes.
127#[cfg(feature = "vlm")]
128fn image_mimetype(bytes: &[u8]) -> Option<&'static str> {
129    match bytes {
130        [0x89, b'P', b'N', b'G', ..] => Some("image/png"),
131        [0xFF, 0xD8, 0xFF, ..] => Some("image/jpeg"),
132        [b'G', b'I', b'F', b'8', ..] => Some("image/gif"),
133        [b'R', b'I', b'F', b'F', _, _, _, _, b'W', b'E', b'B', b'P', ..] => Some("image/webp"),
134        [b'B', b'M', ..] => Some("image/bmp"),
135        [b'I', b'I', 0x2A, 0x00, ..] | [b'M', b'M', 0x00, 0x2A, ..] => Some("image/tiff"),
136        _ => None,
137    }
138}
139
140/// `img` as the endpoint takes it: PNG/JPEG/GIF/WebP bytes as they are
141/// (the type read off the bytes, not the declared one — an office file's
142/// `image/jpg` or a mislabelled PNG), BMP/TIFF re-encoded as PNG, anything
143/// else (EMF/WMF, SVG, …) `None`.
144#[cfg(feature = "vlm")]
145fn endpoint_image(
146    img: &docling_core::PictureImage,
147) -> Option<(&'static str, std::borrow::Cow<'_, [u8]>)> {
148    match image_mimetype(&img.data)? {
149        m @ ("image/png" | "image/jpeg" | "image/gif" | "image/webp") => {
150            Some((m, std::borrow::Cow::Borrowed(&img.data)))
151        }
152        _ => {
153            let decoded = image::load_from_memory(&img.data).ok()?;
154            let mut buf = std::io::Cursor::new(Vec::new());
155            decoded.write_to(&mut buf, image::ImageFormat::Png).ok()?;
156            Some(("image/png", std::borrow::Cow::Owned(buf.into_inner())))
157        }
158    }
159}
160
161/// Whether `text` begins with an XML prolog — an `<?xml …?>` declaration or a
162/// non-HTML `<!DOCTYPE …>`. Used to route XML documents that arrived with a
163/// text/Markdown extension (e.g. a JATS article saved as `.txt`) to the XML
164/// backends. An HTML5 `<!DOCTYPE html>` is deliberately excluded.
165fn looks_like_xml(text: &str) -> bool {
166    let head = text.trim_start();
167    if head.starts_with("<?xml") {
168        return true;
169    }
170    if let Some(rest) = head.get(..9) {
171        if rest.eq_ignore_ascii_case("<!doctype") {
172            return !head[9..]
173                .trim_start()
174                .to_ascii_lowercase()
175                .starts_with("html");
176        }
177    }
178    false
179}
180
181/// Whether an XML document is a JATS article: a JATS DOCTYPE, or an
182/// `<article` root element (JATS files in the wild often carry no DOCTYPE).
183fn looks_like_jats(bytes: &[u8]) -> bool {
184    let head = String::from_utf8_lossy(&bytes[..bytes.len().min(4000)]);
185    has_jats_doctype(&head) || head.contains("<article")
186}
187
188/// Pick the concrete XML backend for a generic `.xml` source by sniffing its
189/// DOCTYPE / root element (the first part of the file).
190/// docling's `_guess_from_content` JATS rule for an `application/xml` input:
191/// the `<!DOCTYPE …>` declaration names a JATS DTD.
192fn has_jats_doctype(text: &str) -> bool {
193    let Some(start) = text.find("<!DOCTYPE ") else {
194        return false;
195    };
196    let Some(len) = text[start..].find('>') else {
197        return false;
198    };
199    let doctype = &text[start..start + len];
200    doctype.contains("JATS-journalpublishing") || doctype.contains("JATS-archive")
201}
202
203fn sniff_xml(bytes: &[u8]) -> InputFormat {
204    // Lossy over the raw head (docling#4038, 2.122): the window can cut a
205    // well-formed file mid-codepoint — a fixed-offset `&str` slice would
206    // panic on that char boundary — and an XML document may legitimately
207    // declare a non-UTF-8 encoding. Every marker matched below is ASCII, so
208    // replacement characters cannot change the outcome.
209    let head = String::from_utf8_lossy(&bytes[..bytes.len().min(4000)]);
210    let head = head.as_ref();
211    // Case-insensitive: USPTO DOCTYPE/root casing varies in the wild (docling
212    // PR #3801 — Grant Full Text v2.5 files were missed on casing).
213    let lower = head.to_ascii_lowercase();
214    if lower.contains("us-patent")
215        || lower.contains("patent-application-publication")
216        || lower.contains("patdoc")
217        || lower.contains("<pap-v1")
218    {
219        InputFormat::XmlUspto
220    } else if head.contains("<doclang") {
221        // A bare DocLang document saved as `.xml` (docling names them
222        // `*.dclg.xml`, whose final extension is plain `xml`).
223        InputFormat::XmlDoclang
224    } else if crate::backend::feed::looks_like_feed(head) {
225        // An RSS / Atom / RDF feed (#678), by its root element.
226        InputFormat::Feed
227    } else if crate::backend::xbrl::looks_like_xbrl(head) {
228        InputFormat::XmlXbrl
229    } else {
230        InputFormat::XmlJats
231    }
232}
233use crate::error::ConversionError;
234use crate::format::InputFormat;
235use crate::result::{ConversionResult, ConversionStatus};
236use crate::source::SourceDocument;
237#[cfg(feature = "pdf")]
238use crate::stream::MarkdownStream;
239#[cfg(feature = "pdf")]
240use docling_core::{ImageMode, MarkdownExportOptions};
241
242/// Routes a [`SourceDocument`] to the backend for its format and returns a
243/// [`ConversionResult`].
244///
245/// The Rust analogue of `docling.document_converter.DocumentConverter`. In
246/// Phase 0 the format→backend dispatch is a direct match; the Python notion of
247/// per-format `FormatOption` (backend + pipeline + options) arrives with the
248/// PDF/ML pipeline in a later phase.
249#[derive(Debug, Clone)]
250pub struct DocumentConverter {
251    allowed_formats: Option<HashSet<InputFormat>>,
252    strict: bool,
253    /// Which image references the declarative backends may resolve (#646):
254    /// the tier, the remote host allow-list and the limit overrides. See
255    /// [`Self::image_sources`]; [`Self::fetch_images`] is the pre-#646 switch.
256    image_sources: crate::ImageSources,
257    image_hosts: Vec<String>,
258    image_limits: ImageLimitOverrides,
259    list_attachments: bool,
260    /// Omit empty cells from sparse spreadsheet table grids (#271, XLSX/XLS
261    /// family; opt-in docling.rs extension).
262    skip_empty_cells: bool,
263    /// Emit Markdown tables in the compact `| a | b |` form instead of the
264    /// width-padded GitHub serializer (#271, opt-in docling.rs extension).
265    compact_tables: bool,
266    /// Render pictures' alt text in Markdown and HTML (#676). See
267    /// [`Self::picture_alt_text`].
268    picture_alt_text: bool,
269    /// Where the document's metadata goes in the exports (#679). See
270    /// [`Self::metadata_output`].
271    metadata_output: docling_core::MetadataOutput,
272    /// docling-core's `MarkdownParams.page_break_placeholder`: text inserted
273    /// between pages in the Markdown export; `None` (default) omits breaks.
274    page_break_placeholder: Option<String>,
275    /// EBCDIC copybook layout (#252): inline JSON or a file path. `None`
276    /// falls back to the `<stem>.layout.json` sidecar.
277    ebcdic_layout: Option<String>,
278    no_table_former: bool,
279    no_text_panels: bool,
280    /// The text layer only, no models (#611: `--text-layer-only`, the
281    /// pre-2.0 `--no-ocr`).
282    text_layer_only: bool,
283    /// Skip OCR, keep layout and tables — docling's `do_ocr=False` (#611:
284    /// `--no-ocr`, `--skip-ocr`).
285    no_ocr: bool,
286    /// The password of an encrypted PDF (#611) or Office document (#625).
287    password: Option<String>,
288    force_full_page_ocr: bool,
289    /// OCR mode id (docling's `OcrMode`, #254); parsed at the ML call sites.
290    ocr_mode: Option<String>,
291    /// OCR engine id (`ppocr` | `tesseract`, #460); parsed at the ML call
292    /// sites.
293    ocr_engine: Option<String>,
294    /// OCR render scale in px/pt (#254); validated at the ML call sites.
295    ocr_scale: Option<f32>,
296    /// RapidOCR's line orientation handling (#666); `None` = the
297    /// environment's default. See [`Self::ocr_textline_orientation`].
298    ocr_textline_orientation: Option<bool>,
299    /// Picture-crop / page-image scale in px/pt (docling's `images_scale`,
300    /// #520); `None` = the pipeline's 2.0 render.
301    images_scale: Option<f32>,
302    /// Keep page renders as the document's page images (docling's
303    /// `generate_page_images`, #520).
304    generate_page_images: bool,
305    /// Infer PDF/image section-header levels after assembly (#302, docling's
306    /// `HeadingHierarchyModel`): bookmarks > numbering > font style. Off by
307    /// default — heading levels then stay exactly as detected.
308    heading_hierarchy: bool,
309    use_web_browser: bool,
310    /// Named Whisper model preset for audio sources (docling's ASR model
311    /// specs, PR #3741): English-only / Distil-Whisper variants under
312    /// `.models/asr/<preset>/`. `None` = the default Whisper tiny.
313    asr_model: Option<String>,
314    asr_lang: Option<String>,
315    /// Max sampled frames per video (#138 Phase 2). `None` = the default
316    /// ([`DEFAULT_VIDEO_FRAMES`]); `Some(0)` disables frame extraction;
317    /// [`ALL_VIDEO_FRAMES`] keeps every distinct cut (#647).
318    video_frames: Option<usize>,
319    /// ffmpeg's scene score a video frame must exceed to count as a cut
320    /// (#647); `None` = `DOCLING_RS_VIDEO_SCENE_THRESHOLD`, else 0.27.
321    video_scene_threshold: Option<f32>,
322    /// Cap on a sampled frame's longer side in px (#647); `None` =
323    /// `DOCLING_RS_VIDEO_FRAME_MAX_SIDE`, else the source resolution.
324    video_frame_max_side: Option<u32>,
325    /// Hamming distance under which a frame's difference hash makes it a
326    /// duplicate of a kept one (#647); `None` = `DOCLING_RS_VIDEO_FRAME_DEDUPE`,
327    /// else no de-duplication.
328    video_frame_dedupe: Option<u32>,
329    /// The directory an XBRL instance's taxonomy is read from (docling's
330    /// `XBRLBackendOptions.taxonomy`); `None` = the instance's own directory.
331    xbrl_taxonomy: Option<PathBuf>,
332    /// Opt-in PDF/image enrichment models (docling's
333    /// `do_picture_classification` / `do_code_enrichment` /
334    /// `do_formula_enrichment`).
335    enrich: crate::EnrichmentOptions,
336    /// OCR the embedded pictures of non-PDF documents (#645). See
337    /// [`Self::do_picture_ocr`].
338    picture_ocr: bool,
339    /// DocumentFigureClassifier labels a picture must carry to be OCR'd;
340    /// empty = every picture. See [`Self::picture_ocr_classes`].
341    picture_ocr_classes: Vec<String>,
342    /// Smallest side (px) a picture must have to be OCR'd; `None` = the
343    /// environment's default. See [`Self::picture_ocr_min_side`].
344    picture_ocr_min_side: Option<u32>,
345    /// The picture OCR's resolution (#666); `None` = the image-input rule.
346    /// See [`Self::picture_ocr_scale`].
347    picture_ocr_scale: Option<f32>,
348    /// Keep the embedded image bytes on every picture (the default). See
349    /// [`Self::keep_picture_images`].
350    keep_picture_images: bool,
351    /// Describe the pictures through a vision endpoint (#670); `None` = off.
352    /// See [`Self::picture_description`].
353    #[cfg(feature = "vlm")]
354    picture_description: Option<crate::vlm::PictureDescriptionOptions>,
355    /// The PII redaction pass (#621), when asked for. See [`Self::redact_pii`].
356    redact: Option<docling_core::RedactionOptions>,
357    /// 1-based inclusive PDF page window (#80). See [`Self::page_range`].
358    page_range: Option<(usize, usize)>,
359    /// OCR recognition language for scanned PDF/image pages (`en`/`ch`).
360    /// `None` = the process default (`DOCLING_RS_OCR_LANG`, else English).
361    ocr_lang: Option<String>,
362    /// Character encoding for text inputs (docling's
363    /// `TextBackendOptions.encoding`); `None` = detect. See [`Self::encoding`].
364    encoding: Option<String>,
365    /// Which Jupyter notebook outputs the document keeps (#673). See
366    /// [`Self::ipynb_outputs`].
367    ipynb_outputs: crate::IpynbOutputs,
368    /// Directory referenced-mode streaming writes images into (#80).
369    /// See [`Self::artifacts_dir`].
370    artifacts_dir: String,
371    /// Per-document wall-clock budget for the PDF/image pipeline (docling's
372    /// `document_timeout`, #497). See [`Self::document_timeout`].
373    document_timeout: Option<std::time::Duration>,
374    /// Bounds on what a ZIP input may decompress (#557,
375    /// [`DocumentConverter::convert_archive`]).
376    archive_limits: crate::archive::ArchiveLimits,
377    /// The caller's long-lived ML pipeline (#669), when one was lent with
378    /// [`Self::warm_pipeline`]; `None` loads the models per conversion.
379    #[cfg(feature = "pdf")]
380    warm: Option<WarmPipeline>,
381    /// Backends registered with [`Self::register_backend`] (#680), in the
382    /// order they are tried: highest priority first, registration order
383    /// among equals.
384    backends: std::sync::Arc<Vec<crate::plugins::RegisteredBackend>>,
385}
386
387/// The builder's overrides of [`crate::ImageLimits`] (#646): `None` = the
388/// environment's value, else the default.
389#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
390struct ImageLimitOverrides {
391    max_bytes: Option<u64>,
392    max_images: Option<usize>,
393    max_total_mb: Option<u64>,
394    min_bytes: Option<u64>,
395}
396
397/// Default cap on sampled frames per video. Scene changes rarely exceed this
398/// in short clips, and uniform fallback at 8 keeps JSON/DCLX output (which
399/// embeds the PNGs) within sane bounds.
400pub const DEFAULT_VIDEO_FRAMES: usize = 8;
401
402/// The `video_frames` count meaning "every distinct cut" (#647): no cap,
403/// no even resampling of a cut-less video (its first frame alone), the
404/// scene threshold and de-duplication deciding what a distinct frame is.
405/// Any count at or above `u32::MAX` reads as this on the JSON surfaces, so
406/// a binding whose integers are 32-bit (the npm addon) can ask for it.
407pub const ALL_VIDEO_FRAMES: usize = usize::MAX;
408
409/// Parse a user-facing page-range string (issue #80's `--pages`): `"A-B"` for
410/// an inclusive 1-based window, or a single `"N"` for one page. Whitespace
411/// around the numbers is tolerated. Validation against the actual page count
412/// happens at convert time; this only checks the spelling (`first >= 1`,
413/// `first <= last`).
414pub fn parse_page_range(s: &str) -> Result<(usize, usize), String> {
415    let parse_one = |part: &str| {
416        part.trim()
417            .parse::<usize>()
418            .map_err(|_| format!("invalid page number '{}'", part.trim()))
419    };
420    let (first, last) = match s.split_once('-') {
421        Some((a, b)) => (parse_one(a)?, parse_one(b)?),
422        None => {
423            let n = parse_one(s)?;
424            (n, n)
425        }
426    };
427    if first == 0 {
428        return Err("pages are 1-based; the range starts at 1".into());
429    }
430    if last < first {
431        return Err(format!("range {first}-{last} is inverted (first <= last)"));
432    }
433    Ok((first, last))
434}
435
436/// A PDF/image ML pipeline kept loaded across conversions (#669) — what a
437/// long-lived caller (a server, an agent tool) lends its converters with
438/// [`DocumentConverter::warm_pipeline`] so the layout, TableFormer and OCR
439/// sessions load once instead of once per document. Cloning shares the
440/// pipeline; conversions on it take turns.
441///
442/// The pipeline is rebuilt only when a conversion asks for different model
443/// switches (text-layer only, OCR off, no TableFormer, no text panels, the
444/// enrichments — what a built pipeline cannot change); a panic inside a
445/// conversion discards it, so the next one starts clean.
446#[cfg(feature = "pdf")]
447#[derive(Clone, Default)]
448pub struct WarmPipeline {
449    slot: std::sync::Arc<std::sync::Mutex<WarmSlot>>,
450}
451
452#[cfg(feature = "pdf")]
453type WarmSlot = Option<(PipelineSwitches, docling_pdf::Pipeline)>;
454
455#[cfg(feature = "pdf")]
456impl WarmPipeline {
457    /// An empty handle; the models load on the first PDF/image conversion.
458    pub fn new() -> Self {
459        Self::default()
460    }
461
462    /// The pipeline for a conversion with `switches`, rebuilt when the
463    /// loaded one was built with others.
464    fn lease(
465        &self,
466        switches: PipelineSwitches,
467    ) -> Result<std::sync::MutexGuard<'_, WarmSlot>, docling_pdf::PdfError> {
468        let mut slot = self.slot.lock().unwrap_or_else(|poisoned| {
469            // A conversion panicked mid-document: its workers may hold half a
470            // page — start from a fresh pipeline rather than reuse them.
471            let mut slot = poisoned.into_inner();
472            *slot = None;
473            slot
474        });
475        self.slot.clear_poison();
476        if slot.as_ref().map(|(built, _)| *built) != Some(switches) {
477            // Drop the old models before the new ones load, not after.
478            *slot = None;
479            *slot = Some((switches, switches.build()?));
480        }
481        Ok(slot)
482    }
483}
484
485#[cfg(feature = "pdf")]
486impl std::fmt::Debug for WarmPipeline {
487    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
488        let loaded = match self.slot.try_lock() {
489            Ok(slot) => format!("{:?}", slot.as_ref().map(|(switches, _)| switches)),
490            Err(_) => "in use".to_string(),
491        };
492        f.debug_struct("WarmPipeline")
493            .field("loaded", &loaded)
494            .finish()
495    }
496}
497
498/// What a built [`docling_pdf::Pipeline`] cannot change: the model set it
499/// loads. Every other setting is applied per conversion.
500#[cfg(feature = "pdf")]
501#[derive(Clone, Copy, Debug, PartialEq, Eq)]
502struct PipelineSwitches {
503    text_layer_only: bool,
504    no_ocr: bool,
505    no_table_former: bool,
506    no_text_panels: bool,
507    enrich: crate::EnrichmentOptions,
508}
509
510#[cfg(feature = "pdf")]
511impl PipelineSwitches {
512    fn of(c: &DocumentConverter) -> Self {
513        Self {
514            text_layer_only: c.text_layer_only,
515            no_ocr: c.no_ocr,
516            no_table_former: c.no_table_former,
517            no_text_panels: c.no_text_panels,
518            enrich: c.enrich,
519        }
520    }
521
522    fn build(self) -> Result<docling_pdf::Pipeline, docling_pdf::PdfError> {
523        Ok(docling_pdf::Pipeline::new()?
524            .no_table_former(self.no_table_former)
525            // docling-pdf's `Pipeline` keeps its pre-2.0 names: its `no_ocr`
526            // is the text-layer fast path, its `skip_ocr` docling's do_ocr=False.
527            .no_ocr(self.text_layer_only)
528            .skip_ocr(self.no_ocr)
529            .no_text_panels(self.no_text_panels)
530            .enrichments(self.enrich))
531    }
532}
533
534/// A conversion's pipeline: its own, or the warm one held for the call.
535#[cfg(feature = "pdf")]
536enum PipelineLease<'a> {
537    Fresh(Box<docling_pdf::Pipeline>),
538    Warm(std::sync::MutexGuard<'a, WarmSlot>),
539}
540
541#[cfg(feature = "pdf")]
542impl std::ops::Deref for PipelineLease<'_> {
543    type Target = docling_pdf::Pipeline;
544
545    fn deref(&self) -> &Self::Target {
546        match self {
547            Self::Fresh(p) => p,
548            Self::Warm(slot) => &slot.as_ref().expect("filled by the lease").1,
549        }
550    }
551}
552
553#[cfg(feature = "pdf")]
554impl std::ops::DerefMut for PipelineLease<'_> {
555    fn deref_mut(&mut self) -> &mut Self::Target {
556        match self {
557            Self::Fresh(p) => p,
558            Self::Warm(slot) => &mut slot.as_mut().expect("filled by the lease").1,
559        }
560    }
561}
562
563impl Default for DocumentConverter {
564    fn default() -> Self {
565        Self {
566            allowed_formats: None,
567            strict: false,
568            image_sources: crate::ImageSources::None,
569            image_hosts: Vec::new(),
570            image_limits: ImageLimitOverrides::default(),
571            list_attachments: false,
572            skip_empty_cells: false,
573            compact_tables: false,
574            picture_alt_text: false,
575            metadata_output: Default::default(),
576            page_break_placeholder: None,
577            ebcdic_layout: None,
578            no_table_former: false,
579            no_text_panels: false,
580            text_layer_only: false,
581            no_ocr: false,
582            password: None,
583            force_full_page_ocr: false,
584            ocr_mode: None,
585            ocr_engine: None,
586            ocr_scale: None,
587            ocr_textline_orientation: None,
588            images_scale: None,
589            generate_page_images: false,
590            heading_hierarchy: false,
591            use_web_browser: false,
592            asr_model: None,
593            asr_lang: None,
594            video_frames: None,
595            video_scene_threshold: None,
596            video_frame_max_side: None,
597            video_frame_dedupe: None,
598            xbrl_taxonomy: None,
599            enrich: crate::EnrichmentOptions::default(),
600            picture_ocr: false,
601            picture_ocr_classes: Vec::new(),
602            picture_ocr_min_side: None,
603            picture_ocr_scale: None,
604            keep_picture_images: true,
605            #[cfg(feature = "vlm")]
606            picture_description: None,
607            redact: None,
608            page_range: None,
609            ocr_lang: None,
610            encoding: None,
611            ipynb_outputs: crate::IpynbOutputs::None,
612            artifacts_dir: "artifacts".to_string(),
613            document_timeout: None,
614            archive_limits: crate::archive::ArchiveLimits::default(),
615            #[cfg(feature = "pdf")]
616            warm: None,
617            backends: std::sync::Arc::new(Vec::new()),
618        }
619    }
620}
621
622impl DocumentConverter {
623    /// A converter that accepts every supported format.
624    pub fn new() -> Self {
625        Self::default()
626    }
627
628    /// A converter restricted to an explicit set of formats. Sources of any
629    /// other format are rejected with [`ConversionError::UnsupportedFormat`].
630    pub fn with_allowed_formats(formats: impl IntoIterator<Item = InputFormat>) -> Self {
631        Self {
632            allowed_formats: Some(formats.into_iter().collect()),
633            ..Self::default()
634        }
635    }
636
637    /// Convert only PDF pages `first..=last` (**1-based** inclusive, the page
638    /// numbers a viewer shows — issue #80's `--pages A-B`). Out-of-window pages
639    /// are skipped before rasterization, so converting 3 pages of a 500-page
640    /// PDF costs 3 pages. `last` clamps to the document; a window that selects
641    /// no pages at all errors at convert time. Non-PDF formats ignore the
642    /// window (they convert whole).
643    pub fn page_range(mut self, first: usize, last: usize) -> Self {
644        self.page_range = Some((first, last));
645        self
646    }
647
648    /// A wall-clock budget per document for the PDF pipeline — docling's
649    /// `PipelineOptions.document_timeout` (#497); `None` = unlimited, the
650    /// default. The budget starts with the conversion and is checked between
651    /// pages: once spent, no further page is rendered or processed, the pages
652    /// already finished become the document, and the result is a
653    /// [`ConversionStatus::PartialSuccess`] carrying one
654    /// [`ErrorItem`](crate::ErrorItem) (`document_backend` / `pipeline`,
655    /// "document timeout of Ns exceeded after D of S pages …"). A page in
656    /// flight finishes first, so a budget shorter than one page's work still
657    /// yields that page. Only the paginated pipeline has pages to stop
658    /// between: declarative formats (Office, HTML, …) convert whole, as in
659    /// docling, and a single image is never cut. A streaming conversion
660    /// emits the pages that fit and ends with
661    /// [`ConversionError::Timeout`](crate::ConversionError::Timeout) as its
662    /// last item.
663    pub fn document_timeout(mut self, timeout: Option<std::time::Duration>) -> Self {
664        self.document_timeout = timeout;
665        self
666    }
667
668    /// OCR recognition language for scanned PDF/image pages: `"en"` (the
669    /// default — English PP-OCRv3, proper Latin word spacing) or `"ch"` (the
670    /// multilingual model docling conformance is measured with — glues Latin
671    /// words). An unknown value warns at conversion time and uses the
672    /// default; explicit `DOCLING_OCR_REC_ONNX`/`DOCLING_OCR_DICT` paths win
673    /// over this switch. Under [`ocr_engine`](Self::ocr_engine) `tesseract`
674    /// it is Tesseract's language list instead — tessdata stems (`"deu"`,
675    /// `"eng+fra"`, `"script/Cyrillic"`) or BCP-47 tags mapped onto them
676    /// (`"de"`, `"zh-Hant"`), see [`docling_pdf::tesseract_lang_arg`]; `en`
677    /// and `ch` keep working there. Formats that never OCR ignore it.
678    pub fn ocr_lang(mut self, lang: impl Into<String>) -> Self {
679        self.ocr_lang = Some(lang.into());
680        self
681    }
682
683    /// Convert on `warm`'s ML pipeline (#669) instead of loading the models
684    /// for each conversion: PDFs, images, SVG's raster route, METS pages and
685    /// a scanned DjVu's OCR fallback all run on the one instance, which keeps
686    /// its ONNX sessions between conversions. Everything else about the
687    /// conversion is this converter's — page window, password, OCR and
688    /// image settings are applied to the pipeline on every call, so nothing
689    /// carries over from the previous caller's options. Converters sharing a
690    /// handle take turns on it; the declarative formats never touch it.
691    #[cfg(feature = "pdf")]
692    pub fn warm_pipeline(mut self, warm: &WarmPipeline) -> Self {
693        self.warm = Some(warm.clone());
694        self
695    }
696
697    /// The configured ML pipeline for one conversion: a fresh one (models
698    /// load per call), or the [`warm`](Self::warm_pipeline) one this
699    /// converter was lent. Both are configured by the same setters, so the
700    /// warm path cannot drift from the cold one.
701    #[cfg(feature = "pdf")]
702    fn ml_pipeline(&self) -> Result<PipelineLease<'_>, docling_pdf::PdfError> {
703        let switches = PipelineSwitches::of(self);
704        let mut lease = match &self.warm {
705            None => PipelineLease::Fresh(Box::new(switches.build()?)),
706            Some(warm) => PipelineLease::Warm(warm.lease(switches)?),
707        };
708        self.configure_pipeline(&mut lease);
709        Ok(lease)
710    }
711
712    /// Every per-conversion setting, set unconditionally — on a warm
713    /// pipeline a setting left alone would be the previous conversion's.
714    #[cfg(feature = "pdf")]
715    fn configure_pipeline(&self, p: &mut docling_pdf::Pipeline) {
716        p.set_ocr_textline_orientation(self.ocr_textline_orientation);
717        p.set_ocr_lang(self.ocr_lang_choice());
718        p.set_ocr_engine(self.ocr_engine_choice());
719        p.set_tesseract_lang(self.tesseract_lang_choice());
720        p.set_ocr_mode(self.ocr_mode_choice());
721        p.set_ocr_scale(self.ocr_scale_choice());
722        p.set_images(docling_pdf::ImageOutput {
723            scale: self.images_scale,
724            page_images: self.generate_page_images,
725        });
726        p.set_heading_hierarchy(docling_pdf::HeadingHierarchyOptions::enabled(
727            self.heading_hierarchy,
728        ));
729        p.set_document_timeout(self.document_timeout);
730        // The PDF route sets these two for itself; every other route reads
731        // the whole input with OCR left to the layout.
732        p.set_force_full_page_ocr(false);
733        p.set_pages(None);
734    }
735
736    /// DjVu (#434): the hidden text layer by default; a scan-only DjVu (no
737    /// text layer on any selected page) falls back to rasterize + OCR when the
738    /// ML pipeline is built and OCR is not disabled, otherwise it degrades to
739    /// an empty document with a warning. See [`crate::backend::djvu`].
740    fn convert_djvu(
741        &self,
742        source: &SourceDocument,
743    ) -> Result<docling_core::DoclingDocument, ConversionError> {
744        use crate::backend::djvu;
745        let text = djvu::convert_text_layer(source, self.page_range)?;
746        if !djvu::is_text_layer_empty(&text) {
747            return Ok(text);
748        }
749        // No text layer anywhere in the selection.
750        #[cfg(feature = "pdf")]
751        if !self.text_layer_only && !self.no_ocr {
752            let pngs = djvu::rasterize_pages(&source.bytes, self.page_range)?;
753            let mut pipeline = self
754                .ml_pipeline()
755                .map_err(|e| ConversionError::with_source("djvu", e))?;
756            let mut doc = docling_core::DoclingDocument::new(&source.name);
757            for (i, (page_no, png)) in pngs.iter().enumerate() {
758                if i > 0 {
759                    doc.push(docling_core::Node::PageBreak);
760                }
761                let mut page = pipeline
762                    .convert_image(png, &source.name)
763                    .map_err(|e| ConversionError::with_source("djvu", e))?;
764                // An image is its own page 1; the DjVu page keeps its number so
765                // a `--pages` window's JSON `pages` matches the text-layer path.
766                docling_pdf::assemble::stamp_page_no(&mut page.nodes, *page_no);
767                doc.nodes.extend(page.nodes);
768                doc.links.extend(page.links);
769            }
770            return Ok(doc);
771        }
772        eprintln!(
773            "docling: warning: DjVu '{}' has no text layer and OCR is unavailable/disabled; \
774             the document is empty",
775            source.name
776        );
777        Ok(text)
778    }
779
780    /// The parsed [`Self::ocr_lang`] choice for the ML call sites; a value
781    /// that parses to nothing warns here (once per conversion) rather than
782    /// erroring — same degradation the env selector applies.
783    #[cfg(feature = "pdf")]
784    fn ocr_lang_choice(&self) -> Option<docling_pdf::OcrLang> {
785        let raw = self.ocr_lang.as_deref()?;
786        // Under Tesseract the value is its language list, not a PP-OCR model
787        // — see `tesseract_lang_choice`.
788        if self.ocr_engine_choice() == Some(docling_pdf::OcrEngine::Tesseract) {
789            return None;
790        }
791        let parsed = docling_pdf::OcrLang::parse(raw);
792        if parsed.is_none() {
793            eprintln!(
794                "docling: ocr_lang {raw:?} names no language the OCR models read ({}); using \
795                 the default",
796                docling_pdf::OcrLang::ACCEPTED
797            );
798        }
799        parsed
800    }
801
802    /// The parsed [`Self::ocr_engine`] choice (#460), with the same
803    /// warn-and-default degradation as [`ocr_lang_choice`](Self::ocr_lang_choice).
804    #[cfg(feature = "pdf")]
805    fn ocr_engine_choice(&self) -> Option<docling_pdf::OcrEngine> {
806        let raw = self.ocr_engine.as_deref()?;
807        let parsed = docling_pdf::OcrEngine::parse(raw);
808        if parsed.is_none() {
809            eprintln!(
810                "docling: ocr_engine {raw:?} is not {}; using the default",
811                docling_pdf::OcrEngine::ACCEPTED
812            );
813        }
814        parsed
815    }
816
817    /// Tesseract's `-l` argument from [`Self::ocr_lang`] (#460) when the
818    /// engine is Tesseract: an unmappable value warns and leaves Tesseract's
819    /// default language.
820    #[cfg(feature = "pdf")]
821    fn tesseract_lang_choice(&self) -> Option<String> {
822        if self.ocr_engine_choice() != Some(docling_pdf::OcrEngine::Tesseract) {
823            return None;
824        }
825        let raw = self.ocr_lang.as_deref()?;
826        match docling_pdf::tesseract_lang_arg(raw) {
827            Ok(arg) => Some(arg),
828            Err(e) => {
829                eprintln!("docling: {e}; using Tesseract's default language");
830                None
831            }
832        }
833    }
834
835    /// The parsed [`Self::ocr_mode`] choice (#254), with the same
836    /// warn-and-default degradation as [`ocr_lang_choice`](Self::ocr_lang_choice).
837    #[cfg(feature = "pdf")]
838    fn ocr_mode_choice(&self) -> Option<docling_pdf::OcrMode> {
839        let raw = self.ocr_mode.as_deref()?;
840        let parsed = docling_pdf::OcrMode::parse(raw);
841        if parsed.is_none() {
842            eprintln!(
843                "docling: ocr_mode {raw:?} is not \
844                 default|full_page|layout_regions|pdf_aware_layout_regions; using the default"
845            );
846        }
847        parsed
848    }
849
850    /// The validated [`Self::ocr_scale`] (#254): non-positive/non-finite
851    /// values warn and fall back to the engine default.
852    #[cfg(feature = "pdf")]
853    fn ocr_scale_choice(&self) -> Option<f32> {
854        let s = self.ocr_scale?;
855        if !(s.is_finite() && s > 0.0) {
856            eprintln!("docling: ocr_scale {s} is not a positive number; using the default");
857            return None;
858        }
859        Some(s)
860    }
861
862    /// The validated [`Self::picture_ocr_scale`] (#666), like
863    /// [`Self::ocr_scale_choice`].
864    #[cfg(feature = "pdf")]
865    fn picture_ocr_scale_choice(&self) -> Option<f32> {
866        let s = self.picture_ocr_scale?;
867        if !(s.is_finite() && s > 0.0) {
868            eprintln!("docling: picture_ocr_scale {s} is not a positive number; using the default");
869            return None;
870        }
871        Some(s)
872    }
873
874    /// [`Self::ocr_textline_orientation`] on a pipeline (#666); unset keeps
875    /// the pipeline's `DOCLING_RS_OCR_TEXTLINE_ORIENTATION` default.
876    #[cfg(feature = "pdf")]
877    fn with_textline_orientation(&self, p: docling_pdf::Pipeline) -> docling_pdf::Pipeline {
878        match self.ocr_textline_orientation {
879            Some(enable) => p.ocr_textline_orientation(enable),
880            None => p,
881        }
882    }
883
884    /// Where [`ImageMode::Referenced`] streaming writes image files, and the
885    /// link prefix used in the Markdown (default `artifacts`, matching the
886    /// buffered export's convention). Relative paths resolve against the
887    /// process working directory.
888    pub fn artifacts_dir(mut self, dir: impl Into<String>) -> Self {
889        self.artifacts_dir = dir.into();
890        self
891    }
892
893    /// Decode text inputs (Markdown, CSV, AsciiDoc, WebVTT, LaTeX, the XML
894    /// dialects, …) with this character encoding instead of detecting one —
895    /// docling's `TextBackendOptions.encoding`
896    /// (`MarkdownBackendOptions(encoding="shift_jis")`). A WHATWG encoding
897    /// label (`shift_jis`, `koi8-r`, `windows-1251`, `latin1`; Python codec
898    /// spellings with `_` are accepted). Nothing is guessed: bytes the
899    /// encoding cannot decode fail the conversion, as does an unknown label.
900    /// `None` (default) detects — a byte-order mark, then UTF-8, then
901    /// windows-1252 (see [`SourceDocument::text`]). A source that already
902    /// carries its own [`SourceDocument::encoding`] keeps it.
903    pub fn encoding(mut self, label: Option<String>) -> Self {
904        self.encoding = label;
905        self
906    }
907
908    /// Jupyter notebooks (#673): which cell outputs the document keeps —
909    /// [`IpynbOutputs::None`](crate::IpynbOutputs::None) (the default: the
910    /// notebook as written, MarkItDown's reading) or
911    /// [`IpynbOutputs::Text`](crate::IpynbOutputs::Text): stream and
912    /// `text/plain` results as code blocks after their cell, raster image
913    /// outputs as pictures. The CLI's `--ipynb-outputs none|text`.
914    pub fn ipynb_outputs(mut self, outputs: crate::IpynbOutputs) -> Self {
915        self.ipynb_outputs = outputs;
916        self
917    }
918
919    /// The converter's [`encoding`](Self::encoding) applied to a source that
920    /// did not set its own.
921    /// Bounds on what a ZIP input may make the converter decompress (#557):
922    /// entries considered, per-entry and total uncompressed size, compression
923    /// ratio. [`ArchiveLimits::default`](crate::archive::ArchiveLimits) when
924    /// not set. Only [`DocumentConverter::convert_archive`] reads them.
925    pub fn archive_limits(mut self, limits: crate::archive::ArchiveLimits) -> Self {
926        self.archive_limits = limits;
927        self
928    }
929
930    /// Register `backend` for the sources `matcher` claims (#680), under
931    /// `name` (what format listings print). Registered backends are tried
932    /// before the built-in formats — highest `priority` first, the earliest
933    /// registration first among equals — so a backend can add a format or
934    /// take one over; its document then goes through the same
935    /// post-processing as a built-in one. An extension the built-in tables
936    /// do not know reaches a converter through [`Self::load_file`] /
937    /// [`Self::load_named_bytes`], which resolve such a source as
938    /// [`InputFormat::Plugin`]. See [`crate::plugins`].
939    ///
940    /// ```
941    /// use std::sync::Arc;
942    /// use docling::{BackendMatcher, ConversionError, DocumentConverter, SourceDocument};
943    /// use docling::backend::DeclarativeBackend;
944    /// use docling_core::{DoclingDocument, Node};
945    ///
946    /// struct Shout;
947    /// impl DeclarativeBackend for Shout {
948    ///     fn convert(&self, source: &SourceDocument) -> Result<DoclingDocument, ConversionError> {
949    ///         let mut doc = DoclingDocument::new(&source.name);
950    ///         doc.push(Node::Paragraph { text: source.text()?.to_uppercase() });
951    ///         Ok(doc)
952    ///     }
953    /// }
954    ///
955    /// let converter = DocumentConverter::new().register_backend(
956    ///     "shout",
957    ///     BackendMatcher::new().extensions(["shout"]),
958    ///     Arc::new(Shout),
959    ///     0,
960    /// );
961    /// let source = converter.load_named_bytes("note.shout", b"hello".to_vec(), None)?;
962    /// let md = converter.convert(source)?.document.export_to_markdown();
963    /// assert_eq!(md, "HELLO\n");
964    /// # Ok::<(), ConversionError>(())
965    /// ```
966    pub fn register_backend(
967        mut self,
968        name: impl Into<String>,
969        matcher: crate::plugins::BackendMatcher,
970        backend: std::sync::Arc<dyn crate::backend::DeclarativeBackend + Send + Sync>,
971        priority: i32,
972    ) -> Self {
973        let mut backends = (*self.backends).clone();
974        backends.push(crate::plugins::RegisteredBackend::new(
975            name.into(),
976            matcher,
977            backend,
978            priority,
979        ));
980        // Stable: registration order stays among equal priorities.
981        backends.sort_by_key(|b| std::cmp::Reverse(b.priority()));
982        self.backends = std::sync::Arc::new(backends);
983        self
984    }
985
986    /// The backends registered with [`Self::register_backend`], in the
987    /// order they are tried.
988    pub fn registered_backends(&self) -> &[crate::plugins::RegisteredBackend] {
989        &self.backends
990    }
991
992    /// The registered backend that claims `source`, if any.
993    fn backend_for(&self, source: &SourceDocument) -> Option<&crate::plugins::RegisteredBackend> {
994        self.backends.iter().find(|b| {
995            b.matcher().matches(
996                source.extension.as_deref(),
997                source.media_type.as_deref(),
998                &source.bytes,
999            )
1000        })
1001    }
1002
1003    /// Whether a registered backend claims `source` (the streaming path
1004    /// then converts it buffered, through [`Self::convert`]).
1005    pub(crate) fn claims(&self, source: &SourceDocument) -> bool {
1006        self.backend_for(source).is_some()
1007    }
1008
1009    /// [`SourceDocument::from_file`] that knows this converter's registered
1010    /// backends (#680): a file a registered backend claims — by extension,
1011    /// or by its bytes — loads even when the built-in tables do not know
1012    /// it, as [`InputFormat::Plugin`] (a claimed file whose extension *is*
1013    /// a built-in format keeps that format). Without registered backends,
1014    /// exactly [`SourceDocument::from_file`].
1015    pub fn load_file(
1016        &self,
1017        path: impl AsRef<std::path::Path>,
1018    ) -> Result<SourceDocument, ConversionError> {
1019        let path = path.as_ref();
1020        let bytes = std::fs::read(path)?;
1021        let ext = path
1022            .extension()
1023            .and_then(|e| e.to_str())
1024            .map(str::to_ascii_lowercase);
1025        if self
1026            .backends
1027            .iter()
1028            .any(|b| b.matcher().matches(ext.as_deref(), None, &bytes))
1029        {
1030            let format = ext
1031                .as_deref()
1032                .and_then(InputFormat::from_extension)
1033                .unwrap_or(InputFormat::Plugin);
1034            let name = path
1035                .file_stem()
1036                .and_then(|s| s.to_str())
1037                .unwrap_or("document")
1038                .to_string();
1039            let mut source = SourceDocument::from_bytes(name, format, bytes);
1040            source.extension = ext;
1041            source.path = Some(path.to_path_buf());
1042            return Ok(source);
1043        }
1044        SourceDocument::from_path_and_bytes(path, bytes)
1045    }
1046
1047    /// [`SourceDocument::from_named_bytes`] that knows this converter's
1048    /// registered backends (#680), as [`Self::load_file`] does: bytes a
1049    /// registered backend claims — by the name's extension, the media type
1050    /// or the content — load even when the built-in tables do not know
1051    /// them, as [`InputFormat::Plugin`] unless the extension or media type
1052    /// names a built-in format.
1053    pub fn load_named_bytes(
1054        &self,
1055        name: &str,
1056        bytes: Vec<u8>,
1057        media_type: Option<&str>,
1058    ) -> Result<SourceDocument, ConversionError> {
1059        let path = std::path::Path::new(name);
1060        let ext = path
1061            .extension()
1062            .and_then(|e| e.to_str())
1063            .map(str::to_ascii_lowercase);
1064        if self
1065            .backends
1066            .iter()
1067            .any(|b| b.matcher().matches(ext.as_deref(), media_type, &bytes))
1068        {
1069            let format = ext
1070                .as_deref()
1071                .and_then(InputFormat::from_extension)
1072                .or_else(|| media_type.and_then(InputFormat::from_mime))
1073                .unwrap_or(InputFormat::Plugin);
1074            let stem = path
1075                .file_stem()
1076                .and_then(|s| s.to_str())
1077                .filter(|s| !s.is_empty())
1078                .unwrap_or("document")
1079                .to_string();
1080            let mut source = SourceDocument::from_bytes(stem, format, bytes);
1081            source.extension = ext;
1082            source.media_type = media_type.map(str::to_string);
1083            return Ok(source);
1084        }
1085        SourceDocument::from_named_bytes(name, bytes, media_type)
1086    }
1087
1088    /// Every input file extension this converter takes: the build's
1089    /// built-in ones ([`InputFormat::supported_extensions`]) and those of
1090    /// its registered backends (#680) — sorted, unique, lowercase, no dot.
1091    pub fn supported_extensions(&self) -> Vec<String> {
1092        let mut out: Vec<String> = InputFormat::supported_extensions()
1093            .into_iter()
1094            .map(str::to_string)
1095            .chain(
1096                self.backends
1097                    .iter()
1098                    .flat_map(|b| b.matcher().extension_list().iter().cloned()),
1099            )
1100            .collect();
1101        out.sort_unstable();
1102        out.dedup();
1103        out
1104    }
1105
1106    pub(crate) fn archive_limits_ref(&self) -> crate::archive::ArchiveLimits {
1107        self.archive_limits
1108    }
1109
1110    fn with_encoding(&self, mut source: SourceDocument) -> SourceDocument {
1111        if source.encoding.is_none() {
1112            source.encoding = self.encoding.clone();
1113        }
1114        source
1115    }
1116
1117    /// Cap the number of frames sampled from a video (#138 Phase 2); `0`
1118    /// disables frame extraction entirely (Phase 1 behavior: transcript only).
1119    /// Defaults to [`DEFAULT_VIDEO_FRAMES`]. Frames are extracted with the
1120    /// `ffmpeg` binary when present (`DOCLING_FFMPEG` overrides the path);
1121    /// without it a video converts to its transcript alone.
1122    pub fn video_frames(mut self, max: usize) -> Self {
1123        self.video_frames = Some(max);
1124        self
1125    }
1126
1127    /// Keep every distinct cut of a video (#647) — [`ALL_VIDEO_FRAMES`]:
1128    /// no cap, so what bounds the picture count is the scene threshold and
1129    /// the de-duplication. Memory stays one frame at a time whatever the
1130    /// count ([`do_picture_ocr`](Self::do_picture_ocr) +
1131    /// [`keep_picture_images`](Self::keep_picture_images)`(false)` reads and
1132    /// drops each frame before the next is decoded).
1133    pub fn video_frames_all(self) -> Self {
1134        self.video_frames(ALL_VIDEO_FRAMES)
1135    }
1136
1137    /// ffmpeg's `scene` score (0–1, the normalized difference of a frame to
1138    /// its predecessor) a frame must exceed to be a cut (#647). Default
1139    /// 0.27 (`DOCLING_RS_VIDEO_SCENE_THRESHOLD` overrides it): a slide
1140    /// change in a screen recording scores well above it, a fade or a
1141    /// lighting change around 0.5, a hard cut near 1.0 — raise it to keep
1142    /// only hard cuts. Out-of-range values are clamped.
1143    pub fn video_scene_threshold(mut self, threshold: f32) -> Self {
1144        self.video_scene_threshold = Some(threshold.clamp(0.0, 1.0));
1145        self
1146    }
1147
1148    /// Downscale each sampled frame inside ffmpeg so its longer side is at
1149    /// most `px` (#647; the aspect ratio is kept, a smaller frame is left as
1150    /// it is): a 1080p recording at 640 yields 640×360 PNGs, so neither the
1151    /// embedded images nor the OCR input ever reach memory at full size.
1152    /// `0` (the default, `DOCLING_RS_VIDEO_FRAME_MAX_SIDE` overrides it) =
1153    /// the source resolution.
1154    pub fn video_frame_max_side(mut self, px: u32) -> Self {
1155        self.video_frame_max_side = Some(px);
1156        self
1157    }
1158
1159    /// Drop a sampled frame whose perceptual difference hash (64 bits over
1160    /// a 9×8 grey thumbnail) is within `max_distance` bits of a frame
1161    /// already kept (#647): the same slide after a fade, or shown again
1162    /// after a camera cut, becomes one picture. 4–6 is a good distance;
1163    /// `None` (the default, `DOCLING_RS_VIDEO_FRAME_DEDUPE` overrides it)
1164    /// keeps every sampled frame.
1165    pub fn video_frame_dedupe(mut self, max_distance: Option<u32>) -> Self {
1166        self.video_frame_dedupe = max_distance.map(|d| d.min(64));
1167        self
1168    }
1169
1170    /// The folder holding the taxonomy an XBRL instance refers to (docling's
1171    /// `XBRLBackendOptions.taxonomy`): the filing's extension schema and
1172    /// linkbases at the relative paths its `link:schemaRef` names, plus any
1173    /// taxonomy packages (`.zip` with a `META-INF/catalog.xml`) that map the
1174    /// base taxonomies' `http(s)` URLs to files for offline use. Without it the
1175    /// instance's own directory is searched. Nothing is fetched remotely; a
1176    /// document that cannot be found only costs the fact graph the hierarchy
1177    /// it would have contributed.
1178    pub fn xbrl_taxonomy(mut self, dir: impl Into<PathBuf>) -> Self {
1179        self.xbrl_taxonomy = Some(dir.into());
1180        self
1181    }
1182
1183    /// Select a named ASR model preset for audio sources — the English-only
1184    /// (`whisper_tiny_en`, `whisper_base_en`, `whisper_small_en`) and
1185    /// Distil-Whisper (`whisper_distil_small_en`) variants of docling's ASR
1186    /// model specs, or `parakeet_tdt_0.6b_v3` (NVIDIA's Parakeet TDT 0.6B v3
1187    /// transducer, 25 European languages detected by the model, #508 — see
1188    /// `docling_asr::parakeet`). `None` (default) uses Whisper tiny
1189    /// (multilingual) from `.models/asr/`; presets load from
1190    /// `.models/asr/<preset>/` (fetch them with `download_dependencies.sh
1191    /// --asr-model=<preset>`).
1192    pub fn asr_model(mut self, model: Option<String>) -> Self {
1193        self.asr_model = model;
1194        self
1195    }
1196
1197    /// Select the ASR transcription language for audio/video sources: a
1198    /// Whisper code (`en`, `de`, `zh`, …) or `auto`. `None` (default) falls
1199    /// back to `DOCLING_RS_ASR_LANG`, and — when that is unset too — to
1200    /// per-file auto-detection from the first 30-second window (docling
1201    /// 2.116 parity). English-only presets always transcribe English.
1202    pub fn asr_lang(mut self, lang: Option<String>) -> Self {
1203        self.asr_lang = lang;
1204        self
1205    }
1206
1207    /// Select the Markdown export mode for documents this converter produces.
1208    ///
1209    /// `false` (default) makes [`crate::DoclingDocument::export_to_markdown`]
1210    /// reproduce docling's legacy output byte-for-byte; `true` makes it emit
1211    /// cleaner, more conformant Markdown (code-fence languages preserved, no
1212    /// inline-run spacing artifacts, no entity re-escaping). Rust-only — Python
1213    /// docling has no such switch.
1214    pub fn strict(mut self, strict: bool) -> Self {
1215        self.strict = strict;
1216        self
1217    }
1218
1219    /// Fetch and embed external `<img>` images for HTML/EPUB/MHTML/JATS/
1220    /// AsciiDoc/Markdown/email sources — the pre-#646 switch, kept as an
1221    /// alias: `true` is [`image_sources`](Self::image_sources)
1222    /// `(`[`ImageSources::Remote`](crate::ImageSources::Remote)`)`, `false`
1223    /// is `None`.
1224    ///
1225    /// Off by default (matching docling's `enable_*_fetch=False`), so output is
1226    /// unchanged unless you opt in. `Remote` resolves `data:` URIs, container
1227    /// parts (EPUB/MHTML entries, email `cid:` attachments), files under the
1228    /// source file's directory, and `http(s)` URLs — fetched over the network,
1229    /// so enable it only for input you trust (it can otherwise make the
1230    /// process issue requests). A server converting untrusted input wants
1231    /// `image_sources(ImageSources::Embedded)` instead. Unlike before #646 an
1232    /// absolute local path (`/etc/hosts`, `file://…`) is never read.
1233    pub fn fetch_images(self, fetch: bool) -> Self {
1234        self.image_sources(if fetch {
1235            crate::ImageSources::Remote
1236        } else {
1237            crate::ImageSources::None
1238        })
1239    }
1240
1241    /// Which image references the declarative backends resolve (#646):
1242    /// [`None`](crate::ImageSources::None) (the default — every picture a
1243    /// placeholder), [`Embedded`](crate::ImageSources::Embedded) (`data:`
1244    /// URIs and parts of the same container: EPUB/MHTML entries, an email's
1245    /// `cid:` attachments — no filesystem, no network),
1246    /// [`Local`](crate::ImageSources::Local) (plus files under the source
1247    /// file's directory, never an absolute path or one that escapes it) and
1248    /// [`Remote`](crate::ImageSources::Remote) (plus `http(s)` fetches, see
1249    /// [`image_hosts`](Self::image_hosts)). Applies to HTML, EPUB, MHTML,
1250    /// JATS, AsciiDoc, ODF (`http(s)` `draw:image` references), Markdown
1251    /// (`![…](…)` and inline `<img>`) and email bodies.
1252    pub fn image_sources(mut self, sources: crate::ImageSources) -> Self {
1253        self.image_sources = sources;
1254        self
1255    }
1256
1257    /// Restrict `Remote` fetches to these hosts (#646): exact names or
1258    /// `*.suffix` wildcards for any subdomain, case-insensitive; a redirect
1259    /// is held to the same list. Empty (the default) allows any host. The
1260    /// private/loopback/link-local block-list still applies to a listed
1261    /// host (`DOCLING_RS_ALLOW_PRIVATE_IP_FETCH` is the only way around it).
1262    pub fn image_hosts<I, S>(mut self, hosts: I) -> Self
1263    where
1264        I: IntoIterator<Item = S>,
1265        S: Into<String>,
1266    {
1267        self.image_hosts = hosts
1268            .into_iter()
1269            .map(|h| h.into().trim().to_ascii_lowercase())
1270            .filter(|h| !h.is_empty())
1271            .collect();
1272        self
1273    }
1274
1275    /// Largest image that resolves, in bytes (#646). Default 32 MiB
1276    /// (`DOCLING_RS_MAX_IMAGE_BYTES` overrides it); a larger one stays a
1277    /// placeholder.
1278    pub fn max_image_bytes(mut self, bytes: u64) -> Self {
1279        self.image_limits.max_bytes = Some(bytes.max(1));
1280        self
1281    }
1282
1283    /// How many images resolve per document (#646); the rest stay
1284    /// placeholders and one warning says so. Default unlimited
1285    /// (`DOCLING_RS_MAX_IMAGES` overrides it).
1286    pub fn max_images(mut self, count: usize) -> Self {
1287        self.image_limits.max_images = Some(count);
1288        self
1289    }
1290
1291    /// Total resolved image bytes per document, in MiB (#646). Default
1292    /// unlimited (`DOCLING_RS_MAX_IMAGE_TOTAL_MB` overrides it).
1293    pub fn max_image_total_mb(mut self, mb: u64) -> Self {
1294        self.image_limits.max_total_mb = Some(mb);
1295        self
1296    }
1297
1298    /// Smallest image that resolves, in bytes (#646) — spacers and tracking
1299    /// pixels are a few dozen bytes. Default 0 (`DOCLING_RS_MIN_IMAGE_BYTES`
1300    /// overrides it).
1301    pub fn min_image_bytes(mut self, bytes: u64) -> Self {
1302        self.image_limits.min_bytes = Some(bytes);
1303        self
1304    }
1305
1306    /// The Jupyter notebook backend (#673) under the builder's Markdown
1307    /// flavour, image policy and [`ipynb_outputs`](Self::ipynb_outputs).
1308    fn ipynb_backend(&self) -> crate::IpynbBackend {
1309        crate::IpynbBackend {
1310            strict: self.strict,
1311            images: self.image_policy(),
1312            outputs: self.ipynb_outputs,
1313        }
1314    }
1315
1316    /// The image policy a conversion runs under (#646): the builder's tier
1317    /// and hosts, the limits from the builder where set, else the
1318    /// environment, else the defaults.
1319    pub fn image_policy(&self) -> crate::ImagePolicy {
1320        let env = crate::ImageLimits::from_env();
1321        let o = &self.image_limits;
1322        crate::ImagePolicy {
1323            sources: self.image_sources,
1324            hosts: self.image_hosts.clone(),
1325            limits: crate::ImageLimits {
1326                max_bytes: o.max_bytes.unwrap_or(env.max_bytes),
1327                max_images: o.max_images.or(env.max_images),
1328                max_total_bytes: o
1329                    .max_total_mb
1330                    .map(|mb| mb.saturating_mul(1024 * 1024))
1331                    .or(env.max_total_bytes),
1332                min_bytes: o.min_bytes.unwrap_or(env.min_bytes),
1333            },
1334        }
1335    }
1336
1337    /// Append an `Attachments` section to converted emails (`.eml` / `.msg`):
1338    /// one list item per attachment, `name (content/type)` — names and types
1339    /// only, the payload is never embedded. docling's opt-in
1340    /// `EmailBackendOptions.list_attachments` (#251); off by default.
1341    pub fn list_attachments(mut self, list: bool) -> Self {
1342        self.list_attachments = list;
1343        self
1344    }
1345
1346    /// Omit empty cells from sparse spreadsheet table grids (#271; XLSX/XLS
1347    /// family, opt-in — a docling.rs extension, docling materialises the full
1348    /// bounding box). A ragged region's box is mostly padding on sparse
1349    /// sheets (~7× output inflation); with this on, each row keeps only its
1350    /// occupied cells (merge-covered continuations included) and a table
1351    /// that loses cells drops its span/structure overlay. Off by default —
1352    /// default output stays byte-for-byte docling.
1353    pub fn skip_empty_cells(mut self, skip: bool) -> Self {
1354        self.skip_empty_cells = skip;
1355        self
1356    }
1357
1358    /// Emit Markdown tables in the compact `| a | b |` / `| - | - |` form
1359    /// instead of docling-core's width-padded GitHub serializer (#271, all
1360    /// formats; opt-in — a docling.rs extension). On sparse spreadsheets the
1361    /// padding dominates the output size; compact rendering keeps the grid
1362    /// semantics and drops only whitespace. Off by default — default output
1363    /// stays byte-for-byte docling.
1364    pub fn compact_tables(mut self, compact: bool) -> Self {
1365        self.compact_tables = compact;
1366        self
1367    }
1368
1369    /// Render pictures' author-written alt text (#676) — the `descr` /
1370    /// `title` of a DOCX, PPTX or XLSX picture's non-visual properties,
1371    /// which the backends keep as the picture's description with
1372    /// `created_by = "alt_text"` — in the Markdown and HTML exports: the
1373    /// `![alt](…)` of an image line, the line a description takes above a
1374    /// placeholder, the `<img alt>` and the description text in HTML. Off
1375    /// by default, so the default Markdown and HTML stay byte-for-byte
1376    /// docling's; strict Markdown renders it either way, and the JSON
1377    /// always carries it as `meta.description`. MarkItDown prints the alt
1378    /// text.
1379    pub fn picture_alt_text(mut self, on: bool) -> Self {
1380        self.picture_alt_text = on;
1381        self
1382    }
1383
1384    /// Where the file's own metadata goes in the exports (#679) — an
1385    /// EPUB's Dublin Core, an Office package's properties, an ODF
1386    /// `meta.xml`, a photo's EXIF, an audio file's tags, a PDF's Info
1387    /// dictionary, read into `document.metadata`. `None` (the default)
1388    /// reads nothing and leaves every export as it was; `Json` adds a
1389    /// `metadata` object to the docling JSON; `Frontmatter` adds YAML front
1390    /// matter at the top of the Markdown as well. The PII pass
1391    /// ([`redact_pii`](Self::redact_pii)) covers the metadata: author
1392    /// fields are masked as persons, the GPS position is dropped.
1393    pub fn metadata_output(mut self, mode: docling_core::MetadataOutput) -> Self {
1394        self.metadata_output = mode;
1395        self
1396    }
1397
1398    /// The metadata of `source` as [`metadata_output`](Self::metadata_output)
1399    /// would read it, whatever the mode — for a caller that streams a
1400    /// document itself and wants the front matter
1401    /// (`MarkdownStreamer::with_metadata`). Reads headers only; empty for a
1402    /// format that carries none.
1403    pub fn document_metadata(&self, source: &SourceDocument) -> docling_core::DocumentMetadata {
1404        crate::metadata::read(source, self.password.as_deref())
1405    }
1406
1407    /// Insert `placeholder` between pages in the Markdown export — docling's
1408    /// `export_to_markdown(page_break_placeholder=…)` (docling-core's
1409    /// `MarkdownParams`, docling-serve's `md_page_break_placeholder`). Where
1410    /// docling marks a break between two items whose `prov.page_no` differ,
1411    /// the serializer here marks it between two rendered blocks separated by a
1412    /// page boundary — the `PageInfo` marker opening every PDF page and sheet,
1413    /// the `PageBreak` between slides and DjVu / DocTags pages — so a break
1414    /// never leads or trails the document and empty pages collapse into one.
1415    /// `None` (the default) keeps Markdown free of page breaks, as docling's
1416    /// default export is. Markdown only; JSON carries pages in `prov`.
1417    pub fn page_break_placeholder(mut self, placeholder: Option<String>) -> Self {
1418        self.page_break_placeholder = placeholder;
1419        self
1420    }
1421
1422    /// The document-level settings [`convert`](Self::convert) applies to
1423    /// every backend's output: the serializer knobs carried on the document
1424    /// (`strict`, `compact_tables`, `page_break_placeholder`) so each later
1425    /// Markdown export agrees, and first-class cells for every table. Public
1426    /// for callers that run a backend themselves — docling-serve converts
1427    /// PDFs and images on a warm `Pipeline` and finishes
1428    /// them here, so a request's options reach them as they reach every
1429    /// other format (#547).
1430    pub fn finish_document(&self, document: &mut docling_core::DoclingDocument) {
1431        // Carry the mode so `result.document.export_to_markdown()` reflects it.
1432        document.strict_markdown = self.strict;
1433        // Compact tables (#271) is additive: the PDF backend already turns it
1434        // on for its own corpus; never turn it back off here.
1435        if self.compact_tables {
1436            document.compact_tables = true;
1437        }
1438        // Alt text in Markdown/HTML (#676): additive like compact tables.
1439        if self.picture_alt_text {
1440            document.picture_alt_text = true;
1441        }
1442        // The metadata output mode (#679), likewise.
1443        if self.metadata_output.in_json() {
1444            document.metadata_output = self.metadata_output;
1445        }
1446        // Page-break placeholder: a serializer knob like `strict`, carried on
1447        // the document so every Markdown export of it agrees.
1448        if self.page_break_placeholder.is_some() {
1449            document.page_break_placeholder = self.page_break_placeholder.clone();
1450        }
1451        // First-class cells for every table (#240): backends with page
1452        // geometry (the PDF TableFormer paths) set them; everything else —
1453        // declarative tables included — derives them from the grid plus the
1454        // structure overlay (real spans for DOCX/XLSX merges, HTML `th`
1455        // headers, ODF covered cells; 1×1 records otherwise), so the repair
1456        // API and the JSON `table_cells` are populated uniformly.
1457        for table in document.tables_mut() {
1458            if table.cells.is_none() {
1459                table.cells = Some(table.derive_cells());
1460            }
1461        }
1462    }
1463
1464    /// The picture enrichment pass: describe the pictures through the
1465    /// vision endpoint when [`picture_description`](Self::picture_description)
1466    /// is set (#670), OCR the embedded pictures when
1467    /// [`do_picture_ocr`](Self::do_picture_ocr) asks for it (#645), then
1468    /// drop the image bytes unless [`keep_picture_images`](Self::keep_picture_images)
1469    /// keeps them. Runs on every conversion after the backend, before
1470    /// [`finish_document`](Self::finish_document).
1471    fn enrich_pictures(
1472        &self,
1473        document: &mut docling_core::DoclingDocument,
1474        source: &SourceDocument,
1475    ) {
1476        let format = source.format;
1477        #[cfg(feature = "vlm")]
1478        if let Some(opts) = &self.picture_description {
1479            self.describe_pictures(document, source, opts);
1480        }
1481        if self.picture_ocr {
1482            self.ocr_pictures(document, format);
1483        }
1484        if !self.keep_picture_images {
1485            strip_picture_images(document);
1486        }
1487    }
1488
1489    /// The picture-OCR pass itself: PDF, image and METS pages already went
1490    /// through the OCR pipeline, so their pictures are left alone, and a
1491    /// video's frames were read as they were decoded
1492    /// ([`convert_video`](Self::convert_video)); with OCR disabled, or
1493    /// without the recognizer, the pictures keep no text and one warning
1494    /// says why. The same image embedded twice — a DOCX walked into both
1495    /// the flat nodes and the item tree, a slide master's logo on every
1496    /// slide — is read once (cached by its bytes).
1497    fn ocr_pictures(&self, document: &mut docling_core::DoclingDocument, format: InputFormat) {
1498        use docling_core::{tree::TreeKind, Node};
1499
1500        if matches!(
1501            format,
1502            InputFormat::Pdf | InputFormat::Image | InputFormat::MetsGbs | InputFormat::Video
1503        ) {
1504            return;
1505        }
1506        let Some(mut reader) = self.picture_reader() else {
1507            return;
1508        };
1509        document.for_each_picture_mut(&mut |node| {
1510            if let Node::Picture {
1511                image: Some(img),
1512                description,
1513                ..
1514            } = node
1515            {
1516                if undescribed(description) {
1517                    *description = reader.read(img);
1518                }
1519            }
1520        });
1521        if let Some(tree) = document.tree.as_mut() {
1522            for item in tree.items.iter_mut() {
1523                if let TreeKind::Picture {
1524                    image: Some(img),
1525                    description,
1526                    ..
1527                } = &mut item.kind
1528                {
1529                    if undescribed(description) {
1530                        *description = reader.read(img);
1531                    }
1532                }
1533            }
1534        }
1535    }
1536
1537    /// The picture-description pass (#670). Two walks over the document:
1538    /// the first collects every undescribed picture that passes the size
1539    /// floor and the class filter, keyed by its bytes so a logo on every
1540    /// slide is asked about once; the requests run on `concurrency` threads;
1541    /// the second walk writes the answers back. In caption mode an image
1542    /// input, which the layout model turned into text and figures, is also
1543    /// described as a whole — the caption MarkItDown gives an image file.
1544    #[cfg(feature = "vlm")]
1545    fn describe_pictures(
1546        &self,
1547        document: &mut docling_core::DoclingDocument,
1548        source: &SourceDocument,
1549        opts: &crate::vlm::PictureDescriptionOptions,
1550    ) {
1551        use std::collections::HashMap;
1552        use std::hash::{Hash, Hasher};
1553
1554        use docling_core::{tree::TreeKind, Node, PictureDescription, PictureImage};
1555
1556        fn key_of(data: &[u8]) -> u64 {
1557            let mut h = std::collections::hash_map::DefaultHasher::new();
1558            data.hash(&mut h);
1559            h.finish()
1560        }
1561
1562        // Walk 1: the candidates, in document order, each distinct image once.
1563        let mut order: Vec<u64> = Vec::new();
1564        let mut images: HashMap<u64, PictureImage> = HashMap::new();
1565        let mut collect = |img: &PictureImage, description: &Option<PictureDescription>| {
1566            if !undescribed(description) {
1567                return;
1568            }
1569            let key = key_of(&img.data);
1570            if let std::collections::hash_map::Entry::Vacant(e) = images.entry(key) {
1571                order.push(key);
1572                e.insert(img.clone());
1573            }
1574        };
1575        document.for_each_picture_mut(&mut |node| {
1576            if let Node::Picture {
1577                image: Some(img),
1578                description,
1579                ..
1580            } = node
1581            {
1582                collect(img, description);
1583            }
1584        });
1585        if let Some(tree) = document.tree.as_ref() {
1586            for item in &tree.items {
1587                if let TreeKind::Picture {
1588                    image: Some(img),
1589                    description,
1590                    ..
1591                } = &item.kind
1592                {
1593                    collect(img, description);
1594                }
1595            }
1596        }
1597        // An image input as a whole (caption mode): the layout model split
1598        // it into text and figures, but the file is the picture.
1599        let whole = (source.format == InputFormat::Image
1600            && opts.mode == crate::vlm::PictureDescriptionMode::Caption)
1601            .then(|| PictureImage {
1602                mimetype: image_mimetype(&source.bytes)
1603                    .unwrap_or("application/octet-stream")
1604                    .into(),
1605                width: 0,
1606                height: 0,
1607                data: source.bytes.clone(),
1608                dpi: PictureImage::DEFAULT_DPI,
1609            });
1610        if let Some(img) = &whole {
1611            collect(img, &None);
1612        }
1613        if order.is_empty() {
1614            return;
1615        }
1616
1617        // The filters picture OCR applies (#645): the size floor on the
1618        // declared, then decoded, size; the classifier's top label when
1619        // classes are named.
1620        let min_side = self
1621            .picture_ocr_min_side
1622            .or_else(|| docling_core::env::parse::<u32>("DOCLING_RS_PICTURE_OCR_MIN_SIDE"))
1623            .unwrap_or(32);
1624        let mut classifier = (!self.picture_ocr_classes.is_empty())
1625            .then(|| docling_pdf::Pipeline::new().ok())
1626            .flatten()
1627            .map(|p| p.no_ocr(true).no_table_former(true));
1628        let mut jobs: Vec<(u64, String, Vec<u8>)> = Vec::new();
1629        for key in &order {
1630            let img = &images[key];
1631            if img.width.min(img.height) < min_side && img.width * img.height > 0 {
1632                continue;
1633            }
1634            // The endpoint takes PNG/JPEG/GIF/WebP data URIs; a BMP or TIFF
1635            // is re-encoded, a vector or Windows metafile picture skipped.
1636            let Some((mimetype, bytes)) = endpoint_image(img) else {
1637                docling_core::debug_log!(
1638                    "docling: picture description: {} is not an image the endpoint takes; skipped",
1639                    img.mimetype
1640                );
1641                continue;
1642            };
1643            if min_side > 0 || classifier.is_some() {
1644                let decoded = match image::load_from_memory(&bytes) {
1645                    Ok(d) => d.into_rgb8(),
1646                    Err(e) => {
1647                        docling_core::debug_log!(
1648                            "docling: picture description: undecodable image: {e}"
1649                        );
1650                        continue;
1651                    }
1652                };
1653                if decoded.width().min(decoded.height()) < min_side {
1654                    continue;
1655                }
1656                if let Some(p) = classifier.as_mut() {
1657                    if let Some(preds) = p.classify_picture(&decoded) {
1658                        let top = preds.first().map(|c| c.class_name.as_str());
1659                        if !top.is_some_and(|t| self.picture_ocr_classes.iter().any(|c| c == t)) {
1660                            continue;
1661                        }
1662                    }
1663                }
1664            }
1665            jobs.push((*key, mimetype.to_string(), bytes.into_owned()));
1666        }
1667        if jobs.is_empty() {
1668            return;
1669        }
1670
1671        // The requests: `concurrency` workers pull from one queue; a
1672        // rejected picture is warned about and skipped, an unreachable
1673        // endpoint stops the queue — every later picture would wait out the
1674        // same retries for the same answer.
1675        let agent = crate::vlm::agent();
1676        let next = std::sync::atomic::AtomicUsize::new(0);
1677        let stop = std::sync::atomic::AtomicBool::new(false);
1678        let answers: std::sync::Mutex<HashMap<u64, String>> = std::sync::Mutex::new(HashMap::new());
1679        let workers = opts.concurrency.max(1).min(jobs.len());
1680        std::thread::scope(|scope| {
1681            for _ in 0..workers {
1682                scope.spawn(|| loop {
1683                    if stop.load(std::sync::atomic::Ordering::Relaxed) {
1684                        break;
1685                    }
1686                    let i = next.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1687                    let Some((key, mimetype, bytes)) = jobs.get(i) else {
1688                        break;
1689                    };
1690                    match opts.describe(&agent, mimetype, bytes) {
1691                        Ok(Some(text)) => {
1692                            answers.lock().unwrap().insert(*key, text);
1693                        }
1694                        Ok(None) => {}
1695                        Err(crate::vlm::RequestError::Rejected(e)) => {
1696                            eprintln!("warning: picture description: {e}; the picture keeps none");
1697                        }
1698                        Err(crate::vlm::RequestError::Unavailable(e)) => {
1699                            if !stop.swap(true, std::sync::atomic::Ordering::Relaxed) {
1700                                let left = jobs.len().saturating_sub(i);
1701                                eprintln!(
1702                                    "warning: picture description: {e}; {left} picture(s) keep no \
1703                                     description"
1704                                );
1705                            }
1706                        }
1707                    }
1708                });
1709            }
1710        });
1711        let answers = answers.into_inner().unwrap();
1712        if answers.is_empty() {
1713            return;
1714        }
1715
1716        // Walk 2: the answers onto every picture carrying those bytes.
1717        let provenance = opts.provenance();
1718        let described = |img: &PictureImage| -> Option<PictureDescription> {
1719            answers
1720                .get(&key_of(&img.data))
1721                .map(|text| PictureDescription {
1722                    text: text.clone(),
1723                    provenance: provenance.clone(),
1724                })
1725        };
1726        document.for_each_picture_mut(&mut |node| {
1727            if let Node::Picture {
1728                image: Some(img),
1729                description,
1730                ..
1731            } = node
1732            {
1733                if undescribed(description) {
1734                    *description = described(img);
1735                }
1736            }
1737        });
1738        if let Some(tree) = document.tree.as_mut() {
1739            for item in tree.items.iter_mut() {
1740                if let TreeKind::Picture {
1741                    image: Some(img),
1742                    description,
1743                    ..
1744                } = &mut item.kind
1745                {
1746                    if undescribed(description) {
1747                        *description = described(img);
1748                    }
1749                }
1750            }
1751        }
1752        if let Some(img) = whole {
1753            if let Some(description) = described(&img) {
1754                document.nodes.push(Node::Picture {
1755                    caption: None,
1756                    caption_href: None,
1757                    image: self.keep_picture_images.then_some(img),
1758                    classification: None,
1759                    description: Some(description),
1760                    caption_parent: Default::default(),
1761                    caption_location: None,
1762                });
1763            }
1764        }
1765    }
1766
1767    /// The reader the picture-OCR pass (#645) and the video frame hook
1768    /// (#647) share: the OCR models only — no layout, no TableFormer, the
1769    /// caller already knows each whole image is the picture — behind the
1770    /// size floor and the classifier filter. `None` (after one warning)
1771    /// when OCR is disabled or the recognizer cannot load.
1772    #[cfg(feature = "pdf")]
1773    fn picture_reader(&self) -> Option<PictureReader> {
1774        static WARNED: std::sync::Once = std::sync::Once::new();
1775        if self.no_ocr || self.text_layer_only {
1776            WARNED.call_once(|| {
1777                eprintln!(
1778                    "warning: picture OCR requested, but OCR is disabled (no_ocr / \
1779                     text_layer_only); pictures keep no text"
1780                );
1781            });
1782            return None;
1783        }
1784        let pipeline = docling_pdf::Pipeline::new().map(|p| {
1785            self.with_textline_orientation(
1786                p.no_ocr(true)
1787                    .no_table_former(true)
1788                    .ocr_lang(self.ocr_lang_choice())
1789                    .ocr_engine(self.ocr_engine_choice())
1790                    .tesseract_lang(self.tesseract_lang_choice())
1791                    .ocr_scale(self.ocr_scale_choice())
1792                    .picture_ocr_scale(self.picture_ocr_scale_choice()),
1793            )
1794        });
1795        let pipeline = match pipeline {
1796            Ok(p) => p,
1797            Err(e) => {
1798                WARNED.call_once(|| {
1799                    eprintln!("warning: picture OCR unavailable ({e}); pictures keep no text");
1800                });
1801                return None;
1802            }
1803        };
1804        let min_side = self
1805            .picture_ocr_min_side
1806            .or_else(|| docling_core::env::parse::<u32>("DOCLING_RS_PICTURE_OCR_MIN_SIDE"))
1807            .unwrap_or(32);
1808        Some(PictureReader {
1809            pipeline,
1810            min_side,
1811            classes: self.picture_ocr_classes.clone(),
1812            cache: std::collections::HashMap::new(),
1813        })
1814    }
1815
1816    /// Without the `pdf` feature there is no OCR engine to run: one warning,
1817    /// the pictures keep no text.
1818    #[cfg(not(feature = "pdf"))]
1819    fn picture_reader(&self) -> Option<PictureReader> {
1820        static WARNED: std::sync::Once = std::sync::Once::new();
1821        WARNED.call_once(|| {
1822            eprintln!(
1823                "warning: picture OCR requested, but this build has no OCR engine (rebuild \
1824                 with the `pdf` feature); pictures keep no text"
1825            );
1826        });
1827        None
1828    }
1829
1830    /// The frame sampling a video gets (#647): the builder's settings, else
1831    /// the environment's, else the defaults.
1832    #[cfg(feature = "asr")]
1833    fn frame_options(&self) -> crate::video::FrameOptions {
1834        use docling_core::env;
1835        crate::video::FrameOptions {
1836            max_frames: self.video_frames.unwrap_or(DEFAULT_VIDEO_FRAMES),
1837            scene_threshold: self
1838                .video_scene_threshold
1839                .or_else(|| env::parse::<f32>("DOCLING_RS_VIDEO_SCENE_THRESHOLD"))
1840                .map_or(crate::video::DEFAULT_SCENE_THRESHOLD, |t| t.clamp(0.0, 1.0)),
1841            max_side: self
1842                .video_frame_max_side
1843                .or_else(|| env::parse::<u32>("DOCLING_RS_VIDEO_FRAME_MAX_SIDE"))
1844                .unwrap_or(0),
1845            dedupe: self
1846                .video_frame_dedupe
1847                .or_else(|| env::parse::<u32>("DOCLING_RS_VIDEO_FRAME_DEDUPE"))
1848                .map(|d| d.min(64)),
1849        }
1850    }
1851
1852    /// Video (#138): the audio track transcribes through the ASR path
1853    /// (Phase 1), and — when the ffmpeg binary is available — sampled
1854    /// frames interleave with the transcript as timestamped pictures
1855    /// (Phase 2). Without ffmpeg: transcript only. Each frame goes through
1856    /// the picture enrichment as soon as it is decoded (#647): read by the
1857    /// OCR models when [`do_picture_ocr`](Self::do_picture_ocr) asks, its
1858    /// bytes dropped when [`keep_picture_images`](Self::keep_picture_images)
1859    /// is off — so however many frames are sampled, one is in memory at a
1860    /// time. The models load on the first frame; a video without one costs
1861    /// nothing.
1862    #[cfg(feature = "asr")]
1863    fn convert_video(
1864        &self,
1865        source: &SourceDocument,
1866    ) -> Result<docling_core::DoclingDocument, String> {
1867        use docling_core::Node;
1868        let opts = self.frame_options();
1869        let mut reader: Option<Option<PictureReader>> = None;
1870        let mut on_frame = |node: &mut Node| {
1871            if self.picture_ocr {
1872                let reader = reader.get_or_insert_with(|| self.picture_reader());
1873                if let (
1874                    Some(reader),
1875                    Node::Picture {
1876                        image: Some(img),
1877                        description,
1878                        ..
1879                    },
1880                ) = (reader.as_mut(), &mut *node)
1881                {
1882                    if undescribed(description) {
1883                        *description = reader.read(img);
1884                    }
1885                }
1886            }
1887            if !self.keep_picture_images {
1888                if let Node::Picture { image, .. } = node {
1889                    *image = None;
1890                }
1891            }
1892        };
1893        crate::video::convert_video(
1894            &source.bytes,
1895            &source.name,
1896            self.asr_model.as_deref(),
1897            self.asr_lang.as_deref(),
1898            &opts,
1899            &mut on_frame,
1900        )
1901    }
1902
1903    /// The copybook layout for EBCDIC sources (#252): docling's
1904    /// `EbcdicLayout` JSON, inline (a string starting with `{`) or as a file
1905    /// path. Without it, a path-loaded source looks for a
1906    /// `<stem>.layout.json` sidecar; converting EBCDIC with neither is an
1907    /// error — the bytes are meaningless without their copybook.
1908    pub fn ebcdic_layout(mut self, layout: impl Into<String>) -> Self {
1909        self.ebcdic_layout = Some(layout.into());
1910        self
1911    }
1912
1913    /// Option-typed variant of [`ebcdic_layout`](Self::ebcdic_layout) for
1914    /// call sites plumbing an optional flag through (`None` keeps the
1915    /// sidecar fallback).
1916    pub fn ebcdic_layout_opt(mut self, layout: Option<String>) -> Self {
1917        self.ebcdic_layout = layout;
1918        self
1919    }
1920
1921    /// Skip loading and running the TableFormer table-structure model for
1922    /// PDF/image/METS sources.
1923    ///
1924    /// Off by default. When enabled, table regions are still detected and
1925    /// emitted, but their structure is reconstructed geometrically from cell
1926    /// positions instead of the ONNX model's predicted structure — no model
1927    /// load and no per-table inference, at the cost of table fidelity. Useful
1928    /// when parsing speed matters more than exact table structure, especially
1929    /// with [`convert_streaming`](Self::convert_streaming).
1930    pub fn no_table_former(mut self, disable: bool) -> Self {
1931        self.no_table_former = disable;
1932        self
1933    }
1934
1935    /// PDF/image: keep every detected picture as a picture — disable the
1936    /// text-panel demotion that turns an uncaptioned, dense text-panel
1937    /// "picture" into paragraphs (#157). The escape hatch for
1938    /// image-extraction workflows and for charts the heuristic might still
1939    /// misjudge on scanned pages (#173).
1940    pub fn no_text_panels(mut self, disable: bool) -> Self {
1941        self.no_text_panels = disable;
1942        self
1943    }
1944
1945    /// Infer PDF/image section-header levels after assembly (#302, docling's
1946    /// `HeadingHierarchyModel` with its default options): the PDF outline
1947    /// (bookmarks) is authoritative, legal/outline numbering covers headings
1948    /// without a bookmark match, and font size/weight/slant/case rank the
1949    /// rest. Off by default (docling parity): every detected heading then
1950    /// keeps the flat level the assembler emits. Non-PDF/image formats
1951    /// ignore it (their backends carry real heading levels already).
1952    pub fn heading_hierarchy(mut self, enable: bool) -> Self {
1953        self.heading_hierarchy = enable;
1954        self
1955    }
1956
1957    /// Skip layout detection, OCR, and TableFormer entirely for PDF/image/METS
1958    /// sources — no model load, no inference of any kind (#611; this was
1959    /// `no_ocr` before 2.0).
1960    ///
1961    /// Off by default. When enabled, the PDF's embedded text cells are grouped by
1962    /// line and emitted as plain paragraphs in reading order: no headings, lists,
1963    /// tables, code blocks, or pictures, since that structure comes from the
1964    /// layout model. The fastest possible PDF path, but pages with no embedded
1965    /// text layer (scanned/image-only PDFs) yield no text at all — convert those
1966    /// without this flag. Implies [`no_table_former`](Self::no_table_former).
1967    pub fn text_layer_only(mut self, enable: bool) -> Self {
1968        self.text_layer_only = enable;
1969        self
1970    }
1971
1972    /// Never run OCR, but keep layout detection and TableFormer — docling's
1973    /// `do_ocr=False`, its CLI's `--no-ocr` (#244; since 2.0, #611, the
1974    /// meaning of `no_ocr` too). Unlike
1975    /// [`text_layer_only`](Self::text_layer_only) (the skip-everything fast
1976    /// path), structured output — headings, tables, pictures, reading order —
1977    /// is preserved; only text that exists solely as pixels is lost (scanned
1978    /// pages come back with empty regions, and the speculative OCR of large
1979    /// embedded images never runs). The OCR model is never loaded, and
1980    /// independently of this flag a *missing* OCR model degrades to the same
1981    /// behavior with a warning instead of failing the conversion. SVG inputs
1982    /// route to direct `<text>` extraction (their text is native — skipping
1983    /// OCR must not lose it).
1984    pub fn no_ocr(mut self, disable: bool) -> Self {
1985        self.no_ocr = disable;
1986        self
1987    }
1988
1989    /// [`no_ocr`](Self::no_ocr) under its pre-2.0 name, kept as an alias.
1990    pub fn skip_ocr(self, disable: bool) -> Self {
1991        self.no_ocr(disable)
1992    }
1993
1994    /// The password of an encrypted document: a PDF (docling's
1995    /// `--pdf-password`, #611) or an Office document (#625, a docling.rs
1996    /// extension — docling reads none): `.docx`/`.xlsx`/`.pptx` (Agile and
1997    /// Standard encryption), `.doc`/`.xls`/`.ppt` (RC4 and RC4 CryptoAPI).
1998    ///
1999    /// A missing or wrong PDF password fails the conversion with "the PDF is
2000    /// encrypted: a password is required"; PDF passwords are read on the ML
2001    /// pipeline only (the `pdf-text` / wasm build reads unencrypted PDFs).
2002    /// Office documents decrypt in every build. Without a password, or when
2003    /// it is wrong, the format's default password is tried (Excel's
2004    /// `VelvetSweatshop`, PowerPoint's for modify-password-only files);
2005    /// otherwise the error says the document is encrypted, or that the
2006    /// password is wrong.
2007    pub fn password(mut self, password: Option<String>) -> Self {
2008        self.password = password;
2009        self
2010    }
2011
2012    /// [`password`](Self::password) under docling's PDF-only name.
2013    pub fn pdf_password(self, password: Option<String>) -> Self {
2014        self.password(password)
2015    }
2016
2017    /// OCR every PDF page from its rendered image even when the page carries
2018    /// an embedded text layer — docling's `force_full_page_ocr`. The escape
2019    /// hatch for text layers that exist but lie (broken encodings, subset
2020    /// fonts with garbage mappings, scanned forms with a few typed-in
2021    /// fields). Off by default; ignored when [`no_ocr`](Self::no_ocr) or
2022    /// [`text_layer_only`](Self::text_layer_only) is set,
2023    /// mirroring docling, where it is a sub-option of `do_ocr`. Applies to
2024    /// PDFs only — standalone images are always OCR'd.
2025    pub fn force_full_page_ocr(mut self, force: bool) -> Self {
2026        self.force_full_page_ocr = force;
2027        self
2028    }
2029
2030    /// Which document regions feed the OCR — docling's `OcrMode` (#254):
2031    /// `default`, `full_page`, `layout_regions`, or
2032    /// `pdf_aware_layout_regions`. The default is the text-layer-aware
2033    /// behavior (docling's `pdf_aware_layout_regions`);
2034    /// `full_page`/`layout_regions` discard the text layer like
2035    /// [`force_full_page_ocr`](Self::force_full_page_ocr) — see
2036    /// [`docling_pdf::OcrMode`] for the mapping. An unknown value warns at
2037    /// conversion time and uses the default. PDF/image ML pipeline only.
2038    pub fn ocr_mode(mut self, mode: impl Into<String>) -> Self {
2039        self.ocr_mode = Some(mode.into());
2040        self
2041    }
2042
2043    /// Which OCR engine recognizes text on scanned pages (#460): `"ppocr"`
2044    /// (the default — the built-in PP-OCRv3 recognizer, the conformance
2045    /// engine) or `"tesseract"` (the system `tesseract` binary, docling's
2046    /// `TesseractCliOcrOptions`; needs `tesseract-ocr` with a language pack
2047    /// installed — `DOCLING_TESSERACT` names the binary,
2048    /// `DOCLING_RS_TESSERACT_PSM` its page segmentation mode,
2049    /// `DOCLING_RS_TESSDATA_DIR` / `TESSDATA_PREFIX` its data). Both read
2050    /// the same layout-region crops; [`ocr_lang`](Self::ocr_lang) is the
2051    /// engine's language. An unknown value warns at conversion time and uses
2052    /// the default (`DOCLING_RS_OCR_ENGINE`, else PP-OCR). Formats that never
2053    /// OCR ignore it.
2054    pub fn ocr_engine(mut self, engine: impl Into<String>) -> Self {
2055        self.ocr_engine = Some(engine.into());
2056        self
2057    }
2058
2059    /// OCR render scale in pixels per PDF point — docling's
2060    /// `OcrOptions.scale` (#254; docling's default 3 = 216 dpi). Unset feeds
2061    /// the recognizer the pipeline's own 2.0 px/pt page render; a different
2062    /// value resamples that render for the OCR input only, leaving layout and
2063    /// TableFormer pixels untouched. Non-positive values warn at conversion
2064    /// time and are ignored. PDF/image ML pipeline only.
2065    pub fn ocr_scale(mut self, scale: f32) -> Self {
2066        self.ocr_scale = Some(scale);
2067        self
2068    }
2069
2070    /// RapidOCR's handling of text-line orientation (#666), off by default
2071    /// (`DOCLING_RS_OCR_TEXTLINE_ORIENTATION` sets the process default):
2072    /// detected lines are cropped along the detector's rotated rectangle, a
2073    /// crop at least 1.5× taller than wide is turned 90°, and the
2074    /// PP-LCNet text-line orientation classifier
2075    /// (`.models/ocr_textline_ori.onnx`) turns upside-down lines — so
2076    /// vertical axis titles, rotated headers, skewed and upside-down lines
2077    /// read as text. Applies to the PP-OCR lines of scanned pages, images
2078    /// and pictures alike (changing their output when on); table words and
2079    /// Tesseract are untouched. A missing classifier warns once and keeps
2080    /// the crop and the 90° turn.
2081    pub fn ocr_textline_orientation(mut self, enable: bool) -> Self {
2082        self.ocr_textline_orientation = Some(enable);
2083        self
2084    }
2085
2086    /// Pixels per PDF point for picture crops and page images — docling's
2087    /// `images_scale` (#520). Unset delivers crops at the pipeline's own 2.0
2088    /// px/pt render (144 dpi), as before; another value resamples it (above
2089    /// 2.0 that upsamples, it does not re-render). The picture's `dpi` in the
2090    /// JSON export is 72·scale either way (#519). Non-finite or non-positive
2091    /// values are ignored. PDF/image ML pipeline only.
2092    pub fn images_scale(mut self, scale: f32) -> Self {
2093        self.images_scale = Some(scale).filter(|s| s.is_finite() && *s > 0.0);
2094        self
2095    }
2096
2097    /// Keep every page's render as a page image — docling's
2098    /// `generate_page_images` (#520): the JSON export carries it as
2099    /// `pages[n].image` at [`Self::images_scale`], which docling-core's
2100    /// `TableItem.get_image` / `FormulaItem.get_image` crop from. Off by
2101    /// default (one full-page PNG per page in memory). PDF/image ML pipeline
2102    /// only; text-layer-only (`text_layer_only`) and streaming conversions get none.
2103    pub fn generate_page_images(mut self, enabled: bool) -> Self {
2104        self.generate_page_images = enabled;
2105        self
2106    }
2107
2108    /// Classify each detected picture with the DocumentFigureClassifier model
2109    /// (docling's `do_picture_classification`). Off by default.
2110    ///
2111    /// The full 26-class prediction distribution (bar_chart, logo, signature,
2112    /// …) lands on the picture item and is serialized into the docling JSON as
2113    /// the `classification` annotation plus the `meta.classification` field.
2114    /// Markdown output is unaffected. Needs `.models/picture_classifier.onnx`
2115    /// (fetched by `scripts/install/download_dependencies.sh`); a missing
2116    /// model warns once and skips classification.
2117    pub fn do_picture_classification(mut self, enable: bool) -> Self {
2118        self.enrich.picture_classification = enable;
2119        self
2120    }
2121
2122    /// OCR the pictures embedded in non-PDF documents (#645) — a DOCX/PPTX
2123    /// screenshot, an HTML figure, a sampled video frame — with the ML
2124    /// pipeline's OCR models (the PP-OCR recognizer + the `ocr_det.onnx`
2125    /// line detector when installed, or Tesseract under
2126    /// [`ocr_engine`](Self::ocr_engine)), and attach the text to the picture
2127    /// as docling's `PictureDescriptionData` annotation: Markdown prints it
2128    /// between the caption and the image placeholder, JSON/DCLX carry it as
2129    /// `meta.description` + the `description` annotation, the hybrid chunker
2130    /// puts it in the picture's chunk. Off by default — every default export
2131    /// is unchanged. Nothing is attached to a picture the engine reads no
2132    /// text from (lines under `DOCLING_RS_OCR_TEXT_SCORE` are dropped as on a
2133    /// scanned page). PDF, image and METS inputs are untouched: their pages
2134    /// go through the OCR pipeline already. With [`no_ocr`](Self::no_ocr) /
2135    /// [`text_layer_only`](Self::text_layer_only), or without the OCR model
2136    /// (or the `pdf` feature), one warning and no text. See also
2137    /// [`picture_ocr_classes`](Self::picture_ocr_classes),
2138    /// [`picture_ocr_min_side`](Self::picture_ocr_min_side) and
2139    /// [`keep_picture_images`](Self::keep_picture_images).
2140    pub fn do_picture_ocr(mut self, enable: bool) -> Self {
2141        self.picture_ocr = enable;
2142        self
2143    }
2144
2145    /// Only OCR the pictures the DocumentFigureClassifier labels as one of
2146    /// `labels` (its 26 classes: `screenshot_from_computer`,
2147    /// `screenshot_from_manual`, `logo`, `photograph`, …), judged by its top
2148    /// prediction — the way to skip photos and logos on a slide deck while
2149    /// reading its screenshots. Empty (the default) OCRs every picture that
2150    /// passes the size floor. Needs `.models/picture_classifier.onnx`; a
2151    /// missing model warns once and the filter is waived.
2152    pub fn picture_ocr_classes<I, S>(mut self, labels: I) -> Self
2153    where
2154        I: IntoIterator<Item = S>,
2155        S: Into<String>,
2156    {
2157        self.picture_ocr_classes = labels
2158            .into_iter()
2159            .map(|s| s.into().trim().to_ascii_lowercase())
2160            .filter(|s| !s.is_empty())
2161            .collect();
2162        self
2163    }
2164
2165    /// The smallest side, in pixels, a picture must have to be OCR'd:
2166    /// bullets, icons and rules are skipped without decoding or inference.
2167    /// Default 32 (`DOCLING_RS_PICTURE_OCR_MIN_SIDE` overrides it); `0`
2168    /// reads everything.
2169    pub fn picture_ocr_min_side(mut self, px: u32) -> Self {
2170        self.picture_ocr_min_side = Some(px);
2171        self
2172    }
2173
2174    /// The picture OCR's resolution (#666), in pixels per picture pixel
2175    /// before RapidOCR's 2000 px longer-side cap: `1.0` reads a picture at
2176    /// its native pixels, as RapidOCR does, shrinking only what exceeds
2177    /// 2000 px. Unset (`DOCLING_RS_PICTURE_OCR_SCALE`, else the image-input
2178    /// rule) reads it like a scanned image — [`ocr_scale`](Self::ocr_scale)
2179    /// when set, else 3 px/pt under the cap, which upscales a 720 × 180
2180    /// screenshot to 2000 × 500. Scanned pages and image inputs are
2181    /// unaffected. Non-positive values warn and are ignored.
2182    pub fn picture_ocr_scale(mut self, scale: f32) -> Self {
2183        self.picture_ocr_scale = Some(scale);
2184        self
2185    }
2186
2187    /// Describe every picture through an OpenAI-compatible vision endpoint
2188    /// (#670) — MarkItDown's `llm_client` / `llm_model` / `llm_prompt` and
2189    /// its markitdown-ocr plugin, for every format: the embedded pictures of
2190    /// DOCX/PPTX/XLSX/HTML, a PDF's or scan's figure crops, sampled video
2191    /// frames, and (in caption mode) an image input as a whole. The answer
2192    /// becomes the picture's description annotation, where
2193    /// [`do_picture_ocr`](Self::do_picture_ocr) puts its text: Markdown
2194    /// prints it after the caption, JSON carries `meta.description` with the
2195    /// model as `created_by`. [`picture_ocr_min_side`](Self::picture_ocr_min_side)
2196    /// and [`picture_ocr_classes`](Self::picture_ocr_classes) select the
2197    /// pictures here too; identical image bytes are sent once per document;
2198    /// `concurrency` pictures are in flight at once. An endpoint that rejects
2199    /// a picture warns and the rest go on; one that cannot be reached warns
2200    /// once and the remaining pictures keep no description — the conversion
2201    /// never fails over it. Runs before the local picture OCR, which then
2202    /// reads only what stayed undescribed.
2203    #[cfg(feature = "vlm")]
2204    pub fn picture_description(mut self, opts: crate::vlm::PictureDescriptionOptions) -> Self {
2205        self.picture_description = Some(opts);
2206        self
2207    }
2208
2209    /// Whether the pictures keep their embedded image bytes (the default,
2210    /// `true`): `false` drops them from every picture after the enrichment
2211    /// pass, so a document whose images were only there to be read — a slide
2212    /// deck of screenshots, the sampled frames of a video — exports a slim
2213    /// JSON/DCLX and a placeholder-only Markdown while keeping the OCR text.
2214    pub fn keep_picture_images(mut self, keep: bool) -> Self {
2215        self.keep_picture_images = keep;
2216        self
2217    }
2218
2219    /// Redact personal data from every converted document (#621): after
2220    /// the backend builds the [`DoclingDocument`](docling_core::DoclingDocument)
2221    /// and before any export, chunker or stream reads it, every detected
2222    /// span — e-mail, phone, card number, IBAN, IP, URL credentials,
2223    /// national IDs, and names / organizations / locations when the NER
2224    /// model is installed (`.models/ner/`, the `ner` feature) — is replaced
2225    /// in place by a placeholder (`[EMAIL]`, `[PERSON_2]` with
2226    /// [`Replacement::Pseudonym`](docling_core::Replacement::Pseudonym), or
2227    /// a fixed string), in the flat nodes, the item tree behind the JSON,
2228    /// the link table, captions, hrefs, code, comments, table cells. Images
2229    /// are dropped by default
2230    /// ([`ImageRedaction`](docling_core::ImageRedaction)); `BoxOut` paints
2231    /// over the OCR'd lines that carry a span, `Keep` leaves them. The
2232    /// result's `redaction` is the [`RedactionReport`](docling_core::RedactionReport)
2233    /// — counts per label, never the values unless `return_mapping` asks.
2234    /// Off by default; unused, the output is byte-identical. A docling.rs
2235    /// extension — Python docling has no redaction stage — and not a
2236    /// compliance guarantee: pattern and model recall are what they are.
2237    pub fn redact_pii(mut self, opts: docling_core::RedactionOptions) -> Self {
2238        self.redact = Some(opts);
2239        self
2240    }
2241
2242    /// Option-typed variant of [`redact_pii`](Self::redact_pii): `None`
2243    /// turns the pass off.
2244    pub fn redact_pii_opt(mut self, opts: Option<docling_core::RedactionOptions>) -> Self {
2245        self.redact = opts;
2246        self
2247    }
2248
2249    /// Run the PII pass (#621) this converter is configured with over a
2250    /// document built elsewhere — docling-serve's warm pipeline and the
2251    /// VLM pipeline bypass [`convert`](Self::convert) — and return its
2252    /// report; `Ok(None)` when [`redact_pii`](Self::redact_pii) is unset.
2253    pub fn redact(
2254        &self,
2255        document: &mut docling_core::DoclingDocument,
2256    ) -> Result<Option<docling_core::RedactionReport>, ConversionError> {
2257        match self.redact.as_ref() {
2258            Some(opts) => self.redact_document(document, opts).map(Some),
2259            None => Ok(None),
2260        }
2261    }
2262
2263    /// The PII pass over a converted document (#621): the detectors from
2264    /// the options, the OCR pipeline for `BoxOut` when this converter may
2265    /// run OCR (a `no_ocr` / `text_layer_only` converter drops the images
2266    /// instead, with the warning), then the walk. An invalid custom regex
2267    /// is a `Parse` error — the conversion cannot honour the request.
2268    fn redact_document(
2269        &self,
2270        document: &mut docling_core::DoclingDocument,
2271        opts: &docling_core::RedactionOptions,
2272    ) -> Result<docling_core::RedactionReport, ConversionError> {
2273        let detector = crate::redact::detector(opts)?;
2274        #[cfg(feature = "pdf")]
2275        {
2276            let mut ocr = None;
2277            if opts.images == docling_core::ImageRedaction::BoxOut
2278                && !self.no_ocr
2279                && !self.text_layer_only
2280            {
2281                // The OCR models only — no layout, no TableFormer.
2282                match docling_pdf::Pipeline::new() {
2283                    Ok(p) => {
2284                        ocr = Some(
2285                            self.with_textline_orientation(
2286                                p.no_ocr(true)
2287                                    .no_table_former(true)
2288                                    .ocr_lang(self.ocr_lang_choice())
2289                                    .ocr_engine(self.ocr_engine_choice())
2290                                    .tesseract_lang(self.tesseract_lang_choice())
2291                                    .ocr_scale(self.ocr_scale_choice()),
2292                            ),
2293                        )
2294                    }
2295                    Err(e) => crate::redact::warn_box_out_unavailable(&e.to_string()),
2296                }
2297            }
2298            Ok(crate::redact::run(document, opts, &detector, ocr.as_mut()))
2299        }
2300        #[cfg(not(feature = "pdf"))]
2301        {
2302            Ok(crate::redact::run(document, opts, &detector))
2303        }
2304    }
2305
2306    /// Rewrite detected code blocks with the CodeFormulaV2 VLM (docling's
2307    /// `do_code_enrichment`). Off by default.
2308    ///
2309    /// The model re-reads the code crop at ~120 dpi, emits the clean source
2310    /// text (line breaks included) and identifies the language, which lands in
2311    /// the JSON `code_language` field. Needs the `.models/code_formula/` graphs
2312    /// (fetched by `scripts/install/download_dependencies.sh`); a missing
2313    /// model warns once and leaves the block as extracted.
2314    pub fn do_code_enrichment(mut self, enable: bool) -> Self {
2315        self.enrich.code = enable;
2316        self
2317    }
2318
2319    /// Decode display formulas to LaTeX with the CodeFormulaV2 VLM (docling's
2320    /// `do_formula_enrichment`). Off by default.
2321    ///
2322    /// An enriched formula renders as `$$latex$$` in Markdown and as a
2323    /// `formula` text item in the JSON, replacing the
2324    /// `<!-- formula-not-decoded -->` placeholder. Same model artifacts as
2325    /// [`do_code_enrichment`](Self::do_code_enrichment).
2326    pub fn do_formula_enrichment(mut self, enable: bool) -> Self {
2327        self.enrich.formula = enable;
2328        self
2329    }
2330
2331    /// Pre-render HTML-routing input in a headless browser before parsing.
2332    ///
2333    /// Off by default. When enabled, HTML sources — and MHTML/EPUB, which
2334    /// assemble HTML from their archives — are loaded in the system Chromium
2335    /// (driven from Rust over the DevTools protocol — no Node/Playwright) so the
2336    /// CSS cascade is resolved: elements the browser computes as `display:none`
2337    /// (e.g. a stylesheet-collapsed nav menu) are removed before the normal HTML
2338    /// backend runs. This is the one behaviour a pure-Rust parse can't reproduce;
2339    /// everything else (structure, tables, KVP, formatting) is still handled in
2340    /// Rust on the cleaned HTML.
2341    ///
2342    /// Requires the crate's `web-browser` Cargo feature; without it, converting
2343    /// an HTML source with this enabled returns [`ConversionError::Browser`].
2344    pub fn use_web_browser(mut self, enable: bool) -> Self {
2345        self.use_web_browser = enable;
2346        self
2347    }
2348
2349    /// Return `html` unchanged, or — when [`use_web_browser`](Self::use_web_browser)
2350    /// is on — its headless-browser-cleaned form (computed-hidden elements
2351    /// removed). Borrows in the common (disabled) case; only allocates when the
2352    /// browser actually runs.
2353    fn maybe_prerender<'a>(
2354        &self,
2355        html: &'a str,
2356    ) -> Result<std::borrow::Cow<'a, str>, ConversionError> {
2357        crate::backend::maybe_prerender_html(html, self.use_web_browser)
2358    }
2359
2360    /// Convert a source document to Markdown **incrementally**, returning an
2361    /// iterator of Markdown chunks (with picture placeholders).
2362    ///
2363    /// Concatenating every `Ok` chunk reproduces
2364    /// [`convert`](Self::convert)`(...).document.export_to_markdown()`
2365    /// byte-for-byte. The win is for PDF, whose pages are processed in parallel:
2366    /// each page's Markdown is emitted in document order as soon as it is ready, so
2367    /// output starts before the whole document is converted. Other formats build
2368    /// their document up front and stream it through the same interface.
2369    ///
2370    /// Streaming is Markdown-only — JSON needs the whole node tree, so there is no
2371    /// streaming JSON. The conversion runs on a background thread; dropping the
2372    /// returned [`MarkdownStream`] cancels it.
2373    #[cfg(feature = "pdf")]
2374    pub fn convert_streaming(
2375        &self,
2376        source: SourceDocument,
2377    ) -> Result<MarkdownStream, ConversionError> {
2378        self.convert_streaming_images(source, ImageMode::Placeholder)
2379    }
2380
2381    /// Like [`convert_streaming`](Self::convert_streaming) but with an explicit
2382    /// picture [`ImageMode`].
2383    ///
2384    /// [`ImageMode::Referenced`] streams too (issue #80): each page's images
2385    /// are written to [`artifacts_dir`](Self::artifacts_dir) *as the page's
2386    /// Markdown is emitted* and dropped from memory, so an image-heavy PDF
2387    /// holds ~one page of images at a time instead of all of them until
2388    /// export. The chunks and files match the buffered
2389    /// `export_to_markdown_with_images(ImageMode::Referenced, ..)` output.
2390    #[cfg(feature = "pdf")]
2391    pub fn convert_streaming_images(
2392        &self,
2393        source: SourceDocument,
2394        image_mode: ImageMode,
2395    ) -> Result<MarkdownStream, ConversionError> {
2396        self.convert_streaming_with_options(
2397            source,
2398            &MarkdownExportOptions {
2399                image_mode,
2400                artifacts_dir: self.artifacts_dir.clone(),
2401                ..MarkdownExportOptions::default()
2402            },
2403        )
2404    }
2405
2406    /// Like [`convert_streaming_images`](Self::convert_streaming_images) but
2407    /// with every [`MarkdownExportOptions`] setting (#599): content layers,
2408    /// picture traversal, escaping, the image placeholder. Referenced images
2409    /// go under `options.artifacts_dir` (not the converter's
2410    /// [`artifacts_dir`](Self::artifacts_dir)). The concatenated chunks match
2411    /// the buffered `export_to_markdown_with_options(options)` byte-for-byte.
2412    #[cfg(feature = "pdf")]
2413    pub fn convert_streaming_with_options(
2414        &self,
2415        source: SourceDocument,
2416        options: &MarkdownExportOptions,
2417    ) -> Result<MarkdownStream, ConversionError> {
2418        if let Some(allowed) = &self.allowed_formats {
2419            if !allowed.contains(&source.format) {
2420                return Err(ConversionError::UnsupportedFormat(source.format));
2421            }
2422        }
2423        let source = self.with_encoding(source);
2424        Ok(crate::stream::spawn(self.clone(), source, options.clone()))
2425    }
2426
2427    /// Whether the heading-hierarchy stage (#302) is enabled — the streaming
2428    /// front-end buffers PDF conversions when it is (the stage needs the whole
2429    /// assembled document, and streamed output must stay byte-identical to
2430    /// buffered output).
2431    #[cfg(feature = "pdf")]
2432    pub(crate) fn heading_hierarchy_enabled(&self) -> bool {
2433        self.heading_hierarchy
2434    }
2435
2436    /// Streaming internals ([`crate::stream`]) read the producer's settings
2437    /// off the converter clone they receive.
2438    #[cfg(feature = "pdf")]
2439    pub(crate) fn stream_settings(&self) -> crate::stream::StreamSettings {
2440        crate::stream::StreamSettings {
2441            strict: self.strict,
2442            no_table_former: self.no_table_former,
2443            no_text_panels: self.no_text_panels,
2444            text_layer_only: self.text_layer_only,
2445            no_ocr: self.no_ocr,
2446            password: self.password.clone(),
2447            force_full_page_ocr: self.force_full_page_ocr,
2448            enrich: self.enrich,
2449            page_range: self.page_range,
2450            ocr_lang: self.ocr_lang_choice(),
2451            ocr_engine: self.ocr_engine_choice(),
2452            tesseract_lang: self.tesseract_lang_choice(),
2453            ocr_mode: self.ocr_mode_choice(),
2454            ocr_scale: self.ocr_scale_choice(),
2455            ocr_textline_orientation: self.ocr_textline_orientation,
2456            images_scale: self.images_scale,
2457            page_break_placeholder: self.page_break_placeholder.clone(),
2458            compact_tables: self.compact_tables,
2459            picture_alt_text: self.picture_alt_text,
2460            metadata_output: self.metadata_output,
2461            document_timeout: self.document_timeout,
2462            redact: self.redact.clone(),
2463        }
2464    }
2465
2466    /// Convert a single source document.
2467    ///
2468    /// The source converts as its declared format (the extension's). Only if
2469    /// that fails is the content inspected: when it is evidently another
2470    /// format — RTF, an OOXML / ODF / EPUB package, an OLE Word / Excel /
2471    /// PowerPoint / Outlook file, PDF or HTML saved under the wrong extension
2472    /// (#556) — the conversion is retried once as that format, and the result
2473    /// reports the format it was converted as. A document that converts as
2474    /// declared is never inspected; when the retry fails too, or nothing is
2475    /// recognised, the first attempt's error stands.
2476    pub fn convert(&self, source: SourceDocument) -> Result<ConversionResult, ConversionError> {
2477        if let Some(allowed) = &self.allowed_formats {
2478            if !allowed.contains(&source.format) {
2479                return Err(ConversionError::UnsupportedFormat(source.format));
2480            }
2481        }
2482        let source = self.with_encoding(source);
2483        // A source a registered backend claims (#680) is that backend's:
2484        // its failure is not retried as the content's built-in format.
2485        if self.claims(&source) {
2486            return self.convert_as(&source);
2487        }
2488        let err = match self.convert_as(&source) {
2489            Ok(result) => return Ok(result),
2490            Err(err) => err,
2491        };
2492        let Some(format) = crate::sniff::detect(&source.bytes).filter(|f| {
2493            *f != source.format
2494                && self
2495                    .allowed_formats
2496                    .as_ref()
2497                    .is_none_or(|allowed| allowed.contains(f))
2498        }) else {
2499            return Err(err);
2500        };
2501        let declared = source.format;
2502        let retry = SourceDocument { format, ..source };
2503        // The retry's error replaces the first one only when it says the
2504        // file is encrypted (#624) — an encrypted `.ppt` named `.pptx` is
2505        // better reported as encrypted than as a bad ZIP.
2506        let result = self.convert_as(&retry).map_err(|e| {
2507            if crate::backend::offcrypto::is_encryption_error(&e) {
2508                e
2509            } else {
2510                err
2511            }
2512        })?;
2513        // Converted, but not as the name said: worth a line, since the
2514        // mislabelled file is otherwise invisible.
2515        eprintln!(
2516            "docling: warning: {}: not a valid {} file; converted as {} (its content)",
2517            retry.name,
2518            declared.as_str(),
2519            format.as_str()
2520        );
2521        Ok(result)
2522    }
2523
2524    /// Convert `source` as its declared format, no retry.
2525    /// Whether `source` is a YouTube watch page fetched from its URL (#681)
2526    /// — HTML whose base URL names a video. Always false without the
2527    /// `youtube` feature, so such a page converts as the HTML it is.
2528    fn is_youtube_page(source: &SourceDocument) -> bool {
2529        #[cfg(feature = "youtube")]
2530        {
2531            source.format == InputFormat::Html
2532                && source
2533                    .base_url
2534                    .as_deref()
2535                    .is_some_and(|url| crate::backend::youtube::video_id(url).is_some())
2536        }
2537        #[cfg(not(feature = "youtube"))]
2538        {
2539            let _ = source;
2540            false
2541        }
2542    }
2543
2544    /// A YouTube watch page's conversion (#681): the title, metadata and
2545    /// caption transcript, the language from `asr_lang`.
2546    #[cfg(feature = "youtube")]
2547    fn youtube_page(
2548        &self,
2549        source: &SourceDocument,
2550    ) -> Result<docling_core::DoclingDocument, ConversionError> {
2551        crate::backend::youtube::YoutubeBackend {
2552            lang: self.asr_lang.clone(),
2553            // The caption fetch follows the one hop YouTube's `timedtext`
2554            // may bounce through; the SSRF guard sees each.
2555            fetch: crate::fetch::FetchPolicy {
2556                max_redirects: 2,
2557                ..crate::fetch::FetchPolicy::default()
2558            },
2559        }
2560        .convert(source)
2561    }
2562
2563    #[cfg(not(feature = "youtube"))]
2564    fn youtube_page(
2565        &self,
2566        _source: &SourceDocument,
2567    ) -> Result<docling_core::DoclingDocument, ConversionError> {
2568        unreachable!("is_youtube_page is false without the youtube feature")
2569    }
2570
2571    fn convert_as(&self, source: &SourceDocument) -> Result<ConversionResult, ConversionError> {
2572        // Problems a conversion survives (docling's `ConversionResult.errors`):
2573        // today the PDF pipeline's spent document budget (#497).
2574        #[cfg_attr(not(feature = "pdf"), allow(unused_mut))]
2575        let mut errors: Vec<crate::ErrorItem> = Vec::new();
2576        // An encrypted Office document (#624/#625) is decrypted with the
2577        // converter's password (or the format's default password) into the
2578        // file the backend reads; without a key that opens it, the error
2579        // says the document is encrypted — not "bad zip" or an empty result.
2580        let unlocked;
2581        let source = match crate::backend::offcrypto::unlock(source, self.password.as_deref())? {
2582            Some(bytes) => {
2583                unlocked = SourceDocument {
2584                    bytes,
2585                    ..source.clone()
2586                };
2587                &unlocked
2588            }
2589            None => source,
2590        };
2591        let registered = self.backend_for(source);
2592        let mut document = if let Some(registered) = registered {
2593            // A registered backend (#680) ahead of every built-in format.
2594            registered.backend().convert(source)?
2595        } else {
2596            match source.format {
2597                // A legacy APS (Automated Patent System) plain-text patent (`PATN`
2598                // first record) is reconstructed verbatim, mirroring docling.
2599                InputFormat::Md if crate::backend::uspto::looks_like_aps(&source.text()?) => {
2600                    crate::backend::uspto::convert_aps(source)?
2601                }
2602                // A text/Markdown-typed file that is actually an XML document (e.g. a
2603                // JATS article saved with a `.txt` extension) routes to the XML
2604                // backends by content, mirroring docling's content-based detection.
2605                InputFormat::Md if looks_like_xml(&source.text()?) => {
2606                    match sniff_xml(&source.bytes) {
2607                        InputFormat::XmlUspto => UsptoBackend.convert(source)?,
2608                        InputFormat::XmlXbrl => crate::backend::xbrl::convert_xbrl(
2609                            source,
2610                            self.xbrl_taxonomy.as_deref(),
2611                        )?,
2612                        // docling's format detection reads an XML-looking `.txt` as
2613                        // `application/xml` and, when its DOCTYPE names a JATS DTD
2614                        // (`JATS-journalpublishing…` / `JATS-archive…`), converts it
2615                        // with the JATS backend like a real `.nxml`; any other XML
2616                        // saved as `.txt` is reconstructed generically
2617                        // (element-by-element).
2618                        _ if has_jats_doctype(&source.text()?) => JatsBackend {
2619                            images: self.image_policy(),
2620                        }
2621                        .convert(source)?,
2622                        _ => crate::backend::jats::convert_generic(source)?,
2623                    }
2624                }
2625                // DeepSeek-OCR annotated Markdown (VLM token format) is detected by
2626                // its `<|ref|>…[[bbox]]` annotations and parsed separately.
2627                InputFormat::Md if is_deepseek_markdown(&source.text()?) => {
2628                    DeepSeekBackend.convert(source)?
2629                }
2630                InputFormat::Md => MarkdownBackend {
2631                    strict: self.strict,
2632                    images: self.image_policy(),
2633                }
2634                .convert(source)?,
2635                InputFormat::Csv => CsvBackend.convert(source)?,
2636                // A YouTube watch page (#681): routed by the URL it was fetched
2637                // from, as MarkItDown's `accepts` does — its title, metadata and
2638                // caption transcript, not the page's markup.
2639                InputFormat::Html if Self::is_youtube_page(source) => self.youtube_page(source)?,
2640                InputFormat::Html => {
2641                    // Optionally resolve the CSS cascade in a headless browser first
2642                    // (strips computed-hidden elements); everything else stays in the
2643                    // Rust HTML backend, which runs on the cleaned HTML.
2644                    // Bytes → text through docling's BeautifulSoup decoding order
2645                    // (#371): BOM, declared charset, UTF-8, windows-1252 — so a
2646                    // legacy windows-1252 page converts instead of failing the
2647                    // UTF-8 check every other text backend applies.
2648                    let decoded = crate::backend::decode_html_bytes(&source.bytes);
2649                    let html = self.maybe_prerender(&decoded)?;
2650                    let policy = self.image_policy();
2651                    if policy.sources != crate::ImageSources::None {
2652                        let resolver = crate::backend::FsImageResolver::new(
2653                            source.base_dir().map(|p| p.to_path_buf()),
2654                            source.base_url.clone(),
2655                            policy,
2656                        );
2657                        crate::backend::convert_html(&source.name, &html, &resolver)
2658                    } else {
2659                        crate::backend::convert_html(&source.name, &html, &crate::backend::NoFetch)
2660                    }
2661                }
2662                InputFormat::Asciidoc => AsciiDocBackend {
2663                    images: self.image_policy(),
2664                }
2665                .convert(source)?,
2666                InputFormat::Xlsx => XlsxBackend {
2667                    skip_empty: self.skip_empty_cells,
2668                }
2669                .convert(source)?,
2670                InputFormat::Pptx => PptxBackend.convert(source)?,
2671                // RTF (#209): a docling.rs extension — docling reaches RTF only via
2672                // LibreOffice; here it parses natively (hand-rolled tokenizer).
2673                InputFormat::Rtf => RtfBackend.convert(source)?,
2674                InputFormat::Visio => VisioBackend.convert(source)?,
2675                // AbiWord (#216): docling.rs extension, native AWML parse.
2676                InputFormat::Abiword => AbwBackend.convert(source)?,
2677                // WordPerfect 5.x/6.x+ (#216): docling.rs extension, native parse
2678                // of the ÿWPC function-code stream.
2679                InputFormat::WordPerfect => WpdBackend.convert(source)?,
2680                // Microsoft Works word processor (#216): docling.rs extension,
2681                // native parse after libwps.
2682                InputFormat::Works => WpsBackend.convert(source)?,
2683                // StarOffice 5 binaries (#215): docling.rs extension, native CFB
2684                // parse (docling would go through LibreOffice).
2685                InputFormat::StarOffice5 => StarOffice5Backend.convert(source)?,
2686                // DjVu (#434): docling.rs extension, pure-Rust decode (`djvu-rs`).
2687                // The hidden text layer is the default; a scan-only DjVu falls back
2688                // to rasterize + OCR when the ML pipeline is built.
2689                InputFormat::Djvu => self.convert_djvu(source)?,
2690                // DIF/SYLK/dBase (#216): docling.rs extensions, one content-sniffing
2691                // backend for the three table relics.
2692                InputFormat::Dbf | InputFormat::Dif | InputFormat::Sylk => {
2693                    InterchangeBackend.convert(source)?
2694                }
2695                // Lotus/Quattro/Works record streams (#216): one BOF-sniffing
2696                // backend for the whole DOS-era family.
2697                InputFormat::Lotus => LotusBackend.convert(source)?,
2698                // Quattro Pro (#216): docling.rs extension, native parse after
2699                // libwps (DOS/Windows record streams, QPW OLE zones).
2700                InputFormat::QuattroPro => QuattroBackend.convert(source)?,
2701                InputFormat::Docx => DocxBackend.convert(source)?,
2702                // Legacy binary Office (issue #127): parsed natively — docling
2703                // proper converts these through LibreOffice first (PR #3804).
2704                InputFormat::Xls => XlsBackend {
2705                    skip_empty: self.skip_empty_cells,
2706                }
2707                .convert(source)?,
2708                InputFormat::Ppt => PptBackend.convert(source)?,
2709                InputFormat::Doc => DocBackend.convert(source)?,
2710                InputFormat::Vtt => WebVttBackend.convert(source)?,
2711                InputFormat::Ebcdic => EbcdicBackend {
2712                    layout: self.ebcdic_layout.clone(),
2713                }
2714                .convert(source)?,
2715                InputFormat::Email => EmailBackend {
2716                    list_attachments: self.list_attachments,
2717                    images: self.image_policy(),
2718                }
2719                .convert(source)?,
2720                InputFormat::Mhtml => MhtmlBackend {
2721                    images: self.image_policy(),
2722                    use_web_browser: self.use_web_browser,
2723                }
2724                .convert(source)?,
2725                InputFormat::Epub => EpubBackend {
2726                    images: self.image_policy(),
2727                    use_web_browser: self.use_web_browser,
2728                }
2729                .convert(source)?,
2730                // A `.json` that is a Jupyter notebook (#673) — `"nbformat"` and
2731                // `"cells"` — reads as one, like MarkItDown's `application/json`
2732                // sniff; any other JSON is the docling-JSON backend's.
2733                InputFormat::JsonDocling => {
2734                    if crate::backend::ipynb::looks_like_notebook(&source.text()?) {
2735                        self.ipynb_backend().convert(source)?
2736                    } else {
2737                        DoclingJsonBackend.convert(source)?
2738                    }
2739                }
2740                InputFormat::Jsonl => crate::backend::text::convert_json_text(source)?,
2741                InputFormat::Text => crate::backend::TextBackend.convert(source)?,
2742                InputFormat::Ipynb => self.ipynb_backend().convert(source)?,
2743                // RSS / Atom / RDF feeds (#678): the title, each item's heading,
2744                // date and body (its HTML through the HTML backend).
2745                InputFormat::Feed => crate::backend::FeedBackend {
2746                    images: self.image_policy(),
2747                }
2748                .convert(source)?,
2749                // A bare `.xml` (#671): the dialects docling reads by content —
2750                // JATS by its DOCTYPE or `<article>` root — else one xml code
2751                // block with a warning, never an empty document.
2752                InputFormat::Xml => match sniff_xml(&source.bytes) {
2753                    InputFormat::XmlUspto => UsptoBackend.convert(source)?,
2754                    InputFormat::Feed => crate::backend::FeedBackend {
2755                        images: self.image_policy(),
2756                    }
2757                    .convert(source)?,
2758                    InputFormat::XmlXbrl => {
2759                        crate::backend::xbrl::convert_xbrl(source, self.xbrl_taxonomy.as_deref())?
2760                    }
2761                    InputFormat::XmlDoclang => crate::backend::DoclangBackend.convert(source)?,
2762                    _ if looks_like_jats(&source.bytes) => JatsBackend {
2763                        images: self.image_policy(),
2764                    }
2765                    .convert(source)?,
2766                    _ => crate::backend::text::convert_xml_text(source)?,
2767                },
2768                InputFormat::Latex => LatexBackend.convert(source)?,
2769                // A bare `.xml` defaults to XmlJats; sniff the content to route to the
2770                // right XML backend (docling distinguishes by DOCTYPE / root element).
2771                InputFormat::XmlJats | InputFormat::XmlUspto | InputFormat::XmlXbrl => {
2772                    match sniff_xml(&source.bytes) {
2773                        InputFormat::XmlUspto => UsptoBackend.convert(source)?,
2774                        InputFormat::XmlXbrl => crate::backend::xbrl::convert_xbrl(
2775                            source,
2776                            self.xbrl_taxonomy.as_deref(),
2777                        )?,
2778                        _ => JatsBackend {
2779                            images: self.image_policy(),
2780                        }
2781                        .convert(source)?,
2782                    }
2783                }
2784                InputFormat::Odt | InputFormat::Ods | InputFormat::Odp => {
2785                    crate::backend::convert_odf(source, &self.image_policy())?
2786                }
2787                // DocLang back in: bare XML (`.dclg`/`.dclg.xml`) or the OPC
2788                // archive `--to dclx` writes.
2789                InputFormat::XmlDoclang | InputFormat::Dclx => {
2790                    crate::backend::DoclangBackend.convert(source)?
2791                }
2792                // Raw DocTags (VLM token markup, #152): the tolerant docling-core
2793                // parser — never fails, best-effort document out.
2794                InputFormat::DocTags => {
2795                    let mut doc = docling_core::doctags::parse(&source.text()?);
2796                    doc.name = source.name.clone();
2797                    doc
2798                }
2799                #[cfg(feature = "pdf")]
2800                InputFormat::Pdf => {
2801                    let converted = self
2802                        .ml_pipeline()
2803                        .and_then(|mut p| {
2804                            p.set_force_full_page_ocr(self.force_full_page_ocr);
2805                            p.set_pages(self.page_range);
2806                            p.convert_outcome(&source.bytes, self.password.as_deref(), &source.name)
2807                        })
2808                        .map_err(|e| ConversionError::with_source("pdf", e))?;
2809                    if let Some(message) = converted.completion.message() {
2810                        errors.push(crate::ErrorItem::timeout(message));
2811                    }
2812                    converted.document
2813                }
2814                // SVG (#212), the ML route: rasterize (resvg, white-backed PNG at
2815                // ~2048px long side) and ride the image pipeline. `--no-ocr` /
2816                // `--text-layer-only` short-circuit to direct <text> extraction
2817                // instead — the SVG carries its text natively, so skipping OCR
2818                // must not mean losing it.
2819                #[cfg(feature = "pdf")]
2820                InputFormat::Svg if !self.text_layer_only && !self.no_ocr => {
2821                    let png = crate::backend::svg::rasterize_png(&source.bytes)?;
2822                    self.ml_pipeline()
2823                        .and_then(|mut p| p.convert_image(&png, &source.name))
2824                        .map_err(|e| ConversionError::with_source("svg", e))?
2825                }
2826                // SVG without the ML pipeline (pdf-text / wasm builds) or with
2827                // --no-ocr / --text-layer-only: pure-Rust <text> extraction, flat
2828                // paragraphs in reading order (the pdf / pdf-text split, applied
2829                // to SVG) — the SVG carries its text natively, so skipping OCR
2830                // must not mean losing it.
2831                InputFormat::Svg => crate::backend::SvgBackend.convert(source)?,
2832                // Apple iWork (#213): pure-Rust IWA text extraction, all builds.
2833                InputFormat::Pages | InputFormat::Numbers | InputFormat::Keynote => {
2834                    crate::backend::IworkBackend.convert(source)?
2835                }
2836                #[cfg(feature = "pdf")]
2837                InputFormat::Image => self
2838                    .ml_pipeline()
2839                    .and_then(|mut p| p.convert_image(&source.bytes, &source.name))
2840                    .map_err(|e| ConversionError::with_source("image", e))?,
2841                #[cfg(feature = "pdf")]
2842                InputFormat::MetsGbs => self
2843                    .ml_pipeline()
2844                    .and_then(|mut p| {
2845                        docling_pdf::convert_mets_gbs_with_pipeline(
2846                            &source.bytes,
2847                            &source.name,
2848                            &mut p,
2849                        )
2850                    })
2851                    .map_err(|e| ConversionError::with_source("mets-gbs", e))?,
2852                // Audio → Whisper ASR (symphonia decode + ONNX inference); each
2853                // transcribed segment becomes a `[time: start-end] text` paragraph.
2854                #[cfg(feature = "asr")]
2855                InputFormat::Audio => docling_asr::convert_audio_with_options(
2856                    &source.bytes,
2857                    &source.name,
2858                    self.asr_model.as_deref(),
2859                    self.asr_lang.as_deref(),
2860                )
2861                .map_err(|e| ConversionError::with_source(source.format.as_str(), e))?,
2862                // Video (#138): the audio track transcribes through the same ASR
2863                // path (Phase 1), and — when the ffmpeg binary is available —
2864                // sampled frames interleave with the transcript as timestamped
2865                // pictures (Phase 2). Without ffmpeg: transcript only.
2866                #[cfg(feature = "asr")]
2867                InputFormat::Video => self
2868                    .convert_video(source)
2869                    .map_err(|e| ConversionError::with_source(source.format.as_str(), e))?,
2870                // Without the full ML pipeline, `pdf-text` still converts a PDF's
2871                // embedded text layer (pure Rust — the wasm32 path), equivalent to
2872                // `--text-layer-only`: flat paragraphs, no headings/tables/pictures. A
2873                // scanned PDF has no text layer, so an empty document means "this
2874                // needs OCR" — say so instead of returning nothing.
2875                #[cfg(all(feature = "pdf-text", not(feature = "pdf")))]
2876                InputFormat::Pdf => {
2877                    let doc = docling_pdf::convert_text_layer_pages(
2878                        &source.bytes,
2879                        &source.name,
2880                        self.page_range,
2881                    )
2882                    .map_err(|e| ConversionError::with_source("pdf", e))?;
2883                    if doc.nodes.is_empty() {
2884                        return Err(ConversionError::Parse(
2885                            "PDF has no embedded text layer (scanned/image-only?); OCR needs a \
2886                         build with the `pdf` feature"
2887                                .into(),
2888                        ));
2889                    }
2890                    doc
2891                }
2892                // Compiled without the ML pipelines: the formats stay detectable,
2893                // but converting them needs a build with the matching feature.
2894                #[cfg(not(any(feature = "pdf", feature = "pdf-text")))]
2895                InputFormat::Pdf => {
2896                    return Err(ConversionError::Parse(
2897                        "Pdf conversion is not compiled in (rebuild with the `pdf` feature, or \
2898                     `pdf-text` for text-layer-only extraction)"
2899                            .into(),
2900                    ))
2901                }
2902                #[cfg(not(feature = "pdf"))]
2903                InputFormat::Image | InputFormat::MetsGbs => {
2904                    return Err(ConversionError::Parse(format!(
2905                        "{:?} conversion is not compiled in (rebuild with the `pdf` feature)",
2906                        source.format
2907                    )))
2908                }
2909                #[cfg(not(feature = "asr"))]
2910                InputFormat::Audio | InputFormat::Video => {
2911                    return Err(ConversionError::Parse(format!(
2912                        "{} conversion is not compiled in (rebuild with the `asr` feature)",
2913                        source.format.as_str()
2914                    )))
2915                }
2916                // Resolved for a registered backend (#680) that this converter
2917                // does not have.
2918                InputFormat::Plugin => {
2919                    return Err(ConversionError::UnknownFormat {
2920                        hint: format!(
2921                            "'{}' was loaded for a registered backend, but none registered on \
2922                         this converter claims it",
2923                            source.name
2924                        ),
2925                    })
2926                }
2927            }
2928        };
2929        self.enrich_pictures(&mut document, source);
2930        // The file's own metadata (#679), read when an export will show it
2931        // (a docling-JSON input keeps what it carried) — before the PII
2932        // pass, which covers it too.
2933        if self.metadata_output.in_json() && document.metadata.is_empty() {
2934            document.metadata = crate::metadata::read(source, self.password.as_deref());
2935        }
2936        // The PII pass (#621) runs on the finished model, before anything
2937        // reads it — after the backend, before the export-side settings.
2938        let redaction = self.redact(&mut document)?;
2939        self.finish_document(&mut document);
2940
2941        let status = if errors.is_empty() {
2942            ConversionStatus::Success
2943        } else {
2944            ConversionStatus::PartialSuccess
2945        };
2946        Ok(ConversionResult {
2947            document,
2948            status,
2949            input_name: source.name.clone(),
2950            format: source.format,
2951            redaction,
2952            errors,
2953        })
2954    }
2955}
2956
2957/// A picture an enrichment pass may still describe: one without a
2958/// description, or with only the alt text its file carried (#676) — the
2959/// model's or the reader's answer replaces that fallback.
2960fn undescribed(description: &Option<docling_core::PictureDescription>) -> bool {
2961    description.as_ref().is_none_or(|d| d.is_alt_text())
2962}
2963
2964#[cfg(test)]
2965mod tests {
2966    use super::*;
2967
2968    /// The warm slot records the switches it was built with and rebuilds
2969    /// on a change (#669).
2970    #[cfg(feature = "pdf")]
2971    #[test]
2972    fn warm_pipeline_tracks_its_switches() {
2973        let warm = WarmPipeline::new();
2974        let full = PipelineSwitches::of(&DocumentConverter::new());
2975        let text = PipelineSwitches::of(&DocumentConverter::new().text_layer_only(true));
2976        assert_ne!(full, text);
2977        let built = |w: &WarmPipeline| w.slot.lock().unwrap().as_ref().map(|(s, _)| *s);
2978        assert_eq!(built(&warm), None, "nothing loads before the first lease");
2979        drop(warm.lease(full).unwrap());
2980        assert_eq!(built(&warm), Some(full));
2981        drop(warm.lease(text).unwrap());
2982        assert_eq!(built(&warm), Some(text));
2983        // Converters share the handle.
2984        let converter = DocumentConverter::new().warm_pipeline(&warm);
2985        drop(converter.ml_pipeline().unwrap());
2986        assert_eq!(built(&warm), Some(full));
2987    }
2988
2989    /// A conversion that panics holding the warm pipeline poisons its lock;
2990    /// the next one gets a fresh pipeline, not the half-used one or a panic.
2991    #[cfg(feature = "pdf")]
2992    #[test]
2993    fn warm_pipeline_recovers_from_a_panic() {
2994        let warm = WarmPipeline::new();
2995        let full = PipelineSwitches::of(&DocumentConverter::new());
2996        drop(warm.lease(full).unwrap());
2997        let held = warm.clone();
2998        let _ = std::thread::spawn(move || {
2999            let _slot = held.lease(full).unwrap();
3000            panic!("a conversion panics mid-document");
3001        })
3002        .join();
3003        assert!(warm.slot.is_poisoned());
3004        let slot = warm.lease(full).expect("recovered");
3005        assert!(slot.is_some());
3006        drop(slot);
3007        assert!(!warm.slot.is_poisoned());
3008        assert!(format!("{warm:?}").contains("WarmPipeline"));
3009    }
3010
3011    /// A file whose extension lies converts as its content after the
3012    /// declared format fails (#556); junk keeps its original error, and a
3013    /// format the converter does not allow is not retried into.
3014    #[test]
3015    fn mislabelled_sources_retry_as_their_content() {
3016        let conv = DocumentConverter::new();
3017        let as_doc =
3018            |bytes: &[u8]| SourceDocument::from_bytes("x", InputFormat::Doc, bytes.to_vec());
3019
3020        let rtf = conv
3021            .convert(as_doc(b"{\\rtf1\\ansi Hello RTF\\par}"))
3022            .unwrap();
3023        assert_eq!(rtf.format, InputFormat::Rtf);
3024        assert_eq!(rtf.document.export_to_markdown().trim(), "Hello RTF");
3025
3026        let html = conv
3027            .convert(as_doc(
3028                b"<!DOCTYPE html><html><body><p>Hello HTML</p></body></html>",
3029            ))
3030            .unwrap();
3031        assert_eq!(html.format, InputFormat::Html);
3032        assert_eq!(html.document.export_to_markdown().trim(), "Hello HTML");
3033
3034        let docx = std::fs::read(
3035            std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
3036                .join("tests/data/docx/sources/docx_moveto_body.docx"),
3037        )
3038        .unwrap();
3039        let docx = conv.convert(as_doc(&docx)).unwrap();
3040        assert_eq!(docx.format, InputFormat::Docx);
3041        assert!(docx
3042            .document
3043            .export_to_markdown()
3044            .contains("avantMARK11apres"));
3045
3046        let err = conv.convert(as_doc(b"neither of them")).unwrap_err();
3047        assert!(err.to_string().contains("doc"), "{err}");
3048
3049        let only_doc = DocumentConverter::with_allowed_formats([InputFormat::Doc]);
3050        assert!(only_doc.convert(as_doc(b"{\\rtf1 Hello\\par}")).is_err());
3051    }
3052
3053    /// docling reads an XML-looking `.txt` as `application/xml` and converts
3054    /// it with the JATS backend when its DOCTYPE names a JATS DTD; other XML
3055    /// under `.txt` stays the generic element-by-element reconstruction.
3056    #[test]
3057    fn jats_doctype_text_file_uses_the_jats_backend() {
3058        let jats = "<!DOCTYPE article PUBLIC \"-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN\" \"JATS-archivearticle1.dtd\">\n<article><front><article-meta><title-group><article-title>T</article-title></title-group></article-meta></front><body><sec><title>S</title><p>Body.</p></sec></body></article>";
3059        let src = SourceDocument::from_bytes("a.txt", InputFormat::Md, jats.as_bytes().to_vec());
3060        let doc = DocumentConverter::new().convert(src).unwrap().document;
3061        assert!(doc.tree.is_some(), "JATS tree expected");
3062        assert_eq!(doc.export_to_markdown().trim(), "# T\n\n## S\n\nBody.");
3063        let other = "<?xml version=\"1.0\"?>\n<article><body><sec><title>S</title><p>Body.</p></sec></body></article>";
3064        let src = SourceDocument::from_bytes("b.txt", InputFormat::Md, other.as_bytes().to_vec());
3065        let doc = DocumentConverter::new().convert(src).unwrap().document;
3066        assert!(doc.tree.is_none(), "generic XML path expected");
3067    }
3068
3069    /// docling's `TextBackendOptions.encoding`: the converter's `encoding`
3070    /// decodes text inputs as named (a source's own setting wins), and an
3071    /// undecodable byte or unknown label is an error, not a guess.
3072    #[test]
3073    fn encoding_option_decodes_text_inputs() {
3074        let sjis = b"# \x93\xfa\x96\x7b\n".to_vec();
3075        let md = |c: &DocumentConverter, s: SourceDocument| {
3076            c.convert(s).map(|r| r.document.export_to_markdown())
3077        };
3078        let conv = DocumentConverter::new().encoding(Some("shift_jis".into()));
3079        let src = || SourceDocument::from_bytes("doc", InputFormat::Md, sjis.clone());
3080        assert_eq!(md(&conv, src()).unwrap().trim(), "# 日本");
3081        // Detection reads the same bytes as windows-1252.
3082        assert_ne!(
3083            md(&DocumentConverter::new(), src()).unwrap().trim(),
3084            "# 日本"
3085        );
3086        // The source's own encoding takes precedence over the converter's.
3087        let own = src().with_encoding(Some("shift_jis".into()));
3088        let latin = DocumentConverter::new().encoding(Some("latin1".into()));
3089        assert_eq!(md(&latin, own).unwrap().trim(), "# 日本");
3090        assert!(md(
3091            &DocumentConverter::new().encoding(Some("utf-8".into())),
3092            src()
3093        )
3094        .is_err());
3095        assert!(md(
3096            &DocumentConverter::new().encoding(Some("nope-1".into())),
3097            src()
3098        )
3099        .is_err());
3100    }
3101
3102    #[test]
3103    fn end_to_end_markdown() {
3104        let src =
3105            SourceDocument::from_bytes("doc", InputFormat::Md, b"# Hello\n\nWorld.\n".to_vec());
3106        let result = DocumentConverter::new().convert(src).unwrap();
3107        assert_eq!(result.status, ConversionStatus::Success);
3108        assert_eq!(result.document.export_to_markdown(), "# Hello\n\nWorld.\n");
3109    }
3110
3111    #[test]
3112    fn doctags_input_converts() {
3113        // Raw DocTags markup (#152) — the VLM token stream — as a first-class
3114        // input format (.doctags/.dt), through the tolerant docling-core
3115        // parser.
3116        let markup = b"<doctag><section_header_level_1><loc_1><loc_2><loc_3><loc_4>Intro</section_header_level_1><text>Body.</text></doctag>"
3117            .to_vec();
3118        let src = SourceDocument::from_bytes("page.doctags", InputFormat::DocTags, markup);
3119        let result = DocumentConverter::new().convert(src).unwrap();
3120        let md = result.document.export_to_markdown();
3121        assert!(md.contains("## Intro"), "{md}");
3122        assert!(md.contains("Body."), "{md}");
3123    }
3124
3125    #[test]
3126    fn doclang_xml_round_trips() {
3127        // Every input format now has a backend; DocLang XML reads back in and
3128        // re-exports as Markdown.
3129        let xml = b"<doclang version=\"0.7\">\n  <heading>Title</heading>\n  \
3130                    <text>Hello <bold>world</bold></text>\n</doclang>"
3131            .to_vec();
3132        let src = SourceDocument::from_bytes("doc.dclg", InputFormat::XmlDoclang, xml);
3133        let result = DocumentConverter::new().convert(src).unwrap();
3134        let md = result.document.export_to_markdown();
3135        assert!(md.contains("# Title"), "{md}");
3136        assert!(md.contains("**world**"), "{md}");
3137    }
3138
3139    #[test]
3140    fn sniffs_uspto_doctype_case_insensitively() {
3141        // docling PR #3801: Grant Full Text v2.5 files were missed when the
3142        // DOCTYPE casing differed.
3143        for head in [
3144            "<?xml version=\"1.0\"?><!DOCTYPE PATDOC SYSTEM \"ST32-US-Grant-025xml.dtd\"><PATDOC/>",
3145            "<?xml version=\"1.0\"?><!DOCTYPE patdoc SYSTEM \"st32-us-grant-025xml.dtd\"><patdoc/>",
3146            "<?xml version=\"1.0\"?><US-PATENT-GRANT-V4/>",
3147        ] {
3148            assert_eq!(
3149                super::sniff_xml(head.as_bytes()),
3150                InputFormat::XmlUspto,
3151                "head: {head}"
3152            );
3153        }
3154    }
3155}