Pipeline Stage Architecture#

Overview#

Docling's threaded PDF pipeline runs pages through five concurrent stages wired in sequence, followed by two sequential cross-page models and an enrichment pass. The architecture is implemented in StandardPdfPipeline, which extends ConvertPipeline → PaginatedPipeline → BasePipeline 1.

Every execute call constructs a fresh RunContext with new threads and bounded queues — models are initialized once at construction time and shared read-only across worker threads 2.

Stage Topology#

Pages flow as ThreadedItem envelopes — each carries a Page, run_id, page_no, ConversionResult, and error state. Stages are wired via ThreadedQueue instances (bounded, blocking, with close() propagating shutdown downstream). Stage wiring is in _create_run_ctx().

After all pages are drained, _assemble_document() runs sequentially: ReadingOrderModel → HeadingHierarchyModel → _enrich_document() 3.

The Assemble stage's postprocess hook (_release_page_resources()) frees page image caches and unloads the page backend unless enrichment stages need them. keep_backend is set to True whenever any enrichment flag (do_picture_classification, do_code_enrichment, etc.) is active 4.

Model Interface Contracts#

BasePageModel — page-level, streaming#

BasePageModel is the contract for all five threaded stage models. Its single abstract method:

__call__(conv_res: ConversionResult, page_batch: Iterable[Page]) → Iterable[Page]

The Page datamodel carries all per-page state between stages:

• parsed_page: SegmentedPdfPage | None — text cells from the PDF backend 5; accessed as page.cells (the textline_cells list)
• predictions: PagePredictions — output slots for layout, table structure, VLM response 6
• assembled: AssembledUnit | None — typed elements, filled by PageAssembleModel 7
• _backend / _image_cache — freed after Assemble unless keep_images/keep_backend is set 8

The non-threaded PaginatedPipeline._apply_on_pages() also chains build_pipe models using this same contract 9.

Ordering constraint: OCR runs before Layout. OCR text cells populate page.cells and are spatially assigned to layout clusters during postprocessing — this is why the two stages are separate and ordered.

GenericEnrichmentModel[T] / enrichment model hierarchy — document-level#

Enrichment models operate on a fully assembled DoclingDocument (not on Page objects). Three abstract methods are required 10:

Two concrete base classes specialize prepare_element:

• BaseEnrichmentModel — returns the element unchanged if is_processable. No image involved. Use for text-only enrichment.
• BaseItemAndImageEnrichmentModel — crops the element's bounding box from the source page image at self.images_scale (with optional expansion_factor). Returns an ItemAndImageEnrichmentElement (item, image) pair. For PictureItem with an embedded image (e.g. Word/HTML), the embedded image is used directly, so the page backend is not required.

The execution loop in BasePipeline._enrich_document() iterates each model in self.enrichment_pipe, uses prepare_element() to filter and prepare candidates, chunks them by model.elements_batch_size, and calls the model. The inner iterator must always be fully exhausted — side effects on NodeItems occur during iteration.

Pipeline Class Hierarchy and Extension Points#

BasePipeline
├── build_pipe: List[Callable] ← page-level models (BasePageModel)
├── enrichment_pipe: List[GenericEnrichmentModel] ← doc-level models
│
└── ConvertPipeline ← adds picture description / classifier / chart extraction
    └── PaginatedPipeline ← sequential page-batch loop (non-threaded base)
        └── StandardPdfPipeline ← threaded 5-stage topology
            └── prepends CodeFormulaVlmModel to enrichment_pipe

11 12

Extension point 1 — Swap a threaded stage model: StandardPdfPipeline._init_models() 13 sets self.layout_model, self.ocr_model, etc. Subclass and override to inject a custom model; it must still implement BasePageModel.__call__.

Extension point 2 — Add enrichment models: Subclass StandardPdfPipeline and reassign self.enrichment_pipe in __init__, then wire via PdfFormatOption(pipeline_cls=MyPipeline). For installed packages, register models via setuptools entry-point plugins under the "docling" group (only loaded when allow_external_plugins=True) 14.

Key Data Types#

Key Source Files#