ummaya 0.2.3 → 0.2.5

package/src/ummaya/tools/documents/render_comparison.py

@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import hashlib
+from decimal import Decimal
+
+from ummaya.tools.documents.models import (
+    DocumentArtifact,
+    DocumentDiff,
+    DocumentExtraction,
+)
+from ummaya.tools.documents.render_comparison_models import (
+    RenderComparisonEvidence,
+    RenderComparisonStatus,
+    StyleDeltaEvidence,
+    TableGeometryDeltaEvidence,
+)
+from ummaya.tools.documents.render_comparison_regions import changed_region_evidence
+from ummaya.tools.documents.render_comparison_style import (
+    style_deltas,
+    table_geometry_deltas,
+)
+
+__all__ = [
+    "RenderComparisonEvidence",
+    "RenderComparisonStatus",
+    "build_render_comparison_evidence",
+]
+
+
+def build_render_comparison_evidence(
+    source: DocumentArtifact,
+    derivative: DocumentArtifact,
+    *,
+    diff: DocumentDiff,
+    before_extraction: DocumentExtraction,
+    after_extraction: DocumentExtraction,
+    confidence_threshold: Decimal,
+) -> RenderComparisonEvidence:
+    changed_regions = changed_region_evidence(
+        diff,
+        source=source,
+        derivative=derivative,
+        threshold=confidence_threshold,
+    )
+    deltas = style_deltas(
+        diff,
+        before_extraction=before_extraction,
+        after_extraction=after_extraction,
+    )
+    geometry_deltas = table_geometry_deltas(before_extraction, after_extraction)
+    if not changed_regions:
+        return _blocked_comparison(
+            source,
+            derivative,
+            threshold=confidence_threshold,
+            failure_reason="source-to-derivative render comparison is missing",
+            style_deltas=deltas,
+            table_geometry_deltas=geometry_deltas,
+        )
+    status: RenderComparisonStatus = (
+        "pass" if all(region.threshold_status == "pass" for region in changed_regions) else "failed"
+    )
+    failure_reason = None if status == "pass" else "changed region confidence below threshold"
+    return RenderComparisonEvidence(
+        comparison_id=_comparison_id(source, derivative, diff),
+        source_artifact_id=source.artifact_id,
+        derivative_artifact_id=derivative.artifact_id,
+        source_sha256=source.sha256,
+        derivative_sha256=derivative.sha256,
+        status=status,
+        threshold=confidence_threshold,
+        threshold_status=status,
+        changed_regions=changed_regions,
+        style_deltas=deltas,
+        table_geometry_deltas=geometry_deltas,
+        failure_reason=failure_reason,
+    )
+
+
+def _blocked_comparison(
+    source: DocumentArtifact,
+    derivative: DocumentArtifact,
+    *,
+    threshold: Decimal,
+    failure_reason: str,
+    style_deltas: tuple[StyleDeltaEvidence, ...],
+    table_geometry_deltas: tuple[TableGeometryDeltaEvidence, ...],
+) -> RenderComparisonEvidence:
+    return RenderComparisonEvidence(
+        comparison_id=_comparison_id(source, derivative, None),
+        source_artifact_id=source.artifact_id,
+        derivative_artifact_id=derivative.artifact_id,
+        source_sha256=source.sha256,
+        derivative_sha256=derivative.sha256,
+        status="blocked",
+        threshold=threshold,
+        threshold_status="blocked",
+        style_deltas=style_deltas,
+        table_geometry_deltas=table_geometry_deltas,
+        failure_reason=failure_reason,
+    )
+
+
+def _comparison_id(
+    source: DocumentArtifact,
+    derivative: DocumentArtifact,
+    diff: DocumentDiff | None,
+) -> str:
+    diff_id = "no-diff" if diff is None else diff.diff_id
+    payload = f"{source.artifact_id}:{derivative.artifact_id}:{diff_id}".encode()
+    return f"render-comparison-{hashlib.sha256(payload).hexdigest()[:16]}"

package/src/ummaya/tools/documents/render_comparison_models.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+type RenderComparisonStatus = Literal["pass", "failed", "blocked"]
+type StylePropertyName = Literal[
+    "font_family",
+    "font_size_pt",
+    "bold",
+    "italic",
+    "underline",
+    "font_color_rgb",
+    "fill_color_rgb",
+    "alignment",
+    "line_spacing",
+    "border",
+    "number_format",
+]
+
+
+class StrictRenderComparisonModel(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class StyleDeltaEvidence(StrictRenderComparisonModel):
+    operation_id: str
+    target_path: str
+    property_name: StylePropertyName
+    before_value: str | None = None
+    after_value: str | None = None
+
+
+class TableGeometryDeltaEvidence(StrictRenderComparisonModel):
+    target_path: str
+    before_row_span: int
+    after_row_span: int
+    before_column_span: int
+    after_column_span: int
+
+
+class RenderChangedRegionEvidence(StrictRenderComparisonModel):
+    region_id: str
+    viewport_id: str
+    change_ids: tuple[str, ...] = Field(min_length=1)
+    page_number: int = Field(ge=1)
+    source_render_artifact_id: str
+    derivative_render_artifact_id: str
+    source_render_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    derivative_render_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    source_artifact_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    derivative_artifact_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    confidence: Decimal = Field(ge=0, le=1)
+    threshold: Decimal = Field(ge=0, le=1)
+    threshold_status: RenderComparisonStatus
+
+
+class RenderComparisonEvidence(StrictRenderComparisonModel):
+    comparison_id: str
+    source_artifact_id: str
+    derivative_artifact_id: str
+    source_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    derivative_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    status: RenderComparisonStatus
+    threshold: Decimal = Field(ge=0, le=1)
+    threshold_status: RenderComparisonStatus
+    changed_regions: tuple[RenderChangedRegionEvidence, ...] = ()
+    style_deltas: tuple[StyleDeltaEvidence, ...] = ()
+    table_geometry_deltas: tuple[TableGeometryDeltaEvidence, ...] = ()
+    failure_reason: str | None = None

package/src/ummaya/tools/documents/render_comparison_regions.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+from ummaya.tools.documents.models import (
+    DocumentArtifact,
+    DocumentChangedViewport,
+    DocumentDiff,
+    RenderArtifactRecord,
+)
+from ummaya.tools.documents.render_comparison_models import (
+    RenderChangedRegionEvidence,
+    RenderComparisonStatus,
+)
+
+
+def changed_region_evidence(
+    diff: DocumentDiff,
+    *,
+    source: DocumentArtifact,
+    derivative: DocumentArtifact,
+    threshold: Decimal,
+) -> tuple[RenderChangedRegionEvidence, ...]:
+    derivative_records = {record.render_artifact_id: record for record in diff.render_artifacts}
+    baseline_by_page = {record.page_number: record for record in diff.baseline_render_artifacts}
+    regions: list[RenderChangedRegionEvidence] = []
+    for viewport in diff.changed_viewports:
+        derivative_record = derivative_records.get(viewport.source_render_artifact_id)
+        baseline_record = baseline_by_page.get(viewport.page_number)
+        if derivative_record is None or baseline_record is None:
+            continue
+        regions.append(
+            _changed_region(
+                viewport,
+                source=source,
+                derivative=derivative,
+                derivative_record=derivative_record,
+                baseline_record=baseline_record,
+                threshold=threshold,
+            )
+        )
+    return tuple(regions)
+
+
+def _changed_region(
+    viewport: DocumentChangedViewport,
+    *,
+    source: DocumentArtifact,
+    derivative: DocumentArtifact,
+    derivative_record: RenderArtifactRecord,
+    baseline_record: RenderArtifactRecord,
+    threshold: Decimal,
+) -> RenderChangedRegionEvidence:
+    threshold_status: RenderComparisonStatus = (
+        "pass" if viewport.confidence >= threshold else "failed"
+    )
+    return RenderChangedRegionEvidence(
+        region_id=viewport.viewport_id,
+        viewport_id=viewport.viewport_id,
+        change_ids=viewport.change_ids,
+        page_number=viewport.page_number,
+        source_render_artifact_id=baseline_record.render_artifact_id,
+        derivative_render_artifact_id=derivative_record.render_artifact_id,
+        source_render_sha256=baseline_record.render_sha256,
+        derivative_render_sha256=derivative_record.render_sha256,
+        source_artifact_sha256=source.sha256,
+        derivative_artifact_sha256=derivative.sha256,
+        confidence=viewport.confidence,
+        threshold=threshold,
+        threshold_status=threshold_status,
+    )

package/src/ummaya/tools/documents/render_comparison_style.py

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from decimal import Decimal
+from typing import Final
+
+from ummaya.tools.documents.models import (
+    BorderDescriptor,
+    DocumentDiff,
+    DocumentExtraction,
+    StyleDescriptor,
+    TableCell,
+)
+from ummaya.tools.documents.render_comparison_models import (
+    StyleDeltaEvidence,
+    StylePropertyName,
+    TableGeometryDeltaEvidence,
+)
+
+_STYLE_PROPERTIES: Final[tuple[StylePropertyName, ...]] = (
+    "font_family",
+    "font_size_pt",
+    "bold",
+    "italic",
+    "underline",
+    "font_color_rgb",
+    "fill_color_rgb",
+    "alignment",
+    "line_spacing",
+    "border",
+    "number_format",
+)
+_STYLE_VALUE_READERS: Final[dict[StylePropertyName, Callable[[StyleDescriptor], str | None]]] = {
+    "font_family": lambda style: style.font_family,
+    "font_size_pt": lambda style: _decimal_value(style.font_size_pt),
+    "bold": lambda style: _bool_value(style.bold),
+    "italic": lambda style: _bool_value(style.italic),
+    "underline": lambda style: _bool_value(style.underline),
+    "font_color_rgb": lambda style: style.font_color_rgb,
+    "fill_color_rgb": lambda style: style.fill_color_rgb,
+    "alignment": lambda style: style.alignment,
+    "line_spacing": lambda style: _decimal_value(style.line_spacing),
+    "border": lambda style: _border_value(style.border),
+    "number_format": lambda style: style.number_format,
+}
+
+
+def style_deltas(
+    diff: DocumentDiff,
+    *,
+    before_extraction: DocumentExtraction,
+    after_extraction: DocumentExtraction,
+) -> tuple[StyleDeltaEvidence, ...]:
+    operation_ids_by_target = {
+        change.target_path: change.operation_id
+        for change in diff.changes
+        if change.change_type == "style"
+    }
+    deltas: list[StyleDeltaEvidence] = []
+    for target_path, operation_id in operation_ids_by_target.items():
+        before_style = _style_for_target(before_extraction, target_path)
+        after_style = _style_for_target(after_extraction, target_path)
+        if before_style is None and after_style is None:
+            continue
+        deltas.extend(_style_delta(operation_id, target_path, before_style, after_style))
+    return tuple(deltas)
+
+
+def table_geometry_deltas(
+    before_extraction: DocumentExtraction,
+    after_extraction: DocumentExtraction,
+) -> tuple[TableGeometryDeltaEvidence, ...]:
+    before_cells = _table_cells_by_path(before_extraction)
+    after_cells = _table_cells_by_path(after_extraction)
+    deltas: list[TableGeometryDeltaEvidence] = []
+    for target_path, after_cell in after_cells.items():
+        before_cell = before_cells.get(target_path)
+        if before_cell is None:
+            continue
+        if (
+            before_cell.row_span == after_cell.row_span
+            and before_cell.column_span == after_cell.column_span
+        ):
+            continue
+        deltas.append(
+            TableGeometryDeltaEvidence(
+                target_path=target_path,
+                before_row_span=before_cell.row_span,
+                after_row_span=after_cell.row_span,
+                before_column_span=before_cell.column_span,
+                after_column_span=after_cell.column_span,
+            )
+        )
+    return tuple(deltas)
+
+
+def _style_delta(
+    operation_id: str,
+    target_path: str,
+    before_style: StyleDescriptor | None,
+    after_style: StyleDescriptor | None,
+) -> tuple[StyleDeltaEvidence, ...]:
+    deltas: list[StyleDeltaEvidence] = []
+    for property_name in _STYLE_PROPERTIES:
+        before_value = _style_value(before_style, property_name)
+        after_value = _style_value(after_style, property_name)
+        if before_value == after_value:
+            continue
+        deltas.append(
+            StyleDeltaEvidence(
+                operation_id=operation_id,
+                target_path=target_path,
+                property_name=property_name,
+                before_value=before_value,
+                after_value=after_value,
+            )
+        )
+    return tuple(deltas)
+
+
+def _style_for_target(
+    extraction: DocumentExtraction,
+    target_path: str,
+) -> StyleDescriptor | None:
+    for style in extraction.style_map:
+        if style.target_path == target_path:
+            return style
+    return None
+
+
+def _style_value(
+    style: StyleDescriptor | None,
+    property_name: StylePropertyName,
+) -> str | None:
+    if style is None:
+        return None
+    return _STYLE_VALUE_READERS[property_name](style)
+
+
+def _table_cells_by_path(extraction: DocumentExtraction) -> dict[str, TableCell]:
+    return {cell.source_path: cell for table in extraction.tables for cell in table.cells}
+
+
+def _bool_value(value: bool | None) -> str | None:
+    if value is None:
+        return None
+    return "true" if value else "false"
+
+
+def _decimal_value(value: Decimal | None) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _border_value(value: BorderDescriptor | None) -> str | None:
+    if value is None:
+        return None
+    return value.model_dump_json()

package/src/ummaya/tools/documents/reread.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Derivative re-read comparison against intended document patches."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+from ummaya.tools.documents.engines import (
+    DocumentEngineRegistry,
+    UnsupportedDocumentEngineError,
+)
+from ummaya.tools.documents.models import (
+    BlockedReason,
+    DocumentArtifact,
+    DocumentExtraction,
+    DocumentPatch,
+    DocumentPatchOperation,
+    OperationType,
+    ScalarValue,
+    ToolResultStatus,
+)
+
+
+class ReReadMismatch(BaseModel):
+    """One intended value that was not observed after saving and re-reading."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    operation_id: str
+    target_path: str
+    expected_value: str
+    observed_value: str | None = None
+
+
+class DocumentReReadResult(BaseModel):
+    """Result of re-reading a saved derivative artifact."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    status: ToolResultStatus
+    correlation_id: str
+    artifact_id: str
+    extraction: DocumentExtraction
+    mismatches: tuple[ReReadMismatch, ...] = ()
+    round_trip_passed: bool
+    blocked_reason: BlockedReason | None = None
+    text_summary: str
+
+
+def reread_derivative(
+    artifact: DocumentArtifact,
+    patch: DocumentPatch,
+    *,
+    engine_registry: DocumentEngineRegistry,
+    correlation_id: str,
+) -> DocumentReReadResult:
+    """Re-read a derivative and compare observed values with the patch intent."""
+    if patch.target_artifact_id != artifact.artifact_id:
+        extraction = DocumentExtraction(artifact_id=artifact.artifact_id)
+        return DocumentReReadResult(
+            status=ToolResultStatus.blocked,
+            correlation_id=correlation_id,
+            artifact_id=artifact.artifact_id,
+            extraction=extraction,
+            round_trip_passed=False,
+            blocked_reason=BlockedReason.validation_failed,
+            text_summary="Patch target does not match the derivative artifact.",
+        )
+    try:
+        engine = engine_registry.require(artifact.format)
+    except UnsupportedDocumentEngineError:
+        extraction = DocumentExtraction(artifact_id=artifact.artifact_id)
+        return DocumentReReadResult(
+            status=ToolResultStatus.blocked,
+            correlation_id=correlation_id,
+            artifact_id=artifact.artifact_id,
+            extraction=extraction,
+            round_trip_passed=False,
+            blocked_reason=BlockedReason.unsupported_operation,
+            text_summary=f"No inspection engine is registered for {artifact.format.value}.",
+        )
+
+    extraction = engine.inspect(Path(artifact.source_path), artifact_id=artifact.artifact_id)
+    mismatches = tuple(
+        mismatch
+        for operation in patch.operations
+        if (mismatch := _operation_mismatch(operation, extraction)) is not None
+    )
+    passed = len(mismatches) == 0
+    return DocumentReReadResult(
+        status=ToolResultStatus.ok if passed else ToolResultStatus.blocked,
+        correlation_id=correlation_id,
+        artifact_id=artifact.artifact_id,
+        extraction=extraction,
+        mismatches=mismatches,
+        round_trip_passed=passed,
+        blocked_reason=None if passed else BlockedReason.validation_failed,
+        text_summary=(
+            "Derivative re-read matched all intended patch values."
+            if passed
+            else f"Derivative re-read found {len(mismatches)} mismatched intended value(s)."
+        ),
+    )
+
+
+def _operation_mismatch(
+    operation: DocumentPatchOperation,
+    extraction: DocumentExtraction,
+) -> ReReadMismatch | None:
+    if operation.operation_type not in {
+        OperationType.set_field_value,
+        OperationType.set_table_cell,
+        OperationType.replace_text,
+        OperationType.insert_paragraph,
+        OperationType.set_document_metadata,
+    }:
+        return None
+    expected = _string_value(operation.value)
+    observed = _observed_value(operation, extraction)
+    if observed == expected:
+        return None
+    return ReReadMismatch(
+        operation_id=operation.operation_id,
+        target_path=operation.target_path,
+        expected_value=expected,
+        observed_value=observed,
+    )
+
+
+def _observed_value(
+    operation: DocumentPatchOperation,
+    extraction: DocumentExtraction,
+) -> str | None:
+    if operation.operation_type is OperationType.set_field_value:
+        for field in extraction.fields:
+            if field.path == operation.target_path:
+                return _string_value(field.current_value)
+        return None
+    if operation.operation_type is OperationType.set_table_cell:
+        for table in extraction.tables:
+            for cell in table.cells:
+                if cell.source_path == operation.target_path:
+                    return cell.text
+        return None
+    if operation.operation_type is OperationType.set_document_metadata:
+        return _string_value(extraction.metadata.get(operation.target_path))
+    expected = _string_value(operation.value)
+    text_parts = [paragraph.text for paragraph in extraction.paragraphs]
+    text_parts.extend(cell.text for table in extraction.tables for cell in table.cells)
+    observed_text = "\n".join(text_parts)
+    return expected if expected in observed_text else None
+
+
+def _string_value(value: ScalarValue) -> str:
+    return "" if value is None else str(value)