ORIGINAL_README.md

AI를 위한 HWP 변환기 (pyhwp Python 3 Port)

"AI가 왜 HWP 파일을 인식하지 못합니까?"

이 프로젝트는 한국의 국정감사에서 이재명 대통령의 이 한 마디 발언에서 시작되었습니다. 비록 정부가 개방형 포맷인 HWPX 도입을 추진하고 있지만, 여전히 수많은 공공 데이터와 일반 사용자들의 문서는 레거시 HWP 포맷(OLE 기반)으로 잠겨 있습니다. 대다수의 사용자들은 HWP와 HWPX의 차이조차 인식하지 못하며, AI 기술의 혜택에서 소외되고 있습니다.

🚀 프로젝트 배경 및 목적

"한글(HWP) 설치 없이, 모든 환경에서 HWP를 이해한다."

기존에 AI가 HWP 파일을 학습하거나 인식하게 하려면, 고가의 '아래아한글' 워드프로세서가 설치된 윈도우 환경에서 OLE Automation을 이용해 텍스트를 추출하는 것이 유일한 대안이었습니다. 이는 리눅스 서버, 맥(Mac), 모바일 환경, 그리고 클라우드 기반의 AI 에이전트(Cursor, Antigravity 등)가 HWP 데이터에 접근하는 데 치명적인 장벽이었습니다.

기존에 pyhwp라는 훌륭한 오픈소스 라이브러리가 존재했으나, 오랜 기간 Python 2.7 환경에 머물러 있어 현대적인 AI 파이프라인(Python 3.10+)에 통합하기 어려웠습니다. 이에 우리는 pyhwp를 Python 3.11로 완벽하게 포팅하고, AI가 즉시 이해할 수 있는 HTML 변환 기능을 추가하여 이 문제를 해결했습니다.

Note: 본래 이러한 상호운용성 지원은 HWP 포맷을 만든 제조사(한글과컴퓨터) 차원에서 진작 제공되었어야 마땅한 기능입니다. 하지만 제조사의 지원 부재로 인해 수많은 개발자와 사용자가 불편을 겪어왔으며, 결국 커뮤니티 주도의 오픈소스 프로젝트가 이 공백을 메우게 되었습니다. 이 프로젝트는 안티그래피티의 에이전트메니저, 클로드 소넷4.5 버전을 이용하여 2시간정도의 작업을 통해 완료 되었습니다. 그 만큼 이렇게 간단하게 개선할수 있던 작업임에도 불구하고 20년간 개선이 이루어지지 않았던 것은 매우 아쉬운 점이며, 이 프로젝트에 영감을 주신, 그리고 이 프로젝트가 가능할수 있었던 기초가 되어준 pyhwp 개발자 에 매우 큰 감사를 드립니다.

🛠️ 기술적 개선 사항 (Why This Fork?)

이 프로젝트는 단순한 버전 업그레이드가 아닙니다. "죽어있던" 코드를 현대적인 개발 환경으로 되살려냈습니다.

1. Python 3.11 완전 지원:

   • 2to3 자동 변환에 그치지 않고, metaclass, bytes/str 처리, ugettext 등 Python 2 기반의 레거시 코드를 전면 리팩토링했습니다.
   • six 모듈 의존성을 제거하고 현대적인 Python 문법을 적용했습니다.

2. AI 최적화 변환기 (HwpToHtmlConverter):

   • 복잡한 내부 로직을 몰라도 단 두 줄의 코드로 HWP를 HTML로 변환할 수 있는 래퍼(Wrapper)를 구현했습니다.
   • 변환된 HTML은 CSS 스타일과 이미지(bindata)를 포함하여 원본의 레이아웃을 최대한 보존합니다. 이는 VLM(Vision Language Model)이나 RAG(Retrieval-Augmented Generation) 시스템이 문서를 시각적/구조적으로 이해하는 데 큰 도움을 줍니다.

3. 플랫폼 독립성:

   • 윈도우뿐만 아니라 Linux, macOS, Mobile 등 Python이 도는 모든 환경에서 작동합니다.
   • 무거운 한글 워드프로세서 설치가 전혀 필요 없습니다.

📦 설치 방법

PyPI에서 설치 (추천)

pip install pyhwp2

소스 코드에서 설치 (개발 버전)

git clone https://github.com/your-repo/pyhwp-py3.git cd pyhwp-py3 pip install -e .

💻 사용 예시 (Python Code)

AI 에이전트 개발자나 Python 개발자는 다음과 같이 쉽게 사용할 수 있습니다.

from pyhwp.html_converter import HwpToHtmlConverter

# HWP 파일을 HTML로 변환
# styles.css 생성 및 bindata(이미지) 폴더 자동 추출
hwp_file = "document.hwp"
html_output = "document.html"

try:
    converter = HwpToHtmlConverter(hwp_file)
    converter.convert(html_output)
    print(f"변환 완료: {html_output}")
    # 이후 생성된 HTML을 AI 모델(OpenAI, Claude 등)의 컨텍스트로 주입하면 됩니다.
except Exception as e:
    print(f"변환 실패: {e}")

🖥️ 커맨드라인 사용법 (CLI Usage)

파이썬 코드를 작성하지 않고도 터미널(CMD, PowerShell, Bash)에서 바로 변환할 수 있습니다.

1. Python 모듈로 실행

pip install pyhwp2 후 다음과 같이 실행하세요.

# 기본 사용법 (파일명.html로 자동 저장)
python -m pyhwp.html_converter 문서.hwp

# 출력 파일명 지정
python -m pyhwp.html_converter 문서.hwp -o 결과물.html

3. 단일 HTML 파일로 변환 (CSS와 이미지 포함)

기본적으로 HWP를 HTML로 변환하면 HTML 파일, CSS 파일, 그리고 이미지 폴더(bindata)가 각각 생성됩니다. 하지만 --embed-image 옵션을 사용하면 모든 CSS와 이미지를 하나의 HTML 파일에 통합하여 관리가 훨씬 쉬워집니다.

# hwp5html 명령어 사용 (단일 파일 생성)
python -m hwp5.hwp5html --embed-image 문서.hwp --output 단일파일.html

# 또는 hwp2html 명령어 사용 (설치된 경우)
hwp5html --embed-image 문서.hwp --output 단일파일.html

이 방법은 다음과 같은 경우에 특히 유용합니다:

• 이메일로 HTML 파일을 첨부할 때
• 웹 서버 없이 로컬에서 HTML을 열어볼 때
• AI 모델에 단일 파일로 전달할 때

### 2. 단독 실행 파일 (.exe) 사용 (Windows)
Python 설치가 없는 환경에서도 `hwp2html.exe` 파일 하나만 있으면 됩니다. (`dist/` 폴더 확인)

```bash
# 그냥 드래그 앤 드롭 하거나 터미널에서 실행
hwp2html.exe 문서.hwp

# 옵션 사용
hwp2html.exe 문서.hwp -o 결과/보고서.html

🤖 AI 에이전트 활용 (MCP & Automation)

이 라이브러리는 MCP (Model Context Protocol) 서버나 Cursor, 안티그래피티(Antigravity) 같은 AI 코딩 에이전트 내에서 HWP 처리 도구로 활용할 수 있습니다.

• Before: 에이전트가 HWP 파일을 만나면 "읽을 수 없는 바이너리 파일입니다"라고 포기함.
• After: 에이전트가 내부적으로 HwpToHtmlConverter를 호출해 HTML 텍스트로 변환한 뒤, 내용을 완벽하게 이해하고 요약/분석함.

🙌 기여 요청

이 프로젝트가 Python 3로의 생명력을 얻었지만, 여전히 개선할 점은 많습니다. 우리는 이 문서가 다른 프로그래머들에게 영감이 되어, "폐쇄적인 포맷을 개방하여 AI의 영역으로 가져오는" 움직임에 동참하게 되기를 바랍니다.

오픈소스 정신을 통해, 더 많은 공공 데이터가 AI와 연결될 수 있도록 기여해 주세요.

박정준 (june9713@gmail.com 주식회사 넥스트나인 대표이사)