ummaya 0.2.3 → 0.2.5

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

@@ -0,0 +1,244 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Final
+
+from ummaya.tools.documents.adapter_registry import (
+    DocumentAdapterRegistry,
+    UnsupportedDocumentAdapterError,
+)
+from ummaya.tools.documents.authoring import hash_authoring_text
+from ummaya.tools.documents.conversion import (
+    DocumentConversionRegistry,
+    UnsupportedDocumentConversionError,
+)
+from ummaya.tools.documents.models import (
+    BlockedReason,
+    DocumentArtifact,
+    DocumentExtraction,
+    DocumentFormat,
+    DocumentToolResult,
+)
+from ummaya.tools.documents.runtime_authoring_bundle import (
+    IssuedAuthoringDraft,
+    approved_patch_bundle_matches_issued_draft,
+    issued_authoring_bundle,
+    issued_authoring_draft_id,
+)
+from ummaya.tools.documents.tool_defs import unsupported_document_tool_result
+
+if TYPE_CHECKING:
+    from ummaya.tools.documents.tool_defs import DocumentFieldPatch
+
+_NARRATIVE_TERMS: Final[tuple[str, ...]] = (
+    "자기소개",
+    "지원동기",
+    "성장과정",
+    "사업계획",
+    "계획",
+    "경험",
+    "수상",
+    "문항",
+    "motivation",
+    "selfintro",
+    "businessplan",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class EditableDerivativePreview:
+    document_format: DocumentFormat
+    extraction: DocumentExtraction
+
+
+def preview_editable_derivative(
+    source: DocumentArtifact,
+    *,
+    correlation_id: str,
+    derivative_format: DocumentFormat,
+    conversion_registry: DocumentConversionRegistry,
+    adapter_registry: DocumentAdapterRegistry,
+) -> EditableDerivativePreview | DocumentToolResult:
+    try:
+        engine = conversion_registry.require(source.format, derivative_format)
+    except UnsupportedDocumentConversionError:
+        return unsupported_document_tool_result(
+            tool_id="document",
+            correlation_id=correlation_id,
+            artifact_refs=(source.artifact_id,),
+            message=_missing_conversion_message(source.format, derivative_format),
+        )
+    try:
+        payload = engine.convert_for_edit(source)
+    except ValueError as exc:
+        return unsupported_document_tool_result(
+            tool_id="document",
+            correlation_id=correlation_id,
+            artifact_refs=(source.artifact_id,),
+            message=f"Document conversion failed before authoring planning: {exc}",
+            reason=BlockedReason.validation_failed,
+        )
+    try:
+        adapter = adapter_registry.require_promoted(derivative_format)
+    except UnsupportedDocumentAdapterError:
+        return unsupported_document_tool_result(
+            tool_id="document",
+            correlation_id=correlation_id,
+            artifact_refs=(source.artifact_id,),
+            message=(
+                f"No promoted {derivative_format.value} adapter is registered for "
+                "authoring planning."
+            ),
+        )
+    with tempfile.TemporaryDirectory(prefix="ummaya-authoring-preview-") as temp_root:
+        preview_path = Path(temp_root) / f"preview.{derivative_format.value}"
+        preview_path.write_bytes(payload)
+        extraction = adapter.inspect(preview_path, artifact_id=correlation_id)
+    return EditableDerivativePreview(document_format=derivative_format, extraction=extraction)
+
+
+def unapproved_narrative_patch_targets(
+    patches: tuple[DocumentFieldPatch, ...],
+    *,
+    extraction: DocumentExtraction | None,
+    approved_draft_id: str | None,
+    approved_draft_sha256: str | None,
+    issued_drafts: tuple[IssuedAuthoringDraft, ...],
+) -> tuple[str, ...]:
+    narrative_patches = _string_narrative_patches(patches, extraction=extraction)
+    if approved_patch_bundle_matches_issued_draft(
+        narrative_patches,
+        approved_draft_id=approved_draft_id,
+        approved_draft_sha256=approved_draft_sha256,
+        issued_drafts=issued_drafts,
+    ):
+        return ()
+    blocked_targets: list[str] = []
+    for patch in patches:
+        if not _patch_targets_narrative_content(patch, extraction=extraction):
+            continue
+        if _approved_patch_matches_issued_draft(
+            patch,
+            approved_draft_id=approved_draft_id,
+            approved_draft_sha256=approved_draft_sha256,
+            issued_drafts=issued_drafts,
+        ):
+            continue
+        blocked_targets.append(patch.target_path)
+    return tuple(blocked_targets)
+
+
+def issue_authoring_drafts_for_unapproved_patches(
+    patches: tuple[DocumentFieldPatch, ...],
+    *,
+    extraction: DocumentExtraction | None,
+) -> tuple[IssuedAuthoringDraft, ...]:
+    drafts: list[IssuedAuthoringDraft] = []
+    narrative_patches: list[DocumentFieldPatch] = []
+    for patch in patches:
+        if not isinstance(patch.value, str):
+            continue
+        if not _patch_targets_narrative_content(patch, extraction=extraction):
+            continue
+        narrative_patches.append(patch)
+        draft_sha256 = hash_authoring_text(patch.value)
+        drafts.append(
+            IssuedAuthoringDraft(
+                draft_id=issued_authoring_draft_id(
+                    target_path=patch.target_path,
+                    draft_sha256=draft_sha256,
+                ),
+                target_path=patch.target_path,
+                draft_sha256=draft_sha256,
+                target_paths=(patch.target_path,),
+            )
+        )
+    if len(narrative_patches) > 1:
+        return (issued_authoring_bundle(tuple(narrative_patches)), *drafts)
+    return tuple(drafts)
+
+
+def _approved_patch_matches_issued_draft(
+    patch: DocumentFieldPatch,
+    *,
+    approved_draft_id: str | None,
+    approved_draft_sha256: str | None,
+    issued_drafts: tuple[IssuedAuthoringDraft, ...],
+) -> bool:
+    if not isinstance(patch.value, str):
+        return False
+    if approved_draft_id is None or approved_draft_sha256 is None:
+        return False
+    if hash_authoring_text(patch.value) != approved_draft_sha256:
+        return False
+    for draft in issued_drafts:
+        if (
+            draft.draft_id == approved_draft_id
+            and draft.target_path == patch.target_path
+            and draft.draft_sha256 == approved_draft_sha256
+        ):
+            return True
+    return False
+
+
+def _string_narrative_patches(
+    patches: tuple[DocumentFieldPatch, ...],
+    *,
+    extraction: DocumentExtraction | None,
+) -> tuple[DocumentFieldPatch, ...]:
+    return tuple(
+        patch
+        for patch in patches
+        if isinstance(patch.value, str)
+        and _patch_targets_narrative_content(patch, extraction=extraction)
+    )
+
+
+def _patch_targets_narrative_content(
+    patch: DocumentFieldPatch,
+    *,
+    extraction: DocumentExtraction | None,
+) -> bool:
+    patch_key = _normalize_authoring_key(patch.target_path)
+    if extraction is None:
+        return _has_narrative_term(patch_key)
+    for field in extraction.fields:
+        field_keys = {
+            _normalize_authoring_key(field.field_id),
+            _normalize_authoring_key(field.label),
+            _normalize_authoring_key(field.path),
+        }
+        if patch_key not in field_keys:
+            continue
+        return any(_has_narrative_term(field_key) for field_key in field_keys)
+    return _has_narrative_term(patch_key)
+
+
+def _has_narrative_term(value: str) -> bool:
+    return any(term in value for term in _NARRATIVE_TERMS)
+
+
+def _normalize_authoring_key(value: str) -> str:
+    return "".join(character for character in value.casefold() if character.isalnum())
+
+
+def _missing_conversion_message(
+    source_format: DocumentFormat,
+    derivative_format: DocumentFormat,
+) -> str:
+    if source_format is DocumentFormat.hwp:
+        return (
+            "HWP binary direct writing is blocked. HWP to HWPX conversion is "
+            "required before editing legacy HWP files. Direct HWP binary working "
+            "copies remain blocked. Use a HWPX or DOCX editable template, or "
+            "register a vetted local HWP to HWPX conversion engine."
+        )
+    return (
+        f"Document conversion is required before planning edits for "
+        f"{source_format.value} files, but no promoted "
+        f"{source_format.value}->{derivative_format.value} conversion engine is registered."
+    )

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

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import TYPE_CHECKING
+
+from ummaya.tools.documents.authoring import hash_authoring_text
+
+if TYPE_CHECKING:
+    from ummaya.tools.documents.tool_defs import DocumentFieldPatch
+
+
+@dataclass(frozen=True, slots=True)
+class IssuedAuthoringDraft:
+    draft_id: str
+    target_path: str
+    draft_sha256: str
+    target_paths: tuple[str, ...] = ()
+
+
+def issued_authoring_draft_id(*, target_path: str, draft_sha256: str) -> str:
+    token = sha256(f"{target_path}\0{draft_sha256}".encode()).hexdigest()[:24]
+    return f"draft-{token}"
+
+
+def approved_patch_bundle_matches_issued_draft(
+    patches: tuple[DocumentFieldPatch, ...],
+    *,
+    approved_draft_id: str | None,
+    approved_draft_sha256: str | None,
+    issued_drafts: tuple[IssuedAuthoringDraft, ...],
+) -> bool:
+    if len(patches) < 2 or approved_draft_id is None or approved_draft_sha256 is None:
+        return False
+    draft_sha256 = _authoring_bundle_sha256(patches)
+    if draft_sha256 != approved_draft_sha256:
+        return False
+    target_paths = tuple(patch.target_path for patch in patches)
+    return any(
+        draft.draft_id == approved_draft_id
+        and draft.draft_sha256 == approved_draft_sha256
+        and draft.target_paths == target_paths
+        for draft in issued_drafts
+    )
+
+
+def issued_authoring_bundle(
+    patches: tuple[DocumentFieldPatch, ...],
+) -> IssuedAuthoringDraft:
+    target_paths = tuple(patch.target_path for patch in patches)
+    draft_sha256 = _authoring_bundle_sha256(patches)
+    bundle_target = _authoring_bundle_target_path(target_paths)
+    return IssuedAuthoringDraft(
+        draft_id=issued_authoring_draft_id(
+            target_path=bundle_target,
+            draft_sha256=draft_sha256,
+        ),
+        target_path=bundle_target,
+        draft_sha256=draft_sha256,
+        target_paths=target_paths,
+    )
+
+
+def _authoring_bundle_sha256(patches: tuple[DocumentFieldPatch, ...]) -> str:
+    return hash_authoring_text(
+        "\0".join(
+            f"{patch.target_path}\0{hash_authoring_text(str(patch.value))}" for patch in patches
+        )
+    )
+
+
+def _authoring_bundle_target_path(target_paths: tuple[str, ...]) -> str:
+    token = sha256("\0".join(target_paths).encode()).hexdigest()[:24]
+    return f"bundle:{token}"

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

@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Promotion scorecards for Public AX document capabilities."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Final, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ummaya.tools.documents.baselines import ConformanceBaseline
+from ummaya.tools.documents.models import DocumentExtraction, TableBlock
+
+ScoreDimension = Literal[
+    "extraction_fidelity",
+    "write_fidelity",
+    "style_layout_control",
+    "deterministic_round_trip",
+    "public_form_validation",
+    "security_privacy",
+    "license_maintenance_tool_usability",
+]
+
+SCORECARD_WEIGHTS: Final[dict[ScoreDimension, int]] = {
+    "extraction_fidelity": 20,
+    "write_fidelity": 20,
+    "style_layout_control": 15,
+    "deterministic_round_trip": 15,
+    "public_form_validation": 15,
+    "security_privacy": 10,
+    "license_maintenance_tool_usability": 5,
+}
+
+
+class CapabilityScorecard(BaseModel):
+    """Evidence-backed promotion score for one format engine."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    extraction_fidelity: int = Field(
+        ge=0,
+        le=SCORECARD_WEIGHTS["extraction_fidelity"],
+    )
+    write_fidelity: int = Field(
+        ge=0,
+        le=SCORECARD_WEIGHTS["write_fidelity"],
+    )
+    style_layout_control: int = Field(
+        ge=0,
+        le=SCORECARD_WEIGHTS["style_layout_control"],
+    )
+    deterministic_round_trip: int = Field(
+        ge=0,
+        le=SCORECARD_WEIGHTS["deterministic_round_trip"],
+    )
+    public_form_validation: int = Field(
+        ge=0,
+        le=SCORECARD_WEIGHTS["public_form_validation"],
+    )
+    security_privacy: int = Field(
+        ge=0,
+        le=SCORECARD_WEIGHTS["security_privacy"],
+    )
+    license_maintenance_tool_usability: int = Field(
+        ge=0,
+        le=SCORECARD_WEIGHTS["license_maintenance_tool_usability"],
+    )
+
+    security_gate_passed: bool = True
+    write_hard_gates_passed: bool = True
+    critical_security_findings: tuple[str, ...] = Field(default_factory=tuple)
+    evidence_refs: tuple[str, ...] = Field(default_factory=tuple)
+
+    @property
+    def total_score(self) -> int:
+        """Return the weighted 100-point total for this scorecard."""
+        return (
+            self.extraction_fidelity
+            + self.write_fidelity
+            + self.style_layout_control
+            + self.deterministic_round_trip
+            + self.public_form_validation
+            + self.security_privacy
+            + self.license_maintenance_tool_usability
+        )
+
+
+class PublicFormMetricScore(BaseModel):
+    """Semantic and structural public-form metric bundle."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    paragraph_block_f1: Decimal = Field(ge=0, le=1)
+    table_cell_f1: Decimal = Field(ge=0, le=1)
+    image_reference_f1: Decimal = Field(ge=0, le=1)
+    metadata_exact_match: Decimal = Field(ge=0, le=1)
+    aggregate_score: Decimal = Field(ge=0, le=1)
+
+
+def compute_public_form_metrics(
+    extraction: DocumentExtraction,
+    baseline: ConformanceBaseline,
+) -> PublicFormMetricScore:
+    """Compute the offline semantic metrics used by public-form validation."""
+    paragraph_f1 = _paragraph_f1(extraction, baseline)
+    table_f1 = _table_cell_f1(extraction, baseline)
+    image_f1 = Decimal("1")
+    metadata_match = _metadata_exact_match(extraction, baseline)
+    return PublicFormMetricScore(
+        paragraph_block_f1=paragraph_f1,
+        table_cell_f1=table_f1,
+        image_reference_f1=image_f1,
+        metadata_exact_match=metadata_match,
+        aggregate_score=_macro_average((paragraph_f1, table_f1, image_f1, metadata_match)),
+    )
+
+
+def _paragraph_f1(extraction: DocumentExtraction, baseline: ConformanceBaseline) -> Decimal:
+    expected = {
+        item.text
+        for item in (
+            *baseline.protected_text,
+            *baseline.required_labels,
+            *baseline.signature_regions,
+        )
+    }
+    observed = {paragraph.text for paragraph in extraction.paragraphs}
+    observed.update(cell.text for table in extraction.tables for cell in table.cells)
+    return _set_f1(expected, observed)
+
+
+def _table_cell_f1(extraction: DocumentExtraction, baseline: ConformanceBaseline) -> Decimal:
+    expected = {
+        (geometry.table_id, row, column)
+        for geometry in baseline.table_geometries
+        for row in range(geometry.rows)
+        for column in range(geometry.columns)
+    }
+    observed = {
+        (table.block_id, cell.row_index, cell.column_index)
+        for table in extraction.tables
+        for cell in table.cells
+    }
+    return _set_f1(expected, observed)
+
+
+def _metadata_exact_match(
+    extraction: DocumentExtraction,
+    baseline: ConformanceBaseline,
+) -> Decimal:
+    expected = dict(baseline.metadata_exact_matches)
+    if baseline.expected_page_count is not None:
+        expected["page_count"] = baseline.expected_page_count
+    if not expected:
+        return Decimal("1")
+    matches = sum(1 for key, value in expected.items() if extraction.metadata.get(key) == value)
+    return Decimal(matches) / Decimal(len(expected))
+
+
+def _set_f1[F1Item](expected: set[F1Item], observed: set[F1Item]) -> Decimal:
+    if not expected and not observed:
+        return Decimal("1")
+    if not expected or not observed:
+        return Decimal("0")
+    matches = len(expected & observed)
+    if matches == 0:
+        return Decimal("0")
+    precision = Decimal(matches) / Decimal(len(observed))
+    recall = Decimal(matches) / Decimal(len(expected))
+    return (Decimal("2") * precision * recall) / (precision + recall)
+
+
+def _macro_average(values: tuple[Decimal, Decimal, Decimal, Decimal]) -> Decimal:
+    return sum(values, Decimal("0")) / Decimal(len(values))
+
+
+def table_shape(table: TableBlock | None) -> tuple[int, int]:
+    """Return the row and column shape for a normalized table block."""
+    if table is None or not table.cells:
+        return 0, 0
+    return (
+        max(cell.row_index + cell.row_span for cell in table.cells),
+        max(cell.column_index + cell.column_span for cell in table.cells),
+    )

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

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Final
+
+from ummaya.tools.documents.models import FormSlot, ScalarValue
+
+_NEEDS_INPUT_PREFIX: Final[str] = "needs_input:"
+_BLOCKED_MISSING_EVIDENCE_PREFIX: Final[str] = "blocked_missing_evidence:"
+_DRAFT_REQUIRES_APPROVAL_PREFIX: Final[str] = "draft_requires_approval:"
+
+_FABRICATION_TERMS: Final[tuple[str, ...]] = (
+    "대충",
+    "그럴듯",
+    "그럴싸",
+    "적당히",
+    "임의로",
+)
+_AUTHORING_TERMS: Final[tuple[str, ...]] = (
+    "작성",
+    "써줘",
+    "써",
+    "완성",
+    "채워",
+    "기입",
+    "해줘",
+)
+_NARRATIVE_TERMS: Final[tuple[str, ...]] = (
+    "자기소개",
+    "지원동기",
+    "성장과정",
+    "경험",
+    "경력",
+    "수상",
+    "사업계획",
+    "계획",
+    "시장",
+    "예산",
+    "성과",
+    "목표",
+    "제안내용",
+    "문항",
+    "에세이",
+)
+
+
+def apply_socratic_fill_gate(
+    slot: FormSlot,
+    *,
+    instruction: str,
+    session_context: Mapping[str, ScalarValue],
+    explicit_value_provided: bool,
+    context_value_provided: bool,
+    broad_autonomous_fill: bool,
+) -> FormSlot:
+    if explicit_value_provided:
+        return _with_provenance(slot, "user_provided_explicit_value")
+    if slot.protected:
+        return slot
+    if _is_document_derived_candidate(slot):
+        return _with_provenance(slot, "document_derived")
+    if _instruction_requests_fabrication(instruction) and _slot_is_empty(slot):
+        return _with_socratic_evidence(
+            slot,
+            prefix=_BLOCKED_MISSING_EVIDENCE_PREFIX,
+            candidate_value=None,
+        )
+    if _is_narrative_slot(slot) and _slot_is_empty(slot):
+        return _gate_narrative_slot(
+            slot,
+            session_context=session_context,
+            context_value_provided=context_value_provided,
+        )
+    if broad_autonomous_fill and _slot_is_empty(slot):
+        if context_value_provided:
+            return _with_provenance(slot, "user_provided_context")
+        return _with_socratic_evidence(slot, prefix=_NEEDS_INPUT_PREFIX, candidate_value=None)
+    return slot
+
+
+def socratic_slot_requires_input(slot: FormSlot) -> bool:
+    return slot.evidence_text is not None and slot.evidence_text.startswith(
+        (
+            _NEEDS_INPUT_PREFIX,
+            _BLOCKED_MISSING_EVIDENCE_PREFIX,
+            _DRAFT_REQUIRES_APPROVAL_PREFIX,
+        )
+    )
+
+
+def _gate_narrative_slot(
+    slot: FormSlot,
+    *,
+    session_context: Mapping[str, ScalarValue],
+    context_value_provided: bool,
+) -> FormSlot:
+    if not context_value_provided:
+        return _with_socratic_evidence(slot, prefix=_NEEDS_INPUT_PREFIX, candidate_value=None)
+    if _context_has_approval(slot, session_context):
+        return slot.model_copy(update={"evidence_text": "approved_user_draft"})
+    return _with_socratic_evidence(
+        slot,
+        prefix=_DRAFT_REQUIRES_APPROVAL_PREFIX,
+        candidate_value=None,
+    )
+
+
+def _with_socratic_evidence(
+    slot: FormSlot,
+    *,
+    prefix: str,
+    candidate_value: ScalarValue,
+) -> FormSlot:
+    return slot.model_copy(
+        update={
+            "candidate_value": candidate_value,
+            "evidence_text": f"{prefix}{_question_for_slot(slot)}",
+        }
+    )
+
+
+def _with_provenance(slot: FormSlot, evidence_text: str) -> FormSlot:
+    if slot.candidate_value is None or slot.evidence_text is not None:
+        return slot
+    return slot.model_copy(update={"evidence_text": evidence_text})
+
+
+def _question_for_slot(slot: FormSlot) -> str:
+    return f"{slot.label} 항목을 작성할 사용자 제공 근거를 알려주세요."
+
+
+def _is_document_derived_candidate(slot: FormSlot) -> bool:
+    if slot.candidate_value is None:
+        return False
+    slot_key = _slot_key(slot)
+    if ("주차" in slot_key or "week" in slot_key) and slot.current_value is not None:
+        return True
+    return (
+        "활동기간" in slot_key or "활동일시" in slot_key or "period" in slot_key
+    ) and slot.current_value is not None
+
+
+def _is_narrative_slot(slot: FormSlot) -> bool:
+    slot_key = _slot_key(slot)
+    return any(term in slot_key for term in _NARRATIVE_TERMS)
+
+
+def _instruction_requests_fabrication(instruction: str) -> bool:
+    instruction_key = _normalize_key(instruction)
+    return any(term in instruction_key for term in _FABRICATION_TERMS) and any(
+        term in instruction_key for term in _AUTHORING_TERMS
+    )
+
+
+def _context_has_approval(
+    slot: FormSlot,
+    session_context: Mapping[str, ScalarValue],
+) -> bool:
+    approval_keys = _approval_keys_for_slot(slot)
+    for key, value in session_context.items():
+        if _normalize_key(key) not in approval_keys:
+            continue
+        if value is True:
+            return True
+        if isinstance(value, str) and _normalize_key(value) in {"승인", "approved", "approve"}:
+            return True
+    return False
+
+
+def _approval_keys_for_slot(slot: FormSlot) -> set[str]:
+    keys: set[str] = set()
+    for label in (slot.slot_id, slot.label, slot.source_anchor.format_path):
+        normalized = _normalize_key(label)
+        keys.add(f"approved{normalized}")
+        keys.add(f"approval{normalized}")
+        keys.add(f"승인{normalized}")
+    return keys
+
+
+def _slot_is_empty(slot: FormSlot) -> bool:
+    value = slot.current_value
+    return value is None or (isinstance(value, str) and value.strip() == "")
+
+
+def _slot_key(slot: FormSlot) -> str:
+    return _normalize_key(f"{slot.slot_id} {slot.label} {slot.source_anchor.format_path}")
+
+
+def _normalize_key(value: str) -> str:
+    return re.sub(r"[^0-9a-z가-힣]+", "", value.casefold())