실제 HWP/HWPX 파일로 rhwp-python 을 사용하는 typer 기반 예제 모음. 각 스크립트는 사용자 본인의 HWP 파일 경로를 인자로 받아 바로 돌릴 수 있다.

# 01 ~ 07 예제 전부 한 방에 설치 (typer + langchain-core + text-splitters + fastmcp + pillow)
pip install "rhwp-python[examples]"

06 의 chunks MCP 도구는 langchain-text-splitters 가 필요한데 위 한 줄에 포함됨. 07 의 디코드 dimension 검증에는 Pillow 가 필요한데 위 한 줄에 포함됨 (미설치 시 PNG magic + 길이만 출력하는 graceful degrade). 통합 레이어만 필요하면 (예제 러너 없이 직접 HwpLoader 사용) pip install "rhwp-python[langchain]" 만으로 충분하다.

모든 스크립트는 --help 로 옵션을 확인할 수 있다.

python examples/01_parse_basic.py path/to/your/file.hwp
python examples/01_parse_basic.py path/to/your/file.hwp --preview 200

옵션:

• --preview / -p INT : 본문 프리뷰 문자 수 (기본 500)

python examples/02_render_svg_pdf.py path/to/your/file.hwp
python examples/02_render_svg_pdf.py path/to/your/file.hwp -o ./out --no-pdf

옵션:

• --output-dir / -o PATH : 출력 디렉토리 (기본 ./render_output)
• --no-svg / --no-pdf : 특정 포맷 건너뛰기
• --prefix TEXT : SVG 파일명 접두사 (기본 page)

python examples/03_langchain_rag.py path/to/your/file.hwp
python examples/03_langchain_rag.py path/to/your/file.hwp --chunk-size 1000 --chunk-overlap 100

옵션:

• --chunk-size INT : 청크 최대 문자 수 (기본 500)
• --chunk-overlap INT : 청크 간 오버랩 (기본 50)

python examples/04_document_ir.py path/to/your/file.hwp
python examples/04_document_ir.py path/to/your/file.hwp --limit 20
python examples/04_document_ir.py path/to/your/file.hwp --out ir.json

to_ir() 로 구조화 IR 을 얻어 블록 타입 분포, layout 셀 개수, 첫 표의 HTML 직렬화를 출력. --out 으로 전체 IR 을 JSON 파일로 저장 가능.

옵션:

• --limit / -n INT : 미리보기할 블록 최대 개수 (기본 15)
• --out / -o PATH : 전체 IR 을 JSON 파일로 덤프

python examples/05_langchain_ir_blocks.py path/to/your/file.hwp
python examples/05_langchain_ir_blocks.py path/to/your/file.hwp --kind-filter table

HwpLoader(mode="ir-blocks") 가 단락은 text, 표는 HTML (HtmlRAG 호환) 로 매핑하는 것을 단락/표 유형별로 미리본다. 표에는 rows/cols/caption/text 가 메타로 함께 노출되어 dual-track RAG (임베딩=평문, LLM=HTML) 가 가능.

옵션:

• --kind-filter / -k {all,paragraph,table} : 표시 종류 필터 (기본 all)
• --limit / -n INT : 미리보기할 Document 최대 개수 (기본 10)

python examples/06_mcp_server.py path/to/your/file.hwp
python examples/06_mcp_server.py path/to/your/file.hwp --skip-chunks

rhwp.mcp.server.build_server() 로 fastmcp 인스턴스를 만들고, fastmcp Client 로 in-process round-trip — 7 도구 (parse_hwp_summary / extract_text / get_ir / iter_blocks / to_markdown / to_html / chunks) 를 차례로 호출하며 출력 형식을 학습.

실제 운영에는 Claude Desktop / Cursor / Cline 등이 stdio subprocess 로 rhwp-mcp 명령을 spawn 하지만, 본 예제는 같은 프로세스에서 client/server 를 묶어 빠르고 확정적으로 동작 검증 가능. 등록 / 실배포 가이드는 README §MCP server.

옵션:

• --skip-chunks : [mcp-chunks] extras 미설치 환경에서 chunks 호출 스킵

python examples/07_render_png.py path/to/your/file.hwp
python examples/07_render_png.py path/to/your/file.hwp --page 2 --scale 2.0
python examples/07_render_png.py path/to/your/file.hwp --all
python examples/07_render_png.py path/to/your/file.hwp --all --scale 1.5 -o ./out

Document.render_png(page) / Document.export_png(dir) 두 표면을 시연. 단일 페이지 모드 (기본) 는 한 장을 {prefix}.png 로 저장 — VLM (Claude Vision / GPT-4V / Gemini) 입력용으로 가장 흔한 형태. --all 모드는 전 페이지를 {prefix}_{NNN}.png 로 저장한다 (--scale / --max-pixels 가 기본값과 다르면 page 단위 루프, 아니면 export_png 일괄 호출 — 두 API 의 trade-off 학습 포인트). Pillow 가 설치돼 있으면 디코드 dimension 까지 출력, 미설치 시 PNG magic + 길이만 출력 (graceful degrade).

옵션:

• --page / -p INT : 0-based 페이지 인덱스 (기본 0). --all 지정 시 무시
• --all : 전 페이지 일괄 렌더링
• --scale / -s FLOAT : 픽셀 너비/높이 배율 (기본 1.0). VLM 해상도 ↑ 시 2.0 ~ 3.0
• --max-pixels INT : DoS 가드 픽셀 상한 (기본 8192×8192 = 67_108_864)
• --output-dir / -o PATH : 출력 디렉토리 (기본 ./render_output)
• --prefix TEXT : PNG 파일명 접두사 (기본 page)

릴리스 직전 본인의 업무 HWP 파일 3종 (일반 문서 / 장문 / HWPX) 으로 일곱 스크립트를 순서대로 돌려 출력을 육안 확인한다. 한컴오피스 뷰어로 연 원본과 대조해 섹션/문단/페이지 수치, SVG/PDF/PNG 렌더, IR 의 block/table 구조, LangChain Document 매핑, MCP 도구 7 종이 깨지지 않는지 본다.