reportgen-pipeline 0.2.8

LLM 기반 국책과제계획서(HWPX) 자동 작성 파이프라인

ReportGen-pipeline

한국 국가 R&D 제안서(HWPX)를 위한 AI 자동 작성 파이프라인 — 양식 분석부터 완성까지, 외부 LLM 에이전트와 함께.

---

Overview

HWPX 양식(연구개발계획서)과 참고자료(PDF·TXT·HWPX)를 입력하면, 양식의 구조를 분석해 외부 LLM 에이전트가 채울 수 있는 매핑 요청(JSON)을 생성하고, 에이전트가 작성한 매핑을 적용해 완성된 HWPX를 만드는 2-phase 파이프라인입니다.

내부에 LLM API 호출이 없습니다 — 내용 생성은 Claude Code·OpenCode 등 외부 에이전트에 위임하고, 이 파이프라인은 HWPX 구조 분석과 XML 편집만 담당합니다. 그래서 API 키 관리나 모델·제공사 종속이 없고, PyPI·standalone 실행파일·Claude Code 플러그인 3가지 채널로 배포되어 어떤 환경에서도 설치할 수 있습니다.

---

Features

• 🔍 HWPX 구조 자동 분석 — TOC 탐지, 표 5종 분류(DATA/INSTR/SKIP/SCHED/IDENT), 단락 placeholder 인식을 한 번에 수행합니다.
• 🤝 매핑 요청 아티팩트 생성 — 외부 LLM 에이전트가 읽을 수 있는 request.json + prompt.md를 출력합니다. 내부 LLM 호출 없음.
• ✍️ FieldMapping 적용 엔진 — 에이전트가 작성한 JSON 매핑을 replace/fill_cell/insert_after 세 가지 액션으로 HWPX XML에 정확히 반영합니다.
• 🔤 폰트 일관성 & 줄바꿈 보호 — 맑은 고딕 12pt non-bold charPr 자동 적용, <hp:linesegarray> stale 캐시 제거로 한글이 재배치할 때 겹침이 생기지 않습니다.
• 📎 참고자료 흡수 — PDF·TXT 파일을 자동 파싱해 매핑 요청 페이로드에 포함시킵니다.
• 🛡️ 구조 검증 게이트 — 표 손실·좌표 이상·단락 채움률을 파이프라인 직후 자동 검사하고, SKIP/SCHED 표를 제외한 정확한 채움률을 측정합니다.
• 🔁 HWP → HWPX 변환 — Java fat JAR로 바이너리 HWP를 ZIP 기반 HWPX로 변환합니다.
• 📦 3중 배포 채널 — PyPI(알림 기반 업그레이드), standalone 실행파일(자가 업데이트), Claude Code 플러그인 마켓플레이스. 채널별 특징은 설치 참고.

---

Quick Start

pip install reportgen-pipeline

# Phase 1 — 양식 분석 & 매핑 요청 생성 (LLM 호출 없음)
hwp-pipeline \
  --template  input/연구개발계획서_양식.hwpx \
  --reference input/과제요약.txt input/RFP.pdf \
  --emit-mapping-request request.json

# (외부 LLM 에이전트가 request.json 을 읽고 mappings.json 을 작성)

# Phase 2 — 매핑 적용 & HWPX 출력
hwp-pipeline \
  --template input/연구개발계획서_양식.hwpx \
  --mappings mappings.json \
  --output   output/result.hwpx \
  --measure

---

How It Works

1. 양식 분석 (Phase 1) — StructureAnalyzer가 HWPX 양식의 표·단락 구조를 파싱하고, 표를 DATA/INSTR/SKIP/SCHED/IDENT 5종으로 자동 분류한 뒤 fill target을 탐지해 request.json(전체 상세) + digest.py가 만드는 압축 다이제스트(수십 KB, --emit-digest) + 선택적 prompt.md를 출력합니다. 이 단계는 LLM API를 호출하지 않습니다.
2. 외부 LLM 에이전트가 채움 — Claude Code, OpenCode 등 외부 에이전트가 (대형 양식일수록) request.json 전체 대신 압축 다이제스트로 채움 설계를 수립하고, 필요한 요소만 타깃 조회해 FieldMapping[] 계약에 맞춰 mappings.json을 작성합니다. 어떤 모델·제공사를 쓰든 파이프라인 코드는 변경할 필요가 없습니다.
3. 매핑 적용 (Phase 2) — SmartFillEngine이 mappings.json을 HWPX XML에 반영합니다: replace(단락, linesegarray 캐시 제거) · fill_cell(표 셀, 실존 좌표 검증) · insert_after(맑은 고딕 12pt 적용).
4. 검증 + 측정 — verify_output이 표 손실·단락 채움률 게이트를 통과시키고, measure_fill_rate가 SKIP/SCHED 표를 제외한 원본 템플릿 기준 정확한 채움률을 계산합니다. 완성된 output.hwpx는 한글(Hangul)에서 바로 열립니다.

핵심 설계 원칙

원칙	내용
양식 불변	작성요령(제출 시 삭제) 표·난해 표·신원 표는 원형 보존, 일반 데이터 표만 채움
줄바꿈 보호	<hp:linesegarray> stale 캐시 제거 → 한글 재배치 트리거, 겹침 없음
동적 분류	간트 일정표·편성도·빈 격자를 패턴으로 자동 식별, 하드코딩 없음
외부 LLM	내용 생성은 외부 에이전트에 위임 — 제공사·모델 전환이 자유로움
정확한 측정	SKIP/SCHED 표 제외, 원본 템플릿 기준 단락 채움률 계산
압축 우선 분석	분석 단계는 request.json 정독 대신 압축 다이제스트를 1차 입력으로 사용 — 실측 사례: 표 29개 양식에서 1.5MB → 45KB

---

CLI

--template   <HWPX 양식 경로>              (필수)
--output     <출력 HWPX 경로>              (Phase 2 필수)
--reference  <파일1> <파일2> ...            PDF/TXT/HWPX 참고파일
--data       <user_data.json>              추가 구조화 데이터 (선택)
--instructions "추가 지시문"                에이전트 추가 지시 (선택)
--emit-mapping-request <request.json>      Phase 1: 매핑 요청 생성
--emit-digest <digest.json>                Phase 1: 압축 구조 다이제스트 저장 (분석 단계 1차 입력, 권장)
--prompt-output <prompt.md>                Phase 1: Markdown 프롬프트 저장 (선택)
--mappings   <mappings.json>               Phase 2: 매핑 적용
--analysis-output <분석결과.json>            양식 분석 결과 저장 (선택)
--measure                                  완료 후 채움률 출력
--version                                  버전 확인
--upgrade                                  standalone 바이너리 채널: 즉시 자가 업그레이드
--no-update-check                          시작 시 업데이트 확인 생략
--verbose

HWP → HWPX 변환 후 실행

java -jar java/hwp2hwpx-fat.jar input/양식.hwp input/양식.hwpx
hwp-pipeline --template input/양식.hwpx --emit-mapping-request request.json

채움률 측정 (별도)

python scripts/measure_fill_rate.py --file output/result.hwpx --template input/양식.hwpx

=======================================================
Fill Rate Report: result.hwpx  [template]
=======================================================
TABLE CELLS (DATA tables only, SKIP/SCHED excluded):
  Total data cells  : 86
  Filled cells      : 86
  Fill rate         : 100.0%  [##################################################]

PARAGRAPH TARGETS (from template):
  Total targets     : 66
  Filled            : 60
  Fill rate         : 90.9%  [#############################################-----]
=======================================================

---

Installation

채널	명령	특징
PyPI (권장)	pip install reportgen-pipeline	공개 배포, 실행 시 새 버전 하루 1회 확인 후 pip install -U 안내
Standalone 바이너리	Releases에서 hwp-pipeline-<os>-<arch> 다운로드	사내/협업자 전용(private repo, 인증 필요), OpenCode 방식 진짜 자가 업그레이드
소스 (개발용)	git clone 후 pip install -e .	hwp-pipeline CLI 포함, editable 설치

사전 요구사항

• Python 3.10+
• Java 11+ / Maven (HWP → HWPX 변환 시에만 필요)

PyPI 채널 상세

pip install reportgen-pipeline
pip install -U reportgen-pipeline   # 업그레이드
hwp-pipeline --version

pip은 설계상 자동으로 재설치하지 않습니다(안전상 정상 동작). CLI는 gh·npm처럼 "새 버전 있음 → pip install -U 하세요" 알림만 출력합니다(REPORTGEN_NO_UPDATE_CHECK=1로 끄기 가능). 이 저장소는 Private이지만 PyPI는 별개의 공개 레지스트리라 이 채널은 누구나 접근할 수 있습니다.

Standalone 바이너리 채널 상세

gh release download v0.2.5 --repo kaismin82/ReportGen-pipeline \
  --pattern "hwp-pipeline-<os>-<arch>*"
./hwp-pipeline-windows-x86_64.exe --template ... --emit-mapping-request request.json

⚠️ 이 저장소가 Private이므로 이 채널은 저장소 접근 권한이 있는 사람만 쓸 수 있습니다(익명 요청은 GitHub API에서 404). gh auth token 또는 GITHUB_TOKEN/GH_TOKEN 환경변수로 인증됩니다. 공개 배포가 필요하면 PyPI 채널을 쓰세요.

pip 패키지와 달리 standalone 실행파일은 자기 자신만 소유하므로(공유 환경/고정 버전을 깰 위험 없음), 실행할 때마다 새 버전을 감지하면 자기 실행파일을 교체하고 같은 명령으로 즉시 재실행합니다 — OpenCode의 opencode upgrade와 동일한 원리입니다. hwp-pipeline --upgrade로 즉시 강제 적용, REPORTGEN_NO_AUTOUPDATE=1로 끄기.

소스 설치 & conda 주의사항

git clone https://github.com/kaismin82/ReportGen-pipeline.git
cd ReportGen-pipeline
pip install -r requirements.txt      # 의존성만
pip install -e .                     # 또는 editable 설치 (hwp-pipeline CLI 포함)
bash setup.sh --java                 # (선택) HWP→HWPX 변환기 빌드

conda 환경에서는 hwpx라는 별개의 패키지가 설치되어 있을 수 있습니다 (pip install hwpx(❌) ≠ pip install python-hwpx(✅)):

pip install python-hwpx --force-reinstall

---

Architecture

모듈	역할
universal_pipeline.py	📌 메인 CLI 진입점 (hwp-pipeline 명령)
document_model.py	데이터 클래스 (DocumentElement, TableInfo, FieldMapping)
structure_analyzer.py	HWPX 구조 분석 · 표/단락 분류
dynamic_template_analyzer.py	분석 오케스트레이터 (LLM 호출 없음)
smart_fill_engine.py	HWPX XML 편집 엔진 (replace/fill_cell/insert_after)
table_resolve.py	중첩 표 리졸버 (레이아웃 프레임 통과)
toc_detection.py	TOC 탐지 · 표 분류 헬퍼 · blank 감지 regex
reference_reader.py	PDF/TXT 참고파일 파서
schedule_handler.py	간트 일정표 메타 추출
verify_output.py	출력 구조 검증 게이트
measure_fill_rate.py	채움률 측정 (템플릿 기준 정확 계산)
digest.py	압축 구조 다이제스트 생성 (elements 만으로 계산, 분석 단계 1차 입력)
hwpx_compat.py / hwpx_utils.py	HWPX 패키지 호환 레이어 · 공유 유틸
update_check.py	PyPI 최신 버전 확인·알림 (pip 채널)
self_update.py	standalone 바이너리 자가 업데이트 (private repo, 인증 필요)
bump_version.py	버전 일괄 갱신·릴리즈·CI 일관성 검사

ReportGen-pipeline/
├── scripts/            # 위 표의 전체 모듈 + archive/(구버전 스크립트)
├── tests/               # pytest 스위트 (103+ passing)
├── java/                # HWP→HWPX 변환기 (Convert.java, hwp2hwpx-fat.jar)
├── .claude-plugin/      # Claude Code 마켓플레이스 카탈로그
├── hwp-pipeline/        # Claude Code 플러그인 (배포용, plugin.json + SKILL.md)
├── .claude/skills/      # 프로젝트 스코프 스킬 (플러그인 미러)
├── .github/workflows/   # ci.yml · publish.yml(PyPI) · build-binaries.yml
├── docs/                # 설계 제안서
├── pyproject.toml       # 패키지 메타데이터 · 빌드 설정
└── requirements.txt

표 분류 체계

분류	기준	처리 방식
DATA	일반 데이터 표	LLM 채움 (fill_cell)
INSTR	작성요령 포함 ("제출 시 삭제")	보존 (건드리지 않음)
SKIP	편성도·WBS·빈 격자	원형 보존
SCHED	간트 일정표 (추진내용+월별 컬럼)	외부 에이전트가 처리
IDENT	연구책임자·기관 정보	user_data 있으면 자동반영, 없으면 SKIP

---

Claude Code 스킬

/hwp-pipeline 스킬을 Claude Code에서 두 가지 경로로 쓸 수 있습니다.

방법 1 — 플러그인 마켓플레이스 (권장, 자동 업그레이드)

/plugin marketplace add kaismin82/ReportGen-pipeline
/plugin install hwp-pipeline@reportgen-marketplace

새 릴리즈가 나오면 백그라운드로 자동 감지·다운로드되고, 다음 세션(재시작)에서 명령 없이 자동 활성화됩니다(현재 세션에 즉시 반영하려면 /reload-plugins 1회). ⚠️ 저장소가 Private이라 이 채널도 접근 권한이 있는 협업자 전용입니다.

방법 2 — 저장소에서 직접 사용 저장소를 클론하면 .claude/skills/hwp-pipeline/SKILL.md가 프로젝트 스코프 스킬로 바로 인식됩니다. 업데이트는 git pull.

/hwp-pipeline 스킬을 활용하여 아래 양식에 맞게 연구개발계획서를 작성해줘.
- template: input/연구개발계획서_양식.hwpx
- 참고 파일들: input/과제요약.txt input/RFP.pdf
- 출력 파일: output/result.hwpx

스킬이 자동으로 Phase 1 실행 → 참고자료+웹 검색 기반 mappings.json 작성 → Phase 2 실행 → --measure 채움률 확인까지 수행합니다.

---

버전 관리 & 배포 자동화

버전 문자열(pyproject.toml, universal_pipeline.py, README 헤더, plugin.json)은 scripts/bump_version.py가 단일 진실원으로 관리합니다:

python scripts/bump_version.py 0.2.6              # 버전만 일괄 갱신 (SKILL.md 미러 동기화 포함)
python scripts/bump_version.py 0.2.6 --release     # + 커밋·태그(v & hwp-pipeline--v)·푸시·GitHub 릴리즈
python scripts/bump_version.py --check              # CI 일관성 검사 (ci.yml 에서 자동 실행)

GitHub Release가 발행되면 두 워크플로가 자동으로 이어집니다:

• publish.yml → PyPI Trusted Publishing(OIDC)으로 sdist/wheel 자동 게시 (토큰 불필요, 최초 1회 PyPI pending publisher + GitHub pypi 환경 설정 필요)
• build-binaries.yml → Linux/macOS/Windows 3-OS 매트릭스로 standalone 실행파일 빌드·검증·릴리즈 자산 첨부

---

FAQ

Q: ImportError: cannot import name 'HwpxPackage' from 'hwpx' 오류가 납니다. conda 환경에 hwpx(별개 패키지)가 설치되어 충돌한 것입니다. pip install python-hwpx --force-reinstall.

Q: Phase 1 실행 후 어떤 파일을 외부 에이전트에 전달하나요? --emit-mapping-request로 저장된 request.json, --emit-digest로 저장된 압축 다이제스트, --prompt-output의 prompt.md를 전달하세요. 에이전트는 다이제스트로 채움을 설계하고 request.json은 필요한 요소만 타깃 조회한 뒤, FieldMapping[] JSON 배열을 mappings.json으로 작성해야 합니다.

Q: 표가 많은 대형 양식에서 분석 단계 토큰(비용)이 너무 큽니다. --emit-digest로 압축 다이제스트를 생성해 분석 모델에게 request.json 대신 이것을 입력하세요. 다이제스트는 요소당 전체 텍스트를 반복하지 않고 인덱스·미리보기·표 분류·fill 좌표만 담아, 표 29개 양식 기준 1.5MB → 45KB로 압축됩니다. 특정 요소의 정확한 원문이 필요할 때만 request.json을 element_index로 타깃 조회하세요.

Q: 단락 채움률이 낮게 나옵니다. --measure 사용 시 반드시 --template을 함께 지정하세요. 채움 품질은 외부 에이전트의 모델 성능에 따라 달라집니다.

Q: 작성요령 표가 채워집니다. structure_analyzer.py의 _is_instruction_table()이 "제출 시 삭제" 마커를 강한 신호로 탐지합니다. 양식에 마커가 없다면 다른 instruction 신호를 _DELETE_RE에 추가하세요.

Q: 추진 일정표(간트)가 이상하게 채워집니다. 간트 표 구조 메타는 schedule_handler.detect_schedule_meta()가 분석해 request.json에 포함시킵니다. 에이전트 프롬프트에서 간트 처리 방식을 조정하세요.

Q: pip 채널과 standalone 바이너리 채널의 자동 업그레이드는 왜 다르게 동작하나요? pip 패키지는 공유 venv/고정 버전 환경에 살아 몰래 자기 버전을 올리면 사용자의 lock 파일을 깰 위험이 있어 "알림만" 합니다. standalone 실행파일은 자기 자신만 소유하므로 실제 자가 교체가 안전합니다.

---

Development

pip install -e ".[test]"
pytest tests/ -v                                              # 전체 테스트
pytest tests/test_output_qa.py tests/test_smart_fill_engine_p0.py -v   # 핵심 불변식만
python scripts/bump_version.py --check                        # 버전 일관성 검사

테스트 파일	검증 내용
test_output_qa.py	lineseg 부재·셀 안착·리졸버 불변식
test_smart_fill_engine_p0.py	replace/fill_cell/linesegarray strip
test_structure_analyzer_p1.py	TOC 탐지·헤더 추출·instruction 표
test_mapping_artifact_handoff.py	Phase 1/2 CLI 정상 동작
test_self_update.py	플랫폼→자산명, 버전 비교, asset 선택 로직
test_digest.py	표 분류 우선순위, fill target 추출, 대형 표 좌표 생략 임계값
test_e2e_pipeline.py	구조 분석 → SmartFillEngine 전체 흐름
test_korean_edge_cases.py	전각 괄호·ZWSP·전각 공백 blank 감지
test_schedule_table.py	간트 표 탐지·메타 추출

---

License & Credits

MIT — LICENSE. 자유롭게 사용·수정·배포 가능합니다.

프로젝트	역할	라이선스
python-hwpx	HWPX 파일 파싱·패키징 (HwpxPackage)	MIT
hwp2hwpx by neolord0	HWP → HWPX 바이너리 변환 (Java)	Apache 2.0
@ohah/hwpjs by ohah	HWP → JSON/Markdown/HTML (Node.js)	MIT
lxml	HWPX XML 파싱 및 조작	BSD
python-dotenv	.env 환경변수 로드	BSD
pypdf	PDF 텍스트 추출	BSD

참고 및 영감: hwp-pipeline (Yoojin-nam) — 초기 설계 참고한 Claude Code skill · HWP/HWPX 포맷 명세(한글과컴퓨터 HWPML 2011/2016) · Claude Code by Anthropic