ummaya 0.2.3 → 0.2.5

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

@@ -0,0 +1,347 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Public-form conformance validation for extracted document artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+from decimal import Decimal
+
+from ummaya.tools.documents.baselines import (
+    BaselineTableGeometry,
+    BaselineTextAnchor,
+    ConformanceBaseline,
+)
+from ummaya.tools.documents.models import (
+    BlockedReason,
+    DocumentExtraction,
+    DocumentToolResult,
+    PublicFormValidationReport,
+    ToolResultStatus,
+    ValidationDecision,
+    ValidationFinding,
+    ValidationReadiness,
+)
+from ummaya.tools.documents.scorecard import compute_public_form_metrics, table_shape
+
+
+def validate_public_form(
+    extraction: DocumentExtraction,
+    *,
+    baseline: ConformanceBaseline,
+    artifact_id: str,
+    correlation_id: str,
+    round_trip_passed: bool = True,
+    render_passed: bool = True,
+    security_passed: bool = True,
+) -> DocumentToolResult:
+    """Validate one extracted derivative against a public-form baseline."""
+    if not baseline.supports_conformance:
+        finding = _finding(
+            code="unsupported_for_conformance",
+            message=baseline.unsupported_reason or "Public-form conformance is not supported.",
+            anchor=f"template:{baseline.template_id}",
+            remediation_hint="Use a promoted editable format with conformance evidence.",
+        )
+        report = _report(
+            extraction,
+            baseline=baseline,
+            artifact_id=artifact_id,
+            findings=[finding],
+            decision=ValidationDecision.blocked,
+            readiness=ValidationReadiness.unsupported,
+            round_trip_passed=round_trip_passed,
+            render_passed=render_passed,
+            security_passed=security_passed,
+        )
+        return _result(
+            report,
+            status=ToolResultStatus.blocked,
+            blocked_reason=BlockedReason.unsupported_operation,
+            summary="Public-form validation blocked: conformance is unsupported.",
+            correlation_id=correlation_id,
+        )
+
+    findings = _hard_rule_findings(extraction, baseline)
+    if not security_passed:
+        findings.append(
+            _finding(
+                code="security_check_failed",
+                message="Security validation failed before public-form readiness.",
+                anchor=f"artifact:{artifact_id}",
+                remediation_hint="Resolve document security findings before validation.",
+            )
+        )
+    if not round_trip_passed:
+        findings.append(
+            _finding(
+                code="round_trip_mismatch",
+                message="Round-trip extraction did not match intended document values.",
+                anchor=f"artifact:{artifact_id}",
+                remediation_hint="Re-read the derivative and repair mismatched values.",
+            )
+        )
+    if not render_passed:
+        findings.append(
+            _finding(
+                code="render_mismatch",
+                message="Rendered derivative evidence did not match the expected layout.",
+                anchor=f"artifact:{artifact_id}",
+                remediation_hint="Repair layout drift and regenerate render evidence.",
+            )
+        )
+
+    metrics = compute_public_form_metrics(extraction, baseline)
+    hard_failure = any(finding.severity == "hard_failure" for finding in findings)
+    decision, readiness = _decision(
+        aggregate_score=metrics.aggregate_score,
+        hard_failure=hard_failure,
+        round_trip_passed=round_trip_passed,
+        render_passed=render_passed,
+        security_passed=security_passed,
+    )
+    report = _report(
+        extraction,
+        baseline=baseline,
+        artifact_id=artifact_id,
+        findings=findings,
+        decision=decision,
+        readiness=readiness,
+        round_trip_passed=round_trip_passed,
+        render_passed=render_passed,
+        security_passed=security_passed,
+    )
+    if decision is ValidationDecision.pass_:
+        return _result(
+            report,
+            status=ToolResultStatus.ok,
+            blocked_reason=None,
+            summary="Public-form validation passed; artifact is ready for human review.",
+            correlation_id=correlation_id,
+        )
+    blocked_reason = (
+        BlockedReason.unsupported_operation
+        if readiness is ValidationReadiness.unsupported
+        else BlockedReason.validation_failed
+    )
+    return _result(
+        report,
+        status=ToolResultStatus.blocked,
+        blocked_reason=blocked_reason,
+        summary="Public-form validation failed; artifact is not ready.",
+        correlation_id=correlation_id,
+    )
+
+
+def _hard_rule_findings(
+    extraction: DocumentExtraction,
+    baseline: ConformanceBaseline,
+) -> list[ValidationFinding]:
+    findings: list[ValidationFinding] = []
+    findings.extend(_required_field_findings(extraction, baseline))
+    findings.extend(
+        _required_text_findings(
+            extraction,
+            baseline.protected_text,
+            "protected_text_missing",
+        )
+    )
+    findings.extend(
+        _required_text_findings(
+            extraction,
+            baseline.required_labels,
+            "required_label_missing",
+        )
+    )
+    findings.extend(_table_geometry_findings(extraction, baseline.table_geometries))
+    findings.extend(
+        _required_text_findings(
+            extraction,
+            baseline.signature_regions,
+            "signature_or_seal_region_missing",
+        )
+    )
+    findings.extend(_metadata_findings(extraction, baseline))
+    return findings
+
+
+def _required_field_findings(
+    extraction: DocumentExtraction,
+    baseline: ConformanceBaseline,
+) -> list[ValidationFinding]:
+    by_field_id = {field.field_id: field for field in extraction.fields}
+    findings: list[ValidationFinding] = []
+    for required in baseline.required_fields:
+        observed = by_field_id.get(required.field_id)
+        if observed is None or observed.current_value in {None, ""}:
+            findings.append(
+                _finding(
+                    code="required_field_missing",
+                    message=f"Required field {required.label!r} is missing or empty.",
+                    anchor=required.path,
+                    remediation_hint=f"Fill the {required.label!r} field before export.",
+                )
+            )
+    return findings
+
+
+def _required_text_findings(
+    extraction: DocumentExtraction,
+    expected: tuple[BaselineTextAnchor, ...],
+    code: str,
+) -> list[ValidationFinding]:
+    observed_text = _combined_text(extraction)
+    findings: list[ValidationFinding] = []
+    for item in expected:
+        if item.text not in observed_text:
+            findings.append(
+                _finding(
+                    code=code,
+                    message=f"Required public-form text {item.text!r} is missing.",
+                    anchor=item.anchor,
+                    remediation_hint=f"Restore required text {item.text!r} at the baseline anchor.",
+                )
+            )
+    return findings
+
+
+def _table_geometry_findings(
+    extraction: DocumentExtraction,
+    expected: tuple[BaselineTableGeometry, ...],
+) -> list[ValidationFinding]:
+    tables_by_id = {table.block_id: table for table in extraction.tables}
+    findings: list[ValidationFinding] = []
+    for geometry in expected:
+        observed = tables_by_id.get(geometry.table_id)
+        observed_rows, observed_columns = table_shape(observed)
+        if observed_rows != geometry.rows or observed_columns != geometry.columns:
+            findings.append(
+                _finding(
+                    code="table_geometry_mismatch",
+                    message=(
+                        f"Table {geometry.table_id!r} shape is "
+                        f"{observed_rows}x{observed_columns}, expected "
+                        f"{geometry.rows}x{geometry.columns}."
+                    ),
+                    anchor=geometry.anchor,
+                    remediation_hint="Restore the protected table row and column geometry.",
+                )
+            )
+    return findings
+
+
+def _metadata_findings(
+    extraction: DocumentExtraction,
+    baseline: ConformanceBaseline,
+) -> list[ValidationFinding]:
+    findings: list[ValidationFinding] = []
+    expected_metadata = dict(baseline.metadata_exact_matches)
+    if baseline.expected_page_count is not None:
+        expected_metadata["page_count"] = baseline.expected_page_count
+    for key, expected in expected_metadata.items():
+        observed = extraction.metadata.get(key)
+        if observed != expected:
+            findings.append(
+                _finding(
+                    code="metadata_mismatch",
+                    message=f"Metadata {key!r} is {observed!r}, expected {expected!r}.",
+                    anchor=f"metadata:{key}",
+                    remediation_hint=f"Restore metadata {key!r} to the baseline value.",
+                )
+            )
+    return findings
+
+
+def _report(
+    extraction: DocumentExtraction,
+    *,
+    baseline: ConformanceBaseline,
+    artifact_id: str,
+    findings: list[ValidationFinding],
+    decision: ValidationDecision,
+    readiness: ValidationReadiness,
+    round_trip_passed: bool,
+    render_passed: bool,
+    security_passed: bool,
+) -> PublicFormValidationReport:
+    metrics = compute_public_form_metrics(extraction, baseline)
+    return PublicFormValidationReport(
+        report_id=f"validation-{artifact_id}-{baseline.template_id}",
+        artifact_id=artifact_id,
+        template_id=baseline.template_id,
+        schema_id=baseline.schema_id,
+        paragraph_block_f1=metrics.paragraph_block_f1,
+        table_cell_f1=metrics.table_cell_f1,
+        image_reference_f1=metrics.image_reference_f1,
+        metadata_exact_match=metrics.metadata_exact_match,
+        aggregate_score=metrics.aggregate_score,
+        round_trip_passed=round_trip_passed,
+        render_passed=render_passed,
+        security_passed=security_passed,
+        findings=findings,
+        decision=decision,
+        readiness=readiness,
+    )
+
+
+def _result(
+    report: PublicFormValidationReport,
+    *,
+    status: ToolResultStatus,
+    blocked_reason: BlockedReason | None,
+    summary: str,
+    correlation_id: str,
+) -> DocumentToolResult:
+    return DocumentToolResult(
+        tool_id="document_validate_public_form",
+        correlation_id=correlation_id,
+        status=status,
+        artifact_refs=[report.artifact_id],
+        validation_report=report,
+        findings=list(report.findings),
+        text_summary=summary,
+        blocked_reason=blocked_reason,
+    )
+
+
+def _decision(
+    *,
+    aggregate_score: Decimal,
+    hard_failure: bool,
+    round_trip_passed: bool,
+    render_passed: bool,
+    security_passed: bool,
+) -> tuple[ValidationDecision, ValidationReadiness]:
+    if not security_passed:
+        return ValidationDecision.blocked, ValidationReadiness.blocked
+    if hard_failure or not round_trip_passed or not render_passed:
+        if not round_trip_passed or not render_passed:
+            return ValidationDecision.needs_manual_review, ValidationReadiness.not_ready
+        return ValidationDecision.fail, ValidationReadiness.not_ready
+    if aggregate_score < Decimal("0.85"):
+        return ValidationDecision.fail, ValidationReadiness.not_ready
+    return ValidationDecision.pass_, ValidationReadiness.ready_for_review
+
+
+def _combined_text(extraction: DocumentExtraction) -> str:
+    parts = [paragraph.text for paragraph in extraction.paragraphs]
+    parts.extend(cell.text for table in extraction.tables for cell in table.cells)
+    parts.extend(field.label for field in extraction.fields)
+    return "\n".join(parts)
+
+
+def _finding(
+    *,
+    code: str,
+    message: str,
+    anchor: str,
+    remediation_hint: str,
+) -> ValidationFinding:
+    digest = hashlib.sha256(f"{code}\0{anchor}\0{message}".encode()).hexdigest()[:12]
+    return ValidationFinding(
+        finding_id=f"validation-{code}-{digest}",
+        severity="hard_failure",
+        code=code,
+        message=message,
+        anchor=anchor,
+        remediation_hint=remediation_hint,
+    )

package/src/ummaya/tools/executor.py

@@ -30,6 +30,7 @@ from ummaya.tools.envelope import make_error_envelope, normalize
 from ummaya.tools.errors import (
     EnvelopeNormalizationError,
     LookupErrorReason,
+    ToolExecutionError,
     ToolNotFoundError,
     UmmayaToolError,
 )
@@ -46,6 +47,7 @@ logger = logging.getLogger(__name__)
 _tracer = trace.get_tracer(__name__)
 
 AdapterFn = Callable[[BaseModel], Awaitable[dict[str, Any]]]
+SessionAwareAdapterFn = Callable[[BaseModel, object | None], Awaitable[dict[str, Any]]]
 
 _LOOKUP_ENVELOPE_KINDS: frozenset[str] = frozenset(
     {"record", "collection", "timeseries", "error", "search"}
@@ -79,6 +81,11 @@ def _classify_adapter_exception(exc: Exception) -> tuple[LookupErrorReason, bool
     if isinstance(exc, Layer3GateViolation):
         # Programming error: stub handler was reached despite auth-gate — never retry.
         return (LookupErrorReason.upstream_unavailable, False)
+    if isinstance(exc, ToolExecutionError) and isinstance(exc.cause, httpx.HTTPStatusError):
+        status_code = exc.cause.response.status_code
+        if status_code in {400, 401, 403, 404}:
+            return (LookupErrorReason.upstream_unavailable, False)
+        return (LookupErrorReason.upstream_unavailable, True)
     if isinstance(exc, LiveAdapterProxyConfigurationError):
         return (LookupErrorReason.upstream_unavailable, False)
     if isinstance(exc, (ValueError, TypeError, KMADomainError)):
@@ -118,6 +125,19 @@ def _adapter_validation_recovery_hint(tool_id: str) -> str:
             " prefer nmc_emergency_search when authenticated, or a location POI"
             " search when no authenticated NMC session is present."
         )
+    if tool_id == "nmc_aed_site_locate":
+        return (
+            " REGION FILTER ONLY: this AED adapter uses official NMC Q0/Q1"
+            " region filters, not ER-search mode. If you have"
+            " a place name, call kakao_keyword_search({query:'<장소명>'}), then"
+            " kakao_coord_to_region({lat:<lat>, lon:<lon>}). Re-invoke this"
+            " tool as nmc_aed_site_locate({q0:region.region_1depth_name,"
+            " q1:region.region_2depth_name, page_no:1, num_of_rows:10,"
+            " origin_lat:<original place lat>, origin_lon:<original place lon>})."
+            " origin_lat/origin_lon are optional client-side distance-sort fields;"
+            " copy them from the coordinate-producing locate result when available."
+            " Do NOT pass mode, lat/lon, or ER-only fields."
+        )
     if tool_id in {"kakao_coord_to_region", "sgis_adm_cd_lookup"}:
         return (
             " COPY EXACT COORDINATES: call this reverse-geocode adapter with"
@@ -176,6 +196,7 @@ class ToolExecutor:
         """
         self._registry = registry
         self._adapters: dict[str, AdapterFn] = {}
+        self._session_adapters: dict[str, SessionAwareAdapterFn] = {}
         self._recovery_executor = recovery_executor
         self._metrics: MetricsCollector | None = metrics
         self._event_logger: ObservabilityEventLogger | None = event_logger
@@ -192,6 +213,31 @@ class ToolExecutor:
         self._adapters[tool_id] = adapter
         logger.debug("Registered adapter for tool: %s", tool_id)
 
+    def register_session_adapter(self, tool_id: str, adapter: SessionAwareAdapterFn) -> None:
+        """Register an adapter that also receives the caller session identity."""
+
+        async def _without_session(inp: BaseModel) -> dict[str, Any]:
+            return await adapter(inp, None)
+
+        self._adapters[tool_id] = _without_session
+        self._session_adapters[tool_id] = adapter
+        logger.debug("Registered session-aware adapter for tool: %s", tool_id)
+
+    def _adapter_for_session(
+        self,
+        tool_id: str,
+        adapter: AdapterFn,
+        session_identity: object | None,
+    ) -> AdapterFn:
+        session_adapter = self._session_adapters.get(tool_id)
+        if session_adapter is None:
+            return adapter
+
+        async def _with_session(inp: BaseModel) -> dict[str, Any]:
+            return await session_adapter(inp, session_identity)
+
+        return _with_session
+
     async def invoke_raw(  # noqa: C901
         self,
         tool_id: str,
@@ -250,6 +296,7 @@ class ToolExecutor:
                 elapsed_ms=_elapsed(),
                 retryable=False,
             )
+        adapter = self._adapter_for_session(tool_id, adapter, session_identity)
 
         try:
             validated_input = tool.input_schema.model_validate(params)
@@ -311,8 +358,9 @@ class ToolExecutor:
                 reason=reason,
                 message=(
                     f"Adapter '{tool_id}' raised {type(exc).__name__}: {str(exc)[:240]}. "
-                    "Do NOT fabricate a response from prior knowledge; use another "
-                    "appropriate adapter or explain that the lookup failed."
+                    "Do NOT fabricate a response from prior knowledge; explain that "
+                    "the lookup failed, cite the official agency channel, and ask "
+                    "before trying a different adapter."
                 ),
                 request_id=request_id,
                 elapsed_ms=_elapsed(),
@@ -438,6 +486,7 @@ class ToolExecutor:
                 elapsed_ms=_elapsed(),
                 retryable=False,
             )
+        adapter = self._adapter_for_session(tool_id, adapter, session_identity)
 
         # --- Input validation ---------------------------------------------------
         try:
@@ -480,20 +529,20 @@ class ToolExecutor:
             recovery_hint = _adapter_validation_recovery_hint(tool_id)
             if not recovery_hint and tool_id == "nmc_emergency_search":
                 recovery_hint = (
-                    " LOCATE FIRST: call locate with a locate adapter from"
+                    " LOCATE FIRST: call a concrete locate adapter from"
                     " <available_adapters>. For a named place use"
-                    " locate({tool_id:'kakao_keyword_search', params:{query:'<지역명>'}}),"
-                    " then call locate({tool_id:'kakao_coord_to_region',"
-                    " params:{lat:<lat>, lon:<lon>}}). Re-invoke this tool with"
-                    " params {mode:'region', q0:region.region_1depth_name,"
+                    " kakao_keyword_search({query:'<지역명>'}), then call"
+                    " kakao_coord_to_region({lat:<lat>, lon:<lon>}). Re-invoke"
+                    " this tool as nmc_emergency_search({mode:'region',"
+                    " q0:region.region_1depth_name,"
                     " q1:region.region_2depth_name, origin_lat:<lat>, origin_lon:<lon>,"
-                    " limit:<N>}. Copy decimal WGS-84 coordinates exactly from locate;"
+                    " limit:<N>}). Copy decimal WGS-84 coordinates exactly from locate;"
                     " do NOT round, guess coordinates, or set QN unless the citizen"
                     " gave a specific institution name."
                 )
             elif not recovery_hint and need_resolve:
                 recovery_hint = (
-                    " LOCATE FIRST: call locate with the appropriate locate adapter"
+                    " LOCATE FIRST: call the appropriate concrete locate adapter"
                     " from <available_adapters> to obtain the missing coordinates /"
                     " admin code, then re-invoke this tool with the returned values."
                     " Do NOT guess coordinates or codes from prior knowledge."
@@ -566,8 +615,8 @@ class ToolExecutor:
                     f"Adapter '{tool_id}' raised an exception during upstream call. "
                     f"Detail: {_exc_summary}. "
                     "Do NOT fabricate a response from prior knowledge — tell the citizen "
-                    "the lookup failed, cite the official agency channel, and offer to "
-                    "retry or try a different tool."
+                    "the lookup failed, cite the official agency channel, and ask "
+                    "before retrying or trying a different tool."
                 ),
                 request_id=request_id,
                 elapsed_ms=_elapsed(),
@@ -637,7 +686,7 @@ class ToolExecutor:
                     f"expected envelope schema. Detail: {_exc_detail}. "
                     "Do NOT fabricate a response from prior knowledge — tell the citizen "
                     "the data could not be parsed, cite the official agency channel, and "
-                    "offer to retry or try a different tool."
+                    "ask before retrying or trying a different tool."
                 ),
                 request_id=request_id,
                 elapsed_ms=_elapsed(),

package/src/ummaya/tools/geocoding/kakao_client.py

@@ -19,8 +19,7 @@ business logic. Reference: PyKakao 1.x ``Local`` class
 endpoints as six methods on a single facade — the industry-standard
 Korean wrapper for this API. UMMAYA originally shipped only
 ``search_address`` (Spec 022); ``search_keyword`` is added here to close
-the POI-coverage gap captured in
-``specs/integration-verification/donga-univ-poi-bug/``.
+the POI-coverage gap captured during historical live-location debugging.
 
 Authentication: REST API key via ``Authorization: KakaoAK {key}`` header.
 Key source: ``UMMAYA_KAKAO_API_KEY`` environment variable.