b565b330d9
- design: docs/superpowers/specs/2026-04-27-kb-final-form-design.md - locks UX shape, wire schema v1, domain model, ID recipe, DDL, layout, traits, module boundaries, versioning, errors - tasks/INDEX.md + 10 phase docs derived from kb_local_rust_report.md
99 lines
2.8 KiB
Markdown
99 lines
2.8 KiB
Markdown
---
|
|
phase: P7
|
|
title: "PDF text extraction + page citation"
|
|
status: planned
|
|
depends_on: [P5]
|
|
source: kb_local_rust_report.md §9.2, §17 Phase 7
|
|
---
|
|
|
|
# P7 — PDF ingestion
|
|
|
|
## 목표
|
|
|
|
text PDF 추출 → page-aware chunking → citation `paper.pdf:p13`. scanned PDF OCR 는 후속 단계.
|
|
|
|
## 산출 crate
|
|
|
|
- `kb-parse-pdf` — `Extractor` 구현.
|
|
|
|
## 단계 분리 (§9.2)
|
|
|
|
| 단계 | 범위 | 우선순위 |
|
|
|------|------|---------|
|
|
| 1 | text PDF 추출 (page + text span) | P7 본체 |
|
|
| 2 | scanned PDF OCR | 후속, image OCR 인프라 재사용 |
|
|
|
|
처음부터 layout reconstruction 욕심 금지. **page number + text span 보존**이 1차 목표.
|
|
|
|
## 라이브러리 선택
|
|
|
|
- 1차: `pdf-extract` (단순 텍스트 추출).
|
|
- 보조: `lopdf` (페이지 단위 접근, metadata).
|
|
- text 추출 실패 / 빈 페이지 → scanned 의심 표시 → 2단계 OCR 후보로 큐잉.
|
|
|
|
## CanonicalDocument 매핑
|
|
|
|
PDF 1개 = 1 document. 페이지 단위 block:
|
|
|
|
```rust
|
|
pub struct PdfPageBlock {
|
|
pub page_number: u32,
|
|
pub text: String,
|
|
pub source_span: SourceSpan, // byte range or char range within page
|
|
pub section_hint: Option<String>, // 휴리스틱 추출, optional
|
|
}
|
|
```
|
|
|
|
heading 검출: PDF 자체엔 heading 의미 없음. 휴리스틱 (font size, bold, ALL CAPS) 1차에서는 생략. section 은 best-effort.
|
|
|
|
## Chunking
|
|
|
|
- page-respect: chunk 가 page 경계 넘지 않음 (citation 단순화).
|
|
- 긴 page → paragraph 단위로 sub-chunk.
|
|
- chunker version: `pdf-page-v1`.
|
|
|
|
## Citation 형식
|
|
|
|
```text
|
|
paper.pdf:p13
|
|
paper.pdf:p13:section=Experiment Setup
|
|
paper.pdf:p13:span=0-1240 # char range within page
|
|
```
|
|
|
|
## CLI
|
|
|
|
```text
|
|
kb ingest ./paper.pdf
|
|
kb ingest ./papers/
|
|
kb search "PDF 안의 특정 개념"
|
|
kb inspect doc <pdf_doc_id>
|
|
```
|
|
|
|
## 테스트
|
|
|
|
- fixture: 한글 PDF (논문/문서), 영문 PDF, 다단 layout, 표 포함, 빈 페이지 포함.
|
|
- page number 정확도 (1-based, 1페이지 PDF 도 OK).
|
|
- citation round-trip: `paper.pdf:p13` 으로 다시 page 텍스트 회수 가능.
|
|
- 추출 실패 페이지는 reject 하지 않고 provenance warning + scanned 후보 표시.
|
|
- 동일 PDF 재수집 idempotent.
|
|
|
|
## 의존성 경계
|
|
|
|
- `kb-parse-pdf` 는 `kb-core` + `pdf-extract` / `lopdf` 만.
|
|
- OCR 호출은 별도 adapter 통해 (P6 OCR 인프라 재사용).
|
|
|
|
## 완료 조건
|
|
|
|
- [ ] `kb ingest <pdf>` 동작
|
|
- [ ] page-level chunk + citation
|
|
- [ ] 검색 결과에 `paper.pdf:p<n>` 포함
|
|
- [ ] 추출 실패 페이지에 대한 provenance warning
|
|
- [ ] 동일 PDF 재수집 idempotent
|
|
|
|
## 리스크 / 주의
|
|
|
|
- text 추출 품질은 PDF 생성 도구에 크게 좌우. 깨진 한글 (CID 미매핑) 흔함.
|
|
- 다단/표 layout 은 reading order 깨짐 → 검색 noise. 1차에선 감수.
|
|
- OCR 단계 들어가면 비용/시간 급증. 별도 background job 으로.
|
|
- 큰 PDF (>1000p) memory streaming 처리 필요.
|