document-adapter 0.7.1__tar.gz → 0.7.2__tar.gz

{document_adapter-0.7.1/document_adapter.egg-info → document_adapter-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: document-adapter
-Version: 0.7.1
+Version: 0.7.2
 Summary: LLM-friendly document template editing (DOCX/PPTX/HWPX) with MCP server and Claude API tool-use support
 Author-email: Son Seongjun <sonsj97@plateer.com>
 License: MIT
@@ -127,13 +127,46 @@ doc.append_to_cell(table_index=2, row=0, col=0, value="홍길동")
 cell = doc.get_cell(table_index=1, row=3, col=2)
 print(cell.text, cell.is_anchor, cell.span, cell.nested_table_indices)
 
-# DOCX/HWPX는 행 추가 지원
+# DOCX/PPTX/HWPX 전부 행 추가 지원 (v0.5+)
 doc.append_row(1, ["새 항목", "값"])
 
 doc.save("checklist_filled.docx")
 doc.close()
 ```
 
+### 라벨 기반 일괄 채우기 (v0.7+)
+
+LLM 이 좌표 `(table_index, row, col)` 를 직접 계산하지 않고 "접수번호", "성명" 같은 사람이 읽는 라벨 key-value 로 양식을 채울 수 있습니다.
+
+```python
+doc = load("form.hwpx")
+result = doc.fill_form({
+    "접수번호": "2026-0001",
+    "성 명":   "홍길동",
+    "주 소":   "서울시 강남구",
+    "금융회사": "국민은행",
+})
+# → {"filled": [...], "not_found": [...], "ambiguous": [...]}
+doc.save()
+doc.close()
+```
+
+- `auto` (기본): 라벨 셀 오른쪽 → 아래 → 같은 셀 순으로 값 셀 탐색. 보수적이라 기존 값 있는 셀은 다른 라벨로 간주하고 skip.
+- `direction="right"` 명시: 라벨 오른쪽 셀을 **덮어쓰기** (예시값 있는 PPTX 템플릿 등).
+- **Dot-path 섹션 지정**: 동일 라벨이 여러 섹션에 있으면 `"피해자.금액"`, `"지급정지요청계좌.금액"` 처럼 섹션 힌트 부여. `ambiguous` 반환 시 `hint` 필드에 예시 제공.
+- **팁**: 한 양식의 관련 라벨을 한 번에 dict 로 넘기면 라벨끼리 서로 보호되어 오염을 방지합니다.
+
+### 셀 크기 메타 (v0.6+)
+
+`get_tables()`가 `column_widths_cm` / `row_heights_cm` 를, `get_cell()`이 `width_cm` / `height_cm` / `char_count` 를 반환해 LLM이 **좁은 셀에 긴 텍스트를 넣어 오버플로 되는 것을 사전에 판단**할 수 있습니다.
+
+```python
+cell = doc.get_cell(table_index=0, row=0, col=0)
+print(cell.width_cm, cell.char_count)  # 1.7cm, 4자 — 작은 배지
+```
+
+DOCX/PPTX는 EMU → cm, HWPX는 HU → cm 자동 환산 (1자리 반올림).
+
 확장자로 자동 분기되므로 `.pptx` / `.hwpx`도 동일한 API를 사용합니다.
 
 ### 병합 셀 인지 동작 (v0.2+)
@@ -185,7 +218,7 @@ document-adapter-mcp
 }
 ```
 
-재시작하면 Claude Desktop에서 아래 4개 도구를 사용할 수 있습니다.
+재시작하면 Claude Desktop에서 아래 7개 도구를 사용할 수 있습니다.
 
 ### Claude Code 설정
 
@@ -227,12 +260,13 @@ resp = client.messages.create(
 
 | 도구 | 설명 |
 |---|---|
-| `inspect_document` | 문서 구조(placeholders, tables)를 JSON으로 반환. **항상 첫 호출로 사용** |
+| `inspect_document` | 문서 구조(placeholders, tables + `column_widths_cm`/`row_heights_cm`)를 JSON으로 반환. **항상 첫 호출로 사용** |
 | `render_template` | `{{key}}`를 context dict 값으로 치환해 새 파일 저장 |
-| `get_cell` | 셀 전체 텍스트 + 병합/중첩 메타 반환 (preview의 40자 잘림 없이) |
+| `get_cell` | 셀 전체 텍스트 + 병합/중첩 메타 + `width_cm`/`height_cm`/`char_count` 반환 |
 | `set_cell` | 특정 표의 `(row, col)` 셀 값 교체 (병합 anchor만) |
 | `append_to_cell` | 기존 텍스트 뒤에 값 덧붙임 (라벨 유지용, 예: `"성 명"` → `"성 명  홍길동"`) |
-| `append_row` | 표 끝에 새 행 추가 (DOCX/HWPX 지원) |
+| `fill_form` (v0.7+) | **라벨 이름**으로 일괄 채우기. 좌표 계산 없이 `{"접수번호": "...", "성명": "..."}` dict. dot-path 섹션 해소 지원 |
+| `append_row` | 표 끝에 새 행 추가 (DOCX/PPTX/HWPX 전부 지원, v0.5+) |
 
 ### `inspect_document` 반환 예시 (v0.2+)
 
@@ -294,13 +328,12 @@ LLM은 이 preview를 보고 **"빈 셀이 어디 있는지 / 어떤 값을 넣
 
 loop / if / filter는 지원하지 않습니다. PPTX는 placeholder가 여러 `run`으로 쪼개질 수 있어, 어댑터가 paragraph 전체 텍스트를 재조립한 뒤 첫 `run`에 다시 담는 방식으로 처리합니다 (서식 일부 손실 가능).
 
-## 내장된 버그 회피
+## 내장된 버그 회피 / 백엔드 선택
 
 | 포맷 | 문제 | 어댑터의 처리 |
 |---|---|---|
-| HWPX | `python-hwpx 2.9.0`의 `set_cell_text()`가 빈 셀에서 lxml/ElementTree 혼용 `TypeError` 발생 | `paragraphs[0].text = value` 직접 할당으로 우회 |
-| HWPX | `replace_text_in_runs()`가 한글 공백이 run으로 쪼개진 경우 매칭 실패 | 위치 기반 API만 사용 |
-| HWPX | `manifest fallback` 경고 로그가 과도하게 출력됨 | `logging.getLogger("hwpx")` 레벨을 `ERROR`로 조정 |
+| HWPX | `python-hwpx` 가 Non-Commercial License → 상용 배포 블로커 | **v0.4.0 부터 자체 `hwpx_core` 모듈** (zipfile + lxml) 로 교체. 런타임에 `python-hwpx` 불필요. 테스트 fixture 생성에만 사용 (dev extras) |
+| PPTX | `python-pptx` 에 공식 `add_row` API 없음 (issue #86, 2014년부터 open) | **v0.5.0 부터 자체 lxml 구현** (`<a:tr>` deepcopy 패턴) |
 | PPTX | placeholder가 여러 `run`으로 쪼개져 단순 `run.text` 치환이 실패 | paragraph 전체 재조립 |
 | DOCX | `docxtpl`의 `{%tr%}`를 같은 행에 두면 파싱 에러 | README에 배치 규칙 명시 |
 
@@ -309,15 +342,20 @@ loop / if / filter는 지원하지 않습니다. PPTX는 placeholder가 여러 `
 ```
 document_adapter/
 ├── __init__.py        # load() dispatcher
-├── base.py            # DocumentAdapter ABC, TableSchema, DocumentSchema
+├── base.py            # DocumentAdapter ABC + fill_form + dataclasses
 ├── docx_adapter.py    # DocxAdapter
-├── pptx_adapter.py    # PptxAdapter
-├── hwpx_adapter.py    # HwpxAdapter (버그 회피 포함)
-├── tools.py           # Tool 정의 + call_tool dispatcher
+├── pptx_adapter.py    # PptxAdapter (append_row 자체 구현 포함)
+├── hwpx_adapter.py    # HwpxAdapter (hwpx_core 기반)
+├── hwpx_core/         # 자체 HWPX 패키지 (v0.4+)
+│   ├── constants.py
+│   ├── package.py     # ZIP + dirty XML 관리
+│   ├── grid.py        # iter_grid, table_shape
+│   └── paragraph.py   # run-level 편집 헬퍼
+├── tools.py           # 7개 MCP 도구 정의 + call_tool dispatcher
 └── mcp_server.py      # MCP stdio server
 
 examples/
-└── claude_api_example.py
+└── claude_api_example.py    # Claude API Tool Use 에이전트 루프
 ```
 
 ## 라이선스
@@ -326,8 +364,15 @@ MIT
 
 ## Credits
 
-- [`python-docx`](https://github.com/python-openxml/python-docx)
-- [`docxtpl`](https://github.com/elapouya/python-docx-template)
-- [`python-pptx`](https://github.com/scanny/python-pptx)
-- [`python-hwpx`](https://github.com/airmang/python-hwpx)
-- [`mcp`](https://github.com/modelcontextprotocol/python-sdk)
+**런타임 의존성** (전부 허용형 OSS):
+- [`python-docx`](https://github.com/python-openxml/python-docx) — MIT
+- [`docxtpl`](https://github.com/elapouya/python-docx-template) — LGPL-2.1
+- [`python-pptx`](https://github.com/scanny/python-pptx) — MIT
+- [`lxml`](https://lxml.de/) — BSD
+- [`mcp`](https://github.com/modelcontextprotocol/python-sdk) — MIT
+
+**코드 참조**:
+- [`xgen-doc2chunk`](https://github.com/PlateerLab/xgen-doc2chunk) (Apache-2.0) — HWPX table grid 파싱 로직 차용 (`NOTICE` 참조)
+
+**Dev 전용** (fixture 생성에만 사용):
+- [`python-hwpx`](https://github.com/airmang/python-hwpx) — Non-Commercial License (v0.4.0 부터 런타임 의존성 제거)

{document_adapter-0.7.1 → document_adapter-0.7.2}/README.md

@@ -86,13 +86,46 @@ doc.append_to_cell(table_index=2, row=0, col=0, value="홍길동")
 cell = doc.get_cell(table_index=1, row=3, col=2)
 print(cell.text, cell.is_anchor, cell.span, cell.nested_table_indices)
 
-# DOCX/HWPX는 행 추가 지원
+# DOCX/PPTX/HWPX 전부 행 추가 지원 (v0.5+)
 doc.append_row(1, ["새 항목", "값"])
 
 doc.save("checklist_filled.docx")
 doc.close()
 ```
 
+### 라벨 기반 일괄 채우기 (v0.7+)
+
+LLM 이 좌표 `(table_index, row, col)` 를 직접 계산하지 않고 "접수번호", "성명" 같은 사람이 읽는 라벨 key-value 로 양식을 채울 수 있습니다.
+
+```python
+doc = load("form.hwpx")
+result = doc.fill_form({
+    "접수번호": "2026-0001",
+    "성 명":   "홍길동",
+    "주 소":   "서울시 강남구",
+    "금융회사": "국민은행",
+})
+# → {"filled": [...], "not_found": [...], "ambiguous": [...]}
+doc.save()
+doc.close()
+```
+
+- `auto` (기본): 라벨 셀 오른쪽 → 아래 → 같은 셀 순으로 값 셀 탐색. 보수적이라 기존 값 있는 셀은 다른 라벨로 간주하고 skip.
+- `direction="right"` 명시: 라벨 오른쪽 셀을 **덮어쓰기** (예시값 있는 PPTX 템플릿 등).
+- **Dot-path 섹션 지정**: 동일 라벨이 여러 섹션에 있으면 `"피해자.금액"`, `"지급정지요청계좌.금액"` 처럼 섹션 힌트 부여. `ambiguous` 반환 시 `hint` 필드에 예시 제공.
+- **팁**: 한 양식의 관련 라벨을 한 번에 dict 로 넘기면 라벨끼리 서로 보호되어 오염을 방지합니다.
+
+### 셀 크기 메타 (v0.6+)
+
+`get_tables()`가 `column_widths_cm` / `row_heights_cm` 를, `get_cell()`이 `width_cm` / `height_cm` / `char_count` 를 반환해 LLM이 **좁은 셀에 긴 텍스트를 넣어 오버플로 되는 것을 사전에 판단**할 수 있습니다.
+
+```python
+cell = doc.get_cell(table_index=0, row=0, col=0)
+print(cell.width_cm, cell.char_count)  # 1.7cm, 4자 — 작은 배지
+```
+
+DOCX/PPTX는 EMU → cm, HWPX는 HU → cm 자동 환산 (1자리 반올림).
+
 확장자로 자동 분기되므로 `.pptx` / `.hwpx`도 동일한 API를 사용합니다.
 
 ### 병합 셀 인지 동작 (v0.2+)
@@ -144,7 +177,7 @@ document-adapter-mcp
 }
 ```
 
-재시작하면 Claude Desktop에서 아래 4개 도구를 사용할 수 있습니다.
+재시작하면 Claude Desktop에서 아래 7개 도구를 사용할 수 있습니다.
 
 ### Claude Code 설정
 
@@ -186,12 +219,13 @@ resp = client.messages.create(
 
 | 도구 | 설명 |
 |---|---|
-| `inspect_document` | 문서 구조(placeholders, tables)를 JSON으로 반환. **항상 첫 호출로 사용** |
+| `inspect_document` | 문서 구조(placeholders, tables + `column_widths_cm`/`row_heights_cm`)를 JSON으로 반환. **항상 첫 호출로 사용** |
 | `render_template` | `{{key}}`를 context dict 값으로 치환해 새 파일 저장 |
-| `get_cell` | 셀 전체 텍스트 + 병합/중첩 메타 반환 (preview의 40자 잘림 없이) |
+| `get_cell` | 셀 전체 텍스트 + 병합/중첩 메타 + `width_cm`/`height_cm`/`char_count` 반환 |
 | `set_cell` | 특정 표의 `(row, col)` 셀 값 교체 (병합 anchor만) |
 | `append_to_cell` | 기존 텍스트 뒤에 값 덧붙임 (라벨 유지용, 예: `"성 명"` → `"성 명  홍길동"`) |
-| `append_row` | 표 끝에 새 행 추가 (DOCX/HWPX 지원) |
+| `fill_form` (v0.7+) | **라벨 이름**으로 일괄 채우기. 좌표 계산 없이 `{"접수번호": "...", "성명": "..."}` dict. dot-path 섹션 해소 지원 |
+| `append_row` | 표 끝에 새 행 추가 (DOCX/PPTX/HWPX 전부 지원, v0.5+) |
 
 ### `inspect_document` 반환 예시 (v0.2+)
 
@@ -253,13 +287,12 @@ LLM은 이 preview를 보고 **"빈 셀이 어디 있는지 / 어떤 값을 넣
 
 loop / if / filter는 지원하지 않습니다. PPTX는 placeholder가 여러 `run`으로 쪼개질 수 있어, 어댑터가 paragraph 전체 텍스트를 재조립한 뒤 첫 `run`에 다시 담는 방식으로 처리합니다 (서식 일부 손실 가능).
 
-## 내장된 버그 회피
+## 내장된 버그 회피 / 백엔드 선택
 
 | 포맷 | 문제 | 어댑터의 처리 |
 |---|---|---|
-| HWPX | `python-hwpx 2.9.0`의 `set_cell_text()`가 빈 셀에서 lxml/ElementTree 혼용 `TypeError` 발생 | `paragraphs[0].text = value` 직접 할당으로 우회 |
-| HWPX | `replace_text_in_runs()`가 한글 공백이 run으로 쪼개진 경우 매칭 실패 | 위치 기반 API만 사용 |
-| HWPX | `manifest fallback` 경고 로그가 과도하게 출력됨 | `logging.getLogger("hwpx")` 레벨을 `ERROR`로 조정 |
+| HWPX | `python-hwpx` 가 Non-Commercial License → 상용 배포 블로커 | **v0.4.0 부터 자체 `hwpx_core` 모듈** (zipfile + lxml) 로 교체. 런타임에 `python-hwpx` 불필요. 테스트 fixture 생성에만 사용 (dev extras) |
+| PPTX | `python-pptx` 에 공식 `add_row` API 없음 (issue #86, 2014년부터 open) | **v0.5.0 부터 자체 lxml 구현** (`<a:tr>` deepcopy 패턴) |
 | PPTX | placeholder가 여러 `run`으로 쪼개져 단순 `run.text` 치환이 실패 | paragraph 전체 재조립 |
 | DOCX | `docxtpl`의 `{%tr%}`를 같은 행에 두면 파싱 에러 | README에 배치 규칙 명시 |
 
@@ -268,15 +301,20 @@ loop / if / filter는 지원하지 않습니다. PPTX는 placeholder가 여러 `
 ```
 document_adapter/
 ├── __init__.py        # load() dispatcher
-├── base.py            # DocumentAdapter ABC, TableSchema, DocumentSchema
+├── base.py            # DocumentAdapter ABC + fill_form + dataclasses
 ├── docx_adapter.py    # DocxAdapter
-├── pptx_adapter.py    # PptxAdapter
-├── hwpx_adapter.py    # HwpxAdapter (버그 회피 포함)
-├── tools.py           # Tool 정의 + call_tool dispatcher
+├── pptx_adapter.py    # PptxAdapter (append_row 자체 구현 포함)
+├── hwpx_adapter.py    # HwpxAdapter (hwpx_core 기반)
+├── hwpx_core/         # 자체 HWPX 패키지 (v0.4+)
+│   ├── constants.py
+│   ├── package.py     # ZIP + dirty XML 관리
+│   ├── grid.py        # iter_grid, table_shape
+│   └── paragraph.py   # run-level 편집 헬퍼
+├── tools.py           # 7개 MCP 도구 정의 + call_tool dispatcher
 └── mcp_server.py      # MCP stdio server
 
 examples/
-└── claude_api_example.py
+└── claude_api_example.py    # Claude API Tool Use 에이전트 루프
 ```
 
 ## 라이선스
@@ -285,8 +323,15 @@ MIT
 
 ## Credits
 
-- [`python-docx`](https://github.com/python-openxml/python-docx)
-- [`docxtpl`](https://github.com/elapouya/python-docx-template)
-- [`python-pptx`](https://github.com/scanny/python-pptx)
-- [`python-hwpx`](https://github.com/airmang/python-hwpx)
-- [`mcp`](https://github.com/modelcontextprotocol/python-sdk)
+**런타임 의존성** (전부 허용형 OSS):
+- [`python-docx`](https://github.com/python-openxml/python-docx) — MIT
+- [`docxtpl`](https://github.com/elapouya/python-docx-template) — LGPL-2.1
+- [`python-pptx`](https://github.com/scanny/python-pptx) — MIT
+- [`lxml`](https://lxml.de/) — BSD
+- [`mcp`](https://github.com/modelcontextprotocol/python-sdk) — MIT
+
+**코드 참조**:
+- [`xgen-doc2chunk`](https://github.com/PlateerLab/xgen-doc2chunk) (Apache-2.0) — HWPX table grid 파싱 로직 차용 (`NOTICE` 참조)
+
+**Dev 전용** (fixture 생성에만 사용):
+- [`python-hwpx`](https://github.com/airmang/python-hwpx) — Non-Commercial License (v0.4.0 부터 런타임 의존성 제거)

{document_adapter-0.7.1 → document_adapter-0.7.2}/document_adapter/tools.py

@@ -177,11 +177,25 @@ TOOL_DEFINITIONS: list[dict[str, Any]] = [
         "description": (
             "라벨 이름으로 값 셀을 자동 탐지해 **일괄 채우기**. 좌표 (table_index, row, col) "
             "계산 없이 '접수번호', '성명' 같은 라벨 key-value dict 로 양식 채움. "
-            "auto 모드: 라벨 셀 오른쪽 → 아래 → 같은 셀 순으로 값 셀 탐색. "
-            "오른쪽/아래 셀이 사용자 요청 라벨 중 하나이면 (서로 라벨 공간 보호) skip 후 다음 시도. "
-            "같은 셀로 fallback 시 append_to_cell 로 라벨 뒤에 값 덧붙임. "
-            "**팁**: 한 양식의 관련 라벨을 함께 넘기면 라벨끼리 서로 보호하여 덮어쓰기 방지. "
-            "반환: {filled:[...], not_found:[...], ambiguous:[...]}."
+            "\n"
+            "**direction 선택 기준 (중요)**: "
+            "(a) `auto` (기본, 보수적): 기존 값이 있는 셀은 다른 라벨로 간주하고 skip → 같은 "
+            "셀에 append_to_cell. **값 셀이 비어있는 양식**에 적합 (HWPX 공공 서식 등). "
+            "(b) `right` / `below` (명시): 라벨 오른쪽/아래 셀을 **덮어쓰기**. **기존에 "
+            "예시값이 채워져 있는 양식**(PPTX 템플릿 등) 에는 반드시 direction='right' 명시. "
+            "\n"
+            "**Dot-path 섹션 지정**: 같은 라벨이 여러 섹션에 있어 ambiguous 로 반환되면 "
+            "`{'피해자.금액': '...', '지급정지요청계좌.금액': '...'}` 처럼 섹션힌트.라벨 "
+            "형태로 재호출. ambiguous 반환의 hint 필드에 예시 제공됨. "
+            "\n"
+            "**output_path**: 생략 시 **원본 파일에 덮어쓰기** (대부분의 경우 생략 권장). "
+            "다른 위치에 저장이 필요할 때만 지정. "
+            "\n"
+            "**팁**: 한 양식의 관련 라벨을 **한 번에 dict 로** 넘기면 라벨끼리 서로 보호되어 "
+            "인접 라벨 오염이 방지됩니다. "
+            "\n"
+            "반환: `{filled: [...], not_found: [...], ambiguous: [...]}`. "
+            "ambiguous candidates 각각에 `context` 필드 포함 (어느 섹션인지 확인)."
         ),
         "input_schema": {
             "type": "object",

{document_adapter-0.7.1 → document_adapter-0.7.2/document_adapter.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: document-adapter
-Version: 0.7.1
+Version: 0.7.2
 Summary: LLM-friendly document template editing (DOCX/PPTX/HWPX) with MCP server and Claude API tool-use support
 Author-email: Son Seongjun <sonsj97@plateer.com>
 License: MIT
@@ -127,13 +127,46 @@ doc.append_to_cell(table_index=2, row=0, col=0, value="홍길동")
 cell = doc.get_cell(table_index=1, row=3, col=2)
 print(cell.text, cell.is_anchor, cell.span, cell.nested_table_indices)
 
-# DOCX/HWPX는 행 추가 지원
+# DOCX/PPTX/HWPX 전부 행 추가 지원 (v0.5+)
 doc.append_row(1, ["새 항목", "값"])
 
 doc.save("checklist_filled.docx")
 doc.close()
 ```
 
+### 라벨 기반 일괄 채우기 (v0.7+)
+
+LLM 이 좌표 `(table_index, row, col)` 를 직접 계산하지 않고 "접수번호", "성명" 같은 사람이 읽는 라벨 key-value 로 양식을 채울 수 있습니다.
+
+```python
+doc = load("form.hwpx")
+result = doc.fill_form({
+    "접수번호": "2026-0001",
+    "성 명":   "홍길동",
+    "주 소":   "서울시 강남구",
+    "금융회사": "국민은행",
+})
+# → {"filled": [...], "not_found": [...], "ambiguous": [...]}
+doc.save()
+doc.close()
+```
+
+- `auto` (기본): 라벨 셀 오른쪽 → 아래 → 같은 셀 순으로 값 셀 탐색. 보수적이라 기존 값 있는 셀은 다른 라벨로 간주하고 skip.
+- `direction="right"` 명시: 라벨 오른쪽 셀을 **덮어쓰기** (예시값 있는 PPTX 템플릿 등).
+- **Dot-path 섹션 지정**: 동일 라벨이 여러 섹션에 있으면 `"피해자.금액"`, `"지급정지요청계좌.금액"` 처럼 섹션 힌트 부여. `ambiguous` 반환 시 `hint` 필드에 예시 제공.
+- **팁**: 한 양식의 관련 라벨을 한 번에 dict 로 넘기면 라벨끼리 서로 보호되어 오염을 방지합니다.
+
+### 셀 크기 메타 (v0.6+)
+
+`get_tables()`가 `column_widths_cm` / `row_heights_cm` 를, `get_cell()`이 `width_cm` / `height_cm` / `char_count` 를 반환해 LLM이 **좁은 셀에 긴 텍스트를 넣어 오버플로 되는 것을 사전에 판단**할 수 있습니다.
+
+```python
+cell = doc.get_cell(table_index=0, row=0, col=0)
+print(cell.width_cm, cell.char_count)  # 1.7cm, 4자 — 작은 배지
+```
+
+DOCX/PPTX는 EMU → cm, HWPX는 HU → cm 자동 환산 (1자리 반올림).
+
 확장자로 자동 분기되므로 `.pptx` / `.hwpx`도 동일한 API를 사용합니다.
 
 ### 병합 셀 인지 동작 (v0.2+)
@@ -185,7 +218,7 @@ document-adapter-mcp
 }
 ```
 
-재시작하면 Claude Desktop에서 아래 4개 도구를 사용할 수 있습니다.
+재시작하면 Claude Desktop에서 아래 7개 도구를 사용할 수 있습니다.
 
 ### Claude Code 설정
 
@@ -227,12 +260,13 @@ resp = client.messages.create(
 
 | 도구 | 설명 |
 |---|---|
-| `inspect_document` | 문서 구조(placeholders, tables)를 JSON으로 반환. **항상 첫 호출로 사용** |
+| `inspect_document` | 문서 구조(placeholders, tables + `column_widths_cm`/`row_heights_cm`)를 JSON으로 반환. **항상 첫 호출로 사용** |
 | `render_template` | `{{key}}`를 context dict 값으로 치환해 새 파일 저장 |
-| `get_cell` | 셀 전체 텍스트 + 병합/중첩 메타 반환 (preview의 40자 잘림 없이) |
+| `get_cell` | 셀 전체 텍스트 + 병합/중첩 메타 + `width_cm`/`height_cm`/`char_count` 반환 |
 | `set_cell` | 특정 표의 `(row, col)` 셀 값 교체 (병합 anchor만) |
 | `append_to_cell` | 기존 텍스트 뒤에 값 덧붙임 (라벨 유지용, 예: `"성 명"` → `"성 명  홍길동"`) |
-| `append_row` | 표 끝에 새 행 추가 (DOCX/HWPX 지원) |
+| `fill_form` (v0.7+) | **라벨 이름**으로 일괄 채우기. 좌표 계산 없이 `{"접수번호": "...", "성명": "..."}` dict. dot-path 섹션 해소 지원 |
+| `append_row` | 표 끝에 새 행 추가 (DOCX/PPTX/HWPX 전부 지원, v0.5+) |
 
 ### `inspect_document` 반환 예시 (v0.2+)
 
@@ -294,13 +328,12 @@ LLM은 이 preview를 보고 **"빈 셀이 어디 있는지 / 어떤 값을 넣
 
 loop / if / filter는 지원하지 않습니다. PPTX는 placeholder가 여러 `run`으로 쪼개질 수 있어, 어댑터가 paragraph 전체 텍스트를 재조립한 뒤 첫 `run`에 다시 담는 방식으로 처리합니다 (서식 일부 손실 가능).
 
-## 내장된 버그 회피
+## 내장된 버그 회피 / 백엔드 선택
 
 | 포맷 | 문제 | 어댑터의 처리 |
 |---|---|---|
-| HWPX | `python-hwpx 2.9.0`의 `set_cell_text()`가 빈 셀에서 lxml/ElementTree 혼용 `TypeError` 발생 | `paragraphs[0].text = value` 직접 할당으로 우회 |
-| HWPX | `replace_text_in_runs()`가 한글 공백이 run으로 쪼개진 경우 매칭 실패 | 위치 기반 API만 사용 |
-| HWPX | `manifest fallback` 경고 로그가 과도하게 출력됨 | `logging.getLogger("hwpx")` 레벨을 `ERROR`로 조정 |
+| HWPX | `python-hwpx` 가 Non-Commercial License → 상용 배포 블로커 | **v0.4.0 부터 자체 `hwpx_core` 모듈** (zipfile + lxml) 로 교체. 런타임에 `python-hwpx` 불필요. 테스트 fixture 생성에만 사용 (dev extras) |
+| PPTX | `python-pptx` 에 공식 `add_row` API 없음 (issue #86, 2014년부터 open) | **v0.5.0 부터 자체 lxml 구현** (`<a:tr>` deepcopy 패턴) |
 | PPTX | placeholder가 여러 `run`으로 쪼개져 단순 `run.text` 치환이 실패 | paragraph 전체 재조립 |
 | DOCX | `docxtpl`의 `{%tr%}`를 같은 행에 두면 파싱 에러 | README에 배치 규칙 명시 |
 
@@ -309,15 +342,20 @@ loop / if / filter는 지원하지 않습니다. PPTX는 placeholder가 여러 `
 ```
 document_adapter/
 ├── __init__.py        # load() dispatcher
-├── base.py            # DocumentAdapter ABC, TableSchema, DocumentSchema
+├── base.py            # DocumentAdapter ABC + fill_form + dataclasses
 ├── docx_adapter.py    # DocxAdapter
-├── pptx_adapter.py    # PptxAdapter
-├── hwpx_adapter.py    # HwpxAdapter (버그 회피 포함)
-├── tools.py           # Tool 정의 + call_tool dispatcher
+├── pptx_adapter.py    # PptxAdapter (append_row 자체 구현 포함)
+├── hwpx_adapter.py    # HwpxAdapter (hwpx_core 기반)
+├── hwpx_core/         # 자체 HWPX 패키지 (v0.4+)
+│   ├── constants.py
+│   ├── package.py     # ZIP + dirty XML 관리
+│   ├── grid.py        # iter_grid, table_shape
+│   └── paragraph.py   # run-level 편집 헬퍼
+├── tools.py           # 7개 MCP 도구 정의 + call_tool dispatcher
 └── mcp_server.py      # MCP stdio server
 
 examples/
-└── claude_api_example.py
+└── claude_api_example.py    # Claude API Tool Use 에이전트 루프
 ```
 
 ## 라이선스
@@ -326,8 +364,15 @@ MIT
 
 ## Credits
 
-- [`python-docx`](https://github.com/python-openxml/python-docx)
-- [`docxtpl`](https://github.com/elapouya/python-docx-template)
-- [`python-pptx`](https://github.com/scanny/python-pptx)
-- [`python-hwpx`](https://github.com/airmang/python-hwpx)
-- [`mcp`](https://github.com/modelcontextprotocol/python-sdk)
+**런타임 의존성** (전부 허용형 OSS):
+- [`python-docx`](https://github.com/python-openxml/python-docx) — MIT
+- [`docxtpl`](https://github.com/elapouya/python-docx-template) — LGPL-2.1
+- [`python-pptx`](https://github.com/scanny/python-pptx) — MIT
+- [`lxml`](https://lxml.de/) — BSD
+- [`mcp`](https://github.com/modelcontextprotocol/python-sdk) — MIT
+
+**코드 참조**:
+- [`xgen-doc2chunk`](https://github.com/PlateerLab/xgen-doc2chunk) (Apache-2.0) — HWPX table grid 파싱 로직 차용 (`NOTICE` 참조)
+
+**Dev 전용** (fixture 생성에만 사용):
+- [`python-hwpx`](https://github.com/airmang/python-hwpx) — Non-Commercial License (v0.4.0 부터 런타임 의존성 제거)

{document_adapter-0.7.1 → document_adapter-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "document-adapter"
-version = "0.7.1"
+version = "0.7.2"
 description = "LLM-friendly document template editing (DOCX/PPTX/HWPX) with MCP server and Claude API tool-use support"
 readme = "README.md"
 requires-python = ">=3.10"