scope:
- "all" (default): concepts + ECOS items + ECOS tables + international dataflows
- "concepts": country-agnostic concepts mapped across institutions (retrieve with get_data(indicator=..., country=...))
- "items": ECOS items (e.g. '쌀' rice, '휘발유' gasoline) from an index generated from the ECOS API
- "tables": ECOS tables (without query: children of the parent_code category)
- "dataflows": OECD, IMF and BIS dataflows (every word must match the English name or id; source narrows the institution)
- "key_statistics": latest values of the Bank of Korea's 100 key statistics

Args:
    query: search terms (e.g. "policy rate", "unemployment", "inflation", "물가")
    scope: "all" | "concepts" | "items" | "tables" | "dataflows" | "key_statistics"
    source: institution for dataflow search (OECD | IMF | BIS)
    parent_code: ECOS table category code
    searchable_only: ECOS tables that can be queried only
    limit: maximum results per category
    language: language of key_statistics ("kr" | "en")

Returns:
    results per category (concepts, items, tables, dataflows, key_statistics)

- OECD, IMF, BIS: source + dataflow → the dimensions and codelists of the institution's own DSD.
  A series key is the codes joined with '.' in dimension order (e.g. BIS WS_CBPOL → 'M.US').
- ECOS: stat_code → the table's structure mapped to SDMX (FREQ + ITEM_CODE1..4, coverage, units).
  output_format="sdmx" returns an SDMX-JSON structure message.

Args:
    stat_code: ECOS table code (e.g. "901Y009")
    source: OECD | IMF | BIS (with dataflow)
    dataflow: SDMX dataflow (e.g. "BIS:WS_CBPOL(1.0)", "IMF.STA:CPI")
    code_keyword: filter codes by name or value (e.g. "Japan", "JPN", "current account")
    codes_limit: maximum codes per dimension (default 30)
    output_format: "compact" | "sdmx" (ECOS only)
    language: "kr" | "en" (ECOS names)

Returns:
    dimensions, codes per dimension, a key template

Three ways to ask (use one):
1. Concept: indicator + country (+ source, cycle), e.g. indicator="CPI_YOY", country="US".
   Korea uses ECOS first; other economies OECD, IMF and BIS. If a source has no data, the next one is tried.
2. ECOS table (Korea): stat_code (+ cycle, item_code1..4)
3. SDMX dataflow: source (OECD | IMF | BIS) + dataflow + key + cycle

* validation: country, frequency, unit (and index base), scale, period, missing, duplicate and revision checks (pass/info/warn/fail)
* cross_validate=True: fetch the concept from every source and compare period by period;
  the result is MATCH, DIFFER (documented cause) or UNRESOLVED (unexplained difference)
* dates: "2024", "2024-03", "2024Q1", "2024-03-15" are converted; default window 3 months for daily data, else 2 years
* transform: "yoy" / "pop" % change — value becomes the change and the level is kept
* rebase_period: rebase an index to that period = 100 (e.g. "2020")

Args:
    indicator: concept id or name (see search_statistics(scope="concepts"))
    country: economy, ISO code or EA (required with indicator; with a direct SDMX query it enables the country check)
    source: ECOS | OECD | IMF | BIS
    stat_code: ECOS table code
    cycle: frequency A/S/Q/M/SM/D
    item_code1..4: ECOS item codes
    dataflow: SDMX dataflow (e.g. "OECD.SDD.STES:DSD_STES@DF_FINMARK(4.0)")
    key: SDMX series key (e.g. "USA.M.IRLT.PA._Z._Z._Z._Z.N")
    start_date: start period
    end_date: end period
    recent_years: window when dates are omitted
    transform: "yoy" | "pop" | "none"
    changes_only: only periods where the value changed (default for policy rates)
    rebase_period: index rebase period
    unit_mult: rescale values to 10^unit_mult (e.g. 12 turns a billions (9) series into trillions)
    cross_validate: include cross-validation across institutions
    output_format: "compact" | "csv" | "json" | "sdmx"
    prefer_latest: when ECOS results are truncated, keep the latest periods
    start_count: ECOS first row
    end_count: ECOS last row
    language: "kr" | "en" (ECOS names)

Returns:
    series (periods and values), provenance (source and citation), validation, and optionally cross_validation

Examples:
- economies: [{"indicator":"POLICY_RATE","country":"US"}, {"indicator":"POLICY_RATE","country":"EA"}]
- institutions: [{"indicator":"CPI","country":"CN","source":"IMF"}, {"indicator":"CPI","country":"CN","source":"BIS"}]
  → the same concept and economy from different institutions adds cross_validation automatically
- concepts: [{"indicator":"POLICY_RATE","country":"GB"}, {"indicator":"CPI_YOY","country":"GB"}]

Args:
    series: list of series (indicator/country/source, or stat_code/..., or source/dataflow/key/cycle)
    start_date: start period (default: the last recent_years years)
    end_date: end period
    recent_years: window (default 3)
    frequency: comparison frequency (default: the lowest one)
    aggregation: "mean" | "last" | "first" | "sum" (default per concept: flows such as the current account
        or GDP are summed, stocks such as reserves take the period end, everything else is averaged)
    normalize_method: "none" | "index" (first period = 100) | "zscore"
    join: "inner" | "outer"
    output_format: "compact" | "csv"

Returns:
    the aligned table, correlations, provenance and validation per series, and cross-validation where it applies

Per series: count, first/last, min/max (with periods), mean, median, std, change/change_pct, cagr_pct,
trend_per_year/trend_r2, latest_pop_pct, pop_pct_std, max_drawdown_pct, latest_yoy_pct, mean_yoy_pct.
Rates (interest rates, inflation) change in percentage points. Validation and provenance are included.

Args:
    indicator: concept id or name
    country: economy, ISO code or EA (required with indicator)
    source: ECOS | OECD | IMF | BIS
    stat_code: ECOS table code
    cycle: frequency
    item_code1..4: ECOS item codes
    dataflow: SDMX dataflow
    key: SDMX series key
    start_date: start period
    end_date: end period
    recent_years: window

Returns:
    statistics, validation status and provenance per series

Returns the concept definition, its source mappings with rendered keys, and for Korean statistics the
Bank of Korea glossary definition, methodology notes and related ECOS tables.

Args:
    term: indicator or term (e.g. "CPI_YOY", "policy rate", "unemployment", "경제심리지수")
    country: economy whose sources to show (default: every verified economy)
    stat_code: a specific ECOS table to explain
    language: "kr" | "en" (Bank of Korea glossary and methodology)

Returns:
    concept (definition, unit, sources), sources per economy, definition (glossary), methodology, tables