PDFToMD/docs/Sprints/SPRINT8CONTRACT.md

Sprint 8 Contract: Doctor And Setup Documentation

Status: Implemented Last updated: 2026-05-08

Objective

Make local setup failures explicit before users run conversions by adding a mockable pdf2md doctor diagnostic path and setup documentation for Windows PowerShell, Python 3.12, uv, MinerU 3.1.0, local model/cache expectations, NVIDIA GPU/CUDA visibility, and strict-local runtime behavior.

Sprint 8 must establish:

• A project-owned doctor module for local environment diagnostics.
• A pdf2md doctor CLI command with deterministic exit codes.
• Clear reporting for Python, uv, MinerU CLI, MinerU version, GPU/CUDA/PyTorch visibility, and model/cache path detection.
• Documentation that explains setup steps and local-only runtime constraints without introducing cloud/API fallback paths.
• Fast tests that mock environment checks and do not require real MinerU, CUDA, GPU, model files, network, samples/, Obsidian, LaTeX tooling, or package/model downloads.

Sprint 8 is a diagnostics and setup-documentation sprint. It must not change conversion output behavior, run real conversions, probe local sample PDFs, or make runtime conversion depend on network access.

Current Precondition

Sprint 7 is complete:

• src/pdf2md/paths.py owns input discovery and output path planning.
• src/pdf2md/ir.py owns project records, block types, warning codes, and warning severities.
• src/pdf2md/metadata.py builds JSON-serializable metadata and summary counts from project-owned records.
• src/pdf2md/mineru_adapter.py owns the mocked direct local MinerU CLI adapter boundary.
• src/pdf2md/markdown.py owns Obsidian Markdown normalization.
• src/pdf2md/quality.py owns local quality checks, including math checker unavailable behavior.
• src/pdf2md/report.py owns report content rendering and final status calculation.
• src/pdf2md/conversion.py owns conversion orchestration and output writing.
• src/pdf2md/cli.py owns pdf2md convert.
• uv run pytest passed 119 tests.

Sprint 8 may add doctor diagnostics and setup documentation. It must not require a real successful local MinerU/GPU/model setup in the default test loop.

Touched Surfaces

Allowed:

• src/pdf2md/doctor.py
• src/pdf2md/cli.py
• src/pdf2md/mineru_adapter.py only for narrowly required availability/version helper compatibility
• README.md
• scripts/install-mineru.ps1 only if implemented as an explicit user-invoked setup helper
• scripts/install-models.py only if implemented as an explicit user-invoked setup helper
• tests/test_doctor.py
• tests/test_cli.py
• tests/test_mineru_adapter.py only if adapter helper compatibility changes
• PLAN.md
• PROGRESS.md
• docs/V1IMPLEMENTATIONPLAN.md
• docs/Sprints/SPRINT8CONTRACT.md

Not allowed:

• Changes to src/pdf2md/conversion.py unless a doctor/CLI regression forces a narrow compatibility fix
• Changes to Markdown normalization, metadata schema, report rendering, or path planning unrelated to doctor behavior
• Real PDF conversion in default tests
• Real MinerU execution in default tests
• Real CUDA/GPU dependency in default tests
• Model downloads in default tests
• Any setup download triggered by pdf2md doctor, pdf2md convert, import time, or tests
• Runtime engine selection or alternate engine support
• Cloud OCR, remote LLM/VLM, hosted renderer, remote document parser, remote asset fetching, HTTP client backend, router mode, --api-url, remote APIs, or remote OpenAI-compatible backend support
• A CLI/API option that disables strict-local policy
• Committed files under samples/
• Generated conversion outputs committed to git

Expected Outputs

Sprint 8 should produce:

1. Doctor result records and API

   • A small project-owned doctor result type containing at least:
     • check name
     • status: pass, warn, or fail
     • human-readable message
     • optional details
   • A doctor report type containing ordered checks and an overall status.
   • Mockable checker dependencies for subprocess calls, executable discovery, Python version, imports, environment variables, and filesystem paths.
   • No public or required field should expose raw subprocess or third-party objects.

2. Required checks

   • Python version check:
     • Pass on Python 3.12.
     • Fail outside the supported project range.
   • uv check:
     • Detect executable availability.
     • Report version text when available.
     • Fail clearly when missing.
   • MinerU check:
     • Detect direct local mineru CLI availability through the existing adapter boundary where possible.
     • Report MinerU version when available.
     • Fail clearly when the CLI is missing.
     • Warn or fail clearly when version detection fails or the detected version is not MinerU 3.1.0.
   • GPU/CUDA/PyTorch visibility:
     • Report whether an NVIDIA GPU is visible when detectable.
     • Report CUDA/PyTorch visibility without requiring PyTorch in default tests.
     • Warn clearly when GPU/CUDA/PyTorch acceleration is unavailable.
     • Warn clearly when the detected GPU is GTX 1070 Ti or another Pascal/pre-Turing class GPU with likely CUDA/PyTorch compatibility risk.
   • Model/cache paths:
     • Report detectable local model/cache paths from documented environment variables or known local config locations.
     • Warn when model/cache paths cannot be detected.
     • Do not download, install, or validate large model files in default tests.
   • Local-only policy:
     • Report that runtime conversion allows only direct local mineru CLI execution and CLI-internal temporary local mineru-api.
     • Report that --api-url, remote APIs, router mode, HTTP client backends, and remote OpenAI-compatible backends are prohibited.

3. CLI command

   • pdf2md doctor exists.
   • pdf2md --version remains unchanged.
   • pdf2md convert behavior remains covered and unchanged except for parser integration.
   • Exit code policy:
     • 0 when all checks pass or only warnings exist.
     • Non-zero when any required check fails.
   • CLI output must be concise, deterministic, and testable.
   • CLI output must distinguish warnings from failures.

4. Setup documentation

   • README or setup section explains:
     • Windows PowerShell workflow.
     • Python 3.12 requirement.
     • uv usage and PATH note for C:\Users\user\.local\bin.
     • MinerU 3.1.0 local CLI expectation.
     • Model/cache setup expectations and where doctor looks.
     • NVIDIA GPU expectations and GTX 1070 Ti 8GB risk.
     • Strict-local runtime policy.
     • Difference between explicit setup downloads and runtime conversion, which must stay local-only.
   • If setup helper scripts are added, they must be explicit user-invoked helpers, not imported by package code, not called by doctor, and not used by default tests.

5. Tests

   • Unit tests for doctor success with mocked checks.
   • Unit tests for missing Python version support.
   • Unit tests for missing uv.
   • Unit tests for missing MinerU.
   • Unit tests for MinerU version detection failure or non-3.1.0 version.
   • Unit tests for missing GPU/CUDA/PyTorch warning behavior.
   • Unit tests for GTX 1070 Ti/Pascal risk warning behavior.
   • Unit tests for missing model/cache warning behavior.
   • CLI tests for pdf2md doctor success, warning-only success, and hard failure exit code.
   • Regression tests proving pdf2md convert and --version still work.
   • Tests proving default checks do not require real MinerU, GPU, CUDA, PyTorch, model files, network, samples/, Obsidian, or LaTeX tooling.

6. Handoff

   • PROGRESS.md records changed files, commands run, tests passed or blocked, known failures, residual risks, and next action.

Non-Goals

• Do not run real MinerU in default tests.
• Do not install MinerU 3.1.0.
• Do not download MinerU models.
• Do not run real model setup during doctor or tests.
• Do not parse, convert, or inspect sample PDFs.
• Do not implement local fixture evaluation.
• Do not change conversion orchestration behavior except for unavoidable CLI parser integration.
• Do not add runtime engine selection.
• Do not add alternate engines.
• Do not add cloud, remote API, router, HTTP client backend, remote OpenAI-compatible backend, hosted renderer, or remote asset-fetching support.
• Do not add a CLI/API option that disables strict-local policy.
• Do not require real CUDA, GPU, PyTorch, MinerU, model files, network, Obsidian, LaTeX tooling, or samples/ in default tests.
• Do not claim that GTX 1070 Ti CUDA/PyTorch acceleration is guaranteed until local validation proves it.
• Do not claim perfect setup automation.

Work Packages

WP8.1: Doctor Records And Mockable Check Boundaries

Owner:

• local-setup-agent
• feature-generator-agent

Actions:

• Add doctor.py.
• Define doctor check/result records.
• Keep all external probes injectable or mockable.
• Implement deterministic aggregation and exit status policy.

Output:

• The CLI can report setup health without depending on real local tools in tests.

WP8.2: Environment And MinerU Diagnostics

Owner:

• local-setup-agent
• mineru-integration-agent
• feature-generator-agent

Actions:

• Add Python, uv, MinerU availability, MinerU version, GPU/CUDA/PyTorch, and model/cache checks.
• Reuse the direct local MinerU adapter boundary where it fits.
• Keep MinerU 3.1.0 as the only accepted engine target.

Output:

• Users get clear local setup failures before conversion.

WP8.3: CLI Doctor Command

Owner:

• feature-generator-agent
• requirements-guard-agent

Actions:

• Add pdf2md doctor without breaking pdf2md convert or --version.
• Print deterministic pass/warn/fail lines and an overall status.
• Return non-zero when required checks fail.

Output:

• The command-line workflow can diagnose setup state.

WP8.4: Setup Documentation And Optional Explicit Helpers

Owner:

• local-setup-agent
• license-privacy-agent
• requirements-guard-agent

Actions:

• Update README setup docs for Windows PowerShell, Python 3.12, uv, MinerU 3.1.0, model/cache, GPU, and local-only runtime policy.
• Verify volatile install/setup claims against official docs before editing.
• If adding scripts, keep them explicit, local setup-only, and never called by doctor, convert, import time, or default tests.

Output:

• Setup instructions are clear without weakening strict-local runtime policy.

WP8.5: Independent Evaluation

Owner:

• evaluation-agent

Actions:

• Review completed doctor behavior and docs against this contract.
• Verify no default test executes real MinerU, uses GPU/CUDA, downloads models, uses network, or requires samples/.
• Verify no runtime remote/API path or alternate engine is introduced.
• Verify samples/ remains untracked and unstaged.

Output:

• PASS/FAIL notes with any missing acceptance criteria.

Verification Checks

Required:

• git status --short --untracked-files=all before staging confirms samples/ remains untracked and unstaged.
• uv --version is run and result is recorded.
• uv sync passes.
• uv run pytest tests/test_doctor.py tests/test_cli.py passes.
• uv run pytest passes.
• git diff --check passes.
• Default tests do not require real MinerU, CUDA, GPU, PyTorch, model files, network, Obsidian, LaTeX tooling, or samples/.
• No model downloads occur.
• No setup downloads occur from doctor, convert, imports, or tests.
• No network calls are required in default tests.
• No candidate engine comparison is reintroduced.
• No alternate engine or runtime engine selection is added.
• No CLI/API option disables strict-local policy.
• No --api-url, router mode, HTTP client backend, remote API, or remote OpenAI-compatible backend support is added.
• Doctor fails clearly when required dependencies are missing.
• Doctor does not report the environment as healthy when MinerU is missing.
• Doctor warnings are clear for GPU/CUDA/PyTorch/model-cache risk.
• pdf2md convert tests still pass.
• pdf2md --version still works.

Recommended:

• Keep doctor checks small, ordered, and deterministic.
• Keep human-readable output stable enough for unit tests.
• Use dependency injection rather than monkeypatching global process state where possible.
• Treat real local GPU/MinerU/model probes as optional manual verification outside the default test suite.
• Use requirements-guard-agent if setup wording risks weakening strict-local policy.
• Use research-agent or local-setup-agent with live web verification before changing volatile installation commands or model-cache documentation.

Hard Failure Criteria

Sprint 8 fails and must stop for a user decision if any of these are true:

• Doctor reports a healthy environment when MinerU is missing.
• Doctor says cloud/API fallback is supported.
• Doctor, import time, or default tests install packages, download models, call network services, or run model setup.
• Default tests require real MinerU, CUDA, GPU, PyTorch, model files, network, Obsidian, LaTeX tooling, or samples/.
• The implementation adds or permits --api-url, remote APIs, router mode, HTTP client backends, or remote OpenAI-compatible backends.
• The implementation adds runtime engine selection or alternate engines.
• pdf2md doctor breaks pdf2md convert or pdf2md --version.
• The README or scripts imply runtime conversion can upload PDFs, page images, extracted text, or intermediates to remote services.
• Setup helper scripts are invoked automatically by doctor, convert, import time, or tests.
• samples/ is staged or committed.

Acceptance Criteria

Sprint 8 is complete when:

• src/pdf2md/doctor.py exists and owns local setup diagnostics.
• pdf2md doctor exists.
• Doctor returns a project-owned report with ordered checks and overall status.
• Python 3.12, uv, MinerU availability/version, GPU/CUDA/PyTorch visibility, and model/cache path checks are implemented with mocked tests.
• Missing uv is tested.
• Missing MinerU is tested and produces a failure.
• Missing GPU/CUDA/PyTorch is tested and produces clear warning behavior.
• GTX 1070 Ti/Pascal risk warning behavior is tested.
• Missing model/cache path warning behavior is tested.
• pdf2md doctor exit code behavior is tested for success, warning-only success, and failure.
• pdf2md convert and pdf2md --version regression tests still pass.
• Setup docs explain local-only runtime behavior and do not imply cloud/API fallback.
• Default tests do not require real MinerU, GPU, CUDA, PyTorch, model files, network, Obsidian, LaTeX tooling, or samples/.
• uv sync passes.
• Targeted doctor/CLI tests pass.
• uv run pytest passes.
• PROGRESS.md records checks performed and residual risks.
• Independent evaluation is complete.
• The completed change is committed.

Handoff Fields

Use these fields when Sprint 8 completes:

• Files changed:
• Commands run:
• Tests passed:
• Tests blocked:
• Known failures:
• Residual risks:
• User decisions needed:
• Go/no-go recommendation for Sprint 9:
• Next action: