Flights

Step 2: Ask Clarifying Questions (only if needed)

Ask the user ONLY if:

• The city has multiple major airports and the choice matters (e.g., "Which Chicago airport: O'Hare (ORD) or Midway (MDW)?")
• Required information is missing: origin, destination, or date are all required
• A return trip is implied but no return date given

Do NOT ask about optional fields — use sensible defaults:

• Passengers: 1 adult
• Seat: economy
• Stops: no filter
• Currency: USD

Step 3: Run Searches

First, build the binary:

go build -o /tmp/flights-bin ./cmd/flights

Then run searches with the -json flag. Build the command from parsed parameters:

/tmp/flights-bin -origin <CODE> -dest <CODE> -date <YYYY-MM-DD> -json [optional flags]

Flag mapping:

For one-way trips, run a single search. For round trips, use the -return flag — the tool automatically handles both phases (outbound search, then return flight search paired with the best outbound option) and returns a combined result.

Step 4: Filter & Rank Results

One-way JSON structure:

{
  "Best": [ ... ],
  "Other": [ ... ]
}

Round-trip JSON structure:

{
  "outbound": { "Best": [ ... ], "Other": [ ... ] },
  "return": { "Best": [ ... ], "Other": [ ... ] },
  "selected_outbound": { ... }
}

Round-trip pricing: All prices in both the outbound and return sections are total round-trip prices. The outbound prices represent the round-trip cost if you pick that outbound with the cheapest compatible return. The return prices represent the round-trip cost pairing that return with the selected_outbound. Do not add outbound and return prices together — each price is already the full round-trip total.

The selected_outbound shows which outbound flight was auto-selected for pairing with the return results. Return options may only show airlines compatible with the selected outbound.

Each itinerary contains:

• depart_time / arrive_time: formatted as YYYY-MM-DD HH:MM (24-hour)
• travel_duration: e.g., "5h 15m"
• airline_names: array of airlines on the itinerary
• flights: array of individual flight segments with flight_number, airline_name, departure_airport, arrival_airport, departure_time, arrival_time, travel_duration, aircraft
• layovers: array of layover info (empty for nonstop)
• summary.price_cents: price in cents (divide by 100 for display)
• summary.currency: currency code
• summary.flight_numbers: comma-separated flight numbers

Apply post-search filters:

1. Time filters: Parse depart_time and arrive_time (24-hour format) and remove itineraries that violate hard time constraints. Interpret natural language times: "before noon" = arrive by 12:00, "morning" = depart before 12:00, "evening" = depart after 17:00, "red-eye" = depart after 21:00.
2. Airline filters: For "only X" — remove non-matching airlines. For "prefer X" — keep all but rank X airlines higher. For "no X" — remove itineraries with that airline. Match against airline_names array.
3. Stop count: Already handled by -max-stops flag, but double-check if the user specified constraints.

Combine both Best and Other arrays when filtering and ranking.

Step 5: Present Options

Show the top 3-5 options per direction in a markdown table:

| # | Airlines | Flight(s) | Depart | Arrive | Duration | Stops | Price |
|---|----------|-----------|--------|--------|----------|-------|-------|
| 1 | Delta | DL 123 | 6:00 AM | 11:15 AM | 5h 15m | Nonstop | $189 |
| 2 | United | UA 456, UA 789 | 7:30 AM | 2:45 PM | 7h 15m | 1 (ORD) | $142 |

For round trips, show outbound and return in separate tables with a header for each direction. Note which outbound flight the return options are paired with.

After the table, add brief notes:

• Which option best matches their stated priorities
• Notable trade-offs ("Option 2 is $47 cheaper but adds a stop and 2 hours")
• If time filters removed many options, mention it ("Filtered out 12 options that arrived after noon")
• If no results match all constraints, show the closest matches and explain which constraint was relaxed

Formatting rules:

• Convert 24-hour times to 12-hour AM/PM for display
• Show prices as dollars (divide price_cents by 100)
• For round-trip prices, label as "round-trip total" in the table header or a note
• For stops: show "Nonstop" or count with layover airport codes (e.g., "1 (ORD)")