Weather

Overview

Melian provides weather data through the National Weather Service (NOAA) API. Three tools cover current conditions, multi-day forecasts, and active weather alerts. All tools default to a configured home location but accept any US location by name. No API key is required.

Configuration

Weather is configured in ~/.melian/weather.yaml:

enabled: true
default_location:
  lat: 39.7392
  lon: -104.9903
  name: "Denver, CO"
units: imperial    # imperial | metric

When enabled, default_location is required. Units affect temperature (F/C) and wind speed (mph/km/h) display.

Tools

Tool	Parameters	Description
`get_current_weather`	`location?: string`	Current conditions from nearest NOAA station
`get_forecast`	`location?: string`, `days?: number` (1-7, default 3)	Daily forecast with day/night periods
`get_weather_alerts`	`location?: string`	Active NWS alerts at the location

All parameters are optional. When location is omitted, the configured default_location is used.

Data Returned

Current conditions:

interface CurrentConditions {
  temperature: number | null;     // Converted to configured units
  humidity: number | null;        // Percentage
  windSpeedKmh: number | null;
  windDirection: string | null;   // Cardinal (N, NNE, SW, etc.)
  description: string | null;     // e.g., "Sunny"
  station: string;                // e.g., "Denver International Airport"
}

Forecast periods:

interface ForecastPeriod {
  name: string;                   // e.g., "Today", "Tonight", "Thursday"
  temperature: number;
  temperatureUnit: string;        // "F" or "C"
  shortForecast: string;          // e.g., "Sunny"
  detailedForecast: string;
  windSpeed: string;              // e.g., "10 mph"
  windDirection: string;
  precipitationChance: number | null;
}

Alerts:

interface Alert {
  severity: string;               // "Moderate", "Severe", etc.
  event: string;                  // e.g., "Wind Advisory"
  headline: string;
  description: string;
  expires: string;                // ISO timestamp
}

Architecture

The weather client uses two external APIs:

NOAA Weather API (api.weather.gov): conditions, forecasts, alerts. Public, no key needed. US locations only.
Census Bureau Geocoder (geocoding.geo.census.gov): converts location names to lat/lon coordinates.

The flow for a named location: geocode the name to coordinates, resolve to a NOAA grid point, then fetch data from the grid point endpoint. Grid points are cached to avoid redundant lookups.

Limitations

US locations only (NOAA coverage). Non-US locations return an error.
NOAA station data can occasionally be stale (stations report on varying intervals).
Geocoding uses the Census Bureau, which handles US addresses and city names but not landmarks or informal place names.