Search Flights

Parse the user's natural language into structured search parameters. You must understand common flight booking concepts:

Basic terms (Mandarin / English):

• round-trip: round-trip search
• one-way: one-way search
• layover / stopover: allow stops
• nonstop / direct: max_stops=0

Advanced concepts:

• Ex-origin ticket: Book from a cheaper foreign origin. E.g., booking BKK->PRG->MIL->MUC->BKK is cheaper than PRG->MIL round-trip because BKK is a cheaper origin. The ex-origin legs are positioning flights the user buys separately. Use multi-city with 4 segments.
• 4-segment ticket: A multi-city itinerary with 4 legs. Common pattern for ex-origin tickets.
• Open-jaw: Fly into city A, out of city B (e.g., into MIL, out of MUC)
• Flexible origin: Try multiple cheap origins for ex-origin tickets (BKK, HKG, SIN, KUL, NRT, ICN, MNL)

Airline codes:

• EVA Air = BR, China Airlines = CI, STARLUX = JX, Cathay Pacific = CX
• JAL = JL, ANA = NH, Scoot = TR, Tigerair = IT
• Emirates = EK, Qatar Airways = QR, Turkish Airlines = TK, Lufthansa = LH

City/Airport codes:

• Taipei = TPE (Taoyuan) / TSA (Songshan), Prague = PRG
• Bangkok = BKK / DMK, Milan = MXP / LIN, Munich = MUC
• Hong Kong = HKG, Singapore = SIN, Kuala Lumpur = KUL
• Tokyo = NRT / HND, Seoul = ICN / GMP, Manila = MNL
• Osaka = KIX, Kaohsiung = KHH, Vienna = VIE

Date interpretation (today is !date +%Y-%m-%d):

• Early May = first week (1st, 3rd, 5th, 7th)
• Mid May = middle (13th, 15th, 17th)
• Late May = end (25th, 27th, 29th)
• Summer = July-August, Winter break = January-February
• Next month = relative to today

Step 2: Set up the search infrastructure

Check if the project has search.py. If yes, read it. If not, create the necessary files:

search.py — wraps the gflights CLI:

import json, subprocess, time
from dataclasses import dataclass, field

@dataclass
class FlightResult:
    origin: str
    destination: str
    departure_date: str
    return_date: str | None
    price_usd: float | None
    duration_minutes: int | None
    stops: int | None
    airlines: list[str] = field(default_factory=list)
    segments: list[str] = field(default_factory=list)
    error: str | None = None

def _run_gflights(args: list[str]) -> dict:
    cmd = ["gflights", *args, "--json"]
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
    if result.returncode != 0:
        raise RuntimeError(result.stderr.strip())
    return json.loads(result.stdout)

def _filter_args(**kw) -> list[str]:
    args = ["--class", kw.get("seat_class", "economy"), "--adults", str(kw.get("adults", 1))]
    if kw.get("max_stops") is not None: args += ["--stops", str(kw["max_stops"])]
    if kw.get("airlines"): args += ["--airlines", ",".join(kw["airlines"])]
    if kw.get("max_duration"): args += ["--max-duration", str(kw["max_duration"])]
    if kw.get("depart_time"): args += ["--depart", kw["depart_time"]]
    if kw.get("max_price"): args += ["--max-price", str(kw["max_price"])]
    return args

def query_round_trip(origin, dest, depart, ret, **kw):
    data = _run_gflights([origin, dest, depart, ret] + _filter_args(**kw))
    return FlightResult(origin=origin, destination=dest, departure_date=depart, return_date=ret,
        price_usd=data.get("priceUsd"), duration_minutes=data.get("durationMinutes"),
        stops=data.get("stops"), airlines=data.get("airlines", []))

def query_one_way(origin, dest, date, **kw):
    data = _run_gflights([origin, dest, date] + _filter_args(**kw))
    return FlightResult(origin=origin, destination=dest, departure_date=date, return_date=None,
        price_usd=data.get("priceUsd"), duration_minutes=data.get("durationMinutes"),
        stops=data.get("stops"), airlines=data.get("airlines", []))

def query_multi_city(segments, **kw):
    args = ["--multi"]
    for s in segments: args += [s["origin"], s["destination"], s["date"]]
    args += _filter_args(**kw)
    data = _run_gflights(args)
    return FlightResult(origin=segments[0]["origin"], destination=segments[-1]["destination"],
        departure_date=segments[0]["date"], return_date=None,
        price_usd=data.get("priceUsd"), duration_minutes=data.get("durationMinutes"),
        stops=data.get("stops"), airlines=data.get("airlines", []),
        segments=[f"{s['origin']}->{s['destination']}" for s in segments])

def _human_delay(i, n):
    """Sleep like a human: 2-5s base, longer pause every few queries, slight fatigue."""
    import random
    base = random.uniform(2.0, 5.0)
    if i > 0 and i % random.randint(4, 6) == 0: base += random.uniform(3.0, 8.0)
    base += (i / max(n, 1)) * random.uniform(0.5, 2.0)
    time.sleep(base)

def query_batch(queries):
    results = []; n = len(queries)
    for i, q in enumerate(queries):
        q = q.copy(); t = q.pop("type", "round-trip")
        try:
            if t == "one-way": results.append(query_one_way(**q))
            elif t == "multi-city": results.append(query_multi_city(**q))
            else: results.append(query_round_trip(**q))
        except Exception as e:
            results.append(FlightResult(origin=q.get("origin","?"), destination=q.get("destination","?"),
                departure_date=q.get("departure_date",q.get("date","?")), return_date=q.get("return_date"),
                price_usd=None, duration_minutes=None, stops=None, error=str(e)))
        if i < n - 1: _human_delay(i, n)
    return results

Step 3: Design search strategy

Based on the interpreted request, plan your iterations:

For a simple round-trip (e.g., "TPE to PRG early May, 50 days"):

1. Date sweep across the target window (weekly)
2. Zoom into cheapest dates (daily)
3. Try nearby airports and open-jaw variants
4. Try multi-city through hubs

For ex-origin tickets (e.g., "EVA Air ex-origin 4 segments, middle legs Milan in Munich out"):

1. Try all candidate ex-origins: BKK, HKG, SIN, KUL, NRT, ICN, MNL — find cheapest
2. Date sweep for the cheapest origin
3. Vary the middle segments (different cities, open-jaw options)
4. Compare with direct booking to confirm savings

For airline-specific searches:

• Always use the airlines filter
• Also run queries without the filter to show the price difference

Step 4: Execute the loop

For each iteration:

1. Write strategy.py with generate_queries() returning 10-20 queries
2. Run: uv run python explore.py (if available) or run queries directly via Python
3. Analyze results, identify patterns
4. Decide next iteration strategy based on results

Run at least 3 iterations, up to 8.

Step 5: Report results

Report in the same language the user used. If they wrote Mandarin, reply in Mandarin. If English, reply in English.

Structure:

1. Search summary — what you searched and why
2. Top 5 results — route, dates, price (USD), airlines, flight numbers, duration, stops
3. Patterns discovered — cheapest days, best ex-origins, etc.
4. Further exploration — what else might be worth trying
5. Money-saving tips — specific to their route