layover 0.1.0.dev0__py3-none-any.whl

layover/interact/__init__.py

@@ -0,0 +1 @@
+"""Interaction layer: questions as data (DESIGN 10)."""

layover/interact/assumptions.py

@@ -0,0 +1,120 @@
+"""Assumptions as data, not prompts (DESIGN §10).
+
+Some inputs cannot be known in advance and should not be silently defaulted: is
+this ESTA still valid, is a 4-hour self-transfer acceptable today, is a night in
+Santorini worth having. The solver emits `Assumption` objects; a front end decides
+how to ask them — a CLI prompt, an MCP round-trip through Claude, or nothing at all
+in an unattended run, where the default is used and *recorded as assumed*.
+
+Every option carries its pros and cons in plain language, because that is what
+makes a question answerable by a human at the moment of deciding — and the same
+text is what the report prints next to the plan the answer produced.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class Source(StrEnum):
+    CONFIG = "config"
+    """Came from the owner's config: a settled preference."""
+
+    ASKED = "asked"
+    """A human answered this, in this session."""
+
+    ASSUMED = "assumed"
+    """Nobody was there to ask; the default was used and is reported as such."""
+
+
+@dataclass(frozen=True, slots=True)
+class Option:
+    label: str
+    value: object
+    pros: str = ""
+    cons: str = ""
+
+    def describe(self) -> str:
+        bits = [self.label]
+        if self.pros:
+            bits.append(f"+ {self.pros}")
+        if self.cons:
+            bits.append(f"- {self.cons}")
+        return "  ".join(bits)
+
+
+@dataclass(slots=True)
+class Assumption:
+    key: str
+    question: str
+    options: list[Option]
+    default: object
+    source: Source = Source.ASSUMED
+    blocking: bool = False
+    """Blocking questions can make a plan infeasible or unbookable — held
+    authorizations, unknown transit regimes, trip mode, airport-change consent.
+    Non-blocking ones are comfort and money trade-offs the default handles."""
+    affects: list[str] = field(default_factory=list)
+    """Plan ids whose cost depends on the answer."""
+    answer: object | None = None
+    remember: bool = False
+    """Whether the answer should be promoted into config (`--remember`)."""
+
+    @property
+    def value(self) -> object:
+        return self.default if self.answer is None else self.answer
+
+    @property
+    def answered(self) -> bool:
+        return self.answer is not None
+
+    def describe(self) -> str:
+        head = f"[{self.source}] {self.question}"
+        body = "\n".join(f"    {o.describe()}" for o in self.options)
+        return f"{head}\n{body}" if body else head
+
+
+@dataclass(slots=True)
+class AssumptionLog:
+    """Everything the system had to decide without being told, in one place.
+
+    The report prints this verbatim: a plan whose ranking rests on an assumed
+    answer must say so, or the number looks more solid than it is.
+    """
+
+    entries: list[Assumption] = field(default_factory=list)
+
+    def add(self, assumption: Assumption) -> Assumption:
+        existing = self.get(assumption.key)
+        if existing is not None:
+            return existing
+        self.entries.append(assumption)
+        return assumption
+
+    def get(self, key: str) -> Assumption | None:
+        for entry in self.entries:
+            if entry.key == key:
+                return entry
+        return None
+
+    def answer(self, key: str, value: object, *, remember: bool = False) -> None:
+        entry = self.get(key)
+        if entry is None:
+            raise KeyError(f"no assumption {key!r} to answer")
+        entry.answer = value
+        entry.source = Source.ASKED
+        entry.remember = remember
+
+    def value_of(self, key: str, fallback: object = None) -> object:
+        entry = self.get(key)
+        return fallback if entry is None else entry.value
+
+    @property
+    def blocking_unanswered(self) -> list[Assumption]:
+        return [e for e in self.entries if e.blocking and not e.answered]
+
+    def describe(self) -> str:
+        if not self.entries:
+            return "no assumptions — everything came from config or the itinerary"
+        return "\n".join(e.describe() for e in self.entries)

layover/models.py

@@ -0,0 +1,363 @@
+"""Canonical models (DESIGN §5).
+
+Everything an oracle returns is normalized into these before the solver or the
+cost model sees it. The models deliberately carry *protection structure* — how
+many tickets, who owns the connection risk, whether bags are through-checked —
+because none of that can be reconstructed later from a price and a duration.
+"""
+
+from __future__ import annotations
+
+import itertools
+from datetime import datetime, timedelta
+from enum import StrEnum
+
+from pydantic import BaseModel, Field, model_validator
+
+from layover.money import Money
+
+
+class TransportMode(StrEnum):
+    AIR = "air"
+    RAIL = "rail"
+    BUS = "bus"
+    FERRY = "ferry"
+
+
+class Cabin(StrEnum):
+    ECONOMY = "economy"
+    PREMIUM = "premium"
+    BUSINESS = "business"
+
+
+class BaggageProfile(StrEnum):
+    PERSONAL_ITEM_ONLY = "personal_item_only"
+    CABIN_BAG = "cabin_bag"
+    CABIN_PLUS_CHECKED = "cabin_plus_checked"
+
+
+class Protection(StrEnum):
+    """Who carries the risk if a connection inside one offer fails."""
+
+    SINGLE_TICKET = "single_ticket"
+    """One PNR: the airline rebooks you. Its own MCT applies."""
+
+    GUARANTEED_SELF_TRANSFER = "guaranteed_self_transfer"
+    """Separate tickets with an aggregator guarantee (Kiwi). Covered, but by the
+    aggregator rather than the airline — the middle risk rate applies."""
+
+    SELF_TRANSFER = "self_transfer"
+    """Separate tickets, nobody's problem but yours."""
+
+
+class TripShape(StrEnum):
+    ONE_WAY = "one_way"
+    RETURN = "return"
+    OPEN_JAW = "open_jaw"
+    MULTI_CITY = "multi_city"
+
+
+class TriState(StrEnum):
+    YES = "yes"
+    NO = "no"
+    UNKNOWN = "unknown"
+
+
+class Segment(BaseModel):
+    """One flight (or ground leg, later)."""
+
+    carrier: str
+    flight_number: str
+    origin: str = Field(min_length=3, max_length=4)
+    destination: str = Field(min_length=3, max_length=4)
+    depart: datetime
+    arrive: datetime
+    mode: TransportMode = TransportMode.AIR
+    cabin: Cabin = Cabin.ECONOMY
+    equipment: str | None = None
+    last_departure_of_day: bool | None = None
+    """Whether this is the day's final departure on the route. Missing it means an
+    overnight and a lost day, not a rebooking — so adapters must report it when
+    they can (ORACLES §3)."""
+
+    @model_validator(mode="after")
+    def _check_times(self) -> Segment:
+        if self.depart.tzinfo is None or self.arrive.tzinfo is None:
+            raise ValueError("segment times must be timezone-aware")
+        if self.arrive <= self.depart:
+            raise ValueError(f"{self.flight_number}: arrive {self.arrive} not after depart")
+        return self
+
+    @property
+    def duration(self) -> timedelta:
+        return self.arrive - self.depart
+
+    @property
+    def local_departure_hour(self) -> int:
+        return self.depart.hour
+
+    def __str__(self) -> str:
+        return (
+            f"{self.carrier}{self.flight_number} {self.origin}-{self.destination} "
+            f"{self.depart:%Y-%m-%d %H:%M}"
+        )
+
+
+class Leg(BaseModel):
+    """Ordered segments sold as one bound (e.g. the outbound of a return)."""
+
+    segments: list[Segment] = Field(min_length=1)
+
+    @property
+    def origin(self) -> str:
+        return self.segments[0].origin
+
+    @property
+    def destination(self) -> str:
+        return self.segments[-1].destination
+
+    @property
+    def depart(self) -> datetime:
+        return self.segments[0].depart
+
+    @property
+    def arrive(self) -> datetime:
+        return self.segments[-1].arrive
+
+    @property
+    def elapsed(self) -> timedelta:
+        return self.arrive - self.depart
+
+
+class POSContext(BaseModel):
+    """Point of sale a price was observed under (DESIGN §9)."""
+
+    site_market: str | None = None
+    currency: str = "EUR"
+    locale: str | None = None
+    ip_country: str | None = None
+    """None = native IP."""
+
+    @property
+    def name(self) -> str:
+        return self.site_market or self.ip_country or "native"
+
+
+class BaggageIncluded(BaseModel):
+    personal_item: TriState = TriState.UNKNOWN
+    cabin_bag: TriState = TriState.UNKNOWN
+    checked: TriState = TriState.UNKNOWN
+
+
+class OfferKind(StrEnum):
+    THROUGH = "through"
+    LEG_PROBE = "leg_probe"
+    OW_PROBE = "ow_probe"
+    POS_PROBE = "pos_probe"
+
+
+class Offer(BaseModel):
+    """One purchasable ticket."""
+
+    legs: list[Leg] = Field(min_length=1)
+    price: Money
+    price_normalized: float | None = None
+    """None means no reference rate was available — the offer is uncomparable and
+    excluded from ranking rather than converted at a guessed rate (DESIGN §9)."""
+    protection: Protection = Protection.SINGLE_TICKET
+    baggage_included: BaggageIncluded = Field(default_factory=BaggageIncluded)
+    pos: POSContext = Field(default_factory=POSContext)
+    oracle_id: str = "unknown"
+    observed_at: datetime | None = None
+    deep_link: str | None = None
+    fare_notes: list[str] = Field(default_factory=list)
+    offer_kind: OfferKind = OfferKind.THROUGH
+
+    @property
+    def segments(self) -> list[Segment]:
+        return [s for leg in self.legs for s in leg.segments]
+
+    @property
+    def identity_key(self) -> tuple:
+        """Same key from two oracles means the same product (DESIGN §5)."""
+        return (
+            tuple(
+                (s.carrier, s.flight_number, s.depart.date().isoformat()) for s in self.segments
+            ),
+            self.segments[0].cabin,
+            self.pos.name,
+        )
+
+
+class Connection(BaseModel):
+    """A gap between two consecutive segments of a plan.
+
+    Whether this is a 50-minute non-event or the thing that wrecks the trip
+    depends on who owns it, which is why the flags live here rather than being
+    inferred at pricing time.
+    """
+
+    arrive_segment: Segment
+    depart_segment: Segment
+    protection: Protection
+    within_offer: bool
+    """True when both segments are on the same ticket."""
+
+    @property
+    def gap(self) -> timedelta:
+        return self.depart_segment.depart - self.arrive_segment.arrive
+
+    @property
+    def gap_minutes(self) -> float:
+        return self.gap.total_seconds() / 60
+
+    @property
+    def at_airport(self) -> str:
+        return self.arrive_segment.destination
+
+    @property
+    def airport_change(self) -> bool:
+        return self.arrive_segment.destination != self.depart_segment.origin
+
+    @property
+    def is_protected(self) -> bool:
+        return self.protection is Protection.SINGLE_TICKET
+
+    @property
+    def onward_is_last_of_day(self) -> bool:
+        return bool(self.depart_segment.last_departure_of_day)
+
+    def __str__(self) -> str:
+        where = (
+            f"{self.arrive_segment.destination}->{self.depart_segment.origin}"
+            if self.airport_change
+            else self.at_airport
+        )
+        return f"{where} {self.gap_minutes / 60:.1f}h ({self.protection})"
+
+
+class TripPlan(BaseModel):
+    """An ordered composition of 1..n offers covering the intent.
+
+    Cost fields are not stored on the model: pricing is a pure function of a plan
+    plus a context (preferences, party, reference data), so the same plan can be
+    priced under two trip modes without mutating anything.
+    """
+
+    offers: list[Offer] = Field(min_length=1)
+    plan_id: str = "plan"
+    label: str = ""
+    """How this plan was arrived at — "2 one-ways" and so on.
+
+    A probe's answer is only useful if the report can say which shape of purchase it
+    is: two itineraries with the same fare are not the same offer when one of them is
+    two bookings (DESIGN §6)."""
+
+    @property
+    def segments(self) -> list[Segment]:
+        return [s for offer in self.offers for s in offer.segments]
+
+    @property
+    def money_out_of_pocket(self) -> float | None:
+        """Sum of normalized fares, or None if any offer could not be normalized."""
+        total = 0.0
+        for offer in self.offers:
+            if offer.price_normalized is None:
+                return None
+            total += offer.price_normalized
+        return total
+
+    @property
+    def depart(self) -> datetime:
+        return self.segments[0].depart
+
+    @property
+    def arrive(self) -> datetime:
+        return self.segments[-1].arrive
+
+    def connections(self) -> list[Connection]:
+        """All gaps in the plan, tagged with who owns the risk.
+
+        Connections inside one offer inherit that offer's protection. Connections
+        *between* offers are bare self-transfers by construction: two tickets
+        bought separately have no relationship at all.
+        """
+        out: list[Connection] = []
+        for offer in self.offers:
+            segs = offer.segments
+            for a, b in itertools.pairwise(segs):
+                out.append(
+                    Connection(
+                        arrive_segment=a,
+                        depart_segment=b,
+                        protection=offer.protection,
+                        within_offer=True,
+                    )
+                )
+        for prev, nxt in itertools.pairwise(self.offers):
+            out.append(
+                Connection(
+                    arrive_segment=prev.segments[-1],
+                    depart_segment=nxt.segments[0],
+                    protection=Protection.SELF_TRANSFER,
+                    within_offer=False,
+                )
+            )
+        out.sort(key=lambda c: c.arrive_segment.arrive)
+        return out
+
+    def stays(self) -> list[Stay]:
+        """Gaps long enough to be a stay somewhere rather than a connection.
+
+        Whether a stay is a wanted stopover or an involuntary layover is not a
+        property of the itinerary — it depends on what the intent asked for, so
+        that judgement belongs to the cost model (DESIGN §8.3), not here.
+        """
+        return [
+            Stay(
+                place=c.at_airport,
+                arrive=c.arrive_segment.arrive,
+                depart=c.depart_segment.depart,
+            )
+            for c in self.connections()
+        ]
+
+
+class Stay(BaseModel):
+    """Time on the ground between two flights, at one place."""
+
+    place: str
+    arrive: datetime
+    depart: datetime
+
+    @property
+    def hours(self) -> float:
+        return (self.depart - self.arrive).total_seconds() / 3600
+
+    @property
+    def nights(self) -> int:
+        """Calendar nights, which is what hotels and stopover rules count."""
+        return max(0, (self.depart.date() - self.arrive.date()).days)
+
+
+class RiskKind(StrEnum):
+    SELF_TRANSFER = "self_transfer"
+    SEPARATE_PNR = "separate_pnr"
+    THIRD_PARTY_GUARANTEE = "third_party_guarantee"
+    AIRPORT_CHANGE = "airport_change"
+    OVERNIGHT_SELF_TRANSFER = "overnight_self_transfer"
+    ENTRY_EXIT_TRANSIT = "entry_exit_transit"
+    LCC_BAG_GAUGE = "lcc_bag_gauge"
+    SKIPLAG = "skiplag"
+    AUTHORIZATION_PENDING = "authorization_pending"
+    UNKNOWN_TRANSIT_REGIME = "unknown_transit_regime"
+    VISA_CHECK = "visa_check"
+
+
+class RiskAnnotation(BaseModel):
+    kind: RiskKind
+    detail: str
+    traveler_id: str | None = None
+
+
+TripPlan.model_rebuild()

layover/money.py

@@ -0,0 +1,112 @@
+"""Money and cost bands.
+
+Every computed cost in layover is a *band*, not a number: ancillary fees are
+ranges, preference terms the user never set are ranges, and a delay prior is an
+expectation. Ranking uses the midpoint; the report shows the interval; two plans
+whose intervals overlap are "too close to call" rather than ordered (DESIGN §8.8).
+
+Values are floats in the session's normalization currency. Cents are not the
+point — the fee tables and priors feeding this are accurate to a few euros at
+best, and pretending otherwise with Decimal would be false precision. Actual
+observed fares keep their own currency in `Money` until normalized.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel, Field
+
+
+class Money(BaseModel):
+    """An observed price in its original currency, exactly as the oracle said it."""
+
+    amount: float
+    currency: str = Field(min_length=3, max_length=3)
+
+    def __str__(self) -> str:
+        return f"{self.amount:,.2f} {self.currency}"
+
+
+@dataclass(frozen=True, slots=True)
+class Band:
+    """A cost interval in the normalization currency: low <= mid <= high."""
+
+    low: float
+    mid: float
+    high: float
+
+    def __post_init__(self) -> None:
+        if not (self.low <= self.mid <= self.high):
+            raise ValueError(f"band must satisfy low <= mid <= high, got {self!r}")
+
+    # ── constructors ──────────────────────────────────────────────────────────
+
+    @classmethod
+    def exact(cls, value: float) -> Band:
+        """A cost we know."""
+        return cls(value, value, value)
+
+    @classmethod
+    def between(cls, low: float, high: float, *, mid: float | None = None) -> Band:
+        """A cost we only know within a range — e.g. an unpublished bag fee."""
+        if high < low:
+            raise ValueError(f"high {high} below low {low}")
+        return cls(low, mid if mid is not None else (low + high) / 2, high)
+
+    @classmethod
+    def zero(cls) -> Band:
+        return cls(0.0, 0.0, 0.0)
+
+    # ── interval arithmetic ───────────────────────────────────────────────────
+
+    def __add__(self, other: Band | float) -> Band:
+        if isinstance(other, int | float):
+            return Band(self.low + other, self.mid + other, self.high + other)
+        return Band(self.low + other.low, self.mid + other.mid, self.high + other.high)
+
+    __radd__ = __add__
+
+    def __mul__(self, factor: float) -> Band:
+        if factor < 0:
+            # Negative scaling flips the interval; nothing in the cost model needs
+            # it, and silently returning an inverted band would corrupt comparisons.
+            raise ValueError("bands scale by non-negative factors only")
+        return Band(self.low * factor, self.mid * factor, self.high * factor)
+
+    __rmul__ = __mul__
+
+    def __neg__(self) -> Band:
+        """Negation for credits (stopover value offsetting lodging)."""
+        return Band(-self.high, -self.mid, -self.low)
+
+    def __sub__(self, other: Band | float) -> Band:
+        if isinstance(other, int | float):
+            return self + (-other)
+        return self + (-other)
+
+    # ── comparison ────────────────────────────────────────────────────────────
+
+    @property
+    def is_exact(self) -> bool:
+        return self.low == self.high
+
+    @property
+    def width(self) -> float:
+        return self.high - self.low
+
+    def overlaps(self, other: Band) -> bool:
+        """True when the two costs cannot be honestly ordered."""
+        return self.low <= other.high and other.low <= self.high
+
+    def __str__(self) -> str:
+        if self.is_exact:
+            return f"{self.mid:,.0f}"
+        return f"{self.low:,.0f}..{self.high:,.0f}"
+
+
+def band_sum(bands: list[Band]) -> Band:
+    total = Band.zero()
+    for b in bands:
+        total = total + b
+    return total

layover/oracles/__init__.py

@@ -0,0 +1 @@
+"""Oracle abstraction: capability descriptors, typed failures, scheduling."""

layover/oracles/api/__init__.py

@@ -0,0 +1 @@
+"""API oracles: HTTP sources that need no browser."""