Content
# 🌍 Unified Planner-Executor Multi-Agent Travel Planner
An intelligent multi-agent travel planning system implementing **Planner → Executor → Evaluation → Multi-Agent** workflow with **hackathon-safe hard limits**, built with Google ADK (Agent Development Kit) and Gemini AI.
## 🎯 Core Workflow (Hackathon-Safe)
```
User Query → Memory → Planner → Executor → [Agents] → Quality Evaluation → Optional Refinement → Result
```
**Natural Language Input**: "Plan a 3-day beach vacation to Goa from Mumbai with ₹30000 budget, I love beaches and seafood"
**Output**: Complete travel plan with flights, hotels, attractions, weather forecast, and day-wise itinerary
## 🔒 Safety Features (Demo-Ready)
- ✅ **Hard Tool Call Limits**: MAX 5 total calls (prevents infinite loops)
- ✅ **Quality Evaluation**: Intelligent confidence scoring
- ✅ **Controlled Refinement**: Max 1 refinement call (only if confidence < 70%)
- ✅ **Predictable Runtime**: No runaway agents, no timeouts
- ✅ **Model Fallback**: gemini-2.5-flash-lite → gemini-2.0-flash-lite
---
## 📋 Prerequisites
1. **Python 3.9+**
2. **Google Gemini API Key**: Set in `.env` file as `GEMINI_API_KEY=your_key_here`
---
## 🚀 Quick Start
### Installation
```bash
# Install dependencies
pip install -r requirements.txt
# Set API key in .env file
echo "GEMINI_API_KEY=your_api_key_here" > .env
```
**Key Dependencies**:
- `google-adk` - Agent Development Kit
- `google-genai` - Gemini API
- `pydantic` - Data validation
- `python-dotenv` - Environment variables
- `tenacity` - Retry logic
- `rfc3987` - URI validation
### Run the Application
```bash
# Main application (recommended)
python run.py
# OR directly
python src/main_hybrid.py
```
---
## 📁 **Main Files Used** (Production Flow)
### **🔥 Core Files - ACTIVELY USED**
| File | Purpose | Status |
|------|---------|--------|
| **`src/main_hybrid.py`** | 🎯 **Main entry point** - User interface & workflow initiation | ✅ MAIN |
| **`src/unified_orchestrator.py`** | 🧠 **Orchestrator** - Planner → Executor → Evaluation → Synthesis | ✅ MAIN |
| **`src/planner.py`** | 📋 **Planner Agent** - Breaks queries into subtasks (ReAct) | ✅ MAIN |
| **`src/executor.py`** | ⚙️ **Executor** - Routes tasks to specialized agents with limits | ✅ MAIN |
| **`src/hybrid_multi_agent.py`** | 🤖 **Multi-Agent System** - 4 specialized agents | ✅ MAIN |
| **`src/tool_limiter.py`** | 🔒 **Tool Call Limiter** - Enforces hard caps (MAX 5 calls) | ✅ NEW |
| **`src/weather_agent.py`** | 🌤️ **Weather Agent** - Forecast integration | ✅ NEW |
| **`src/model_config.py`** | 🔄 **Model Fallback** - Handles quota limits | ✅ NEW |
| **`src/structured_tools.py`** | 🛠️ **Structured Tools** - Parameter extraction | ✅ NEW |
| **`src/memory.py`** | 💾 **Memory Module** - User history & preferences | ✅ MAIN |
| **`src/retry_handler.py`** | 🔁 **Retry Logic** - Resilient API calls | ✅ MAIN |
| **`run.py`** | 🚀 **Entry Point** - Launches main_hybrid.py | ✅ MAIN |
### **📚 Supporting Files**
| File | Purpose | Usage |
|------|---------|-------|
| `src/models.py` | Data models (Pydantic) | Supporting |
| `src/tools.py` | Helper tools (mock data) | Supporting |
| `requirements.txt` | Python dependencies | Config |
| `.env` | API keys configuration | Config |
| `user_memory.json` | User data persistence | Data |
| `hybrid_agent_usage.log` | Execution logs | Runtime |
### **🧪 Test Files**
| File | Purpose | Usage |
|------|---------|-------|
| `tests/test_weather_flow.py` | 🌤️ Test weather integration | ✅ NEW |
| `tests/test_weather_integration.py` | Test weather agent | ✅ NEW |
| `tests/demo_free_browser_tools.py` | Browser tool demos | Optional |
| `tests/demo_real_booking_sites.py` | Booking site demos | Optional |
| `tests/test_computer_use.py` | Computer use tests | Optional |
### **📖 Documentation Files**
| File | Purpose |
|------|---------|
| **`WORKFLOW_COMPLETE.md`** | Complete workflow documentation |
| `README.md` | This file - Project overview |
| `IMPLEMENTATION_PLAN.md` | Implementation notes |
| `rules.md` | Development rules |
### **🗂️ Legacy/Reference Files**
| Directory/File | Purpose | Status |
|----------------|---------|--------|
| `src/main.py` | Old main file | ⚠️ Legacy |
| `src/grounding_utils.py` | Grounding utilities | Supporting |
| `adk-docs/` | Google ADK documentation | Reference |
| `gemini_docs/` | Gemini API documentation | Reference |
---
## 🏗️ **Architecture Overview**
### **Step-by-Step Workflow**
```
┌─────────────────────────────────────────────┐
│ 1. USER QUERY (Natural Language) │
│ "Plan 3-day trip to Goa, ₹30k budget" │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 2. MEMORY MODULE (src/memory.py) │
│ - Load user history │
│ - Load preferences │
│ - Build context │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 3. PLANNER AGENT (src/planner.py) │
│ - Analyzes query with ReAct reasoning │
│ - Extracts parameters │
│ - Creates subtask plan: │
│ • TASK 1: Flight/Hotel search │
│ • TASK 2: Attractions search │
│ • TASK 2B: Weather forecast │
│ • TASK 3: Itinerary creation │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 4. EXECUTOR (src/executor.py) │
│ 🔒 Tool Limiter: MAX 5 calls │
│ Routes tasks to agents: │
│ │
│ ┌────────────────────────────────────┐ │
│ │ TASK 1: FlightHotelAgent (1 call) │ │
│ │ (src/hybrid_multi_agent.py) │ │
│ │ - Google Search for flights/hotels │ │
│ └────────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────────┐ │
│ │ TASK 2: MapsGroundingAgent (1) │ │
│ │ (src/hybrid_multi_agent.py) │ │
│ │ - Google Maps for attractions │ │
│ └────────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────────┐ │
│ │ TASK 2B: WeatherAgent (1 call) │ │
│ │ (src/weather_agent.py) │ │
│ │ - Weather forecast tool │ │
│ └────────────────────────────────────┘ │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 5. QUALITY EVALUATION │
│ (src/tool_limiter.py) │
│ - Check data completeness │
│ - Calculate confidence score │
│ - Decide if refinement needed │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 6. OPTIONAL REFINEMENT (max 1 call) │
│ IF confidence < 70%: │
│ - Refine weakest data source │
│ ELSE: Skip refinement │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 7. ITINERARY SYNTHESIS │
│ ItineraryAgent combines all data │
│ - Flights + Hotels + Attractions │
│ - Weather-aware scheduling │
│ - Day-wise breakdown │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 5. FINAL RESULT │
│ - Complete travel plan │
│ - Flights, hotels, attractions │
│ - Day-wise itinerary │
│ - Budget breakdown │
└─────────────────────────────────────────────┘
```
**All coordination handled by**: `src/unified_orchestrator.py`
---
## 🎮 Usage Examples
### **Option 1: Run Main Application (Recommended)**
```bash
python run.py
```
**Natural Language Input Example**:
```
"Plan a 3-day beach vacation to Goa from Mumbai.
My budget is ₹30000. I love beaches, seafood, and nightlife."
```
**Or use structured input** if you prefer:
```
From: Mumbai
To: Goa
Duration: 3 days
Budget: ₹30000
Interests: beaches, food, nightlife
```
### **Option 2: Run Tests**
**Full workflow test**:
```bash
python test_unified_workflow.py
```
**Quick test**:
```bash
python test_unified_workflow.py --quick
```
---
## 🤖 **Agents & Technologies**
### **Multi-Agent System**
1. **Planner Agent** (`src/planner.py`)
- Model: `gemini-2.5-flash-lite` (fallback: `gemini-2.0-flash-lite`)
- Pattern: ReAct (Reasoning + Acting)
- Purpose: Task decomposition
- Calls: 1 (planning phase only)
2. **FlightHotelAgent** (`src/hybrid_multi_agent.py`)
- Model: `gemini-2.5-flash-lite` (fallback: `gemini-2.0-flash-lite`)
- Tool: Google Search grounding
- Purpose: Find flights and hotels
- Max Calls: 1 + optional 1 refinement
3. **MapsGroundingAgent** (`src/hybrid_multi_agent.py`)
- Model: `gemini-2.5-flash`
- Tool: Google Maps grounding
- Purpose: Find attractions and places
- Max Calls: 1 + optional 1 refinement
4. **WeatherForecastAgent** (`src/weather_agent.py`) 🆕
- Model: `gemini-2.5-flash-lite` (fallback: `gemini-2.0-flash-lite`)
- Tool: Google Weather API
- Purpose: 3-day weather forecast
- Max Calls: 1 + optional 1 refinement
5. **ItineraryAgent** (`src/hybrid_multi_agent.py`)
- Model: `gemini-2.5-flash-lite` (fallback: `gemini-2.0-flash-lite`)
- Purpose: Synthesize final itinerary
- Calls: 1 (synthesis phase only)
### **Control Systems** 🔒
6. **Tool Call Limiter** (`src/tool_limiter.py`) 🆕
- **Global Limit**: MAX 5 total tool calls
- **Per-Tool Limits**: 1 call each + max 1 refinement
- **Purpose**: Prevent infinite loops & quota exhaustion
7. **Quality Evaluator** (`src/tool_limiter.py`) 🆕
- **Confidence Scoring**: 0-100%
- **Refinement Trigger**: < 70% confidence
- **Purpose**: Intelligent quality assessment
### **Technologies Used**
- **Google ADK (Agent Development Kit)**: Multi-agent orchestration
- **Google Gemini API**: LLM for reasoning and generation
- **Google Search**: Real-time flight/hotel search
- **Google Maps**: Location-based recommendations
- **Python AsyncIO**: Async agent execution
## ✨ Key Features
### **Core Capabilities**
✅ **Planner-Executor Pattern**: Dynamic task decomposition and routing
✅ **Multi-Agent System**: 5 specialized agents for different domains
✅ **Natural Language Input**: No structured forms needed
✅ **ReAct Reasoning**: Intelligent planning with thought process
✅ **Google Grounding**: Real-time data from Search, Maps & Weather
✅ **Memory & Personalization**: Learns from user history
✅ **Weather Integration**: 3-day forecast with activity recommendations
### **Hackathon-Safe Features** 🔒
✅ **Hard Tool Call Limits**: MAX 5 total calls (prevents runaway agents)
✅ **Quality Evaluation**: Automatic confidence scoring (0-100%)
✅ **Intelligent Refinement**: Max 1 refinement if confidence < 70%
✅ **Model Fallback**: Automatic fallback on quota errors
✅ **Predictable Runtime**: No infinite loops, no timeouts
✅ **Demo-Ready**: Stable execution every time
✅ **Error Resilient**: Retry logic with exponential backoff
### **Production Ready**
✅ **Fully Tested**: Complete test suite
✅ **Documented**: Inline comments + comprehensive docs
✅ **Structured Logging**: Execution tracking and debugging
✅ **Efficient API Usage**: Sequential execution minimizes calls
---
## 📊 Example Output
```
🌍 YOUR COMPLETE TRAVEL PLAN
════════════════════════════════════════════════════════
✈️ Flight Options
• Air India AI-542: Mumbai → Goa | 10:00 AM - 11:30 AM | ₹4,500
• IndiGo 6E-324: Mumbai → Goa | 2:00 PM - 3:30 PM | ₹3,800
• Vistara UK-872: Mumbai → Goa | 6:30 PM - 8:00 PM | ₹5,200
🏨 Hotel Options
• Hotel Goa Beach Resort | ⭐ 4.5 | ₹3,500/night
• Seaside Paradise Inn | ⭐ 4.2 | ₹2,800/night
• Luxury Goa Suites | ⭐ 4.8 | ₹4,200/night
🗺️ Top Attractions
• Baga Beach - Water sports, sunbathing
• Fort Aguada - Historic Portuguese fort
• Tito's Lane - Nightlife hub
• Fisherman's Wharf - Seafood dining
🌤️ Weather Forecast
• Day 1: Sunny, 32°C, UV Index: High - Perfect beach day!
• Day 2: Partly Cloudy, 30°C, Light breeze - Ideal for sightseeing
• Day 3: Sunny, 31°C - Great departure weather
📅 Day-wise Itinerary (Weather-Optimized)
Day 1: Arrival & Beach Exploration
- 10:00 AM: Flight arrives (Sunny weather ☀️)
- 11:30 AM: Check-in at Hotel Goa Beach Resort
- 2:00 PM: Lunch at beach shack
- 4:00 PM: Baga Beach water sports (Take advantage of sunny weather!)
- 8:00 PM: Dinner at Fisherman's Wharf
Day 2: Heritage & Culture
- 9:00 AM: Visit Fort Aguada (Partly cloudy - comfortable for outdoor)
- 12:00 PM: Lunch at local restaurant
- 3:00 PM: Explore Old Goa churches (Indoor during peak heat)
- 7:00 PM: Sunset at Anjuna Beach
- 10:00 PM: Nightlife at Tito's Lane
Day 3: Departure
- 9:00 AM: Last-minute beach walk (Sunny morning)
- 12:00 PM: Check-out
- 2:00 PM: Lunch
- 6:30 PM: Flight departure
💰 Budget Breakdown
• Flights: ₹3,800 × 2 = ₹7,600
• Hotels: ₹3,500 × 2 nights = ₹7,000
• Activities: ₹10,000 (estimated)
• Food: ₹5,000 (estimated)
• Total: ₹29,600 (within budget!)
════════════════════════════════════════════════════════
📊 WORKFLOW EXECUTION SUMMARY
════════════════════════════════════════════════════════
Workflow: Planner → Executor → Evaluation → [Refinement] → Synthesis
Steps: Planning → Task1_FlightHotel → Task2_Attractions → Task2B_Weather → Quality_Evaluation → Task3_Itinerary
Agents: PlannerAgent, FlightHotelAgent, MapsGroundingAgent, WeatherForecastAgent, ItineraryAgent
Time: 60.07 seconds
🔒 Safety Metrics (Hackathon-Safe):
• Tool Calls: 3/5 (hard limit enforced)
• Refinement Used: No (quality sufficient)
• Quality Score: High
• Confidence: 100%
════════════════════════════════════════════════════════
```
---
## 💾 Memory & Personalization
The system automatically saves to `user_memory.json`:
- ✅ Travel history (destinations, dates, budgets)
- ✅ User preferences (interests, patterns)
- ✅ Context for future personalized recommendations
**Example memory.json**:
```json
{
"user_id": "default_user",
"preferences": ["beaches", "food", "nightlife", "culture"],
"history": [
{
"destination": "Goa",
"date": "2025-12-12",
"budget": 30000.0
}
]
}
```
---
## 🔧 Configuration
### Environment Variables
Create a `.env` file:
```bash
GEMINI_API_KEY=your_api_key_here
```
### Model Configuration
**Primary Models**:
- `gemini-2.5-flash-lite` - Fast, cost-effective (most agents)
- `gemini-2.5-flash` - More capable (Maps agent)
**Fallback Chain** (on quota errors):
1. `gemini-2.5-flash-lite` (primary)
2. `gemini-2.0-flash-lite` (fallback)
**Hard Limits** (configured in `src/tool_limiter.py`):
```python
MAX_TOTAL_TOOL_CALLS = 5
TOOL_LIMITS = {
"flight_hotel": 1,
"maps_attractions": 1,
"weather": 1,
"refinement": 1 # Single refinement across all tools
}
```
### API Rate Limits
- **Free tier**: 20 requests/day for gemini-2.5-flash-lite
- **Solution**: Hard limits + fallback models prevent quota exhaustion
- **Upgrade**: Paid tier for higher limits
---
## 📚 Documentation
- **`WORKFLOW_COMPLETE.md`**: Complete technical documentation
- **`README.md`**: This file - Quick start guide
- **`rules.md`**: Development guidelines
- **`adk-docs/`**: Google ADK documentation
- **`gemini_docs/`**: Gemini API references
---
## 🐛 Troubleshooting
### "GEMINI_API_KEY not set"
```bash
echo "GEMINI_API_KEY=your_key" > .env
```
### Rate limit errors
Wait 60 seconds and retry, or use paid tier
### Import errors
```bash
pip install -r requirements.txt
```
---
## 📞 Support & Contributing
- Check `WORKFLOW_COMPLETE.md` for detailed workflow explanation
- Read `rules.md` for development guidelines
- All modules are fully documented with inline comments
---
## 📄 License
Apache 2.0 License
---
## 🎉 Quick Command Reference
```bash
# Run main application
python run.py
# Run complete test
python test_unified_workflow.py
# Run quick test
python test_unified_workflow.py --quick
# Check main files being used
ls src/main_hybrid.py src/unified_orchestrator.py src/planner.py src/executor.py
```
---
**Happy Agent Building!** 🚀
