python-hwpx-automation 6.0.3__py3-none-any.whl

hwpx_automation/identity.json

@@ -0,0 +1,263 @@
+{
+  "schemaVersion": "python-hwpx-automation.identity/v1",
+  "product": "python-hwpx-automation",
+  "releaseMajor": 6,
+  "releaseState": {
+    "status": "release-approved",
+    "candidate": {
+      "pythonHwpx": "5.0.1",
+      "canonicalDistribution": "python-hwpx-automation",
+      "canonicalAutomation": "6.0.3",
+      "compatibilityDistribution": "hwpx-mcp-server",
+      "compatibility": "6.0.3",
+      "plugin": "1.0.0",
+      "contractHash": "0ce938371f0b55a6"
+    },
+    "currentPublic": {
+      "pythonHwpx": "4.2.0",
+      "primaryDistribution": "hwpx-mcp-server",
+      "primaryApplication": "5.1.0",
+      "plugin": "0.8.0",
+      "contractHash": "429cb6706323e762"
+    },
+    "promotionGate": "Three states are mandatory: unreleased-candidate while auditing; release-approved only after separate owner approval and while currentPublic still names the previously observed coherent stack; released only in a follow-up commit after remote truth is observed for core, canonical automation, the compatibility distribution, the plugin GitHub release, the marketplace entry, and a real marketplace install. The automation tag workflow publishes only release-approved, leaves currentPublic unchanged, and hands an attached receipt to plugin publication."
+  },
+  "identifiers": [
+    {
+      "surface": "repository",
+      "value": "airmang/python-hwpx-automation",
+      "classification": "canonical"
+    },
+    {
+      "surface": "distribution",
+      "value": "python-hwpx-automation",
+      "classification": "canonical"
+    },
+    {
+      "surface": "import-namespace",
+      "value": "hwpx_automation",
+      "classification": "canonical"
+    },
+    {
+      "surface": "task-console",
+      "value": "hwpx",
+      "classification": "canonical"
+    },
+    {
+      "surface": "mcp-console",
+      "value": "hwpx-automation-mcp",
+      "classification": "canonical"
+    },
+    {
+      "surface": "fastmcp-server-info-name",
+      "value": "python-hwpx-automation",
+      "classification": "canonical"
+    },
+    {
+      "surface": "host-config-key",
+      "value": "hwpx",
+      "classification": "host-local-alias"
+    },
+    {
+      "surface": "environment-prefix",
+      "value": "HWPX_AUTOMATION_",
+      "classification": "canonical"
+    },
+    {
+      "surface": "distribution",
+      "value": "hwpx-mcp-server",
+      "classification": "compatibility"
+    },
+    {
+      "surface": "import-namespace",
+      "value": "hwpx_mcp_server",
+      "classification": "compatibility"
+    },
+    {
+      "surface": "mcp-console",
+      "value": "hwpx-mcp-server",
+      "classification": "compatibility"
+    },
+    {
+      "surface": "environment-prefix",
+      "value": "HWPX_MCP_",
+      "classification": "compatibility"
+    },
+    {
+      "surface": "capability-version-field",
+      "value": "versions.automation",
+      "classification": "canonical"
+    },
+    {
+      "surface": "capability-version-field",
+      "value": "versions.mcp",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "capability-floor-field",
+      "value": "minAutomationVersion",
+      "classification": "canonical"
+    },
+    {
+      "surface": "capability-floor-field",
+      "value": "minMcpVersion",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "contract-floor-constant",
+      "value": "MIN_AUTOMATION_VERSION",
+      "classification": "canonical"
+    },
+    {
+      "surface": "contract-floor-constant",
+      "value": "MIN_MCP_VERSION",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "protocol-error-schema",
+      "value": "hwpx.mcp-error/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-receipt-schema",
+      "value": "hwpx-mcp.authoring-runtime-owner/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-receipt-schema",
+      "value": "hwpx-mcp.compliance-quality-utilities-owner/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-receipt-schema",
+      "value": "hwpx-mcp.document-operations-owner/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-receipt-schema",
+      "value": "hwpx-mcp.evalplan-runtime-owner/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-receipt-schema",
+      "value": "hwpx-mcp.exam-runtime-owner/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-receipt-schema",
+      "value": "hwpx-mcp.form-fill-runtime-owner/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-receipt-schema",
+      "value": "hwpx-mcp.form-fill-runtime-parity/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-receipt-schema",
+      "value": "hwpx-mcp.visual-runtime-owner/v1",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "frozen-parity-receipt-field",
+      "value": "mcpRuntimeMembers",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "workflow-state-environment",
+      "value": "HWPX_AUTOMATION_WORKFLOW_STORE",
+      "classification": "canonical"
+    },
+    {
+      "surface": "workflow-state-environment",
+      "value": "HWPX_WORKFLOW_STORE",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "workflow-state-path",
+      "value": "${XDG_STATE_HOME:-~/.local/state}/hwpx-mcp-server/workflows.sqlite3",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "render-queue-principal",
+      "value": "hwpx-mcp-server",
+      "classification": "compatibility-preserved"
+    },
+    {
+      "surface": "render-integration-environment",
+      "value": "HWPX_RENDER_QUEUE_ROOT",
+      "classification": "integration-preserved"
+    },
+    {
+      "surface": "render-integration-environment",
+      "value": "HWPX_RENDER_QUEUE_URL",
+      "classification": "integration-preserved"
+    },
+    {
+      "surface": "render-integration-environment",
+      "value": "HWPX_RENDER_QUEUE_SECRET",
+      "classification": "integration-preserved"
+    },
+    {
+      "surface": "render-integration-environment",
+      "value": "HWPX_RENDER_TRANSPORT_AUTH",
+      "classification": "integration-preserved"
+    },
+    {
+      "surface": "render-integration-environment",
+      "value": "HWPX_RENDER_CA_FILE",
+      "classification": "integration-preserved"
+    },
+    {
+      "surface": "render-integration-environment",
+      "value": "HWPX_RENDER_CLIENT_CERT_FILE",
+      "classification": "integration-preserved"
+    },
+    {
+      "surface": "render-integration-environment",
+      "value": "HWPX_RENDER_CLIENT_KEY_FILE",
+      "classification": "integration-preserved"
+    },
+    {
+      "surface": "workflow-security-environment",
+      "value": "HWPX_WORKFLOW_ENCRYPTION_KEY",
+      "classification": "capability-preserved"
+    },
+    {
+      "surface": "oracle-capability-environment",
+      "value": "HWPX_ORACLE_STRUCTURAL_ONLY",
+      "classification": "capability-preserved"
+    },
+    {
+      "surface": "oracle-capability-environment",
+      "value": "HWPX_ORACLE_BUDGET_SECONDS",
+      "classification": "capability-preserved"
+    },
+    {
+      "surface": "plugin-integration-environment",
+      "value": "HWPX_SKILL_VERSION",
+      "classification": "integration-preserved"
+    },
+    {
+      "surface": "plugin-integration-environment",
+      "value": "HWPX_PLUGIN_ROOT",
+      "classification": "integration-preserved"
+    }
+  ],
+  "compatibilityPolicy": {
+    "supportedThroughMajor": 6,
+    "removalNotBeforeMajor": 7,
+    "minimumPublicNoticeDays": 90,
+    "requiresObservedUsageWindow": true,
+    "requiresSeparateOwnerApproval": true,
+    "statePathMigrationInMajor6": false
+  },
+  "notes": {
+    "hostConfigKey": "The key is a host-local alias, not the MCP protocol identity.",
+    "environmentPrecedence": "HWPX_AUTOMATION_* wins; HWPX_MCP_* remains a 6.x fallback.",
+    "preservedWireIdentifiers": "The public hwpx.mcp-error/v1 schema, versions.mcp/minMcpVersion/MIN_MCP_VERSION aliases, frozen hwpx-mcp.* architecture receipt IDs, and mcpRuntimeMembers parity-receipt field remain exact in 6.x. They are compatibility identifiers, not statements that MCP owns the automation product.",
+    "preservedIntegrationEnvironment": "Product-neutral HWPX_RENDER_*, HWPX_WORKFLOW_ENCRYPTION_KEY, HWPX_ORACLE_*, HWPX_SKILL_VERSION, and HWPX_PLUGIN_ROOT names do not encode the former MCP product identity. They remain unchanged and are not aliases in the HWPX_AUTOMATION_ transition.",
+    "statePath": "HWPX_AUTOMATION_WORKFLOW_STORE wins over the prior HWPX_WORKFLOW_STORE override; the existing hwpx-mcp-server on-disk default remains in 6.x to avoid silent workflow loss.",
+    "renderQueuePrincipal": "The signed queue principal remains hwpx-mcp-server in 6.x so queued work and worker authorization do not split during the rename."
+  }
+}

hwpx_automation/identity.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Load the installed product-identity contract."""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+from typing import Any
+
+
+def product_identity() -> dict[str, Any]:
+    """Return a detached copy of the installed identity manifest."""
+
+    resource = files("hwpx_automation").joinpath("identity.json")
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+__all__ = ["product_identity"]

hwpx_automation/ingest_adapters.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Optional document-ingest adapters for the MCP server layer."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any, BinaryIO
+
+from hwpx.ingest import (
+    DocumentIngestError,
+    DocumentIngestResult,
+    DocumentSourceInfo,
+)
+
+
+class MissingMarkItDownDependency(DocumentIngestError):
+    """Raised when the optional MarkItDown runtime is not installed."""
+
+
+class MarkItDownAdapter:
+    """Fallback converter that delegates non-HWPX sources to Microsoft MarkItDown."""
+
+    name = "MarkItDownAdapter"
+
+    def accepts(self, file_stream: BinaryIO, source_info: DocumentSourceInfo) -> bool:
+        del file_stream
+        extension = (source_info.extension or "").lower()
+        return extension != ".hwpx"
+
+    def convert(
+        self,
+        file_stream: BinaryIO,
+        source_info: DocumentSourceInfo,
+        **kwargs: Any,
+    ) -> DocumentIngestResult:
+        del kwargs
+        markitdown_cls = _load_markitdown_class()
+        source_path = _source_path(file_stream, source_info)
+        result = markitdown_cls().convert(str(source_path))
+        markdown = _extract_markdown(result)
+        return DocumentIngestResult(
+            markdown=markdown,
+            source_info=source_info,
+            source_format=(source_info.extension or "unknown").lstrip(".") or "unknown",
+            engine="markitdown",
+            metadata={"converter": self.name},
+            warnings=[
+                "Converted by optional MarkItDown adapter; layout fidelity is not claimed.",
+            ],
+            lossiness="unknown",
+        )
+
+
+def _load_markitdown_class() -> type:
+    try:
+        from markitdown import MarkItDown
+    except ImportError as exc:
+        raise MissingMarkItDownDependency(
+            "install python-hwpx-automation[ingest] (or hwpx-mcp-server[ingest]) "
+            "to enable non-HWPX document ingest"
+        ) from exc
+    return MarkItDown
+
+
+def _source_path(file_stream: BinaryIO, source_info: DocumentSourceInfo) -> Path:
+    if source_info.local_path:
+        return Path(source_info.local_path)
+
+    suffix = source_info.extension or ""
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+        start_pos = file_stream.tell()
+        tmp.write(file_stream.read())
+        file_stream.seek(start_pos)
+        return Path(tmp.name)
+
+
+def _extract_markdown(result: Any) -> str:
+    for attr in ("text_content", "markdown", "text"):
+        value = getattr(result, attr, None)
+        if isinstance(value, str):
+            return value
+    if isinstance(result, str):
+        return result
+    raise ValueError("MarkItDown result did not include Markdown text")

hwpx_automation/markdown_plan.py

@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Markdown-to-document-plan bridge."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class MarkdownPlanResult:
+    plan: dict[str, Any]
+    warnings: list[str]
+
+
+def markdown_to_document_plan(
+    markdown: str,
+    *,
+    title: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    style_preset: str = "standard_korean_business",
+) -> MarkdownPlanResult:
+    """Convert a conservative Markdown subset into ``hwpx.document_plan.v1``."""
+
+    warnings: list[str] = []
+    blocks: list[dict[str, Any]] = []
+    lines = (markdown or "").replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    resolved_title = (title or "").strip()
+    index = 0
+
+    while index < len(lines):
+        line = lines[index]
+        stripped = line.strip()
+        if not stripped:
+            index += 1
+            continue
+
+        if table := _parse_table(lines, index):
+            table_block, next_index = table
+            blocks.append(table_block)
+            index = next_index
+            continue
+
+        heading = _parse_heading(stripped)
+        if heading is not None:
+            level, text = heading
+            if not resolved_title and level == 1 and not blocks:
+                resolved_title = text
+            else:
+                blocks.append({"type": "heading", "level": min(level, 3), "text": text})
+                if level > 3:
+                    warnings.append(f"Heading level {level} was clamped to document_plan level 3.")
+            index += 1
+            continue
+
+        if _is_list_item(stripped):
+            items, next_index, ordered = _collect_list(lines, index)
+            blocks.append({"type": "bullets", "items": items})
+            if ordered:
+                warnings.append("Ordered Markdown lists were converted to bullet blocks.")
+            index = next_index
+            continue
+
+        paragraph, next_index = _collect_paragraph(lines, index)
+        if paragraph:
+            blocks.append({"type": "paragraph", "text": paragraph})
+        index = next_index
+
+    if not resolved_title:
+        resolved_title = _title_from_blocks(blocks) or "Markdown Import"
+
+    if not blocks:
+        blocks.append({"type": "paragraph", "text": "작성 필요"})
+        warnings.append("Markdown had no content blocks; inserted an empty paragraph placeholder.")
+
+    quality_gates = {
+        "validatePackage": True,
+        "validateDocument": True,
+        "reopen": True,
+        "minNonEmptyParagraphs": max(1, _non_empty_block_count(blocks)),
+        "visualReviewRequired": True,
+    }
+    return MarkdownPlanResult(
+        plan={
+            "schemaVersion": "hwpx.document_plan.v1",
+            "title": resolved_title,
+            "metadata": _string_metadata(metadata or {}),
+            "stylePreset": style_preset,
+            "blocks": blocks,
+            "qualityGates": quality_gates,
+        },
+        warnings=warnings,
+    )
+
+
+def _parse_heading(stripped: str) -> tuple[int, str] | None:
+    match = re.match(r"^(#{1,6})\s+(.+?)\s*#*\s*$", stripped)
+    if not match:
+        return None
+    return len(match.group(1)), match.group(2).strip()
+
+
+def _is_list_item(stripped: str) -> bool:
+    return bool(re.match(r"^([-+*])\s+.+", stripped) or re.match(r"^\d+[.)]\s+.+", stripped))
+
+
+def _collect_list(lines: list[str], index: int) -> tuple[list[str], int, bool]:
+    items: list[str] = []
+    ordered = False
+    while index < len(lines):
+        stripped = lines[index].strip()
+        unordered = re.match(r"^[-+*]\s+(.+)$", stripped)
+        numbered = re.match(r"^\d+[.)]\s+(.+)$", stripped)
+        if unordered:
+            items.append(unordered.group(1).strip())
+        elif numbered:
+            ordered = True
+            items.append(numbered.group(1).strip())
+        else:
+            break
+        index += 1
+    return items, index, ordered
+
+
+def _collect_paragraph(lines: list[str], index: int) -> tuple[str, int]:
+    parts: list[str] = []
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if not stripped or _parse_heading(stripped) or _is_list_item(stripped) or _parse_table(lines, index):
+            break
+        parts.append(stripped)
+        index += 1
+    return " ".join(parts).strip(), index
+
+
+def _parse_table(lines: list[str], index: int) -> tuple[dict[str, Any], int] | None:
+    if index + 1 >= len(lines):
+        return None
+    header = lines[index].strip()
+    divider = lines[index + 1].strip()
+    if not _looks_like_table_row(header) or not _looks_like_divider(divider):
+        return None
+
+    labels = _split_table_row(header)
+    if not labels:
+        return None
+    keys = [f"col{col_index + 1}" for col_index in range(len(labels))]
+    rows: list[dict[str, str]] = []
+    index += 2
+    while index < len(lines) and _looks_like_table_row(lines[index].strip()):
+        cells = _split_table_row(lines[index].strip())
+        row = {
+            key: cells[col_index].strip() if col_index < len(cells) else ""
+            for col_index, key in enumerate(keys)
+        }
+        rows.append(row)
+        index += 1
+
+    return {
+        "type": "table",
+        "columns": [
+            {"key": key, "label": label.strip() or key}
+            for key, label in zip(keys, labels)
+        ],
+        "rows": rows,
+    }, index
+
+
+def _looks_like_table_row(line: str) -> bool:
+    return "|" in line and len(_split_table_row(line)) >= 2
+
+
+def _looks_like_divider(line: str) -> bool:
+    cells = _split_table_row(line)
+    return bool(cells) and all(re.match(r"^:?-{3,}:?$", cell.strip()) for cell in cells)
+
+
+def _split_table_row(line: str) -> list[str]:
+    stripped = line.strip()
+    if stripped.startswith("|"):
+        stripped = stripped[1:]
+    if stripped.endswith("|"):
+        stripped = stripped[:-1]
+    return [cell.replace(r"\|", "|").strip() for cell in stripped.split("|")]
+
+
+def _title_from_blocks(blocks: list[dict[str, Any]]) -> str:
+    for block in blocks:
+        text = str(block.get("text") or "").strip()
+        if block.get("type") == "heading" and text:
+            return text
+    for block in blocks:
+        text = str(block.get("text") or "").strip()
+        if text:
+            return text[:80]
+    return ""
+
+
+def _string_metadata(metadata: Mapping[str, Any]) -> dict[str, str]:
+    return {
+        str(key): str(value)
+        for key, value in metadata.items()
+        if value is not None and str(value).strip()
+    }
+
+
+def _non_empty_block_count(blocks: list[dict[str, Any]]) -> int:
+    count = 0
+    for block in blocks:
+        kind = block.get("type")
+        if kind in {"heading", "paragraph"} and str(block.get("text") or "").strip():
+            count += 1
+        elif kind == "bullets":
+            count += len(block.get("items") or [])
+    return count

hwpx_automation/mcp_cli.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Guarded entry point for the optional MCP adapter."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+
+_INSTALL_HINT = (
+    'MCP support is optional. Install it with '
+    '"python-hwpx-automation[mcp]" and retry.'
+)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Start the MCP adapter or fail with an actionable extra-install hint."""
+
+    try:
+        from .server import main as server_main
+    except ModuleNotFoundError as exc:
+        if exc.name == "mcp" or (exc.name or "").startswith("mcp."):
+            print(_INSTALL_HINT, file=sys.stderr)
+            raise SystemExit(2) from exc
+        raise
+    server_main(list(argv) if argv is not None else None)
+
+
+if __name__ == "__main__":
+    main()

hwpx_automation/metadata/tools_meta.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Static metadata used for hardened tool responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict
+
+
+@dataclass(frozen=True)
+class ExampleTemplate:
+    tool: str
+    example_json: str
+
+    def render(self, plan_id: str) -> Dict[str, str]:
+        return {
+            "tool": self.tool,
+            "exampleJson": self.example_json.replace("<plan-id>", plan_id),
+        }
+
+
+PLAN_NEXT_ACTION = ExampleTemplate(
+    tool="hwpx.preview_edit",
+    example_json='{"planId":"<plan-id>"}',
+)
+
+PREVIEW_NEXT_ACTION = ExampleTemplate(
+    tool="hwpx.apply_edit",
+    example_json='{"planId":"<plan-id>","confirm":true}',
+)
+
+APPLY_BAD_EXAMPLE = ExampleTemplate(
+    tool="hwpx.apply_edit",
+    example_json='{"planId":"<plan-id>"}',
+)
+
+ERROR_PREVIEW_REQUIRED = ExampleTemplate(
+    tool="hwpx.preview_edit",
+    example_json='{"planId":"<plan-id>"}',
+)