PDF Summary: 스캔한 PDF 도서 자동 요약 및 서평 생성 프로그램

1. 개발 배경

서재 공간을 확보하기 위해 소장 중이던 종이책을 북스캐너(ScanSnap)로 직접 스캔하여 PDF로 보관해 왔습니다. 그러나 시간이 지나면서 각 도서의 주요 내용이 기억나지 않는 문제가 발생했습니다.

이러한 문제를 해결하고자, 대량의 PDF 도서를 자동으로 분석·요약하고 고품질 서평 마크다운 문서로 만들어 주는 PDF Summary 프로그램을 개발하게 되었습니다.

---

2. 주요 기능 및 특징

1. ⚡ 로컬 초고속 마크다운 추출, 텍스트 캐싱 및 저비용 AI 분석:

   • pymupdf4llm 기반으로 PDF의 제목, 본문, 표, 서식을 로컬에서 즉시 마크다운으로 추출 (불필요한 이미지 파싱 연산 생략 최적화로 고속 파싱)
   • 이미 {도서명}_source.md 파일이 존재하는 경우 PDF 추출을 건너뛰고 기존 파일을 즉시 로드하여 고속 요약 지원 (텍스트 캐싱)
   • 불필요한 파일 업로드 대기 시간을 없애고 순수 텍스트 토큰만 소모하여 초고속 서평 생성
   • 텍스트 레이어가 없는 순수 스캔본 PDF는 Gemini Files API 비전 멀티모달 모드로 자동 전환(Fallback)

2. 폴더 단위 일괄 처리 & 스마트 스킵 및 리소스 자동 보충:

   • 지정된 폴더 내의 모든 도서 PDF를 순차적으로 탐색 및 처리
   • 이미 마크다운 리뷰가 완성된 도서는 자동으로 감지하여 건너뛰므로(Skip), 작업 중단 후 재실행 시 중복 API 호출 방지
   • 스킵 시 북커버 이미지(_cover.jpg)나 도서 원문 마크다운(_source.md, --source 활성화 시)이 누락되어 있다면 API 호출 없이 로컬에서 즉시 보충 생성

3. 시리즈물 자동 감지, 전 권 자동 수집 및 장편(3권 이상) 권별 분할 파이프라인:

   • 1권, 2권, 3권, (1), (2), _01, _02, 상/중/하, Vol.1, Vol.2 등 동일 도서명의 시리즈물을 자동 그룹화
   • 스마트 시리즈 자동 수집: 단일 파일 실행 시 시리즈 중 임의의 권수(예: 상도 1.pdf)만 지정하더라도 같은 폴더 내 동일 시리즈의 전 권을 자동 검색 및 묶음 처리
   • 북커버 이미지: 첫 번째 PDF(1권)에서만 대표 커버 이미지를 추출하여 생성
   • 장편 시리즈 최적화 & 중복 파싱 제거: 3권 이상의 다권 시리즈(또는 30만 자 초과) 도서는 1회차 추출본을 메모리에서 즉시 재사용(중복 추출 생략)하며, 권별로 핵심 요약을 먼저 추출한 뒤 종합 합성하여 단일 요청 토큰 한도 초과 및 과부하를 원천 차단

4. 🛡️ 무료 할당량(Quota) 보호 및 자동 모델 폴백 / 즉시 안전 종료:

   • 일일 무료 한도(PerDay/FreeTier) 초과 대응: 기본 모델(gemini-3.7-flash)의 일일 한도 소진 시 gemini-3.6-flash로 자동 전환하며, 모든 대체 모델의 일일 한도 소진 시 불필요한 쿨다운 대기 없이 작업을 즉시 안전하게 종료
   • 분당 토큰/요청 한도(RPM/TPM) 초과 대응: 에러 메시지의 권장 대기 시간을 자동 파싱하여 안전하게 쿨다운 대기 후 자동 재시도 (최대 5회)
   • 404 미지원 모델 자동 감지: 서비스가 종료된 모델 감지 시 다음 사용 가능한 대체 모델로 즉시 전환

5. 📄 대용량 도서 자동 분할 요약 및 파트 간 TPM 보호 쿨다운:

   • 100만 토큰(1,048,576 tokens)을 초과하는 대형 도서(400 INVALID_ARGUMENT) 감지 시 텍스트/PDF를 3등분 자동 분할
   • 파트별 요약 호출 사이와 최종 통합 직전에 15초 안전 쿨다운을 적용하여 1분당 토큰 한도(TPM) 초과 없이 누락 없는 완성형 종합 서평 마크다운 생성

6. 첫 페이지 북커버 캡처 & 이미지 링크 안정화:

   • PyMuPDF를 활용하여 1페이지를 선명한 고해상도(200 DPI) 경량 JPG로 추출 및 저장
   • 도서명에 포함된 공백을 _로 치환({도서명_공백제거}_cover.jpg)하여 마크다운 뷰어/웹 플랫폼에서 이미지 링크 깨짐 현상 방지

7. 스포일러 없는 장르별 맞춤 AI 도서 요약:

   • 소설/문학: 결말 및 핵심 반전 스포일러 없이, 인물 갈등과 서스펜스 중심의 예고편 스타일 서평 + 등장인물 관계도 (Mermaid 다이어그램)
   • 비문학/실용서: 저자의 핵심 통찰, 프레임워크, 실사례 중심 서술 + 핵심 개념 체계도 (Mermaid 다이어그램)

8. SEO & AEO 최적화 마크다운 및 렌더링 후처리:

   • SEO (검색 엔진 최적화): 메타 타이틀(30~50자), 메타 디스크립션(80~150자), 추천 태그, 구조화된 H1/H2/H3 헤딩
   • AEO (AI 답변 최적화): ChatGPT Search, Perplexity, Google AI Overviews 등이 바로 인용할 수 있는 핵심 Q&A (FAQ) 섹션 포함
   • 렌더링 자동 보정:
     • 물결표 이스케이프: 취소선(strikethrough) 오작동 방지를 위한 \~ 자동 이스케이프
     • 볼드 공백 정규화: **강조** 뒤 공백 자동 삽입
     • Mermaid 다이어그램 최적화: 고시인성 테마 + 4대 구문 오류 자동 보정
     • 태그 쉼표 정규화: 블로그 플랫폼 태그창에 바로 복사 가능한 쉼표 구분 포맷
   • 네이버 블로그, 티스토리, 워드프레스, 벨로그, 노션 등에 즉시 복사/붙여넣기 가능

---

3. 프로그램 다운로드

프로그램 소스 코드 및 설치 방법은 GitHub 리포지토리에서 확인할 수 있습니다.

• GitHub Repository: https://github.com/ethanjoh/pdf_summary

---

4. 유의사항

• 텍스트 기반 PDF(OCR 필수): 텍스트 레이어가 포함된 PDF를 기준으로 작동합니다. OCR 처리가 되지 않은 이미지 형태의 PDF 요약이 필요할 경우 별도의 OCR API 연동 및 코드 수정이 필요합니다.
• 티스토리 다이어그램 수정 주의: 티스토리 에디터에서 글을 수정한 뒤 재발행할 경우 Mermaid 다이어그램 태그가 누락될 수 있으므로, 최종 발행 전 다이어그램 코드가 유지되었는지 확인해야 합니다.