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

hwpx_automation/public-modules.json

@@ -0,0 +1,206 @@
+{
+  "schemaVersion": "python-hwpx-automation.public-modules/v1",
+  "scope": "All Python modules shipped by the canonical 6.x distribution. Base-public modules must import without the optional MCP SDK; the five adapter modules require the mcp extra by design.",
+  "moduleCount": 177,
+  "moduleSha256": "4fb2c3852fef3aa83ff1c8ddbbb40feca55889b478cfabfa7e304f25c22d5c06",
+  "basePublicModuleCount": 172,
+  "basePublicModuleSha256": "ae0e52305fae27f664d71c475a9d40041c02b635955259cf9b9a622b81371547",
+  "basePublicModules": [
+    "hwpx_automation",
+    "hwpx_automation.__main__",
+    "hwpx_automation.agent_document",
+    "hwpx_automation.api",
+    "hwpx_automation.blind_eval",
+    "hwpx_automation.capabilities",
+    "hwpx_automation.compat",
+    "hwpx_automation.configuration",
+    "hwpx_automation.core",
+    "hwpx_automation.core.content",
+    "hwpx_automation.core.context",
+    "hwpx_automation.core.diff",
+    "hwpx_automation.core.document",
+    "hwpx_automation.core.formatting",
+    "hwpx_automation.core.handles",
+    "hwpx_automation.core.locations",
+    "hwpx_automation.core.locator",
+    "hwpx_automation.core.plan",
+    "hwpx_automation.core.resources",
+    "hwpx_automation.core.search",
+    "hwpx_automation.core.transactions",
+    "hwpx_automation.core.txn",
+    "hwpx_automation.document_state",
+    "hwpx_automation.errors",
+    "hwpx_automation.execution_lock",
+    "hwpx_automation.form_fill",
+    "hwpx_automation.form_output_models",
+    "hwpx_automation.handlers",
+    "hwpx_automation.handlers._shared",
+    "hwpx_automation.handlers.agent_document",
+    "hwpx_automation.handlers.authoring",
+    "hwpx_automation.handlers.content_edit",
+    "hwpx_automation.handlers.form_fill",
+    "hwpx_automation.handlers.layout_style",
+    "hwpx_automation.handlers.read_export",
+    "hwpx_automation.handlers.specialized",
+    "hwpx_automation.handlers.tracked_changes",
+    "hwpx_automation.handlers.workflow",
+    "hwpx_automation.hwp_converter",
+    "hwpx_automation.hwp_support",
+    "hwpx_automation.hwpx_ops",
+    "hwpx_automation.identity",
+    "hwpx_automation.ingest_adapters",
+    "hwpx_automation.markdown_plan",
+    "hwpx_automation.mcp_cli",
+    "hwpx_automation.metadata.tools_meta",
+    "hwpx_automation.mixed_form",
+    "hwpx_automation.mutation_models",
+    "hwpx_automation.network_policy",
+    "hwpx_automation.office",
+    "hwpx_automation.office.agent",
+    "hwpx_automation.office.agent._batch_verification",
+    "hwpx_automation.office.agent.blueprint",
+    "hwpx_automation.office.agent.blueprint.bundle",
+    "hwpx_automation.office.agent.blueprint.catalog",
+    "hwpx_automation.office.agent.blueprint.dump",
+    "hwpx_automation.office.agent.blueprint.mapping",
+    "hwpx_automation.office.agent.blueprint.model",
+    "hwpx_automation.office.agent.blueprint.native",
+    "hwpx_automation.office.agent.blueprint.replay",
+    "hwpx_automation.office.agent.catalog",
+    "hwpx_automation.office.agent.cli",
+    "hwpx_automation.office.agent.commands",
+    "hwpx_automation.office.agent.document",
+    "hwpx_automation.office.agent.form_plan",
+    "hwpx_automation.office.agent.model",
+    "hwpx_automation.office.agent.path",
+    "hwpx_automation.office.agent.query",
+    "hwpx_automation.office.agent.story",
+    "hwpx_automation.office.authoring",
+    "hwpx_automation.office.authoring.advanced_generators",
+    "hwpx_automation.office.authoring.builder",
+    "hwpx_automation.office.authoring.builder.core",
+    "hwpx_automation.office.authoring.builder.report",
+    "hwpx_automation.office.authoring.design",
+    "hwpx_automation.office.authoring.design._support",
+    "hwpx_automation.office.authoring.design.composer",
+    "hwpx_automation.office.authoring.design.harvest",
+    "hwpx_automation.office.authoring.design.plan",
+    "hwpx_automation.office.authoring.design.profile",
+    "hwpx_automation.office.authoring.design.validator",
+    "hwpx_automation.office.authoring.presets",
+    "hwpx_automation.office.authoring.presets.proposal",
+    "hwpx_automation.office.authoring.report_parser",
+    "hwpx_automation.office.authoring.style_profile",
+    "hwpx_automation.office.authoring.template_analyzer",
+    "hwpx_automation.office.compliance",
+    "hwpx_automation.office.compliance.official_lint",
+    "hwpx_automation.office.compliance.pii",
+    "hwpx_automation.office.document_ops",
+    "hwpx_automation.office.document_ops.comparison",
+    "hwpx_automation.office.document_ops.mail_merge",
+    "hwpx_automation.office.document_ops.redline",
+    "hwpx_automation.office.evalplan",
+    "hwpx_automation.office.evalplan.runtime",
+    "hwpx_automation.office.exam",
+    "hwpx_automation.office.exam.compose",
+    "hwpx_automation.office.exam.ir",
+    "hwpx_automation.office.exam.measure",
+    "hwpx_automation.office.exam.parser",
+    "hwpx_automation.office.exam.profile",
+    "hwpx_automation.office.form_fill",
+    "hwpx_automation.office.form_fill.classification",
+    "hwpx_automation.office.form_fill.fill_residue",
+    "hwpx_automation.office.form_fill.fit",
+    "hwpx_automation.office.form_fill.fit.apply",
+    "hwpx_automation.office.form_fill.fit.engine",
+    "hwpx_automation.office.form_fill.fit.measure",
+    "hwpx_automation.office.form_fill.fit.policy",
+    "hwpx_automation.office.form_fill.fit.report",
+    "hwpx_automation.office.form_fill.fit.seal",
+    "hwpx_automation.office.form_fill.fit.wordbox",
+    "hwpx_automation.office.form_fill.guidance",
+    "hwpx_automation.office.form_fill.quality",
+    "hwpx_automation.office.form_fill.split_run",
+    "hwpx_automation.office.form_fill.template_formfit",
+    "hwpx_automation.office.house_style",
+    "hwpx_automation.office.house_style.composition",
+    "hwpx_automation.office.quality",
+    "hwpx_automation.office.quality.page_guard",
+    "hwpx_automation.office.rendering",
+    "hwpx_automation.office.rendering.block_splits",
+    "hwpx_automation.office.rendering.detectors",
+    "hwpx_automation.office.rendering.diff",
+    "hwpx_automation.office.rendering.fixture_corpus",
+    "hwpx_automation.office.rendering.oracle",
+    "hwpx_automation.office.rendering.page_qa",
+    "hwpx_automation.office.rendering.qa_contracts",
+    "hwpx_automation.office.rendering.qa_metrics",
+    "hwpx_automation.office.rendering.worker",
+    "hwpx_automation.office.utilities",
+    "hwpx_automation.office.utilities.table_compute",
+    "hwpx_automation.ops_services",
+    "hwpx_automation.ops_services._border_fill",
+    "hwpx_automation.ops_services.composition",
+    "hwpx_automation.ops_services.content_layout",
+    "hwpx_automation.ops_services.context",
+    "hwpx_automation.ops_services.form_fields",
+    "hwpx_automation.ops_services.media",
+    "hwpx_automation.ops_services.memo_style",
+    "hwpx_automation.ops_services.package_validation",
+    "hwpx_automation.ops_services.planning",
+    "hwpx_automation.ops_services.preview_export",
+    "hwpx_automation.ops_services.read_query",
+    "hwpx_automation.ops_services.save_policy",
+    "hwpx_automation.ops_services.tables",
+    "hwpx_automation.ops_services.transactions",
+    "hwpx_automation.preview_output_models",
+    "hwpx_automation.quality",
+    "hwpx_automation.quality_generation",
+    "hwpx_automation.runtime_services",
+    "hwpx_automation.storage",
+    "hwpx_automation.tool_contract",
+    "hwpx_automation.upstream",
+    "hwpx_automation.utils",
+    "hwpx_automation.utils.helpers",
+    "hwpx_automation.visual_qa",
+    "hwpx_automation.workflow",
+    "hwpx_automation.workflow.adapters",
+    "hwpx_automation.workflow.dispatcher",
+    "hwpx_automation.workflow.models",
+    "hwpx_automation.workflow.policy",
+    "hwpx_automation.workflow.render_contracts",
+    "hwpx_automation.workflow.render_metrics",
+    "hwpx_automation.workflow.render_queue",
+    "hwpx_automation.workflow.render_security",
+    "hwpx_automation.workflow.render_transport",
+    "hwpx_automation.workflow.rendering",
+    "hwpx_automation.workflow.service",
+    "hwpx_automation.workflow.state_machine",
+    "hwpx_automation.workflow.store",
+    "hwpx_automation.workspace"
+  ],
+  "mcpAdapterModuleCount": 5,
+  "mcpAdapterModuleSha256": "89fa1f67eebb1b370021c6285be567f1926155188f5e2df35a6a4a49b1cffb61",
+  "mcpAdapterModules": [
+    {
+      "module": "hwpx_automation.fastmcp_adapter",
+      "reason": "Imports FastMCP protocol types and implements the adapter boundary."
+    },
+    {
+      "module": "hwpx_automation.handlers.quality_render",
+      "reason": "Returns MCP protocol content blocks from adapter-facing quality handlers."
+    },
+    {
+      "module": "hwpx_automation.runtime",
+      "reason": "Composes the FastMCP runtime and protocol types."
+    },
+    {
+      "module": "hwpx_automation.server",
+      "reason": "Starts the optional MCP transport."
+    },
+    {
+      "module": "hwpx_automation.tool_bindings",
+      "reason": "Binds pure ToolSpec data to FastMCP runtime handlers."
+    }
+  ]
+}

hwpx_automation/py.typed

@@ -0,0 +1 @@
+

hwpx_automation/quality.py

@@ -0,0 +1,351 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Automation quality contract (VisualComplete Phase F).
+
+Every write funnels through the one ``python-hwpx`` SavePipeline gate and reports a
+uniform ``VisualCompleteReport``. This module owns:
+
+* :func:`resolve_policy` — turn a model-facing ``quality`` block into a
+  :class:`~hwpx.quality.QualityPolicy` (default = transparent, i.e. today's
+  open-safety-only behaviour, so the contract is invisible until a caller opts in).
+* :func:`save_through_pipeline` / :func:`visual_complete_block` — run the gate and
+  map the report to an MCP payload (``ok`` / ``visualComplete`` / structured
+  ``errors`` carrying retry-able codes + ``suggestedRetry``).
+* :class:`QualityGateError` — raised when an elevated policy's gate fails so the
+  write is **withheld** (fail-closed) and the model sees the structured error.
+* the **capability handshake** (:func:`capability_state` / :func:`assert_write_capability`)
+  — core/automation/plugin versions + a hash that **fails closed on skew** (e.g. a
+  ``python-hwpx`` too old to expose the SavePipeline gate).
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import os
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from pathlib import Path
+from typing import Any, Mapping
+
+from .configuration import canonical_env_name, env_value
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10 runtime compatibility
+    import tomli as tomllib
+
+from .tool_contract import (
+    MIN_AUTOMATION_VERSION,
+    MIN_MCP_VERSION,
+    MIN_PYTHON_HWPX,
+    MIN_SKILL_VERSION,
+    contract_hash,
+)
+
+# FastMCP's call_tool catches a tool's exception and returns an isError result in
+# a copied context, so the structured gate/skew error can't be caught at the
+# dispatch boundary nor handed back via a ContextVar. A plain module global is
+# shared across that boundary (and across threads): the exceptions stash
+# themselves here on construction; the dispatch handler reads it back to rebuild
+# the structured payload (codes + suggestedRetry). Dispatch is serial per request
+# (clear-then-read brackets each call), so this is not a concurrency hazard.
+_LAST_GATE_ERROR: Any = None
+
+
+def take_last_gate_error() -> Any:
+    """Pop the most recent gate/skew error recorded since the last clear."""
+
+    global _LAST_GATE_ERROR
+    err = _LAST_GATE_ERROR
+    _LAST_GATE_ERROR = None
+    return err
+
+
+def clear_last_gate_error() -> None:
+    global _LAST_GATE_ERROR
+    _LAST_GATE_ERROR = None
+
+
+def _record_gate_error(err: Any) -> None:
+    global _LAST_GATE_ERROR
+    _LAST_GATE_ERROR = err
+
+_QUALITY_ENV = canonical_env_name("QUALITY")
+_REQUIRE_CAPABILITY_ENV = canonical_env_name("REQUIRE_CAPABILITY")
+
+
+# --------------------------------------------------------------------------- #
+# python-hwpx quality stack (imported lazily so this module loads even on a skew).
+# --------------------------------------------------------------------------- #
+def _quality_available() -> bool:
+    return importlib.util.find_spec("hwpx.quality") is not None
+
+
+def package_version(package: str) -> str:
+    module_name = {"python-hwpx": "hwpx", "python-hwpx-automation": "hwpx_automation",
+                   "hwpx-mcp-server": "hwpx_automation"}.get(package)
+    if module_name:
+        spec = importlib.util.find_spec(module_name)
+        origin = Path(spec.origin).resolve() if spec and spec.origin else None
+        if origin is not None:
+            for parent in origin.parents:
+                pyproject = parent / "pyproject.toml"
+                if not pyproject.is_file():
+                    continue
+                try:
+                    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+                    project = data.get("project", {})
+                    if project.get("name") == package and isinstance(project.get("version"), str):
+                        return project["version"]
+                except (OSError, tomllib.TOMLDecodeError):
+                    break
+    try:
+        return _pkg_version(package)
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _version_lt(value: str, minimum: str) -> bool:
+    """True if *value* is an older version than *minimum* (PEP 440 aware).
+
+    Uses ``packaging.version`` so that ``"2.12"`` == ``"2.12.0"`` and a
+    pre-release (``"2.12.0rc1"`` / ``".dev1"``) sorts BEFORE the final release —
+    otherwise a healthy install (or an rc of the boundary) would falsely skew and
+    fail closed.
+    """
+
+    try:
+        from packaging.version import InvalidVersion, Version
+
+        try:
+            return Version(value) < Version(minimum)
+        except InvalidVersion:
+            pass
+    except Exception:  # pragma: no cover - packaging always present via pip
+        pass
+    # Stdlib fallback: zero-pad to equal length so "2.12" is not < "2.12.0".
+    a = [int("".join(c for c in p if c.isdigit()) or 0) for p in value.split(".")]
+    b = [int("".join(c for c in p if c.isdigit()) or 0) for p in minimum.split(".")]
+    width = max(len(a), len(b))
+    a += [0] * (width - len(a))
+    b += [0] * (width - len(b))
+    return a < b
+
+
+# --------------------------------------------------------------------------- #
+# Quality policy resolution.
+# --------------------------------------------------------------------------- #
+_POLICY_KEY_MAP = {
+    "requireOpenSafety": "require_open_safety",
+    "requireVisualComplete": "require_visual_complete",
+    "requireReferenceIntegrity": "require_reference_integrity",
+    "renderCheck": "render_check",
+    "xsdMode": "xsd_mode",
+    "overflowPolicy": "overflow_policy",
+    "layoutLint": "layout_lint",
+    "allowExpertUnsafe": "allow_expert_unsafe",
+}
+
+
+def resolve_policy(quality: Mapping[str, Any] | str | None) -> Any:
+    """Map a model-facing ``quality`` block to a ``QualityPolicy``.
+
+    ``None`` → the ``HWPX_AUTOMATION_QUALITY`` env default (with the supported
+    6.x ``HWPX_MCP_QUALITY`` fallback) → transparent. A string picks a
+    named policy (``transparent`` / ``strict``). A dict elevates from transparent
+    with camelCase overrides (``renderCheck`` / ``overflowPolicy`` / ``layoutLint`` …).
+    """
+
+    from hwpx.quality import QualityPolicy
+
+    if quality is None:
+        quality = env_value("QUALITY", "transparent") or "transparent"
+
+    if isinstance(quality, str):
+        mode = quality.strip().lower()
+        if mode in ("strict", "docx", "full"):
+            return QualityPolicy.strict()
+        return QualityPolicy.transparent()
+
+    if isinstance(quality, Mapping):
+        mode = str(quality.get("mode", "transparent")).lower()
+        base = QualityPolicy.strict() if mode in ("strict", "docx", "full") else QualityPolicy.transparent()
+        changes: dict[str, Any] = {}
+        for key, attr in _POLICY_KEY_MAP.items():
+            if key in quality:
+                changes[attr] = quality[key]
+        return base.with_(**changes) if changes else base
+
+    return QualityPolicy.transparent()
+
+
+# --------------------------------------------------------------------------- #
+# Report → MCP payload.
+# --------------------------------------------------------------------------- #
+def visual_complete_block(report: Any) -> dict[str, Any]:
+    """The model-facing VisualComplete block (codes + suggestedRetry)."""
+
+    errors = [
+        {
+            "code": err.code,
+            "message": err.message,
+            "suggestedRetry": err.suggested_retry,
+        }
+        for err in report.errors
+    ]
+    return {
+        "ok": bool(report.ok),
+        "visualComplete": bool(report.visual_complete),
+        "status": report.visual_complete_status,
+        "renderChecked": bool(report.render_checked),
+        "errors": errors,
+        "errorCodes": [err.code for err in report.errors],
+        "warnings": list(report.warnings),
+        "suggestedRetry": _aggregate_retry(report),
+        "form": report.form.to_dict(),
+        "layout": report.layout.to_dict(),
+    }
+
+
+def _aggregate_retry(report: Any) -> dict[str, Any] | None:
+    for err in report.errors:
+        if err.suggested_retry:
+            return {"code": err.code, **err.suggested_retry}
+    if report.errors:
+        return {"code": report.errors[0].code}
+    return None
+
+
+class QualityGateError(RuntimeError):
+    """An elevated-policy gate failed; the write was withheld (fail-closed)."""
+
+    def __init__(self, report: Any) -> None:
+        block = visual_complete_block(report)
+        self.report = report
+        self.block = block
+        self.code = (block["errorCodes"] or ["VISUAL_COMPLETE_FAILED"])[0]
+        message = "; ".join(e["message"] for e in block["errors"]) or "visual_complete gate failed"
+        _record_gate_error(self)
+        super().__init__(message)
+
+
+def save_through_pipeline(document: Any, output_path: Any, *, quality: Any = None) -> Any:
+    """Save *document* through the SavePipeline; return the ``VisualCompleteReport``.
+
+    Raises :class:`QualityGateError` when the gate fails (so the caller withholds
+    the output — fail-closed). Open-safety serialize failures still raise the
+    library's ``ValueError`` as before.
+    """
+
+    # Accept a ready QualityPolicy, or resolve None/str/dict into one.
+    if quality is None or isinstance(quality, (str, Mapping)):
+        policy = resolve_policy(quality)
+    else:
+        policy = quality
+    from .office.rendering import bind_document_rendering
+
+    with bind_document_rendering(document):
+        report = document.save_report(output_path, quality=policy)
+    if not report.ok:
+        raise QualityGateError(report)
+    return report
+
+
+# --------------------------------------------------------------------------- #
+# Capability handshake (fail-closed on skew).
+# --------------------------------------------------------------------------- #
+def capability_state() -> dict[str, Any]:
+    """Core/automation/plugin versions + a fingerprint hash + any version skew."""
+
+    core = package_version("python-hwpx")
+    automation = package_version("python-hwpx-automation")
+    plugin = os.environ.get("HWPX_SKILL_VERSION", "unknown")
+    has_pipeline = _quality_available()
+
+    skew: list[str] = []
+    if not has_pipeline:
+        skew.append("python-hwpx is missing the hwpx.quality SavePipeline gate")
+    elif _version_lt(core, MIN_PYTHON_HWPX):
+        skew.append(f"python-hwpx {core} < required {MIN_PYTHON_HWPX}")
+    if automation == "unknown":
+        skew.append("python-hwpx-automation version is unresolved")
+    elif _version_lt(automation, MIN_AUTOMATION_VERSION):
+        skew.append(
+            f"python-hwpx-automation {automation} < required {MIN_AUTOMATION_VERSION}"
+        )
+    if plugin != "unknown" and _version_lt(plugin, MIN_SKILL_VERSION):
+        skew.append(f"hwpx skill {plugin} < required {MIN_SKILL_VERSION}")
+
+    fingerprint = hashlib.sha256(
+        "|".join(
+            [
+                "core", core,
+                "automation", automation,
+                "plugin", plugin,
+                "pipeline", str(has_pipeline),
+                "toolContract", contract_hash(),
+            ]
+        ).encode()
+    ).hexdigest()[:16]
+
+    return {
+        "versions": {
+            "core": core,
+            "automation": automation,
+            # 6.x compatibility alias.
+            "mcp": automation,
+            "plugin": plugin,
+        },
+        "minPythonHwpx": MIN_PYTHON_HWPX,
+        "minAutomationVersion": MIN_AUTOMATION_VERSION,
+        # 6.x compatibility alias.
+        "minMcpVersion": MIN_MCP_VERSION,
+        "minSkillVersion": MIN_SKILL_VERSION,
+        "savePipelineAvailable": has_pipeline,
+        "toolContractHash": contract_hash(),
+        "hash": fingerprint,
+        "skew": skew,
+        "ok": not skew,
+    }
+
+
+def fail_closed_enabled() -> bool:
+    return env_value("REQUIRE_CAPABILITY", "1") != "0"
+
+
+def assert_write_capability() -> None:
+    """Raise :class:`QualityGateError`-style failure if capability is skewed.
+
+    Fail-closed: a write must not proceed when the installed quality stack can't
+    honour the gate (e.g. a stale python-hwpx). Disable with
+    ``HWPX_AUTOMATION_REQUIRE_CAPABILITY=0`` for an expert/debug bypass. The
+    old ``HWPX_MCP_REQUIRE_CAPABILITY`` spelling remains a 6.x fallback.
+    """
+
+    if not fail_closed_enabled():
+        return
+    state = capability_state()
+    if not state["ok"]:
+        raise CapabilitySkewError(state)
+
+
+class CapabilitySkewError(RuntimeError):
+    """The core/automation/plugin handshake detected skew; writes fail closed."""
+
+    code = "CAPABILITY_SKEW"
+
+    def __init__(self, state: Mapping[str, Any]) -> None:
+        self.state = dict(state)
+        _record_gate_error(self)
+        super().__init__("; ".join(state.get("skew", [])) or "capability skew detected")
+
+
+__all__ = [
+    "MIN_PYTHON_HWPX",
+    "resolve_policy",
+    "save_through_pipeline",
+    "visual_complete_block",
+    "QualityGateError",
+    "CapabilitySkewError",
+    "capability_state",
+    "assert_write_capability",
+    "fail_closed_enabled",
+    "package_version",
+]