김경종
340 lines
15 KiB
Markdown
340 lines
15 KiB
Markdown
# 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:
|