ADR-0003: PyMuPDF as an optional AGPL PDF backend¶
- Status: Accepted
- Date: 2026-09-27
- Deciders: user, pc-1
- Related: ADR-0001 (dependency licence rule), ADR-0001 §4 (profiles)
Context¶
ADR-0001 2 allows only permissive licences (MIT/BSD/Apache-2.0/PSF/ISC) in
core; anything copyleft requires an explicit addendum before it enters any
dependency profile. The native PDF backend needs real text, layout, and
image extraction. pypdf is permissive but materially weaker as a parser;
PyMuPDF is a strong, fast extraction engine but is licensed AGPL-3.0.
Decision¶
- PyMuPDF is allowed only behind the optional
pdfextra (pdf = ["pymupdf>=1.24"]). It is never a core dependency. - Core stays MIT and import-clean: the
pdfextra is not installed bymise devor CI, and the backend loads PyMuPDF only at instantiation (module boundary +importlib). Amended (ADR-0009): pypdf is now a core dependency — the permissive path for cheap, always-available inspection — page count, encryption, text-density and other difficulty signals used bypdf-lite(pypdf, BSD-3-Clause) remainsanalyze()— so routing works without the AGPL extra.- Installing the
pdfextra is the user's own licence decision; AGPL-3.0 terms apply to that extra, not to the MIT-licensed core.
Amended (2026-10-14, pc-1): the AGPL extra is renamed pdf → pymupdf under the
package-named convention (matching docling/mineru/web-or-trafilatura).
Consumers of parsecraft[pdf] must switch to parsecraft[pymupdf]. A new
meta-extra pdf-full = [pymupdf, mineru] ships as the convenience bundle
(pymupdf is AGPL; mineru is Apache-2.0 weights + source-available code
per ADR-0007). The original pdf extra is removed in the same commit;
setup-pandoc was the unrelated previous rename.
Consequences¶
- The
pymupdfextra is copyleft and therefore never bundled into the default distribution or theallconvenience profile without the same explicit acknowledgement. pymupdfextraction requiresparsecraft[pymupdf];pymupdfanalysis works on the core install alone.- Any future copyleft dependency follows this same pattern: optional extra + addendum + no core/dev install.