smart-trip

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

# SmartTripClaw orchestrates the three agents

def recommend_trip_windows(origin, destination, city, country, 
                           min_nights, max_nights):
    
    # 5A: Find calendar windows
    windows = CalendarWindow.find_windows(
        min_nights=min_nights,
        max_nights=max_nights
    )
    
    recommendations = []
    
    for window in windows:
        # 5B: Get price-optimized route
        price_option = PriceRouteOptimizer.optimize(
            origin=origin,
            destination=destination,
            city=city,
            dates=window['dates']
        )
        
        # 5C: Check weather for these dates
        weather = WeatherSeasonality.check(
            city=city,
            country=country,
            dates=window['dates']
        )
        
        # Calculate combined score
        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 top 3 with reasoning
    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:

# Step 1: Find calendar windows
windows = CalendarWindow.find_windows(
    min_nights=4, max_nights=7
)

# Step 2: For each window, parallel query
for window in windows:
    flights = FlightClaw.search(origin, destination, window)
    stays = StayClaw.search(city, window)
    weather = Weather.get_forecast(city, window)
    
    # Compute combined metrics
    total_cost = flights['price'] + stays['total']
    duration_score = flights['duration']  # shorter = better
    weather_score = weather['rating']
    
    window['score'] = calculate_score(total_cost, duration_score, weather_score)

# Step 3: Rank and return
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