WeatherAgent AI (Day 2 of 7-Day AI Coding Challenge)

An autonomous AI-powered weather decision agent. The application takes a city name, fetches real-time coordinates and weather data using the free Open-Meteo API, feeds the data to an LLM (Agnes AI) alongside predefined "tools" (function schemas), and allows the AI to autonomously decide which action to take.

The entire step-by-step reasoning trace of the agent is displayed dynamically in a sleek, glassmorphic cartoon-styled UI.

---

🌟 Key Features

• True LLM Tool/Function Calling — Integrates OpenAI-compatible tools schemas, allowing the LLM (agnes-2.0-flash) to choose the appropriate tool and generate parameters based on the weather conditions.
• Agentic Reasoning Trace — Shows a vertical stepper timeline (Geocoding → Weather Retrieval → Agnes AI Reasoning → Action Selected) to visualize the agent's internal thought process.
• Hybrid Autocomplete Search — A snappy autocomplete dropdown that merges an instant offline country and popular cities dictionary with online Open-Meteo geocoding results, matching names like "Kuala Lumpur" instantly.
• Glassmorphism & Cartoon Theme — A beautiful, playful UI style featuring animated floating cartoon clouds and raindrops in the background.
• Zero-setup Weather Integration — Queries the Open-Meteo Geocoding and Forecast API which are completely free and require no keys.

---

🛠️ The Agent's Tools

The AI Agent evaluates the real-time weather parameters and autonomously selects one of the following tools:

1. send_rain_alert(city, message) — Triggers if rain, drizzle, or storms are detected or expected.
2. suggest_outdoor_activity(city, weather_condition, activity_suggestion) — Triggers if the weather is clear, sunny, or pleasant.
3. suggest_indoor_activity(city, weather_condition, activity_suggestion) — Triggers if the weather is sub-optimal (cold, overcast, hot) but not dangerous.
4. send_extreme_weather_warning(city, severity, warning_message) — Triggers if hazardous conditions exist (extreme heat, freezing cold, strong winds).

---

⚙️ Tech Stack

Layer	Technology
Backend	FastAPI (Python 3.9+), Uvicorn
HTTP Client	HTTPX (for async API requests)
LLM Engine	Agnes AI API (OpenAI-compatible client)
Frontend	HTML5, Vanilla CSS3 (Custom Glassmorphism/Animations), Vanilla JS
Geocoding & Weather	Open-Meteo API

---

🚀 Setup & Installation

Prerequisites

• Python 3.9+ installed
• An Agnes AI API key (from platform.agnes-ai.com)

Installation Steps

1. Clone the repository and go to the project directory:

   git clone <your-repo-url>
   cd WeatherAgent-AI

2. Initialize and activate virtual environment:

   # Windows (PowerShell)
   python -m venv venv
   .\venv\Scripts\activate
   
   # macOS/Linux
   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment variables: Copy the example environment file and insert your API Key:

   # Windows
   copy .env.example .env
   
   # macOS/Linux
   cp .env.example .env

   Open .env and fill in:

   AGNES_API_KEY=your_actual_key_here

5. Start the local server:

   uvicorn main:app --reload

6. Test the app: Open http://127.0.0.1:8000 in your web browser.

---

💡 Interview Notes (AI Developer Focus)

If asked about this project in an interview, here are the key architectural details to discuss:

• How Tool Calling Works: Explain that you do not call the python functions directly during the LLM call. Instead, you send the JSON description schemas of the tools. The model determines which tool should be called based on the weather context and returns the name and argument values (e.g. {"city": "Cairo", "message": "..."}). Your backend parses this JSON and executes the corresponding local python helper.
• Async I/O in FastAPI: The backend endpoints are fully asynchronous. Network requests to geocoding, forecast, and LLM APIs run using async/await and httpx.AsyncClient to avoid blocking the main server thread, maintaining responsiveness.
• UX & Autocomplete: Explain the hybrid autocomplete implementation: resolving the "delayed network query" issue by matching popular cities and countries instantly from a local offline dictionary and merging online API results in parallel.