김경종
91 lines
8.7 KiB
Markdown
91 lines
8.7 KiB
Markdown
# Work Archive
|
|
|
|
Last updated: 2026-05-08
|
|
|
|
This document stores completed project work, historical sprint outcomes, environment setup results, and sample conversion evidence. `PROGRESS.md` should stay focused on current status, blockers, and next actions. Read this archive when a task needs past implementation context, previous verification commands, or historical handoff details.
|
|
|
|
## Archive Policy
|
|
|
|
- Keep completed sprint outcomes here after they no longer need to stay in `PROGRESS.md`.
|
|
- Keep `PROGRESS.md` short and current.
|
|
- Keep source-of-truth product requirements in `PRD.md` and architecture decisions in `ARCHITECTURE.md`.
|
|
- Keep sprint contract details under `docs/Sprints/`.
|
|
- Do not archive or commit sample PDFs or generated conversion outputs.
|
|
|
|
## Completed Milestones
|
|
|
|
| Area | Completed Outcome | Primary References |
|
|
| --- | --- | --- |
|
|
| Core project documents | Created and iterated `PRD.md`, `AGENTS.md`, `ARCHITECTURE.md`, and `docs/KNOWLEDGEBASE.md`. | `PRD.md`, `AGENTS.md`, `ARCHITECTURE.md`, `docs/KNOWLEDGEBASE.md` |
|
|
| Engine decision | Moved from the initial MinerU 2.5-era planning to fixed MinerU 3.1.0. | `PLAN.md`, `ARCHITECTURE.md`, `docs/KNOWLEDGEBASE.md` |
|
|
| Strict-local policy | Redefined v1 runtime policy: allow direct local `mineru` CLI and its CLI-internal temporary local `mineru-api`; prohibit `--api-url`, remote APIs, router mode, HTTP client backends, and remote OpenAI-compatible backends. | `PRD.md`, `ARCHITECTURE.md`, `AGENTS.md` |
|
|
| Agent workflow | Added shared `PLAN.md` and `PROGRESS.md` workflow, project-scoped agents, commands, skills, hooks, and the planner/generator/evaluator harness guidance. | `AGENTS.md`, `.codex/agents/`, `.codex/commands/`, `.codex/skills/`, `.codex/hooks.json` |
|
|
| V1 implementation planning | Created `docs/V1IMPLEMENTATIONPLAN.md` and sprint contracts under `docs/Sprints/`. | `docs/V1IMPLEMENTATIONPLAN.md`, `docs/Sprints/*.md` |
|
|
| Sprint 0 | Completed source, environment, license, privacy, and contract verification. Recommendation was `go-with-risks`. | `docs/Sprints/SPRINT0CONTRACT.md` |
|
|
| Sprint 1 | Created minimal Python package scaffold, CLI placeholder, `pyproject.toml`, `uv.lock`, and fast pytest loop. | `docs/Sprints/SPRINT1CONTRACT.md` |
|
|
| Sprint 2 | Implemented deterministic local PDF discovery, path planning, overwrite conflict checks, duplicate output checks, and output-root escape prevention. | `docs/Sprints/SPRINT2CONTRACT.md`, `src/pdf2md/paths.py` |
|
|
| Sprint 3 | Implemented project-owned IR records, warning codes/severities, metadata construction, and metadata tests. | `docs/Sprints/SPRINT3CONTRACT.md`, `src/pdf2md/ir.py`, `src/pdf2md/metadata.py` |
|
|
| Sprint 4 | Implemented mocked direct local MinerU CLI adapter boundary and strict-local validation. | `docs/Sprints/SPRINT4CONTRACT.md`, `src/pdf2md/mineru_adapter.py` |
|
|
| Sprint 5 | Implemented Obsidian Markdown normalization, math delimiter handling, asset link normalization, and table fallback warnings. | `docs/Sprints/SPRINT5CONTRACT.md`, `src/pdf2md/markdown.py` |
|
|
| Sprint 6 | Implemented local quality checks and human-readable report rendering from metadata and quality results. | `docs/Sprints/SPRINT6CONTRACT.md`, `src/pdf2md/quality.py`, `src/pdf2md/report.py` |
|
|
| Sprint 7 | Implemented conversion orchestration, `convert_pdf`, `convert_input`, `pdf2md convert`, final Markdown writing, metadata/report writing, asset copying, and fake-adapter CLI/API tests. | `docs/Sprints/SPRINT7CONTRACT.md`, `src/pdf2md/conversion.py`, `src/pdf2md/cli.py` |
|
|
| Sprint 8 | Implemented `pdf2md doctor`, local setup diagnostics, GPU/CUDA/PyTorch/model/cache checks, and setup documentation. | `docs/Sprints/SPRINT8CONTRACT.md`, `src/pdf2md/doctor.py`, `README.md` |
|
|
| Sprint 9 | Implemented fast mocked v1 release-gate tests, optional local MinerU fixture evaluation, and `docs/V1RELEASECHECKLIST.md`. | `docs/Sprints/SPRINT9CONTRACT.md`, `docs/V1RELEASECHECKLIST.md`, `tests/integration/` |
|
|
| GPU default/runtime setup | Made conversion default to `cuda:0`, mapped CUDA requests to MinerU subprocess environment variables, rebuilt `.venv`, installed CUDA-enabled PyTorch and MinerU 3.1.0, downloaded MinerU models, and set `MINERU_MODEL_SOURCE=local`. | `README.md`, `src/pdf2md/mineru_adapter.py`, `src/pdf2md/conversion.py` |
|
|
| MathJax checker | Planned and implemented local MathJax render checker with Node.js helper, Python wrapper, conversion integration, and doctor diagnostics. | `docs/MATHJAXCHECKERPLAN.md`, `tools/mathjax-checker/check.mjs`, `src/pdf2md/math_render.py` |
|
|
| Sprint 10 | Implemented opt-in pre-conversion PDF chunking with `pypdf`, temporary chunk PDF cleanup, `--chunk-pages [PAGES]`, chunk metadata/report context, and mocked tests. | `docs/Sprints/SPRINT10CONTRACT.md`, `src/pdf2md/pdf_splitter.py` |
|
|
|
|
## Runtime Setup Archive
|
|
|
|
- OS/workspace: Windows PowerShell in `D:\Work\Repos\AICoding\ConvertPDFToMD`.
|
|
- Python target: 3.12.
|
|
- Local Python observed during Sprint 0: 3.12.7.
|
|
- `uv` installed per-user at `C:\Users\user\.local\bin`.
|
|
- GPU target: NVIDIA GTX 1070 Ti 8GB.
|
|
- Local GPU observed: NVIDIA GeForce GTX 1070 Ti, driver 577.00, 8192 MiB VRAM, WDDM.
|
|
- MinerU execution mode: direct local `mineru` CLI only.
|
|
- MinerU 3.1.0 CLI-internal temporary local `mineru-api` is allowed when the CLI runs without `--api-url`.
|
|
- GTX 1070 Ti runtime setup used `torch==2.6.0+cu126`, `torchvision==0.21.0+cu126`, and `mineru[core]==3.1.0`.
|
|
- MinerU models were downloaded with `uv run mineru-models-download -s huggingface -m all`.
|
|
- Runtime model loading uses `MINERU_MODEL_SOURCE=local`.
|
|
- Current doctor status after setup is WARN because GTX 1070 Ti is Pascal/pre-Turing; MinerU, CUDA PyTorch, local model config, MathJax checker, and strict-local checks pass.
|
|
|
|
## Sample Conversion Archive
|
|
|
|
Generated outputs are ignored under `outputs/` and are not committed.
|
|
|
|
| Sample | Result | Output Location | Summary |
|
|
| --- | --- | --- | --- |
|
|
| `samples/MITC공부.pdf` | Completed after CUDA-enabled runtime setup. | `outputs/MITC공부/` | 13 pages, 107 assets, 23 inline formulas, 103 display formulas, 1 info warning at the time of that run because the local MathJax checker was unavailable. |
|
|
| `samples/FourNodeQuadrilateralShellElementMITC4.pdf` | Completed with default GPU request and `MINERU_MODEL_SOURCE=local`. | `outputs/FourNodeQuadrilateralShellElementMITC4/` | Report status `success`: 7 pages, 22 assets, 38 inline formulas, 16 display formulas, 0 math render errors, 0 warnings. |
|
|
|
|
## Historical Verification Highlights
|
|
|
|
- Sprint 1 scaffold: `uv run pytest` passed 4 tests; `uv run pdf2md --version` printed `pdf2md 0.1.0`.
|
|
- Sprint 2 path planning: `uv run pytest tests/test_paths.py` passed 17 tests; full suite passed 21 tests.
|
|
- Sprint 3 metadata/IR: targeted IR/metadata tests passed 25 tests; full suite passed 46 tests.
|
|
- Sprint 4 MinerU adapter: adapter tests passed 26 tests; full suite passed 72 tests.
|
|
- Sprint 5 Markdown normalization: targeted Markdown/IR tests passed 30 tests; full suite passed 89 tests.
|
|
- Sprint 6 quality/report: targeted quality/report/metadata tests passed 26 tests; full suite passed 103 tests.
|
|
- Sprint 7 conversion orchestration: full suite passed 119 tests after metadata math count fixes.
|
|
- Sprint 8 doctor: full suite passed 133 tests.
|
|
- Sprint 9 release gate: full suite passed 136 tests with 1 optional skip.
|
|
- CUDA runtime rebuild: verified CUDA with an actual tensor operation on `NVIDIA GeForce GTX 1070 Ti`, compute capability 6.1; `mineru --version` reported 3.1.0.
|
|
- MathJax checker: `npm run mathjax-checker:health` returned `{"ok":true}` after local `npm install`; full suite passed 150 tests with 1 optional skip after integration.
|
|
- Sprint 10 chunking: targeted chunking tests passed 42 tests; full default suite passed 163 tests with 1 optional skip; `git diff --check` passed with line-ending warnings only.
|
|
|
|
## Historical Blockers And Resolutions
|
|
|
|
- Early `uv` availability was missing; resolved by installing `uv` per-user.
|
|
- Initial real sample conversion failed when PyTorch was CPU-only; resolved by rebuilding `.venv` and installing CUDA-enabled PyTorch before MinerU.
|
|
- Optional local MinerU fixture checks were originally blocked by missing MinerU CLI; resolved for the local environment after MinerU 3.1.0 and model setup.
|
|
- Local MathJax render checking was originally unavailable; resolved after adding the local Node.js MathJax checker and installing local npm dependencies.
|
|
- GTX 1070 Ti remains a Pascal/pre-Turing GPU risk. This is a warning, not a current blocker.
|
|
|
|
## Archive Notes For Agents
|
|
|
|
- Read this file when a task asks for historical implementation state, prior verification, completed sprint context, or sample conversion evidence.
|
|
- Prefer `PROGRESS.md` for current state and next actions.
|
|
- Prefer sprint contract files for detailed acceptance criteria and handoff structure.
|
|
- Prefer `docs/V1RELEASECHECKLIST.md` for release readiness gates.
|