dochan 0.1.0__tar.gz

dochan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dochan contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dochan-0.1.0/NOTICE

@@ -0,0 +1,8 @@
+NOTICE
+
+본 소프트웨어는 한글과컴퓨터의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발되었습니다.
+참조 스펙: 한글문서파일형식_5.0_revision1.3.pdf (2018.11.08)
+
+This software was developed with reference to the publicly available HWP document
+file format specification published by Hancom Inc.
+Reference: HWP Document File Format 5.0 revision 1.3 (2018.11.08)

dochan-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: dochan
+Version: 0.1.0
+Summary: dochan — HWP/HWPX 문서 파서, AI/LLM 최적 Markdown 변환
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/illuwa/dochan
+Project-URL: Repository, https://github.com/illuwa/dochan
+Project-URL: Issues, https://github.com/illuwa/dochan/issues
+Keywords: hwp,hwpx,parser,korean,document,markdown,ai,llm,hancom
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: olefile>=0.47
+Requires-Dist: lxml>=4.9
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3; extra == "ocr"
+Requires-Dist: Pillow>=9.0; extra == "ocr"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">dochan (독한)</h1>
+  <p align="center">
+    <strong>독한 HWP/HWPX 파서 — AI/LLM 최적 Markdown 변환</strong>
+  </p>
+  <p align="center">
+    The toughest Korean document parser. HWP/HWPX → Markdown, JSON, Plain Text.
+  </p>
+  <p align="center">
+    <a href="https://pypi.org/project/dochan/"><img src="https://img.shields.io/pypi/v/dochan?color=blue" alt="PyPI"></a>
+    <a href="https://pypi.org/project/dochan/"><img src="https://img.shields.io/pypi/pyversions/dochan" alt="Python"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  </p>
+</p>
+
+---
+
+## What is dochan?
+
+**dochan**(독한)은 한글(HWP/HWPX) 문서를 파싱하여 AI/LLM이 바로 사용할 수 있는 Markdown으로 변환하는 Python 파서입니다.
+
+- `doc` (문서) + `한` (韓, 한국) = **dochan** — "독한 파서"라는 더블 미닝
+- HWP 5.0 바이너리 + HWPX(OWPML) XML 이중 지원
+- 155개 실문서로 검증, 평균 96.5점, 공개가능한 문서로 계속 학습시켜 개선할 예정
+
+```python
+from dochan import Dochan
+
+doc = Dochan("공문서.hwp")
+print(doc.to_markdown())
+```
+
+## Features
+
+| 기능 | 설명 |
+|------|------|
+| **HWP + HWPX** | 바이너리(.hwp)와 XML(.hwpx) 모두 자동 감지 파싱 |
+| **Markdown 출력** | 제목, 표, 서식(bold/italic), 수식까지 AI가 바로 쓸 수 있는 Markdown |
+| **표 파싱** | 셀 병합, 중첩 표, 좌표 배치 지원 |
+| **서식 보존** | CharShape 기반 bold/italic/글자크기 → TextRun 연결 |
+| **제목 자동 감지** | Style 이름 + 글자 크기 기반 heading 레벨 판별 |
+| **수식 LaTeX** | HWP 수식 스크립트 → LaTeX 기본 변환 |
+| **JSON / Plain Text** | Markdown 외 구조화 JSON, 플레인 텍스트 출력 |
+| **OCR (선택)** | Tesseract 연동, 이미지 속 텍스트 추출 |
+| **CLI** | `dochan convert 문서.hwp` 한 줄로 변환 |
+| **배치 처리** | 디렉토리 단위 병렬 변환 |
+| **보안** | Zip Bomb, XXE, Path Traversal, 메모리 폭발 방어 |
+
+## Installation
+
+```bash
+pip install dochan
+```
+
+OCR 기능이 필요한 경우:
+```bash
+pip install dochan[ocr]
+brew install tesseract tesseract-lang  # macOS
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from dochan import Dochan
+
+# HWP 또는 HWPX — 자동 감지
+doc = Dochan("보고서.hwp")
+
+# AI/LLM용 Markdown
+markdown = doc.to_markdown()
+
+# 구조화 JSON
+json_str = doc.to_json()
+
+# 플레인 텍스트
+text = doc.to_plain_text()
+
+# 요소별 접근
+for table in doc.find_all('table'):
+    print(f"표: {table.row_count}행 x {table.col_count}열")
+
+for eq in doc.find_all('equation'):
+    print(f"수식: {eq.latex}")
+
+# 메타데이터
+print(doc.metadata)
+```
+
+### CLI
+
+```bash
+# Markdown 변환 (stdout)
+dochan convert 문서.hwp
+
+# 파일로 저장
+dochan convert 문서.hwp -o output.md
+
+# JSON 출력
+dochan convert 문서.hwpx --format json
+
+# 디렉토리 일괄 변환
+dochan batch input_dir/ output_dir/ --format markdown --workers 4
+
+# 문서 정보
+dochan info 문서.hwp
+```
+
+### OCR (이미지 속 텍스트 추출)
+
+```python
+doc = Dochan("이미지포함문서.hwpx", ocr=True)
+print(doc.to_markdown())  # 이미지 속 텍스트도 포함
+```
+
+## Output Examples
+
+### Input: 한글 공문서 (.hwp)
+
+### Output: Markdown
+
+```markdown
+# **사내 규정집**
+
+| 연번 | 내용 | 일자 |
+| --- | --- | --- |
+| 1 | 제정 | 2020. 3. 1. |
+| 2 | 개정 | 2024. 9.15. |
+
+### **제1장 총칙**
+
+**제1조(목적)** 이 규정은 회사 직원의 복무에 관한 사항을 정함을
+목적으로 한다.
+```
+
+## Supported Elements
+
+| 요소 | HWP (바이너리) | HWPX (XML) |
+|------|:-:|:-:|
+| 텍스트 | ✅ | ✅ |
+| 표 (단순) | ✅ | ✅ |
+| 표 (셀 병합) | ✅ | ✅ |
+| 표 (중첩) | ✅ | ✅ |
+| 서식 (bold/italic) | ✅ | ✅ |
+| 제목 감지 | ✅ | ✅ |
+| 수식 | ✅ | ✅ |
+| 이미지 참조 | ✅ | ✅ |
+| 이미지 OCR | ✅ | ✅ |
+| 머리글/바닥글 | ✅ | ⬜ |
+| 각주/미주 | ✅ | ⬜ |
+| 암호화 문서 | ⬜ | — |
+
+✅ 지원 &nbsp; ⬜ 미지원 &nbsp; — 해당 없음
+
+## Architecture
+
+```
+dochan/
+├── reader.py          # 통합 진입점 (Dochan 클래스)
+├── cli.py             # CLI 도구
+├── hwp/               # HWP 5.0 바이너리 파서
+│   ├── header.py      #   FileHeader (256바이트)
+│   ├── doc_info.py    #   DocInfo (서식/스타일)
+│   ├── section.py     #   섹션 (레코드 트리 → 모델)
+│   └── records/       #   개별 레코드 파서
+├── hwpx/              # HWPX (OWPML) XML 파서
+│   └── parser.py
+├── model/             # Document 모델
+│   ├── document.py    #   Document, Section, Paragraph
+│   ├── table.py       #   Table, Cell
+│   └── equation.py    #   Equation (LaTeX 변환)
+├── output/            # 출력 포맷
+│   ├── markdown.py    #   Markdown (AI/LLM 최적)
+│   ├── json_out.py    #   구조화 JSON
+│   └── plain_text.py  #   플레인 텍스트
+└── utils/             # 유틸리티
+    ├── ocr.py         #   Tesseract OCR
+    └── safe_decompress.py  # Zip Bomb 방어
+```
+
+## Security
+
+dochan은 신뢰할 수 없는 문서도 안전하게 처리합니다:
+
+- **Zip Bomb 방어**: zlib/ZIP 해제 크기 제한 (200MB)
+- **XXE 차단**: XML 외부 엔티티 해석 비활성화
+- **Path Traversal 방지**: 배치 처리 시 경로 탈출 차단
+- **메모리 제한**: 표 크기 1M셀, 재귀 깊이 100 제한
+- **입력 검증**: FileHeader/스트림명/바이너리 바운드 체크
+
+## Contributing
+
+기여를 환영합니다! Issues, Pull Requests 모두 열려 있습니다.
+
+```bash
+# 개발 환경 설정
+git clone https://github.com/illuwa/dochan.git
+cd dochan
+pip install -e ".[dev]"
+python -m pytest dochan/tests/
+```
+
+## Acknowledgments
+
+> [kordoc](https://github.com/chrisryugj/kordoc)를 보고 자극받아 만들었습니다.
+
+dochan은 다음 프로젝트와 자료를 기반으로 개발되었습니다:
+
+**스펙 참조**
+- [한글과컴퓨터](https://www.hancom.com/) — HWP 문서 파일 형식 5.0 공개 스펙 (revision 1.3, 2018)
+- [OWPML (KS X 6101:2011)](https://www.kssn.net/) — HWPX 국가 표준
+
+**오픈소스**
+- [olefile](https://github.com/decalage2/olefile) — OLE2 파일 파싱 (Philippe Lagadec, BSD)
+- [lxml](https://lxml.de/) — XML 파싱 (BSD)
+- [pdfplumber](https://github.com/jsvine/pdfplumber) — 품질 검증용 PDF 추출 (MIT)
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) — 이미지 텍스트 추출 (Apache 2.0)
+
+**선행 연구**
+- [hwplib](https://github.com/neolord0/hwplib) (Java) — HWP 레코드 구조 참조
+- [hwp.js](https://github.com/niceeee/hwp.js) — 레코드 트리 구축 참조
+- [pyhwp](https://github.com/mete0r/pyhwp) — Python HWP 파서 선구자
+
+## License
+
+[MIT License](LICENSE)
+
+본 소프트웨어는 한글과컴퓨터의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발되었습니다. 자세한 내용은 [NOTICE](NOTICE) 파일을 참조하세요.

dochan-0.1.0/README.md

@@ -0,0 +1,229 @@
+<p align="center">
+  <h1 align="center">dochan (독한)</h1>
+  <p align="center">
+    <strong>독한 HWP/HWPX 파서 — AI/LLM 최적 Markdown 변환</strong>
+  </p>
+  <p align="center">
+    The toughest Korean document parser. HWP/HWPX → Markdown, JSON, Plain Text.
+  </p>
+  <p align="center">
+    <a href="https://pypi.org/project/dochan/"><img src="https://img.shields.io/pypi/v/dochan?color=blue" alt="PyPI"></a>
+    <a href="https://pypi.org/project/dochan/"><img src="https://img.shields.io/pypi/pyversions/dochan" alt="Python"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  </p>
+</p>
+
+---
+
+## What is dochan?
+
+**dochan**(독한)은 한글(HWP/HWPX) 문서를 파싱하여 AI/LLM이 바로 사용할 수 있는 Markdown으로 변환하는 Python 파서입니다.
+
+- `doc` (문서) + `한` (韓, 한국) = **dochan** — "독한 파서"라는 더블 미닝
+- HWP 5.0 바이너리 + HWPX(OWPML) XML 이중 지원
+- 155개 실문서로 검증, 평균 96.5점, 공개가능한 문서로 계속 학습시켜 개선할 예정
+
+```python
+from dochan import Dochan
+
+doc = Dochan("공문서.hwp")
+print(doc.to_markdown())
+```
+
+## Features
+
+| 기능 | 설명 |
+|------|------|
+| **HWP + HWPX** | 바이너리(.hwp)와 XML(.hwpx) 모두 자동 감지 파싱 |
+| **Markdown 출력** | 제목, 표, 서식(bold/italic), 수식까지 AI가 바로 쓸 수 있는 Markdown |
+| **표 파싱** | 셀 병합, 중첩 표, 좌표 배치 지원 |
+| **서식 보존** | CharShape 기반 bold/italic/글자크기 → TextRun 연결 |
+| **제목 자동 감지** | Style 이름 + 글자 크기 기반 heading 레벨 판별 |
+| **수식 LaTeX** | HWP 수식 스크립트 → LaTeX 기본 변환 |
+| **JSON / Plain Text** | Markdown 외 구조화 JSON, 플레인 텍스트 출력 |
+| **OCR (선택)** | Tesseract 연동, 이미지 속 텍스트 추출 |
+| **CLI** | `dochan convert 문서.hwp` 한 줄로 변환 |
+| **배치 처리** | 디렉토리 단위 병렬 변환 |
+| **보안** | Zip Bomb, XXE, Path Traversal, 메모리 폭발 방어 |
+
+## Installation
+
+```bash
+pip install dochan
+```
+
+OCR 기능이 필요한 경우:
+```bash
+pip install dochan[ocr]
+brew install tesseract tesseract-lang  # macOS
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from dochan import Dochan
+
+# HWP 또는 HWPX — 자동 감지
+doc = Dochan("보고서.hwp")
+
+# AI/LLM용 Markdown
+markdown = doc.to_markdown()
+
+# 구조화 JSON
+json_str = doc.to_json()
+
+# 플레인 텍스트
+text = doc.to_plain_text()
+
+# 요소별 접근
+for table in doc.find_all('table'):
+    print(f"표: {table.row_count}행 x {table.col_count}열")
+
+for eq in doc.find_all('equation'):
+    print(f"수식: {eq.latex}")
+
+# 메타데이터
+print(doc.metadata)
+```
+
+### CLI
+
+```bash
+# Markdown 변환 (stdout)
+dochan convert 문서.hwp
+
+# 파일로 저장
+dochan convert 문서.hwp -o output.md
+
+# JSON 출력
+dochan convert 문서.hwpx --format json
+
+# 디렉토리 일괄 변환
+dochan batch input_dir/ output_dir/ --format markdown --workers 4
+
+# 문서 정보
+dochan info 문서.hwp
+```
+
+### OCR (이미지 속 텍스트 추출)
+
+```python
+doc = Dochan("이미지포함문서.hwpx", ocr=True)
+print(doc.to_markdown())  # 이미지 속 텍스트도 포함
+```
+
+## Output Examples
+
+### Input: 한글 공문서 (.hwp)
+
+### Output: Markdown
+
+```markdown
+# **사내 규정집**
+
+| 연번 | 내용 | 일자 |
+| --- | --- | --- |
+| 1 | 제정 | 2020. 3. 1. |
+| 2 | 개정 | 2024. 9.15. |
+
+### **제1장 총칙**
+
+**제1조(목적)** 이 규정은 회사 직원의 복무에 관한 사항을 정함을
+목적으로 한다.
+```
+
+## Supported Elements
+
+| 요소 | HWP (바이너리) | HWPX (XML) |
+|------|:-:|:-:|
+| 텍스트 | ✅ | ✅ |
+| 표 (단순) | ✅ | ✅ |
+| 표 (셀 병합) | ✅ | ✅ |
+| 표 (중첩) | ✅ | ✅ |
+| 서식 (bold/italic) | ✅ | ✅ |
+| 제목 감지 | ✅ | ✅ |
+| 수식 | ✅ | ✅ |
+| 이미지 참조 | ✅ | ✅ |
+| 이미지 OCR | ✅ | ✅ |
+| 머리글/바닥글 | ✅ | ⬜ |
+| 각주/미주 | ✅ | ⬜ |
+| 암호화 문서 | ⬜ | — |
+
+✅ 지원 &nbsp; ⬜ 미지원 &nbsp; — 해당 없음
+
+## Architecture
+
+```
+dochan/
+├── reader.py          # 통합 진입점 (Dochan 클래스)
+├── cli.py             # CLI 도구
+├── hwp/               # HWP 5.0 바이너리 파서
+│   ├── header.py      #   FileHeader (256바이트)
+│   ├── doc_info.py    #   DocInfo (서식/스타일)
+│   ├── section.py     #   섹션 (레코드 트리 → 모델)
+│   └── records/       #   개별 레코드 파서
+├── hwpx/              # HWPX (OWPML) XML 파서
+│   └── parser.py
+├── model/             # Document 모델
+│   ├── document.py    #   Document, Section, Paragraph
+│   ├── table.py       #   Table, Cell
+│   └── equation.py    #   Equation (LaTeX 변환)
+├── output/            # 출력 포맷
+│   ├── markdown.py    #   Markdown (AI/LLM 최적)
+│   ├── json_out.py    #   구조화 JSON
+│   └── plain_text.py  #   플레인 텍스트
+└── utils/             # 유틸리티
+    ├── ocr.py         #   Tesseract OCR
+    └── safe_decompress.py  # Zip Bomb 방어
+```
+
+## Security
+
+dochan은 신뢰할 수 없는 문서도 안전하게 처리합니다:
+
+- **Zip Bomb 방어**: zlib/ZIP 해제 크기 제한 (200MB)
+- **XXE 차단**: XML 외부 엔티티 해석 비활성화
+- **Path Traversal 방지**: 배치 처리 시 경로 탈출 차단
+- **메모리 제한**: 표 크기 1M셀, 재귀 깊이 100 제한
+- **입력 검증**: FileHeader/스트림명/바이너리 바운드 체크
+
+## Contributing
+
+기여를 환영합니다! Issues, Pull Requests 모두 열려 있습니다.
+
+```bash
+# 개발 환경 설정
+git clone https://github.com/illuwa/dochan.git
+cd dochan
+pip install -e ".[dev]"
+python -m pytest dochan/tests/
+```
+
+## Acknowledgments
+
+> [kordoc](https://github.com/chrisryugj/kordoc)를 보고 자극받아 만들었습니다.
+
+dochan은 다음 프로젝트와 자료를 기반으로 개발되었습니다:
+
+**스펙 참조**
+- [한글과컴퓨터](https://www.hancom.com/) — HWP 문서 파일 형식 5.0 공개 스펙 (revision 1.3, 2018)
+- [OWPML (KS X 6101:2011)](https://www.kssn.net/) — HWPX 국가 표준
+
+**오픈소스**
+- [olefile](https://github.com/decalage2/olefile) — OLE2 파일 파싱 (Philippe Lagadec, BSD)
+- [lxml](https://lxml.de/) — XML 파싱 (BSD)
+- [pdfplumber](https://github.com/jsvine/pdfplumber) — 품질 검증용 PDF 추출 (MIT)
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) — 이미지 텍스트 추출 (Apache 2.0)
+
+**선행 연구**
+- [hwplib](https://github.com/neolord0/hwplib) (Java) — HWP 레코드 구조 참조
+- [hwp.js](https://github.com/niceeee/hwp.js) — 레코드 트리 구축 참조
+- [pyhwp](https://github.com/mete0r/pyhwp) — Python HWP 파서 선구자
+
+## License
+
+[MIT License](LICENSE)
+
+본 소프트웨어는 한글과컴퓨터의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발되었습니다. 자세한 내용은 [NOTICE](NOTICE) 파일을 참조하세요.

dochan-0.1.0/dochan/__init__.py

@@ -0,0 +1,9 @@
+"""dochan — HWP/HWPX 문서 파서, AI/LLM 최적 Markdown 변환"""
+__version__ = "0.1.0"
+
+from .reader import Dochan
+
+# 하위 호환 별칭
+HWPReader = Dochan
+
+__all__ = ['Dochan', 'HWPReader']

dochan-0.1.0/dochan/batch.py

@@ -0,0 +1,154 @@
+"""
+batch.py — 배치 처리
+다수 HWP 파일의 병렬 변환
+"""
+
+import os
+import logging
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List
+
+logger = logging.getLogger('dochan')
+
+
+@dataclass
+class BatchResult:
+    """단일 파일 처리 결과"""
+    file_path: str = ""
+    success: bool = False
+    output_path: str = ""
+    error_count: int = 0
+    errors: List[str] = field(default_factory=list)
+
+
+@dataclass
+class BatchSummary:
+    """배치 처리 전체 요약"""
+    total: int = 0
+    success: int = 0
+    failed: int = 0
+    results: List[BatchResult] = field(default_factory=list)
+
+    @property
+    def success_rate(self) -> float:
+        return self.success / max(self.total, 1) * 100
+
+
+def _process_single(file_path: str, output_dir: str, output_format: str) -> BatchResult:
+    """단일 파일 처리 (별도 프로세스에서 실행)"""
+    from .reader import Dochan
+
+    result = BatchResult(file_path=file_path)
+
+    try:
+        reader = Dochan(file_path)
+
+        # 출력 파일명 생성
+        base_name = os.path.splitext(os.path.basename(file_path))[0]
+        ext_map = {'markdown': '.md', 'json': '.json', 'text': '.txt'}
+        ext = ext_map.get(output_format, '.md')
+        output_path = os.path.join(output_dir, base_name + ext)
+
+        # 변환
+        if output_format == 'json':
+            content = reader.to_json()
+        elif output_format == 'text':
+            content = reader.to_plain_text()
+        else:
+            content = reader.to_markdown()
+
+        # 저장
+        with open(output_path, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+        result.success = True
+        result.output_path = output_path
+        result.errors = reader.errors
+        result.error_count = len(reader.errors)
+
+    except Exception as e:
+        result.success = False
+        result.errors = [str(e)]
+        result.error_count = 1
+
+    return result
+
+
+def batch_convert(
+    input_dir: str,
+    output_dir: str,
+    output_format: str = 'markdown',
+    max_workers: int = 4,
+    extensions: tuple = ('.hwp', '.hwpx'),
+) -> BatchSummary:
+    """
+    디렉토리 내 HWP 파일 일괄 변환
+
+    Args:
+        input_dir: 입력 디렉토리
+        output_dir: 출력 디렉토리
+        output_format: 'markdown', 'json', 'text'
+        max_workers: 병렬 워커 수
+        extensions: 처리할 확장자
+
+    Returns:
+        BatchSummary
+    """
+    # output_dir 경로 검증
+    try:
+        Path(output_dir).resolve().relative_to(Path(os.getcwd()).resolve())
+    except ValueError:
+        pass  # output_dir가 cwd 밖이어도 허용하되, 아래에서 symlink 공격 방지
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    # 파일 수집
+    files = []
+    resolved_input = Path(input_dir).resolve()
+    for root, _, filenames in os.walk(input_dir):
+        for fn in filenames:
+            if any(fn.lower().endswith(ext) for ext in extensions):
+                full_path = os.path.join(root, fn)
+                # Path traversal 방지: 실제 경로가 input_dir 내부인지 검증
+                try:
+                    Path(full_path).resolve().relative_to(resolved_input)
+                except ValueError:
+                    logger.warning(f"경로 이탈 감지, 건너뜀: {full_path}")
+                    continue
+                files.append(full_path)
+
+    summary = BatchSummary(total=len(files))
+    logger.info(f"배치 시작: {len(files)}개 파일, {max_workers} 워커")
+
+    # 병렬 처리
+    with ProcessPoolExecutor(max_workers=max_workers) as executor:
+        futures = {
+            executor.submit(_process_single, f, output_dir, output_format): f
+            for f in files
+        }
+
+        for future in as_completed(futures):
+            file_path = futures[future]
+            try:
+                result = future.result()
+                summary.results.append(result)
+                if result.success:
+                    summary.success += 1
+                    logger.info(f"✓ {os.path.basename(file_path)}")
+                else:
+                    summary.failed += 1
+                    logger.error(f"✗ {os.path.basename(file_path)}: {result.errors}")
+            except Exception as e:
+                summary.failed += 1
+                summary.results.append(BatchResult(
+                    file_path=file_path,
+                    success=False,
+                    errors=[str(e)],
+                    error_count=1,
+                ))
+                logger.error(f"✗ {os.path.basename(file_path)}: {e}")
+
+    logger.info(f"배치 완료: {summary.success}/{summary.total} 성공 ({summary.success_rate:.1f}%)")
+    return summary