ummaya 0.2.3 → 0.2.5

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

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Local ODF promotion diagnostics.
+
+ODF is promoted for bounded odfdo-backed write/render/save operations. This
+module keeps the separate LibreOffice layout-oracle bridge visible so evidence
+does not confuse structural SVG rendering with original-page fidelity.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from importlib.util import find_spec
+from pathlib import Path
+from shutil import which
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ummaya.tools.documents.adapter_registry import build_default_document_adapter_registry
+from ummaya.tools.documents.models import DocumentFormat, DocumentFormatFamily, KnownDocumentFormat
+
+ODF_WRITER_PACKAGE = "odfdo"
+ODF_WRITER_CANDIDATE_ID = "odfdo-odf-package-writer"
+ODF_RENDER_ORACLE_ID = "libreoffice-headless-pdf-export"
+ODF_READ_ADAPTER_ID = "odfdo-document-adapter"
+ODF_SOURCE_REFS = (
+    "upstream:oasis-open-document-v1.4",
+    "upstream:odfdo-v3.22.8",
+    "upstream:libreoffice-26.2-headless-pdf-export",
+)
+ODF_PROMOTION_FORMATS = (
+    KnownDocumentFormat.odt,
+    KnownDocumentFormat.ods,
+    KnownDocumentFormat.odp,
+)
+
+OdfPromotionProbeStatus = Literal["blocked", "promoted_bounded"]
+
+
+class OdfPromotionProbeReport(BaseModel):
+    """Current local availability of ODF writer/render promotion candidates."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    candidate_id: str = Field(min_length=1)
+    known_format: KnownDocumentFormat
+    family: DocumentFormatFamily
+    status: OdfPromotionProbeStatus
+    read_adapter_id: str = Field(min_length=1)
+    writer_package: str = Field(min_length=1)
+    writer_available: bool
+    render_oracle_id: str = Field(min_length=1)
+    render_oracle_available: bool
+    render_oracle_executable: Path | None
+    reasons: tuple[str, ...]
+    required_gates: tuple[str, ...]
+    evidence_refs: tuple[str, ...]
+
+
+def probe_odf_promotion(
+    *,
+    env: Mapping[str, str] | None = None,
+    search_path: Sequence[str] | None = None,
+    importable_modules: frozenset[str] | None = None,
+) -> tuple[OdfPromotionProbeReport, ...]:
+    """Report ODF promotion readiness without mutating adapter registries."""
+    active_env = os.environ if env is None else env
+    writer_available = _is_importable(ODF_WRITER_PACKAGE, importable_modules=importable_modules)
+    runtime_promoted = _is_runtime_promoted()
+    render_oracle_executable = _find_libreoffice_cli(active_env=active_env, search_path=search_path)
+    render_oracle_available = render_oracle_executable is not None
+    status: OdfPromotionProbeStatus = (
+        "promoted_bounded" if writer_available and runtime_promoted else "blocked"
+    )
+    reasons = _reasons(
+        writer_available=writer_available,
+        runtime_promoted=runtime_promoted,
+        render_oracle_available=render_oracle_available,
+    )
+    return tuple(
+        OdfPromotionProbeReport(
+            candidate_id=ODF_WRITER_CANDIDATE_ID,
+            known_format=known_format,
+            family=DocumentFormatFamily.odf,
+            status=status,
+            read_adapter_id=ODF_READ_ADAPTER_ID,
+            writer_package=ODF_WRITER_PACKAGE,
+            writer_available=writer_available,
+            render_oracle_id=ODF_RENDER_ORACLE_ID,
+            render_oracle_available=render_oracle_available,
+            render_oracle_executable=render_oracle_executable,
+            reasons=reasons,
+            required_gates=(
+                "odf_writer_package_available",
+                "odf_save_reread_fixture_gate",
+                "odf_runtime_document_format_promotion",
+                "odf_structural_svg_render_gate",
+                "odf_layout_oracle_bridge_deferred",
+            ),
+            evidence_refs=ODF_SOURCE_REFS,
+        )
+        for known_format in ODF_PROMOTION_FORMATS
+    )
+
+
+def _is_importable(name: str, *, importable_modules: frozenset[str] | None) -> bool:
+    if importable_modules is not None:
+        return name in importable_modules
+    return find_spec(name) is not None
+
+
+def _is_runtime_promoted() -> bool:
+    registry = build_default_document_adapter_registry()
+    return all(
+        document_format in registry.require_known(known_format).promoted_formats
+        for known_format, document_format in (
+            (KnownDocumentFormat.odt, DocumentFormat.odt),
+            (KnownDocumentFormat.ods, DocumentFormat.ods),
+            (KnownDocumentFormat.odp, DocumentFormat.odp),
+        )
+    )
+
+
+def _find_libreoffice_cli(
+    *,
+    active_env: Mapping[str, str],
+    search_path: Sequence[str] | None,
+) -> Path | None:
+    path_env = os.pathsep.join(search_path) if search_path is not None else active_env.get("PATH")
+    if not path_env:
+        return None
+    for executable_name in ("soffice", "libreoffice"):
+        found = which(executable_name, path=path_env)
+        if found is None:
+            continue
+        executable = Path(found).expanduser().resolve(strict=False)
+        if _is_executable_file(executable):
+            return executable
+    return None
+
+
+def _is_executable_file(path: Path) -> bool:
+    return path.exists() and path.is_file() and os.access(path, os.X_OK)
+
+
+def _reasons(
+    *,
+    writer_available: bool,
+    runtime_promoted: bool,
+    render_oracle_available: bool,
+) -> tuple[str, ...]:
+    reasons: list[str] = []
+    if runtime_promoted:
+        reasons.append("odf_runtime_promoted_bounded")
+    else:
+        reasons.append("odf_runtime_not_promoted")
+    if writer_available:
+        reasons.append("odfdo_package_registered")
+    else:
+        reasons.append("odfdo_package_not_found")
+    if render_oracle_available:
+        reasons.append("libreoffice_cli_found_layout_oracle_candidate")
+    else:
+        reasons.append("libreoffice_cli_not_found")
+    reasons.append("libreoffice_layout_oracle_deferred")
+    return tuple(reasons)

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

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Internal orchestration boundary for the model-facing document primitive."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from ummaya.tools.documents.adapter_registry import (
+    DocumentAdapterRegistry,
+    build_document_adapter_registry_from_engine_registry,
+)
+from ummaya.tools.documents.engines import DocumentEngineRegistry
+from ummaya.tools.documents.inspection import inspect_document
+from ummaya.tools.documents.models import (
+    DocumentExtraction,
+    DocumentFormat,
+    DocumentIR,
+    DocumentToolResult,
+)
+
+
+class DocumentInspectionOrchestrator(Protocol):
+    """Minimal inspection boundary consumed by the document runtime."""
+
+    def inspect_local_path(
+        self,
+        source_path: Path,
+        *,
+        expected_format: DocumentFormat | None,
+        correlation_id: str,
+    ) -> DocumentToolResult:
+        """Inspect one local document path through adapter selection."""
+
+    def build_document_ir(
+        self,
+        *,
+        artifact_id: str,
+        document_format: DocumentFormat,
+        extraction: DocumentExtraction,
+    ) -> DocumentIR:
+        """Normalize inspected document content into planner-facing IR."""
+
+
+class DocumentOrchestrator:
+    """Coordinate intake, format selection, and adapter-backed inspection."""
+
+    def __init__(
+        self,
+        *,
+        adapter_registry: DocumentAdapterRegistry | None = None,
+        engine_registry: DocumentEngineRegistry | None = None,
+    ) -> None:
+        self.engine_registry = engine_registry or DocumentEngineRegistry()
+        self.adapter_registry = (
+            adapter_registry
+            or build_document_adapter_registry_from_engine_registry(self.engine_registry)
+        )
+
+    def inspect_local_path(
+        self,
+        source_path: Path,
+        *,
+        expected_format: DocumentFormat | None,
+        correlation_id: str,
+    ) -> DocumentToolResult:
+        """Inspect a local source document without mutating it."""
+        return inspect_document(
+            source_path,
+            expected_format=expected_format,
+            engine_registry=self.engine_registry,
+            adapter_registry=self.adapter_registry,
+        )
+
+    def build_document_ir(
+        self,
+        *,
+        artifact_id: str,
+        document_format: DocumentFormat,
+        extraction: DocumentExtraction,
+    ) -> DocumentIR:
+        """Normalize inspected document content into planner-facing IR."""
+        return DocumentIR.from_extraction(
+            artifact_id=artifact_id,
+            document_format=document_format,
+            extraction=extraction,
+            engine_id=_engine_id_for_extraction(extraction),
+        )
+
+
+def _engine_id_for_extraction(extraction: DocumentExtraction) -> str:
+    for key in ("engine_id", "adapter_id", "format_adapter_id"):
+        value = extraction.metadata.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return "document-orchestrator"

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

@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Local passive attachment capability diagnostics."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from importlib.util import find_spec
+from pathlib import Path
+from shutil import which
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ummaya.tools.documents.models import DocumentFormatFamily, KnownDocumentFormat
+
+PASSIVE_CAPABILITY_CANDIDATE_ID = "passive-attachment-extraction-boundary"
+PASSIVE_CAPABILITY_SOURCE_REFS = (
+    "upstream:tesseract-ocr-cli",
+    "upstream:ffmpeg-ffprobe",
+    "upstream:gdal-ogrinfo",
+    "upstream:pyshp",
+    "upstream:trimesh",
+    "upstream:owasp-file-upload-attachment-limits",
+)
+
+PassiveCapabilityProbeStatus = Literal["blocked", "candidate_available"]
+
+_IMAGE_FORMATS = (
+    KnownDocumentFormat.png,
+    KnownDocumentFormat.jpg,
+    KnownDocumentFormat.jpeg,
+    KnownDocumentFormat.gif,
+    KnownDocumentFormat.tif,
+    KnownDocumentFormat.tiff,
+    KnownDocumentFormat.bmp,
+    KnownDocumentFormat.webp,
+)
+_GEOSPATIAL_FORMATS = (
+    KnownDocumentFormat.shp,
+    KnownDocumentFormat.shx,
+    KnownDocumentFormat.dbf,
+    KnownDocumentFormat.prj,
+    KnownDocumentFormat.stl,
+)
+_MEDIA_FORMATS = (
+    KnownDocumentFormat.wav,
+    KnownDocumentFormat.mp3,
+    KnownDocumentFormat.mp4,
+)
+
+
+class PassiveCapabilityProbeReport(BaseModel):
+    """Current local availability of passive attachment extraction candidates."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    candidate_id: str = Field(min_length=1)
+    known_format: KnownDocumentFormat
+    family: DocumentFormatFamily
+    status: PassiveCapabilityProbeStatus
+    read_adapter_id: str = Field(min_length=1)
+    runtime_id: str = Field(min_length=1)
+    runtime_available: bool
+    runtime_executable: Path | None
+    extraction_available: bool
+    direct_mutation_promoted: bool
+    reasons: tuple[str, ...]
+    required_gates: tuple[str, ...]
+    evidence_refs: tuple[str, ...]
+
+
+def probe_passive_capabilities(
+    *,
+    env: Mapping[str, str] | None = None,
+    search_path: Sequence[str] | None = None,
+    importable_modules: frozenset[str] | None = None,
+) -> tuple[PassiveCapabilityProbeReport, ...]:
+    """Report passive attachment readiness without promoting document writes."""
+    active_env = os.environ if env is None else env
+    tesseract = _find_executable("tesseract", active_env=active_env, search_path=search_path)
+    ffprobe = _find_executable("ffprobe", active_env=active_env, search_path=search_path)
+    geospatial_available = _geospatial_runtime_available(
+        active_env=active_env,
+        search_path=search_path,
+        importable_modules=importable_modules,
+    )
+    reports: list[PassiveCapabilityProbeReport] = []
+    reports.extend(_image_reports(tesseract=tesseract))
+    reports.extend(_geospatial_reports(runtime_available=geospatial_available))
+    reports.extend(_media_reports(ffprobe=ffprobe))
+    return tuple(reports)
+
+
+def _image_reports(*, tesseract: Path | None) -> tuple[PassiveCapabilityProbeReport, ...]:
+    runtime_available = tesseract is not None
+    reasons = (
+        "image_ocr_candidate_available" if runtime_available else "tesseract_cli_not_found",
+        "image_document_write_not_promoted",
+        "no_in_place_raster_mutation",
+    )
+    return tuple(
+        _report(
+            known_format=known_format,
+            family=DocumentFormatFamily.image_scan,
+            read_adapter_id="image-scan-extraction-only-adapter",
+            runtime_id="tesseract-ocr-cli",
+            runtime_available=runtime_available,
+            runtime_executable=tesseract,
+            extraction_available=runtime_available,
+            reasons=reasons,
+            required_gates=(
+                "image_ocr_runtime_available",
+                "image_text_extraction_gate",
+                "document_derivative_write_gate",
+                "image_original_preservation_gate",
+            ),
+        )
+        for known_format in _IMAGE_FORMATS
+    )
+
+
+def _geospatial_reports(
+    *,
+    runtime_available: bool,
+) -> tuple[PassiveCapabilityProbeReport, ...]:
+    reasons = (
+        "geospatial_runtime_candidate_available"
+        if runtime_available
+        else "geospatial_runtime_not_found",
+        "geospatial_document_write_not_promoted",
+        "geospatial_sidecar_lineage_required",
+    )
+    return tuple(
+        _report(
+            known_format=known_format,
+            family=DocumentFormatFamily.geospatial_data,
+            read_adapter_id="geospatial-metadata-only-adapter",
+            runtime_id="gdal-or-pyshp-geospatial-reader",
+            runtime_available=runtime_available,
+            runtime_executable=None,
+            extraction_available=runtime_available,
+            reasons=reasons,
+            required_gates=(
+                "geospatial_runtime_available",
+                "sidecar_set_integrity_gate",
+                "geometry_metadata_extraction_gate",
+                "document_derivative_write_gate",
+            ),
+        )
+        for known_format in _GEOSPATIAL_FORMATS
+    )
+
+
+def _media_reports(*, ffprobe: Path | None) -> tuple[PassiveCapabilityProbeReport, ...]:
+    runtime_available = ffprobe is not None
+    reasons = (
+        "media_metadata_candidate_available" if runtime_available else "ffprobe_cli_not_found",
+        "media_transcription_not_promoted",
+        "media_document_write_not_promoted",
+    )
+    return tuple(
+        _report(
+            known_format=known_format,
+            family=DocumentFormatFamily.media_asset,
+            read_adapter_id="media-metadata-only-adapter",
+            runtime_id="ffprobe-media-metadata",
+            runtime_available=runtime_available,
+            runtime_executable=ffprobe,
+            extraction_available=runtime_available,
+            reasons=reasons,
+            required_gates=(
+                "media_metadata_runtime_available",
+                "transcription_or_metadata_extraction_gate",
+                "document_derivative_write_gate",
+                "media_original_preservation_gate",
+            ),
+        )
+        for known_format in _MEDIA_FORMATS
+    )
+
+
+def _report(
+    *,
+    known_format: KnownDocumentFormat,
+    family: DocumentFormatFamily,
+    read_adapter_id: str,
+    runtime_id: str,
+    runtime_available: bool,
+    runtime_executable: Path | None,
+    extraction_available: bool,
+    reasons: tuple[str, ...],
+    required_gates: tuple[str, ...],
+) -> PassiveCapabilityProbeReport:
+    return PassiveCapabilityProbeReport(
+        candidate_id=PASSIVE_CAPABILITY_CANDIDATE_ID,
+        known_format=known_format,
+        family=family,
+        status="candidate_available" if extraction_available else "blocked",
+        read_adapter_id=read_adapter_id,
+        runtime_id=runtime_id,
+        runtime_available=runtime_available,
+        runtime_executable=runtime_executable,
+        extraction_available=extraction_available,
+        direct_mutation_promoted=False,
+        reasons=reasons,
+        required_gates=required_gates,
+        evidence_refs=PASSIVE_CAPABILITY_SOURCE_REFS,
+    )
+
+
+def _geospatial_runtime_available(
+    *,
+    active_env: Mapping[str, str],
+    search_path: Sequence[str] | None,
+    importable_modules: frozenset[str] | None,
+) -> bool:
+    return (
+        _find_executable("ogrinfo", active_env=active_env, search_path=search_path) is not None
+        or _find_executable("gdalinfo", active_env=active_env, search_path=search_path) is not None
+        or _is_importable("shapefile", importable_modules=importable_modules)
+        or _is_importable("trimesh", importable_modules=importable_modules)
+    )
+
+
+def _find_executable(
+    name: str,
+    *,
+    active_env: Mapping[str, str],
+    search_path: Sequence[str] | None,
+) -> Path | None:
+    path_env = os.pathsep.join(search_path) if search_path is not None else active_env.get("PATH")
+    if not path_env:
+        return None
+    found = which(name, path=path_env)
+    if found is None:
+        return None
+    executable = Path(found).expanduser().resolve(strict=False)
+    if not _is_executable_file(executable):
+        return None
+    return executable
+
+
+def _is_importable(name: str, *, importable_modules: frozenset[str] | None) -> bool:
+    if importable_modules is not None:
+        return name in importable_modules
+    return find_spec(name) is not None
+
+
+def _is_executable_file(path: Path) -> bool:
+    return path.exists() and path.is_file() and os.access(path, os.X_OK)

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

@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Engine-backed document patch harness."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+from ummaya.tools.documents.artifact_store import DocumentArtifactStore
+from ummaya.tools.documents.diff import DocumentDiff, diff_from_patch
+from ummaya.tools.documents.engines import (
+    DocumentEngineRegistry,
+    DocumentMutationBlockedError,
+    DocumentMutationEngine,
+    UnsupportedDocumentEngineError,
+)
+from ummaya.tools.documents.models import (
+    ArtifactLineage,
+    BlockedReason,
+    DocumentArtifact,
+    DocumentExtraction,
+    DocumentPatch,
+    ToolResultStatus,
+)
+from ummaya.tools.documents.style import DocumentPatchValidationError, validate_document_patch
+
+logger = logging.getLogger(__name__)
+
+
+class DocumentPatchResult(BaseModel):
+    """Result of a copy or patch operation."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    status: ToolResultStatus
+    source_artifact: DocumentArtifact
+    derivative_artifact: DocumentArtifact | None = None
+    diff: DocumentDiff | None = None
+    blocked_reason: BlockedReason | None = None
+    text_summary: str
+
+
+def copy_for_edit(
+    store: DocumentArtifactStore,
+    source: DocumentArtifact,
+    *,
+    artifact_id: str,
+    destination_name: str,
+) -> DocumentArtifact:
+    """Create a working copy without mutating the source artifact."""
+    payload = Path(source.source_path).read_bytes()
+    return store.write_derivative(
+        source,
+        artifact_id=artifact_id,
+        lineage=ArtifactLineage.working_copy,
+        destination_name=destination_name,
+        payload=payload,
+    )
+
+
+def apply_document_patch(
+    store: DocumentArtifactStore,
+    working_artifact: DocumentArtifact,
+    patch: DocumentPatch,
+    *,
+    engine_registry: DocumentEngineRegistry,
+    artifact_id: str,
+    destination_name: str,
+) -> DocumentPatchResult:
+    """Apply an ordered patch through a promoted mutation engine."""
+    if patch.target_artifact_id != working_artifact.artifact_id:
+        return _blocked(
+            working_artifact,
+            BlockedReason.validation_failed,
+            "Document patch target does not match the working artifact.",
+        )
+    if patch.expected_format is not working_artifact.format:
+        return _blocked(
+            working_artifact,
+            BlockedReason.validation_failed,
+            "Document patch expected_format does not match the working artifact.",
+        )
+
+    try:
+        validate_document_patch(patch)
+        engine = engine_registry.require_mutation(working_artifact.format)
+    except DocumentPatchValidationError as exc:
+        return _blocked(working_artifact, BlockedReason.validation_failed, str(exc))
+    except UnsupportedDocumentEngineError:
+        return _blocked(
+            working_artifact,
+            BlockedReason.unsupported_operation,
+            f"No mutation-capable engine is registered for {working_artifact.format.value}.",
+        )
+
+    before_extraction = _safe_inspect_for_diff(
+        engine,
+        Path(working_artifact.source_path),
+        artifact_id=working_artifact.artifact_id,
+        phase="before",
+    )
+    try:
+        payload = engine.apply_patch(Path(working_artifact.source_path), patch)
+    except DocumentMutationBlockedError as exc:
+        return _blocked(working_artifact, exc.reason, str(exc))
+    except ValueError as exc:
+        return _blocked(working_artifact, BlockedReason.validation_failed, str(exc))
+    derivative = store.write_derivative(
+        working_artifact,
+        artifact_id=artifact_id,
+        lineage=ArtifactLineage.working_copy,
+        destination_name=destination_name,
+        payload=payload,
+    )
+    after_extraction = _safe_inspect_for_diff(
+        engine,
+        Path(derivative.source_path),
+        artifact_id=derivative.artifact_id,
+        phase="after",
+    )
+    return DocumentPatchResult(
+        status=ToolResultStatus.ok,
+        source_artifact=working_artifact,
+        derivative_artifact=derivative,
+        diff=diff_from_patch(
+            patch,
+            source_artifact_id=working_artifact.artifact_id,
+            derivative_artifact_id=derivative.artifact_id,
+            before_extraction=before_extraction,
+            after_extraction=after_extraction,
+        ),
+        text_summary=(
+            f"Applied {len(patch.operations)} document patch operation(s) "
+            f"through {engine.engine_id}."
+        ),
+    )
+
+
+def _blocked(
+    source: DocumentArtifact,
+    reason: BlockedReason,
+    message: str,
+) -> DocumentPatchResult:
+    return DocumentPatchResult(
+        status=ToolResultStatus.blocked,
+        source_artifact=source,
+        blocked_reason=reason,
+        text_summary=message,
+    )
+
+
+def _safe_inspect_for_diff(
+    engine: DocumentMutationEngine,
+    path: Path,
+    *,
+    artifact_id: str,
+    phase: str,
+) -> DocumentExtraction | None:
+    try:
+        return engine.inspect(path, artifact_id=artifact_id)
+    except Exception as exc:  # pragma: no cover - defensive evidence enrichment path.
+        logger.warning(
+            "Document patch diff %s-inspection failed for %s: %s",
+            phase,
+            artifact_id,
+            exc,
+        )
+        return None