layover 0.1.0.dev0__py3-none-any.whl

layover/oracles/api/azair.py

@@ -0,0 +1,480 @@
+"""AZair: European LCC one-way combinatorics (ORACLES §4).
+
+The oracle that answers the question Google structurally cannot. Google is
+metasearch — it displays fares — so its storefront parameter changed prices by 0.0%
+across three continents. AZair sells to European buyers, quotes in EUR or HUF, and
+composes its results out of **separate one-way tickets** from different carriers,
+which is precisely the split-ticket structure this project exists to evaluate.
+
+Three things make it a better citizen of our data model than Google:
+
+* **Flight numbers.** Every leg carries one (`FR8859`), so `identity_key` is real and
+  cross-oracle matching becomes possible.
+* **Ticket boundaries are explicit.** Each result's `tp` attribute carries JSON —
+  `{"tp":136,"d":[31.92,27.99],"b":[51.99,23.99]}` — where `d` and `b` are the
+  per-ticket prices out and back. Two entries means two bookings, and that is exactly
+  what the cost model needs to know: the airline owes you nothing between them, bags
+  are not through-checked, and the buffer rules apply (DESIGN §8.9).
+* **Native date ranges.** One `flexi` query prices a whole window with a
+  min/max-nights constraint — the cheap bound generator the solver wants (§6),
+  instead of one request per date pair.
+
+Read from the page's own structured attributes and stable class names rather than
+layout: `tp` for money, `.result` for grouping, `.legPrice` / `.airline iata**` /
+the flightradar link for each ticket.
+"""
+
+from __future__ import annotations
+
+import html as html_module
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime, timedelta
+from typing import Any
+from urllib.parse import urlencode
+
+from layover.models import Leg, Offer, POSContext, Protection, Segment, TripShape
+from layover.money import Money
+from layover.oracles.base import (
+    FailureKind,
+    Oracle,
+    OracleCapabilities,
+    OracleQuery,
+    QueryResult,
+)
+from layover.oracles.transport import HttpTransport
+
+BASE_URL = "https://www.azair.eu/azfin.php"
+
+# Markers that say "this *is* a results page", whatever it found. Their presence with
+# zero rows is a real answer — the route is not in AZair's network — while their
+# absence means we are looking at something we do not understand.
+_RESULTS_SHELL = ("Soonest depart", "Latest return")
+
+COVERAGE = "european low-cost network"
+"""What AZair actually knows about, measured 2026-08-05.
+
+BUD-LIS returns 180 combinations; BUD-DXB and BUD-BKK return an empty results page
+under the identical window and duration — including with the destination spelled as
+the site's own autocomplete does. So the limit is coverage, not query shape: AZair
+combines European LCC one-ways, and Bangkok is outside that network however the
+question is phrased. The solver should not spend budget asking it about long-haul."""
+
+_RESULT = re.compile(r'<div class="result ')
+_TP = re.compile(r"tp='([^']+)'")
+# "There" is `caption tam`, "Back" is `caption sem` — same element, different class.
+_DIRECTION = re.compile(r'class="caption (?:tam|sem)">(There|Back)</span>')
+_DATE = re.compile(r'class="date">\w{2,3} (\d{2})/(\d{2})/(\d{2})<')
+_DURCHA = re.compile(r'class="durcha">(\d+):(\d+) h / (no change|\d+ changes?)<')
+# Airport codes sometimes carry a nested tooltip span ("MXP<span
+# class="aeroDetail">Milan (Malpensa) MXP</span>"), so the code group stops at the
+# first three letters and anything nested is skipped rather than assumed absent.
+_CODE = r'<span class="code">([A-Z]{3})(?:<span class="aeroDetail">[^<]*</span>)?</span>'
+_TICKET = re.compile(
+    r'class="from"[^>]*>(?:\w{2}&nbsp;)?(\d{1,2}:\d{2})&nbsp;([^<]*?)&nbsp;'
+    + _CODE
+    + r"</span>\s*"
+    r'<span class="to"[^>]*>(\d{1,2}:\d{2})&nbsp;([^<]*?)&nbsp;'
+    + _CODE
+    + r'.*?flightradar24">([A-Z0-9]+)</a>'
+    r'.*?class="airline iata([A-Z0-9]{2})">([^<]+)</span>'
+    r'.*?class="legPrice">([^\d]*)([\d.,]+)</span>',
+    re.DOTALL,
+)
+
+
+@dataclass(slots=True)
+class Ticket:
+    """One separately-bookable flight, as AZair lists it."""
+
+    depart_time: str
+    origin: str
+    origin_city: str
+    arrive_time: str
+    destination: str
+    destination_city: str
+    flight_number: str
+    carrier: str
+    carrier_name: str
+    price: float
+
+
+@dataclass(slots=True)
+class Direction:
+    """One direction of a result: a date, a duration, and its tickets."""
+
+    label: str
+    day: date | None
+    minutes: int | None
+    changes: int
+    tickets: list[Ticket] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class AzairResult:
+    """A whole combination as offered: out and back, with per-ticket prices."""
+
+    result_id: str
+    total: float
+    out_prices: list[float]
+    back_prices: list[float]
+    directions: list[Direction] = field(default_factory=list)
+
+    @property
+    def ticket_count(self) -> int:
+        return len(self.out_prices) + len(self.back_prices)
+
+    @property
+    def is_split(self) -> bool:
+        """More than one ticket per direction means self-transfers inside a leg."""
+        return len(self.out_prices) > 1 or len(self.back_prices) > 1
+
+
+def build_url(query: OracleQuery, *, currency: str | None = None) -> str:
+    """Compose a `flexi` search.
+
+    The window is the point: `depdate`..`arrdate` with `minDaysStay`/`maxDaysStay`
+    prices every date pair in range in one request. Sending a single date would throw
+    away the capability that makes this oracle cheap.
+    """
+    depart_from = query.depart
+    depart_to = query.depart_until or query.return_on or query.depart
+    is_return = query.trip_shape is TripShape.RETURN
+
+    params: dict[str, Any] = {
+        "searchtype": "flexi",
+        "tp": "0",
+        "isOneway": "return" if is_return else "oneway",
+        "srcAirport": f"{query.origin} [{query.origin}]",
+        "srcTypedText": query.origin.lower(),
+        "srcFreeTypedText": "",
+        "srcMC": "",
+        "dstAirport": f"{query.destination} [{query.destination}]",
+        "dstTypedText": query.destination.lower(),
+        "dstFreeTypedText": "",
+        "dstMC": "",
+        "depdate": depart_from.isoformat(),
+        "arrdate": (query.return_until or depart_to).isoformat(),
+        "aid": "0",
+        "minDaysStay": str(query.min_nights if query.min_nights is not None else 0),
+        "maxDaysStay": str(query.max_nights if query.max_nights is not None else 30),
+        "samedep": "true",
+        "samearr": "true",
+        # Their own minimum connection time. Left at the site default: our buffer
+        # rules (§8.9) are stricter and applied afterwards, so filtering here would
+        # only hide options we might have wanted to see rejected for a stated reason.
+        "minHourStay": "0:45",
+        "maxHourStay": "23:20",
+        "minHourOutbound": "0:00",
+        "maxHourOutbound": "24:00",
+        "minHourInbound": "0:00",
+        "maxHourInbound": "24:00",
+        "autoprice": "true",
+        "adults": str(query.adults),
+        "children": "0",
+        "infants": "0",
+        "maxChng": str(query.max_stops if query.max_stops is not None else 1),
+        "currency": (currency or query.pos.currency or "EUR").upper(),
+        "lang": "en",
+    }
+    for index in range(7):  # every weekday allowed unless the intent says otherwise
+        params[f"dep{index}"] = "true"
+        params[f"arr{index}"] = "true"
+    return f"{BASE_URL}?{urlencode(params)}"
+
+
+# ── parsing ──────────────────────────────────────────────────────────────────
+
+
+def _clean(text: str) -> str:
+    return html_module.unescape(text).replace("\xa0", " ").strip()
+
+
+def parse_results(html: str) -> list[AzairResult]:
+    """Split the page into results and read each one's money and tickets."""
+    starts = [m.start() for m in _RESULT.finditer(html)]
+    results: list[AzairResult] = []
+    for index, start in enumerate(starts):
+        end = starts[index + 1] if index + 1 < len(starts) else len(html)
+        parsed = _parse_result(html[start:end])
+        if parsed is not None:
+            results.append(parsed)
+    return results
+
+
+def _parse_result(chunk: str) -> AzairResult | None:
+    money = _TP.search(chunk)
+    if not money:
+        return None
+    try:
+        payload = json.loads(_clean(money.group(1)))
+    except json.JSONDecodeError:
+        return None
+
+    result_id = (re.search(r'id="([^"]+)"', chunk) or [None, ""])[1]
+    result = AzairResult(
+        result_id=result_id,
+        total=float(payload.get("tp", 0)),
+        out_prices=[float(x) for x in payload.get("d", [])],
+        back_prices=[float(x) for x in payload.get("b", [])],
+    )
+
+    # The block is a sequence of "There"/"Back" sections; slice on the captions.
+    marks = [(m.start(), m.group(1)) for m in _DIRECTION.finditer(chunk)]
+    for index, (start, label) in enumerate(marks):
+        end = marks[index + 1][0] if index + 1 < len(marks) else len(chunk)
+        result.directions.append(_parse_direction(chunk[start:end], label))
+    return result
+
+
+def _parse_direction(chunk: str, label: str) -> Direction:
+    day = None
+    if match := _DATE.search(chunk):
+        d, m, y = (int(x) for x in match.groups())
+        day = date(2000 + y, m, d)
+
+    minutes = changes = None
+    if match := _DURCHA.search(chunk):
+        minutes = int(match.group(1)) * 60 + int(match.group(2))
+        changes = 0 if match.group(3) == "no change" else int(match.group(3).split()[0])
+
+    direction = Direction(label=label, day=day, minutes=minutes, changes=changes or 0)
+    for match in _TICKET.finditer(chunk):
+        (
+            dep_time,
+            dep_city,
+            dep_code,
+            arr_time,
+            arr_city,
+            arr_code,
+            flight,
+            carrier,
+            carrier_name,
+            _symbol,
+            price,
+        ) = match.groups()
+        direction.tickets.append(
+            Ticket(
+                depart_time=dep_time,
+                origin=dep_code,
+                origin_city=_clean(dep_city),
+                arrive_time=arr_time,
+                destination=arr_code,
+                destination_city=_clean(arr_city),
+                flight_number=flight,
+                carrier=carrier,
+                carrier_name=_clean(carrier_name),
+                price=float(price.replace(",", "")),
+            )
+        )
+    return direction
+
+
+# ── results to offers ────────────────────────────────────────────────────────
+
+
+def _at(day: date, clock: str, *, after: datetime | None = None) -> datetime:
+    """A local clock time on a day, rolling past midnight when the clock goes back.
+
+    Times are local at each airport and labelled UTC, as with Google: mapping them to
+    instants needs an airport timezone table (M1). Same-airport gaps — the layovers
+    the connection rules actually use — are exact regardless, since both ends share a
+    timezone.
+    """
+    hour, minute = (int(part) for part in clock.split(":"))
+    stamp = datetime(day.year, day.month, day.day, hour, minute, tzinfo=UTC)
+    if after is not None and stamp < after:
+        stamp += timedelta(days=1)
+    return stamp
+
+
+def result_to_offers(
+    result: AzairResult,
+    query: OracleQuery,
+    *,
+    oracle_id: str = "azair",
+    pos: POSContext | None = None,
+) -> list[Offer]:
+    """One `Offer` per separately-bookable ticket.
+
+    This is the honest shape: AZair combines one-ways, each with its own price and its
+    own booking link, so each is its own product. The composer then sees the
+    connections *between* them as what they are — separate tickets, nobody's problem
+    but yours — and prices the exposure without anyone having to remember to.
+    """
+    pos = pos or POSContext(currency=query.pos.currency)
+    offers: list[Offer] = []
+
+    for direction in result.directions:
+        if direction.day is None or not direction.tickets:
+            continue
+        cursor: datetime | None = None
+        for position, ticket in enumerate(direction.tickets):
+            depart = _at(direction.day, ticket.depart_time, after=cursor)
+            arrive = _at(direction.day, ticket.arrive_time, after=depart)
+            cursor = arrive
+            segment = Segment(
+                carrier=ticket.carrier,
+                flight_number=ticket.flight_number.removeprefix(ticket.carrier),
+                origin=ticket.origin,
+                destination=ticket.destination,
+                depart=depart,
+                arrive=arrive,
+                cabin=query.cabin,
+            )
+            notes = [
+                f"azair {result.result_id}: {direction.label.lower()} leg, "
+                f"ticket {position + 1} of {len(direction.tickets)}",
+                f"{ticket.carrier_name} — separately booked, priced per ticket",
+                "local clock times labelled UTC (needs an airport timezone table)",
+            ]
+            if result.is_split:
+                notes.append(
+                    "part of a multi-ticket combination: no through-checked bags, "
+                    "and no airline owes you the connection"
+                )
+            offers.append(
+                Offer(
+                    legs=[Leg(segments=[segment])],
+                    price=Money(amount=ticket.price, currency=pos.currency),
+                    protection=Protection.SINGLE_TICKET,  # each ticket, on its own
+                    pos=pos,
+                    oracle_id=oracle_id,
+                    observed_at=datetime.now(UTC),
+                    fare_notes=notes,
+                )
+            )
+    return offers
+
+
+def parse_combinations(
+    html: str,
+    query: OracleQuery,
+    *,
+    oracle_id: str = "azair",
+    pos: POSContext | None = None,
+) -> list[tuple[AzairResult, list[Offer]]]:
+    """Results with their tickets kept together.
+
+    The solver will compose plans itself (M4), but AZair has already done the work of
+    finding combinations that no single airline sells — so until then its grouping is
+    worth keeping rather than flattening and re-deriving.
+    """
+    out: list[tuple[AzairResult, list[Offer]]] = []
+    for result in parse_results(html):
+        offers = result_to_offers(result, query, oracle_id=oracle_id, pos=pos)
+        if offers:
+            out.append((result, offers))
+    return out
+
+
+def parse_page(
+    html: str,
+    query: OracleQuery,
+    *,
+    oracle_id: str = "azair",
+    pos: POSContext | None = None,
+) -> list[Offer]:
+    offers: list[Offer] = []
+    for _result, group in parse_combinations(html, query, oracle_id=oracle_id, pos=pos):
+        offers.extend(group)
+    return offers
+
+
+class AzairOracle(Oracle):
+    """The European LCC combinator."""
+
+    id = "azair"
+    capabilities = OracleCapabilities(
+        trip_shapes=frozenset({TripShape.ONE_WAY, TripShape.RETURN}),
+        date_range_query=True,
+        composes_one_ways=True,
+        nearby_airports=True,
+        virtual_interline=True,
+        baggage_filter=False,
+        pos_controls=frozenset({"currency_param"}),
+        latency_est_s=3.0,
+        coverage=COVERAGE,
+        block_risk="low",
+        money_cost_per_query=0.0,
+        bookable="deep_link",
+    )
+
+    def __init__(
+        self, *, transport: HttpTransport | None = None, timeout: float = 60.0
+    ) -> None:
+        self._transport = transport
+        self._timeout = timeout
+
+    def search(self, query: OracleQuery) -> QueryResult:
+        if not self.capabilities.can_answer(query):
+            return QueryResult.failed(
+                query, self.id, FailureKind.UNSUPPORTED, f"cannot do {query.trip_shape}"
+            )
+
+        transport = self._transport or HttpTransport(pos=query.pos, timeout=self._timeout)
+        url = build_url(query)
+        started = time.monotonic()
+        try:
+            response = transport.get(url, headers={"Referer": "https://www.azair.eu/"})
+        except Exception as exc:
+            return QueryResult.failed(
+                query,
+                self.id,
+                FailureKind.TIMEOUT,
+                f"{type(exc).__name__}: {exc}",
+                latency_ms=(time.monotonic() - started) * 1000,
+            )
+
+        if response.status_code == 429:
+            return QueryResult.failed(query, self.id, FailureKind.RATE_LIMITED, "HTTP 429")
+        if response.status_code >= 400:
+            return QueryResult.failed(
+                query, self.id, FailureKind.BLOCKED, f"HTTP {response.status_code}"
+            )
+
+        offers = parse_page(
+            response.text, query, oracle_id=self.id, pos=transport.pos_with_egress()
+        )
+        if not offers:
+            # Two very different "no offers", and conflating them would have the
+            # health monitor cooling an oracle that answered correctly.
+            looks_like_results = all(mark in response.text for mark in _RESULTS_SHELL)
+            if looks_like_results:
+                return QueryResult.failed(
+                    query,
+                    self.id,
+                    FailureKind.EMPTY_MARKET,
+                    f"AZair returned a results page with nothing on it: "
+                    f"{query.origin}-{query.destination} is outside its coverage "
+                    f"({COVERAGE}) or has no combination in this window",
+                    latency_ms=response.latency_ms,
+                )
+            return QueryResult.failed(
+                query,
+                self.id,
+                FailureKind.EMPTY_ANOMALY,
+                f"no results shell in {len(response.text)} bytes — the page is not "
+                f"what this parser expects",
+                latency_ms=response.latency_ms,
+            )
+        return QueryResult(
+            query=query,
+            oracle_id=self.id,
+            offers=offers,
+            latency_ms=response.latency_ms,
+            raw=response.text,
+        )
+
+    def canary_query(self) -> OracleQuery:
+        today = date.today()
+        return OracleQuery(
+            origin="BUD",
+            destination="LON",
+            depart=today + timedelta(days=30),
+            depart_until=today + timedelta(days=37),
+            trip_shape=TripShape.ONE_WAY,
+            pos=POSContext(currency="EUR"),
+        )