Content
# 🌤️ 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.
[](https://www.python.org/downloads/)
[](https://fastapi.tiangolo.com/)
[](https://www.docker.com/)
[](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>
