PDFToMD/docs/PRD.md

PRD: PDFtoMD

목표

PDFtoMD는 수학, 공학, 역학 중심의 PDF 문서를 AI Agent가 쉽게 접근하고 읽을 수 있는 Markdown 문서 묶음으로 변환하는 프로그램입니다.

이 프로젝트의 목표는 PDF의 텍스트를 단순 추출하는 것이 아니라, 원문 문서의 논리 구조를 보존하면서 AI가 읽기 쉬운 지식 자료로 재구성하는 것입니다.

문제 정의

• PDF는 텍스트, 이미지, 수식, 표, 캡션을 좌표 기반으로 저장하므로 원문 읽기 순서가 쉽게 깨집니다.
• 논문과 공학 문서에는 다단 레이아웃, 수식 번호, 그림/표 참조, 복잡한 표가 자주 등장합니다.
• 스캔 PDF와 텍스트 레이어 PDF가 섞인 문서는 OCR 여부를 문서 전체 단위가 아니라 페이지 단위로 판단해야 합니다.
• AI Agent와 RAG 도구는 긴 PDF 하나보다 논리적으로 나뉜 Markdown chunk와 연결된 asset을 더 안정적으로 탐색합니다.

사용자

• PDF 문서를 Markdown으로 변환해 AI Agent, RAG, 개인 지식 관리 도구에 활용하고 싶은 사용자
• 수식, 표, 이미지가 많은 논문/공학 문서를 Markdown으로 읽고 관리하고 싶은 사용자
• 긴 PDF를 여러 Markdown 파일로 나누어 부분 탐색하고 싶은 사용자
• Windows native 환경에서 외부 서비스 없이 로컬로 변환하고 싶은 사용자

1차 MVP 범위

• Windows native 환경에서 완전 로컬 실행
• GPU 기본 사용, VRAM 8GB 환경을 기준으로 안정적인 chunk 처리
• repo-local Python 3.11 단일 venv 환경 사용
• PDF parser는 Marker를 기본 엔진으로 사용
• 본문 구조, OCR/layout, reading order, 표, 그림, heading, caption은 Marker 경로를 유지
• 수학적 표현이나 수식은 Nougat parser를 사용
• PyMuPDF로 페이지 수, 텍스트 레이어 품질, OCR 필요 여부, chunk 계획을 사전 분석
• PDF 텍스트를 Markdown 문단과 heading 구조로 변환
• PDF 내 수식을 Markdown math delimiter를 사용하는 LaTeX로 변환
• Nougat 실패 시 Marker 원문 수식 문자열을 fallback으로 보존
• PDF 내 이미지를 추출하고 Markdown에서 연결
• 이미지의 figure 번호와 캡션을 가능한 한 보존
• PDF 내 표를 구조화하고 Markdown table로 출력
• Markdown table 손실이 큰 표는 제한적 HTML table 또는 표 영역 이미지 fallback으로 보존
• 페이지 수가 많은 문서를 20페이지 목표 chunk로 분할하되 논리 block 경계 보존
• CLI 진행률, chunk 단위 성공/실패 요약, stderr/local log 기록
• 실패 chunk 재개를 위한 runtime cache/state 기반 resume 옵션
• samples/ PDF 기반 품질 검증과 회귀 테스트 지원

2차 범위

• PyQt 기반 Windows UI
• UI는 CLI/라이브러리 계층을 호출하는 thin client로 구현
• 선택적 외부 API 연동은 변환 엔진 안정화 이후 검토

제외 범위

• hosted conversion API 기본 경로화
• LLM 보정 모드 기본 경로화
• 생성 문서와 함께 배포되는 별도 sidecar metadata/log 산출물
• 변환 엔진 로직을 PyQt UI 안에 중복 구현하는 방식

핵심 기능

1. PDF 문서를 Markdown 문서 묶음으로 변환
2. 텍스트 PDF, 스캔 PDF, 혼합 PDF를 페이지별 OCR 판단으로 처리
3. 수식을 $ ... $ 또는 $$ ... $$ 형식의 LaTeX로 보존
4. 수식 번호와 본문 내 수식 참조를 가능한 한 내부 링크로 연결
5. 논문에서 자주 쓰이는 다중 컬럼 문서를 Markdown의 선형 구조로 재배치
6. 이미지 추출 및 Markdown 연결
7. figure 번호, caption, 본문 내 figure 참조 연결
8. 표 구조화 및 표 유형별 Markdown/HTML/fallback 이미지 출력
9. 긴 PDF를 여러 chunk Markdown 파일로 분할 변환
10. 한글 파일명, 긴 Windows 경로, 공백 포함 경로 지원
11. GTX 1070 Ti 8GB VRAM 기준 batch 크기 제어와 OOM 재시도
12. offline 실행을 위한 명시적 model cache 정책

품질 기준

• 원문 읽기 순서가 Markdown에서 자연스럽게 유지되어야 합니다.
• heading, 본문, 리스트, 인용, 표, 그림, 캡션, 수식의 의미 역할이 구분되어야 합니다.
• 수식 delimiter와 기본 LaTeX 구조가 깨지지 않아야 합니다.
• 수식 번호와 본문 참조가 가능한 한 연결되어야 합니다.
• 이미지와 캡션, figure 번호, 본문 참조가 가능한 한 연결되어야 합니다.
• 표는 구조 손실을 최소화하는 형식으로 저장되어야 합니다.
• chunk 경계가 문단, 표, 그림, 수식을 중간에서 깨뜨리지 않아야 합니다.
• 같은 입력 PDF와 같은 옵션은 같은 파일명, anchor, asset 구조를 생성해야 합니다.
• Windows 경로, 한글 파일명, 긴 문서, GPU 메모리 부족 상황을 고려해야 합니다.
• 오류와 경고는 Markdown 본문을 오염시키지 않고 stderr/local log에 남겨야 합니다.

Acceptance Criteria

• python scripts/validate_workspace.py가 성공해야 합니다.
• .\venv\python.exe -m pip check가 성공해야 합니다.
• CUDA smoke test가 GTX 1070 Ti에서 성공해야 합니다.
• .\venv\Scripts\nougat.exe --help가 성공해야 합니다.
• sample metadata mapping 파일이 각 sample PDF의 특성을 설명해야 합니다.
• focused pytest가 heading, 수식 delimiter, LaTeX environment pair, image link, caption matching, table parseability, chunk boundary, no-exception conversion을 검증해야 합니다.

UI

• UI는 2차 목표로 PyQt를 사용합니다.
• UI는 변환 엔진을 직접 구현하지 않고 CLI/라이브러리 계층을 호출하는 thin client로 둡니다.
• 미니멀하고 깔끔한 Windows 표준 디자인을 따릅니다.