README.md

---
title: Weather App
emoji: 🌤️
colorFrom: gray
colorTo: blue
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
---

agent-demo-track

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference


# agent-demo-track


# 📹 Video Overview

[![Weather App Pro Enhanced Demo](https://img.youtube.com/vi/2F2jrSrjy20/0.jpg)](https://www.youtube.com/watch?v=2F2jrSrjy20)

Watch our video overview to learn about the app's features and how to get the most out of the AI-powered weather assistant.

![Data Processing Flow](static/images/graphs/Data_Processing_Flow.png)
*Weather Data Processing Flow: Visualizing how data moves through the system, from acquisition to user presentation*

![Advanced System Architecture](static/images/graphs/advanced_system_architecture.png)
*System Architecture: Illustrating the integration between LlamaIndex, Gemini API, and the weather data processing components*

# 🌤️ Weather App Pro Enhanced - Complete Package

## 🚀 **NEW: Full AI Integration with LlamaIndex & Gemini!**

This is the **COMPLETE** Weather App Pro package with **full LLM integration** for intelligent weather conversations.

### 🤖 **Enhanced AI Features**

#### **LlamaIndex Integration**
- **Document Understanding**: Advanced context processing
- **Memory Management**: Maintains conversation context
- **Vector Search**: Intelligent information retrieval
- **Chat Engine**: Sophisticated conversation handling

#### **Gemini API Integration**
- **Google's Gemini Pro**: State-of-the-art language model
- **Natural Conversations**: Human-like weather discussions
- **Smart Responses**: Context-aware and informative
- **Fallback System**: Works even without API key

#### **🆕 Conversational Weather Intelligence**
- **Activity Advice**: "Should I go biking in Seattle?" - Get weather-based recommendations
- **Forecast Queries**: Natural language forecast requests with timeline awareness
- **Historical Comparisons**: "How does today compare to normal?" context
- **Safety Considerations**: Intelligent warnings for outdoor activities
- **Multi-City Analysis**: Smart comparisons between locations
- **Personalized Responses**: Context-aware advice for your specific needs

> 📖 **See [CONVERSATIONAL_FEATURES.md](CONVERSATIONAL_FEATURES.md) for detailed examples and usage guide**

### 📁 **Complete Project Structure**

```
weather_app_complete/
├── enhanced_main.py         # 🆕 Enhanced app with full AI
├── app.py                   # Standalone version (Hugging Face ready)
├── main.py                  # Basic modular version
├── requirements.txt         # Updated with LlamaIndex & Gemini
├── run_enhanced.sh          # 🆕 Enhanced quick start script
├── run.sh                   # Basic quick start (Linux/Mac)
├── run.bat                  # Basic quick start (Windows)
├── README.md               # This comprehensive guide
├── INSTALLATION.md         # Detailed setup instructions
├── src/                    # Complete modular architecture
│   ├── __init__.py
│   ├── ai/                 # Multi-AI provider system
│   │   ├── __init__.py
│   │   └── multi_provider.py
│   ├── analysis/           # Climate analysis & ML
│   │   ├── __init__.py
│   │   └── climate_analyzer.py
│   ├── api/                # Advanced weather API client
│   │   ├── __init__.py
│   │   └── weather_client.py
│   ├── chatbot/            # 🆕 Enhanced chatbot system
│   │   ├── __init__.py
│   │   ├── nlp_processor.py
│   │   └── enhanced_chatbot.py  # 🆕 Full LLM integration
│   ├── geovisor/          # Interactive maps & visualization
│   │   ├── __init__.py
│   │   └── map_manager.py
│   ├── mcp_server/        # MCP protocol support
│   │   └── __init__.py
│   └── utils/             # Utility functions
│       └── __init__.py
├── static/                # Static assets
├── templates/             # HTML templates
├── data/                  # Data storage
└── logs/                  # Application logs
```

## 🚀 **Quick Start Options**

### **Option 1: Enhanced AI Version (Recommended)**
```bash
# Extract the package
tar -xzf weather_app_complete_ENHANCED.tar.gz
cd weather_app_complete

# Set Gemini API key for full AI features
export GEMINI_API_KEY="your-gemini-api-key"

# Run enhanced version
./run_enhanced.sh
```

### **Option 2: Standalone Version (Hugging Face)**
```bash
# For Hugging Face Spaces deployment
python app.py
```

### **Option 3: Basic Modular Version**
```bash
# Basic version without advanced AI
./run.sh
```

## 🤖 **AI Configuration**

### **Gemini API Key (Recommended)**
```bash
# Get your free API key from: https://makersuite.google.com/app/apikey
export GEMINI_API_KEY="your-gemini-api-key-here"
```

### **Optional: Additional AI Providers**
```bash
export OPENAI_API_KEY="your-openai-key"
export CLAUDE_API_KEY="your-claude-key"
```

## 💬 **Enhanced Conversation Examples**

The AI now provides **intelligent, contextual responses**:

### **Simple Query**
**User:** "What's the temperature in Wichita?"
**AI:** "The current temperature in Wichita is 72°F with partly cloudy skies. It's a pleasant day with light winds from the southwest at 8 mph. The humidity is comfortable at 45%, making it feel quite nice outside. Perfect weather for outdoor activities!"

### **Comparison Query**
**User:** "Compare rain in New York and Miami"
**AI:** "Great question! Looking at the current conditions:

🗽 **New York**: 15% chance of rain, mostly sunny with 68°F
🏖️ **Miami**: 65% chance of rain, scattered thunderstorms with 82°F

Miami has a significantly higher chance of precipitation today - about 50% more likely than New York. This is typical for Miami's subtropical climate, especially during summer months when afternoon thunderstorms are common. New York is experiencing a drier weather pattern today with high pressure dominating the region."

### **Complex Analysis**
**User:** "Should I plan outdoor activities in Denver this weekend?"
**AI:** "Based on Denver's weekend forecast, here's my recommendation:

**Saturday**: Excellent for outdoor activities! 75°F, sunny skies, light winds. Perfect hiking or biking weather.

**Sunday**: Plan indoor alternatives. 30% chance of afternoon thunderstorms, temperatures dropping to 65°F with gusty winds up to 25 mph.

**Recommendation**: Schedule your outdoor activities for Saturday morning through early afternoon. If you must be outside Sunday, plan for earlier in the day before the storm system moves in around 2 PM."

## 🌟 **Key Enhancements**

### **🧠 Intelligent Responses**
- **Context Awareness**: Remembers conversation history
- **Weather Expertise**: Trained on meteorological knowledge
- **Practical Advice**: Offers actionable recommendations
- **Natural Language**: Human-like conversation flow

### **🗺️ Dynamic Map Integration**
- **Auto-Focus**: Map zooms to mentioned cities automatically
- **Smart Markers**: Rich weather information in popups
- **Comparison Lines**: Visual connections between compared cities
- **Weather Layers**: Precipitation radar and overlays

### **📊 Advanced Analytics**
- **Real-time Processing**: Instant weather data analysis
- **Trend Recognition**: Identifies weather patterns
- **Anomaly Detection**: Highlights unusual conditions
- **Predictive Insights**: Future weather implications

## 🔧 **Technical Features**

### **LlamaIndex Integration**
- **Vector Store**: Efficient weather knowledge retrieval
- **Chat Memory**: Maintains conversation context
- **Document Processing**: Weather data understanding
- **Query Engine**: Intelligent information synthesis

### **Gemini API Features**
- **Advanced NLP**: Superior language understanding
- **Context Retention**: Multi-turn conversations
- **Weather Expertise**: Domain-specific knowledge
- **Error Handling**: Graceful fallback mechanisms

### **Robust Architecture**
- **Modular Design**: Clean, maintainable code
- **Error Recovery**: Handles API failures gracefully
- **Performance Optimized**: Fast response times
- **Scalable**: Ready for production deployment

## 📱 **Deployment Options**

### **Hugging Face Spaces**
1. Upload `app.py` and `requirements.txt`
2. Add `GEMINI_API_KEY` in Space settings
3. Select Gradio SDK
4. Auto-deploys with full AI features!

### **Local Development**
```bash
pip install -r requirements.txt
export GEMINI_API_KEY="your-key"
python enhanced_main.py
```

### **Docker Deployment**
```dockerfile
FROM python:3.9
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
ENV GEMINI_API_KEY="your-key"
CMD ["python", "enhanced_main.py"]
```

## 🆘 **Troubleshooting**

### **AI Features Not Working**
1. Verify Gemini API key is set correctly
2. Check internet connection
3. Ensure API key has proper permissions
4. App works in basic mode without API key

### **Import Errors**
1. Install all requirements: `pip install -r requirements.txt`
2. Check Python version (3.7+ required)
3. Verify all files are in correct structure

### **Performance Issues**
1. Ensure stable internet connection
2. Check system resources (512MB RAM minimum)
3. Try basic version if enhanced is slow

## 🌟 **What's New in Enhanced Version**

✅ **Full LlamaIndex Integration** - Advanced AI framework  
✅ **Gemini API Integration** - Google's powerful LLM  
✅ **Intelligent Conversations** - Context-aware responses  
✅ **Enhanced NLP** - Better query understanding  
✅ **Memory Management** - Conversation history retention  
✅ **Weather Expertise** - Domain-specific knowledge  
✅ **Fallback Systems** - Works without API keys  
✅ **Performance Optimized** - Fast, efficient processing  

---

**🌟 The Most Advanced Weather Intelligence Platform**

*Complete AI integration with LlamaIndex & Gemini for truly intelligent weather conversations!*