Gaia Domain - Features

Sovereign weather and climate ML platform (libs/gaia/*; TODO Phase 175).

Gaia owns the ecosystem weather and climate intelligence substrate. It provides frontier deterministic forecasting, probabilistic ensemble forecasting, tropical-cyclone prediction, precipitation nowcasting, climate emulation, downscaling, bias correction, alerting, and weather-impact APIs consumed by agriculture, robotics, construction, live events, journalism, finance, and emergency workflows.

Gaia is built on the same science as Google DeepMind's GraphCast and GenCast, NVIDIA's FourCastNet and StormCast, Huawei's Pangu-Weather, and Microsoft's Aurora — but as sovereign, auditable, openly-licensed weights that Oshun controls end-to-end. The domain spans the entire ML stack: raw observation ingestion, dataset curation and normalization, model training, evaluation gating, operational forecast cycles, API serving, and alert publication.

Gaia is distinct from Nyx's Gaia star-catalog references. In DOMAINS/, Gaia means Earth-system forecasting and climate ML.

Current Status#

Gaia is a planned-only domain. No packages exist in the monorepo yet, and no implementation work has begun. Phase 175 is the canonical task-level checklist.

• Planned-only domain introduced by TODOS/phase-175.md.
• No apps/gaia/*, libs/gaia/*, or services/gaia/* packages exist yet.
• Planned libraries use the @gaia/* package prefix.
• Phase 175 is the canonical task-level checklist for this domain.

Planned Package Inventory#

Phase 175 specifies eight libraries that together cover the full pipeline from raw data ingestion to downstream forecast consumption. Each library is independently deployable and has a defined scope.

Phase 175 Feature Coverage#

The sections below describe every feature family Phase 175 introduces, organized by model class and capability. Each section maps to one or more planned @gaia/* packages.

Reanalysis and Observation Data Foundation#

@gaia/weather-data ingests from ten distinct source classes, covering the full range from multi-decade reanalysis archives to real-time radar and lightning. The breadth of sources is intentional: each model class depends on a different data mix, and all sources feed the same canonical WeatherSample schema so training jobs can mix them freely.

• ERA5 archive ingestion from 1940-present with hourly 0.25 degree surface and pressure-level fields, GRIB2 to Zarr conversion, Kerchunk indexing, and tiered MinIO storage.
• ERA5-Land high-resolution surface ingestion for downscaling priors and hydrology.
• IFS HRES operational analysis ingestion for live initial conditions.
• GFS operational ingestion as fallback initial-condition source and cross-validation baseline.
• MERRA-2 ingestion for multi-reanalysis agreement and aerosol inputs.
• IBTrACS tropical-cyclone best-track ingestion for formation, track, intensity, pressure, and wind-radius training labels.
• NEXRAD Level-II, OPERA composites, GOES-R, MTG, Himawari, GPM IMERG, METAR, SYNOP, BUFR, ASOS, GLM, and EUCLID ingestion for radar, satellite, station, and lightning coverage.
• Canonical WeatherSample schema with date, lead time, grid, levels, variables, provenance hash, Zod validation, Zarr chunk alignment, stratified sampling, temporal train/validation/test separation, and per-variable normalization statistics.

Deterministic Spherical GNN Forecasting#

@gaia/graphcast implements the deterministic medium-range model. It is architecturally aligned with the published GraphCast paper — icosahedral mesh, grid-to-mesh encoder, interaction-network processor, mesh-to-grid decoder — but with Oshun-specific training plans, stability diagnostics, and evaluation gates that give the project an auditable checkpoint trail independent of any external provider.

• Icosahedral multi-mesh generation from M0 through M6 with precomputed edges.
• Grid-to-mesh encoder, hierarchical interaction-network mesh processor, and mesh-to-grid decoder matching GraphCast semantics.
• Autoregressive 6-hour rollout driver for horizons up to 10 days.
• GraphCast-Sovereign base and XL training plans, including 1 degree and 0.25 degree variants, mixed precision, distributed training, multi-step fine-tuning, and latitude/variable/level weighting.
• Rollout-stability diagnostics for energy conservation, spectra, blur, and automatic checkpoint rejection on collapse.

Probabilistic Diffusion Forecasting#

@gaia/gencast extends the deterministic model with ensemble generation. Rather than a single forecast, it produces a calibrated spread of plausible future states, which is essential for any downstream consumer that needs to make risk-weighted decisions rather than acting on a single best-guess outcome.

• State-diffusion model over 12-hour residuals on the spherical mesh using EDM parametrization and GNN score backbones.
• DPM-Solver++ and stochastic Heun samplers for calibrated ensembles.
• CRPS, spread-skill, rank histogram, reliability diagram, extreme-percentile, and scenario-clustering diagnostics.
• Operational 50-member ensemble generation targets suitable for H100/B200 clusters.

Tropical Cyclone Prediction#

Direct tropical-cyclone prediction in @gaia/cyclone-forecast produces a CycloneForecastProduct keyed by stormId and basin, holding an ordered list of CycloneForecastPoint records — one per forecast lead time.

Cyclone prediction is singled out as its own library because the required outputs (ATCF deck format, quadrant wind radii, eye-formation probability) and the required evaluation protocol (NHC-style verification) are substantially different from the standard grid-forecast stack. Emergency-response systems downstream — particularly Oya's hurricane-hunter drone tasking and Kuanyin's safety escalation — need these specialized fields and formats.

• Per-lead-time forecast point — Each CycloneForecastPoint carries leadTimeHours, a probabilityOfCyclone (the model's confidence that a coherent cyclone exists at that lead time), centerLat/centerLon, and the intensity fields below. Points are emitted along the standard forecast horizon, so a single product is the full track.
• Intensity and structure fields — maxSustainedWindKt, centralPressureHpa, radiusOfMaximumWindNm, and the three wind-radius quadrant tuples r34QuadrantsNm / r50QuadrantsNm / r64QuadrantsNm (NE, SE, SW, NW radii of 34-, 50-, and 64-knot wind). saffirSimpsonCategory is a 0-5 enum (0 = tropical storm or weaker). eyeFormationProbability reports the chance of a closed eye. Intensity and structure fields are optional per point because a low-probability or pre-formation point may carry only position.
• Trajectory decoder — A trajectory decoder conditioned on recent best-track history (from IBTrACS-trained labels) and the forecast model's latent state produces the position sequence; intensity and structure are decoded jointly so track and intensity stay physically consistent.
• Loss formulation — Training uses joint position, intensity, category, and formation loss functions, so the model is penalized for a good track with a wrong intensity as well as the reverse.
• ATCF and uncertainty-cone products — Each product can publish atcfUri (ATCF-compatible deck for emergency-response systems that already consume the format) and uncertaintyConeUri (the track uncertainty cone). Both are signed product URIs.
• Downstream consumers — Oya hurricane-hunter drone tasking, Cybele pre-storm asset hardening, Galatea outdoor safety gating, and Veritas tropical-cyclone bulletin generation consume the cyclone product; each owns its own decision (see Downstream Product Consumers below).

Precipitation Nowcasting#

Minute-scale precipitation nowcasting in @gaia/nowcast answers a PrecipitationNowcastRequest and returns a PrecipitationNowcastProduct.

Nowcasting fills the gap between the 6-hour deterministic forecast cadence and the immediate future: consumers like Uzume (live-event safety) and Oya (short-hop drone missions) need accurate precipitation predictions at 1–15 minute lead times and kilometer scale, well within the useful horizon of a radar-based model but too fine-grained for a global NWP model.

• Request parameters — issuedAt (nowcast base time), horizonMinutes (how far ahead, within the 0-12 hour skill window), cadenceMinutes (output step), a required region bounding box, thresholdsMmPerHour (the rain-rate thresholds the user wants probability fields for, e.g. light/moderate/heavy), and an optional ensembleMembers count that selects ensemble GAN nowcasting over a single deterministic run.
• Deterministic model — A MetNet-3-class axial transformer over radar, satellite, topography, and NWP boundary conditions produces deterministic 0-12 hour precipitation at kilometer scale. Radar and satellite supply the recent motion and convection signal; NWP boundary conditions keep the longer lead times physically anchored.
• Ensemble model — When ensembleMembers is set, a DGMR-class conditional GAN generates an ensemble of precipitation fields, so downstream consumers see spread rather than a single track.
• Convective-mode classification — The product reports convectiveMode as one of stratiform, convective, tropical, frontal, or mixed. The mode changes how a consumer should weight the nowcast — a convective regime is fast-evolving and short-lived, a stratiform regime is more predictable.
• Verification block — When verification has run, the product carries csi (critical success index), pod (probability of detection), far (false-alarm ratio), and fss (fractional skill score), computed against Stage IV and radar-gauge blends. The block is optional because a freshly issued nowcast has no verification until the valid period elapses.

Climate Emulation#

Climate emulation in @gaia/climate-emulator answers a ClimateScenarioRequest for multi-decade rollouts under tunable forcing.

Where the deterministic and ensemble models operate on 6-hour time steps up to 10 days, the climate emulator operates on annual-to-decadal time steps up to 100 years. Its consumers — primarily Cybele (construction climate adaptation) and Lakshmi (long-horizon energy investment) — need climate projections under different emissions scenarios rather than short-range weather forecasts.

• Request parameters — baselinePeriod (the reference climate the rollout departs from), rolloutYears (rollout length, up to the validated 100-year range), a variables list, and a forcing block. The forcing block accepts an explicit co2Ppm and ch4Ppb, an aerosolScenario, and an ssp selector with values ssp2_45, ssp5_85, or custom — custom is the path that uses the explicit gas concentrations rather than a standard SSP pathway.
• Emulator model — A spherical-FNO or ACE-class emulator trained on CMIP6 pre-industrial and scenario runs produces stable 100-year rollouts; stability over the full rollout is a hard requirement, not a best effort, because an emulator that drifts is useless for decadal decision support.
• Coupled feedbacks — Sea-ice-albedo and soil-moisture feedback modules are coupled into the rollout so ice-albedo and land-surface feedbacks evolve rather than being held fixed.
• Hindcast validation — A decadal hindcast driver is validated against HadCRUT5, GISTEMP, and AMIP-SST before a checkpoint is promoted, and energy, moisture, and drift budgets must close over the long rollout.

Downscaling and Bias Correction#

Downscaling in @gaia/downscale answers a DownscalingRequest that refines an existing coarse forecast to finer scale or to specific sites.

The global models in @gaia/graphcast and @gaia/gencast operate at 0.25° resolution (roughly 25 km). Many downstream consumers need much finer detail — Cybele needs city-block resolution for urban heat-island adaptation, Asase needs growing-degree-day estimates at station level, and Lakshmi needs site-specific wind-power density. Downscaling is the bridge between global model outputs and these site- or sub-grid-scale requirements.

• Request parameters — sourceForecastId (the coarse ForecastProduct to refine), a targetResolution of 2km, 1km, 50m_urban, or station, a method selector, an optional region bounding box, and an optional stationIds list used when the target is station.
• Method selector — residual_diffusion is CorrDiff-class residual diffusion (used for the 25 km to 2 km grid refinement); station_bias applies station-level bias correction at METAR/SYNOP locations; quantile_mapping applies multivariate quantile mapping; urban_uhi is urban heat-island-aware 50 m downscaling. The method is chosen for the target — grid refinement, point-site correction, distribution correction, or city-scale heat.
• Derived variables — Quantile mapping covers wind power density, heating and cooling degree days, growing degree days, and hydrology-derived variables, so a downscaled product can directly serve energy and agriculture consumers rather than only raw meteorological fields.
• Urban target — 50 m urban heat-island downscaling targets Cybele construction and Themis climate-adaptation workflows, which need city-block resolution that a 2 km grid cannot give.

Operational Forecast Cycles#

@gaia/forecast-serving runs the live operational cycle that turns the latest analysis into published forecast products. The cycle runner is the operational heartbeat of the domain: it fires four times per day, fetches initial conditions, runs the configured model stack, checks publication gates, and either publishes products or retains them as drafts with an event trail that explains why.

• Cycle cadence — Cycles run on the 00/06/12/18 UTC analysis schedule. A cycle launches when live IFS HRES initial conditions are available, or fallback GFS initial conditions if HRES is missing — the cycle is not skipped for want of the primary source.
• Publication gate — A cycle's products may publish only when all three gates pass: rollout-stability diagnostics (energy conservation, spectra, blur — see Deterministic Spherical GNN Forecasting), a skill-regression check against the prior promoted baseline, and a data-completeness check on the inputs. A cycle that fails any gate does not publish; its ForecastProduct records stay in publicationStatus: 'draft'.
• Cycle rollback — When a published cycle is later found bad, it is rolled back: affected products transition to publicationStatus: 'rolled_back', a gaia.forecast.cycle.rolled_back event fires, and downstream consumers fall back to the previous good cycle. A rolled-back product is retained, not deleted, so the failure is auditable.
• Latency target — The operational deterministic cycle has a p95 completion target under 20 minutes on the planned H100-class cluster, measured from analysis availability to product publication.
• Observability — Forecast availability, skill, latency, calibration, cycle completion, cost, and downstream publication failure are first-class metrics with dashboards; they are not derived after the fact.

Forecast API and Products#

@gaia/forecast-serving exposes an OpenAPI 3.1 forecast API. Forecast jobs are described by a ForecastRequest and resolve to a ForecastProduct.

• Forecast request — A ForecastRequest carries cycleTime, horizonHours, an optional region bounding box, a product discriminator (deterministic, ensemble, cyclone, nowcast, climate_scenario, or downscaled), a variables list, and an outputFormat of json, zarr, grib2, stac, or ogc_edr. The outputFormat lets a scientific user pull Zarr or GRIB2 while a shell surface pulls JSON.

• Forecast product — A ForecastProduct carries id, modelId, modelVersion, cycleTime, horizonHours, grid, a variables list, productUris (signed URIs to the product files), an optional skillSummary, and publicationStatus of draft, published, or rolled_back.

• Endpoints — The API defines ten endpoints, one per forecast product type plus retrieval, download, and alert operations:

  Endpoint	Purpose
  POST /forecast/deterministic	Run a deterministic GNN forecast
  POST /forecast/ensemble	Run a probabilistic diffusion ensemble
  POST /forecast/cyclone	Run a tropical-cyclone forecast
  POST /forecast/nowcast	Run a minute-scale precipitation nowcast
  POST /forecast/climate-scenario	Run a climate-emulation scenario rollout
  POST /forecast/downscale	Downscale an existing product to finer scale
  GET /forecast/products/{id}	Retrieve a product's metadata and URIs
  GET /forecast/products/{id}/stac	Retrieve the product's STAC 1.0 item
  GET /forecast/products/{id}/download	Download the product files
  POST /forecast/alerts/cap	Publish a CAP 1.2 severe-weather alert

• Mandatory response metadata — Every forecast response must include the model version, cycle time, the data-source versions used, an output hash, the skill summary where available, and signed output URIs for large products. This is non-negotiable: a forecast a consumer cannot trace back to a model version and source set is not publishable.

• Product warehouse and catalogs — Products are persisted to a Zarr forecast-product warehouse and registered in a STAC 1.0 catalog, with OGC EDR and OGC API Features endpoints so external scientific users can query products through standard geospatial interfaces.

• CAP alerts — POST /forecast/alerts/cap publishes CAP 1.2-compatible severe-weather alerts. Each alert preserves the source forecast identity and threshold rule, integrates with Kuanyin emergency escalation and Oshun shell-routine notification, and emits an audit event for downstream publication.

Domain Events#

Gaia publishes ten domain events that let downstream consumers and internal operations react to state changes without polling. Events cover the full lifecycle: data arrival, dataset versioning, cycle execution, product publication, alert dispatch, model promotion, and model rejection. The table below lists each event with its trigger and payload.

Gaia consumes shared identity, tenant, storage, queue, model-serving, observability, and evaluation contracts.

Downstream Product Consumers#

Gaia's boundary principle is that it owns forecast products; consumers own the decisions made from them. This principle exists to prevent domain logic from leaking into Gaia — if Gaia were to decide "this wind speed is too high for drone flight", it would be duplicating Oya's domain logic and embedding assumptions about drone types it should not know about. Instead, Gaia emits physically grounded forecasts and each consumer applies its own policy.

Every consumer reads public Gaia products or signed product URIs — never Gaia private training splits — and must preserve forecast uncertainty rather than collapsing a low-confidence forecast into a deterministic user action without its own domain-owned policy gate. Severe-weather alert consumers must preserve CAP IDs and Gaia provenance in user-facing notifications and audit logs.

Evaluation and Research Release#

Model promotion is not automatic — every checkpoint must pass a per-class evaluation suite before it can serve operational forecasts. The suite is grounded in community benchmarks so Gaia's published skill can be directly compared against external frontier models.

• WeatherBench-2, ECMWF scorecards, NHC verification, pysteps verification, and public checkpoint leaderboards.
• Stress-test cases for recent hurricanes, heat domes, and cold snaps.
• Continuous forecast-versus-analysis feedback into the Phase 85 data flywheel.
• Station, radiosonde, buoy, and observational residual feedback loops.
• Scientific paper and open-weight release plan for major model classes when licensing permits.

Source Coverage#

This file was checked against TODOS/phase-175.md. It captures every Phase 175 capability family, package prefix, planned package path, data source class, model class, operational API, downstream integration, evaluation gate, and research-release requirement at the domain-specification level. Task-level checkboxes remain in TODOS/phase-175.md.