document-adapter 0.1.0__tar.gz

document_adapter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plateer Lab
+
+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.

document_adapter-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: document-adapter
+Version: 0.1.0
+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
+Project-URL: Homepage, https://github.com/PlateerLab/document-adapter
+Project-URL: Repository, https://github.com/PlateerLab/document-adapter
+Keywords: mcp,llm,document,docx,pptx,hwpx,template,claude
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-docx>=1.1
+Requires-Dist: docxtpl>=0.20
+Requires-Dist: python-pptx>=1.0
+Requires-Dist: python-hwpx>=2.9
+Requires-Dist: mcp>=1.0
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.40; extra == "claude"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# document-adapter
+
+**LLM이 DOCX / PPTX / HWPX 문서를 직접 편집할 수 있게 해주는 통합 어댑터 + MCP 서버.**
+
+세 가지 오피스 포맷을 하나의 파이썬 인터페이스로 추상화하고, Claude Desktop / Claude Code / Anthropic API Tool Use에서 바로 호출할 수 있는 MCP 도구로 노출합니다. 양식 문서의 빈 셀을 자동으로 채우거나, 템플릿의 `{{key}}`를 치환하거나, 기존 표의 내용을 수정하는 작업을 LLM 에이전트가 수행할 수 있습니다.
+
+## 지원 포맷
+
+| 포맷 | 백엔드 | 템플릿 렌더 | 표 읽기 | 셀 수정 | 행 추가 |
+|---|---|---|---|---|---|
+| `.docx` | `docxtpl` + `python-docx` | Jinja2 (`{%tr%}` loop 포함) | ✅ | ✅ | ✅ |
+| `.pptx` | `python-pptx` | `{{key}}` 치환 | ✅ (슬라이드 위치 포함) | ✅ | ❌ (미지원) |
+| `.hwpx` | `python-hwpx` (Pure Python) | `{{key}}` 치환 | ✅ | ✅ | ❌ (미지원) |
+
+- HWPX는 한컴오피스 설치가 **불필요**합니다 (macOS/Linux 서버에서 그대로 동작).
+- 구버전 `.hwp`(바이너리 포맷)는 지원하지 않습니다 — `.hwpx`로 변환 후 사용하세요.
+
+## 설치
+
+```bash
+pip install -e .
+
+# Claude API 예시 스크립트까지 쓰려면
+pip install -e ".[claude]"
+```
+
+Python 3.10+ 필요.
+
+## 빠른 시작 — 파이썬 API
+
+```python
+from document_adapter import load
+
+doc = load("report_template.docx")
+
+# 1. 구조 파악
+schema = doc.get_schema()
+print(schema.placeholders)   # ['author', 'date', 'title']
+print(schema.tables)         # [TableSchema(index=0, rows=7, cols=2, ...), ...]
+
+# 2. 템플릿 렌더
+doc.render_template({
+    "title": "Q1 운영 리포트",
+    "author": "손성준",
+    "date": "2026-04-15",
+})
+doc.save("report_filled.docx")
+
+# 3. 기존 양식 파일의 표 셀 수정
+doc = load("checklist.docx")
+old = doc.set_cell(table_index=1, row=1, col=1, value="○○전자")
+doc.append_row(1, ["새 항목", "값"])  # DOCX만 지원
+doc.save("checklist_filled.docx")
+doc.close()
+```
+
+확장자로 자동 분기되므로 `.pptx` / `.hwpx`도 동일한 API를 사용합니다.
+
+## MCP 서버로 사용 — Claude Desktop / Claude Code
+
+### 실행
+
+```bash
+python -m document_adapter.mcp_server
+# 또는 설치 후
+document-adapter-mcp
+```
+
+### Claude Desktop 설정
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "document-adapter": {
+      "command": "/absolute/path/to/venv/bin/python",
+      "args": ["-m", "document_adapter.mcp_server"]
+    }
+  }
+}
+```
+
+재시작하면 Claude Desktop에서 아래 4개 도구를 사용할 수 있습니다.
+
+### Claude Code 설정
+
+```bash
+claude mcp add document-adapter \
+  /absolute/path/to/venv/bin/python -m document_adapter.mcp_server
+```
+
+## Anthropic API Tool Use로 사용
+
+`document_adapter.tools`가 Claude API의 tool schema 형식과 그대로 호환됩니다.
+
+```python
+import anthropic
+from document_adapter.tools import TOOL_DEFINITIONS, call_tool
+
+client = anthropic.Anthropic()
+
+resp = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=4096,
+    tools=[{
+        "name": t["name"],
+        "description": t["description"],
+        "input_schema": t["input_schema"],
+    } for t in TOOL_DEFINITIONS],
+    messages=[{
+        "role": "user",
+        "content": "report_template.docx의 표 구조를 확인하고 빈 셀을 적절히 채워줘",
+    }],
+)
+
+# tool_use 블록을 받으면 call_tool(name, args)로 실행 후 결과 반환
+```
+
+전체 agent loop 예시는 [`examples/claude_api_example.py`](examples/claude_api_example.py) 참고.
+
+## 노출되는 4개 도구
+
+| 도구 | 설명 |
+|---|---|
+| `inspect_document` | 문서 구조(placeholders, tables)를 JSON으로 반환. **항상 첫 호출로 사용** |
+| `render_template` | `{{key}}`를 context dict 값으로 치환해 새 파일 저장 |
+| `set_cell` | 특정 표의 `(row, col)` 셀 값 교체 |
+| `append_row` | 표 끝에 새 행 추가 (DOCX 전용) |
+
+### `inspect_document` 반환 예시
+
+```json
+{
+  "format": "docx",
+  "source": "/path/to/checklist.docx",
+  "placeholders": [],
+  "tables": [
+    {
+      "index": 1,
+      "rows": 7,
+      "cols": 2,
+      "location": null,
+      "preview": [
+        {"row": 0, "cells": ["항목", "기입 내용"]},
+        {"row": 1, "cells": ["고객사 / 조직", ""]},
+        {"row": 2, "cells": ["현업 담당부서 / 책임자", ""]}
+      ]
+    }
+  ]
+}
+```
+
+LLM은 이 preview를 보고 **"빈 셀이 어디 있는지 / 어떤 값을 넣어야 하는지"** 를 판단하여 `set_cell`을 호출합니다.
+
+## 템플릿 작성 규칙
+
+### DOCX — Jinja2 전체 문법 사용 가능
+
+```
+{{ report_title }}
+작성자: {{ author }}
+
+{% for item in items %}- {{ item.name }}: {{ item.value }}
+{% endfor %}
+```
+
+**표 행 반복은 `{%tr for ... %}` / `{%tr endfor %}`를 각각 별도 행에 두어야 합니다.**
+같은 행에 두 태그를 넣으면 `<w:tr>` 전체가 `{% for %}`로 교체되어 `endfor`가 손실됩니다.
+
+```
+┌─────────────────────┬─────┬─────┐
+│ 항목                │ 목표 │ 실적 │    <- 헤더
+├─────────────────────┼─────┼─────┤
+│ {%tr for r in rows %}          │    <- for 행
+├─────────────────────┼─────┼─────┤
+│ {{ r.name }}        │ {{ r.target }} │ {{ r.actual }} │  <- 반복 본문
+├─────────────────────┼─────┼─────┤
+│ {%tr endfor %}                 │    <- endfor 행
+└─────────────────────┴─────┴─────┘
+```
+
+### PPTX / HWPX — 단순 `{{key}}` 치환만
+
+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`로 조정 |
+| PPTX | placeholder가 여러 `run`으로 쪼개져 단순 `run.text` 치환이 실패 | paragraph 전체 재조립 |
+| DOCX | `docxtpl`의 `{%tr%}`를 같은 행에 두면 파싱 에러 | README에 배치 규칙 명시 |
+
+## 프로젝트 구조
+
+```
+document_adapter/
+├── __init__.py        # load() dispatcher
+├── base.py            # DocumentAdapter ABC, TableSchema, DocumentSchema
+├── docx_adapter.py    # DocxAdapter
+├── pptx_adapter.py    # PptxAdapter
+├── hwpx_adapter.py    # HwpxAdapter (버그 회피 포함)
+├── tools.py           # Tool 정의 + call_tool dispatcher
+└── mcp_server.py      # MCP stdio server
+
+examples/
+└── claude_api_example.py
+```
+
+## 라이선스
+
+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)

document_adapter-0.1.0/README.md

@@ -0,0 +1,223 @@
+# document-adapter
+
+**LLM이 DOCX / PPTX / HWPX 문서를 직접 편집할 수 있게 해주는 통합 어댑터 + MCP 서버.**
+
+세 가지 오피스 포맷을 하나의 파이썬 인터페이스로 추상화하고, Claude Desktop / Claude Code / Anthropic API Tool Use에서 바로 호출할 수 있는 MCP 도구로 노출합니다. 양식 문서의 빈 셀을 자동으로 채우거나, 템플릿의 `{{key}}`를 치환하거나, 기존 표의 내용을 수정하는 작업을 LLM 에이전트가 수행할 수 있습니다.
+
+## 지원 포맷
+
+| 포맷 | 백엔드 | 템플릿 렌더 | 표 읽기 | 셀 수정 | 행 추가 |
+|---|---|---|---|---|---|
+| `.docx` | `docxtpl` + `python-docx` | Jinja2 (`{%tr%}` loop 포함) | ✅ | ✅ | ✅ |
+| `.pptx` | `python-pptx` | `{{key}}` 치환 | ✅ (슬라이드 위치 포함) | ✅ | ❌ (미지원) |
+| `.hwpx` | `python-hwpx` (Pure Python) | `{{key}}` 치환 | ✅ | ✅ | ❌ (미지원) |
+
+- HWPX는 한컴오피스 설치가 **불필요**합니다 (macOS/Linux 서버에서 그대로 동작).
+- 구버전 `.hwp`(바이너리 포맷)는 지원하지 않습니다 — `.hwpx`로 변환 후 사용하세요.
+
+## 설치
+
+```bash
+pip install -e .
+
+# Claude API 예시 스크립트까지 쓰려면
+pip install -e ".[claude]"
+```
+
+Python 3.10+ 필요.
+
+## 빠른 시작 — 파이썬 API
+
+```python
+from document_adapter import load
+
+doc = load("report_template.docx")
+
+# 1. 구조 파악
+schema = doc.get_schema()
+print(schema.placeholders)   # ['author', 'date', 'title']
+print(schema.tables)         # [TableSchema(index=0, rows=7, cols=2, ...), ...]
+
+# 2. 템플릿 렌더
+doc.render_template({
+    "title": "Q1 운영 리포트",
+    "author": "손성준",
+    "date": "2026-04-15",
+})
+doc.save("report_filled.docx")
+
+# 3. 기존 양식 파일의 표 셀 수정
+doc = load("checklist.docx")
+old = doc.set_cell(table_index=1, row=1, col=1, value="○○전자")
+doc.append_row(1, ["새 항목", "값"])  # DOCX만 지원
+doc.save("checklist_filled.docx")
+doc.close()
+```
+
+확장자로 자동 분기되므로 `.pptx` / `.hwpx`도 동일한 API를 사용합니다.
+
+## MCP 서버로 사용 — Claude Desktop / Claude Code
+
+### 실행
+
+```bash
+python -m document_adapter.mcp_server
+# 또는 설치 후
+document-adapter-mcp
+```
+
+### Claude Desktop 설정
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "document-adapter": {
+      "command": "/absolute/path/to/venv/bin/python",
+      "args": ["-m", "document_adapter.mcp_server"]
+    }
+  }
+}
+```
+
+재시작하면 Claude Desktop에서 아래 4개 도구를 사용할 수 있습니다.
+
+### Claude Code 설정
+
+```bash
+claude mcp add document-adapter \
+  /absolute/path/to/venv/bin/python -m document_adapter.mcp_server
+```
+
+## Anthropic API Tool Use로 사용
+
+`document_adapter.tools`가 Claude API의 tool schema 형식과 그대로 호환됩니다.
+
+```python
+import anthropic
+from document_adapter.tools import TOOL_DEFINITIONS, call_tool
+
+client = anthropic.Anthropic()
+
+resp = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=4096,
+    tools=[{
+        "name": t["name"],
+        "description": t["description"],
+        "input_schema": t["input_schema"],
+    } for t in TOOL_DEFINITIONS],
+    messages=[{
+        "role": "user",
+        "content": "report_template.docx의 표 구조를 확인하고 빈 셀을 적절히 채워줘",
+    }],
+)
+
+# tool_use 블록을 받으면 call_tool(name, args)로 실행 후 결과 반환
+```
+
+전체 agent loop 예시는 [`examples/claude_api_example.py`](examples/claude_api_example.py) 참고.
+
+## 노출되는 4개 도구
+
+| 도구 | 설명 |
+|---|---|
+| `inspect_document` | 문서 구조(placeholders, tables)를 JSON으로 반환. **항상 첫 호출로 사용** |
+| `render_template` | `{{key}}`를 context dict 값으로 치환해 새 파일 저장 |
+| `set_cell` | 특정 표의 `(row, col)` 셀 값 교체 |
+| `append_row` | 표 끝에 새 행 추가 (DOCX 전용) |
+
+### `inspect_document` 반환 예시
+
+```json
+{
+  "format": "docx",
+  "source": "/path/to/checklist.docx",
+  "placeholders": [],
+  "tables": [
+    {
+      "index": 1,
+      "rows": 7,
+      "cols": 2,
+      "location": null,
+      "preview": [
+        {"row": 0, "cells": ["항목", "기입 내용"]},
+        {"row": 1, "cells": ["고객사 / 조직", ""]},
+        {"row": 2, "cells": ["현업 담당부서 / 책임자", ""]}
+      ]
+    }
+  ]
+}
+```
+
+LLM은 이 preview를 보고 **"빈 셀이 어디 있는지 / 어떤 값을 넣어야 하는지"** 를 판단하여 `set_cell`을 호출합니다.
+
+## 템플릿 작성 규칙
+
+### DOCX — Jinja2 전체 문법 사용 가능
+
+```
+{{ report_title }}
+작성자: {{ author }}
+
+{% for item in items %}- {{ item.name }}: {{ item.value }}
+{% endfor %}
+```
+
+**표 행 반복은 `{%tr for ... %}` / `{%tr endfor %}`를 각각 별도 행에 두어야 합니다.**
+같은 행에 두 태그를 넣으면 `<w:tr>` 전체가 `{% for %}`로 교체되어 `endfor`가 손실됩니다.
+
+```
+┌─────────────────────┬─────┬─────┐
+│ 항목                │ 목표 │ 실적 │    <- 헤더
+├─────────────────────┼─────┼─────┤
+│ {%tr for r in rows %}          │    <- for 행
+├─────────────────────┼─────┼─────┤
+│ {{ r.name }}        │ {{ r.target }} │ {{ r.actual }} │  <- 반복 본문
+├─────────────────────┼─────┼─────┤
+│ {%tr endfor %}                 │    <- endfor 행
+└─────────────────────┴─────┴─────┘
+```
+
+### PPTX / HWPX — 단순 `{{key}}` 치환만
+
+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`로 조정 |
+| PPTX | placeholder가 여러 `run`으로 쪼개져 단순 `run.text` 치환이 실패 | paragraph 전체 재조립 |
+| DOCX | `docxtpl`의 `{%tr%}`를 같은 행에 두면 파싱 에러 | README에 배치 규칙 명시 |
+
+## 프로젝트 구조
+
+```
+document_adapter/
+├── __init__.py        # load() dispatcher
+├── base.py            # DocumentAdapter ABC, TableSchema, DocumentSchema
+├── docx_adapter.py    # DocxAdapter
+├── pptx_adapter.py    # PptxAdapter
+├── hwpx_adapter.py    # HwpxAdapter (버그 회피 포함)
+├── tools.py           # Tool 정의 + call_tool dispatcher
+└── mcp_server.py      # MCP stdio server
+
+examples/
+└── claude_api_example.py
+```
+
+## 라이선스
+
+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)

document_adapter-0.1.0/document_adapter/__init__.py

@@ -0,0 +1,45 @@
+"""Document template editing — 통합 어댑터.
+
+사용법:
+    from document_adapter import load
+    doc = load("report.docx")
+    schema = doc.get_schema()
+    doc.set_cell(0, 1, 1, "홍길동")
+    doc.save("report_filled.docx")
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .base import DocumentAdapter, DocumentSchema, TableSchema
+from .docx_adapter import DocxAdapter
+from .hwpx_adapter import HwpxAdapter
+from .pptx_adapter import PptxAdapter
+
+__all__ = [
+    "load",
+    "DocumentAdapter",
+    "DocumentSchema",
+    "TableSchema",
+    "DocxAdapter",
+    "PptxAdapter",
+    "HwpxAdapter",
+]
+
+_ADAPTERS: dict[str, type[DocumentAdapter]] = {
+    ".docx": DocxAdapter,
+    ".pptx": PptxAdapter,
+    ".hwpx": HwpxAdapter,
+}
+
+
+def load(path: str | Path) -> DocumentAdapter:
+    """확장자로 적절한 어댑터를 선택해 문서를 연다."""
+    p = Path(path)
+    suffix = p.suffix.lower()
+    cls = _ADAPTERS.get(suffix)
+    if cls is None:
+        raise ValueError(
+            f"지원하지 않는 포맷: {suffix}. 지원: {sorted(_ADAPTERS.keys())}"
+        )
+    return cls(p)

document_adapter-0.1.0/document_adapter/base.py

@@ -0,0 +1,108 @@
+"""DocumentAdapter 공통 인터페이스.
+
+세 포맷(DOCX/PPTX/HWPX)의 공통 작업을 추상화:
+- 템플릿 렌더링 ({{key}} 치환)
+- 표 스키마 추출 (LLM 입력용)
+- 셀 수정 / 행 추가
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class TableSchema:
+    """표 한 개의 구조 (LLM에게 넘길 형태)."""
+    index: int
+    rows: int
+    cols: int
+    preview: list[list[str]]
+    location: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "index": self.index,
+            "rows": self.rows,
+            "cols": self.cols,
+            "location": self.location,
+            "preview": self.preview,
+        }
+
+
+@dataclass
+class DocumentSchema:
+    """문서 전체 스키마."""
+    format: str
+    source: str
+    placeholders: list[str] = field(default_factory=list)
+    tables: list[TableSchema] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "format": self.format,
+            "source": self.source,
+            "placeholders": self.placeholders,
+            "tables": [t.to_dict() for t in self.tables],
+        }
+
+
+class DocumentAdapter(ABC):
+    """모든 포맷 어댑터의 공통 부모."""
+
+    format: str = ""
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+        self._open()
+
+    # ---- lifecycle ----
+    @abstractmethod
+    def _open(self) -> None: ...
+
+    @abstractmethod
+    def save(self, path: Path | str | None = None) -> Path: ...
+
+    def close(self) -> None:
+        """일부 포맷(HWPX)은 명시적 close 필요."""
+        pass
+
+    # ---- inspection ----
+    @abstractmethod
+    def get_placeholders(self) -> list[str]:
+        """본문에서 사용된 {{key}} 목록 반환."""
+
+    @abstractmethod
+    def get_tables(self, min_rows: int = 1, min_cols: int = 1,
+                   preview_rows: int = 4, max_cell_len: int = 40) -> list[TableSchema]:
+        """필터 조건을 만족하는 표 스키마 목록."""
+
+    def get_schema(self) -> DocumentSchema:
+        return DocumentSchema(
+            format=self.format,
+            source=str(self.path),
+            placeholders=self.get_placeholders(),
+            tables=self.get_tables(),
+        )
+
+    # ---- editing ----
+    @abstractmethod
+    def render_template(self, context: dict[str, Any]) -> None:
+        """템플릿의 {{key}}를 context 값으로 치환."""
+
+    @abstractmethod
+    def set_cell(self, table_index: int, row: int, col: int, value: str) -> str:
+        """셀 값 교체. 원래 값 반환."""
+
+    @abstractmethod
+    def append_row(self, table_index: int, values: list[str]) -> None:
+        """표 끝에 새 행 추가."""
+
+    # ---- context manager ----
+    def __enter__(self) -> "DocumentAdapter":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()