# 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: