Weather Integration

Iris integrates with tomorrow.io to give her environmental awareness. Current conditions, short-term precipitation, and air quality automatically appear in every conversation — so when you mention outdoor plans, Iris already knows whether it's raining.

Features

• Ambient context: Current conditions, feels-like temperature, humidity, wind, and air quality injected into every conversation automatically
• Precipitation outlook: Hourly precipitation probability for the next 4 hours
• Daily range: Today's forecast high and low
• On-demand weather tool: Query detailed forecasts (hourly up to 120h, daily up to 5 days) or real-time conditions for any location
• Air quality: EPA AQI headline in ambient context; full breakdown (index value, primary pollutant) available via the weather tool
• Unit preferences: Imperial (°F, mph) or Metric (°C, m/s) per user

How It Works

Tomorrow.io's forecast API is called once and cached using stale-while-revalidate. The resulting context is injected into Iris's system prompt alongside calendar context — so she can connect "you have a 2pm outdoor meeting" with "rain starts at 1:30pm" without being asked.

Caching windows:

• Ambient context: 30-minute fresh window, 60-minute stale window
• On-demand tool queries: 5-minute fresh, 15-minute stale
• Weather data for your configured location is shared between the ambient context and the tool — asking "what's the weather?" after Iris already loaded context doesn't trigger a second API call

When no location is configured, the weather section is silently omitted from the system prompt. No errors, no placeholders.

Setup

1. Get a Tomorrow.io API Key

1. Go to tomorrow.io and create a free account
2. From your dashboard, navigate to Development → API Keys
3. Create a new key and copy it

TIP

The free tier covers real-time conditions, hourly forecasts (up to 120 hours), and daily forecasts (up to 5 days) — everything Iris needs.

2. Configure Environment

Add these to your .env:

IRIS_WEATHER_ENABLED=true
TOMORROW_IO_API_KEY=your-api-key-here

3. Set Your Location

1. Open Iris and go to Settings → Weather
2. Enter your location — accepts city name, US zip code, or lat/lon coordinates:
   • Orlando, FL
   • 32801
   • 28.54,-81.38
3. Choose your preferred units (Imperial or Metric)
4. Click Save

Iris validates your location against tomorrow.io on save and shows the matched name so you can confirm the right place was resolved.

Ambient Context

Once configured, the weather section appears in Iris's system prompt automatically:

## Current Weather (Orlando, FL)
Partly Cloudy, 72.0°F (feels like 75.0°F)
Humidity: 65% | Wind: 8.0 mph
Air Quality: Good
Today: High 78.0°F / Low 62.0°F

### Next 4 Hours
- 1:00 PM: 20% chance of precipitation
- 2:00 PM: 45% chance of precipitation
- 3:00 PM: 80% chance of precipitation
- 4:00 PM: 60% chance of precipitation

Iris uses this context to make weather-relevant observations without being prompted:

You: "Should I take the kids to the park this afternoon?"

Iris: "Rain is likely by 3pm with an 80% chance — if you go, aim for before 2pm to beat it."

Weather Tool

Iris can look up weather for any location on demand using the get_weather tool.

Parameter	Description
location	City name, zip code, or lat/lon coordinates. Omit to use your configured default.
forecast_type	realtime (precise current conditions), hourly (next 120 hours), or daily (next 5 days). Default: hourly.

Units always come from your user settings — there's no way to request a different unit system per query.

Example queries Iris can handle with this tool:

• "What's the weather in Chicago this weekend?"
• "Is it going to rain in Denver tomorrow?"
• "What's the air quality right now?" (uses your configured location)
• "Give me a 5-day forecast for Miami"

Air Quality

Air quality context is included because both the AQI and its health concern level are directly relevant to outdoor activity planning. The ambient context shows a headline:

Air Quality: Unhealthy for Sensitive Groups

For more detail — the EPA index value, primary pollutant — ask Iris to look it up with the weather tool:

You: "What's the full air quality breakdown for today?"

Iris: (calls get_weather with forecast_type: realtime)

Iris: "Air quality is currently at EPA index 2 — Unhealthy for Sensitive Groups. The primary pollutant is PM2.5. I'd hold off on outdoor exercise today."

Configuration

Environment Variable	Default	Description
IRIS_WEATHER_ENABLED	false	Enable weather integration
TOMORROW_IO_API_KEY	—	Your tomorrow.io API key

The iris.weather config block in config/iris.php exposes additional tuning options:

Setting	Default	Description
cache_ttl	30	Fresh window for ambient context cache (minutes)
stale_ttl	60	Stale window for ambient context cache (minutes)
tool_cache_ttl	5	Fresh window for on-demand tool queries (minutes)
tool_stale_ttl	15	Stale window for on-demand tool queries (minutes)
http_timeout	10	Max seconds to wait for API response
http_connect_timeout	5	Max seconds to establish TCP connection

User Settings

Each user controls their own weather context from Settings → Weather:

Setting	Description
Location	City name, zip code, or lat/lon. Validated against tomorrow.io on save.
Units	Imperial (°F, mph) or Metric (°C, m/s).

Changing the location immediately invalidates the cache so the next conversation fetches fresh data for the new location.

Disabling Weather

• System-wide: Set IRIS_WEATHER_ENABLED=false in your .env. The Settings → Weather page shows a "not available" message and the nav item is hidden. No API calls are made.
• Per-user: Clear the location field in Settings → Weather. The weather section is silently omitted from the system prompt when no location is set.