# 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 표준 디자인을 따릅니다.