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

{document_adapter-0.7.0/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.0
+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.0 → 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.0 → document_adapter-0.7.2}/document_adapter/base.py

@@ -28,6 +28,91 @@ def _normalize_label(s: str) -> str:
     return _LABEL_NORMALIZE_RE.sub("", s).lower().strip()
 
 
+def _split_dot_path(label: str) -> tuple[str | None, str]:
+    """dot-path 분리: '피해자.금액' → ('피해자', '금액'). dot 없으면 (None, label)."""
+    if "." in label:
+        section, actual = label.rsplit(".", 1)
+        return section.strip() or None, actual.strip()
+    return None, label
+
+
+def _candidate_context_labels(
+    candidate: tuple[int, int, int, int, int, str],
+    tables_by_idx: dict[int, Any],
+) -> list[str]:
+    """candidate 셀 주변에서 section/row 라벨 후보 텍스트 수집.
+
+    전형적으로 양식은:
+      - 같은 table 의 (r, 0) 또는 (r-1..0, 0) 위치 anchor cell 이 섹션 헤더
+      - 또는 (r-1, c), (0, c) 가 header row
+    단순 휴리스틱: 같은 row 의 col=0 anchor text + 그 위로 올라가면서 나오는
+    col=0 anchor text 몇 개를 수집.
+    """
+    t_idx, r, c = candidate[0], candidate[1], candidate[2]
+    t = tables_by_idx.get(t_idx)
+    if t is None:
+        return []
+
+    preview = t.preview
+    labels: list[str] = []
+    # candidate row 자신 또는 위쪽으로 올라가며 col=0 의 가장 가까운 anchor 1개.
+    # 병합 anchor 의 rowSpan 으로 candidate row 가 덮이므로 그게 진짜 섹션 헤더.
+    # candidate 가 col=0 자체이면 자기 자신이 아니라 **위쪽** row 의 col=0 라벨.
+    candidate_col = candidate[2]
+    start_r = min(r, len(preview) - 1)
+    # col=0 후보인 경우 자기 자신을 skip
+    if candidate_col == 0:
+        start_r = r - 1
+    for cur_r in range(start_r, -1, -1):
+        if cur_r < 0:
+            break
+        row = preview[cur_r]
+        if not row:
+            continue
+        val = row[0]
+        if val:
+            labels.append(val.strip())
+            break
+    return labels
+
+
+def _candidate_matches_section(
+    candidate: tuple[int, int, int, int, int, str],
+    section_hint_norm: str,
+    tables_by_idx: dict[int, Any],
+) -> bool:
+    """candidate 의 주변 섹션 라벨에 section_hint_norm 이 포함되면 매칭."""
+    if not section_hint_norm:
+        return True
+    for ctx_label in _candidate_context_labels(candidate, tables_by_idx):
+        if section_hint_norm in _normalize_label(ctx_label):
+            return True
+    return False
+
+
+def _describe_cell_context(
+    candidate: tuple[int, int, int, int, int, str],
+    tables_by_idx: dict[int, Any],
+) -> str:
+    """LLM 에게 보여줄 candidate 셀의 사람 읽는 컨텍스트 문자열."""
+    labels = _candidate_context_labels(candidate, tables_by_idx)
+    if labels:
+        return " / ".join(labels)
+    t_idx, r, c = candidate[0], candidate[1], candidate[2]
+    t = tables_by_idx.get(t_idx)
+    loc = getattr(t, "location", None) if t else None
+    return loc or f"table[{t_idx}]"
+
+
+def _suggest_dot_path(
+    candidate: tuple[int, int, int, int, int, str],
+    tables_by_idx: dict[int, Any],
+) -> str:
+    """ambiguous hint 용 dot-path prefix 후보 (첫 후보의 섹션 라벨)."""
+    labels = _candidate_context_labels(candidate, tables_by_idx)
+    return labels[-1] if labels else "섹션"
+
+
 # ---- custom exceptions -----------------------------------------------------
 # 표준 예외를 상속해 기존 ``except ValueError/IndexError`` 흐름과 호환.
 
@@ -233,9 +318,14 @@ class DocumentAdapter(ABC):
         "성명" 같은 **사람이 읽는 라벨** 로 값을 넣게 하는 API. 양식 문서의
         전형적인 라벨-값 패턴 (라벨 오른쪽 또는 아래 셀이 값) 을 자동 탐지한다.
 
+        **Dot-path 로 ambiguous 해소**: 한 양식에 같은 라벨이 여러 번 등장하면
+        (예: "금액" 이 피해자 섹션, 지급정지계좌 섹션, 피해금이전계좌 섹션 각각)
+        ``"피해자.금액"`` 처럼 dot-path 로 section hint 를 지정하면 section 컨텍스트가
+        일치하는 후보만 선택한다.
+
         Args:
             data: {라벨: 값} dict. 라벨은 셀 텍스트와 whitespace/특수문자 제거
-                후 정규화 비교 (예: "성 명" == "성명").
+                후 정규화 비교 (예: "성 명" == "성명"). "섹션힌트.라벨" 형태도 허용.
             direction: 값 셀 탐색 방향.
                 - "auto" (기본): right → below → same 순서로 빈 셀 우선
                 - "right": 라벨 셀 오른쪽
@@ -247,7 +337,8 @@ class DocumentAdapter(ABC):
             {
               "filled":   [{"label", "table_index", "row", "col", "action", "old_value", "new_value"}],
               "not_found": [라벨 목록],
-              "ambiguous": [{"label", "candidates": [(t,r,c), ...]}],
+              "ambiguous": [{"label", "candidates": [{"table_index", "row", "col", "context"}, ...],
+                             "hint": "dot-path 예시 (예: '피해자.금액')"}],
             }
         """
         if direction not in ("auto", "right", "below", "same"):
@@ -259,6 +350,7 @@ class DocumentAdapter(ABC):
         # 동일 라벨이 여러 곳에 있으면 ambiguous 로 분류.
         label_index: dict[str, list[tuple[int, int, int, int, int, str]]] = {}
         tables = self.get_tables(preview_rows=10_000, max_cell_len=10_000)
+        tables_by_idx = {t.index: t for t in tables}
         for t in tables:
             merge_map = {m.anchor: m.span for m in t.merges}
             for r, row in enumerate(t.preview):
@@ -273,31 +365,65 @@ class DocumentAdapter(ABC):
                         (t.index, r, c, rs, cs, val)
                     )
 
+        # user_keys 는 dot-path 분리 후 뒷부분 기준으로 만든다.
+        # "피해자.금액" 과 "지급정지.금액" 이 섞여 있어도 "금액" 단일로 보호.
+        user_keys = {_normalize_label(_split_dot_path(k)[1]) for k in data.keys()}
+
         filled: list[dict[str, Any]] = []
         not_found: list[str] = []
         ambiguous: list[dict[str, Any]] = []
 
         for label, value in data.items():
-            key = _normalize_label(label)
-            candidates = label_index.get(key, [])
+            section_hint, actual_label = _split_dot_path(label)
+            key = _normalize_label(actual_label)
+            all_candidates = label_index.get(key, [])
+
+            # dot-path 가 있으면 section_hint 로 candidate 필터
+            if section_hint and all_candidates:
+                hint_norm = _normalize_label(section_hint)
+                filtered = [
+                    cand for cand in all_candidates
+                    if _candidate_matches_section(cand, hint_norm, tables_by_idx)
+                ]
+                if filtered:
+                    candidates = filtered
+                else:
+                    # hint 와 매칭 안 되면 원본 후보 유지 (ambiguous 또는 single)
+                    candidates = all_candidates
+            else:
+                candidates = all_candidates
+
             if not candidates:
                 if strict:
                     raise ValueError(f"label not found: {label!r}")
                 not_found.append(label)
                 continue
             if len(candidates) > 1:
-                # 여러 곳에 있으면 채우지 않음 — LLM 이 명확히 지정하게 유도
+                # 여러 곳 — 각 후보의 section context 수집해서 LLM 이 구분 가능하게
                 ambiguous.append({
                     "label": label,
-                    "candidates": [(t, r, c) for (t, r, c, *_) in candidates],
+                    "candidates": [
+                        {
+                            "table_index": cand[0],
+                            "row": cand[1],
+                            "col": cand[2],
+                            "context": _describe_cell_context(cand, tables_by_idx),
+                        }
+                        for cand in candidates
+                    ],
+                    "hint": (
+                        f"dot-path 로 재호출 예시: "
+                        f"'{_suggest_dot_path(candidates[0], tables_by_idx)}.{actual_label}'"
+                    ),
                 })
                 continue
 
             t_idx, r, c, rs, cs, current_text = candidates[0]
-            # "옆 셀이 다른 라벨이면 skip" 판단에 사용자가 요청한 라벨들만 cross-check.
-            # (label_index 전체를 쓰면 값 셀 텍스트까지 라벨로 오판 → 덮어쓰기 실패)
-            user_keys = {_normalize_label(k) for k in data.keys()}
-            other_label_keys = user_keys - {key}
+            # auto 모드에서 인접 라벨 오염 방지 — 문서 내 **모든 anchor cell 텍스트**
+            # 를 보호 대상으로. (값 셀이 포함되어 덮어쓰기 차단될 수 있지만 라벨 파괴가
+            # 더 치명적이라 보수적 default. 예시값이 있는 양식에서 값 셀을 덮어쓰려면
+            # direction="right"/"below" 로 명시.)
+            other_label_keys = set(label_index.keys()) - {key}
             action, coord, old = self._fill_one_cell(
                 t_idx, r, c, rs, cs, str(value), direction, other_label_keys
             )
@@ -372,13 +498,18 @@ class DocumentAdapter(ABC):
                 return "append_to_cell", (t_idx, target_r, target_c), old
 
             # right / below
+            if direction == "auto" and not cell.is_anchor:
+                # target 이 병합의 non-anchor 면 anchor 로 redirect 되어 엉뚱한 셀에
+                # 쓰일 위험 (예: 스페이서 행의 병합 anchor). auto 에서는 skip 하고
+                # 다음 mode 로.
+                continue
             if direction == "auto" and target_key and target_key in other_label_keys:
                 # 옆 셀이 다른 라벨 → 덮어쓰면 라벨 손상. 다음 mode 시도.
                 continue
             try:
                 old = self.set_cell(
                     t_idx, target_r, target_c, value,
-                    allow_merge_redirect=not cell.is_anchor,
+                    allow_merge_redirect=(direction != "auto"),
                 )
             except MergedCellWriteError:
                 continue

{document_adapter-0.7.0 → 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.0 → 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.0
+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.0 → document_adapter-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "document-adapter"
-version = "0.7.0"
+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"

{document_adapter-0.7.0 → document_adapter-0.7.2}/tests/test_smoke.py

@@ -1085,7 +1085,11 @@ def test_fill_form_docx_label_right_value(tmp_path: Path) -> None:
 
 
 def test_fill_form_pptx_label_right_value(tmp_path: Path) -> None:
-    """PPTX 2x2 라벨|값 패턴 — fill_form auto 가 오른쪽 값 셀에 set_cell."""
+    """PPTX 2x2 라벨|값 패턴 — 예시값 있는 셀 덮어쓰려면 direction='right' 명시.
+
+    auto 는 보수적 기본값이라 기존 값이 있는 셀은 다른 라벨로 간주하고 skip,
+    최종적으로 same append. 예시값 덮어쓰기가 의도면 direction 명시 필요.
+    """
     src = tmp_path / "form.pptx"
     prs = Presentation()
     prs.slide_width = Inches(10)
@@ -1101,7 +1105,10 @@ def test_fill_form_pptx_label_right_value(tmp_path: Path) -> None:
 
     adapter = load(src)
     try:
-        result = adapter.fill_form({"보고일자": "2026.04.16", "작성자": "홍길동"})
+        result = adapter.fill_form(
+            {"보고일자": "2026.04.16", "작성자": "홍길동"},
+            direction="right",
+        )
         adapter.save()
     finally:
         adapter.close()
@@ -1113,6 +1120,41 @@ def test_fill_form_pptx_label_right_value(tmp_path: Path) -> None:
     assert filled_by_label["보고일자"]["old_value"] == "2026.01.01"
 
 
+def test_fill_form_dot_path_resolves_ambiguous(tmp_path: Path) -> None:
+    """동일 라벨이 여러 섹션에 있으면 dot-path 로 섹션 지정해 해소."""
+    src = tmp_path / "form.docx"
+    doc = Document()
+    t = doc.add_table(rows=4, cols=2)
+    t.cell(0, 0).text = "재무"
+    t.cell(0, 1).text = ""
+    t.cell(1, 0).text = "금액"
+    t.cell(1, 1).text = ""
+    t.cell(2, 0).text = "영업"
+    t.cell(2, 1).text = ""
+    t.cell(3, 0).text = "금액"
+    t.cell(3, 1).text = ""
+    doc.save(src)
+
+    adapter = load(src)
+    try:
+        r_ambig = adapter.fill_form({"금액": "1"})
+        assert len(r_ambig["ambiguous"]) == 1
+        assert r_ambig["ambiguous"][0]["label"] == "금액"
+        assert len(r_ambig["ambiguous"][0]["candidates"]) == 2
+        contexts = [c["context"] for c in r_ambig["ambiguous"][0]["candidates"]]
+        assert any("재무" in ctx for ctx in contexts)
+        assert any("영업" in ctx for ctx in contexts)
+
+        r_resolved = adapter.fill_form(
+            {"재무.금액": "100", "영업.금액": "200"},
+            direction="right",
+        )
+        assert r_resolved["ambiguous"] == []
+        assert len(r_resolved["filled"]) == 2
+    finally:
+        adapter.close()
+
+
 def test_fill_form_not_found_records_missing(tmp_path: Path) -> None:
     """존재하지 않는 라벨은 not_found 에 기록되고, strict=False 면 예외 없음."""
     src = tmp_path / "form.docx"