edit2docs 0.2.0__tar.gz → 0.2.1__tar.gz

edit2docs-0.2.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: edit2docs
+Version: 0.2.1
+Summary: AI-agent-native document engine: generate and chat-edit DOCX, XLSX and PPTX as a Python library, agent tool set, MCP server or hosted service. Korean-first. Sister project of edit2ppt.
+Project-URL: Homepage, https://github.com/CocoRoF/edit2docs
+Project-URL: Issues, https://github.com/CocoRoF/edit2docs/issues
+Project-URL: Upstream, https://github.com/hugohe3/ppt-master
+Author: edit2docs contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,korean,mcp,pptx,presentation
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: ebooklib>=0.18
+Requires-Dist: edge-tts>=7.2.8
+Requires-Dist: lxml>=5.3.0
+Requires-Dist: mammoth>=1.6.0
+Requires-Dist: markdownify>=0.11.6
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: nbconvert>=7.0.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: pillow>=9.0.0
+Requires-Dist: pydantic-settings>=2.6.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pymupdf>=1.23.0
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: python-pptx>=0.6.21
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: aioboto3>=13.2.0; extra == 'dev'
+Requires-Dist: aiosqlite>=0.20.0; extra == 'dev'
+Requires-Dist: alembic>=1.14.0; extra == 'dev'
+Requires-Dist: arq>=0.26.1; extra == 'dev'
+Requires-Dist: asyncpg>=0.30.0; extra == 'dev'
+Requires-Dist: botocore>=1.35.0; extra == 'dev'
+Requires-Dist: fastapi>=0.115.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.2; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.388; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.3; extra == 'dev'
+Requires-Dist: python-multipart>=0.0.17; extra == 'dev'
+Requires-Dist: redis>=5.2.0; extra == 'dev'
+Requires-Dist: ruff>=0.7.0; extra == 'dev'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.36; extra == 'dev'
+Requires-Dist: sse-starlette>=2.1.3; extra == 'dev'
+Requires-Dist: structlog>=24.4.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'dev'
+Provides-Extra: images
+Requires-Dist: google-genai>=1.0.0; extra == 'images'
+Requires-Dist: openai>=1.55.0; extra == 'images'
+Provides-Extra: server
+Requires-Dist: aioboto3>=13.2.0; extra == 'server'
+Requires-Dist: aiosqlite>=0.20.0; extra == 'server'
+Requires-Dist: alembic>=1.14.0; extra == 'server'
+Requires-Dist: arq>=0.26.1; extra == 'server'
+Requires-Dist: asyncpg>=0.30.0; extra == 'server'
+Requires-Dist: botocore>=1.35.0; extra == 'server'
+Requires-Dist: fastapi>=0.115.0; extra == 'server'
+Requires-Dist: python-multipart>=0.0.17; extra == 'server'
+Requires-Dist: redis>=5.2.0; extra == 'server'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.36; extra == 'server'
+Requires-Dist: sse-starlette>=2.1.3; extra == 'server'
+Requires-Dist: structlog>=24.4.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'server'
+Provides-Extra: svg-fallback
+Requires-Dist: cairosvg>=2.7.0; extra == 'svg-fallback'
+Description-Content-Type: text/markdown
+
+# edit2docs
+
+**AI-agent-native document engine — DOCX · XLSX · PPTX. Korean-first.**
+
+[한국어 README](./README.ko.md) · Sister project of
+[edit2ppt](https://github.com/CocoRoF/edit2ppt) (the PPTX pipeline is inherited
+from it) · Built on [ppt-master](https://github.com/hugohe3/ppt-master) (MIT)
+
+---
+
+`edit2docs` generates complete Office documents from a one-line intent and
+chat-edits existing files — Word reports, Excel workbooks and PowerPoint decks —
+always producing natively editable OOXML. One engine, four surfaces:
+
+```bash
+pip install edit2docs              # library + agent tools + local MCP
+pip install "edit2docs[server]"    # + the hosted multi-tenant service
+```
+
+## The five verbs
+
+Every surface exposes the same five format-dispatched verbs — the file
+extension picks the engine:
+
+| verb | what it does | LLM? |
+|---|---|---|
+| `generate_doc` | intent (+ optional sources / PPTX template) → complete document | ✳ |
+| `edit_doc` | one natural-language edit turn; untouched content stays byte-identical | ✳ |
+| `preview_doc` | .pptx → per-slide SVG · .docx/.xlsx → markdown | — |
+| `analyze_doc` | structure outline **with the exact addresses `set_doc_text` needs** | — |
+| `set_doc_text` | deterministic targeted edits (paragraphs / cells / slide text) | — |
+
+## 1 · Python library
+
+```python
+from edit2docs import generate_doc, edit_doc, preview_doc, analyze_doc, set_doc_text
+
+generate_doc("3분기 실적 보고서", output="report.docx")
+generate_doc("분기별 매출 정리", output="sales.xlsx", sources=["raw.pdf"])
+generate_doc("Q3 영업 결과 임원 보고", output="deck.pptx", template="brand.pptx",
+             deck_mode="template_restyle")
+
+r = edit_doc("report.docx", "진행 사항 섹션에 배포 완료 항목을 추가해줘")
+print(r.reply, r.operations)
+
+info = analyze_doc("sales.xlsx")               # sheets + sample rows
+set_doc_text("sales.xlsx", [{"sheet": "매출", "cell": "B3", "value": 142}])
+```
+
+BYOK: `api_key=...` or `ANTHROPIC_API_KEY`. The deterministic verbs need no key.
+Async variants: `async_generate_doc`, `async_edit_doc`.
+
+## 2 · Agent tools (function calling)
+
+```python
+from edit2docs.agent_tools import ANTHROPIC_TOOLS, run_tool
+
+msg = client.messages.create(model="claude-opus-4-7", tools=ANTHROPIC_TOOLS, ...)
+for block in msg.content:
+    if block.type == "tool_use":
+        result = run_tool(block.name, block.input)
+```
+
+## 3 · Local MCP server (zero infra)
+
+```jsonc
+// Claude Desktop / Claude Code / Cursor
+{ "mcpServers": { "edit2docs": {
+    "command": "edit2docs-mcp",
+    "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
+} } }
+```
+
+## 4 · Hosted service
+
+`pip install "edit2docs[server]"` then `edit2docs serve` — the FastAPI service
+(REST + SSE jobs + hosted MCP) inherited from edit2ppt: multi-tenant assets,
+job queue, S3-compatible storage, PPTX studio endpoints.
+
+## How each format works
+
+* **DOCX** — the writer LLM emits a constrained markdown document; a
+  deterministic renderer (python-docx) turns it into styled Word. Edits are
+  paragraph-addressed operations (`replace` / `insert_after` / `delete`,
+  table cells by row/col) so untouched paragraphs keep their formatting.
+* **XLSX** — the designer LLM emits a YAML *sheet spec* (sheets / headers /
+  rows / number formats, formulas allowed); openpyxl renders styled sheets.
+  Edits are `set_cell` / `append_rows` / `add_sheet` with staleness guards.
+* **PPTX** — the full multi-stage deck pipeline inherited from edit2ppt:
+  strategist → per-page SVG → native DrawingML, user-PPTX templates
+  (restyle/extend), chat-edit with slide recompose, per-paragraph text edits
+  incl. table cells.
+
+Every LLM planner follows the same contract: fenced `reply` + `edit_plan`
+blocks, one retry with a format reminder, and an honest reply (instead of a
+silent no-op) when planning fails. Korean-native throughout: Hangul-aware
+widths, `lang="ko-KR"` OOXML runs, bilingual errors.
+
+## License
+
+MIT. PPTX core forked from ppt-master (MIT) via edit2ppt.

edit2docs-0.2.1/pyproject.toml

@@ -0,0 +1,161 @@
+[project]
+name = "edit2docs"
+version = "0.2.1"
+description = "AI-agent-native document engine: generate and chat-edit DOCX, XLSX and PPTX as a Python library, agent tool set, MCP server or hosted service. Korean-first. Sister project of edit2ppt."
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "edit2docs contributors"}]
+keywords = ["pptx", "presentation", "ai-agent", "mcp", "korean"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+
+# Core = everything the LIBRARY / agent-tools / local MCP surfaces need:
+# the tool layer (generate/edit/preview/text-edit) with zero server infra.
+# `pip install edit2docs` stays lean; the hosted service adds `[server]`.
+dependencies = [
+    "pydantic>=2.9.0",
+    "pydantic-settings>=2.6.0",
+    # i18n + spec_lock / edit-plan parsing
+    "pyyaml>=6.0",
+    # Core engine dependencies (from ppt-master)
+    "python-pptx>=0.6.21",
+    "python-docx>=1.1.0",
+    "PyMuPDF>=1.23.0",
+    "mammoth>=1.6.0",
+    "openpyxl>=3.1.0",
+    "nbconvert>=7.0.0",
+    "markdownify>=0.11.6",
+    "ebooklib>=0.18",
+    "beautifulsoup4>=4.12.0",
+    "requests>=2.31.0",
+    "Pillow>=9.0.0",
+    "numpy>=1.20.0",
+    "lxml>=5.3.0",
+    # TTS
+    "edge-tts>=7.2.8",
+    # LLM
+    "anthropic>=0.40.0",
+    # MCP (Model Context Protocol) — powers the zero-infra `edit2docs-mcp`
+    "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+# Hosted multi-tenant service: FastAPI + DB + object storage + job queue.
+server = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "python-multipart>=0.0.17",
+    "sse-starlette>=2.1.3",
+    "aioboto3>=13.2.0",
+    "botocore>=1.35.0",
+    "sqlalchemy[asyncio]>=2.0.36",
+    "aiosqlite>=0.20.0",
+    "asyncpg>=0.30.0",
+    "alembic>=1.14.0",
+    "arq>=0.26.1",
+    "redis>=5.2.0",
+    "structlog>=24.4.0",
+]
+dev = [
+    # The test suite covers the hosted service too.
+    "edit2docs[server]",
+    "pytest>=8.3.3",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=6.0.0",
+    "httpx>=0.27.2",
+    "ruff>=0.7.0",
+    "pyright>=1.1.388",
+    "pre-commit>=4.0.0",
+]
+images = [
+    # AI image generation backends — optional. Each gated by env var.
+    "google-genai>=1.0.0",
+    "openai>=1.55.0",
+]
+svg-fallback = [
+    # SVG -> PNG fallback for legacy Office. Pick one.
+    "cairosvg>=2.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CocoRoF/edit2docs"
+Issues = "https://github.com/CocoRoF/edit2docs/issues"
+Upstream = "https://github.com/hugohe3/ppt-master"
+
+[project.scripts]
+edit2docs = "edit2docs.cli:main"
+# Zero-infra stdio MCP server over local files (Claude Desktop / Code / Cursor):
+#   uvx --from edit2docs edit2docs-mcp   or   pip install edit2docs && edit2docs-mcp
+edit2docs-mcp = "edit2docs.mcp.local_main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/edit2docs"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/edit2docs" = "edit2docs"
+
+# ---------------------------------------------------------------------------
+# Ruff (lint + format)
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+extend-exclude = [
+    "src/edit2docs/core",  # ppt-master fork; lint separately if/when we rewrite
+]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "W",   # pycodestyle warnings
+]
+ignore = [
+    "E501",  # line length handled by formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B", "E402"]
+
+# ---------------------------------------------------------------------------
+# Pytest
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+addopts = "-ra --strict-markers"
+markers = [
+    "integration: hits external services (LLM, image, TTS)",
+    "slow: takes more than ~5s",
+]
+
+# ---------------------------------------------------------------------------
+# Pyright
+# ---------------------------------------------------------------------------
+
+[tool.pyright]
+include = ["src/edit2docs", "tests"]
+exclude = [
+    "src/edit2docs/core",  # ppt-master fork has its own conventions
+    "**/__pycache__",
+    ".venv",
+]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"

edit2docs-0.2.1/src/edit2docs/__init__.py

@@ -0,0 +1,64 @@
+"""edit2docs — AI-agent-native PPTX engine. Korean-first.
+
+Four ways to use it:
+
+* **Library** — ``from edit2docs import generate_doc, edit_doc, ...``
+  (zero infra, works on local files)
+* **Agent tools** — ``from edit2docs.agent_tools import ANTHROPIC_TOOLS,
+  run_tool`` (function-calling schemas + dispatcher)
+* **Local MCP** — ``edit2docs-mcp`` console script (stdio, zero infra)
+* **Hosted service** — ``pip install "edit2docs[server]"`` then
+  ``edit2docs serve`` (FastAPI + jobs + MCP over HTTP; powers the studio)
+
+Exports resolve lazily so ``import edit2docs`` stays fast and the base
+install never touches server-only dependencies.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+__version__ = "0.2.1"
+
+_LAZY: dict[str, str] = {
+    # Unified, extension-dispatched verbs (docx / xlsx / pptx)
+    "generate_doc": ".simple",
+    "edit_doc": ".simple",
+    "preview_doc": ".simple",
+    "set_doc_text": ".simple",
+    "analyze_doc": ".simple",
+    "async_generate_doc": ".simple",
+    "async_edit_doc": ".simple",
+    # PPTX-specific surface (full deck pipeline)
+    "generate_pptx": ".simple",
+    "edit_pptx": ".simple",
+    "preview_pptx": ".simple",
+    "set_pptx_text": ".simple",
+    "analyze_pptx": ".simple",
+    "async_generate_pptx": ".simple",
+    "async_edit_pptx": ".simple",
+    "GenerateResult": ".simple",
+    "EditResult": ".simple",
+    "TextEditsResult": ".simple",
+    # Agent tool surface
+    "ANTHROPIC_TOOLS": ".agent_tools",
+    "run_tool": ".agent_tools",
+    "run_tool_async": ".agent_tools",
+}
+
+__all__ = ["__version__", *sorted(_LAZY)]
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = importlib.import_module(module_name, __name__)
+    value = getattr(module, name)
+    globals()[name] = value  # cache for subsequent lookups
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY))

edit2docs-0.2.1/src/edit2docs/agent_tools.py

@@ -0,0 +1,236 @@
+"""edit2docs as a function-calling tool set for LLM agents.
+
+``ANTHROPIC_TOOLS`` is a ready-to-send ``tools=[...]`` list for the
+Anthropic Messages API; ``run_tool`` / ``run_tool_async`` dispatch a tool
+call to the library facade (:mod:`edit2docs.simple`) and return a
+JSON-safe dict for the tool_result block.
+
+Five format-dispatched verbs cover DOCX, XLSX and PPTX — the file
+extension picks the engine, so agents don't juggle per-format tools.
+
+All tools operate on local file paths. ``generate_doc`` / ``edit_doc``
+need an Anthropic key (``api_key=`` on the dispatcher or
+``ANTHROPIC_API_KEY``); the rest are deterministic and keyless.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+__all__ = ["ANTHROPIC_TOOLS", "TOOL_NAMES", "run_tool", "run_tool_async"]
+
+_DOC_PATH = {
+    "type": "string",
+    "description": "Path to a local document (.docx / .xlsx / .pptx).",
+}
+
+ANTHROPIC_TOOLS: list[dict[str, Any]] = [
+    {
+        "name": "generate_doc",
+        "description": (
+            "Generate a complete document from a one-line intent; the OUTPUT "
+            "file extension picks the engine: .docx (Word report/proposal), "
+            ".xlsx (Excel workbook with styled sheets, real numbers, "
+            "formulas), .pptx (full presentation pipeline — supports "
+            "template/deck_mode/pages). Optionally ground the content in "
+            "source documents. Korean-first; any language works. PPTX "
+            "generation is slow (minutes); DOCX/XLSX take one model call."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "intent": {
+                    "type": "string",
+                    "description": "What the document is for, e.g. '3분기 실적 보고서'.",
+                },
+                "output": {
+                    "type": "string",
+                    "description": "Output path — extension (.docx/.xlsx/.pptx) selects the format.",
+                },
+                "sources": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Optional source document paths (PDF/DOCX/PPTX/XLSX/HTML).",
+                },
+                "template": {
+                    "type": "string",
+                    "description": "PPTX only: existing deck to inherit design from.",
+                },
+                "deck_mode": {
+                    "type": "string",
+                    "enum": ["new", "template_restyle", "template_extend"],
+                    "description": "PPTX only: how to use the template (default new).",
+                },
+                "pages": {
+                    "type": "array",
+                    "items": {"type": "integer"},
+                    "minItems": 2,
+                    "maxItems": 2,
+                    "description": "PPTX only: target [min, max] page count.",
+                },
+                "lang": {"type": "string", "description": "BCP-47, default ko-KR."},
+            },
+            "required": ["intent", "output"],
+        },
+    },
+    {
+        "name": "edit_doc",
+        "description": (
+            "Apply one natural-language edit turn to an existing document "
+            "(.docx/.xlsx/.pptx — extension picks the engine): '2번 문단 "
+            "수치를 15%로 바꿔줘', 'B3 셀을 142로', '3번 슬라이드 제목 바꿔줘'. "
+            "Untouched content survives byte-identical. Question-only "
+            "instructions are answered in `reply` without changing the "
+            "file. Attach reference documents via `sources`."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "doc": _DOC_PATH,
+                "instruction": {"type": "string"},
+                "output": {
+                    "type": "string",
+                    "description": "Output path (default: <input>_edited.<ext>).",
+                },
+                "sources": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Reference document paths for this edit.",
+                },
+                "lang": {"type": "string", "description": "BCP-47, default ko-KR."},
+            },
+            "required": ["doc", "instruction"],
+        },
+    },
+    {
+        "name": "preview_doc",
+        "description": (
+            "Render a document for inspection: .pptx -> one self-contained "
+            "SVG file per slide; .docx/.xlsx -> a markdown rendering "
+            "(preview.md). Deterministic, no LLM, no key."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "doc": _DOC_PATH,
+                "out_dir": {
+                    "type": "string",
+                    "description": "Directory for the preview file(s).",
+                },
+            },
+            "required": ["doc", "out_dir"],
+        },
+    },
+    {
+        "name": "set_doc_text",
+        "description": (
+            "Deterministic targeted edits (instant, no LLM, formatting "
+            "preserved). Addresses come from analyze_doc: .docx -> "
+            "{action: replace|insert_after|delete, para | table/row/col, "
+            "new_text|markdown}; .xlsx -> {action: set_cell|append_rows|"
+            "add_sheet, sheet, cell, value, rows}; .pptx -> {slide, "
+            "shape_id, para, new_text, row/col for tables}. Prefer this "
+            "over edit_doc for plain value/text swaps."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "doc": _DOC_PATH,
+                "edits": {
+                    "type": "array",
+                    "items": {"type": "object"},
+                    "description": "Format-specific edit objects (see tool description).",
+                },
+                "output": {
+                    "type": "string",
+                    "description": "Output path (default: <input>_edited.<ext>).",
+                },
+            },
+            "required": ["doc", "edits"],
+        },
+    },
+    {
+        "name": "analyze_doc",
+        "description": (
+            "Inspect a document's structure and get the exact addresses "
+            "set_doc_text needs: .docx -> paragraph/table-cell outline with "
+            "indices; .xlsx -> sheets, dimensions, sample rows; .pptx -> "
+            "slides, theme, per-paragraph shape ids. Deterministic, no LLM, "
+            "no key. Call this before editing."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {"doc": _DOC_PATH},
+            "required": ["doc"],
+        },
+    },
+]
+
+TOOL_NAMES = [t["name"] for t in ANTHROPIC_TOOLS]
+
+
+async def run_tool_async(
+    name: str, tool_input: dict[str, Any], *, api_key: str | None = None
+) -> dict[str, Any]:
+    """Dispatch one tool call; returns a JSON-safe result dict."""
+    from . import simple
+
+    args = dict(tool_input)
+    if name == "generate_doc":
+        pages_raw = args.pop("pages", None)
+        pages = tuple(pages_raw) if pages_raw and len(pages_raw) == 2 else (8, 12)
+        result = await simple.async_generate_doc(
+            args.pop("intent"),
+            output=args.pop("output"),
+            api_key=api_key,
+            sources=args.pop("sources", None),
+            template=args.pop("template", None),
+            deck_mode=args.pop("deck_mode", "new") or "new",
+            pages=pages,  # type: ignore[arg-type]
+            lang=args.pop("lang", "ko-KR") or "ko-KR",
+        )
+        return {
+            "path": str(result.path),
+            "page_count": result.page_count,
+            "warnings": result.warnings,
+        }
+    if name == "edit_doc":
+        result = await simple.async_edit_doc(
+            args.pop("doc"),
+            args.pop("instruction"),
+            output=args.pop("output", None),
+            api_key=api_key,
+            sources=args.pop("sources", None),
+            lang=args.pop("lang", "ko-KR"),
+        )
+        return {
+            "path": str(result.path),
+            "changed": result.changed,
+            "reply": result.reply,
+            "operations": result.operations,
+        }
+    if name == "preview_doc":
+        rendered = simple.preview_doc(args["doc"], out_dir=args["out_dir"])
+        if isinstance(rendered, list):
+            return {"svg_paths": [str(p) for p in rendered], "page_count": len(rendered)}
+        return {"preview_path": str(rendered)}
+    if name == "set_doc_text":
+        result = simple.set_doc_text(
+            args["doc"], args["edits"], output=args.get("output")
+        )
+        return {
+            "path": str(result.path),
+            "applied": result.applied,
+            "results": result.results,
+        }
+    if name == "analyze_doc":
+        return simple.analyze_doc(args["doc"])
+    raise ValueError(f"unknown edit2docs tool: {name!r} (known: {TOOL_NAMES})")
+
+
+def run_tool(
+    name: str, tool_input: dict[str, Any], *, api_key: str | None = None
+) -> dict[str, Any]:
+    """Sync wrapper for :func:`run_tool_async`."""
+    return asyncio.run(run_tool_async(name, tool_input, api_key=api_key))