PDFToMD/ARCHITECTURE.md

# Architecture: Local PDF-to-Markdown Converter

Last updated: 2026-05-13

## 1. Overview

The system converts math-heavy digital PDFs into Obsidian-friendly Markdown using MinerU 3.1.0 as the fixed local conversion engine. Product requirements live in `PRD.md`; agent workflow rules live in `AGENTS.md`; research notes live in `docs/KNOWLEDGEBASE.md`.

The architecture separates MinerU execution from project-owned normalization and internal provenance/reporting. This boundary exists only to isolate MinerU I/O; it is not a pluggable engine system.

## 2. System Layers

1. CLI/API layer
   - Parse command arguments and Python API parameters.
   - Discover input PDFs.
   - Plan output paths.
   - Enforce overwrite behavior.
   - Print conversion summaries.

Optional local UI launcher sits above this layer and invokes the project-owned `pdf2md` CLI. It can run a selected folder by discovering direct-child PDFs and sequentially invoking existing `pdf2md convert` commands. It must not call MinerU directly, add a second conversion engine, run parallel GPU conversions by default, or expose remote/API runtime paths.

2. MinerU adapter layer
   - Validate MinerU 3.1.0 installation and version.
   - Run MinerU through direct local CLI execution.
   - Capture raw Markdown, structured output, assets, logs, and exit status.
   - Enforce strict-local execution.

3. Intermediate representation layer
   - Convert MinerU-specific output into project-owned document/page/block objects.
   - Preserve page index, bbox, confidence, source engine, and asset references returned by MinerU.
   - Prevent raw MinerU objects from becoming public API return types.

4. Normalization layer
   - Convert project-owned objects and MinerU Markdown into Obsidian-friendly Markdown.
   - Normalize math delimiters, display math spacing, headings, tables, and asset links.

5. Quality and reporting layer
   - Run link checks and math renderability checks with local tooling.
   - Aggregate structured warnings.
   - Build internal metadata-like records for reports and result summaries.
   - Write quality report Markdown and optional raw MinerU diagnostics.

## 3. Conversion Pipeline

1. Input discovery
   - Accept a single PDF or a directory.
   - Require `--recursive` for subdirectory traversal.
   - Validate that each selected input is a local PDF.
   - Compute source SHA-256.

2. MinerU conversion
   - Create an isolated work directory per input PDF.
   - Run the MinerU 3.1.0 adapter through the direct `mineru` CLI.
   - Capture raw Markdown, raw JSON/structured output when available, extracted assets, warnings, and logs.
   - When `--chunk-pages` is active, write one-page temporary PDFs, run MinerU once per source page, and group successful page Markdown into final outputs of the configured page count.

3. Intermediate representation
   - Build document/page/block records from MinerU output.
   - Preserve provenance data instead of relying only on final Markdown text.

4. Obsidian normalization
   - Normalize inline math to `$...$`.
   - Normalize display math to `$$...$$` blocks on separate lines.
   - Normalize image links to stable relative asset paths.
   - Normalize tables without destroying complex table structure.

5. Quality checks
   - Verify generated asset links.
   - Check math renderability when local tooling is available.
   - Compare local pypdf text-layer extraction with Markdown text where page mapping is credible.
   - Emit warnings without stopping conversion unless no usable output can be produced.

6. Output writing
   - Write final Markdown parts under `<output>/<stem>/`.
   - Write extracted assets under `<output>/<stem>/images/`.
   - Write one report at `<output>/<stem>/<stem>_report.md`.
   - Keep raw MinerU output when requested.
   - In grouped page conversion mode, write one public Markdown part per grouped page range and delete temporary one-page PDFs plus intermediate per-page outputs.

## 4. MinerU Adapter Contract

The MinerU adapter exposes:

- `name`
- `is_available()`
- `version()`
- `doctor()`
- `convert(input_pdf, work_dir, options)`

Adapter conversion output contains:

- `raw_markdown`
- `raw_structured`
- `assets`
- `pages`
- `warnings`
- `engine`
- `engine_version`
- `engine_options`
- `exit_code`
- `stderr`

The adapter must fail fast if it cannot run in strict-local mode. Runtime engine selection is not part of v1.

The default conversion device is `cuda:0`. Because MinerU 3.1.0 selects its local device through environment/config rather than a dedicated CLI GPU flag, the adapter must set the MinerU subprocess environment to request CUDA by default while keeping the command shape direct and local.

Runtime tuning is project-owned and strict-local:

- `--gpu auto` selects the visible NVIDIA GPU with the largest VRAM from local `nvidia-smi` inventory.
- `--mineru-profile auto` is the default.
- Safe profile settings are used for GTX 1070 Ti 8GB, pre-Turing, low-VRAM GPUs, or unavailable inventory.
- Stronger settings are used only for 16GB+ Turing-or-newer GPUs.
- Tuning is applied only through allowlisted MinerU subprocess environment variables: `MINERU_PROCESSING_WINDOW_SIZE`, `MINERU_API_MAX_CONCURRENT_REQUESTS`, and `MINERU_PDF_RENDER_THREADS`.
- The adapter must not add MinerU backend flags, API URLs, router mode, HTTP client backend use, remote OpenAI-compatible endpoints, or `MINERU_HYBRID_BATCH_RATIO`.

Resolved profile details must be recorded in `engine_options["mineru_profile"]`, including requested profile, applied profile, environment values, and selected GPU details when known.

Allowed MinerU execution in v1:

- Direct local `mineru` CLI execution.
- The temporary local `mineru-api` process that MinerU 3.1.0 starts internally when the CLI runs without `--api-url`.

Prohibited MinerU execution in v1:

- Passing `--api-url`.
- Remote APIs.
- Router mode.
- HTTP client backends.
- Remote OpenAI-compatible backends or inference endpoints.

## 5. Intermediate Representation

The project uses a small internal representation for normalization and metadata.

Required concepts:

- Document
- Page
- Block
- Asset
- Warning

Required block types:

- `heading`
- `paragraph`
- `inline_formula`
- `display_formula`
- `table`
- `figure`
- `caption`
- `footnote`
- `reference`
- `unknown`

Record these page/block fields when MinerU returns them. Do not invent missing values.

- Page index.
- Page dimensions.
- Bounding boxes.
- Confidence.
- Source engine, fixed to MinerU 3.1.0 in v1.
- Markdown character span.

## 6. Markdown Normalization

Final Markdown must prioritize Obsidian.

- Use `$...$` for inline math.
- Use display math blocks with `$$` on their own lines.
- Keep blank lines around display math.
- Do not escape underscores or carets inside math unnecessarily.
- Prefer Markdown tables for simple tables.
- Use HTML tables for complex tables when Markdown would lose structure.
- Store figures/images in the stable `images/` directory under the PDF output folder.
- Do not add visible page separators in v1; grouped page conversion may add invisible HTML comments such as `<!-- source-page: 7 -->` for provenance.
- Preserve captions and references when MinerU provides them.

## 7. Internal Provenance Schema

New conversions do not write a public metadata JSON sidecar. The same schema shape remains useful internally for report generation, warning aggregation, and tests.

Required top-level fields:

- `source_pdf`
- `source_sha256`
- `created_at`
- `engine`
- `engine_version`
- `engine_options`
- `pages`
- `assets`
- `warnings`
- `summary`

Optional top-level fields:

- `text_fidelity`: page-level local pypdf-vs-Markdown text diagnostics when source text can be extracted or page mapping uncertainty needs to be recorded.

Required summary fields:

- `pages_processed`
- `warning_count`
- `asset_count`
- `display_formula_count`
- `inline_formula_count`
- `math_render_error_count`

Optional text fidelity summary fields:

- `text_fidelity_checked_page_count`
- `text_fidelity_low_page_count`
- `text_fidelity_unexpected_cjk_count`
- `text_fidelity_replacement_candidate_page_count`
- `text_fidelity_page_mapping_uncertain_count`

Grouped page conversion records these `engine_options` entries:

- `chunk`: original source PDF path, grouped output index, total grouped outputs, and original source page range.
- `page_conversion`: `single_page` mode, MinerU input page count of 1, grouped output page count, and failed source page numbers.
- `parts`: aggregate report records for output Markdown part paths, source page ranges, status, warning counts, and failed source pages.
- `output_folder`: the PDF-stem output folder.

Warning records include:

- `code`
- `severity`
- `page_index`
- `bbox`
- `message`

Stable warning code examples:

- `ENGINE_MISSING`
- `GPU_UNAVAILABLE`
- `LOW_CONFIDENCE_FORMULA`
- `MATH_RENDER_FAILED`
- `MATH_RENDER_REPAIRED`
- `ASSET_LINK_MISSING`
- `READING_ORDER_UNCERTAIN`
- `STRICT_LOCAL_VIOLATION`
- `MINERU_CLI_FAILED`
- `MINERU_PROFILE_ADJUSTED`
- `TEXT_LAYER_AVAILABLE`
- `TEXT_FIDELITY_LOW`
- `UNEXPECTED_CJK_IN_KOREAN_TEXT`
- `HANGUL_SPACING_SUSPECT`
- `TEXT_PAGE_MAPPING_UNCERTAIN`

## 8. Quality Report

Every conversion writes `<stem>/<stem>_report.md`.

The report is derived from internal provenance and local quality checks. It contains:

- Source and output paths.
- Markdown part paths and source page ranges.
- MinerU version and execution mode.
- Pages processed.
- Warning count.
- Asset count and missing asset link count.
- Inline and display formula counts.
- Math render error count.
- Text fidelity summary when pypdf diagnostics are available.
- Pages with warnings.
- Final status: `success`, `partial`, or `failed`.

## 9. Local-Only Enforcement

The implementation must not upload PDFs, page images, or extracted text to remote services.

Strict-local mode is on by default. The MinerU adapter must not call cloud OCR APIs, hosted document parsing APIs, hosted LLM/VLM APIs, or remote model inference endpoints.

Local-only execution means direct `mineru` CLI execution in v1. MinerU 3.1.0's CLI-internal temporary local `mineru-api` process is allowed because it is local orchestration owned by the CLI invocation. User-specified API URLs, router mode, HTTP client backends, remote APIs, and remote OpenAI-compatible backends are not allowed.

Allowed network activity is limited to documentation, package/model installation initiated by setup commands, or tests explicitly marked as network tests and disabled by default.

## 10. Failure Policy

Conversion should continue automatically when possible.

- Low-confidence formulas are included as best effort and recorded as warnings.
- Low-confidence pages are included as best effort and recorded as warnings.
- Run MinerU with its default local CLI behavior first.
- If MinerU cannot run or returns a failure, report the failure clearly and do not silently switch backend.
- Conversion fails only when the input cannot be opened, MinerU cannot run, no usable output can be produced, output cannot be written, or strict-local policy is violated.
- CLI summaries must report warning counts clearly.