#!/usr/bin/env python
# Copyright Salient Predictions 2026

"""Auto-generated type definitions from the Salient API OpenAPI schema.

DO NOT EDIT THIS FILE MANUALLY.

Regenerate with: poetry run python -m salientsdk.schema
Generated: 2026-02-17T17:12:48Z
"""

from typing import Literal

# ======================================================================
# data_timeseries
# Return a historical timeseries for chosen coordinates including information about the average climatological cycle.
# ======================================================================

DataTimeseriesField = Literal[
    "all",
    "anom",
    "anom_d",
    "anom_ds",
    "anom_qnt",
    "anom_s",
    "clim",
    "stdv",
    "trend",
    "vals",
]
"""data_timeseries field options.

Field to plot.
If returning a csv, clim returns only information about the climatological cycle, while vals or anom will return a historical timeseries since 1950.

- `anom`: Total anomaly: departure from climatological normal (vals - clim).
- `anom_d`: Detrended anomaly component: anomaly with trend removed.
- `anom_ds`: Detrended and destandardized anomaly: normalized anomaly signal.
- `anom_qnt`: Anomaly expressed as a quantile (0-1) relative to historical distribution.
- `anom_s`: Standardized anomaly: anomaly divided by climatological standard deviation.
- `clim`: Climatological mean: long-term average for each day/week/month of the year.
- `stdv`: Climatological standard deviation: historical variability for each period.
- `trend`: Linear trend component: long-term directional change in the variable.
- `vals`: Raw ERA5 reanalysis values in absolute units.
- `all`: Returns all available fields.
"""

DataTimeseriesFormat = Literal["csv", "nc"]
"""data_timeseries format options.

File format of the returned data.

- `nc`: NetCDF4 binary format. Optimized for geospatial analysis with xarray.
- `csv`: Comma-Separated Values text format. Suitable for Pandas tables, spreadsheets, databases, and LLMs.
"""

DataTimeseriesFrequency = Literal["3-monthly", "daily", "hourly", "monthly", "weekly"]
"""data_timeseries frequency options.

Temporal resolution of historical values.

- `hourly`: Hourly values.
- `daily`: Daily averages.
- `weekly`: Calendar-locked weekly aggregated values (Monday-Sunday).
- `monthly`: Calendar-locked monthly aggregated values.
- `3-monthly`: 3-month (quarterly/seasonal) aggregated values.
"""

DataTimeseriesUnits = Literal["SI", "US"]
"""data_timeseries units options.

Unit system for returned data.

- `SI`: Metric: °C for temperature, mm/day for precipitation, m/s for wind speed, etc.
- `US`: Imperial: °F for temperature, in/day for precipitation, mph for wind speed, etc.
"""

DataTimeseriesVariable = Literal[
    "cc",
    "cdd",
    "dewpoint",
    "dhi",
    "dni",
    "evap",
    "hdd",
    "hgt10",
    "hgt250",
    "hgt500",
    "mslp",
    "olr",
    "precip",
    "rh",
    "si",
    "sm",
    "snow",
    "sss",
    "sst",
    "st",
    "temp",
    "tmax",
    "tmin",
    "tsi",
    "wdir",
    "wdir100",
    "wgst",
    "wpow",
    "wspd",
    "wspd100",
]
"""data_timeseries variable options.

Forecast variable.

- `cc`: Cloud cover fraction (0-1).
- `cdd`: Cooling degree days (°C | °F). Cumulative measure of warm conditions requiring cooling.
- `dewpoint`: 2-meter dewpoint temperature (°C | °F).
- `evap`: Evaporation (mm/day). Negative values indicate evaporation, positive indicate condensation.
- `hdd`: Heating degree days (°C | °F). Cumulative measure of cold conditions requiring heating.
- `hgt10`: Geopotential height at 10 hPa (m | ft).
- `hgt250`: Geopotential height at 250 hPa (m | ft).
- `hgt500`: Geopotential height at 500 hPa (m | ft). Atmospheric pressure level indicator.
- `mslp`: Mean sea level pressure (mbar).
- `olr`: Outgoing longwave radiation (W/m²).
- `precip`: Total precipitation (mm/day | in/day). Liquid and frozen water equivalent.
- `rh`: Relative humidity (0-1). Ratio of actual to saturation vapor pressure.
- `si`: Sea ice cover fraction (0-1).
- `sm`: Soil moisture in upper 10 cm (m³/m³). Volumetric water content.
- `snow`: Snow depth (m water equivalent).
- `sss`: Sea surface salinity (psu).
- `sst`: Sea surface temperature (°C | °F).
- `st`: Soil temperature in upper 10 cm (°C | °F).
- `temp`: 2-meter air temperature (°C | °F). Average temperature forecast.
- `tmax`: Daily maximum 2-meter temperature (°C | °F).
- `tmin`: Daily minimum 2-meter temperature (°C | °F).
- `tsi`: Total solar irradiance / insolation (W/m² hourly | kWh/m²/day daily).
- `wdir`: 10-meter wind direction (degrees). True direction from which wind is blowing.
- `wdir100`: 100-meter wind direction (degrees). True direction from which wind is blowing.
- `wgst`: Maximum 10-meter wind gust (m/s | mph).
- `wpow`: Wind power density at 10 meters (W/m²).
- `wspd`: 10-meter wind speed (m/s | mph).
- `wspd100`: 100-meter wind speed (m/s | mph). Useful for wind energy applications.
- `dhi`: Diffuse horizontal irradiance (W/m²). Solar radiation from the sky excluding direct sunlight.
- `dni`: Direct normal irradiance (W/m²). Direct solar radiation perpendicular to surface.
"""

DataTimeseriesWeights = Literal["equal", "population", "solar_capacity", "wind_capacity"]
"""data_timeseries weights options.

Weighting scheme used to aggregate data across grid points within a `shapefile` region.
If unspecified, no weighted mean will be calculated and the function will return values for all available gridpoints in the polygon.

- `population`: Weight each grid point by population. Useful when calculating heating/cooling demand.
- `equal`: Each grid point within the shapefile receives uniform weight.
- `wind_capacity`: Weight each grid point by total nameplate capacity of wind turbines. USA only.
- `solar_capacity`: Weight each grid point by total nameplate capacity of grid-scale solar resources. Does not include smaller residential solar. USA only.
"""

# ======================================================================
# downscale
# Return a realistic synthetic ensemble of temporally downscaled forecast data,
# ======================================================================

DownscaleFormat = Literal["nc"]
"""downscale format options.

File format of the returned data.

- `nc`: NetCDF4 binary format. Optimized for geospatial analysis with xarray.
"""

DownscaleFrequency = Literal["daily", "hourly"]
"""downscale frequency options.

Temporal resolution of downscaled forecast values.

- `daily`: Daily downscaled values.
- `hourly`: Hourly downscaled values.
"""

DownscaleModel = Literal["blend"]
"""downscale model options.

Forecast model.
"""

DownscaleReferenceClim = Literal["10_yr", "30_yr", "5_yr", "salient"]
"""downscale reference_clim options.

Reference climatology period used to calculate forecast anomalies, tercile boundaries, and skill score baselines.

- `salient`: Salient Climatology: Salient's proprietary climatological reference optimized for anomaly calculations and tercile boundaries. Provides the most accurate baseline for evaluating Salient forecast skill.
- `30_yr`: 30-year Climatology (1991-2020): NOAA's standard 30-year historical average with temporal smoothing. Updated every 10 years following scientific convention. Use this for anomaly calculations that match climatological forecast models.
- `10_yr`: 10-year Normal: Rolling 10-year straight average, updated annually. Captures more recent climate trends and variability. Useful for benchmarking forecast skill against recent climate conditions.
- `5_yr`: 5-year Normal: Rolling 5-year straight average, updated annually. Most responsive to recent climate change and short-term trends. Best for applications requiring the most current climate baseline.
"""

DownscaleUnits = Literal["SI", "US"]
"""downscale units options.

Unit system for returned data.

- `SI`: Metric: °C for temperature, mm/day for precipitation, m/s for wind speed, etc.
- `US`: Imperial: °F for temperature, in/day for precipitation, mph for wind speed, etc.
"""

DownscaleVariables = Literal[
    "cc",
    "cdd",
    "dewpoint",
    "dhi",
    "dhi",
    "dni",
    "dni",
    "evap",
    "gdd",
    "hdd",
    "heat_index",
    "hgt10",
    "hgt250",
    "hgt500",
    "mslp",
    "olr",
    "precip",
    "rh",
    "si",
    "sm",
    "snow",
    "sp",
    "sss",
    "sst",
    "st",
    "temp",
    "tmax",
    "tmin",
    "tsi",
    "wdir",
    "wdir100",
    "wgst",
    "wind_chill",
    "wpow",
    "wspd",
    "wspd100",
]
"""downscale variables options.

Forecast variable.

- `cdd`: Cooling degree days (°C | °F). Cumulative measure of warm conditions requiring cooling.
- `hdd`: Heating degree days (°C | °F). Cumulative measure of cold conditions requiring heating.
- `mslp`: Mean sea level pressure (mbar).
- `precip`: Total precipitation (mm/day | in/day). Liquid and frozen water equivalent.
- `rh`: Relative humidity (0-1). Ratio of actual to saturation vapor pressure.
- `sm`: Soil moisture in upper 10 cm (m³/m³). Volumetric water content.
- `snow`: Snow depth (m water equivalent).
- `st`: Soil temperature in upper 10 cm (°C | °F).
- `temp`: 2-meter air temperature (°C | °F). Average temperature forecast.
- `tsi`: Total solar irradiance / insolation (W/m² hourly | kWh/m²/day daily).
- `wdir`: 10-meter wind direction (degrees). True direction from which wind is blowing.
- `wdir100`: 100-meter wind direction (degrees). True direction from which wind is blowing.
- `wgst`: Maximum 10-meter wind gust (m/s | mph).
- `wpow`: Wind power density at 10 meters (W/m²).
- `wspd`: 10-meter wind speed (m/s | mph).
- `wspd100`: 100-meter wind speed (m/s | mph). Useful for wind energy applications.
- `dewpoint`: 2-meter dewpoint temperature (°C | °F).
- `hgt10`: Geopotential height at 10 hPa (m | ft).
- `hgt500`: Geopotential height at 500 hPa (m | ft). Atmospheric pressure level indicator.
- `olr`: Outgoing longwave radiation (W/m²).
- `tmax`: Daily maximum 2-meter temperature (°C | °F).
- `tmin`: Daily minimum 2-meter temperature (°C | °F).
- `cc`: Cloud cover fraction (0-1).
- `dni`: Direct normal irradiance (W/m²). Direct solar radiation perpendicular to surface.
- `dhi`: Diffuse horizontal irradiance (W/m²). Solar radiation from the sky excluding direct sunlight.
- `heat_index`: Heat index at 2 meters (°C | °F). Apparent temperature combining heat and humidity.
- `wind_chill`: Wind chill at 2 meters (°C | °F). Apparent temperature combining cold and wind.
- `evap`: Evaporation (mm/day). Negative values indicate evaporation, positive indicate condensation.
- `hgt250`: Geopotential height at 250 hPa (m | ft).
- `si`: Sea ice cover fraction (0-1).
- `sss`: Sea surface salinity (psu).
- `sst`: Sea surface temperature (°C | °F).
- `gdd`: Growing degree days. Measure of heat accumulation for agricultural applications.
- `dhi`: Diffuse horizontal irradiance (W/m²). Solar radiation from the sky excluding direct sunlight.
- `dni`: Direct normal irradiance (W/m²). Direct solar radiation perpendicular to surface.
"""

DownscaleWeights = Literal["equal", "population", "solar_capacity", "wind_capacity"]
"""downscale weights options.

Weighting scheme used to aggregate data across grid points within a `shapefile` region.
If unspecified, no weighted mean will be calculated and the function will return values for all available gridpoints in the polygon.

- `population`: Weight each grid point by population. Useful when calculating heating/cooling demand.
- `equal`: Each grid point within the shapefile receives uniform weight.
- `wind_capacity`: Weight each grid point by total nameplate capacity of wind turbines. USA only.
- `solar_capacity`: Weight each grid point by total nameplate capacity of grid-scale solar resources. Does not include smaller residential solar. USA only.
"""

# ======================================================================
# files
# Returns the list of location_files, shapefiles, and custom_quantities available to the account.
# ======================================================================

FilesType = Literal["derived", "location"]
"""files type options.

Type of custom files to retrieve.

- `location`: Returns a JSON structure with keys `shapefiles` and `coordinates`, listing `shapefile`s and `location_file`s respectively.
- `derived`: Returns all user-defined `custom_quantity` names.
"""

# ======================================================================
# forecast_timeseries
# Return a timeseries of forecast probability quantiles or ensembles.
# ======================================================================

ForecastTimeseriesField = Literal["anom", "anom_ens", "terciles", "vals", "vals_ens"]
"""forecast_timeseries field options.

Type of data to return, typically a quantile-based probability distribution or a set of ensemble trajectories.
N=31 to 300, depending on model.

- `vals`: Probability quantiles of forecast values in absolute units.
- `anom`: Probability quantiles representing the departure from climatological normal.
- `vals_ens`: Ensemble trajectories in absolute units.
- `anom_ens`: Ensemble trajectories representing departure from climatological normal.
- `terciles`: Tercile categories indicating above-normal, near-normal, or below-normal conditions.
"""

ForecastTimeseriesFormat = Literal["csv", "nc"]
"""forecast_timeseries format options.

File format of the returned data.

- `nc`: NetCDF4 binary format. Optimized for geospatial analysis with xarray.
- `csv`: Comma-Separated Values text format. Suitable for Pandas tables, spreadsheets, databases, and LLMs.
"""

ForecastTimeseriesModel = Literal[
    "blend",
    "clim",
    "ecmwf",
    "ecmwf_ens",
    "ecmwf_ens15",
    "ecmwf_ens_calib",
    "ecmwf_seas5",
    "ecmwf_seas5_calib",
    "gem",
    "gfs",
    "noaa_gefs",
    "noaa_gefs_calib",
    "noaa_gfs",
    "norm_10yr",
    "norm_5yr",
    "salient_clim",
]
"""forecast_timeseries model options.

Forecast model.

- `clim`: Climatological forecasts: Probabilistic distributions characterizing uncertainty around calculated climatological means based on historical climate patterns.
- `gfs`: Generic reference to NOAA GFS models. See `noaa_gfs` for details.
- `ecmwf`: Generic reference to ECMWF models. See `ecmwf_ens` and `ecmwf_seas5` for specific model details.
- `blend`: Salient Blend: Proprietary multi-model ensemble that objectively combines Salient's AI models with properly calibrated dynamical models (GEFS and ECMWF). Available as probability distributions for weekly through quarterly timescales. Use `downscale` for daily ensembles.
- `gem`: Salient GemAI: Generative AI model. Produces native daily ensemble trajectories for days 1-126 ahead, aggregating to coarser timescales and probability distributions.
- `salient_clim`: Salient's proprietary climatological model providing full probabilistic distributions with enhanced uncertainty characterization.
- `norm_5yr`: 5-year rolling climatological normal calculated from the most recent 5 years of observations.
- `norm_10yr`: 10-year rolling climatological normal calculated from the most recent 10 years of observations.
- `noaa_gfs`: NOAA GFS - Global Forecast System: single-member weather model providing hourly forecasts for hours 1-120 (~5 days).
- `noaa_gefs`: NOAA GEFS - Global Ensemble Forecast System: 31-member ensemble providing probabilistic forecasts for days 1-35.
- `noaa_gefs_calib`: Calibrated NOAA GEFS: GEFS ensemble with statistical post-processing to reduce systematic biases and improve reliability.
- `ecmwf_ens`: ECMWF ENS - Extended Range: European Centre ensemble model providing 101 ensemble members for 46 days of forecasts.
- `ecmwf_ens_calib`: Calibrated ECMWF ENS Extended Range: ECMWF ensemble with statistical calibration to improve forecast reliability and reduce biases.
- `ecmwf_seas5`: ECMWF SEAS5 - Seasonal forecast system: Ensemble covering months 1-3 and quarters 1-2
- `ecmwf_seas5_calib`: Calibrated ECMWF SEAS5: ECMWF seasonal model with post-processing for improved skill and reliability at seasonal timescales.
- `ecmwf_ens15`: ECMWF 15-day forecast
"""

ForecastTimeseriesReferenceClim = Literal["10_yr", "30_yr", "5_yr", "salient"]
"""forecast_timeseries reference_clim options.

Reference climatology period used to calculate forecast anomalies, tercile boundaries, and skill score baselines.

- `salient`: Salient Climatology: Salient's proprietary climatological reference optimized for anomaly calculations and tercile boundaries. Provides the most accurate baseline for evaluating Salient forecast skill.
- `30_yr`: 30-year Climatology (1991-2020): NOAA's standard 30-year historical average with temporal smoothing. Updated every 10 years following scientific convention. Use this for anomaly calculations that match climatological forecast models.
- `10_yr`: 10-year Normal: Rolling 10-year straight average, updated annually. Captures more recent climate trends and variability. Useful for benchmarking forecast skill against recent climate conditions.
- `5_yr`: 5-year Normal: Rolling 5-year straight average, updated annually. Most responsive to recent climate change and short-term trends. Best for applications requiring the most current climate baseline.
"""

ForecastTimeseriesTimescale = Literal[
    "all",
    "daily",
    "hourly",
    "long-range",
    "monthly",
    "quarterly",
    "seasonal",
    "sub-seasonal",
    "weekly",
]
"""forecast_timeseries timescale options.

Temporal resolution and lookahead range of the forecast.

- `all`: Returns all available timescales for the selected model. Timescale availability varies by model.
- `hourly`: NOAA GFS hourly resolution covers hours 1-120 (~5 days) and initializes at 00z/06z/12z/18z.
- `daily`: Day-by-day ensemble forecasts, 15/35/46/126 days into the future (depending on model). Updates daily.
- `sub-seasonal`: Rolling weekly forecasts covering weeks 1-5 ahead of forecast_date. Updates daily.
- `seasonal`: Rolling monthly forecasts covering 3x30 day periods ahead of forecast_date. Updates daily or weekly depending on model.
- `long-range`: Rolling quarterly forecasts covering quarters 1-4 ahead for 12 months of predictability. Updates monthly on the 15th for the `blend` model.
- `weekly`: Calendar-aligned weekly forecasts covering weeks 1-4 or 5, starting each Monday and ending Sunday.
- `monthly`: Calendar-aligned monthly forecasts covering 2-3 calendar months ahead, starting on day 1 of the month.
- `quarterly`: Calendar-aligned seasonal forecasts covering seasons 1-3 or 4 (e.g., DJF, MAM, JJA, SON).
"""

ForecastTimeseriesUnits = Literal["SI", "US"]
"""forecast_timeseries units options.

Unit system for returned data.

- `SI`: Metric: °C for temperature, mm/day for precipitation, m/s for wind speed, etc.
- `US`: Imperial: °F for temperature, in/day for precipitation, mph for wind speed, etc.
"""

ForecastTimeseriesVariable = Literal[
    "cc",
    "cdd",
    "dewpoint",
    "dhi",
    "dni",
    "evap",
    "hdd",
    "heat_index",
    "hgt10",
    "hgt250",
    "hgt500",
    "mslp",
    "olr",
    "precip",
    "rh",
    "si",
    "sm",
    "snow",
    "sp",
    "sss",
    "sst",
    "st",
    "temp",
    "tmax",
    "tmin",
    "tsi",
    "wdir",
    "wdir100",
    "wgst",
    "wind_chill",
    "wpow",
    "wspd",
    "wspd100",
]
"""forecast_timeseries variable options.

Forecast variable.

- `cdd`: Cooling degree days (°C | °F). Cumulative measure of warm conditions requiring cooling.
- `hdd`: Heating degree days (°C | °F). Cumulative measure of cold conditions requiring heating.
- `mslp`: Mean sea level pressure (mbar).
- `precip`: Total precipitation (mm/day | in/day). Liquid and frozen water equivalent.
- `rh`: Relative humidity (0-1). Ratio of actual to saturation vapor pressure.
- `sm`: Soil moisture in upper 10 cm (m³/m³). Volumetric water content.
- `snow`: Snow depth (m water equivalent).
- `st`: Soil temperature in upper 10 cm (°C | °F).
- `temp`: 2-meter air temperature (°C | °F). Average temperature forecast.
- `tsi`: Total solar irradiance / insolation (W/m² hourly | kWh/m²/day daily).
- `wdir`: 10-meter wind direction (degrees). True direction from which wind is blowing.
- `wdir100`: 100-meter wind direction (degrees). True direction from which wind is blowing.
- `wgst`: Maximum 10-meter wind gust (m/s | mph).
- `wpow`: Wind power density at 10 meters (W/m²).
- `wspd`: 10-meter wind speed (m/s | mph).
- `wspd100`: 100-meter wind speed (m/s | mph). Useful for wind energy applications.
- `dewpoint`: 2-meter dewpoint temperature (°C | °F).
- `hgt10`: Geopotential height at 10 hPa (m | ft).
- `hgt500`: Geopotential height at 500 hPa (m | ft). Atmospheric pressure level indicator.
- `olr`: Outgoing longwave radiation (W/m²).
- `tmax`: Daily maximum 2-meter temperature (°C | °F).
- `tmin`: Daily minimum 2-meter temperature (°C | °F).
- `cc`: Cloud cover fraction (0-1).
- `dni`: Direct normal irradiance (W/m²). Direct solar radiation perpendicular to surface.
- `dhi`: Diffuse horizontal irradiance (W/m²). Solar radiation from the sky excluding direct sunlight.
- `heat_index`: Heat index at 2 meters (°C | °F). Apparent temperature combining heat and humidity.
- `wind_chill`: Wind chill at 2 meters (°C | °F). Apparent temperature combining cold and wind.
- `evap`: Evaporation (mm/day). Negative values indicate evaporation, positive indicate condensation.
- `hgt250`: Geopotential height at 250 hPa (m | ft).
- `si`: Sea ice cover fraction (0-1).
- `sss`: Sea surface salinity (psu).
- `sst`: Sea surface temperature (°C | °F).
"""

ForecastTimeseriesWeights = Literal["equal", "population", "solar_capacity", "wind_capacity"]
"""forecast_timeseries weights options.

Weighting scheme used to aggregate data across grid points within a `shapefile` region.
If unspecified, no weighted mean will be calculated and the function will return values for all available gridpoints in the polygon.

- `population`: Weight each grid point by population. Useful when calculating heating/cooling demand.
- `equal`: Each grid point within the shapefile receives uniform weight.
- `wind_capacity`: Weight each grid point by total nameplate capacity of wind turbines. USA only.
- `solar_capacity`: Weight each grid point by total nameplate capacity of grid-scale solar resources. Does not include smaller residential solar. USA only.
"""

# ======================================================================
# geo
# Return xarray.Dataset of static geographical data.
# ======================================================================

GeoFormat = Literal["csv", "nc"]
"""geo format options.

File format of the returned data.

- `csv`: Comma-Separated Values text format. Suitable for Pandas tables, spreadsheets, databases, and LLMs.
- `nc`: NetCDF4 binary format. Optimized for geospatial analysis with xarray.
"""

GeoResolution = Literal[0.0625, 0.125, 0.25]
"""geo resolution options.

Spatial resolution of extracted geodata in the polygon, when used with `shapefile`.

- `0.25`: 0.25° (~28 km). Native ERA5 resolution.
- `0.125`: 0.125° (~14 km). 2x oversampled.
- `0.0625`: 0.0625° (~7 km). 4x oversampled.
"""

GeoVariables = Literal[
    "bdod",
    "cec",
    "cfvo",
    "clay",
    "elevation",
    "fal",
    "lai_hv",
    "lai_lv",
    "lulc_bgc",
    "lulc_bgc_per",
    "lulc_igbp",
    "lulc_igbp_per",
    "lulc_lai",
    "lulc_lai_per",
    "lulc_land_water",
    "lulc_land_water_per",
    "lulc_lccs_cover",
    "lulc_lccs_cover_per",
    "lulc_lccs_hydro",
    "lulc_lccs_hydro_per",
    "lulc_lccs_use",
    "lulc_lccs_use_per",
    "lulc_pft",
    "lulc_pft_per",
    "lulc_umd",
    "lulc_umd_per",
    "nitrogen",
    "ocd",
    "ocs",
    "phh2o",
    "pop_density",
    "population",
    "sand",
    "silt",
    "slope",
    "soc",
    "solar_capacity",
    "solar_capacity_0_axis",
    "solar_capacity_1_axis",
    "solar_capacity_2_axis",
    "wind_capacity",
    "wind_elev",
    "wind_hub_height",
    "wind_turbine_ct",
    "wv0010",
    "wv0033",
    "wv1500",
]
"""geo variables options.

Comma-separated list of geospatial variables to extract from the GeoData Archive.

- `bdod`: Bulk Density (Oven Dry) (g cm**-3).
- `cec`: Cation exchange capacity of the soil (meq 100g**-1).
- `cfvo`: Volumetric fraction of coarse fragments (> 2 mm) (cm3 100**cm-3 (% vol)).
- `clay`: Proportion of clay particles (< 0.002 mm) in the fine earth fraction (g 100g**-1 (% wt)).
- `elevation`: Elevation (m).
- `fal`: Forecast albedo ((0 - 1)).
- `lai_hv`: Leaf area index high vegetation (m**2 m**-2).
- `lai_lv`: Leaf area index low vegetation (m**2 m**-2).
- `lulc_bgc`: BGC Land Cover Class (unitless).
- `lulc_bgc_per`: Percent BGC Land Cover Class (percent).
- `lulc_igbp`: IGBP Land Cover Class (unitless).
- `lulc_igbp_per`: Percent IGBP Land Cover Class (percent).
- `lulc_lai`: LAI Land Cover Class (unitless).
- `lulc_lai_per`: Percent LAI Land Cover Class (percent).
- `lulc_land_water`: MOD44W Land/Water Classes (unitless).
- `lulc_land_water_per`: Percent MOD44W Land/Water Classes (percent).
- `lulc_lccs_cover`: FAO-LCCS Land Cover Class (unitless).
- `lulc_lccs_cover_per`: Percent FAO-LCCS Land Cover Class (percent).
- `lulc_lccs_hydro`: FAO-LCCS Surface Hydrology Class (unitless).
- `lulc_lccs_hydro_per`: Percent FAO-LCCS Surface Hydrology Class (percent).
- `lulc_lccs_use`: FAO-LCCS Land Use Class (unitless).
- `lulc_lccs_use_per`: Percent FAO-LCCS Land Use Class (percent).
- `lulc_pft`: PFT Land Cover Class (unitless).
- `lulc_pft_per`: Percent PFT Land Cover Class (percent).
- `lulc_umd`: UMD Land Cover Class (unitless).
- `lulc_umd_per`: Percent UMD Land Cover Class (percent).
- `nitrogen`: Total nitrogen (g kg**-1).
- `ocd`: Organic carbon density (kg m**3).
- `ocs`: Organic carbon stocks (kg m**2).
- `phh2o`: Soil pH measured in a soil-water solution (pH).
- `pop_density`: Population Density (persons km**-2).
- `population`: Population (persons).
- `sand`: Proportion of sand particles (> 0.05/0.063 mm) in the fine earth fraction (g 100g**-1 (% wt)).
- `silt`: Proportion of silt particles (≥ 0.002 mm and ≤ 0.05/0.063 mm) in the fine earth fraction (g 100g**-1 (% wt)).
- `slope`: Slope (percent).
- `soc`: Soil organic carbon content in the fine earth fraction (g kg**-1).
- `solar_capacity`: Total nameplate capacity of solar resources in each grid cell (MW).
- `solar_capacity_0_axis`: Total nameplate capacity of fixed-axis solar resources in each grid cell (MW).
- `solar_capacity_1_axis`: Total nameplate capacity of single-axis tracker solar resources in each grid cell (MW).
- `solar_capacity_2_axis`: Total nameplate capacity of two-axis tracker solar resources in each grid cell (MW).
- `wind_capacity`: Total nameplate capacity of wind turbines in each grid cell (MW).
- `wind_elev`: Capacity-weighted mean elevation of turbine locations (m).
- `wind_hub_height`: Capacity-weighted mean turbine hub height (m).
- `wind_turbine_ct`: Number of wind turbines in each grid cell (#).
- `wv0010`: Volumetric water content at 10kPa suction (cm**3 100cm**-3 (% vol)).
- `wv0033`: Volumetric water content at 33kPa suction (cm**3 100cm**-3 (% vol)).
- `wv1500`: Volumetric water content at 1500kPa suction (cm**3 100cm**-3 (% vol)).
"""

# ======================================================================
# hindcast_summary
# Return summary of accuracy metrics for a given region over the entire backtesting period.
# ======================================================================

HindcastSummaryFormat = Literal["csv"]
"""hindcast_summary format options.

File format of the returned data.

- `csv`: Comma-Separated Values text format. Suitable for Pandas tables, spreadsheets, databases, and LLMs.
"""

HindcastSummaryInterpMethod = Literal["linear", "nearest"]
"""hindcast_summary interp_method options.

Interpolation method to use for the requested data not on native grid points.

- `nearest`: Nearest neighbor interpolation. Returns the value from the closest grid point.
- `linear`: Bilinear interpolation. Weighted average of surrounding grid points.
"""

HindcastSummaryMetric = Literal[
    "crps",
    "crps_skill_score",
    "mae",
    "mae_skill_score",
    "rps",
    "rps_skill_score",
]
"""hindcast_summary metric options.

Forecast skill score metric.

- `crps`: Continuous Ranked Probability Score. Measures probabilistic forecast accuracy for continuous variables.
- `rps`: Ranked Probability Score. Measures probabilistic forecast accuracy for categorical outcomes.
- `mae`: Mean Absolute Error. Average magnitude of forecast errors.
- `crps_skill_score`: CRPS Skill Score. CRPS improvement relative to `reference` model (1 = perfect, 0 = no improvement, negative = worse).
- `rps_skill_score`: RPS Skill Score. RPS improvement relative to `reference` model (1 = perfect, 0 = no improvement, negative = worse).
- `mae_skill_score`: MAE Skill Score. MAE improvement relative to `reference` model (1 = perfect, 0 = no improvement, negative = worse).
"""

HindcastSummaryModel = Literal[
    "blend",
    "clim",
    "ecmwf",
    "ecmwf_ens",
    "ecmwf_ens15",
    "ecmwf_ens_calib",
    "ecmwf_seas5",
    "ecmwf_seas5_calib",
    "gem",
    "gfs",
    "noaa_gefs",
    "noaa_gefs_calib",
    "noaa_gfs",
    "norm_10yr",
    "norm_5yr",
    "salient_clim",
]
"""hindcast_summary model options.

Forecast model.

- `clim`: Climatological forecasts: Probabilistic distributions characterizing uncertainty around calculated climatological means based on historical climate patterns.
- `gfs`: Generic reference to NOAA GFS models. See `noaa_gfs` for details.
- `ecmwf`: Generic reference to ECMWF models. See `ecmwf_ens` and `ecmwf_seas5` for specific model details.
- `blend`: Salient Blend: Proprietary multi-model ensemble that objectively combines Salient's AI models with properly calibrated dynamical models (GEFS and ECMWF). Available as probability distributions for weekly through quarterly timescales. Use `downscale` for daily ensembles.
- `gem`: Salient GemAI: Generative AI model. Produces native daily ensemble trajectories for days 1-126 ahead, aggregating to coarser timescales and probability distributions.
- `salient_clim`: Salient's proprietary climatological model providing full probabilistic distributions with enhanced uncertainty characterization.
- `norm_5yr`: 5-year rolling climatological normal calculated from the most recent 5 years of observations.
- `norm_10yr`: 10-year rolling climatological normal calculated from the most recent 10 years of observations.
- `noaa_gfs`: NOAA GFS - Global Forecast System: single-member weather model providing hourly forecasts for hours 1-120 (~5 days).
- `noaa_gefs`: NOAA GEFS - Global Ensemble Forecast System: 31-member ensemble providing probabilistic forecasts for days 1-35.
- `noaa_gefs_calib`: Calibrated NOAA GEFS: GEFS ensemble with statistical post-processing to reduce systematic biases and improve reliability.
- `ecmwf_ens`: ECMWF ENS - Extended Range: European Centre ensemble model providing 101 ensemble members for 46 days of forecasts.
- `ecmwf_ens_calib`: Calibrated ECMWF ENS Extended Range: ECMWF ensemble with statistical calibration to improve forecast reliability and reduce biases.
- `ecmwf_seas5`: ECMWF SEAS5 - Seasonal forecast system: Ensemble covering months 1-3 and quarters 1-2
- `ecmwf_seas5_calib`: Calibrated ECMWF SEAS5: ECMWF seasonal model with post-processing for improved skill and reliability at seasonal timescales.
- `ecmwf_ens15`: ECMWF 15-day forecast
"""

HindcastSummaryReference = Literal[
    "blend",
    "clim",
    "ecmwf",
    "ecmwf_ens",
    "ecmwf_ens15",
    "ecmwf_ens_calib",
    "ecmwf_seas5",
    "ecmwf_seas5_calib",
    "gem",
    "gfs",
    "noaa_gefs",
    "noaa_gefs_calib",
    "noaa_gfs",
    "norm_10yr",
    "norm_5yr",
    "salient_clim",
]
"""hindcast_summary reference options.

Forecast model.

- `clim`: Climatological forecasts: Probabilistic distributions characterizing uncertainty around calculated climatological means based on historical climate patterns.
- `gfs`: Generic reference to NOAA GFS models. See `noaa_gfs` for details.
- `ecmwf`: Generic reference to ECMWF models. See `ecmwf_ens` and `ecmwf_seas5` for specific model details.
- `blend`: Salient Blend: Proprietary multi-model ensemble that objectively combines Salient's AI models with properly calibrated dynamical models (GEFS and ECMWF). Available as probability distributions for weekly through quarterly timescales. Use `downscale` for daily ensembles.
- `gem`: Salient GemAI: Generative AI model. Produces native daily ensemble trajectories for days 1-126 ahead, aggregating to coarser timescales and probability distributions.
- `salient_clim`: Salient's proprietary climatological model providing full probabilistic distributions with enhanced uncertainty characterization.
- `norm_5yr`: 5-year rolling climatological normal calculated from the most recent 5 years of observations.
- `norm_10yr`: 10-year rolling climatological normal calculated from the most recent 10 years of observations.
- `noaa_gfs`: NOAA GFS - Global Forecast System: single-member weather model providing hourly forecasts for hours 1-120 (~5 days).
- `noaa_gefs`: NOAA GEFS - Global Ensemble Forecast System: 31-member ensemble providing probabilistic forecasts for days 1-35.
- `noaa_gefs_calib`: Calibrated NOAA GEFS: GEFS ensemble with statistical post-processing to reduce systematic biases and improve reliability.
- `ecmwf_ens`: ECMWF ENS - Extended Range: European Centre ensemble model providing 101 ensemble members for 46 days of forecasts.
- `ecmwf_ens_calib`: Calibrated ECMWF ENS Extended Range: ECMWF ensemble with statistical calibration to improve forecast reliability and reduce biases.
- `ecmwf_seas5`: ECMWF SEAS5 - Seasonal forecast system: Ensemble covering months 1-3 and quarters 1-2
- `ecmwf_seas5_calib`: Calibrated ECMWF SEAS5: ECMWF seasonal model with post-processing for improved skill and reliability at seasonal timescales.
- `ecmwf_ens15`: ECMWF 15-day forecast
"""

HindcastSummaryRegion = Literal[
    "africa",
    "asia",
    "brazil",
    "europe",
    "global",
    "north-america",
    "russia",
    "south-america",
    "south-pacific",
    "usa",
]
"""hindcast_summary region options.

Accepts continents, countries, or U.S. states.
"""

HindcastSummarySeason = Literal["DJF", "JJA", "MAM", "SON", "all"]
"""hindcast_summary season options.

Season filter for hindcast validation metrics.

- `all`: All seasons combined.
- `DJF`: December, January, February (Northern Hemisphere winter).
- `MAM`: March, April, May (Northern Hemisphere spring).
- `JJA`: June, July, August (Northern Hemisphere summer).
- `SON`: September, October, November (Northern Hemisphere autumn).
"""

HindcastSummarySplitSet = Literal["all", "test", "validation"]
"""hindcast_summary split_set options.

Selection of test or validation sets.

- `all`: All data (combined test and validation sets).
- `test`: Test set only. Data held out during model training for final evaluation.
- `validation`: Validation set only. Data used for hyperparameter tuning during development.
"""

HindcastSummaryTimescale = Literal["all", "daily", "long-range", "seasonal", "sub-seasonal"]
"""hindcast_summary timescale options.

Temporal resolution and lookahead range of the forecast.

- `all`: Returns all available timescales for the selected model. Timescale availability varies by model.
- `daily`: Day-by-day ensemble forecasts, 15/35/46/126 days into the future (depending on model). Updates daily.
- `sub-seasonal`: Rolling weekly forecasts covering weeks 1-5 ahead of forecast_date. Updates daily.
- `seasonal`: Rolling monthly forecasts covering 3x30 day periods ahead of forecast_date. Updates daily or weekly depending on model.
- `long-range`: Rolling quarterly forecasts covering quarters 1-4 ahead for 12 months of predictability. Updates monthly on the 15th for the `blend` model.
"""

HindcastSummaryUnits = Literal["SI", "US"]
"""hindcast_summary units options.

Unit system for returned data.

- `SI`: Metric: °C for temperature, mm/day for precipitation, m/s for wind speed, etc.
- `US`: Imperial: °F for temperature, in/day for precipitation, mph for wind speed, etc.
"""

HindcastSummaryVariable = Literal[
    "cc",
    "cdd",
    "dewpoint",
    "hdd",
    "heat_index",
    "hgt500",
    "mslp",
    "precip",
    "rh",
    "temp",
    "tmax",
    "tmin",
    "tsi",
    "wgst",
    "wind_chill",
    "wspd",
    "wspd100",
]
"""hindcast_summary variable options.

Forecast variable.

- `hdd`: Heating degree days (°C | °F). Cumulative measure of cold conditions requiring heating.
- `wspd`: 10-meter wind speed (m/s | mph).
- `tmin`: Daily minimum 2-meter temperature (°C | °F).
- `cdd`: Cooling degree days (°C | °F). Cumulative measure of warm conditions requiring cooling.
- `hgt500`: Geopotential height at 500 hPa (m | ft). Atmospheric pressure level indicator.
- `precip`: Total precipitation (mm/day | in/day). Liquid and frozen water equivalent.
- `temp`: 2-meter air temperature (°C | °F). Average temperature forecast.
- `cc`: Cloud cover fraction (0-1).
- `heat_index`: Heat index at 2 meters (°C | °F). Apparent temperature combining heat and humidity.
- `mslp`: Mean sea level pressure (mbar).
- `dewpoint`: 2-meter dewpoint temperature (°C | °F).
- `rh`: Relative humidity (0-1). Ratio of actual to saturation vapor pressure.
- `tmax`: Daily maximum 2-meter temperature (°C | °F).
- `wspd100`: 100-meter wind speed (m/s | mph). Useful for wind energy applications.
- `tsi`: Total solar irradiance / insolation (W/m² hourly | kWh/m²/day daily).
- `wgst`: Maximum 10-meter wind gust (m/s | mph).
- `wind_chill`: Wind chill at 2 meters (°C | °F). Apparent temperature combining cold and wind.
"""

# ======================================================================
# met_observations
# Fetch meteorological station observations by variable, time range, and spatial proximity given a coordinate, location file, or a shapefile.
# ======================================================================

MetObservationsFormat = Literal["csv", "nc"]
"""met_observations format options.

File format of the returned data.

- `csv`: Comma-Separated Values text format. Suitable for Pandas tables, spreadsheets, databases, and LLMs.
- `nc`: NetCDF4 binary format. Optimized for geospatial analysis with xarray.
"""

MetObservationsVariables = Literal["precip", "snow", "temp", "tmax", "tmin", "wdir", "wspd"]
"""met_observations variables options.

Comma-separated list of meteorological variables to retrieve from weather station observations.

- `precip`: Daily total precipitation (mm).
- `temp`: Daily average temperature (°C).
- `tmax`: Daily maximum temperature (°C).
- `tmin`: Daily minimum temperature (°C).
- `snow`: Daily snowfall (mm).
- `wdir`: Daily average wind direction (degrees).
- `wspd`: Daily average wind speed (m/s).
"""

# ======================================================================
# met_stations
# Search meteorological stations by variables recorded, time range, and spatial proximity given a coordinate, location file, or a shapefile.
# ======================================================================

MetStationsFormat = Literal["csv"]
"""met_stations format options.

File format of the returned data.

- `csv`: Comma-Separated Values text format. Suitable for Pandas tables, spreadsheets, databases, and LLMs.
"""


def get_all_types() -> dict[str, object]:
    """Return all generated Literal types as a dictionary.

    This function exists to satisfy vulture's unused variable detection.
    It also provides a convenient way to introspect all available types.

    Returns:
        A dictionary mapping Literal type names to their type aliases.
    """
    return {
        "DataTimeseriesField": DataTimeseriesField,
        "DataTimeseriesFormat": DataTimeseriesFormat,
        "DataTimeseriesFrequency": DataTimeseriesFrequency,
        "DataTimeseriesUnits": DataTimeseriesUnits,
        "DataTimeseriesVariable": DataTimeseriesVariable,
        "DataTimeseriesWeights": DataTimeseriesWeights,
        "DownscaleFormat": DownscaleFormat,
        "DownscaleFrequency": DownscaleFrequency,
        "DownscaleModel": DownscaleModel,
        "DownscaleReferenceClim": DownscaleReferenceClim,
        "DownscaleUnits": DownscaleUnits,
        "DownscaleVariables": DownscaleVariables,
        "DownscaleWeights": DownscaleWeights,
        "FilesType": FilesType,
        "ForecastTimeseriesField": ForecastTimeseriesField,
        "ForecastTimeseriesFormat": ForecastTimeseriesFormat,
        "ForecastTimeseriesModel": ForecastTimeseriesModel,
        "ForecastTimeseriesReferenceClim": ForecastTimeseriesReferenceClim,
        "ForecastTimeseriesTimescale": ForecastTimeseriesTimescale,
        "ForecastTimeseriesUnits": ForecastTimeseriesUnits,
        "ForecastTimeseriesVariable": ForecastTimeseriesVariable,
        "ForecastTimeseriesWeights": ForecastTimeseriesWeights,
        "GeoFormat": GeoFormat,
        "GeoResolution": GeoResolution,
        "GeoVariables": GeoVariables,
        "HindcastSummaryFormat": HindcastSummaryFormat,
        "HindcastSummaryInterpMethod": HindcastSummaryInterpMethod,
        "HindcastSummaryMetric": HindcastSummaryMetric,
        "HindcastSummaryModel": HindcastSummaryModel,
        "HindcastSummaryReference": HindcastSummaryReference,
        "HindcastSummaryRegion": HindcastSummaryRegion,
        "HindcastSummarySeason": HindcastSummarySeason,
        "HindcastSummarySplitSet": HindcastSummarySplitSet,
        "HindcastSummaryTimescale": HindcastSummaryTimescale,
        "HindcastSummaryUnits": HindcastSummaryUnits,
        "HindcastSummaryVariable": HindcastSummaryVariable,
        "MetObservationsFormat": MetObservationsFormat,
        "MetObservationsVariables": MetObservationsVariables,
        "MetStationsFormat": MetStationsFormat,
    }
