# 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. | Package | Planned path | Responsibility | | ------------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `@gaia/weather-data` | `libs/gaia/weather-data` | Reanalysis, operational analysis, observation, radar, satellite, station, lightning, and cyclone best-track ingestion | | `@gaia/graphcast` | `libs/gaia/graphcast` | GraphCast-class deterministic spherical GNN forecasts | | `@gaia/gencast` | `libs/gaia/gencast` | GenCast-class probabilistic diffusion ensemble forecasts | | `@gaia/cyclone-forecast` | `libs/gaia/cyclone-forecast` | Direct tropical-cyclone formation, track, intensity, and ATCF output prediction | | `@gaia/nowcast` | `libs/gaia/nowcast` | Minute-scale radar, satellite, and lightning precipitation nowcasting | | `@gaia/climate-emulator` | `libs/gaia/climate-emulator` | ACE-class climate emulation, long rollouts, and scenario support | | `@gaia/downscale` | `libs/gaia/downscale` | Fine-scale statistical and ML downscaling plus site bias correction | | `@gaia/forecast-serving` | `libs/gaia/forecast-serving` | Forecast APIs, operational cycle runner, product warehouse, alerts, and downstream adapters | ## 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. | Event | Trigger | Payload | | --------------------------------- | ---------------------------------------- | ----------------------------------------------------------------- | | `gaia.data.ingested` | A raw source archive is ingested | Source class, acquisition time, checksum, object URI | | `gaia.dataset.versioned` | A training dataset manifest is cut | Dataset id, version, temporal split ranges, normalization version | | `gaia.forecast.cycle.started` | An operational cycle launches | Cycle time, initial-condition source (HRES or GFS) | | `gaia.forecast.cycle.completed` | A cycle passes all gates and publishes | Cycle time, product ids, completion latency | | `gaia.forecast.cycle.rolled_back` | A published cycle is rolled back | Cycle time, affected product ids, rollback reason | | `gaia.forecast.product.published` | A product becomes `published` | Product id, model id/version, grid, variables, signed URIs | | `gaia.alert.cap.published` | A CAP 1.2 alert is published | CAP id, source forecast id, threshold rule, publication targets | | `gaia.skill.regression_detected` | A skill-regression check fails | Model id, baseline, regressed metric and magnitude | | `gaia.model.promoted` | A checkpoint passes its evaluation gates | Model id, version, evaluation suite results | | `gaia.model.rejected` | A checkpoint fails an evaluation gate | Model id, version, failed gate | 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. | Consumer | Gaia output consumed | Consumer-owned decision | | --------- | ---------------------------------------------------------- | -------------------------------------------------------- | | Asase | Weather ensembles, GDD, precipitation, wind, heat, drought | Crop, irrigation, planting, and livestock operations | | Demeter | Garden weather, GDD, frost, localized alerts | Garden tasks, plant care, and automation rules | | Oya | Wind, convective risk, cyclone tracks, no-fly weather | Drone missions, no-fly cones, swarm safety | | Galatea | Outdoor weather and hazard gates | Robot deployment and safety policies | | Cybele | Storm hardening, climate adaptation, urban downscaling | Construction and property operations | | Lakshmi | Renewable energy potential and climate risk | Trading, capacity planning, and personal finance outputs | | Uzume | Lightning, wind, precipitation, heat, outdoor-event risk | Live-event safety decisions | | Aphrodite | Outdoor shoot risk and severe-weather warnings | Performer and production scheduling | | Veritas | Weather products and alert metadata | Editorial weather reporting and fact-checking | | Kuanyin | Severe-weather emergency signals | Safety escalation and community protection | ### 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`.