# 🌤️ Weather Bot with AI-Powered Research

> An intelligent AI assistant that combines real-time weather data, smart web research, and graph database capabilities - all through a simple chat interface.

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
[![MCP](https://img.shields.io/badge/MCP-Enabled-purple.svg)](https://modelcontextprotocol.io/)

---

## 🎯 What is This?

Weather Bot is a smart AI assistant that can:

- 🌡️ **Tell you the weather** - Current conditions and forecasts for any city
- 🔍 **Research topics** - Searches the web and gives you intelligent, grounded answers
- 🗄️ **Store data** - Saves information in a graph database (Neo4j)
- 💬 **Chat naturally** - Just ask questions in plain English

Built using the **Model Context Protocol (MCP)**, it demonstrates how AI can seamlessly interact with multiple tools and data sources.

---

## ✨ Features at a Glance

### 🌡️ Weather Information
- Current weather for any city worldwide
- Multi-day weather forecasts
- Temperature, humidity, and detailed conditions

### 🧠 Intelligent Research
- Automatically searches the web using **Firecrawl**
- Analyzes content with **Ragie** (RAG technology)
- Generates smart answers using **OpenRouter** AI
- All answers are based on real, up-to-date information

### 🗄️ Data Storage
- Uses **Neo4j** graph database
- Store and connect information
- Query your data anytime

### 🎨 Beautiful Interface
- Clean **Streamlit** chat UI
- No coding required - just chat!
- Works in your web browser

---

## 🏗️ How It Works

```mermaid
graph TB
    User[👤 You] -->|Chat| UI[🖥️ Beautiful Chat Interface]
    UI -->|Sends Request| Server[⚙️ AI Brain]
    Server -->|Gets Weather| Weather[🌤️ Weather API]
    Server -->|Searches Web| Web[🔍 Web Scraper]
    Server -->|Analyzes| RAG[📚 Smart Retrieval]
    Server -->|Generates Answer| AI[🤖 AI Model]
    Server -->|Stores Data| DB[(🗄️ Database)]
    
    style UI fill:#4CAF50,stroke:#333,stroke-width:2px,color:#fff
    style Server fill:#2196F3,stroke:#333,stroke-width:2px,color:#fff
    style DB fill:#FF9800,stroke:#333,stroke-width:2px,color:#fff
```

### Three Main Parts

| Component | What It Does | Where to Access |
|-----------|--------------|-----------------|
| 🖥️ **Chat Interface** | Where you type and see responses | http://localhost:8501 |
| ⚙️ **AI Server** | The brain that handles your requests | http://localhost:8000 |
| 🗄️ **Database** | Stores your data | http://localhost:7474 |

---

## 🛠️ Technologies Used

### AI & APIs
- 🤖 **OpenRouter** - Powers the AI responses (supports GPT, Claude, etc.)
- 🔥 **Firecrawl** - Searches and scrapes the web
- 📚 **Ragie** - Smart document retrieval (RAG)
- 🌤️ **OpenWeatherMap** - Real-time weather data

### Core Tech
- 🚀 **FastMCP** - Model Context Protocol framework
- ⚡ **FastAPI** - High-performance backend
- 🎨 **Streamlit** - Interactive user interface
- 🗄️ **Neo4j** - Graph database

### Infrastructure
- 🐳 **Docker** - Easy setup and deployment
- 🐍 **Python** - Programming language

---

## 📦 What You Need

Before starting, you'll need:

### Required Software
- ✅ **Docker Desktop** - [Download here](https://www.docker.com/products/docker-desktop/)

### API Keys (All Free to Start!)
You'll need to sign up for these services and get free API keys:

1. 🌤️ **OpenWeatherMap** - [Get free key](https://openweathermap.org/api)
2. 🔥 **Firecrawl** - [Get free key](https://firecrawl.dev/)
3. 📚 **Ragie** - [Get free key](https://ragie.ai/)
4. 🤖 **OpenRouter** - [Get key](https://openrouter.ai/) (Pay-as-you-go, very cheap)

> 💡 **Don't worry!** All services have free tiers or are very inexpensive to use.

---

## 🚀 Quick Start

### Step 1: Get the Project

Download or clone this project to your computer.

### Step 2: Set Up Your Keys

1. Find the file named `.env.example`
2. Make a copy and rename it to `.env`
3. Open `.env` in any text editor
4. Add your API keys where indicated:

```
OPENWEATHER_API_KEY=paste_your_key_here
FIRECRAWL_API_KEY=paste_your_key_here
RAGIE_API_KEY=paste_your_key_here
OPENROUTER_API_KEY=paste_your_key_here
NEO4J_PASSWORD=choose_a_strong_password
```

### Step 3: Start Everything

Open your terminal/command prompt in the project folder and run:

```
docker-compose up
```

⏳ **Wait 1-2 minutes** for everything to start...

### Step 4: Start Chatting!

Open your web browser and go to:

**http://localhost:8501**

That's it! 🎉

---

## 💬 What Can You Ask?

### Weather Questions
- "What's the weather in Paris?"
- "Give me a 5-day forecast for Tokyo"
- "Is it raining in London right now?"

### Research Questions
- "What are the latest developments in AI?"
- "Research quantum computing advancements"
- "Tell me about climate change solutions"

### Database Commands
- "Store this: Person named Alice, age 30"
- "Show me all the people in the database"
- "Create a connection between Alice and Bob"

> 💡 **Pro Tip:** Just ask naturally! The AI will figure out which tool to use.

---

## 🎯 The 4 Smart Tools

### 1️⃣ Current Weather
Tells you what the weather is like **right now** in any city.

**Ask:** "What's the weather in New York?"

---

### 2️⃣ Weather Forecast
Shows you the weather for the **next few days**.

**Ask:** "Give me a 3-day forecast for Paris"

---

### 3️⃣ Web Research
This is the smart one! It:
1. Searches the web for information
2. Reads and understands the content
3. Gives you a clear, accurate answer

**Ask:** "Research the benefits of meditation"

---

### 4️⃣ Database Storage
Stores information in a graph database (great for connected data).

**Ask:** "Store a person named Alice who knows Bob"

---

## 📂 Project Files

```
weather_bot_gg/
├── 🎨 client.py              # Chat interface
├── ⚙️ server.py              # AI brain with all the tools
├── 🐳 docker-compose.yml     # Starts everything together
├── 📄 requirements.txt       # Python packages needed
├── 🔒 .env                   # Your API keys (keep secret!)
└── 📖 README.md              # This guide
```

---

## 🌐 Access Points

Once everything is running, you can access:

| Service | URL | What It's For |
|---------|-----|---------------|
| 💬 **Chat Interface** | http://localhost:8501 | Talk to the AI |
| 🔧 **API Server** | http://localhost:8000 | Backend server |
| 📊 **API Docs** | http://localhost:8000/docs | Interactive API documentation |
| 🗄️ **Database Browser** | http://localhost:7474 | View stored data visually |

> 🔐 For Neo4j Browser, login with username `neo4j` and your password from `.env`

---

## 🐛 Common Issues

### ❌ Port Already in Use
**Problem:** Another program is using the same port.

**Fix:** Close other applications or change the port in `docker-compose.yml`

---

### ❌ API Key Errors
**Problem:** "API key not set" message appears.

**Fix:** 
1. Check your `.env` file exists
2. Make sure all keys are filled in
3. No extra spaces or quotes around keys
4. Restart Docker: `docker-compose restart`

---

### ❌ Can't Connect to Database
**Problem:** Neo4j errors or connection refused.

**Fix:** Wait! Neo4j takes 30-60 seconds to fully start. Check if it's ready:

```
docker-compose logs neo4j
```

Look for "Started" message.

---

### ❌ Docker Won't Start
**Fix:** Try a clean restart:

```
docker-compose down
docker-compose up --build
```

---

## 📊 Viewing Your Database

1. Go to **http://localhost:7474**
2. Login with:
   - Username: `neo4j`
   - Password: (what you set in `.env`)
3. You'll see a visual interface to explore your data!

---

## 🧪 Testing

### Quick Health Check

Make sure everything works:

1. **Chat Interface:** Go to http://localhost:8501 - You should see the chat
2. **Server:** Go to http://localhost:8000/health - Should say "healthy"
3. **Database:** Go to http://localhost:7474 - Should load the login page

### Try These Questions

1. "What's the weather in London?" → Should get actual weather
2. "Research artificial intelligence" → Should search and answer
3. Simple questions work best at first!

---

## 💡 Tips & Best Practices

### For Best Results
- ✅ Be specific in your questions
- ✅ One question at a time works best
- ✅ Weather: Use city names (not coordinates)
- ✅ Research: Ask clear, focused questions

### Cost Management
- 💰 Most API calls cost less than $0.01
- 💰 OpenWeatherMap is free (up to 1000 calls/day)
- 💰 Research tool is the most expensive (uses AI generation)
- 💰 Monitor your usage in each service's dashboard

### Performance
- ⚡ Weather queries: ~1 second
- ⚡ Research queries: 10-30 seconds (lots of processing!)
- ⚡ Database queries: ~1 second

---

## 🔒 Security Notes

### Keep These Private
- ❌ Never share your `.env` file
- ❌ Never commit API keys to GitHub
- ❌ Change default Neo4j password
- ✅ The `.gitignore` file protects your `.env` automatically

---

## 🎓 Learn More

### About the Technology
- **Model Context Protocol:** https://modelcontextprotocol.io/
- **RAG (Retrieval-Augmented Generation):** AI technique for grounded answers
- **Neo4j:** Graph database for connected information
- **Docker:** Containerization for easy deployment

### Useful Resources
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Streamlit Docs](https://docs.streamlit.io/)
- [Neo4j Cypher Guide](https://neo4j.com/docs/cypher-manual/current/)

---

## 🤝 Contributing

Want to improve this project?

1. Fork the repository
2. Make your changes
3. Test everything works
4. Submit a pull request

Ideas for contributions:
- 🎨 Improve the UI design
- 🔧 Add new tools
- 📚 Better documentation
- 🐛 Fix bugs

---

## 📝 License

MIT License - Free to use and modify!

---

## 🙏 Credits

**Built with:**
- **Model Context Protocol** by Anthropic
- **FastMCP** by Marvin
- All the amazing open-source communities

**Special Thanks:**
- OpenAI, Anthropic, and the AI community
- Docker and Python communities
- Everyone who contributed to the libraries used

---

<div align="center">

### Built with ❤️ using the Model Context Protocol

**Combining AI, Real-Time Data, and Smart Research**

---

⭐ **Star this repo if you found it useful!**

📧 **Questions?** Open an issue on GitHub

🚀 **Happy Chatting!**

</div>