KOSIS 통계표를 키워드로 검색합니다.

원하는 통계 데이터를 찾을 때 첫 번째로 사용하는 도구입니다. 검색 결과에서 org_id와 tbl_id를 얻어 다음 단계에 사용합니다.

Args: keyword: 검색 키워드 (예: "인구", "고용", "물가", "GDP") org_id: 기관 ID로 필터링 (선택) "101"=통계청, "154"=고용노동부, "301"=한국은행 limit: 최대 결과 수 (기본 10) sort: 정렬 기준 (선택) - "RANK": 관련도 순 (KOSIS 기본) - "DATE": 최신 갱신일 순 — verify_statistics 같이 최신 데이터가 중요할 때 권장 None이면 KOSIS 기본(RANK).

Returns: { "query": "인구", "result_count": 10, "results": [...], "org_distribution": {"통계청": 5, "한국은행": 3, ...}, "next_step": "get_table_metadata(org_id, tbl_id)로 테이블 구조 확인" }

Example: >>> search_statistics("인구") >>> search_statistics("고용", org_id="154") >>> search_statistics("최저임금", sort="DATE") # 최신 갱신 순

기관별 / 주제별 / 임의 view 로 KOSIS 통계 목록을 탐색합니다.

Args: by: 탐색 기준 - "org": 기관별 (통계청, 고용노동부 등) — 일반 사용 - "theme": 주제별 (인구, 경제, 사회 등) — 일반 사용 - "view": 임의 vwCd (광복이전 / 북한 / 영문 / e-지방지표 / 국제 등 12종) code: by="org"면 기관 코드(101, 118, ...). by="theme"이면 주제 코드(A, B, C, ...). by="view"이면 vwCd 본문(MT_ETITLE, MT_BUKHAN, MT_CHOSUN_TITLE, MT_HANKUK_TITLE, MT_STOP_TITLE, MT_RTITLE, MT_TM1_TITLE, MT_TM2_TITLE, MT_GTITLE01, MT_GTITLE02, MT_OTITLE, MT_ZTITLE). None이면 view 루트 목록 반환.

Returns: { "browse_type": "org" | "theme" | "view", "code": <입력 그대로>, "count": , "categories" 또는 "statistics": [...], "usage" 또는 "next_step": <안내 문구> }

Example: >>> browse_categories(by="org") >>> browse_categories(by="org", code="101") >>> browse_categories(by="theme") >>> browse_categories(by="view", code="MT_ETITLE") # 영문 KOSIS >>> browse_categories(by="view", code="MT_BUKHAN") # 북한통계

통계표의 메타데이터(구조 정보)를 조회합니다.

테이블의 분류항목, 항목, 기간 정보를 파악할 때 사용합니다. 데이터 조회 전에 어떤 필터가 가능한지 확인하는 데 유용합니다.

Args: org_id: 기관 ID (예: "101") tbl_id: 테이블 ID (예: "DT_1B040A3")

Returns: { "table_info": { "tbl_id": "DT_1B040A3", "tbl_nm": "행정구역별 인구수", "org_nm": "통계청", "prd_se": "Y", "period_range": "19922023" }, "structure": { "dimensions": [...], "dimension_count": 1, "items": [...], "item_count": 1 }, "suggested_query": { "example": "get_statistics_data('101', 'DT_1B040A3', '2019', '2023')", "available_periods": "19922023" } }

Example: >>> get_table_metadata("101", "DT_1B040A3")

데이터에서 특정 필드의 사용 가능한 값을 조회합니다.

필터링 옵션을 확인하거나, 어떤 값으로 필터링할지 결정할 때 사용합니다.

Args: data_json: KOSIS 데이터 JSON 문자열 (get_statistics_data 결과) field: 필드명 (예: "C1_NM", "PRD_DE", "ITM_NM") - C1_NM: 분류1 (보통 지역명) - PRD_DE: 기간 - ITM_NM: 항목명

Returns: { "field": "C1_NM", "field_description": "분류1 (지역/카테고리)", "count": 17, "values": ["강원도", "경기도", ...], "filter_example": "filter_statistics(data, regions='서울특별시,부산광역시')" }

Example: >>> get_available_values(data, "C1_NM")

KOSIS에서 통계 데이터를 조회합니다.

search_statistics나 get_table_metadata로 확인한 테이블의 실제 데이터를 가져옵니다.

Args: org_id: 기관 ID (예: "101") tbl_id: 테이블 ID (예: "DT_1B040A3") start_date: 시작 기간 (예: "2019", "202301") end_date: 종료 기간 (예: "2023", "202312") prd_se: 기간 유형 "Y"=연간, "M"=월간, "Q"=분기, "S"=반기 format: 응답 형식 "summary" (기본): LLM 친화적 요약 형식 (메타데이터 + 피벗 요약 + 샘플) "raw": 전체 원본 데이터 (주의: 컨텍스트 초과 가능) new_est_prd_cnt: 최근 N개 시점만 반환 (선택). KOSIS newEstPrdCnt 매핑. 예: 5 → 가장 최근 5개 기간만. start_date/end_date를 자동 제한하므로 "최근 5년만" 같은 자연어 쿼리에 직접 사용. prd_interval: 기간 stride (선택). KOSIS prdInterval 매핑. 예: prd_se="Y" + prd_interval=2 → 격년 데이터.

Returns: format="summary" (기본): { "summary": { "total_records": 850, "period_range": "2019~2023", "dimensions": ["행정구역별"], "items": ["인구수"] }, "metadata": { "tbl_id": "DT_1B040A3", "tbl_nm": "행정구역별 인구수", "org_nm": "통계청", "unit": "명" }, "pivot_summary": { "by_period": {"2019": 51849861, "2023": 51558034}, "by_c1": {"경기도": 68123456, "서울특별시": 47056789, ...} }, "data_preview": [최근 기간 샘플 50건], "available_values": { "PRD_DE": ["2019", "2020", "2021", "2022", "2023"], "C1_NM": ["서울특별시", "부산광역시", ...] } }

format="raw": 전체 API 응답 (배열 형태)

Example: >>> get_statistics_data("101", "DT_1B040A3", "2019", "2023") >>> get_statistics_data("101", "DT_1B040A3", "2019", "2023", format="raw")

통계 데이터를 필터링합니다.

서버에 저장된 데이터(data_id) 또는 직접 전달된 데이터(data_json)를 사용합니다. data_id 사용 시 LLM 컨텍스트에 데이터를 포함하지 않아 효율적입니다.

Args: regions: 포함할 지역 목록 (쉼표 구분) 예: "서울특별시,부산광역시" periods: 포함할 기간 목록 (쉼표 구분) 예: "2022,2023" items: 포함할 항목 목록 (쉼표 구분) 예: "인구수,세대수" format: 응답 형식 ("summary" 또는 "raw") data_id: 저장된 데이터 ID (get_statistics_data 결과에서 확인) data_json: KOSIS 데이터 JSON 문자열 (data_id 없을 때 사용)

Returns: JSON 문자열: 필터링된 데이터 (summary 형식이면 요약 포함)

Example: # 권장: data_id 사용 (서버에서 파일 읽음) >>> filter_statistics(regions="서울특별시,부산광역시", data_id="20231213_abc12345")

# 대안: data_json 직접 전달
>>> filter_statistics(regions="서울특별시,부산광역시", data_json=data)

통계 데이터를 그룹별로 집계합니다.

서버에 저장된 데이터(data_id) 또는 직접 전달된 데이터(data_json)를 사용합니다. data_id 사용 시 LLM 컨텍스트에 데이터를 포함하지 않아 효율적입니다.

Args: group_by: 그룹핑 필드 (쉼표로 여러 개 가능) 예: "C1_NM" 또는 "C1_NM,PRD_DE" agg_func: 집계 함수 "sum", "mean", "min", "max", "count" format: 응답 형식 ("summary" 또는 "raw") data_id: 저장된 데이터 ID (get_statistics_data 결과에서 확인) data_json: KOSIS 데이터 JSON 문자열 (data_id 없을 때 사용)

Returns: JSON 문자열: 집계된 데이터 (summary 형식이면 요약 포함)

Example: # 권장: data_id 사용 (서버에서 파일 읽음) >>> aggregate_statistics(group_by="C1_NM", data_id="20231213_abc12345")

# 대안: data_json 직접 전달
>>> aggregate_statistics(group_by="C1_NM", data_json=data)

저장된 원본 데이터 파일 목록을 조회합니다.

get_statistics_data로 조회한 대용량 데이터는 자동으로 파일에 저장됩니다. 이 도구로 저장된 파일 목록을 확인하고, read_stored_data로 접근할 수 있습니다.

Returns: { "stored_files": [ { "data_id": "20231213_abc12345", "file_path": "/tmp/kosis_data/...", "record_count": 1000, "tbl_nm": "행정구역별 인구수", "created_at": "2023-12-13T10:30:00" }, ... ], "total_files": 5, "hint": "read_stored_data(data_id)로 데이터 접근" }

Example: >>> list_stored_data()

저장된 원본 데이터를 읽습니다.

대용량 데이터는 청크 단위로 읽을 수 있습니다. chunk_index를 지정하지 않으면 전체 데이터를 반환합니다.

Args: data_id: 데이터 ID (list_stored_data 또는 get_statistics_data에서 확인) chunk_index: 청크 인덱스 (0부터 시작, 선택) chunk_size: 청크 크기 (기본 50건)

Returns: { "data_id": "20231213_abc12345", "meta": { "tbl_id": "DT_1B040A3", "tbl_nm": "행정구역별 인구수", "record_count": 1000 }, "data": [...], # 요청한 데이터 "chunk_info": { # chunk_index 지정 시 "chunk_index": 0, "chunk_size": 50, "total_chunks": 20, "has_more": True } }

Example: # 전체 데이터 읽기 >>> read_stored_data("20231213_abc12345")

# 청크별로 읽기
>>> read_stored_data("20231213_abc12345", chunk_index=0)
>>> read_stored_data("20231213_abc12345", chunk_index=1)

LLM이 생성한 숫자 주장을 KOSIS 원본 데이터와 대조 검증합니다 (US-005).

한국어/영문 자연어 주장에서 숫자 + 시점 + 지역 + 지표를 추출하여 KOSIS의 실제 셀 값과 상대 오차 비교 후 일치 여부를 반환합니다.

Args: claim: 검증할 주장 (예: "2023년 서울 인구는 9.4M명"). table_id: 알고 있는 KOSIS TBL_ID. 'org_id:tbl_id' 형식도 허용. 생략하면 키워드 검색으로 자동 추정합니다 (정확도 ↓). tolerance: 상대 허용 오차. 기본 0.01 (= 1%).

Returns: VerifyResult dict: match, expected, actual, diff_pct, tolerance, table_id, source_url, confidence, explanation.

KOSIS 통계주요지표(Key Indicator)의 설명자료를 조회합니다.

8개 KOSIS 통계주요지표 sub-service 중 설명자료 계열 두 가지를 by 인자로 구분합니다 (KOSIS dev guide §2.7).

Args: by: "id" → 지표 고유번호로 조회 (pkNumberService.do) "name" → 지표명으로 조회 (indExpService.do) value: by="id" 면 지표 ID(jipyoId), by="name" 이면 지표명(jipyoNm). page: 페이지 번호 (기본 1). limit: 페이지당 결과 수 (기본 10).

Returns: {"by": ..., "value": ..., "count": , "results": [{...}, ...]} 결과 항목은 IndicatorExplanation 의 dict 형태.

Example: >>> get_key_indicator(by="id", value="160") >>> get_key_indicator(by="name", value="실업률")

KOSIS 통계주요지표를 카테고리 또는 수록주기 기준으로 나열합니다.

Args: by: "category" → 목록ID(listId)별 지표 (indiListService.do) "period" → 수록주기(prdSe)별 지표 (prListSearchRequest.do) value: by="category" 면 listId(예: "A"). by="period" 면 prdSe(Y/M/Q/S). page: 페이지 번호. limit: 페이지당 결과 수.

Returns: {"by": ..., "value": ..., "count": , "results": [{...}, ...]}

KOSIS 통계주요지표를 이름 또는 고유번호로 검색합니다.

Args: by: "name" → 지표명별 목록 검색 (indListSearchRequest.do, service=4) "id" → 고유번호별 검색 (indListSearchRequest.do, service=4) value: by="name" 이면 지표명, by="id" 이면 jipyoId. page: 페이지 번호. limit: 페이지당 결과 수.

Returns: {"by": ..., "value": ..., "count": , "results": [{...}, ...]}

KOSIS 통계주요지표의 시계열 상세 데이터를 조회합니다.

indIdDetailSearchRequest.do (service=4 / serviceDetail=indIdDetail).

Args: jipyo_id: 지표 ID (필수). start_date / end_date: 시점 기준 조회 (예: "2020", "2023"). recent_n: 최신자료 기준으로 최근 N개 시점만. start/end 와 동시 지정 시 start/end 우선. page, limit: 페이지네이션.

Returns: {"jipyo_id": ..., "count": , "results": [{period, value, ...}]}

노출/내부 도구 전체 목록 조회.

LLM에 기본 노출되는 도구는 V1_EXPOSED 한정이지만, 모든 등록된 내부 도구는 execute_tool(name, args)로 호출할 수 있습니다.

Returns: dict with keys: exposed, internal, total, exposed_count.

이름으로 임의의 등록된 도구를 호출 (파워유저 escape hatch).

Args: name: 도구 이름 (discover_tools()로 확인 가능). args: 도구에 전달할 키워드 인자. 시그니처와 맞지 않으면 에러 반환.

Returns: {"tool": name, "result": ...} 또는 {"tool": name, "error": ...}.