@nomadamas/k-skill 0.1.0

package/skills/bok-ecos-stats/scripts/bok_ecos.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+"""Read-only Bank of Korea ECOS economic statistics helper (stdlib only).
+
+Site-dependent access path (discovered live 2026-07-21):
+
+    GET https://ecos.bok.or.kr/api/<Service>/<key>/json/kr/<start>/<end>/<segments...>
+
+- Positional URL segments, no query string.
+- The published demo key ``sample`` works without registration but caps each
+  call at 10 rows (exceeding it returns ERROR-301).
+- Invalid keys return HTTP 200 with {"RESULT": {"CODE": "INFO-100", ...}}.
+- Empty results return {"RESULT": {"CODE": "INFO-200", "MESSAGE": "해당하는 데이터가 없습니다."}}.
+
+Services used:
+- StatisticSearch/<stat>/<cycle>/<start>/<end>[/<item1>] — time series cells
+- StatisticTableList — table catalog
+- StatisticItemList/<stat> — items of one table
+- KeyStatisticList — 100+ headline indicators (환율/금리/물가 등)
+- StatisticWord/<keyword> — glossary
+
+Because the demo key works without registration, this skill calls upstream
+directly (no k-skill-proxy route). Users may set KSKILL_BOK_ECOS_API_KEY for
+larger row limits.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+ECOS_BASE_URL = "https://ecos.bok.or.kr/api"
+ECOS_DEMO_KEY = "sample"
+SAMPLE_MAX_ROWS = 10
+DEFAULT_SECRETS_PATH = pathlib.Path("~/.config/k-skill/secrets.env").expanduser()
+USER_AGENT = "k-skill-bok-ecos/0.1 (+https://github.com/NomaDamas/k-skill)"
+
+# 자주 쓰는 지표 alias → (stat_code, cycle, item_code)
+ALIASES = {
+    "기준금리": ("722Y001", "D", "0101000"),
+    "원달러환율": ("731Y001", "D", "0000001"),
+    "원/달러환율": ("731Y001", "D", "0000001"),
+    "소비자물가지수": ("901Y009", "M", "0"),
+    "cpi": ("901Y009", "M", "0"),
+    "m2": ("101Y004", "M", "BBHA00"),
+    "통화량": ("101Y004", "M", "BBHA00"),
+    "국고채3년": ("817Y002", "D", "010200000"),
+}
+
+SEGMENT_PATTERN = re.compile(r"^[A-Za-z0-9_.\-]+$")
+
+ERROR_HINTS = {
+    "INFO-100": "인증키가 유효하지 않습니다. KSKILL_BOK_ECOS_API_KEY를 확인하거나 https://ecos.bok.or.kr/api 에서 키를 발급받으세요.",
+    "ERROR-301": "sample 키는 최대 10건까지만 조회할 수 있습니다. 더 많은 행이 필요하면 개인 키를 발급받아 KSKILL_BOK_ECOS_API_KEY로 지정하세요.",
+}
+
+EMPTY_CODES = {"INFO-200"}
+
+
+class HelperError(RuntimeError):
+    pass
+
+
+def load_secrets(path: pathlib.Path) -> Dict[str, str]:
+    values: Dict[str, str] = {}
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return values
+    for raw in lines:
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip('"').strip("'")
+    return values
+
+
+def resolve_api_key(secrets_path: str) -> Optional[str]:
+    env_value = os.environ.get("KSKILL_BOK_ECOS_API_KEY")
+    if env_value and env_value.strip():
+        return env_value.strip()
+    secrets = load_secrets(pathlib.Path(secrets_path).expanduser())
+    value = secrets.get("KSKILL_BOK_ECOS_API_KEY")
+    return value.strip() if value and value.strip() else None
+
+
+def _check_segment(value: str, label: str) -> str:
+    if not SEGMENT_PATTERN.match(value or ""):
+        raise HelperError(f"올바른 {label} 값이 아닙니다: {value!r}")
+    return value
+
+
+def _resolve_series(args: argparse.Namespace) -> tuple[str, str, Optional[str]]:
+    if args.alias:
+        needle = args.alias.strip().lower()
+        if needle not in ALIASES:
+            known = ", ".join(sorted(ALIASES))
+            raise HelperError(f"알 수 없는 alias 입니다: {args.alias!r} (지원: {known})")
+        stat_code, cycle, item_code = ALIASES[needle]
+        return stat_code, cycle, item_code
+    if not args.stat_code:
+        raise HelperError("--stat-code 또는 --alias 중 하나가 필요합니다.")
+    if not args.cycle:
+        raise HelperError("--stat-code 사용 시 --cycle(A/S/Q/M/SM/D)이 필요합니다.")
+    return (
+        _check_segment(args.stat_code, "stat-code"),
+        _check_segment(args.cycle, "cycle"),
+        _check_segment(args.item_code, "item-code") if args.item_code else None,
+    )
+
+
+def build_url(args: argparse.Namespace, api_key: Optional[str]) -> str:
+    key = api_key or ECOS_DEMO_KEY
+    limit = max(1, args.limit)
+    if key == ECOS_DEMO_KEY:
+        limit = min(limit, SAMPLE_MAX_ROWS)
+
+    if args.command == "search":
+        stat_code, cycle, item_code = _resolve_series(args)
+        start = _check_segment(args.start, "start")
+        end = _check_segment(args.end, "end")
+        segments = [ECOS_BASE_URL, "StatisticSearch", key, "json", "kr", "1", str(limit), stat_code, cycle, start, end]
+        if item_code:
+            segments.append(item_code)
+        return "/".join(segments)
+    if args.command == "tables":
+        return "/".join([ECOS_BASE_URL, "StatisticTableList", key, "json", "kr", "1", str(limit)]) + "/"
+    if args.command == "items":
+        stat_code = _check_segment(args.stat_code, "stat-code")
+        return "/".join([ECOS_BASE_URL, "StatisticItemList", key, "json", "kr", "1", str(limit), stat_code])
+    if args.command == "key":
+        return "/".join([ECOS_BASE_URL, "KeyStatisticList", key, "json", "kr", "1", str(limit)]) + "/"
+    # word
+    query = (args.query or "").strip()
+    if not query:
+        raise HelperError("--query 검색어가 필요합니다.")
+    encoded = urllib.parse.quote(query, safe="")
+    return "/".join([ECOS_BASE_URL, "StatisticWord", key, "json", "kr", "1", str(limit), encoded])
+
+
+def http_get_json(url: str, timeout: int) -> Dict[str, Any]:
+    request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = response.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as exc:
+        raise HelperError(f"ECOS HTTP 오류: {exc.code}") from exc
+    except urllib.error.URLError as exc:
+        raise HelperError(f"ECOS 접속 실패: {exc.reason}") from exc
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise HelperError("ECOS 응답이 JSON이 아닙니다 (차단 또는 점검 가능성).") from exc
+
+
+def normalize_payload(payload: Dict[str, Any], service: str) -> List[Dict[str, Any]]:
+    if not isinstance(payload, dict):
+        raise HelperError("ECOS 응답 형식이 올바르지 않습니다.")
+    result = payload.get("RESULT")
+    if isinstance(result, dict):
+        code = str(result.get("CODE") or "")
+        if code in EMPTY_CODES:
+            return []
+        message = ERROR_HINTS.get(code) or f"ECOS 오류 [{code}]: {result.get('MESSAGE', '')}"
+        raise HelperError(message)
+    body = payload.get(service)
+    if not isinstance(body, dict) or not isinstance(body.get("row"), list):
+        raise HelperError("ECOS 응답에서 데이터 행을 찾지 못했습니다 (서비스명/파라미터 확인).")
+    return [row for row in body["row"] if isinstance(row, dict)]
+
+
+def _project(rows: List[Dict[str, Any]], mapping: Dict[str, str]) -> List[Dict[str, Any]]:
+    return [{out: row.get(src) for out, src in mapping.items()} for row in rows]
+
+
+PROJECTIONS = {
+    "search": {
+        "stat_code": "STAT_CODE",
+        "stat_name": "STAT_NAME",
+        "item_name": "ITEM_NAME1",
+        "unit": "UNIT_NAME",
+        "time": "TIME",
+        "value": "DATA_VALUE",
+    },
+    "tables": {
+        "stat_code": "STAT_CODE",
+        "stat_name": "STAT_NAME",
+        "cycle": "CYCLE",
+        "searchable": "SRCH_YN",
+        "org": "ORG_NAME",
+    },
+    "items": {
+        "stat_code": "STAT_CODE",
+        "item_code": "ITEM_CODE",
+        "item_name": "ITEM_NAME",
+        "cycle": "CYCLE",
+        "start_time": "START_TIME",
+        "end_time": "END_TIME",
+    },
+    "key": {
+        "class_name": "CLASS_NAME",
+        "name": "KEYSTAT_NAME",
+        "value": "DATA_VALUE",
+        "cycle": "CYCLE",
+        "unit": "UNIT_NAME",
+    },
+    "word": {
+        "word": "WORD",
+        "content": "CONTENT",
+    },
+}
+
+SERVICES = {
+    "search": "StatisticSearch",
+    "tables": "StatisticTableList",
+    "items": "StatisticItemList",
+    "key": "KeyStatisticList",
+    "word": "StatisticWord",
+}
+
+
+def render_text(command: str, rows: List[Dict[str, Any]]) -> str:
+    if not rows:
+        return "조건에 맞는 데이터가 없습니다."
+    lines = []
+    for row in rows:
+        if command == "search":
+            lines.append(f"{row['time']} · {row['item_name']}: {row['value']} {row['unit'] or ''}".rstrip())
+        elif command == "key":
+            lines.append(f"[{row['class_name']}] {row['name']}: {row['value']} {row['unit'] or ''} ({row['cycle']})")
+        elif command == "tables":
+            lines.append(f"{row['stat_code']} · {row['stat_name']} (주기 {row['cycle'] or '-'})")
+        elif command == "items":
+            lines.append(f"{row['item_code']} · {row['item_name']} ({row['cycle']}, {row['start_time']}~{row['end_time']})")
+        else:
+            lines.append(f"{row['word']}: {row['content']}")
+    return "\n".join(lines)
+
+
+def parse_args(argv: List[str]) -> argparse.Namespace:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--secrets-path", default=str(DEFAULT_SECRETS_PATH))
+    common.add_argument("--timeout", type=int, default=30)
+    common.add_argument("--limit", type=int, default=10, help="조회 행 수 (sample 키는 최대 10)")
+    common.add_argument("--text", action="store_true", help="사람용 요약 출력")
+
+    parser = argparse.ArgumentParser(description="한국은행 ECOS 경제통계 조회")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    search = subparsers.add_parser("search", parents=[common], help="통계코드/alias 기반 시계열 조회")
+    search.add_argument("--stat-code", help="통계표 코드 (예: 722Y001)")
+    search.add_argument("--cycle", help="주기: A/S/Q/M/SM/D")
+    search.add_argument("--item-code", help="통계항목 코드 (선택)")
+    search.add_argument("--alias", help="자주 쓰는 지표 별칭 (기준금리/원달러환율/소비자물가지수/M2/국고채3년)")
+    search.add_argument("--start", required=True, help="시작 시점 (주기 형식에 맞춤, 예: 20260101, 202601, 2026)")
+    search.add_argument("--end", required=True, help="종료 시점")
+
+    subparsers.add_parser("tables", parents=[common], help="통계표 목록")
+
+    items = subparsers.add_parser("items", parents=[common], help="통계표의 항목 목록")
+    items.add_argument("--stat-code", required=True)
+
+    subparsers.add_parser("key", parents=[common], help="100대 핵심 지표 (환율/금리/물가 등)")
+
+    word = subparsers.add_parser("word", parents=[common], help="통계 용어 사전 검색")
+    word.add_argument("--query", required=True)
+
+    return parser.parse_args(argv)
+
+
+def run(argv: List[str]) -> int:
+    args = parse_args(argv)
+    try:
+        api_key = resolve_api_key(args.secrets_path)
+        url = build_url(args, api_key)
+        payload = http_get_json(url, args.timeout)
+        raw_rows = normalize_payload(payload, SERVICES[args.command])
+        rows = _project(raw_rows, PROJECTIONS[args.command])
+        if args.text:
+            print(render_text(args.command, rows))
+        else:
+            print(json.dumps({
+                "result": "ok" if rows else "empty",
+                "rows": rows,
+                "source": "ecos.bok.or.kr Open API",
+            }, ensure_ascii=False, indent=2))
+        return 0
+    except HelperError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(run(sys.argv[1:]))

package/skills/bok-ecos-stats/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "bok-ecos-stats",
+  "description": "한국은행 ECOS Open API로 기준금리, 환율, 소비자물가지수, 통화량 등 중앙은행 경제통계 시계열과 100대 핵심지표를 조회한다. Use when the user asks 기준금리, 환율 추이, 물가지수, M2, 국고채 금리, 거시경제 통계. Not for 주식 시세(korean-stock-search) or KOSIS 일반 통계(kosis-stats).",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: bok-ecos-stats\ndescription: 한국은행 ECOS Open API로 기준금리, 환율, 소비자물가지수, 통화량 등 중앙은행 경제통계 시계열과 100대 핵심지표를 조회한다. Use when the user asks 기준금리, 환율 추이, 물가지수, M2, 국고채 금리, 거시경제 통계. Not for 주식 시세(korean-stock-search) or KOSIS 일반 통계(kosis-stats).\nlicense: MIT\nmetadata:\n  category: data\n  locale: ko-KR\n  phase: v1"
+}

package/skills/building-register-search/instruction.md

@@ -0,0 +1,69 @@
+# Building Register Search
+
+## What this skill does
+
+국토교통부 건축물대장정보 서비스의 표제부(`getBrTitleInfo`)를 조회한다. 주소, 19자리 PNU, 또는 법정동 코드와 지번을 입력받아 주용도, 연면적, 지상/지하 층수, 사용승인일, 관리번호와 주소 식별 필드를 반환한다.
+
+이 스킬은 건축물의 행정대장 정보만 조회한다. 소유권, 근저당, 가압류 등 권리관계는 확인하지 않으며, 그 목적에는 별도 `iros-registry-automation` 스킬을 사용한다.
+
+## Official access path
+
+1. 공공데이터포털 데이터셋 `15134735`
+2. 공식 endpoint `https://apis.data.go.kr/1613000/BldRgstHubService/getBrTitleInfo`
+3. portable XML 응답을 프록시가 파싱해 JSON으로 정규화
+4. 주소 입력 시 hosted/self-host proxy의 `/v1/kakao-local/geocode?q=...`로 법정동 `b_code`와 지번을 확정한 뒤 `/v1/building-register/title` 호출
+
+공식 API가 기본 경로이며 화면 scraping이나 비공식 endpoint로 우회하지 않는다.
+
+## Commands
+
+```bash
+python3 scripts/building_register.py title --address '서울 강남구 역삼동 123-4'
+python3 scripts/building_register.py title --pnu 1168010100101230004
+python3 scripts/building_register.py title --sigungu-cd 11680 --bjdong-cd 10100 --plat-gb-cd 0 --bun 123 --ji 4
+python3 scripts/building_register.py title --pnu 1168010100101230004 --json
+```
+
+PNU는 `sigunguCd(5) + bjdongCd(5) + 토지구분(1) + bun(4) + ji(4)`의 19자리다. PNU 토지구분 `1`(일반 토지)은 건축물대장 API `platGbCd=0`, `2`(산)는 `platGbCd=1`로 변환한다. 개별 필드나 주소 결과로 PNU를 구성할 때도 API 값 `0`은 PNU `1`, API 값 `1`은 PNU `2`로 역변환한다. `--plat-gb-cd`를 직접 입력할 때는 PNU 값이 아니라 건축물대장 API 값이며 공식 값 `0`, `1`, `2`를 허용한다. API 값 `2`는 그대로 조회에 전달하되 대응하는 표준 PNU 토지구분이 없으므로 PNU를 구성하지 않는다. 개별 입력의 `bun`, `ji`는 4자리로 왼쪽 zero-padding되며 `ji` 생략 시 `0000`이다. `pageNo` 기본값은 1, `numOfRows` 기본값은 10이고 최대 100이다.
+
+주소 입력은 proxy mode 전용이다. Kakao 응답에서 정확히 하나의 주소, 10자리 법정동 `b_code`, 본번, 산 여부를 얻어야 한다. 결과가 여러 개이거나 장소명 fallback만 있거나 필지 정보가 빠졌으면 추정하지 않고 중단한다.
+
+## Direct mode
+
+```bash
+python3 scripts/building_register.py title --pnu 1168010100101230004 --direct
+python3 scripts/building_register.py title --pnu 1168010100101230004 --direct --dry-run
+```
+
+`--direct`는 주소를 받지 않는다. `KSKILL_BUILDING_REGISTER_API_KEY`, 그다음 `DATA_GO_KR_API_KEY`, 마지막으로 `~/.config/k-skill/secrets.env`의 같은 키 순서로 찾는다. Kakao direct credential은 사용하지 않는다. `--dry-run`은 실제 키를 `REDACTED`로 가린다.
+
+hosted proxy 사용자는 키가 필요 없다. self-host 운영자 또는 direct 사용자는 공공데이터포털 키 발급과 별개로 데이터셋 `15134735`에 **별도 활용신청**해야 한다. 이 데이터셋은 자동승인 대상이지만 활성화 전 호출은 인증 오류가 될 수 있다.
+
+## Output
+
+기본 출력은 한국어 요약이고 `--json`은 정규화된 payload를 출력한다. 주요 필드는 `mgmBldrgstPk`, `regstrKindCdNm`, `platPlc`, `newPlatPlc`, `sigunguCd`, `bjdongCd`, `platGbCd`, `bun`, `ji`, `mainPurpsCdNm`, `totArea`, `grndFlrCnt`, `ugrndFlrCnt`, `useAprDay`다. API가 제공한 그 밖의 유용한 표제부 원문 필드와 데이터셋/operation/upstream/XML source metadata도 보존한다.
+
+## Fallback order
+
+1. PNU가 있으면 바로 건축물대장 route를 호출한다.
+2. 법정동 코드와 필지가 있으면 건축물대장 API 의미의 개별 필드로 같은 route를 호출한다.
+3. 주소만 있으면 proxy Kakao geocode로 법정동 코드와 필지를 확정한 뒤 building route를 호출한다.
+4. 주소가 모호하거나 필지가 없으면 사용자에게 더 정확한 지번 주소 또는 PNU를 요청한다.
+5. official API 장애, 인증/쿼터 오류에는 비공식 데이터로 대체하지 않는다.
+
+## Failure modes
+
+- empty result: 해당 필지에 표제부가 없거나 입력 코드/지번이 맞지 않음
+- ambiguous address: Kakao 결과가 하나로 확정되지 않음
+- missing parcel or `b_code`: 장소명/도로명만으로 필지를 확정할 수 없음
+- `upstream_not_configured`: self-host proxy에 `DATA_GO_KR_API_KEY`가 없음
+- HTTP 401/403 or semantic auth XML: 데이터셋 `15134735` 활용신청/활성화 확인
+- quota/service limit: 공공데이터포털 이용량과 서비스 상태 확인 후 재시도
+- empty/invalid XML: upstream 응답 오류로 처리하며 캐시하지 않음
+- proxy down: 잠시 후 재시도하거나 self-host 운영자에게 문의
+
+## Done when
+
+- 주소 또는 PNU/법정동+필지 입력이 하나의 조회 필지로 정규화됐다.
+- 표제부 결과와 source metadata를 제공했거나 명시적 실패 모드로 중단했다.
+- 건축물대장 정보와 등기부 권리관계를 혼동하지 않았다.