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

hwpx_automation/office/rendering/qa_metrics.py

@@ -0,0 +1,241 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Frozen-corpus metrics for deterministic visual QA."""
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from .fixture_corpus import FixtureCorpus
+from .page_qa import inspect_fixture_case
+from .qa_contracts import (
+    TAXONOMY_VERSION,
+    DefectCategory,
+    FindingSeverity,
+    VerdictStatus,
+)
+
+
+DEFAULT_MINIMUM_CATEGORY_SAMPLES = 5
+GATE_THRESHOLDS = {
+    "criticalRecall": 0.95,
+    "criticalPrecision": 0.90,
+    "defectFalseAcceptanceRate": 0.01,
+    "cleanFalseRejectionRate": 0.01,
+}
+
+
+def _wilson(successes: int, total: int, z: float = 1.959963984540054) -> list[float] | None:
+    if total <= 0:
+        return None
+    p = successes / total
+    denominator = 1 + z * z / total
+    center = (p + z * z / (2 * total)) / denominator
+    margin = z * math.sqrt((p * (1 - p) + z * z / (4 * total)) / total) / denominator
+    return [max(0.0, center - margin), min(1.0, center + margin)]
+
+
+def _required_category_contract(
+    required_categories: Iterable[DefectCategory | str] | None,
+    provenance: Mapping[str, Any] | None,
+) -> tuple[tuple[str, ...], dict[str, Any]]:
+    taxonomy = tuple(category.value for category in DefectCategory)
+    if required_categories is None:
+        return taxonomy, {
+            "mode": "full_taxonomy",
+            "taxonomyVersion": TAXONOMY_VERSION,
+        }
+
+    normalized: list[str] = []
+    for category in required_categories:
+        value = category.value if isinstance(category, DefectCategory) else str(category)
+        if value not in taxonomy:
+            raise ValueError(f"unsupported required visual-QA category: {value!r}")
+        if value not in normalized:
+            normalized.append(value)
+    if not normalized:
+        raise ValueError("required visual-QA categories cannot be empty")
+
+    narrowed = set(normalized) != set(taxonomy)
+    provenance_copy = dict(provenance or {})
+    if narrowed:
+        missing = [key for key in ("reason", "source") if not provenance_copy.get(key)]
+        if missing:
+            raise ValueError(
+                "narrowed required visual-QA categories require provenance fields: "
+                + ", ".join(missing)
+            )
+        provenance_copy["mode"] = "explicitly_narrowed"
+    else:
+        provenance_copy.setdefault("mode", "explicit_full_taxonomy")
+    provenance_copy.setdefault("taxonomyVersion", TAXONOMY_VERSION)
+    return tuple(normalized), provenance_copy
+
+
+def measure_fixture_corpus(
+    corpus: FixtureCorpus,
+    *,
+    required_categories: Iterable[DefectCategory | str] | None = None,
+    minimum_category_samples: int = DEFAULT_MINIMUM_CATEGORY_SAMPLES,
+    required_categories_provenance: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    if minimum_category_samples < 1:
+        raise ValueError("minimum_category_samples must be at least 1")
+    required, scope_provenance = _required_category_contract(
+        required_categories,
+        required_categories_provenance,
+    )
+    expected: set[tuple[str, int, str]] = set()
+    predicted: set[tuple[str, int, str]] = set()
+    per_category: dict[str, dict[str, int]] = defaultdict(lambda: {"tp": 0, "fp": 0, "fn": 0})
+    clean_total = clean_rejected = defect_total = defect_accepted = 0
+    case_rows: list[dict[str, Any]] = []
+
+    for case in corpus.cases:
+        if any(annotation.label_status != "adjudicated" for annotation in case.annotations):
+            raise ValueError(f"case {case.case_id} has non-adjudicated annotations")
+        verdict = inspect_fixture_case(case)
+        expected_case = {
+            (case.case_id, item.page, item.category.value)
+            for item in case.annotations
+            if item.severity is FindingSeverity.CRITICAL
+        }
+        predicted_case = {
+            (case.case_id, item.page, item.category.value)
+            for item in verdict.findings
+            if item.severity is FindingSeverity.CRITICAL
+        }
+        expected.update(expected_case)
+        predicted.update(predicted_case)
+        if case.classification == "clean":
+            clean_total += 1
+            clean_rejected += int(verdict.status is not VerdictStatus.PASS)
+        else:
+            defect_total += 1
+            defect_accepted += int(verdict.status is VerdictStatus.PASS)
+        case_rows.append({
+            "caseId": case.case_id,
+            "classification": case.classification,
+            "status": verdict.status.value,
+            "renderChecked": verdict.render_checked,
+            "expectedCritical": len(expected_case),
+            "predictedCritical": len(predicted_case),
+        })
+
+    true_positive = expected & predicted
+    false_positive = predicted - expected
+    false_negative = expected - predicted
+    for _case, _page, category in true_positive:
+        per_category[category]["tp"] += 1
+    for _case, _page, category in false_positive:
+        per_category[category]["fp"] += 1
+    for _case, _page, category in false_negative:
+        per_category[category]["fn"] += 1
+
+    recall = len(true_positive) / len(expected) if expected else None
+    precision = len(true_positive) / len(predicted) if predicted else None
+    defect_false_acceptance = defect_accepted / defect_total if defect_total else None
+    clean_false_rejection = clean_rejected / clean_total if clean_total else None
+    category_report: dict[str, dict[str, Any]] = {}
+    for category in DefectCategory:
+        counts = per_category[category.value]
+        expected_total = counts["tp"] + counts["fn"]
+        predicted_total = counts["tp"] + counts["fp"]
+        recall_ci = _wilson(counts["tp"], expected_total)
+        precision_ci = _wilson(counts["tp"], predicted_total)
+        is_required = category.value in required
+        category_report[category.value] = {
+            **counts,
+            "recall": counts["tp"] / expected_total if expected_total else None,
+            "recall95CI": recall_ci,
+            "precision": counts["tp"] / predicted_total if predicted_total else None,
+            "precision95CI": precision_ci,
+            "required": is_required,
+            "minimumSamples": minimum_category_samples if is_required else None,
+            "sampleSufficient": bool(
+                not is_required or expected_total >= minimum_category_samples
+            ),
+            "recallLowerBoundPassed": bool(
+                not is_required
+                or (recall_ci is not None and recall_ci[0] >= GATE_THRESHOLDS["criticalRecall"])
+            ),
+        }
+
+    recall_ci = _wilson(len(true_positive), len(expected))
+    precision_ci = _wilson(len(true_positive), len(predicted))
+    defect_false_acceptance_ci = _wilson(defect_accepted, defect_total)
+    clean_false_rejection_ci = _wilson(clean_rejected, clean_total)
+    required_coverage_passed = all(
+        category_report[category]["sampleSufficient"] for category in required
+    )
+    required_recall_bounds_passed = all(
+        category_report[category]["recallLowerBoundPassed"] for category in required
+    )
+    aggregate_bounds = {
+        "criticalRecallLower": bool(
+            recall_ci is not None and recall_ci[0] >= GATE_THRESHOLDS["criticalRecall"]
+        ),
+        "criticalPrecisionLower": bool(
+            precision_ci is not None
+            and precision_ci[0] >= GATE_THRESHOLDS["criticalPrecision"]
+        ),
+        "defectFalseAcceptanceUpper": bool(
+            defect_false_acceptance_ci is not None
+            and defect_false_acceptance_ci[1]
+            <= GATE_THRESHOLDS["defectFalseAcceptanceRate"]
+        ),
+        "cleanFalseRejectionUpper": bool(
+            clean_false_rejection_ci is not None
+            and clean_false_rejection_ci[1]
+            <= GATE_THRESHOLDS["cleanFalseRejectionRate"]
+        ),
+    }
+    failed_requirements: list[str] = []
+    for category in required:
+        if not category_report[category]["sampleSufficient"]:
+            failed_requirements.append(f"category:{category}:minimum_samples")
+        elif not category_report[category]["recallLowerBoundPassed"]:
+            failed_requirements.append(f"category:{category}:recall_lower_bound")
+    failed_requirements.extend(
+        f"aggregate:{name}" for name, passed in aggregate_bounds.items() if not passed
+    )
+
+    return {
+        "schema": "hwpx.visual-qa-metrics/v2",
+        "assurance": "fixture",
+        "renderChecked": False,
+        "counts": {
+            "cases": len(corpus.cases), "expectedCritical": len(expected),
+            "predictedCritical": len(predicted), "truePositive": len(true_positive),
+            "falsePositive": len(false_positive), "falseNegative": len(false_negative),
+        },
+        "criticalRecall": recall,
+        "criticalRecall95CI": recall_ci,
+        "criticalPrecision": precision,
+        "criticalPrecision95CI": precision_ci,
+        "defectFalseAcceptanceRate": defect_false_acceptance,
+        "defectFalseAcceptance95CI": defect_false_acceptance_ci,
+        "cleanFalseRejectionRate": clean_false_rejection,
+        "cleanFalseRejection95CI": clean_false_rejection_ci,
+        "gateContract": {
+            "requiredCategories": list(required),
+            "minimumCategorySamples": minimum_category_samples,
+            "scopeProvenance": scope_provenance,
+            "requiredCoveragePassed": required_coverage_passed,
+            "requiredRecallBoundsPassed": required_recall_bounds_passed,
+            "aggregateBounds": aggregate_bounds,
+            "failedRequirements": failed_requirements,
+        },
+        "thresholds": dict(GATE_THRESHOLDS),
+        "gatePassed": not failed_requirements,
+        "perCategory": category_report,
+        "cases": case_rows,
+    }
+
+
+__all__ = [
+    "DEFAULT_MINIMUM_CATEGORY_SAMPLES",
+    "GATE_THRESHOLDS",
+    "measure_fixture_corpus",
+]

hwpx_automation/office/rendering/worker.py

@@ -0,0 +1,290 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Serialized, supervised real-Hancom render worker primitives."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import subprocess
+import tempfile
+import threading
+from dataclasses import asdict, dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Callable, Protocol
+
+
+WORKER_SCHEMA_VERSION = "hwpx.hancom-worker.v1"
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return "sha256:" + digest.hexdigest()
+
+
+@dataclass(frozen=True)
+class WorkerJob:
+    job_id: str
+    input_path: Path
+    input_content_hash: str
+    dpi: int = 144
+
+
+@dataclass(frozen=True)
+class WorkerArtifact:
+    kind: str
+    content_hash: str
+    size_bytes: int
+    relative_path: str
+    page_number: int | None = None
+
+
+@dataclass(frozen=True)
+class WorkerResult:
+    schema_version: str
+    job_id: str
+    status: str
+    real_hancom: bool
+    render_checked: bool
+    worker_version: str
+    hancom_build: str | None
+    session_generation: int
+    retryable: bool
+    terminal_reason: str
+    artifacts: tuple[WorkerArtifact, ...] = field(default_factory=tuple)
+    page_count: int = 0
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False, sort_keys=True)
+
+
+class RenderSession(Protocol):
+    real_hancom: bool
+    hancom_build: str | None
+
+    def render_pdf(self, source: Path, target: Path) -> Path | None: ...
+    def abort(self) -> None: ...
+    def close(self) -> None: ...
+
+
+class PowerShellHancomSession:
+    """One-at-a-time Windows COM adapter with a killable PowerShell boundary."""
+
+    real_hancom = True
+
+    def __init__(self, *, hancom_build: str, powershell: str = "powershell") -> None:
+        if not hancom_build:
+            raise ValueError("hancom_build is required for real-Hancom provenance")
+        self.hancom_build = hancom_build
+        self.powershell = powershell
+        self._process: subprocess.Popen[bytes] | None = None
+        self._guard = threading.Lock()
+
+    def render_pdf(self, source: Path, target: Path) -> Path | None:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        work = target.parent
+        jobs = work / "jobs.json"
+        result = work / "result.json"
+        jobs.write_text(json.dumps([{"src": str(source.resolve()), "pdf": str(target.resolve())}]), encoding="utf-8")
+        script = resources.files("hwpx_automation.office.rendering").joinpath(
+            "_render_hwpx.ps1"
+        )
+        with resources.as_file(script) as ps1:
+            command = [
+                self.powershell, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+                "-File", str(ps1), "-Jobs", str(jobs), "-ResultPath", str(result),
+            ]
+            with self._guard:
+                self._process = subprocess.Popen(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            try:
+                return_code = self._process.wait()
+            finally:
+                with self._guard:
+                    self._process = None
+        if return_code != 0 or not target.is_file():
+            return None
+        return target
+
+    def abort(self) -> None:
+        with self._guard:
+            process = self._process
+        if process and process.poll() is None:
+            process.kill()
+            try:
+                process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.terminate()
+
+    def close(self) -> None:
+        self.abort()
+
+
+class DeterministicFakeSession:
+    """Contract-faithful CI renderer that can never claim real Hancom."""
+
+    real_hancom = False
+    hancom_build = None
+
+    def __init__(self) -> None:
+        self.aborted = False
+
+    def render_pdf(self, source: Path, target: Path) -> Path | None:
+        target.write_bytes(b"%PDF-FAKE\n" + source.read_bytes()[:64])
+        return target
+
+    def abort(self) -> None:
+        self.aborted = True
+
+    def close(self) -> None:
+        return None
+
+
+class SerializedHancomWorker:
+    """Single-flight worker; a timeout poisons and replaces the render session."""
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        session_factory: Callable[[], RenderSession],
+        worker_version: str,
+        timeout_seconds: float = 300,
+        abort_grace_seconds: float = 10,
+    ) -> None:
+        self.root = root.resolve()
+        self.sandboxes = self.root / "sandboxes"
+        self.artifacts = self.root / "artifacts"
+        self.sandboxes.mkdir(parents=True, exist_ok=True)
+        self.artifacts.mkdir(parents=True, exist_ok=True)
+        self.session_factory = session_factory
+        self.worker_version = worker_version
+        self.timeout_seconds = timeout_seconds
+        self.abort_grace_seconds = abort_grace_seconds
+        self._lock = threading.Lock()
+        self._session: RenderSession | None = None
+        self._generation = 0
+        self._poisoned_thread: threading.Thread | None = None
+
+    def _new_session(self) -> RenderSession:
+        self._generation += 1
+        self._session = self.session_factory()
+        return self._session
+
+    def _restart_session(self) -> None:
+        if self._session:
+            self._session.close()
+        self._session = None
+
+    def render(self, job: WorkerJob) -> WorkerResult:
+        if not self._lock.acquire(blocking=False):
+            return self._failure(job, "WORKER_BUSY", retryable=True)
+        try:
+            return self._render_locked(job)
+        finally:
+            self._lock.release()
+
+    def _render_locked(self, job: WorkerJob) -> WorkerResult:
+        if self._poisoned_thread is not None:
+            if self._poisoned_thread.is_alive():
+                return self._failure(job, "POISONED_SESSION_STILL_RUNNING", retryable=True)
+            self._poisoned_thread = None
+            self._restart_session()
+        actual = sha256_file(job.input_path)
+        if actual != job.input_content_hash:
+            return self._failure(job, "INPUT_HASH_MISMATCH", retryable=False)
+        sandbox = Path(tempfile.mkdtemp(prefix=f"{job.job_id}-", dir=self.sandboxes))
+        try:
+            source = sandbox / "input.hwpx"
+            shutil.copyfile(job.input_path, source)
+            pdf = sandbox / "output.pdf"
+            session = self._session or self._new_session()
+            outcome: dict[str, object] = {}
+
+            def invoke() -> None:
+                try:
+                    outcome["pdf"] = session.render_pdf(source, pdf)
+                except BaseException as exc:  # contained at the worker boundary
+                    outcome["error"] = type(exc).__name__
+
+            thread = threading.Thread(target=invoke, name=f"hancom-{job.job_id}", daemon=True)
+            thread.start()
+            thread.join(self.timeout_seconds)
+            if thread.is_alive():
+                session.abort()
+                thread.join(self.abort_grace_seconds)
+                if thread.is_alive():
+                    self._poisoned_thread = thread
+                else:
+                    self._restart_session()
+                return self._failure(job, "COM_WATCHDOG_TIMEOUT", retryable=True)
+            if "error" in outcome or not outcome.get("pdf") or not pdf.is_file():
+                self._restart_session()
+                return self._failure(job, "HANCOM_RENDER_FAILED", retryable=True)
+
+            destination = self.artifacts / job.job_id
+            if destination.exists():
+                shutil.rmtree(destination)
+            destination.mkdir(parents=True)
+            final_pdf = destination / "document.pdf"
+            shutil.copyfile(pdf, final_pdf)
+            try:
+                pages = self._rasterize(final_pdf, destination, job.dpi)
+            except Exception:
+                shutil.rmtree(destination, ignore_errors=True)
+                return self._failure(job, "PAGE_RASTERIZE_FAILED", retryable=True)
+            artifacts = [
+                WorkerArtifact("pdf", sha256_file(final_pdf), final_pdf.stat().st_size, f"{job.job_id}/document.pdf")
+            ]
+            artifacts.extend(
+                WorkerArtifact("page_png", sha256_file(page), page.stat().st_size, f"{job.job_id}/{page.name}", index)
+                for index, page in enumerate(pages, 1)
+            )
+            real = bool(session.real_hancom and session.hancom_build)
+            return WorkerResult(
+                WORKER_SCHEMA_VERSION, job.job_id, "succeeded", real, real,
+                self.worker_version, session.hancom_build, self._generation, False,
+                "SUCCEEDED" if real else "FAKE_RENDER_ONLY", tuple(artifacts), len(pages),
+            )
+        finally:
+            shutil.rmtree(sandbox, ignore_errors=True)
+
+    @staticmethod
+    def _rasterize(pdf: Path, destination: Path, dpi: int) -> list[Path]:
+        try:
+            import fitz
+        except ImportError as exc:
+            raise RuntimeError("PyMuPDF is required for page PNG output") from exc
+        document = fitz.open(pdf)
+        pages: list[Path] = []
+        try:
+            scale = dpi / 72
+            for page_index in range(document.page_count):
+                page = document.load_page(page_index)
+                target = destination / f"page-{page_index + 1:04d}.png"
+                page.get_pixmap(matrix=fitz.Matrix(scale, scale), alpha=False).save(target)
+                pages.append(target)
+        finally:
+            document.close()
+        return pages
+
+    def _failure(self, job: WorkerJob, reason: str, *, retryable: bool) -> WorkerResult:
+        session = self._session
+        return WorkerResult(
+            WORKER_SCHEMA_VERSION, job.job_id, "unverified", False, False,
+            self.worker_version, session.hancom_build if session else None,
+            self._generation, retryable, reason,
+        )
+
+    def close(self) -> None:
+        with self._lock:
+            self._restart_session()
+
+
+__all__ = [
+    "DeterministicFakeSession", "PowerShellHancomSession", "SerializedHancomWorker",
+    "WorkerArtifact", "WorkerJob", "WorkerResult", "WORKER_SCHEMA_VERSION", "sha256_file",
+]

hwpx_automation/office/utilities/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Canonical application utilities unrelated to HWPX format semantics."""
+
+from .table_compute import (
+    TABLE_COMPUTE_REPORT_VERSION,
+    table_compute,
+)
+
+__all__ = [
+    "TABLE_COMPUTE_REPORT_VERSION",
+    "table_compute",
+]