# task-937.2: OpenDataLoader PDF 환경 구축 + PDF 스킬 업그레이드 (한정위임)

## 배경
- task-937.1에서 OpenDataLoader PDF(ODL) 심층 분석 완료 (보고서: memory/reports/task-937.1.md)
- 권장안 B안(하이브리드 도입) 채택: 기존 폼 처리 유지 + ODL 문서 추출 추가
- 목표: ODL을 시스템에 설치하고, PDF 스킬을 업그레이드하여 향후 모든 PDF 인식 작업에 자동 활용

## 작업 범위

### Step 1: Java 11+ 설치
- 현재 시스템: Java 8 (openjdk 1.8.0_482) → ODL은 Java 11+ 필수
- `sudo apt install openjdk-11-jre-headless` (또는 openjdk-17)
- 기존 Java 8과 공존 가능 (alternatives 설정)
- `java -version`으로 11+ 확인

### Step 2: ODL Python SDK 설치
- `pip install opendataloader-pdf`
- 설치 후 테스트: `python3 -c "from opendataloader_pdf import convert; print('OK')"`
- CLI 테스트: `opendataloader-pdf --version` (또는 JAR 직접 호출)

### Step 3: hybrid 서버 설치 (docling-fast)
- docling 설치: `pip install docling`
- hybrid_server.py 세팅 (FastAPI + uvicorn, 포트 5002)
- ODL GitHub의 `docs/` 디렉토리에서 hybrid 서버 설정 참조
- systemd 서비스 또는 실행 스크립트 작성: `/home/jay/workspace/scripts/start-hybrid-server.sh`
- GPU 활용 여부 확인 (GTX 1060 CUDA)

### Step 4: PDF 스킬 업그레이드
- 위치: `/home/jay/.claude/skills/pdf/`
- **SKILL.md 업데이트**:
  - "문서 이해/추출 (OpenDataLoader PDF)" 섹션 추가
  - 기존 "폼 처리" 섹션은 그대로 유지
  - 작업 유형별 라우팅 가이드:
    - 폼 작성/필드 추출 → 기존 스크립트 (pypdf, pdfplumber)
    - 텍스트 추출/테이블 추출/OCR/구조 분석 → ODL
  - ODL 주요 옵션 레시피 (format, reading-order, hybrid, ocr-lang, sanitize 등)

- **래핑 스크립트 작성** (scripts/ 디렉토리에 추가):
  1. `extract_text_odl.py` — ODL로 텍스트 추출 (markdown/text 출력)
     - 입력: PDF 경로, 출력 형식(markdown/text/json), 페이지 범위
     - 출력: 추출된 텍스트 (stdout 또는 파일)
     - 옵션: --reading-order xycut, --hybrid docling-fast
  2. `extract_table_odl.py` — ODL로 테이블 추출 (JSON 구조)
     - 입력: PDF 경로
     - 출력: 테이블 데이터 JSON
     - 옵션: --hybrid docling-fast (테이블은 hybrid 필수급)
  3. `ocr_pdf_odl.py` — ODL로 스캔 PDF OCR
     - 입력: PDF 경로, 언어 코드
     - 출력: OCR 텍스트
     - 옵션: --force-ocr, --ocr-lang "ko,en"
  4. `convert_pdf_odl.py` — 범용 ODL 변환 (모든 옵션 지원)
     - 모든 ODL 옵션을 argparse로 노출
     - 결과 파일을 읽어서 stdout으로 출력 (ODL의 None 반환 문제 해결)

- **중요**: ODL convert()는 결과를 파일로만 출력 (return None). 래핑 스크립트에서 임시 디렉토리에 출력 → 결과 파일 읽기 → stdout 출력 패턴 필수.

### Step 5: 테스트 검증
- 로컬 모드 테스트: 샘플 PDF로 텍스트/테이블/JSON 추출
- hybrid 모드 테스트: docling-fast 서버 연동 확인
- OCR 테스트: 한국어 스캔 PDF (있으면)
- 기존 폼 스크립트 정상 동작 확인 (회귀 테스트)

## 참조 자료
- task-937.1 보고서: `/home/jay/workspace/memory/reports/task-937.1.md`
- 기존 PDF 스킬: `/home/jay/.claude/skills/pdf/`
- ODL GitHub: https://github.com/opendataloader-project/opendataloader-pdf
- ODL Python SDK API: task-937.1 보고서 1.7절 참조

## 주의사항
- 기존 PDF 스킬의 폼 관련 스크립트(8개) 절대 수정/삭제 금지
- SKILL.md 기존 내용은 유지하고 ODL 섹션만 추가
- Java 8 제거하지 말 것 (다른 도구에서 사용 가능)
- hybrid 서버는 선택적 (로컬 모드만으로도 가치 있음, hybrid 설치 실패 시 로컬만으로 완료)

## 산출물
- Java 11+ 설치 완료
- opendataloader-pdf 패키지 설치 완료
- hybrid 서버 실행 스크립트 (선택)
- PDF 스킬 SKILL.md 업데이트
- ODL 래핑 스크립트 4개
- 테스트 결과 보고서