Provides current weather and forecasts for any location using two free APIs:
Nominatim (OpenStreetMap) for geocoding locations → scripts/geocode.py
Open-Meteo for weather data → scripts/fetch_weather.py
Workflow
Understand the user's request. Extract the location, time range, and whether they're planning travel. See examples below.
Geocode the location by running scripts/geocode.py "<location>". It returns JSON with display_name, lat, lon, and an ambiguous flag. If ambiguous, ask the user to clarify.
If outside forecast horizon, clearly state limits.
"past weather" / "last 3 days" / "yesterday"
daily (or hourly for short windows)
set from request
If user says "past" without a number, default to 7.
The user may specify dates in various formats (MM/DD, DD/MM, "May 1st", "1 March", etc.) — interpret based on context and filter the returned timeline accordingly. Use the current year unless another year is stated or implied.
Use daily for ranges > 3 days, hourly for shorter windows, current for right-now queries (but still include hourly for context).
Default (no time specified): current conditions + next 24 hours hourly.
Remember: Forecast is fixed to 16 days. For past requests, use past_days (0..92).
3. Travel Intent
Detect if the user is planning to go somewhere. Look for keywords like: pack, wear, travel, visiting, going to, headed to, trip, vacation, holiday, outing, flight, should I bring
If travel intent is detected → also include clothing guidance (see below).
Example Outputs
Example 1: Simple current weather
User: "What's the weather in Jeddah now?"
Response:
Weather in Jeddah, Saudi Arabia
Right now it's Clear sky with a temperature of 28°C (feels like 30°C). Wind is light at 12 km/h from the north, and humidity is at 45%. No precipitation expected.
Next few hours:
3 PM: 29°C, Clear sky, 0% rain
4 PM: 28°C, Partly cloudy, 0% rain
5 PM: 26°C, Clear sky, 0% rain (and so on...)
Example 2: Weekend forecast
User: "Forecast for London this weekend"
Response:
Weekend Forecast for London, UK
Saturday, Mar 1: Highs of 11°C, lows of 5°C. Moderate rain expected (70% probability, ~4mm). Wind up to 25 km/h.
Sunday, Mar 2: Highs of 13°C, lows of 6°C. Partly cloudy, 20% rain chance. Lighter wind at 15 km/h.
Overall: A wet Saturday clearing into a drier Sunday. Bring an umbrella for Saturday.
Example 3: Travel planning with clothing advice
User: "I'm going to Tokyo next week — what should I pack?"
Response:
Tokyo, Japan — Next Week Forecast (Mar 3–9)
Day
High
Low
Conditions
Rain
Wind
Mon
12°C
4°C
Partly cloudy
10%
15 km/h
Tue
10°C
3°C
Slight rain
65%
20 km/h
...
...
...
...
...
...
What to Wear: Expect cold conditions (lows near 3°C) with rain mid-week. Pack:
Warm layers: fleece or wool sweater + insulated jacket
Waterproof jacket and umbrella for Tuesday/Wednesday
Closed-toe waterproof shoes
Scarf and light gloves for mornings/evenings
See: clothing_guide.md — sections: cold, rainy
Example 4: Specific condition query
User: "How windy will it be in AlUla on Friday?"
Response:
Wind Forecast for AlUla, Saudi Arabia — Friday, Feb 28
Wind speeds will peak at 35 km/h in the early afternoon, settling to around 15 km/h by evening. Morning winds are lighter at ~10 km/h.
⚠️ Moderately windy conditions expected midday — secure loose items and consider a windbreaker if you'll be outdoors.
Warnings
Include warnings when conditions are notable:
Extreme heat: temp ≥ 40°C
Extreme cold: temp ≤ -10°C
Strong wind: ≥ 50 km/h
Heavy rain: ≥ 20mm precipitation
Clothing Guidance
When travel intent is detected, read references/clothing_guide.md and include relevant advice in the response.
Error Handling
Location not found: Ask the user to be more specific (add city, country).
Ambiguous location: Present the alternatives and ask which one.
API failure / network blocked: Scripts return a JSON error envelope instead of a traceback:
{
"error": {
"code": "NETWORK_UNAVAILABLE",
"message": "Unable to reach remote weather service.",
"details": "URLError: ...",
"retryable": true,
"hint": "Enable outbound network access or rerun with elevated permissions."
}
}
Error codes:
INVALID_INPUT: bad user input (invalid past_days, missing location, no results).
NETWORK_UNAVAILABLE: DNS/connectivity/timeouts to upstream weather APIs.
Operational guidance: If network is blocked in a sandbox, request elevated permissions or run scripts from an environment with outbound internet access.
Beyond forecast horizon: Inform them of the 16-day limit, return what's available.
No time specified: Default to current + next 24 hours.
