ummaya 0.2.4 → 0.2.6

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

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ummaya.tools.routing.intent import ACTIVE_PRIMITIVES, ToolSelectionIntent
+from ummaya.tools.routing.lint import lint_adapter_card
+from ummaya.tools.routing.types import AdapterCard, PrimitiveFamily, SourceMode
+
+DEFAULT_SOURCE_MODES: tuple[SourceMode, ...] = ("live", "mock")
+SIDE_EFFECT_LEVELS = frozenset({"login", "action", "sign", "send", "verify"})
+PERMISSION_CONTEXT_LEVELS = frozenset({"action", "sign", "send", "verify"})
+
+
+def hard_exclusion_reasons(
+    card: AdapterCard,
+    *,
+    active_tool_ids: frozenset[str],
+    allowed_source_modes: frozenset[SourceMode],
+    allowed_credentials: frozenset[str] | None,
+) -> tuple[str, ...]:
+    reasons: list[str] = []
+    if card.tool_id not in active_tool_ids:
+        reasons.append("inactive_adapter")
+    if card.source_mode not in allowed_source_modes:
+        reasons.append(f"disallowed_source_mode:{card.source_mode}")
+    if allowed_credentials is not None:
+        missing_credentials = [
+            requirement
+            for requirement in card.credential_requirements
+            if requirement not in allowed_credentials
+        ]
+        reasons.extend(f"disallowed_credential:{credential}" for credential in missing_credentials)
+    return tuple(dict.fromkeys(reasons))
+
+
+def soft_filter_reasons(
+    card: AdapterCard,
+    *,
+    route_intent: ToolSelectionIntent,
+    session_identity: object | None,
+    active_tool_ids: frozenset[str],
+    active_primitives: frozenset[PrimitiveFamily],
+) -> tuple[str, ...]:
+    reasons: list[str] = []
+    reasons.extend(
+        f"adapter_card_quality:{violation.code}" for violation in lint_adapter_card(card)
+    )
+    reasons.extend(_missing_slot_reasons(card.required_slots, route_intent.missing_slots))
+    reasons.extend(_permission_reasons(card, route_intent, session_identity))
+    reasons.extend(_prerequisite_reasons(card, active_tool_ids, active_primitives))
+    return tuple(dict.fromkeys(reasons))
+
+
+def score_breakdown(
+    card: AdapterCard,
+    retrieval_score: float,
+    filter_reasons: tuple[str, ...],
+) -> dict[str, float]:
+    return {
+        "retrieval": retrieval_score,
+        "feasibility": 1.0 if not filter_reasons else 0.0,
+        "source_mode": 1.0 if card.source_mode in {"live", "mock"} else 0.0,
+        "permission": 0.0 if any("permission" in reason for reason in filter_reasons) else 1.0,
+        "prerequisite": 0.0 if any("prerequisite" in reason for reason in filter_reasons) else 1.0,
+        "quality": 0.0
+        if any("adapter_card_quality" in reason for reason in filter_reasons)
+        else 1.0,
+    }
+
+
+def requires_permission_gate(card: AdapterCard, *, feasible: bool) -> bool:
+    return feasible and card.side_effect_level in SIDE_EFFECT_LEVELS
+
+
+def source_modes(value: Sequence[SourceMode]) -> frozenset[SourceMode]:
+    return frozenset(value)
+
+
+def _missing_slot_reasons(
+    required_slots: tuple[str, ...],
+    intent_missing_slots: tuple[str, ...],
+) -> tuple[str, ...]:
+    missing = frozenset(intent_missing_slots)
+    return tuple(f"missing_slot:{slot}" for slot in required_slots if slot in missing)
+
+
+def _permission_reasons(
+    card: AdapterCard,
+    intent: ToolSelectionIntent,
+    session_identity: object | None,
+) -> tuple[str, ...]:
+    if card.side_effect_level not in SIDE_EFFECT_LEVELS:
+        return ()
+    reasons: list[str] = []
+    if card.policy_authority_url is None:
+        reasons.append("missing_policy_citation")
+    if (
+        card.side_effect_level in PERMISSION_CONTEXT_LEVELS
+        and not intent.requires_permission
+        and session_identity is None
+    ):
+        reasons.append("permission_context_missing")
+    return tuple(reasons)
+
+
+def _prerequisite_reasons(
+    card: AdapterCard,
+    active_tool_ids: frozenset[str],
+    active_primitives: frozenset[PrimitiveFamily],
+) -> tuple[str, ...]:
+    reasons: list[str] = []
+    primitive_names = frozenset((*ACTIVE_PRIMITIVES, "document"))
+    for prerequisite in card.prerequisite_tools:
+        if prerequisite in primitive_names:
+            if prerequisite not in active_primitives:
+                reasons.append(f"missing_prerequisite_primitive:{prerequisite}")
+            continue
+        if prerequisite not in active_tool_ids:
+            reasons.append(f"missing_prerequisite_tool:{prerequisite}")
+    return tuple(reasons)

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

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from ummaya.tools.routing.intent_extractor import extract_tool_selection_intent
+from ummaya.tools.routing.intent_types import (
+    ACTIVE_PRIMITIVES,
+    LEGACY_PRIMITIVE_ALIASES,
+    ActivePrimitive,
+    ToolSelectionIntent,
+)
+
+__all__ = [
+    "ACTIVE_PRIMITIVES",
+    "LEGACY_PRIMITIVE_ALIASES",
+    "ActivePrimitive",
+    "ToolSelectionIntent",
+    "extract_tool_selection_intent",
+]

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

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Collection, Iterable
+
+from ummaya.tools.routing.intent_patterns import (
+    _ADMIN_LOCATION_RE,
+    _ARTIFACT_ID_RE,
+    _COORDINATE_PAIR_RE,
+    _CREDENTIAL_RE,
+    _DOCUMENT_FORMAT_RE,
+    _DOCUMENT_INTENT_RE,
+    _DOCUMENT_LOCAL_HINT_RE,
+    _DOCUMENT_PATH_RE,
+    _DOCUMENT_WRITE_INTENT_RE,
+    _EXPLICIT_TOOL_ID_RE,
+    _PAYMENT_SIDE_EFFECT_RE,
+    _POI_LOCATION_RE,
+    _SIDE_EFFECT_RE,
+    _SUBMIT_SIDE_EFFECT_RE,
+    _WHITESPACE_RE,
+)
+from ummaya.tools.routing.intent_public_data import extract_public_data_refs
+from ummaya.tools.routing.intent_types import (
+    ACTIVE_PRIMITIVES,
+    ActivePrimitive,
+    ToolSelectionIntent,
+)
+
+
+def extract_tool_selection_intent(
+    query: str, *, known_tool_ids: Collection[str] = ()
+) -> ToolSelectionIntent:
+    normalized_query = _normalize_query(query)
+    document_refs = _extract_document_refs(query)
+    location_refs = _extract_location_refs(query)
+    public_data_refs = extract_public_data_refs(query)
+    credential_refs = _extract_credential_refs(query)
+    side_effect_markers = _extract_side_effect_markers(query, document_refs=document_refs)
+    explicit_tool_ids = _extract_explicit_tool_ids(query, known_tool_ids=known_tool_ids)
+    explicit_artifact_ids = _ordered_unique(_ARTIFACT_ID_RE.findall(query))
+    candidate_primitives = _candidate_primitives(
+        normalized_query=normalized_query,
+        document_refs=document_refs,
+        location_refs=location_refs,
+        public_data_refs=public_data_refs,
+        credential_refs=credential_refs,
+        side_effect_markers=side_effect_markers,
+        explicit_tool_ids=explicit_tool_ids,
+    )
+    return ToolSelectionIntent(
+        raw_query=query,
+        normalized_query=normalized_query,
+        intent_verbs=candidate_primitives,
+        entities=(),
+        document_refs=document_refs,
+        location_refs=location_refs,
+        time_refs=(),
+        public_data_refs=public_data_refs,
+        credential_refs=credential_refs,
+        side_effect_markers=side_effect_markers,
+        explicit_tool_ids=explicit_tool_ids,
+        explicit_artifact_ids=explicit_artifact_ids,
+        candidate_primitives=candidate_primitives,
+        missing_slots=_missing_slots(location_refs, public_data_refs),
+        unsafe_assumptions=_unsafe_assumptions(location_refs, public_data_refs),
+        requires_clarification=not normalized_query,
+        requires_permission=bool(credential_refs or side_effect_markers),
+    )
+
+
+def _normalize_query(query: str) -> str:
+    return _WHITESPACE_RE.sub(" ", query.strip()).lower()
+
+
+def _extract_explicit_tool_ids(query: str, *, known_tool_ids: Collection[str]) -> tuple[str, ...]:
+    matches: list[tuple[int, str]] = []
+    for match in _EXPLICIT_TOOL_ID_RE.finditer(query):
+        matches.append((match.start(1), match.group(1)))
+    query_lower = query.lower()
+    for tool_id in known_tool_ids:
+        index = query_lower.find(tool_id.lower())
+        if index >= 0:
+            matches.append((index, tool_id))
+    return _ordered_unique(value for _index, value in sorted(matches))
+
+
+def _extract_document_refs(query: str) -> tuple[str, ...]:
+    refs: list[str] = []
+    refs.extend(match.group(1).strip() for match in _DOCUMENT_PATH_RE.finditer(query))
+    refs.extend(f"format:{match.group(1).lower()}" for match in _DOCUMENT_FORMAT_RE.finditer(query))
+    if _is_document_harness_query(query):
+        refs.append("document_harness")
+    return _ordered_unique(refs)
+
+
+def _extract_location_refs(query: str) -> tuple[str, ...]:
+    refs: list[str] = []
+    for match in _COORDINATE_PAIR_RE.finditer(query):
+        lat = float(match.group("lat"))
+        lon = float(match.group("lon"))
+        if -90.0 <= lat <= 90.0 and -180.0 <= lon <= 180.0:
+            refs.append(f"coordinate:{_format_decimal(lat)},{_format_decimal(lon)}")
+    if _POI_LOCATION_RE.search(query):
+        refs.append("poi")
+    if _ADMIN_LOCATION_RE.search(query):
+        refs.append("admin")
+    return _ordered_unique(refs)
+
+
+def _extract_credential_refs(query: str) -> tuple[str, ...]:
+    if not _CREDENTIAL_RE.search(query):
+        return ()
+    refs: list[str] = []
+    lowered = query.lower()
+    if "간편인증" in query:
+        refs.append("simple_auth")
+    if "모바일" in query and "신분증" in query:
+        refs.append("mobile_id")
+    if "인증서" in query:
+        refs.append("certificate")
+    if "동의" in query or "consent" in lowered or "delegation" in lowered:
+        refs.append("delegation")
+    if not refs:
+        refs.append("credential")
+    return _ordered_unique(refs)
+
+
+def _extract_side_effect_markers(query: str, *, document_refs: tuple[str, ...]) -> tuple[str, ...]:
+    refs: list[str] = []
+    if _SIDE_EFFECT_RE.search(query):
+        refs.append("action")
+    if _SUBMIT_SIDE_EFFECT_RE.search(query):
+        refs.append("submit")
+    if _PAYMENT_SIDE_EFFECT_RE.search(query):
+        refs.append("payment")
+    if document_refs and _DOCUMENT_WRITE_INTENT_RE.search(query):
+        refs.append("document_write")
+    return _ordered_unique(refs)
+
+
+def _candidate_primitives(
+    *,
+    normalized_query: str,
+    document_refs: tuple[str, ...],
+    location_refs: tuple[str, ...],
+    public_data_refs: tuple[str, ...],
+    credential_refs: tuple[str, ...],
+    side_effect_markers: tuple[str, ...],
+    explicit_tool_ids: tuple[str, ...],
+) -> tuple[ActivePrimitive, ...]:
+    primitives: set[ActivePrimitive] = set()
+    if normalized_query or public_data_refs or document_refs or explicit_tool_ids:
+        primitives.add("find")
+    if location_refs:
+        primitives.add("locate")
+    if side_effect_markers:
+        primitives.add("send")
+    if credential_refs:
+        primitives.add("check")
+    return tuple(primitive for primitive in ACTIVE_PRIMITIVES if primitive in primitives)
+
+
+def _missing_slots(
+    location_refs: tuple[str, ...], public_data_refs: tuple[str, ...]
+) -> tuple[str, ...]:
+    has_coordinate = any(ref.startswith("coordinate:") for ref in location_refs)
+    coordinate_bound_refs = {"emergency_medical", "aed"}
+    if not has_coordinate and any(ref in coordinate_bound_refs for ref in public_data_refs):
+        return ("lat", "lon")
+    return ()
+
+
+def _unsafe_assumptions(
+    location_refs: tuple[str, ...], public_data_refs: tuple[str, ...]
+) -> tuple[str, ...]:
+    if "poi" in location_refs and not any(ref.startswith("coordinate:") for ref in location_refs):
+        return ("poi_requires_location_resolution",)
+    return ()
+
+
+def _is_document_harness_query(query: str) -> bool:
+    return bool(
+        _DOCUMENT_PATH_RE.search(query)
+        or (_DOCUMENT_FORMAT_RE.search(query) and _DOCUMENT_INTENT_RE.search(query))
+        or (
+            _DOCUMENT_INTENT_RE.search(query)
+            and _DOCUMENT_WRITE_INTENT_RE.search(query)
+            and _DOCUMENT_LOCAL_HINT_RE.search(query)
+        )
+    )
+
+
+def _format_decimal(value: float) -> str:
+    return f"{value:.6f}".rstrip("0").rstrip(".")
+
+
+def _ordered_unique(values: Iterable[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_patterns.py

@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import re
+
+_WHITESPACE_RE = re.compile(r"\s+")
+_EXPLICIT_TOOL_ID_RE = re.compile(
+    r"(?:tool_id|adapter|도구)\s*[:=]\s*`?([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)?)`?",
+    re.IGNORECASE,
+)
+_ARTIFACT_ID_RE = re.compile(
+    r"\b(?:artifact|source|working|derivative|render|viewport)-[A-Za-z0-9_-]+\b"
+)
+_DOCUMENT_PATH_RE = re.compile(
+    r"(?:^|[\s:'\"(])((?:~|/|[A-Za-z]:\\|\.{1,2}/)?[^\s:'\"]*"
+    r"\.(?:hwpx|hwp|docx|pdf|xlsx|pptx))\b",
+    re.IGNORECASE,
+)
+_DOCUMENT_FORMAT_RE = re.compile(r"\b(hwpx|hwp|docx|pdf|xlsx|pptx)\b", re.IGNORECASE)
+_DOCUMENT_INTENT_RE = re.compile(
+    r"(문서|공문서|양식|서식|파일|작성|저장|렌더|미리보기|변경사항|"
+    r"\bdiff\b|\bcompact\b|\bdocument\b|\bfile\b|\bform\b|\brender\b|\bsave\b|\bwrite\b)",
+    re.IGNORECASE,
+)
+_DOCUMENT_WRITE_INTENT_RE = re.compile(
+    r"(작성|수정|편집|채우|채워|입력|변경|저장|write|edit|fill|apply|save)",
+    re.IGNORECASE,
+)
+_DOCUMENT_LOCAL_HINT_RE = re.compile(
+    r"(다운로드|downloads?|폴더|파일|양식|서식|활동일지|신청서|등본|증명서)",
+    re.IGNORECASE,
+)
+_COORDINATE_PAIR_RE = re.compile(
+    r"(?P<lat>[+-]?\d{1,2}(?:\.\d+)?)\s*,\s*(?P<lon>[+-]?\d{2,3}(?:\.\d+)?)"
+)
+_POI_LOCATION_RE = re.compile(
+    r"(근처|주변|인근|가까운|역|터미널|공항|캠퍼스|대학교|대학|해수욕장|시장|공원|랜드마크)"
+)
+_ADMIN_LOCATION_RE = re.compile(
+    r"(?:[가-힣]{2,}(?:시|군|구|동|읍|면)\b|[가-힣0-9]{2,}(?<!으)(?:로|길)\b)"
+)
+_PUBLIC_DATA_OPERATION_RE = re.compile(
+    r"\b(getSurfaceChart|getAuxillaryChart|SEA\d{4}|FinancesService|"
+    r"StudentService|WthrChartInfoService)\b",
+    re.IGNORECASE,
+)
+_KMA_GIMHAE_AIRPORT_RE = re.compile(r"(김해(?:공항)?|Gimhae|RKPK)", re.IGNORECASE)
+_KMA_GIMPO_AIRPORT_RE = re.compile(r"(김포(?:공항)?|Gimpo|RKSS)", re.IGNORECASE)
+_KMA_AIRPORT_AVIATION_RE = re.compile(
+    r"(AMOS|METAR|SPECI|RVR|항공기상|공항기상|활주로|runway|aviation|"
+    r"비행기|항공편|비행편|이륙|착륙|결항|지연|운항|뜰\s*만|뜨나|뜰\s*수|"
+    r"flight|take\s*off|landing|delay|cancel)",
+    re.IGNORECASE,
+)
+_KMA_EXPLICIT_METAR_RE = re.compile(r"(\bMETAR\b|\bSPECI\b|해독자료)", re.IGNORECASE)
+_KMA_RUNWAY_AREA_RE = re.compile(
+    r"(AMOS|활주로|RVR|runway|시정|visibility|공항기상관측|매분)",
+    re.IGNORECASE,
+)
+_KMA_ANALYSIS_CHART_RE = re.compile(
+    r"(분석일기도|지상일기도|보조일기도|WthrChartInfoService|getSurfaceChart|"
+    r"getAuxillaryChart|synoptic\s+chart)",
+    re.IGNORECASE,
+)
+_KMA_ANALYSIS_DATA_RE = re.compile(
+    r"(분석자료|이미\s*분석|고해상도\s*격자|객관분석|AWS\s*객관|지도\s*자료|"
+    r"일기도|분석일기도|비구름|바람\s*흐름|날씨\s*흐름|공식\s*기상자료|전국\s*날씨|"
+    r"synoptic|weather\s*chart|objective\s*analysis|high[-\s]?resolution|grid)",
+    re.IGNORECASE,
+)
+_KMA_ANALYSIS_MAP_RE = re.compile(
+    r"(일기도|분석일기도|지도\s*자료|비구름|바람\s*흐름|날씨\s*흐름|전국\s*날씨|"
+    r"synoptic|weather\s*chart)",
+    re.IGNORECASE,
+)
+_KMA_ANALYSIS_POINT_RE = re.compile(
+    r"(주변|근처|특정지점|좌표|위도|경도|\blat\b|\blon\b|공항\s*주변)",
+    re.IGNORECASE,
+)
+_KMA_LIFESTYLE_WEATHER_RE = re.compile(
+    r"(날씨|현재\s*기상|실황|관측|예보|기온|습도|풍속|지금\s*비|"
+    r"비\s*(?:와|오|올|내리)|우산|강수|소나기|산책|퇴근|"
+    r"current\s+weather|forecast|rain|umbrella|precipitation|temperature)",
+    re.IGNORECASE,
+)
+_EMERGENCY_RE = re.compile(r"(응급|응급실|응급의료|\bemergency\b|\ber\b)", re.IGNORECASE)
+_IMPLICIT_EMERGENCY_RE = re.compile(
+    r"(사람이\s*(?:쓰러|쓰러졌|쓰러져)|의식(?:을)?\s*(?:잃|없)|"
+    r"갑자기\s*쓰러|쓰러진\s*사람|위급|심정지|호흡(?:이)?\s*없|"
+    r"collapsed|unconscious|cardiac\s*arrest)",
+    re.IGNORECASE,
+)
+_AED_RE = re.compile(r"(\bAED\b|자동심장충격기|자동제세동기|제세동기)", re.IGNORECASE)
+_TRAFFIC_HAZARD_RE = re.compile(
+    r"(교통사고|사고\s*위험|사고다발|위험\s*(?:구간|도로|지점)|어린이보호구역|보호구역|"
+    r"도로\s*구간|accident|hazard|hotspot)",
+    re.IGNORECASE,
+)
+_TRAFFIC_HAZARD_SPECIFIC_RE = re.compile(
+    r"(사고\s*위험|위험\s*(?:구간|도로|지점)|어린이보호구역|보호구역|스쿨존|"
+    r"도로\s*구간|행정동코드|adm_cd|hazard|hotspot)",
+    re.IGNORECASE,
+)
+_MOF_OCEAN_WATER_QUALITY_RE = re.compile(
+    r"(해양\s*수질|해양수질|수질\s*자동\s*측정|용존산소|\bpH\b|"
+    r"water\s+quality|ocean\s+water)",
+    re.IGNORECASE,
+)
+_PPS_BID_RE = re.compile(r"(입찰|나라장터|조달청|\bbid\b|procurement|tender)", re.IGNORECASE)
+_PPS_SHOPPING_RE = re.compile(
+    r"(종합\s*쇼핑몰|쇼핑몰|계약\s*물품|물품\s*조회|shopping\s*mall)",
+    re.IGNORECASE,
+)
+_AIRKOREA_AIR_QUALITY_RE = re.compile(
+    r"(미세먼지|초미세먼지|초미세|대기질|대기오염|공기질|마스크|"
+    r"pm\s*2\.?5|pm\s*10|air\s*korea|airkorea|air\s*quality|airquality)",
+    re.IGNORECASE,
+)
+_KCUE_REGIONAL_RE = re.compile(
+    r"(대학알리미|대학정보공시|학교구분코드|schl[_\s-]?div[_\s-]?cd|KCUE|"
+    r"지역별\s*(등록금|재정)|외국인\s*유학생|foreign\s+student|international\s+student)",
+    re.IGNORECASE,
+)
+_KCUE_REGIONAL_FINANCE_RE = re.compile(
+    r"(지역별\s*(등록금|재정)|등록금\s*(현황|지역별)?|tuition|finance)",
+    re.IGNORECASE,
+)
+_KCUE_REGIONAL_FOREIGN_STUDENT_RE = re.compile(
+    r"(외국인\s*유학생|유학생\s*현황|foreign\s+student|international\s+student)",
+    re.IGNORECASE,
+)
+_HIRA_MEDICAL_DETAIL_RE = re.compile(
+    r"((병원|의료기관|의원).*(상세|진료과|진료과목|진료시간|주차)|"
+    r"(상세|진료시간|주차|응급실).*(병원|의료기관|의원)|ykiho|detail)",
+    re.IGNORECASE,
+)
+_MOIS_EMERGENCY_CALL_BOX_RE = re.compile(
+    r"(안전\s*비상벨|비상벨|긴급\s*신고함|긴급신고함|방범벨|"
+    r"emergency\s+call\s+box)",
+    re.IGNORECASE,
+)
+_GYERYONG_ASSISTIVE_CHARGER_RE = re.compile(
+    r"((전동보장구|전동\s*휠체어|보장구|장애인).*(충전|충전소|충전장소)|"
+    r"(충전|충전소|충전장소).*(전동보장구|전동\s*휠체어|보장구|장애인)|"
+    r"계룡시?.*(충전소|충전\s*장소))",
+    re.IGNORECASE,
+)
+_CREDENTIAL_RE = re.compile(
+    r"(간편인증|본인인증|모바일\s*신분증|공동인증서|금융인증서|인증서|"
+    r"delegation|consent|verify|login|로그인|동의)",
+    re.IGNORECASE,
+)
+_SIDE_EFFECT_RE = re.compile(
+    r"(신청|제출|신고|송신|납부|결제|발급|저장|수정|편집|채우|"
+    r"submit|send|pay|issue|save|write|edit|fill|apply)",
+    re.IGNORECASE,
+)
+_SUBMIT_SIDE_EFFECT_RE = re.compile(r"(신청|제출|신고|submit|send|apply)", re.IGNORECASE)
+_PAYMENT_SIDE_EFFECT_RE = re.compile(r"(납부|결제|pay)", re.IGNORECASE)

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)