Content
<p align="center">
<h1 align="center">python-hwpx-automation</h1>
<p align="center">
<strong>Python Automation Layer for HWPX Document Authoring, Form Filling, and Workflow</strong>
</p>
<p align="center">
<a href="https://pypi.org/project/python-hwpx-automation/"><img src="https://img.shields.io/pypi/v/python-hwpx-automation?color=blue&label=PyPI" alt="PyPI"></a>
<a href="https://pepy.tech/project/python-hwpx-automation"><img src="https://static.pepy.tech/badge/python-hwpx-automation/month" alt="Downloads"></a>
<a href="https://pypi.org/project/python-hwpx-automation/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx-automation" alt="Python"></a>
<a href="https://github.com/airmang/python-hwpx-automation/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx-automation/tests.yml?branch=main&label=tests" alt="Tests"></a>
<a href="https://github.com/airmang/python-hwpx-automation/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
</p>
</p>
<!-- release-state: released -->
> [!NOTE]
> The current release train is `python-hwpx 5.0.1 → python-hwpx-automation 6.0.4 → hwpx-plugin 1.0.0` (contract `0ce938371f0b55a6`, released on 2026-07-28). The core/automation PyPI and plugin GitHub Release/marketplace/installation have been verified.
An application layer providing document authoring, form filling, and secure agent workflows on top of the [python-hwpx](https://github.com/airmang/python-hwpx) engine. The basic installation uses Python API and `hwpx` CLI without MCP, and the MCP server can be added with the `[mcp]` extra when needed.
| | Repository | Role |
|---|---|---|
| 📦 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | Pure Python engine for reading, editing, and creating HWPX documents |
| 🔌 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | Authoring, form filling workflow, `hwpx` CLI, and optional MCP server |
| 🎯 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | Plugin/skill bundles to help agents choose the right tools |
## Getting Started with Python Automation
```bash
pip install python-hwpx-automation
```
```python
from hwpx_automation import create_document_from_plan
document = create_document_from_plan(
{
"schemaVersion": "hwpx.document_plan.v1",
"title": "Meeting Result",
"blocks": [{"type": "paragraph", "text": "Decisions"}],
}
)
document.save_to_path("meeting-result.hwpx")
```
`python -m hwpx_automation --help` and `hwpx help` execute the same task CLI.
## Getting Started with MCP Adapter
```bash
pip install "python-hwpx-automation[mcp]"
hwpx-automation-mcp
```
MCP client configuration file with the following block to capture the `hwpx` server — Claude Desktop uses `claude_desktop_config.json`, VS Code uses `.vscode/mcp.json` (key is `servers` instead of `mcpServers`), Gemini CLI uses `~/.gemini/settings.json`, and Cursor/Windsurf use their respective MCP configuration files.
```json
{
"mcpServers": {
"hwpx": {
"command": "uvx",
"args": [
"--from",
"python-hwpx-automation[mcp]==6.0.4",
"hwpx-automation-mcp"
],
"env": {
"HWPX_AUTOMATION_WORKSPACE_ROOTS": "[\"~/Documents\"]"
}
}
}
}
```
Specify the folders containing documents in `HWPX_AUTOMATION_WORKSPACE_ROOTS`. Use absolute paths or `~` for user directories. Windows paths use double backslashes, e.g., `"[\"C:\\\\hwpx\"]"`. Empty values will cause GUI clients to launch servers in system directories, blocking all document paths — it is recommended to specify the paths from the beginning.
> To read non-HWPX documents (PDF/DOCX/XLSX/HTML/TXT) using `document_to_markdown`, install the MarkItDown adapter with `pip install "python-hwpx-automation[ingest]"`. Requirements: `Python >= 3.10` and `python-hwpx >= 5.0.0`.
Existing `hwpx-mcp-server` deployments, imports, consoles, and configuration keys continue to work during the 6.x period — see the full list and compatibility rules in [6.x Compatibility Surface](docs/compatibility-6x.md).
## Capabilities
In basic mode, it provides multiple HWPX tools, and in advanced mode (`HWPX_AUTOMATION_ADVANCED=1`), additional inspection and verification tools are added.
- **Reading and Exploration** — `get_document_info`, `get_document_map` (outline, table map, and anchors in one call), `find_text` (no saving)
- **Search and Replacement** — `search_and_replace`, `apply_document_commands` (applying edit atoms with dry-run, rollback, and idempotence keys), `add_tracked_edit` (change tracking)
- **Table and Form Filling** — `analyze_form_fill` → `apply_form_fill` → `verify_form_fill` byte-preserving transactions, `table_compute` (sums and subtotals)
- **Document Creation and Official Documents** — declarative `create_document_from_plan`, `inspect_official_document_style` (administrative regulation lint), `mail_merge`
- **Templates, Images, and Generators** — `set_paragraph_format` and `set_page_setup`, `insert_picture`, photo layouts, nameplates, and organization charts
- **Preview, Extraction, Recovery, and Diagnostics** — `render_preview` (HTML/PNG self-verification), `hwpx_to_markdown`, `repair_hwpx`, `mcp_server_health`
See [Use Cases](docs/use-cases.md) and [Skill-First Workflows](docs/skill-first-workflows.md) for more information.
## Safe Usage
There is no need to memorize all the tools at once. Typically, the workflow is:
1. **Read** — `get_document_info` → `get_document_outline`/`get_document_text` → `find_text`, `get_table_map` to understand the necessary parts (no saving)
2. **Safe Editing** — create a copy with `copy_document`, apply the smallest changes (`search_and_replace`, `set_table_cell_text`, `apply_document_commands`), re-read and verify, and then deliver the reviewed copy.
The key is **copy first, smallest edit, and re-read after edits**. Editing tools save immediately, so review tasks must be done on a copy.
The model only sends operations/plans and does not directly edit raw XML. The standard save path through python-hwpx's single `SavePipeline` gate checks for integrity, XML, OPC/ID, and safe opening, and if the gate fails, it does not write anything. Capability handshake blocks version and hash skew with fail-closed.
## Environment Variables
| Variable | Description | Default Value |
|---|---|---|
| `HWPX_AUTOMATION_WORKSPACE_ROOTS` | JSON array of allowed workspace absolute paths (supports multiple roots) | unset → process cwd. degenerate cwd is rejected with `WORKSPACE_ROOT_INVALID` |
| `HWPX_AUTOMATION_MAX_CHARS` | Default maximum length for text return tools | `10000` |
| `HWPX_AUTOMATION_AUTOBACKUP` | Create `.bak` backup before saving if `1` | `1` |
| `HWPX_AUTOMATION_ADVANCED` | Enable advanced tools if `1` | `0` |
| `HWPX_AUTOMATION_FETCH_TIMEOUT_SECONDS` | URL-based HWPX fetch timeout | `20.0` |
| `HWPX_AUTOMATION_ALLOW_PRIVATE_NETWORK` | Allow trusted private/loopback HTTPS targets if `1`. Link-local, metadata, and reserved addresses are still blocked | `0` |
| `HWPX_AUTOMATION_QUALITY` | Global default save gate policy (`transparent`/`strict`). Tool-specific `quality` takes priority | `transparent` |
| `HWPX_AUTOMATION_REQUIRE_CAPABILITY` | Disable capability skew fail-closed if `0` (for diagnostics/experts) | `1` |
| `HWPX_AUTOMATION_WORKFLOW_STORE` | Durable workflow SQLite path. Takes priority over existing `HWPX_WORKFLOW_STORE` | existing 6.x state path |
| `LOG_LEVEL` | Log level | `INFO` |
Existing keys with the same suffix, `HWPX_MCP_*`, are maintained as fallbacks during the 6.x period, and `HWPX_AUTOMATION_*` takes priority when both keys are present. See [6.x Compatibility Surface](docs/compatibility-6x.md) for the complete list of preserved keys and workflow DB path rules.
Paths are rejected for traversal outside the workspace and symlink escape, and URL inputs are restricted to HTTPS and public IPs. For concurrency considerations on hosts without atomic rename, see the [Hardening Guide](docs/hardening_guide.md).
## Contributing
[Good First Issues](https://github.com/airmang/python-hwpx-automation/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) ·
[Milestones](https://github.com/airmang/python-hwpx-automation/milestones) ·
[Discussions](https://github.com/airmang/python-hwpx-automation/discussions) ·
[CONTRIBUTING](CONTRIBUTING.md) ·
[CHANGELOG](CHANGELOG.md)
```bash
python -m pip install -e ".[test]" # Test dependencies
python -m pytest -q # Full tests
python scripts/run_conformance.py run \
--tier structural --check tests/conformance/golden/structural.json
```
## Acknowledgments
Built on top of the [python-hwpx](https://github.com/airmang/python-hwpx) core library, with gratitude to the following open standards and projects:
- **[OWPML — Open Word Processor Markup Language (KS X 6101)](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — Korean industrial standard for HWPX
- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML element structure reference model · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — Oracle sample corpus
- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — Idempotence and verification gate design inspiration
## License and Maintainer
Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)
