Search Flights

Use AskUserQuestion to gather missing required parameters. You can batch related questions together. If $ARGUMENTS covers everything, skip straight to priorities.

Step 2: Ask about ranking priorities

Always ask this, even if arguments are complete. Priorities change per search. Ask something like:

What matters most for this trip?

• Cheapest price
• Shortest flight time
• Fewest stops / nonstop preferred
• Best balance of all factors

Translate the user's answer into RankingWeights:

• Cheapest price: RankingWeights(price=1.0, duration=0.1, stops=0.1)
• Shortest flight: RankingWeights(price=0.2, duration=1.0, stops=0.3)
• Fewest stops: RankingWeights(price=0.2, duration=0.3, stops=1.0)
• Balanced: RankingWeights(price=0.6, duration=0.3, stops=0.3) (default)

Step 3: Execute the search

Run this Python code using the Bash tool (with the project venv):

source .venv/bin/activate && python3 -c "
import json
from flight_finder.scraper import FlightSearchParams, search_flights
from flight_finder.ranking import RankingWeights, rank_flights
from fast_flights import FlightData, Passengers
from fast_flights.filter import TFSData

params = FlightSearchParams(
    origin='<ORIGIN>',
    destination='<DESTINATION>',
    departure_date='<YYYY-MM-DD>',
    return_date='<YYYY-MM-DD or None>',    # Set to None for one-way
    trip_type='<round-trip or one-way>',
    seat='<economy>',
    adults=<1>,
    max_stops=<None or int>,
)

result = search_flights(params)
weights = RankingWeights(price=<P>, duration=<D>, stops=<S>)
ranked = rank_flights(result.flights, weights=weights)

# Build Google Flights URL for validation
flight_data_list = params.build_flight_data()
tfs = TFSData.from_interface(
    flight_data=flight_data_list,
    trip=params.trip_type,
    passengers=Passengers(adults=params.adults),
    seat=params.seat,
    max_stops=params.max_stops,
)
google_flights_url = f'https://www.google.com/travel/flights?tfs={tfs.as_b64().decode()}&hl=en&tfu=EgQIABABIgA'

# Output as JSON for parsing
output = {
    'current_price': result.current_price,
    'total_flights': len(result.flights),
    'google_flights_url': google_flights_url,
    'flights': []
}
for rf in ranked[:15]:
    f = rf.flight
    output['flights'].append({
        'rank': rf.rank,
        'name': f.name,
        'price': rf.price_dollars,
        'duration': f.duration,
        'duration_min': rf.duration_minutes,
        'stops': f.stops,
        'departure': f.departure,
        'arrival': f.arrival,
        'arrival_ahead': f.arrival_time_ahead,
        'is_best': f.is_best,
        'score': round(rf.score, 4),
    })
print(json.dumps(output, indent=2))
"

Adjust the parameters in the script based on what the user specified. If the search fails after retries, report the error and suggest trying again or adjusting parameters.

Step 4: Present results

Format the results as a clear table. Include:

After the table, include:

• Google Flights link: Always include the google_flights_url from the search output as a clickable markdown link (e.g., [View on Google Flights](url)). This lets the user verify results directly. If presenting multiple searches, include a link for each one.
• Price trend: whether current prices are "low", "typical", or "high"
• Total flights found vs how many are shown
• Brief note on why the top result ranked well (e.g., "Cheapest nonstop option" or "Best balance of price and duration")

If the user specified a budget, highlight which flights are within budget and which exceed it.

If the user specified time preferences, note any flights that don't meet them (e.g., redeye departures when user said no redeyes).

Step 5: Offer follow-ups

After presenting results, offer options like:

• "Want me to search nonstop only?" (if results included connections)
• "Try different dates?"
• "Compare with a different airport?"
• "Show more results?"
• "Re-rank with different priorities?"

If the user wants to refine, loop back to the relevant step. No need to re-ask parameters that haven't changed.

Important Notes

• Always activate the venv: source .venv/bin/activate
• The scraper has built-in retry (3 attempts with exponential backoff). If it still fails, it's likely a temporary Google Flights issue.
• Rate limiting (1.5s between requests) is built in — no need to add delays.
• For round-trip, both departure_date and return_date are required.
• Airport codes must be valid IATA codes (3 letters, uppercase).