Metadata-Version: 2.4
Name: hwp-converter-ai
Version: 0.2.0
Summary: Python으로 HWP/HWPX 파일 생성·파싱·변환. HWP 문서를 Markdown으로, Markdown을 HWP/HWPX로.
Project-URL: Homepage, https://www.hwpsome.com
Author: HWP Converter AI
License: MIT
License-File: LICENSE
Keywords: converter,document,hancom,hwp,hwpx,markdown,한글
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: olefile>=0.47
Provides-Extra: images
Requires-Dist: pillow>=10.0; extra == 'images'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# HWP Converter AI

[![PyPI](https://img.shields.io/pypi/v/hwp-converter-ai)](https://pypi.org/project/hwp-converter-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/hwp-converter-ai)](https://pypi.org/project/hwp-converter-ai/)

Python으로 HWP/HWPX 파일을 생성·파싱·변환합니다.

> 웹에서 바로 체험하기: [https://www.hwpsome.com](https://www.hwpsome.com)

## 설치

```bash
pip install hwp-converter-ai
```

## 빠른 시작

### Markdown → HWP (한글 97~2024)

```python
from hwp_converter_ai import HwpWriter

HwpWriter().from_markdown("# 업무 보고\n\n내용입니다.", "report.hwp")
```

### Markdown → HWPX (한글 2014+)

```python
from hwp_converter_ai import HwpxGenerator

HwpxGenerator().from_markdown("# 제목\n\n**볼드** 텍스트", output_path="report.hwpx")
```

### HWP → Markdown

```python
from hwp_converter_ai import HwpParser

ir = HwpParser.parse("document.hwp")
print(ir.to_markdown())
```

### HWPX → Markdown

```python
from hwp_converter_ai import HwpxParser

ir = HwpxParser().parse("document.hwpx")
print(ir.to_markdown())
```

## 지원 기능

### Markdown 변환

| 기능 | HWP | HWPX |
|------|:---:|:----:|
| 텍스트/문단 | ✅ | ✅ |
| 제목 (H1~H3) | ✅ | ✅ |
| **볼드**/*이탤릭* | ✅ | ✅ |
| 밑줄/취소선 (파싱 방향) | ✅ | ✅ |
| 표 (테두리 포함) | ✅ | ✅ |
| 표 병합 셀 (세로/가로 병합 구조 보존) | ✅ | ✅ |
| 수식 (한컴 수식 스크립트 ↔ LaTeX) | ✅ | ✅ |
| 이미지 추출 | ✅ | ✅ |
| 리스트/글머리표 감지 | ✅ | ✅ |
| 다단(N단) 레이아웃 생성 | ✅ | ✅ |
| 긴 문서 | ✅ | ✅ |

### IR(JSON)로 보존되는 서식

Markdown이 표현하지 못하는 서식은 중간 표현 `DocumentIR`에 보존됩니다.
IR을 직접 사용하면 뷰어 렌더링·HWP 재생성 시 아래 서식이 유지됩니다.

- 문단 정렬(왼쪽·가운데·오른쪽·배분), 문단 여백·줄간격
- 글자 자간·장평, 글꼴 크기·색상
- 용지 크기·여백 (PAGE_DEF)
- 표 열 너비, 셀 배경색, 셀 테두리 스타일
- 머리말·꼬리말·쪽 번호
- 기본 도형(GSO — 직선·사각형 등)과 도형 내 텍스트
- 하이퍼링크

### v0.2.0 변경사항

- **표 병합 셀**: 세로/가로 병합(rowspan·colspan) 구조 보존 — 병합 라벨이 Markdown 표의 올바른 행에 연결
- **수식**: 한컴 수식 스크립트 ↔ LaTeX 변환 모듈 추가 (`eq_to_latex` / `latex_to_eq`), HWPX `hp:equation` 개체 생성
- **머리말·꼬리말·쪽 번호**: HWP/HWPX 파싱 지원
- **밑줄·취소선**: 파싱 지원 (Markdown 출력 시 보존)
- **글머리표(bullet) 문단**: HWP 바이너리 파싱 지원
- **다단(N단) 레이아웃**: Markdown → HWP 생성 시 단 수 지정(`columns`), 단 나누기 처리
- 문단 여백·테두리(BORDER_FILL)·셀 스타일 등 파싱 충실도 전반 개선
- 실적: 이 변환 코어로 법령·행정규칙·공문서 등 **실문서 3,700여 건**을 변환해 RAG 검색 서비스에 운영 중
- v0.2.0 회귀 검증: 공공기관 결재 문서 30건 + 공문서 서식 9종 파싱, MD→HWP/HWPX→MD 왕복 테스트 통과

## 예제

### 볼드/이탤릭 포함 문서

```python
from hwp_converter_ai import HwpWriter

md = """# 업무 보고서

일반 텍스트 **볼드 강조** 그리고 *이탤릭 참고*.

| 항목 | 상태 |
|------|------|
| 변환 | 완료 |
| 교정 | 진행중 |
"""

HwpWriter().from_markdown(md, "report.hwp")
```

### HWP 파싱 후 텍스트 추출

```python
from hwp_converter_ai import HwpParser

ir = HwpParser.parse("input.hwp")

# Markdown으로
print(ir.to_markdown())

# 순수 텍스트로 (검색/인덱싱용)
print(ir.to_plain_text())
```

### IR(중간 표현) 직접 조작

```python
from hwp_converter_ai import HwpWriter, DocumentIR, BlockNode, InlineNode, BlockType, InlineType

ir = DocumentIR(title="보고서")
ir.blocks.append(BlockNode(
    type=BlockType.HEADING, level=1,
    children=[InlineNode(type=InlineType.TEXT, text="제목")]
))
ir.blocks.append(BlockNode(
    type=BlockType.PARAGRAPH,
    children=[
        InlineNode(type=InlineType.TEXT, text="일반 "),
        InlineNode(type=InlineType.BOLD, text="강조"),
    ]
))

HwpWriter().from_ir(ir, "custom.hwp")
```

## 요구사항

- Python 3.10+
- `olefile` (자동 설치)
- 이미지 리사이즈가 필요하면: `pip install hwp-converter-ai[images]` (Pillow)

## 웹 서비스

코드 없이 브라우저에서 바로 변환해 보려면:

**[https://www.hwpsome.com](https://www.hwpsome.com)**

## 스펙 기반

[한컴 공식 HWP 5.0 문서 파일 구조](https://www.hancom.com/etc/hwpDownload.do) 및 [OWPML(KS X 6101)](https://tech.hancom.com/hwpxformat/) 표준을 기반으로 구현되었습니다.

> 본 제품은 한글과컴퓨터의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.

## 라이선스

MIT License
