Flight Expert

Overview

Turn a natural-language flight request into an ITA Matrix site payload, add careful routing or extension codes when they express real hard constraints, call the Matrix search flow for both specific-date and calendar searches, and summarize the best results for the user.

Workflow

1. Extract a structured Matrix site payload using references/payloads.md.
2. Ask a concise follow-up only when a missing detail makes the search materially ambiguous or risky. Otherwise make the smallest reasonable assumption and state it.
3. Prefer ordinary fields over advanced codes:
   • Use options.stops, options.cabin, and options.allowAirportChanges before custom codes.
   • Add routing or extension codes only for explicit airline, operating-carrier, sequencing, connection, aircraft, alliance, or fare-basis constraints.
4. When advanced constraints are needed, load references/matrix-codes.md.
5. Save the site payload to a temp JSON file and run:

node scripts/matrix_search.js --payload-file /tmp/request.json --limit 5

• The CLI accepts either one site payload object or an array of site payloads.
• When given an array, it executes all searches concurrently with Promise.all and returns a result array in the same order.

6. Read the returned JSON and answer with:
   • The exact itinerary assumptions you used
   • The top results with price, carrier, key flights, stops, and notable warnings
   • For calendar searches, the cheapest dates or duration combinations
   • Any routing or extension codes you added and why
   • The shareable Matrix URL

Build the Matrix Site Payload

• Use the site payload shape from references/payloads.md. This is the same JSON that gets base64-encoded into the search= URL parameter.
• Keep passenger counts, stop counts, and booleans in the site payload as strings because Matrix serializes them that way.
• For round-trip searches, keep one slice with returnDate*, routingRet, and extRet fields instead of manually duplicating the return slice.
• Prefer airport codes when the user names specific airports. Use metro or city codes only when the user clearly wants broader matching.
• Encode date flexibility with departureDateModifier and returnDateModifier. Example: 11 means minus=1, plus=1.
• Default showOnlyAvailable to "true" unless the user explicitly asks for broader theoretical fare construction.

Routing And Extension Rules

• Routing codes describe airline or segment patterns.
• Extension codes constrain itinerary selection or fare construction.
• Keep them conservative. Overconstraining is worse than underconstraining because it silently drops valid options.
• Mention every non-obvious code you added in the final answer.
• Good default behavior:
  • User asks for nonstop: prefer standard stop handling and, if needed, add routing N.
  • User asks for a specific operating carrier: use routing O:XX.
  • User asks to avoid codeshares: add extension -CODESHARE.
  • User asks to avoid overnight stops: add extension -OVERNIGHTS.
  • User asks to exclude certain airlines: prefer extension -AIRLINES.

Script Outputs

scripts/matrix_search.js returns JSON with:

• matrix_url: shareable Matrix search URL
• site_payload: normalized site payload
• request_body: exact direct API body when --show-request
• summary: compact summary of top solutions
• response: raw Matrix API response when --raw

If the input is a payload array, the script returns an array of those result objects.

For calendar searches, the script generates Matrix bgProgramResponse through agent-browser, so that CLI must be installed and usable in the environment.

Limitations

• scripts/matrix_search.js supports specific and calendar search modes.
• Calendar mode supports one-way and round-trip, not multi-city.
• Calendar mode depends on agent-browser to run the Matrix Botguard challenge in a real browser context.
• If the user asks for constraints Matrix cannot express cleanly, say so plainly and search with the nearest faithful approximation.