Skip to content

ADR 0003 — Docling canonical artifacts and resource guard

  • Date: 2026-08-07 · Status: Accepted

Context

Docling is the default parser. Its output is not infallible. The old scaffold relied on a private result.input._backend.unload() call that is not a stable public contract.

Decision

  • Persist the DoclingDocument JSON as the canonical parsed artifact. Markdown, plain text, tables, thumbnails are derived artifacts. Never claim error-free extraction.
  • Implement DoclingResourceGuard in one adapter module:
  • prefer a public release / context-manager API when available;
  • otherwise guarded feature detection for a private unload;
  • log which cleanup path was used;
  • drop references and invoke gc only after artifacts are persisted;
  • expose a memory regression test;
  • support worker recycling (worker_recycle_documents).
  • Docling configuration is selected version-aware and validated at startup; unsupported settings fail with a precise message rather than being ignored.
  • When the docling extra is not installed, the parser path degrades to a documented safe adapter (e.g., plain-text/markdown fallback) so intake and the offline demo still function.

Consequence

Memory-safe parsing with a stable adapter boundary; heavy Docling is an opt-in extra that does not block the lean core.