ummaya 0.2.3 → 0.2.5

package/src/ummaya/tools/routing/intent_public_data.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from ummaya.tools.routing.intent_patterns import (
+    _AED_RE,
+    _AIRKOREA_AIR_QUALITY_RE,
+    _EMERGENCY_RE,
+    _GYERYONG_ASSISTIVE_CHARGER_RE,
+    _HIRA_MEDICAL_DETAIL_RE,
+    _IMPLICIT_EMERGENCY_RE,
+    _KCUE_REGIONAL_FINANCE_RE,
+    _KCUE_REGIONAL_FOREIGN_STUDENT_RE,
+    _KCUE_REGIONAL_RE,
+    _KMA_AIRPORT_AVIATION_RE,
+    _KMA_ANALYSIS_CHART_RE,
+    _KMA_ANALYSIS_DATA_RE,
+    _KMA_ANALYSIS_MAP_RE,
+    _KMA_ANALYSIS_POINT_RE,
+    _KMA_EXPLICIT_METAR_RE,
+    _KMA_GIMHAE_AIRPORT_RE,
+    _KMA_GIMPO_AIRPORT_RE,
+    _KMA_LIFESTYLE_WEATHER_RE,
+    _KMA_RUNWAY_AREA_RE,
+    _MOF_OCEAN_WATER_QUALITY_RE,
+    _MOIS_EMERGENCY_CALL_BOX_RE,
+    _PPS_BID_RE,
+    _PPS_SHOPPING_RE,
+    _PUBLIC_DATA_OPERATION_RE,
+    _TRAFFIC_HAZARD_RE,
+    _TRAFFIC_HAZARD_SPECIFIC_RE,
+)
+
+
+def extract_public_data_refs(query: str) -> tuple[str, ...]:
+    refs = [f"operation:{match.group(1)}" for match in _PUBLIC_DATA_OPERATION_RE.finditer(query)]
+    refs.extend(_extract_kma_public_data_refs(query))
+    refs.extend(_extract_emergency_public_data_refs(query))
+    refs.extend(_extract_domain_public_data_refs(query))
+    return _ordered_unique(refs)
+
+
+def _extract_kma_public_data_refs(query: str) -> list[str]:
+    has_airport_aviation = bool(_KMA_AIRPORT_AVIATION_RE.search(query))
+    has_emergency = bool(_EMERGENCY_RE.search(query) or _IMPLICIT_EMERGENCY_RE.search(query))
+    refs: list[str] = []
+    refs.extend(_extract_kma_aviation_refs(query, has_airport_aviation=has_airport_aviation))
+    refs.extend(_extract_kma_analysis_refs(query))
+    if _is_lifestyle_weather_ref(query, has_airport_aviation, has_emergency):
+        refs.append("kma_lifestyle_weather")
+    return refs
+
+
+def _extract_kma_aviation_refs(query: str, *, has_airport_aviation: bool) -> list[str]:
+    refs: list[str] = []
+    if has_airport_aviation:
+        refs.append("kma_airport_aviation")
+    if _KMA_GIMHAE_AIRPORT_RE.search(query):
+        refs.append("kma_gimhae_airport")
+    if _KMA_GIMPO_AIRPORT_RE.search(query):
+        refs.append("kma_gimpo_airport")
+    if _KMA_EXPLICIT_METAR_RE.search(query):
+        refs.append("kma_explicit_metar")
+    if _KMA_RUNWAY_AREA_RE.search(query):
+        refs.append("kma_runway_area")
+    return refs
+
+
+def _extract_kma_analysis_refs(query: str) -> list[str]:
+    refs: list[str] = []
+    if _KMA_ANALYSIS_CHART_RE.search(query):
+        refs.append("kma_analysis_chart")
+    if _KMA_ANALYSIS_DATA_RE.search(query):
+        refs.append("kma_analysis_data")
+    if _KMA_ANALYSIS_MAP_RE.search(query):
+        refs.append("kma_analysis_map")
+    if _KMA_ANALYSIS_POINT_RE.search(query):
+        refs.append("kma_analysis_point")
+    return refs
+
+
+def _is_lifestyle_weather_ref(query: str, has_airport_aviation: bool, has_emergency: bool) -> bool:
+    return bool(
+        _KMA_LIFESTYLE_WEATHER_RE.search(query)
+        and not has_airport_aviation
+        and not has_emergency
+        and not _AIRKOREA_AIR_QUALITY_RE.search(query)
+        and not _KMA_ANALYSIS_DATA_RE.search(query)
+        and not _TRAFFIC_HAZARD_RE.search(query)
+        and not _MOF_OCEAN_WATER_QUALITY_RE.search(query)
+    )
+
+
+def _extract_emergency_public_data_refs(query: str) -> list[str]:
+    refs: list[str] = []
+    has_call_box = bool(_MOIS_EMERGENCY_CALL_BOX_RE.search(query))
+    has_emergency = bool(_EMERGENCY_RE.search(query) or _IMPLICIT_EMERGENCY_RE.search(query))
+    if has_emergency and not has_call_box:
+        refs.append("emergency_medical")
+    if _IMPLICIT_EMERGENCY_RE.search(query) and not has_call_box:
+        refs.append("implicit_emergency")
+    if _AED_RE.search(query):
+        refs.append("aed")
+    if has_call_box:
+        refs.append("mois_emergency_call_box")
+    return refs
+
+
+def _extract_domain_public_data_refs(query: str) -> list[str]:
+    refs: list[str] = []
+    if _TRAFFIC_HAZARD_RE.search(query):
+        refs.append("traffic_hazard")
+    if _TRAFFIC_HAZARD_SPECIFIC_RE.search(query):
+        refs.append("traffic_hazard_specific")
+    refs.extend(_extract_environment_public_data_refs(query))
+    if _PPS_BID_RE.search(query) and not _PPS_SHOPPING_RE.search(query):
+        refs.append("pps_bid")
+    has_kcue_finance = bool(_KCUE_REGIONAL_FINANCE_RE.search(query))
+    has_kcue_foreign_student = bool(_KCUE_REGIONAL_FOREIGN_STUDENT_RE.search(query))
+    if _KCUE_REGIONAL_RE.search(query) or has_kcue_finance or has_kcue_foreign_student:
+        refs.append("kcue_regional")
+    if has_kcue_finance:
+        refs.append("kcue_regional_finance")
+    if has_kcue_foreign_student:
+        refs.append("kcue_regional_foreign_student")
+    if _HIRA_MEDICAL_DETAIL_RE.search(query):
+        refs.append("hira_medical_detail")
+    if _GYERYONG_ASSISTIVE_CHARGER_RE.search(query):
+        refs.append("gyeryong_assistive_charger")
+    return refs
+
+
+def _extract_environment_public_data_refs(query: str) -> list[str]:
+    refs: list[str] = []
+    if _MOF_OCEAN_WATER_QUALITY_RE.search(query):
+        refs.append("mof_ocean_water_quality")
+    if _AIRKOREA_AIR_QUALITY_RE.search(query):
+        refs.append("airkorea_air_quality")
+    return refs
+
+
+def _ordered_unique(values: list[str]) -> tuple[str, ...]:
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for value in values:
+        if value in seen:
+            continue
+        seen.add(value)
+        ordered.append(value)
+    return tuple(ordered)

package/src/ummaya/tools/routing/intent_types.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+ActivePrimitive = Literal["find", "locate", "send", "check"]
+
+ACTIVE_PRIMITIVES: Final[tuple[ActivePrimitive, ...]] = ("find", "locate", "send", "check")
+LEGACY_PRIMITIVE_ALIASES: Final[dict[str, ActivePrimitive]] = {
+    "lookup": "find",
+    "resolve_location": "locate",
+    "submit": "send",
+    "verify": "check",
+}
+
+
+class ToolSelectionIntent(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    raw_query: str
+    normalized_query: str
+    intent_verbs: tuple[ActivePrimitive, ...]
+    entities: tuple[str, ...]
+    document_refs: tuple[str, ...]
+    location_refs: tuple[str, ...]
+    time_refs: tuple[str, ...]
+    public_data_refs: tuple[str, ...]
+    credential_refs: tuple[str, ...]
+    side_effect_markers: tuple[str, ...]
+    explicit_tool_ids: tuple[str, ...]
+    explicit_artifact_ids: tuple[str, ...]
+    candidate_primitives: tuple[ActivePrimitive, ...]
+    missing_slots: tuple[str, ...]
+    unsafe_assumptions: tuple[str, ...]
+    requires_clarification: bool
+    requires_permission: bool
+
+    def has_location_ref(self, value: str) -> bool:
+        return value in self.location_refs
+
+    def has_public_data_ref(self, value: str) -> bool:
+        return value in self.public_data_refs
+
+    def has_document_ref(self, value: str) -> bool:
+        return value in self.document_refs

package/src/ummaya/tools/routing/lint.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from ummaya.tools.routing.types import (
+    RAW_SCHEMA_MARKERS,
+    AdapterCard,
+    AdapterCardQualityViolation,
+)
+
+
+def lint_adapter_card(card: AdapterCard) -> tuple[AdapterCardQualityViolation, ...]:
+    violations: list[AdapterCardQualityViolation] = []
+    if card.source_mode in ("live", "mock") and not card.policy_authority_url:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_policy_citation",
+                message="live/mock adapter cards must cite an agency policy URL",
+            )
+        )
+    if not card.input_schema_summary:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_required_slot_metadata",
+                message="adapter cards must summarize input slots",
+            )
+        )
+    if not card.safety_annotations:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_safety_annotations",
+                message="adapter cards must expose safety annotations",
+            )
+        )
+    if not card.credential_requirements:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_credential_requirements",
+                message="adapter cards must expose credential requirements",
+            )
+        )
+    if not card.examples_ko or not card.examples_en:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_examples",
+                message="adapter cards must include Korean and English examples",
+            )
+        )
+    if not card.negative_examples:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_negative_examples",
+                message="adapter cards must include negative examples",
+            )
+        )
+    if not card.limitations:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_limitations",
+                message="adapter cards must state routing limitations",
+            )
+        )
+    if any(marker in card.routing_text for marker in RAW_SCHEMA_MARKERS):
+        violations.append(
+            AdapterCardQualityViolation(
+                code="raw_schema_leakage",
+                message="routing_text must not embed raw JSON schema",
+            )
+        )
+    return tuple(violations)
+
+
+def assert_adapter_card_quality(card: AdapterCard) -> None:
+    violations = lint_adapter_card(card)
+    if not violations:
+        return
+    detail = ", ".join(f"{violation.code}: {violation.message}" for violation in violations)
+    raise ValueError(f"AdapterCard quality violations: {detail}")

package/src/ummaya/tools/routing/metadata.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import assert_never
+
+from ummaya.tools.models import GovAPITool, MockFidelityGrade
+from ummaya.tools.routing.schema import unique
+from ummaya.tools.routing.types import (
+    AdapterCardError,
+    PrimitiveFamily,
+    SchemaFieldSummary,
+    SideEffectLevel,
+    SourceMode,
+)
+
+
+def primitive_family(value: str | None) -> PrimitiveFamily:
+    match value:
+        case "find":
+            return "find"
+        case "locate":
+            return "locate"
+        case "send":
+            return "send"
+        case "check":
+            return "check"
+        case "document":
+            return "document"
+        case None:
+            raise AdapterCardError("AdapterCard requires GovAPITool.primitive to be declared")
+        case _:
+            raise AdapterCardError(f"Unsupported adapter primitive for AdapterCard: {value!r}")
+
+
+def source_mode_for_tool(tool: GovAPITool) -> SourceMode:
+    return "mock" if tool.adapter_mode == "mock" else "live"
+
+
+def side_effect_level_for_tool(
+    tool: GovAPITool,
+    primitive: PrimitiveFamily,
+) -> SideEffectLevel:
+    if tool.policy is not None:
+        match tool.policy.citizen_facing_gate:
+            case "read-only":
+                return "read_only"
+            case "login":
+                return "login"
+            case "action":
+                return "action"
+            case "sign":
+                return "sign"
+            case "send":
+                return "send"
+            case unreachable_gate:
+                assert_never(unreachable_gate)
+    match primitive:
+        case "send":
+            return "send"
+        case "check":
+            return "verify"
+        case "find" | "locate" | "document":
+            return "read_only"
+        case unreachable_primitive:
+            assert_never(unreachable_primitive)
+
+
+def mock_fidelity_grade_for_tool(tool: GovAPITool) -> MockFidelityGrade:
+    if tool.adapter_mode != "mock":
+        return "not_applicable"
+    if tool.mock_fidelity_grade == "not_applicable":
+        return "unknown"
+    return tool.mock_fidelity_grade
+
+
+def credential_requirements_for_tool(tool: GovAPITool) -> tuple[str, ...]:
+    requirements: list[str] = [tool.auth_type]
+    if tool.published_tier_minimum is not None:
+        requirements.append(tool.published_tier_minimum)
+    if tool.nist_aal_hint is not None:
+        requirements.append(tool.nist_aal_hint)
+    return tuple(unique(requirements))
+
+
+def capabilities_for_tool(tool: GovAPITool, primitive: PrimitiveFamily) -> tuple[str, ...]:
+    return tuple(unique([primitive, *tool.category, tool.name_ko]))
+
+
+def entity_types_for_tool(
+    input_summary: Sequence[SchemaFieldSummary],
+    categories: Sequence[str],
+) -> tuple[str, ...]:
+    names = [field.name for field in input_summary]
+    if names:
+        return tuple(names)
+    return tuple(unique(categories))
+
+
+def prerequisite_tools_for_tool(tool: GovAPITool, primitive: PrimitiveFamily) -> tuple[str, ...]:
+    description = (tool.llm_description or "").lower()
+    if primitive == "send" or "prior check" in description or "delegation" in description:
+        return ("check",)
+    return ()
+
+
+def examples_ko_for_tool(tool: GovAPITool) -> tuple[str, ...]:
+    if tool.trigger_examples:
+        return tuple(tool.trigger_examples)
+    return (tool.name_ko,)
+
+
+def examples_en_for_tool(tool: GovAPITool, primitive: PrimitiveFamily) -> tuple[str, ...]:
+    domain = tool.category[0] if tool.category else tool.id
+    return (f"Use {tool.id} to {primitive} {domain} information.",)
+
+
+def limitations_for_tool(
+    tool: GovAPITool,
+    source_mode: SourceMode,
+    policy_authority_url: str | None,
+) -> tuple[str, ...]:
+    limitations = [f"Requires registry source_mode {source_mode} and auth_type {tool.auth_type}."]
+    if source_mode == "mock":
+        limitations.append("Mock output may mirror shape without live upstream freshness.")
+    if policy_authority_url is None:
+        limitations.append("No agency policy citation is registered for this adapter.")
+    return tuple(limitations)
+
+
+def safety_annotations_for_tool(
+    tool: GovAPITool,
+    side_effect_level: SideEffectLevel,
+) -> tuple[str, ...]:
+    values = [
+        f"side_effect_level:{side_effect_level}",
+        f"auth_type:{tool.auth_type}",
+        f"concurrency_safe:{str(tool.is_concurrency_safe).lower()}",
+    ]
+    if tool.policy is not None:
+        values.append(f"citizen_gate:{tool.policy.citizen_facing_gate}")
+    return tuple(values)
+
+
+def domain_for_tool(tool: GovAPITool) -> str:
+    if tool.category:
+        return tool.category[0]
+    return tool.id
+
+
+def routing_text(
+    *,
+    tool_id: str,
+    primitive: PrimitiveFamily,
+    agency: str,
+    domain: str,
+    capabilities: Sequence[str],
+    required_slots: Sequence[str],
+    examples_ko: Sequence[str],
+    limitations: Sequence[str],
+) -> str:
+    return " | ".join(
+        (
+            f"tool_id={tool_id}",
+            f"primitive={primitive}",
+            f"agency={agency}",
+            f"domain={domain}",
+            f"capabilities={', '.join(capabilities)}",
+            f"required_slots={', '.join(required_slots) or 'none'}",
+            f"examples_ko={'; '.join(examples_ko)}",
+            f"limitations={'; '.join(limitations)}",
+        )
+    )