Composition: Earth physical ops stack

Series: compositions (3 of 4)
Prerequisites: Platform intro, Earth
Directions: Earth only (multi-module composition inside one direction)
Auth: x-api-key

Not every composition crosses directions. This one stays inside Earth and joins weather, hazards, grid, and aviation into one operations brief.

Portal recipes: weather-aware-operations, grid-load-monitor.

Goal

For a site or region (lat/lon + optional ICAO + grid region):

Current multi-model weather at the point
Nearby / global hazards of interest
Grid demand (or other metric) for the power region
Optional METAR for the nearest/ops airport

Output a single ops JSON for dashboards or agents. Forecast guidance only - not an official warning service.

Call sequence

[Earth] GET /api/v2/weather?lat=&lon=
[Earth] GET /api/v2/hazards/earthquakes?window=day&min_magnitude=4.5&limit=20
        (or other /hazards/* types as needed)
[Earth] GET /api/v2/energy/grid?region=US48&metric=demand&limit=24
[Earth] GET /api/v2/air-quality?lat=&lon=          (optional)
[Earth] GET /api/v2/transport/aviation/metar?ids=KJFK   (optional)
         -> ops_brief

H="x-api-key: $SUGRA_API_KEY"
B=https://sugra.ai
LAT=40.64
LON=-73.78

curl -H "$H" "$B/api/v2/weather?lat=$LAT&lon=$LON"
curl -H "$H" "$B/api/v2/hazards/earthquakes?window=day&min_magnitude=4.5&limit=10"
curl -H "$H" "$B/api/v2/energy/grid?region=US48&metric=demand&limit=24"
curl -H "$H" "$B/api/v2/transport/aviation/metar?ids=KJFK"

Path note: METAR is under /api/v2/transport/aviation/metar?ids=, not /api/v1/aviation/metar.

Client package (example)

ops_brief = {
    "location": {"lat": lat, "lon": lon},
    "weather": {
        "temperature_c": weather["weather"]["temperature_c"],
        "wind_speed_ms": weather["weather"]["wind_speed_ms"],
        "model": weather.get("forecast", {}).get("name"),
        "provenance": weather.get("provenance"),
        "attribution": weather.get("attribution"),
    },
    "hazards": {
        "earthquakes_matched": hazards.get("total_matched"),
        "events": hazards.get("events", [])[:5],
        "disclaimer": hazards.get("disclaimer"),
    },
    "grid": {
        "region": grid.get("region"),
        "metric": grid.get("metric"),
        "latest": (grid.get("series") or [None])[0],
        "source_meta": grid_meta.get("source"),
    },
    "aviation": metar_payload,  # may be null if 503 / not ingested
}

Keep meta.source / attribution blocks for each leg.

Why this composition works

Module	Contribution
Weather v2	Multi-model point conditions + per-field provenance
Hazards v2	Unified event schema
Energy grid	Infrastructure load context
Aviation METAR	Station truth near hubs

All under one direction, one key, mostly standard data/meta envelope.

Cadence and quota

Leg	Suggested refresh
Weather	15-60 minutes
Hazards	15-60 minutes
Grid	15-60 minutes (region-dependent publish)
METAR	15-30 minutes when aviation matters

Full brief: about 3-5 calls per refresh.

Optional cross-direction extensions (out of scope here)

Add NetAtlas outage alerts for connectivity context
Add News disaster category headlines

Those become multi-direction compositions; keep them explicit so failure domains stay clear.

Failure modes

Failure	Handling
Weather 503	Last-good weather; flag stale
Hazards empty	Valid “no events above threshold”
METAR 503 / not ingested	Omit aviation block
Wrong region code on grid	4xx - fix enum from docs

Ops brief from Sugra Earth