release: v1.6.1 - Weather forecasts, sun times, air quality

- Weather fetch now returns 7-day forecasts with UV index
- New /volatile/fetch/sun/{city} endpoint for sunrise/sunset
- New /volatile/fetch/air_quality/{city} endpoint for AQI and pollutants
- OpenMeteoProvider now implements AirQualityProvider interface

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/apis/__init__.py

@@ -27,6 +27,9 @@ from .base import (
     DayForecast,
     WeatherForecast,
     GeoLocation,
+    SunTimes,
+    # Air quality models
+    AirQuality,
     # News models
     NewsItem,
     NewsFeed,
@@ -34,6 +37,7 @@ from .base import (
     StockQuote,
     # Abstract providers
     WeatherProvider,
+    AirQualityProvider,
     NewsProvider,
     FinancialProvider,
 )
@@ -53,8 +57,12 @@ __all__ = [
     "DayForecast",
     "WeatherForecast",
     "GeoLocation",
+    "SunTimes",
     "WeatherProvider",
     "OpenMeteoProvider",
+    # Air quality
+    "AirQuality",
+    "AirQualityProvider",
     # News
     "NewsItem",
     "NewsFeed",

src/apis/base.py

@@ -44,14 +44,18 @@ class CurrentWeather:
     condition_text: str  # Human-readable description
     timestamp: datetime
     location: str  # City/location name
+    uv_index: Optional[float] = None  # UV index 0-11+
 
     def to_text(self) -> str:
         """Generate natural language description."""
-        return (
-            f"Currently {self.temperature:.1f}°C "
-            f"({self.condition_text}) in {self.location}. "
+        parts = [
+            f"Currently {self.temperature:.1f}°C",
+            f"({self.condition_text}) in {self.location}.",
             f"Humidity {self.humidity}%, wind {self.wind_speed:.0f} km/h."
-        )
+        ]
+        if self.uv_index is not None:
+            parts.append(f"UV index: {self.uv_index:.0f}.")
+        return " ".join(parts)
 
 
 @dataclass
@@ -64,6 +68,14 @@ class DayForecast:
     condition_text: str
     precipitation_chance: Optional[int]  # Percentage 0-100
     precipitation_mm: Optional[float]
+    uv_index_max: Optional[float] = None  # Max UV index for the day
+
+    def to_text(self) -> str:
+        """Generate natural language description."""
+        date_str = self.date.strftime("%A")  # Day name
+        precip = f", {self.precipitation_chance}% rain" if self.precipitation_chance else ""
+        uv = f", UV {self.uv_index_max:.0f}" if self.uv_index_max else ""
+        return f"{date_str}: {self.temp_high:.0f}°/{self.temp_low:.0f}°C, {self.condition_text}{precip}{uv}"
 
 
 @dataclass
@@ -84,6 +96,78 @@ class GeoLocation:
     admin_area: Optional[str] = None  # State/province
 
 
+@dataclass
+class SunTimes:
+    """Sunrise/sunset times for a location."""
+    location: str
+    date: datetime
+    sunrise: datetime
+    sunset: datetime
+    daylight_duration: int  # seconds
+    solar_noon: Optional[datetime] = None
+
+    def to_text(self) -> str:
+        """Generate natural language description."""
+        sunrise_str = self.sunrise.strftime("%H:%M")
+        sunset_str = self.sunset.strftime("%H:%M")
+        hours = self.daylight_duration // 3600
+        minutes = (self.daylight_duration % 3600) // 60
+        return (
+            f"Sun times for {self.location} on {self.date.strftime('%A %d %B')}: "
+            f"Sunrise at {sunrise_str}, sunset at {sunset_str}. "
+            f"Daylight duration: {hours}h {minutes}m."
+        )
+
+
+@dataclass
+class AirQuality:
+    """Air quality measurements for a location."""
+    location: str
+    timestamp: datetime
+    aqi_european: Optional[int]  # European AQI 0-500+
+    aqi_us: Optional[int]  # US AQI 0-500+
+    pm2_5: Optional[float]  # µg/m³
+    pm10: Optional[float]  # µg/m³
+    ozone: Optional[float]  # µg/m³
+    nitrogen_dioxide: Optional[float]  # µg/m³
+    sulphur_dioxide: Optional[float]  # µg/m³
+    carbon_monoxide: Optional[float]  # µg/m³
+    # Pollen (European data only, seasonal)
+    pollen_grass: Optional[float] = None
+    pollen_birch: Optional[float] = None
+    pollen_alder: Optional[float] = None
+
+    def to_text(self) -> str:
+        """Generate natural language description."""
+        parts = [f"Air quality in {self.location}:"]
+        if self.aqi_european is not None:
+            level = self._aqi_level(self.aqi_european)
+            parts.append(f"European AQI {self.aqi_european} ({level}).")
+        if self.pm2_5 is not None:
+            parts.append(f"PM2.5: {self.pm2_5:.1f} µg/m³.")
+        if self.pm10 is not None:
+            parts.append(f"PM10: {self.pm10:.1f} µg/m³.")
+        if self.ozone is not None:
+            parts.append(f"Ozone: {self.ozone:.1f} µg/m³.")
+        return " ".join(parts)
+
+    @staticmethod
+    def _aqi_level(aqi: int) -> str:
+        """Convert AQI to human-readable level."""
+        if aqi <= 20:
+            return "good"
+        elif aqi <= 40:
+            return "fair"
+        elif aqi <= 60:
+            return "moderate"
+        elif aqi <= 80:
+            return "poor"
+        elif aqi <= 100:
+            return "very poor"
+        else:
+            return "hazardous"
+
+
 # =============================================================================
 # News Models
 # =============================================================================
@@ -163,6 +247,11 @@ class WeatherProvider(ABC):
         """Get weather forecast for a location."""
         pass
 
+    @abstractmethod
+    async def get_sun_times(self, location: GeoLocation) -> SunTimes:
+        """Get sunrise/sunset times for today."""
+        pass
+
     async def get_weather_for_city(self, city: str) -> CurrentWeather:
         """Convenience method: geocode and get current weather."""
         location = await self.geocode(city)
@@ -171,6 +260,15 @@ class WeatherProvider(ABC):
         return await self.get_current(location)
 
 
+class AirQualityProvider(ABC):
+    """Abstract base class for air quality API providers."""
+
+    @abstractmethod
+    async def get_air_quality(self, location: GeoLocation) -> AirQuality:
+        """Get current air quality for a location."""
+        pass
+
+
 class NewsProvider(ABC):
     """Abstract base class for news API providers."""
 

src/apis/openmeteo.py

@@ -14,11 +14,14 @@ from typing import Optional
 
 from .base import (
     WeatherProvider,
+    AirQualityProvider,
     WeatherCondition,
     CurrentWeather,
     DayForecast,
     WeatherForecast,
     GeoLocation,
+    SunTimes,
+    AirQuality,
 )
 
 logger = logging.getLogger(__name__)
@@ -89,11 +92,12 @@ WMO_DESCRIPTIONS: dict[int, str] = {
 }
 
 
-class OpenMeteoProvider(WeatherProvider):
-    """Open-Meteo weather API implementation."""
+class OpenMeteoProvider(WeatherProvider, AirQualityProvider):
+    """Open-Meteo weather and air quality API implementation."""
 
     GEOCODING_URL = "https://geocoding-api.open-meteo.com/v1/search"
     WEATHER_URL = "https://api.open-meteo.com/v1/forecast"
+    AIR_QUALITY_URL = "https://air-quality-api.open-meteo.com/v1/air-quality"
 
     def __init__(
         self,
@@ -194,9 +198,11 @@ class OpenMeteoProvider(WeatherProvider):
                         "wind_speed_10m",
                         "wind_direction_10m"
                     ],
+                    "daily": ["uv_index_max"],
                     "timezone": self.timezone,
                     "temperature_unit": "celsius",
-                    "wind_speed_unit": "kmh"
+                    "wind_speed_unit": "kmh",
+                    "forecast_days": 1
                 }
             )
             response.raise_for_status()
@@ -205,6 +211,12 @@ class OpenMeteoProvider(WeatherProvider):
             current = data.get("current", {})
             weather_code = current.get("weather_code", 0)
 
+            # Get today's UV index from daily data
+            daily = data.get("daily", {})
+            uv_index = None
+            if daily.get("uv_index_max"):
+                uv_index = daily["uv_index_max"][0]
+
             return CurrentWeather(
                 temperature=current.get("temperature_2m", 0.0),
                 feels_like=current.get("apparent_temperature"),
@@ -214,7 +226,8 @@ class OpenMeteoProvider(WeatherProvider):
                 condition=WMO_CODE_MAP.get(weather_code, WeatherCondition.UNKNOWN),
                 condition_text=WMO_DESCRIPTIONS.get(weather_code, "Unknown"),
                 timestamp=datetime.now(),
-                location=location.name
+                location=location.name,
+                uv_index=uv_index
             )
         except httpx.HTTPError as e:
             logger.error(f"Weather request failed for {location.name}: {e}")
@@ -259,7 +272,8 @@ class OpenMeteoProvider(WeatherProvider):
                         "temperature_2m_max",
                         "temperature_2m_min",
                         "precipitation_sum",
-                        "precipitation_probability_max"
+                        "precipitation_probability_max",
+                        "uv_index_max"
                     ],
                     "timezone": self.timezone,
                     "temperature_unit": "celsius",
@@ -272,7 +286,14 @@ class OpenMeteoProvider(WeatherProvider):
 
             # Parse current weather
             current_data = data.get("current", {})
+            daily_data = data.get("daily", {})
             weather_code = current_data.get("weather_code", 0)
+
+            # Get today's UV from daily data
+            uv_index = None
+            if daily_data.get("uv_index_max"):
+                uv_index = daily_data["uv_index_max"][0]
+
             current = CurrentWeather(
                 temperature=current_data.get("temperature_2m", 0.0),
                 feels_like=current_data.get("apparent_temperature"),
@@ -282,15 +303,16 @@ class OpenMeteoProvider(WeatherProvider):
                 condition=WMO_CODE_MAP.get(weather_code, WeatherCondition.UNKNOWN),
                 condition_text=WMO_DESCRIPTIONS.get(weather_code, "Unknown"),
                 timestamp=datetime.now(),
-                location=location.name
+                location=location.name,
+                uv_index=uv_index
             )
 
             # Parse daily forecast
-            daily_data = data.get("daily", {})
             daily = []
             dates = daily_data.get("time", [])
             for i, date_str in enumerate(dates):
                 code = daily_data.get("weather_code", [])[i] if i < len(daily_data.get("weather_code", [])) else 0
+                uv_max = daily_data.get("uv_index_max", [])[i] if i < len(daily_data.get("uv_index_max", [])) else None
                 daily.append(DayForecast(
                     date=datetime.fromisoformat(date_str),
                     temp_high=daily_data.get("temperature_2m_max", [])[i] if i < len(daily_data.get("temperature_2m_max", [])) else 0.0,
@@ -298,7 +320,8 @@ class OpenMeteoProvider(WeatherProvider):
                     condition=WMO_CODE_MAP.get(code, WeatherCondition.UNKNOWN),
                     condition_text=WMO_DESCRIPTIONS.get(code, "Unknown"),
                     precipitation_chance=daily_data.get("precipitation_probability_max", [])[i] if i < len(daily_data.get("precipitation_probability_max", [])) else None,
-                    precipitation_mm=daily_data.get("precipitation_sum", [])[i] if i < len(daily_data.get("precipitation_sum", [])) else None
+                    precipitation_mm=daily_data.get("precipitation_sum", [])[i] if i < len(daily_data.get("precipitation_sum", [])) else None,
+                    uv_index_max=uv_max
                 ))
 
             return WeatherForecast(
@@ -309,3 +332,110 @@ class OpenMeteoProvider(WeatherProvider):
         except httpx.HTTPError as e:
             logger.error(f"Forecast request failed for {location.name}: {e}")
             raise ValueError(f"Failed to get forecast: {e}")
+
+    async def get_sun_times(self, location: GeoLocation) -> SunTimes:
+        """
+        Get sunrise/sunset times for today.
+
+        Args:
+            location: GeoLocation with lat/long
+
+        Returns:
+            SunTimes with sunrise, sunset, and daylight duration
+
+        Raises:
+            ValueError: If API request fails
+        """
+        try:
+            response = await self.client.get(
+                self.WEATHER_URL,
+                params={
+                    "latitude": location.latitude,
+                    "longitude": location.longitude,
+                    "daily": [
+                        "sunrise",
+                        "sunset",
+                        "daylight_duration"
+                    ],
+                    "timezone": self.timezone,
+                    "forecast_days": 1
+                }
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            daily = data.get("daily", {})
+            date_str = daily.get("time", [""])[0]
+            sunrise_str = daily.get("sunrise", [""])[0]
+            sunset_str = daily.get("sunset", [""])[0]
+            daylight = daily.get("daylight_duration", [0])[0]
+
+            return SunTimes(
+                location=location.name,
+                date=datetime.fromisoformat(date_str) if date_str else datetime.now(),
+                sunrise=datetime.fromisoformat(sunrise_str) if sunrise_str else datetime.now(),
+                sunset=datetime.fromisoformat(sunset_str) if sunset_str else datetime.now(),
+                daylight_duration=int(daylight) if daylight else 0
+            )
+        except httpx.HTTPError as e:
+            logger.error(f"Sun times request failed for {location.name}: {e}")
+            raise ValueError(f"Failed to get sun times: {e}")
+
+    async def get_air_quality(self, location: GeoLocation) -> AirQuality:
+        """
+        Get current air quality for a location.
+
+        Args:
+            location: GeoLocation with lat/long
+
+        Returns:
+            AirQuality with pollutant measurements and AQI
+
+        Raises:
+            ValueError: If API request fails
+        """
+        try:
+            response = await self.client.get(
+                self.AIR_QUALITY_URL,
+                params={
+                    "latitude": location.latitude,
+                    "longitude": location.longitude,
+                    "current": [
+                        "european_aqi",
+                        "us_aqi",
+                        "pm2_5",
+                        "pm10",
+                        "ozone",
+                        "nitrogen_dioxide",
+                        "sulphur_dioxide",
+                        "carbon_monoxide",
+                        "grass_pollen",
+                        "birch_pollen",
+                        "alder_pollen"
+                    ],
+                    "timezone": self.timezone
+                }
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            current = data.get("current", {})
+
+            return AirQuality(
+                location=location.name,
+                timestamp=datetime.now(),
+                aqi_european=current.get("european_aqi"),
+                aqi_us=current.get("us_aqi"),
+                pm2_5=current.get("pm2_5"),
+                pm10=current.get("pm10"),
+                ozone=current.get("ozone"),
+                nitrogen_dioxide=current.get("nitrogen_dioxide"),
+                sulphur_dioxide=current.get("sulphur_dioxide"),
+                carbon_monoxide=current.get("carbon_monoxide"),
+                pollen_grass=current.get("grass_pollen"),
+                pollen_birch=current.get("birch_pollen"),
+                pollen_alder=current.get("alder_pollen")
+            )
+        except httpx.HTTPError as e:
+            logger.error(f"Air quality request failed for {location.name}: {e}")
+            raise ValueError(f"Failed to get air quality: {e}")