| name | smart-trip |
| description | Intelligent travel window optimizer and orchestrator. Coordinates CalendarWindow (5A), PriceRouteOptimizer (5B), and WeatherSeasonality (5C) agents to find optimal travel dates. Checks calendar availability, computes cheapest flight+accommodation combinations, validates weather conditions, and ranks top recommendations. Use when user wants to find the best time to travel considering schedule, cost, and weather together. |
Smart Trip Recommender (Agent 5 - Orchestrator)
The brain that brings it all together — calendar, price, and weather.
Sub-Agents Coordinated
This orchestrator manages three specialized agents:
| Sub-Agent | ID | Job |
|---|
| CalendarWindow | 5A | Find feasible date ranges from your calendar |
| PriceRouteOptimizer | 5B | Compute cheapest flight + accommodation combos |
| WeatherSeasonality | 5C | Validate weather and flag bad seasons |
How It Works
┌─────────────────────────────────────────────┐
│ SMART TRIP RECOMMENDER (Orchestrator) │
└─────────────────────────────────────────────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
┌───────┐ ┌────────┐ ┌──────────┐
│ 5A │ │ 5B │ │ 5C │
│Calendar│ │ Price │ │ Weather │
│Window │ │ Route │ │ Check │
└───┬───┘ └───┬────┘ └────┬─────┘
│ │ │
└───────────┼────────────┘
▼
┌───────────────────────┐
│ RANK & COMBINE │
│ Top 5 recommendations │
└───────────────────────┘
Step-by-Step Flow
1. READ user constraints (origin, destination, trip length)
└──
2. CALL 5A: CalendarWindow.find_windows()
└── Returns: List of feasible date ranges
└──
3. FOR EACH date range:
│
├── CALL 5B: PriceRouteOptimizer.optimize()
│ └── Returns: Cheapest flight + stay combo
│
└── CALL 5C: WeatherSeasonality.check()
└── Returns: Weather risk + suitability score
│
└── COMPUTE: Combined score (price + weather + convenience)
4. RANK all options by combined score
5. RETURN: Top 5 recommendations with full details
Example Integration
def recommend_trip_windows(origin, destination, city, country,
min_nights, max_nights):
windows = CalendarWindow.find_windows(
min_nights=min_nights,
max_nights=max_nights
)
recommendations = []
for window in windows:
price_option = PriceRouteOptimizer.optimize(
origin=origin,
destination=destination,
city=city,
dates=window['dates']
)
weather = WeatherSeasonality.check(
city=city,
country=country,
dates=window['dates']
)
score = calculate_combined_score(
price=price_option['total_cost'],
weather_penalty=weather['risk']['score_penalty'],
calendar_score=window['score']
)
recommendations.append({
'dates': window['dates'],
'price': price_option,
'weather': weather,
'total_score': score
})
return sorted(recommendations, key=lambda x: x['total_score'], reverse=True)[:3]
Parameters
| Flag | Description | Example |
|---|
--destination | Where you want to go | BKK, NRT, DPS |
--origin | From airport | SIN, KUL |
--min-nights | Minimum trip length | 3, 5 |
--max-nights | Maximum trip length | 7, 10 |
--flexibility-days | Days you can shift dates | 3, 7 (±days) |
--date-range | Search window | next-30-days, 2025-04:2025-06 |
--optimize | Primary goal | price, weather, balanced |
--calendar-source | Where to check | google, outlook, manual |
--avoid-dates | Blackout dates | 2025-05-01:2025-05-05 |
--budget-max | Max total budget | 500, 1000 (USD) |
Optimization Strategies
| Strategy | What it does | Best for |
|---|
price | Cheapest flight + hotel combo | Budget travelers |
weather | Best weather window | Comfort seekers |
balanced | Good weather, fair price | Most travelers |
events | During festivals/events | Experience hunters |
How It Works
1. READ calendar → CalendarWindow finds available windows
2. FOR each candidate date range:
├── QUERY FlightClaw → Get flight options & prices
├── QUERY StayClaw → Get accommodation prices
├── QUERY Weather → Get forecast for dates
└── COMPUTE combined cost vs duration
3. SCORE each window → Price + weather + convenience
4. RANK options → Present **top 3 recommendations with reasoning**
5. ALERT if booking window optimal (price about to rise)
Agent Flow
SmartTripClaw orchestrates multiple agents:
windows = CalendarWindow.find_windows(
min_nights=4, max_nights=7
)
for window in windows:
flights = FlightClaw.search(origin, destination, window)
stays = StayClaw.search(city, window)
weather = Weather.get_forecast(city, window)
total_cost = flights['price'] + stays['total']
duration_score = flights['duration']
weather_score = weather['rating']
window['score'] = calculate_score(total_cost, duration_score, weather_score)
return sorted(windows, key=lambda x: x['score'], reverse=True)
Output
Top 3 Travel Windows (with Reasoning)
Each recommendation includes:
🥇 OPTION 1: May 15-20 (5 nights)
─────────────────────────────────
📅 Calendar: Perfect fit - no conflicts, uses weekend
💰 Total Cost: $420 (Flight $180 + Hotel $240)
✈️ Route: SIN → BKK direct, 2h 30m
🏨 Stay: On Nut area - 40% cheaper than Sukhumvit
🌤️ Weather: Dry season, 32°C, low humidity
💡 REASONING: Best overall value - good price, great weather,
minimal PTO needed (1 day), perfect timing before rainy season
─────────────────────────────────
🥈 OPTION 2: Jun 5-10 (5 nights)
─────────────────────────────────
📅 Calendar: Good fit - weekend departure
💰 Total Cost: $380 (Flight $150 + Hotel $230)
✈️ Route: SIN → DMK via 1-stop, 4h total
🏨 Stay: Chinatown - budget area with character
🌤️ Weather: Early monsoon, expect afternoon showers
💡 REASONING: Cheapest option but weather risk - good for
budget travelers who don't mind rain, indoor activities
─────────────────────────────────
🥉 OPTION 3: Apr 25-30 (5 nights)
─────────────────────────────────
📅 Calendar: Requires 2 PTO days but long weekend
💰 Total Cost: $510 (Flight $220 + Hotel $290)
✈️ Route: SIN → BKK direct, 2h 30m
🏨 Stay: Sukhumvit central - premium location
🌤️ Weather: Hot season, 35-38°C, very humid
💡 REASONING: Premium option in best location - pay more for
comfort and walkability, weather is hot but manageable
─────────────────────────────────
Reasoning Components
Each option explains:
- Calendar Fit: Why these dates work with your schedule
- Price Breakdown: Where the savings come from
- Route Choice: Why this airport/neighborhood was selected
- Weather Trade-off: Seasonal pros/cons
- Best For: Who this option suits (budget, comfort, adventure)
Smart Recommendations
- "Book now" — prices trending up
- "Wait" — prices may drop
- "Consider" — nearby dates with better value
Calendar Integration
Google Calendar
--calendar-source google --calendar-id primary
Requires OAuth setup (one-time).
Manual (No Integration)
--calendar-source manual --available-dates "2025-05-10:2025-05-20"
Weather Scoring
Weather rated 0-100 based on:
- Temperature comfort (20-28°C ideal)
- Rain probability (<30% good)
- Humidity (40-70% comfortable)
- Historical reliability
Price Forecasting
Uses:
- Historical price data
- Seasonal trends
- Days-until-departure patterns
- Current booking velocity
Data Sources
- Calendar: Google Calendar API, Outlook API, manual
- Flights: Amadeus Price Forecast API, Skyscanner
- Hotels: Booking.com, Amadeus
- Weather: Open-Meteo, wttr.in
- Price trends: Hopper API (if available), historical scrapes
See Also
references/price_forecasting.md — How price prediction works
references/seasonal_data/ — Best/worst times by destination
references/calendar_setup.md — OAuth setup guides