@nomadamas/k-skill 0.1.0

package/skills/korean-heritage-search/scripts/korean_heritage_search.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+from typing import Iterable
+
+LIST_URL = "https://www.khs.go.kr/cha/SearchKindOpenapiList.do"
+DETAIL_URL = "https://www.khs.go.kr/cha/SearchKindOpenapiDt.do"
+EVENT_URL = "https://www.khs.go.kr/cha/openapi/selectEventListOpenapi.do"
+OPEN_API_GUIDE_URL = "https://www.khs.go.kr/html/HtmlPage.do?mn=NS_04_04_03&pg=%2Fpublicinfo%2Fpbinfo3_0201.jsp"
+USER_AGENT = "k-skill-korean-heritage-search/1.0"
+
+REGION_CODES = {
+    "서울": "11",
+    "부산": "21",
+    "대구": "22",
+    "인천": "23",
+    "광주": "24",
+    "대전": "25",
+    "울산": "26",
+    "경기": "31",
+    "강원": "32",
+    "충북": "33",
+    "충남": "34",
+    "전북": "35",
+    "전남": "36",
+    "경북": "37",
+    "경남": "38",
+    "제주": "39",
+    "세종": "45",
+}
+
+
+class HeritageApiError(RuntimeError):
+    """Raised when the official heritage API cannot return valid XML."""
+
+
+def _clean_text(value: str | None) -> str:
+    if not value:
+        return ""
+    text = html.unescape(value)
+    text = re.sub(r"<br\s*/?>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"</?(?:p|div|li|ul|ol|h[1-6])[^>]*>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"<[^>]+>", "", text)
+    text = re.sub(r"[ \t\f\v]+", " ", text)
+    text = re.sub(r"\n[ \t]+", "\n", text)
+    return text.strip()
+
+
+def _child_text(parent: ET.Element, name: str) -> str:
+    child = parent.find(name)
+    return _clean_text(child.text if child is not None else "")
+
+
+def _int_or_none(value: str) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _float_or_none(value: str) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _request_xml(url: str, params: dict[str, str], timeout: float = 20.0) -> ET.Element:
+    query = urllib.parse.urlencode({key: value for key, value in params.items() if value != ""})
+    request = urllib.request.Request(
+        f"{url}?{query}",
+        headers={"Accept": "application/xml", "User-Agent": USER_AGENT},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = response.read()
+    except urllib.error.HTTPError as exc:
+        raise HeritageApiError(f"official heritage API returned HTTP {exc.code}") from exc
+    except (urllib.error.URLError, TimeoutError) as exc:
+        raise HeritageApiError(f"official heritage API request failed: {exc.reason if isinstance(exc, urllib.error.URLError) else exc}") from exc
+
+    try:
+        root = ET.fromstring(body)
+    except ET.ParseError as exc:
+        raise HeritageApiError("official heritage API returned invalid XML") from exc
+    if root.tag.rsplit("}", 1)[-1] != "result":
+        raise HeritageApiError("official heritage API returned an unexpected XML root")
+    return root
+
+
+def _source_payload(url: str, fetched_at: str) -> dict[str, str]:
+    return {"url": url, "fetched_at": fetched_at}
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def normalize_region(region: str) -> str:
+    value = region.strip()
+    if value in REGION_CODES:
+        return REGION_CODES[value]
+    if value in REGION_CODES.values():
+        return value
+    raise ValueError(f"unknown region: {region}; use a Korean region name or code")
+
+
+def _list_item(item: ET.Element) -> dict[str, object]:
+    return {
+        "name": _child_text(item, "ccbaMnm1"),
+        "name_hanja": _child_text(item, "ccbaMnm2"),
+        "heritage_type": _child_text(item, "ccmaName"),
+        "province": _child_text(item, "ccbaCtcdNm"),
+        "district": _child_text(item, "ccsiName"),
+        "admin": _child_text(item, "ccbaAdmin"),
+        "latitude": _float_or_none(_child_text(item, "latitude")),
+        "longitude": _float_or_none(_child_text(item, "longitude")),
+        "designated_status": _child_text(item, "ccbaCncl"),
+        "updated_at": _child_text(item, "regDt"),
+        "heritage_code": {
+            "kind": _child_text(item, "ccbaKdcd"),
+            "number": _child_text(item, "ccbaAsno"),
+            "province": _child_text(item, "ccbaCtcd"),
+        },
+    }
+
+
+def parse_search_result(root: ET.Element, *, url: str, fetched_at: str) -> dict[str, object]:
+    items = [_list_item(item) for item in root.findall("./item")]
+    return {
+        "total_results": _int_or_none(_child_text(root, "totalCnt")) or 0,
+        "page": _int_or_none(_child_text(root, "pageIndex")) or 1,
+        "page_size": _int_or_none(_child_text(root, "pageUnit")) or len(items),
+        "items": items,
+        "source": _source_payload(url, fetched_at),
+    }
+
+
+def search_heritage(query: str = "", region: str = "", page: int = 1, limit: int = 10) -> dict[str, object]:
+    if page < 1:
+        raise ValueError("page must be at least 1")
+    if not 1 <= limit <= 100:
+        raise ValueError("limit must be between 1 and 100")
+    params = {
+        "pageUnit": str(limit),
+        "pageIndex": str(page),
+        "ccbaCncl": "N",
+        "ccbaMnm1": query.strip(),
+        "ccbaCtcd": normalize_region(region) if region else "",
+    }
+    fetched_at = _now_iso()
+    root = _request_xml(LIST_URL, params)
+    return parse_search_result(root, url=LIST_URL, fetched_at=fetched_at)
+
+
+def parse_detail_result(root: ET.Element, *, url: str, fetched_at: str) -> dict[str, object]:
+    item = root.find("./item")
+    if item is None:
+        raise HeritageApiError("heritage detail was not found")
+    if not _child_text(item, "ccbaMnm1") or any(
+        not _child_text(root, field) for field in ("ccbaKdcd", "ccbaAsno", "ccbaCtcd")
+    ):
+        raise HeritageApiError("heritage detail was not found")
+    return {
+        "name": _child_text(item, "ccbaMnm1"),
+        "name_hanja": _child_text(item, "ccbaMnm2"),
+        "heritage_type": _child_text(item, "ccmaName"),
+        "classification": [
+            value for value in (
+                _child_text(item, "gcodeName"),
+                _child_text(item, "bcodeName"),
+                _child_text(item, "mcodeName"),
+                _child_text(item, "scodeName"),
+            ) if value
+        ],
+        "quantity": _child_text(item, "ccbaQuan"),
+        "designated_date": _child_text(item, "ccbaAsdt"),
+        "province": _child_text(item, "ccbaCtcdNm"),
+        "district": _child_text(item, "ccsiName"),
+        "address": _child_text(item, "ccbaLcad"),
+        "built_or_created": _child_text(item, "ccceName"),
+        "ownership": _child_text(item, "ccbaPoss"),
+        "admin": _child_text(item, "ccbaAdmin"),
+        "description": _child_text(item, "content"),
+        "image_url": _child_text(item, "imageUrl"),
+        "latitude": _float_or_none(_child_text(root, "latitude")),
+        "longitude": _float_or_none(_child_text(root, "longitude")),
+        "heritage_code": {
+            "kind": _child_text(root, "ccbaKdcd"),
+            "number": _child_text(root, "ccbaAsno"),
+            "province": _child_text(root, "ccbaCtcd"),
+        },
+        "source": _source_payload(url, fetched_at),
+    }
+
+
+def get_heritage_detail(kind: str, number: str, province_code: str) -> dict[str, object]:
+    values = {"ccbaKdcd": kind.strip(), "ccbaAsno": number.strip(), "ccbaCtcd": province_code.strip()}
+    if any(not value for value in values.values()):
+        raise ValueError("detail requires ccba-kdcd, ccba-asno, and ccba-ctcd")
+    fetched_at = _now_iso()
+    root = _request_xml(DETAIL_URL, values)
+    return parse_detail_result(root, url=DETAIL_URL, fetched_at=fetched_at)
+
+
+def _event_item(item: ET.Element) -> dict[str, object]:
+    return {
+        "title": _child_text(item, "subTitle"),
+        "description": _child_text(item, "subContent"),
+        "start_date": _child_text(item, "sDate"),
+        "end_date": _child_text(item, "eDate"),
+        "display_date": _child_text(item, "subDate"),
+        "province": _child_text(item, "sido"),
+        "district": _child_text(item, "gugun"),
+        "venue": _child_text(item, "subDesc"),
+        "organizer": _child_text(item, "groupName"),
+        "audience": _child_text(item, "subDesc_2"),
+        "fee": _child_text(item, "subDesc_3"),
+        "contact": _child_text(item, "contact"),
+        "url": _child_text(item, "subPath"),
+    }
+
+
+def parse_event_result(
+    root: ET.Element,
+    *,
+    year: int,
+    month: int,
+    region: str,
+    limit: int,
+    url: str,
+    fetched_at: str,
+) -> dict[str, object]:
+    items: Iterable[dict[str, object]] = (_event_item(item) for item in root.findall("./item"))
+    if region:
+        needle = region.strip()
+        items = (
+            item for item in items
+            if needle in str(item["province"]) or needle in str(item["district"])
+        )
+    selected = list(items)[:limit]
+    return {
+        "year": year,
+        "month": month,
+        "returned_count": len(selected),
+        "items": selected,
+        "source": _source_payload(url, fetched_at),
+    }
+
+
+def search_events(year: int, month: int, region: str = "", limit: int = 20) -> dict[str, object]:
+    if not 1 <= year <= 9999:
+        raise ValueError("year must be between 1 and 9999")
+    if not 1 <= month <= 12:
+        raise ValueError("month must be between 1 and 12")
+    if not 1 <= limit <= 100:
+        raise ValueError("limit must be between 1 and 100")
+    params = {"searchYear": str(year), "searchMonth": str(month)}
+    fetched_at = _now_iso()
+    root = _request_xml(EVENT_URL, params)
+    return parse_event_result(
+        root,
+        year=year,
+        month=month,
+        region=region,
+        limit=limit,
+        url=EVENT_URL,
+        fetched_at=fetched_at,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Search official Korean heritage records and events.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    search = subparsers.add_parser("search", help="search heritage records")
+    search.add_argument("--query", default="", help="heritage name keyword")
+    search.add_argument("--region", default="", help="Korean province name or code")
+    search.add_argument("--page", type=int, default=1)
+    search.add_argument("--limit", type=int, default=10)
+
+    detail = subparsers.add_parser("detail", help="show one heritage record")
+    detail.add_argument("--ccba-kdcd", required=True)
+    detail.add_argument("--ccba-asno", required=True)
+    detail.add_argument("--ccba-ctcd", required=True)
+
+    events = subparsers.add_parser("events", help="search monthly heritage events")
+    events.add_argument("--year", type=int, required=True)
+    events.add_argument("--month", type=int, required=True)
+    events.add_argument("--region", default="", help="province or district text filter")
+    events.add_argument("--limit", type=int, default=20)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "search":
+            payload = search_heritage(args.query, args.region, args.page, args.limit)
+        elif args.command == "detail":
+            payload = get_heritage_detail(args.ccba_kdcd, args.ccba_asno, args.ccba_ctcd)
+        else:
+            payload = search_events(args.year, args.month, args.region, args.limit)
+    except (HeritageApiError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/korean-heritage-search/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "korean-heritage-search",
+  "description": "Search official Korean national heritage records, details, locations, and monthly heritage events from the Korea Heritage Service Open API.",
+  "profiles": [
+    "lookup"
+  ],
+  "frontmatter": "name: korean-heritage-search\ndescription: Search official Korean national heritage records, details, locations, and monthly heritage events from the Korea Heritage Service Open API.\nlicense: MIT\nmetadata:\n  category: history\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-holiday-calendar/instruction.md

@@ -0,0 +1,97 @@
+# Korean Holiday Calendar
+
+## What this skill does
+
+공공데이터포털 **한국천문연구원_특일 정보**(data.go.kr `15012690`)의 `SpcdeInfoService`를 `k-skill-proxy` 경유로 호출한다.
+
+지원 operation:
+
+- `rest` → `getRestDeInfo` 공휴일
+- `national` → `getHoliDeInfo` 국경일
+- `anniversary` → `getAnniversaryInfo` 기념일
+- `solarTerm` → `get24DivisionsInfo` 24절기
+- `sundry` → `getSundryDayInfo` 잡절
+
+## When to use
+
+- "2026년 8월 공휴일 알려줘"
+- "오늘이 공휴일인지 확인해줘"
+- "2026년 24절기 조회해줘"
+- "대체공휴일 있는지 확인해줘"
+
+## Prerequisites
+
+- 인터넷 연결
+- hosted/self-host `k-skill-proxy`의 `/v1/korean-holiday/calendar` route 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+- `DATA_GO_KR_API_KEY` 는 프록시 운영 서버 환경에만 둔다. 공공데이터포털 `한국천문연구원_특일 정보`(15012690) 활용신청이 승인돼 있어야 한다.
+
+키 발급:
+
+- API 페이지: <https://www.data.go.kr/data/15012690/openapi.do>
+- 공공데이터포털 이용 가이드: <https://www.data.go.kr/ugs/selectPublicDataUseGuideView.do>
+
+## Inputs
+
+- `operation`/`type`: `rest`(기본), `national`, `anniversary`, `solarTerm`, `sundry`
+- `year`/`solYear`: 4자리 연도
+- `month`/`solMonth`: 선택, `01`-`12`
+- `page`/`pageNo`: 기본 1
+- `limit`/`numOfRows`: 기본 100, 최대 1000
+
+## Workflow
+
+### 1. Query holidays for the target month or year
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/korean-holiday/calendar" \
+  --data-urlencode "operation=rest" \
+  --data-urlencode "year=2026" \
+  --data-urlencode "month=08"
+```
+
+### 2. Decide holiday status from upstream fields
+
+응답 item의 핵심 필드:
+
+- `locdate`: `YYYYMMDD`
+- `dateName`: 특일 이름
+- `isHoliday`: `Y`면 공휴일, `N`이면 특일이지만 휴일 아님
+- `dateKind`, `seq`: upstream 분류/순번
+
+"오늘/내일이 공휴일인지" 묻는 경우 KST 기준 날짜를 `YYYYMMDD`로 만든 뒤 해당 `locdate`의 `isHoliday`를 확인한다.
+
+## Failure modes
+
+- `400 bad_request`: 연도/월/operation/page 값이 잘못됨.
+- `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY` 없음 또는 15012690 활용신청 미승인.
+- `502 upstream_forbidden`: data.go.kr gateway가 키를 거부함.
+- 빈 결과: 해당 연월/operation에 특일 없음. operation을 바꿔 재조회한다.
+- 24절기/잡절 operation은 한국천문연구원 특일 서비스의 관례적 operation 이름을 사용한다. live smoke에서 upstream 변경이 확인되면 route allowlist를 갱신한다.
+
+## Done when
+
+- KST 기준 날짜와 요청 연월이 일치한다.
+- `k-skill-proxy` route를 통해 호출했고 사용자에게 API key를 요구하지 않았다.
+- 답변에는 `locdate`, `dateName`, `isHoliday`, operation을 함께 명시했다.
+
+## Maintainer review notes
+
+키 없이 가능한 검증:
+
+- `./scripts/validate-skills.sh`
+- `node --test packages/k-skill-proxy/test/server.test.js`
+- `curl -i --get "$KSKILL_PROXY_BASE_URL/v1/korean-holiday/calendar" --data-urlencode "year=2026"` (키 미설정이면 503 확인)
+
+Live smoke는 hosted/self-host proxy에 `DATA_GO_KR_API_KEY`가 설정되고 `15012690` 활용신청이 승인된 뒤 수행한다.
+
+## Safety notes
+
+- 조회 전용 스킬이다.
+- 법정 영업일 판단, 금융/법률 마감 산정에는 원천 API 결과와 관계 법령/기관 공지를 함께 확인한다.
+- 인증키는 프록시 서버에서만 다루며 repo/GitHub Actions/public docs에 저장하지 않는다.

package/skills/korean-holiday-calendar/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "korean-holiday-calendar",
+  "description": "한국천문연구원 특일 정보 API를 k-skill-proxy 경유로 호출해 공휴일·국경일·기념일·24절기·잡절을 조회한다. 조회 전용.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: korean-holiday-calendar\ndescription: 한국천문연구원 특일 정보 API를 k-skill-proxy 경유로 호출해 공휴일·국경일·기념일·24절기·잡절을 조회한다. 조회 전용.\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v1"
+}