ummaya 0.2.3 → 0.2.5

package/src/ummaya/tools/verified_data_go_kr/airkorea_air_quality.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from ummaya.tools.executor import ToolExecutor
 from ummaya.tools.models import GovAPITool
@@ -21,11 +21,29 @@ class AirKoreaAirQualityInput(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    sido_name: str = Field(..., min_length=1, description="Korean province/city name.")
+    sido_name: str = Field(
+        ...,
+        min_length=1,
+        description="AirKorea short province/city name, e.g. 서울, 부산, 경기.",
+    )
     page_no: int = Field(default=1, ge=1, description="Page number.")
-    num_of_rows: int = Field(default=10, ge=1, le=100, description="Rows per page.")
+    num_of_rows: int = Field(
+        default=100,
+        ge=1,
+        le=100,
+        description="Rows per page; 100 captures all city/province stations in normal use.",
+    )
     ver: str = Field(default="1.0", description="AirKorea response version.")
 
+    @field_validator("sido_name", mode="before")
+    @classmethod
+    def normalize_sido_name(cls, value: object) -> object:
+        """AirKorea returns rows for short 시도 names, not full 행정명 names."""
+
+        if not isinstance(value, str):
+            return value
+        return _normalize_airkorea_sido_name(value)
+
 
 SPEC = require_spec("airkorea_ctprvn_air_quality")
 INPUT_SCHEMA = AirKoreaAirQualityInput
@@ -39,7 +57,94 @@ async def handle(
 ) -> dict[str, object]:
     """Fetch or replay AirKorea air quality rows."""
 
-    return await handle_verified_input(input_model, SPEC, fixture_body=fixture_body)
+    output = await handle_verified_input(input_model, SPEC, fixture_body=fixture_body)
+    return _enrich_air_quality_grades(output)
+
+
+_AIRKOREA_GRADE_LABELS: dict[str, str] = {
+    "1": "좋음",
+    "2": "보통",
+    "3": "나쁨",
+    "4": "매우나쁨",
+}
+
+_AIRKOREA_ITEM_NAMES: dict[str, str] = {
+    "khai": "통합대기환경지수(CAI)",
+    "pm10": "미세먼지(PM10)",
+    "pm25": "초미세먼지(PM2.5)",
+    "o3": "오존(O3)",
+    "no2": "이산화질소(NO2)",
+    "co": "일산화탄소(CO)",
+    "so2": "아황산가스(SO2)",
+}
+
+_AIRKOREA_SIDO_ALIASES: dict[str, str] = {
+    "서울특별시": "서울",
+    "부산광역시": "부산",
+    "대구광역시": "대구",
+    "인천광역시": "인천",
+    "광주광역시": "광주",
+    "대전광역시": "대전",
+    "울산광역시": "울산",
+    "세종특별자치시": "세종",
+    "경기도": "경기",
+    "강원특별자치도": "강원",
+    "강원도": "강원",
+    "충청북도": "충북",
+    "충청남도": "충남",
+    "전북특별자치도": "전북",
+    "전라북도": "전북",
+    "전라남도": "전남",
+    "경상북도": "경북",
+    "경상남도": "경남",
+    "제주특별자치도": "제주",
+    "제주도": "제주",
+}
+
+
+def _normalize_airkorea_sido_name(value: str) -> str:
+    normalized = value.strip()
+    return _AIRKOREA_SIDO_ALIASES.get(normalized, normalized)
+
+
+def _enrich_air_quality_grades(output: dict[str, object]) -> dict[str, object]:
+    items = output.get("items")
+    if not isinstance(items, list):
+        return output
+    enriched_items: list[dict[str, object]] = []
+    changed = False
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        record_raw = item.get("record")
+        if not isinstance(record_raw, dict):
+            enriched_items.append(item)
+            continue
+        record = dict(record_raw)
+        for prefix, name_ko in _AIRKOREA_ITEM_NAMES.items():
+            name_key = f"{prefix}NameKo"
+            if name_key not in record:
+                record[name_key] = name_ko
+                changed = True
+            grade_value = record.get(f"{prefix}Grade")
+            label = _airkorea_grade_label(grade_value)
+            if label is not None:
+                record[f"{prefix}GradeLabelKo"] = label
+                changed = True
+        next_item = dict(item)
+        next_item["record"] = record
+        enriched_items.append(next_item)
+    if not changed:
+        return output
+    enriched_output = dict(output)
+    enriched_output["items"] = enriched_items
+    return enriched_output
+
+
+def _airkorea_grade_label(value: object) -> str | None:
+    if value is None:
+        return None
+    return _AIRKOREA_GRADE_LABELS.get(str(value).strip())
 
 
 def register(registry: ToolRegistry, executor: ToolExecutor) -> None:

package/src/ummaya/tools/verified_data_go_kr/nmc_aed_site.py

@@ -3,7 +3,9 @@
 
 from __future__ import annotations
 
-from pydantic import BaseModel, ConfigDict, Field
+import math
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from ummaya.tools.executor import ToolExecutor
 from ummaya.tools.models import GovAPITool
@@ -25,6 +27,30 @@ class NmcAedSiteInput(BaseModel):
     q1: str = Field(..., min_length=1, description="District/county name.")
     page_no: int = Field(default=1, ge=1, description="Page number.")
     num_of_rows: int = Field(default=10, ge=1, le=100, description="Rows per page.")
+    origin_lat: float | None = Field(
+        default=None,
+        ge=-90,
+        le=90,
+        description=(
+            "Optional original query latitude for client-side distance sorting. "
+            "Not sent to the upstream NMC AED API."
+        ),
+    )
+    origin_lon: float | None = Field(
+        default=None,
+        ge=-180,
+        le=180,
+        description=(
+            "Optional original query longitude for client-side distance sorting. "
+            "Not sent to the upstream NMC AED API."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _origin_pair_is_complete(self) -> NmcAedSiteInput:
+        if (self.origin_lat is None) ^ (self.origin_lon is None):
+            raise ValueError("origin_lat and origin_lon must be supplied together")
+        return self
 
 
 SPEC = require_spec("nmc_aed_site_locate")
@@ -39,7 +65,87 @@ async def handle(
 ) -> dict[str, object]:
     """Fetch or replay NMC AED rows."""
 
-    return await handle_verified_input(input_model, SPEC, fixture_body=fixture_body)
+    output = await handle_verified_input(input_model, SPEC, fixture_body=fixture_body)
+    if input_model.origin_lat is None or input_model.origin_lon is None:
+        return output
+    _sort_items_by_origin_distance(
+        output,
+        origin_lat=input_model.origin_lat,
+        origin_lon=input_model.origin_lon,
+    )
+    return output
+
+
+def _sort_items_by_origin_distance(
+    output: dict[str, object],
+    *,
+    origin_lat: float,
+    origin_lon: float,
+) -> None:
+    items = output.get("items")
+    if not isinstance(items, list):
+        return
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        record = item.get("record")
+        if not isinstance(record, dict):
+            continue
+        lat = _as_float(record.get("wgs84Lat"))
+        lon = _as_float(record.get("wgs84Lon"))
+        if lat is None or lon is None:
+            continue
+        distance_km = round(
+            _haversine_km(
+                lat1=origin_lat,
+                lon1=origin_lon,
+                lat2=lat,
+                lon2=lon,
+            ),
+            3,
+        )
+        record["distance"] = distance_km
+        record["distance_km"] = distance_km
+        record["distance_unit"] = "km"
+    items.sort(key=_distance_sort_key)
+
+
+def _distance_sort_key(item: object) -> tuple[int, float]:
+    if not isinstance(item, dict):
+        return (1, 0.0)
+    record = item.get("record")
+    if not isinstance(record, dict):
+        return (1, 0.0)
+    distance = _as_float(record.get("distance_km"))
+    if distance is None:
+        return (1, 0.0)
+    return (0, distance)
+
+
+def _as_float(value: object) -> float | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int | float):
+        return float(value)
+    if not isinstance(value, str):
+        return None
+    try:
+        return float(value.strip())
+    except ValueError:
+        return None
+
+
+def _haversine_km(*, lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    radius_km = 6371.0088
+    phi1 = math.radians(lat1)
+    phi2 = math.radians(lat2)
+    delta_phi = math.radians(lat2 - lat1)
+    delta_lambda = math.radians(lon2 - lon1)
+    a = (
+        math.sin(delta_phi / 2.0) ** 2
+        + math.cos(phi1) * math.cos(phi2) * math.sin(delta_lambda / 2.0) ** 2
+    )
+    return radius_km * 2.0 * math.atan2(math.sqrt(a), math.sqrt(1.0 - a))
 
 
 def register(registry: ToolRegistry, executor: ToolExecutor) -> None:

package/src/ummaya/tools/verified_data_go_kr/pps_bid_public_info.py

@@ -3,9 +3,10 @@
 
 from __future__ import annotations
 
+from datetime import datetime, timedelta
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from ummaya.tools.executor import ToolExecutor
 from ummaya.tools.models import GovAPITool
@@ -17,27 +18,113 @@ from ummaya.tools.verified_data_go_kr._factory import (
 )
 from ummaya.tools.verified_data_go_kr._manifest import require_spec
 
+_PPS_DATETIME_FORMAT = "%Y%m%d%H%M"
+_PPS_MAX_SEARCH_WINDOW = timedelta(days=31)
+
 
 class PpsBidPublicInfoInput(BaseModel):
     """Input for PPS bid public information."""
 
     model_config = ConfigDict(extra="forbid")
 
-    inqry_div: Literal["2"] = Field(
-        default="2",
+    inqry_div: Literal["1", "2"] = Field(
+        default="1",
+        description=(
+            "Official PPS inqryDiv. Use '1' for bid notice publication datetime "
+            "(pblancDate) searches such as 'this week posted notices'; use '2' "
+            "for bid opening datetime (opengDt) searches."
+        ),
+    )
+    inqry_bgn_dt: str = Field(
+        ...,
+        pattern=r"^\d{12}$",
         description=(
-            "PPS inquiry division. This adapter wraps the verified "
-            "inqryDiv=2 bid-notice-number lookup path."
+            "Official PPS inqryBgnDt search start datetime in YYYYMMDDHHMM. "
+            "Required when inqry_div is '1' or '2'. Keep each PPS request window "
+            "within 31 days."
         ),
     )
-    bid_ntce_no: str = Field(
+    inqry_end_dt: str = Field(
         ...,
-        min_length=1,
-        description="Bid notice number required by the verified inqryDiv=2 lookup path.",
+        pattern=r"^\d{12}$",
+        description=(
+            "Official PPS inqryEndDt search end datetime in YYYYMMDDHHMM. "
+            "Required when inqry_div is '1' or '2'. Keep each PPS request window "
+            "within 31 days."
+        ),
+    )
+    bid_ntce_nm: str | None = Field(
+        default=None,
+        max_length=1000,
+        description=(
+            "Official PPS bidNtceNm notice-name keyword. Partial names are allowed; "
+            "use this for citizen keywords such as 전기공사."
+        ),
+    )
+    ntce_instt_nm: str | None = Field(
+        default=None,
+        max_length=400,
+        description=(
+            "Official PPS ntceInsttNm public notice agency name filter. "
+            "Partial agency names are allowed."
+        ),
+    )
+    dminstt_nm: str | None = Field(
+        default=None,
+        max_length=400,
+        description=(
+            "Official PPS dminsttNm demand agency name filter. Partial agency names are allowed."
+        ),
+    )
+    region_name: str | None = Field(
+        default=None,
+        max_length=100,
+        description=(
+            "UMMAYA client-side region relevance filter copied from citizen wording. "
+            "This is not sent to PPS upstream; after the official response, UMMAYA "
+            "keeps rows whose documented region/agency fields such as cnstrtsiteRgnNm, "
+            "prtcptLmtRgnNm, ntceInsttNm, or dminsttNm match this value."
+        ),
+    )
+    prtcpt_lmt_rgn_nm: str | None = Field(
+        default=None,
+        max_length=100,
+        description=(
+            "Official PPS prtcptLmtRgnNm participation-limit region name. "
+            "For Busan-region notices use 부산광역시 when the citizen says 부산시."
+        ),
+    )
+    indstryty_nm: str | None = Field(
+        default=None,
+        max_length=100,
+        description=(
+            "Official PPS indstrytyNm industry/license name. Use 전기공사업 "
+            "for electrical-construction qualification searches when requested."
+        ),
     )
     page_no: int = Field(default=1, ge=1, description="Page number.")
     num_of_rows: int = Field(default=10, ge=1, le=100, description="Rows per page.")
 
+    @model_validator(mode="after")
+    def validate_official_search_window(self) -> PpsBidPublicInfoInput:
+        """Keep PPS searches inside the observed upstream contract window."""
+
+        try:
+            start = datetime.strptime(self.inqry_bgn_dt, _PPS_DATETIME_FORMAT)
+            end = datetime.strptime(self.inqry_end_dt, _PPS_DATETIME_FORMAT)
+        except ValueError as exc:
+            raise ValueError(
+                "PPS inqry_bgn_dt and inqry_end_dt must be valid YYYYMMDDHHMM datetimes."
+            ) from exc
+        if end < start:
+            raise ValueError("PPS inqry_end_dt must be greater than or equal to inqry_bgn_dt.")
+        if end - start > _PPS_MAX_SEARCH_WINDOW:
+            raise ValueError(
+                "PPS Nara Market bid searches must be split into 31-day-or-smaller "
+                "inqry_bgn_dt/inqry_end_dt windows before calling the upstream API."
+            )
+        return self
+
 
 SPEC = require_spec("pps_bid_public_info")
 INPUT_SCHEMA = PpsBidPublicInfoInput
@@ -51,7 +138,85 @@ async def handle(
 ) -> dict[str, object]:
     """Fetch or replay PPS bid public information rows."""
 
-    return await handle_verified_input(input_model, SPEC, fixture_body=fixture_body)
+    output = await handle_verified_input(input_model, SPEC, fixture_body=fixture_body)
+    return _filter_output_by_region_name(output, input_model.region_name)
+
+
+_REGION_RELEVANCE_FIELDS: tuple[str, ...] = (
+    "cnstrtsiteRgnNm",
+    "prtcptLmtRgnNm",
+    "ntceInsttNm",
+    "dminsttNm",
+    "jntcontrctDutyRgnNm1",
+    "jntcontrctDutyRgnNm2",
+    "jntcontrctDutyRgnNm3",
+)
+
+
+def _filter_output_by_region_name(
+    output: dict[str, object],
+    region_name: str | None,
+) -> dict[str, object]:
+    """Filter PPS rows by documented region-bearing response fields."""
+
+    terms = _region_terms(region_name)
+    if not terms:
+        return output
+
+    raw_items = output.get("items")
+    if not isinstance(raw_items, list):
+        return output
+
+    filtered: list[dict[str, object]] = []
+    for raw_item in raw_items:
+        if not isinstance(raw_item, dict):
+            continue
+        if _item_matches_region(raw_item, terms):
+            filtered.append(raw_item)
+
+    next_output = dict(output)
+    next_output["items"] = filtered
+    next_output["total_count"] = len(filtered)
+    raw_meta = output.get("meta")
+    meta = dict(raw_meta) if isinstance(raw_meta, dict) else {}
+    meta["upstream_total_count"] = output.get("total_count")
+    meta["client_filter"] = {
+        "field": "region_name",
+        "value": region_name,
+        "matched_count": len(filtered),
+    }
+    next_output["meta"] = meta
+    return next_output
+
+
+def _region_terms(region_name: str | None) -> tuple[str, ...]:
+    if region_name is None:
+        return ()
+    normalized = " ".join(region_name.split())
+    if not normalized:
+        return ()
+    terms = [normalized]
+    for suffix in ("특별자치시", "특별자치도", "특별시", "광역시", "도"):
+        if normalized.endswith(suffix):
+            short = normalized[: -len(suffix)]
+            if short:
+                terms.append(short)
+            break
+    return tuple(dict.fromkeys(terms))
+
+
+def _item_matches_region(item: dict[str, object], terms: tuple[str, ...]) -> bool:
+    raw_record = item.get("record")
+    record = raw_record if isinstance(raw_record, dict) else item
+    for field_name in _REGION_RELEVANCE_FIELDS:
+        value = record.get(field_name)
+        if not isinstance(value, str):
+            continue
+        compact_value = value.replace(" ", "")
+        for term in terms:
+            if term in value or term.replace(" ", "") in compact_value:
+                return True
+    return False
 
 
 def register(registry: ToolRegistry, executor: ToolExecutor) -> None:

package/src/ummaya/tools/verified_data_go_kr/tago_bus_arrival.py

@@ -3,6 +3,8 @@
 
 from __future__ import annotations
 
+from typing import cast
+
 from pydantic import BaseModel, ConfigDict, Field
 
 from ummaya.tools.executor import ToolExecutor
@@ -15,14 +17,41 @@ from ummaya.tools.verified_data_go_kr._factory import (
 )
 from ummaya.tools.verified_data_go_kr._manifest import require_spec
 
+_TAGO_CITY_CODE_DESCRIPTION = (
+    "Official TAGO cityCode from the provider getCtyCodeList contract. "
+    "Common metropolitan examples: Busan=21, Daegu=22, Incheon=23, "
+    "Gwangju=24, Daejeon=25, Ulsan=26."
+)
+
 
 class TagoBusArrivalInput(BaseModel):
     """Input for TAGO bus arrival search."""
 
     model_config = ConfigDict(extra="forbid")
 
-    city_code: str = Field(..., min_length=1, description="TAGO city code.")
-    node_id: str = Field(..., min_length=1, description="TAGO bus station ID.")
+    city_code: str = Field(..., min_length=1, description=_TAGO_CITY_CODE_DESCRIPTION)
+    node_id: str = Field(
+        ...,
+        min_length=1,
+        description="Official TAGO nodeId returned by tago_bus_station_search.",
+    )
+    route_no: str | None = Field(
+        default=None,
+        min_length=1,
+        description=(
+            "Optional client-side filter against the official TAGO response field routeno. "
+            "It is not sent upstream; use it when the citizen names a visible bus route "
+            "such as 1001."
+        ),
+    )
+    route_id: str | None = Field(
+        default=None,
+        min_length=1,
+        description=(
+            "Optional client-side filter against the official TAGO response field routeid. "
+            "Get it from tago_bus_route_search when route_no alone is ambiguous."
+        ),
+    )
     page_no: int = Field(default=1, ge=1, description="Page number.")
     num_of_rows: int = Field(default=10, ge=1, le=100, description="Rows per page.")
 
@@ -39,7 +68,41 @@ async def handle(
 ) -> dict[str, object]:
     """Fetch or replay TAGO bus arrival rows."""
 
-    return await handle_verified_input(input_model, SPEC, fixture_body=fixture_body)
+    output = await handle_verified_input(input_model, SPEC, fixture_body=fixture_body)
+    if input_model.route_no is None and input_model.route_id is None:
+        return output
+    return _filter_arrivals(output, route_no=input_model.route_no, route_id=input_model.route_id)
+
+
+def _filter_arrivals(
+    output: dict[str, object],
+    *,
+    route_no: str | None,
+    route_id: str | None,
+) -> dict[str, object]:
+    items = output.get("items")
+    if not isinstance(items, list):
+        return output
+
+    filtered: list[dict[str, object]] = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        record = item.get("record")
+        if not isinstance(record, dict):
+            continue
+        typed_record = cast(dict[str, object], record)
+        if route_no is not None and str(typed_record.get("routeno", "")) != route_no:
+            continue
+        if route_id is not None and str(typed_record.get("routeid", "")) != route_id:
+            continue
+        filtered.append(cast(dict[str, object], item))
+
+    filtered_output = dict(output)
+    filtered_output["items"] = filtered
+    filtered_output["total_count"] = len(filtered)
+    filtered_output["next_cursor"] = None
+    return filtered_output
 
 
 def register(registry: ToolRegistry, executor: ToolExecutor) -> None:

package/src/ummaya/tools/verified_data_go_kr/tago_bus_location.py

@@ -15,14 +15,24 @@ from ummaya.tools.verified_data_go_kr._factory import (
 )
 from ummaya.tools.verified_data_go_kr._manifest import require_spec
 
+_TAGO_CITY_CODE_DESCRIPTION = (
+    "Official TAGO cityCode from the provider getCtyCodeList contract. "
+    "Common metropolitan examples: Busan=21, Daegu=22, Incheon=23, "
+    "Gwangju=24, Daejeon=25, Ulsan=26."
+)
+
 
 class TagoBusLocationInput(BaseModel):
     """Input for TAGO bus location search."""
 
     model_config = ConfigDict(extra="forbid")
 
-    city_code: str = Field(..., min_length=1, description="TAGO city code.")
-    route_id: str = Field(..., min_length=1, description="TAGO route ID.")
+    city_code: str = Field(..., min_length=1, description=_TAGO_CITY_CODE_DESCRIPTION)
+    route_id: str = Field(
+        ...,
+        min_length=1,
+        description="Official TAGO routeId returned by tago_bus_route_search.",
+    )
     page_no: int = Field(default=1, ge=1, description="Page number.")
     num_of_rows: int = Field(default=10, ge=1, le=100, description="Rows per page.")
 

package/src/ummaya/tools/verified_data_go_kr/tago_bus_route.py

@@ -15,14 +15,20 @@ from ummaya.tools.verified_data_go_kr._factory import (
 )
 from ummaya.tools.verified_data_go_kr._manifest import require_spec
 
+_TAGO_CITY_CODE_DESCRIPTION = (
+    "Official TAGO cityCode from the provider getCtyCodeList contract. "
+    "Common metropolitan examples: Busan=21, Daegu=22, Incheon=23, "
+    "Gwangju=24, Daejeon=25, Ulsan=26."
+)
+
 
 class TagoBusRouteInput(BaseModel):
     """Input for TAGO bus route search."""
 
     model_config = ConfigDict(extra="forbid")
 
-    city_code: str = Field(..., min_length=1, description="TAGO city code.")
-    route_no: str = Field(..., min_length=1, description="Bus route number.")
+    city_code: str = Field(..., min_length=1, description=_TAGO_CITY_CODE_DESCRIPTION)
+    route_no: str = Field(..., min_length=1, description="Bus route number visible to citizens.")
     page_no: int = Field(default=1, ge=1, description="Page number.")
     num_of_rows: int = Field(default=10, ge=1, le=100, description="Rows per page.")