List available SDMX dataflows, optionally filtered by keywords.

This is typically the first step in SDMX data discovery. Returns a list of
statistical domains (dataflows) available from the specified agency.

If you already know a country code or indicator code, consider using
find_code_usage_across_dataflows() instead — it directly discovers all
dataflows with data for that code, across all topics.

Args:
    keywords: Optional keyword string or list of keywords to filter dataflows
    agency_id: The agency to query (uses session endpoint if not specified)
    limit: Number of results to return (default: 10)
    offset: Number of results to skip for pagination (default: 0)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.
    fresh: Bypass the module-level dataflow listing cache and force a
        live re-fetch from the provider. The fetch still refreshes the
        cache for other callers. Defaults to False; use True only when
        the point of the call is to prove the provider is reachable
        right now (a cached answer would say nothing about that).

Returns:
    Structured result with dataflows, pagination info, and navigation hints

Get detailed structure information for a specific dataflow.

Returns dimensions, attributes, measures, and codelist references.
Use this after list_dataflows() to understand data organization.

Args:
    dataflow_id: The dataflow identifier
    agency_id: The agency (uses session endpoint if not specified)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Structured result with dataflow metadata and structure definition

Get codes and values for a specific codelist.

Codelists define the allowed values for dimensions (e.g., country codes, commodity codes).
Use this to find the exact codes needed for your data query.

Args:
    codelist_id: The codelist identifier
    agency_id: The agency (uses session endpoint if not specified)
    version: Version (default: "latest")
    search_term: Optional search term to filter codes
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Dictionary with codelist information and codes

Get codes for a specific dimension of a dataflow.

This allows drilling down into specific dimensions without loading all codelists at once.
Useful for finding valid values for a particular dimension in your data query.

Args:
    dataflow_id: The dataflow identifier
    dimension_id: The dimension identifier
    limit: Maximum codes to return (default: 50)
    offset: Number of codes to skip for pagination (default: 0)
    agency_id: The agency (uses session endpoint if not specified)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Structured result with codes for the dimension

Efficiently check if specific codes are actually used in a dataflow's data.

This uses the Actual ContentConstraint (if available) to determine which
codes have real data, WITHOUT iterating through data queries. This is
much faster than trial-and-error data requests.

Use cases:
- "Is country code 'FJ' actually used in DF_SDG?"
- "Which indicator codes have data?" (leave codes empty)
- "Are these 5 codes I want to use valid AND have data?"

Args:
    dataflow_id: The dataflow to check
    codes: Optional list of specific codes to check. If empty, returns all used codes.
    dimension_id: Optional dimension to check. If empty, checks all dimensions.
    agency_id: The agency (uses session endpoint if not specified)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    CodeUsageResult with:
        - codes_checked: List of codes with their usage status
        - all_used_codes: All codes that have data (by dimension)
        - summary: Counts of used/unused codes

Examples:
    >>> get_code_usage("DF_SDG", codes=["FJ", "WS", "XX"], dimension_id="GEO_PICT")
    # Checks if Fiji, Samoa, and "XX" have SDG data

    >>> get_code_usage("DF_SDG", dimension_id="INDICATOR")
    # Returns all indicator codes that actually have data

Check whether a specific time period is likely to have data in a dataflow.

Uses the Actual ContentConstraint (FREQ values + TimeRange) to quickly
rule out periods that definitely have no data, without querying the data
itself. The constraint only tells us what CAN'T exist — a "plausible"
result means "worth querying", not "guaranteed to have data".

Use after identifying a dataflow and before building a data URL.
For confirmed availability, query the data directly via build_data_url().

Three-valued result:
- "no": constraint rules this out — don't bother querying
- "plausible": period within range and frequency matches — worth trying
- "plausible_different_frequency": data exists in this time window but
  at different granularity (e.g. querying monthly but only annual exists)

Args:
    dataflow_id: The dataflow to check
    query_period: The period to check (e.g. "2010", "2010-Q1", "2010-01", "2010-W05")
    agency_id: The agency (uses session endpoint if not specified)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    TimeAvailabilityResult with availability classification and reasoning

Discover all dataflows that have data for a given code.

Use this as your starting point when exploring what data exists for a
country, indicator, or any other code. For example, to find everything
available for Fiji: find_code_usage_across_dataflows("FJ", dimension_id="GEO_PICT").
Searches all constraints in a single API call.

**When to use this tool:**
- "What datasets have data for Vanuatu?" -> code="VU", dimension_id="GEO_PICT"
- "Which dataflows cover GDP indicators?" -> code="GDP", dimension_id="INDICATOR"
- "What data exists for this country across all topics?" -> start here, then use
  compare_dataflow_dimensions() to check how the discovered dataflows relate.

**Workflow A -- search by dimension (direct):**
    find_code_usage_across_dataflows("FJ", dimension_id="GEO_PICT")
    Returns only matches where "FJ" appears in the GEO_PICT dimension.

**Workflow B -- search by codelist (two steps):**
    If you know a code belongs to a codelist (e.g., CL_COM_GEO_PICT) but
    not which dimensions use it:
    1. Call this tool WITHOUT dimension_id to get all dataflows/dimensions
       where the code appears.
    2. For each matched dataflow, call get_dataflow_structure() to inspect
       the DSD and verify which codelist each matched dimension uses.

**Provider support:** Bulk search requires endpoint support. Currently
supported by SPC (Actual), ECB (Allowed), and UNICEF (Actual). Other
endpoints will return a message explaining the limitation.

Args:
    code: The specific code to check (e.g., "FJ")
    dimension_id: Optional dimension to restrict search (e.g., "GEO_PICT").
        If provided, only matches in this dimension are returned.
        If omitted, all dimensions are searched.
    agency_id: The agency (uses session endpoint if not specified)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    CrossDataflowCodeUsageResult with:
        - dataflows_with_data: Dataflows where code is actually used
        - summary: Counts of usage

Compare dimension structures across two dataflows to understand how they relate.

Use this whenever you want to combine or contrast data from two dataflows.
Returns which dimensions are shared, whether their codes overlap, time period
coverage, and recommended join columns. Works across providers too — e.g.
compare SPC population data with UNICEF child health indicators.

**When to use this tool:**
- After discovering dataflows with find_code_usage_across_dataflows(), compare
  them to understand how they can be joined.
- When a user asks about combining datasets from different topics or providers.
- To check geographic, temporal, and dimensional overlap before writing queries.

Supports cross-provider comparison (e.g., SPC vs IMF) by specifying endpoint_a/b.
When endpoints are omitted, uses the current session endpoint.

Args:
    dataflow_id_a: First dataflow identifier
    dataflow_id_b: Second dataflow identifier
    endpoint_a: Optional endpoint key for dataflow A (e.g., "SPC", "IMF", "ECB")
    endpoint_b: Optional endpoint key for dataflow B
    ctx: MCP context

Returns:
    DataflowDimensionComparisonResult with dimension comparison, overlap stats,
    and join column recommendations

Get actual data availability for a dataflow or specific dimension combinations.

This tool is critical for avoiding empty query results. Use it to check
if data exists before building the final data URL.

Args:
    dataflow_id: The dataflow to check
    filters: Optional dict of dimension=value pairs to check
    agency_id: The agency ID
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Information about what data exists, including time ranges and suggestions

Validate SDMX query parameters before building the final URL.

Checks syntax according to SDMX 2.1 REST API specification.
Validates that dimension codes actually exist in the dataflow.

Args:
    dataflow_id: The dataflow to validate against
    key: The data key (dimensions separated by dots)
    filters: Dictionary of dimension_id -> code (alternative to key)
    start_period: Start of time range
    end_period: End of time range
    agency_id: The agency
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Validation results including any errors, warnings, and validated parameters

Build a properly formatted SDMX key from dimension values.

This helper tool constructs the key string with dimensions in the correct order
according to the dataflow structure. Unspecified dimensions are left empty
(meaning "all values").

Use this before build_data_url() to ensure your key has the correct format.

Args:
    dataflow_id: The dataflow identifier
    filters: Optional dict mapping dimension IDs to values
    agency_id: The agency (uses session endpoint if not specified)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Structured result with the constructed key and usage information

Generate final SDMX REST API URLs for data retrieval.

Creates URLs that can be used directly to download data in various formats.
This is the final step in the SDMX query construction process.

Args:
    dataflow_id: The dataflow to query
    key: The data key (use build_key() to construct), or use filters instead
    filters: Dictionary of dimension_id -> code (alternative to key)
    start_period: Start of time range (optional)
    end_period: End of time range (optional)
    format_type: Output format (csv, json, xml)
    agency_id: The agency (uses session endpoint if not specified)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Structured result with the complete data URL and usage information

Probe an exact SDMX data query and return whether it contains data.

This answers the question that validation and code-usage checks cannot:
does this exact query return observations right now?

Accepts either a complete data URL or structured parameters.
Uses lightweight probing (firstNObservations=1) to minimise payload.

Args:
    data_url: Complete SDMX data URL to probe
    dataflow_id: Dataflow ID (alternative to data_url)
    filters: Dimension filters (alternative to data_url)
    start_period: Start time period
    end_period: End time period
    agency_id: Owning agency when different from the session default.
        Required for OECD sub-agency flows (e.g. pass "OECD.STI.STP"
        alongside dataflow_id="DSD_RDS_GERD@DF_GERD_SOF"). Only consulted
        when data_url is not provided; ignored when data_url is.
    sample_observations_limit: Max sample observations to return
    max_distinct_values_per_dimension: Max distinct values per dimension summary
    timeout_ms: Probe timeout in milliseconds
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Probe result with status, observation count, shape, and sample data

Suggest nearby non-empty SDMX queries when the original returns no data.

Given an exact query that may be empty, explores bounded relaxations —
removing one filter at a time — and returns validated alternatives ranked
by minimal deviation from the original.

Args:
    data_url: The exact SDMX data URL to recover from
    relax_dimensions: Only relax these dimensions (None = try all)
    max_suggestions: Maximum number of suggestions to return
    max_probes: Maximum HTTP probes to make (budget)
    strategy: Recovery strategy (currently only least_change)
    intent_hint: One of generic, kpi, timeseries, ranking, map
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    Suggestion result with ranked non-empty alternatives

Get reference metadata for a dataflow: source, methodology, licence, caveats.

Reference metadata is the descriptive material about a dataflow rather
than its structure: who compiled it, from what source, under what licence.
Use it to explain or cite data you have retrieved.

Coverage varies by provider and the result says which channels were
available, so an empty answer can be told apart from an unanswerable one.

Args:
    dataflow_id: The dataflow to describe
    key: Optional dimension key to narrow the query. Strongly recommended
        for large dataflows: SPC's DF_SDG is 5.37 MB unfiltered and 5.6 KB
        with a partial key.
    agency_id: The agency (uses the session endpoint if not specified)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.
    ctx: MCP context

Returns:
    Reference metadata attributes, their provenance, and channel status

Use after get_reference_metadata() reports drill_down=true for an
attribute, which means more detail remains than the summary shows. This
can happen because the attribute's values differ across the dataflow (for
example recommended-uses text that differs per country), or because a
single value was identical on every row this query returned but drill_down
stays true since other rows queried differently might differ.

Args:
    dataflow_id: The dataflow to read
    attribute_id: An attribute id from get_reference_metadata()
    key: Optional dimension key to narrow the query. Strongly recommended
        for large dataflows: an unfiltered request that is too large to
        return is reported back rather than guessed at, but supplying a
        key (for example a single indicator or reference area) up front
        avoids that round trip.
    agency_id: The agency that owns the dataflow
    endpoint: Optional endpoint key for this call only

Returns:
    Every value of the attribute, each with the dimension key it applies to

Generate an SDMX-aware Mermaid diagram for any structural artifact.

The visualization adapts based on the artifact type to show the most
relevant information following the SDMX information model:

**Dataflow**: Shows full SDMX hierarchy (entry point view)
    - Dataflow → DSD → Components (Dimensions, Attributes, Measure)
    - Components → Concepts (semantic meaning from ConceptSchemes)
    - Components → Representations (Codelists or free text)

**DSD/DataStructure**: Shows component structure + relationships
    - Parent dataflows that use this DSD
    - Child codelists and concept schemes referenced

**Codelist**: Shows impact/usage view (building block)
    - Parent DSDs/dimensions that reference this codelist
    - Useful for impact analysis (what breaks if I change this?)

**ConceptScheme**: Shows usage across structures
    - Parent DSDs/components that use these concepts

Args:
    structure_type: Type of structure - one of:
        - "dataflow": Statistical data publication (shows full hierarchy)
        - "datastructure" or "dsd": Data Structure Definition
        - "codelist": Code list (enumeration of valid values)
        - "conceptscheme": Concept scheme (definitions)
        - "categoryscheme": Category scheme (classification)
    structure_id: The structure identifier
    agency_id: Agency ID (uses current endpoint's default if not specified)
    version: Version string (default "latest") - query a specific version
    direction: Relationship direction to explore (ignored for dataflow):
        - "parents": Show structures that USE this one
        - "children": Show structures this one REFERENCES
        - "both": Show both directions (default)
    show_versions: If True, display version numbers on each node
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    StructureDiagramResult with:
        - mermaid_diagram: Ready-to-render Mermaid code
        - nodes: All structures in the relationship graph
        - edges: Relationships between structures
        - interpretation: Human-readable explanation

Examples:
    >>> get_structure_diagram("dataflow", "DF_SDG")
    # Shows complete SDG dataflow structure with SDMX hierarchy

    >>> get_structure_diagram("codelist", "CL_FREQ", show_versions=True)
    # Shows what structures use CL_FREQ (impact analysis)

    >>> get_structure_diagram("dsd", "DSD_POP", direction="children")
    # Shows codelists and concept schemes used by DSD_POP

Compare two SDMX structures to identify differences.

Supports comparing different structure types with specialized logic:

**Codelists** (`structure_type="codelist"`):
- Compares actual codes (code IDs and names)
- Shows added/removed/renamed codes
- Perfect for: "What codes changed between CL_GEO v1.0 and v2.0?"

**Data Structure Definitions** (`structure_type="datastructure"`):
- Compares codelist/concept scheme references
- Shows version changes in referenced codelists
- Perfect for: "What codelists were updated in DSD v3.0?"

**Dataflows** (`structure_type="dataflow"`):
- Compares structural references (DSD, constraints)
- Perfect for: "What structures do these dataflows share?"

Args:
    structure_type: Type of structure to compare:
        - "codelist": Compare codes within codelists
        - "datastructure" or "dsd": Compare DSD references
        - "dataflow": Compare dataflow references
        - "conceptscheme": Compare concept schemes
    structure_id_a: First structure identifier
    structure_id_b: Second structure identifier (defaults to same as A for version comparison)
    version_a: Version of first structure (default "latest")
    version_b: Version of second structure (default "latest")
    agency_id: Agency ID (uses current endpoint's default if not specified)
    show_diagram: Generate a Mermaid diff diagram (default True)
    endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
        specific provider for this call only. Defaults to the session's
        current endpoint.

Returns:
    StructureComparisonResult with type-specific changes:
        - code_changes: For codelist comparisons
        - reference_changes: For DSD/dataflow comparisons
        - summary: Counts of added/removed/modified/unchanged
        - mermaid_diff_diagram: Visual diff diagram
        - interpretation: Human-readable explanation

Examples:
    # Compare two versions of a codelist - see what codes changed
    >>> compare_structures("codelist", "CL_GEO", version_a="1.0", version_b="2.0")

    # Compare two different codelists - find intersection/differences
    >>> compare_structures("codelist", "CL_FREQ", "CL_TIME_FREQ")

    # Compare DSD versions - see what codelist references changed
    >>> compare_structures("datastructure", "DSD_SDG", version_a="2.0", version_b="3.0")

    # Compare two different DSDs
    >>> compare_structures("datastructure", "DSD_SDG", "DSD_EDUCATION")

Get information about the currently active SDMX data source.

Shows which statistical organization's API is being used (e.g., Pacific Data,
European Central Bank, UNICEF).

In multi-user deployments, this returns the endpoint for the current session.

Returns:
    Current endpoint name, URL, agency ID, and description

List all available SDMX data sources that can be switched to.

Shows all configured statistical data providers (e.g., SPC, ECB, UNICEF)
and indicates which one is currently active for your session.

You don't need to switch endpoints to compare data across providers.
Use compare_dataflow_dimensions(df_a, df_b, endpoint_a="SPC", endpoint_b="ECB")
to directly compare dataflows from different providers.

In multi-user deployments, the current endpoint is session-specific.

Returns:
    List of available endpoints with their descriptions and status