layover 0.1.0.dev0__py3-none-any.whl

layover/cost/__init__.py

@@ -0,0 +1 @@
+"""Cost model: generalized cost in money-equivalent terms (DESIGN 8)."""

layover/cost/borders.py

@@ -0,0 +1,449 @@
+"""Borders: transit regimes, passports and authorizations (DESIGN §8.6).
+
+Two connections with the same clock gap are not equally feasible. Some airports
+move international passengers airside with a security re-screen; the United States
+has no airside transit at all, so a "connection" there is immigration, customs,
+baggage re-claim, re-check and re-screening.
+
+Resolved **per traveller**, then combined: added time takes the party maximum (a
+couple clears immigration together, at the slower queue), fees and applications are
+per person, and any traveller who cannot be admitted makes the routing infeasible
+for everyone.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from enum import StrEnum
+from pathlib import Path
+
+from layover.prefs.travelers import Party, Traveler
+
+
+class Regime(StrEnum):
+    AIRSIDE = "airside"
+    """International-to-international transit without immigration."""
+
+    AIRSIDE_WITHIN = "airside_within"
+    """No control for members of the bloc (Schengen internal legs)."""
+
+    ENTRY_REQUIRED = "entry_required"
+    """Full entry and exit: immigration, bags, re-screening (US, CA)."""
+
+    UNKNOWN = "unknown"
+    """Not in the table. Asked, never assumed airside — guessing wrong here costs
+    a flight, not money."""
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorizationRule:
+    kind: str
+    fee: float
+    currency: str = "USD"
+    effort_hours: float = 1.0
+    lead_time_days: int = 3
+    apply_now_days: int = 7
+    validity_years: float = 2.0
+    amortize: bool = True
+    expected_uses: int = 2
+    eligible_nationalities: frozenset[str] | None = None
+    """None = anyone may apply. Otherwise only these nationalities are eligible —
+    a Brazilian passport cannot get an ESTA at all, which is a different situation
+    from not having one yet."""
+    exempt_nationalities: frozenset[str] = field(default_factory=frozenset)
+    """Nationalities needing no authorization at all (Irish citizens for the UK
+    ETA). Citizens of the destination itself are exempt without being listed —
+    nobody needs permission to enter their own country."""
+    exempt_bloc_members: bool = False
+    """True when the destination's whole bloc is exempt: an EU/EEA citizen needs no
+    ETIAS in any member state, because that is freedom of movement rather than a
+    per-country courtesy. False for the UK ETA, which does apply to EU nationals."""
+    ineligible_note: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class CountryRule:
+    country: str
+    international_transit: Regime
+    added_time_min: float = 0.0
+    entry_from_outside_min: float = 0.0
+    requires_authorization: str | None = None
+    bloc: str | None = None
+    """e.g. "schengen" — members transit internally without control."""
+    bloc_members: frozenset[str] = field(default_factory=frozenset)
+    own_nationals_must_use_own_passport: bool = False
+    as_of: str = "unknown"
+
+
+class RegimeTable:
+    """Country transit rules plus authorization definitions."""
+
+    def __init__(
+        self,
+        countries: dict[str, CountryRule],
+        authorizations: dict[str, AuthorizationRule],
+        *,
+        as_of: str = "unknown",
+    ) -> None:
+        self.countries = countries
+        self.authorizations = authorizations
+        self.as_of = as_of
+
+    @classmethod
+    def from_toml(cls, regimes_path: Path, authorizations_path: Path) -> RegimeTable:
+        raw = tomllib.loads(regimes_path.read_text())
+        blocs = {
+            name: frozenset(x.upper() for x in (body.get("members") or []))
+            for name, body in (raw.get("bloc") or {}).items()
+        }
+        countries: dict[str, CountryRule] = {}
+        for code, body in (raw.get("country") or {}).items():
+            bloc = body.get("bloc")
+            members = blocs.get(bloc, frozenset()) if bloc else frozenset()
+            countries[code.upper()] = CountryRule(
+                country=code.upper(),
+                international_transit=Regime(body["international_transit"]),
+                added_time_min=float(body.get("added_time_min", 0.0)),
+                entry_from_outside_min=float(body.get("entry_from_outside_min", 0.0)),
+                requires_authorization=body.get("requires_authorization"),
+                bloc=bloc,
+                bloc_members=members
+                | frozenset(x.upper() for x in body.get("bloc_members", [])),
+                own_nationals_must_use_own_passport=bool(
+                    body.get("own_nationals_must_use_own_passport", False)
+                ),
+                as_of=str(body.get("as_of", raw.get("as_of", "unknown"))),
+            )
+        auth_raw = tomllib.loads(authorizations_path.read_text())
+        authorizations: dict[str, AuthorizationRule] = {}
+        for kind, body in (auth_raw.get("authorization") or {}).items():
+            eligible = body.get("eligible_nationalities")
+            authorizations[kind] = AuthorizationRule(
+                kind=kind,
+                fee=float(body["fee"]),
+                currency=str(body.get("currency", "USD")),
+                effort_hours=float(body.get("effort_hours", 1.0)),
+                lead_time_days=int(body.get("lead_time_days", 3)),
+                apply_now_days=int(body.get("apply_now_days", 7)),
+                validity_years=float(body.get("validity_years", 2.0)),
+                amortize=bool(body.get("amortize", True)),
+                expected_uses=int(body.get("expected_uses", 2)),
+                eligible_nationalities=(
+                    frozenset(x.upper() for x in eligible) if eligible else None
+                ),
+                exempt_nationalities=frozenset(
+                    x.upper() for x in body.get("exempt_nationalities", [])
+                ),
+                exempt_bloc_members=bool(body.get("exempt_bloc_members", False)),
+                ineligible_note=str(body.get("ineligible_note", "")),
+            )
+        return cls(countries, authorizations, as_of=str(raw.get("as_of", "unknown")))
+
+    def rule_for(self, country: str) -> CountryRule:
+        return self.countries.get(
+            country.upper(),
+            CountryRule(country=country.upper(), international_transit=Regime.UNKNOWN),
+        )
+
+
+class AuthorizationStatus(StrEnum):
+    NOT_NEEDED = "not_needed"
+    HELD = "held"
+    OBTAINABLE = "obtainable"
+    TOO_LATE = "too_late"
+    """Inside the official lead time: a risk, not a plan."""
+    INELIGIBLE = "ineligible"
+    """This passport cannot get this authorization at all (BR for ESTA)."""
+
+
+@dataclass(frozen=True, slots=True)
+class TravelerBorder:
+    """One traveller's exposure at one border."""
+
+    traveler_id: str
+    country: str
+    regime: Regime
+    passport_used: str | None
+    added_time_min: float
+    authorization_kind: str | None = None
+    authorization_status: AuthorizationStatus = AuthorizationStatus.NOT_NEEDED
+    money_cost: float = 0.0
+    """Fee plus effort, already amortized when the rule says so."""
+    money_cost_full: float = 0.0
+    """The un-amortized figure: what actually leaves the account."""
+    effort_hours: float = 0.0
+    note: str = ""
+
+    @property
+    def feasible(self) -> bool:
+        return self.authorization_status not in (
+            AuthorizationStatus.TOO_LATE,
+            AuthorizationStatus.INELIGIBLE,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PartyBorder:
+    """The party's combined exposure at one border."""
+
+    country: str
+    regime: Regime
+    per_traveler: list[TravelerBorder]
+
+    @property
+    def added_time_min(self) -> float:
+        """Party maximum: you clear immigration together, at the slower queue."""
+        return max((b.added_time_min for b in self.per_traveler), default=0.0)
+
+    @property
+    def money_cost(self) -> float:
+        """Per person, summed."""
+        return sum(b.money_cost for b in self.per_traveler)
+
+    @property
+    def money_cost_full(self) -> float:
+        return sum(b.money_cost_full for b in self.per_traveler)
+
+    @property
+    def effort_hours(self) -> float:
+        return sum(b.effort_hours for b in self.per_traveler)
+
+    @property
+    def feasible(self) -> bool:
+        return all(b.feasible for b in self.per_traveler)
+
+    @property
+    def blocking_notes(self) -> list[str]:
+        return [b.note for b in self.per_traveler if not b.feasible]
+
+
+def _choose_passport(traveler: Traveler, rule: CountryRule, day: date) -> str | None:
+    """Pick the cheapest admissible passport for one border.
+
+    Preference order: a passport of the destination country itself (and several
+    countries require their citizens to use it), then a bloc member's passport that
+    removes the control entirely, then whatever is valid.
+    """
+    valid = [p.nationality for p in traveler.passports if p.valid_on(day)]
+    if not valid:
+        return None
+    if rule.country in valid:
+        return rule.country
+    bloc = [n for n in valid if n in rule.bloc_members]
+    if bloc:
+        return bloc[0]
+    return valid[0]
+
+
+def resolve_traveler(
+    traveler: Traveler,
+    country: str,
+    *,
+    table: RegimeTable,
+    departure: date,
+    wage_rate_per_hour: float,
+    is_transit: bool = True,
+) -> TravelerBorder:
+    """Work out what this border costs this traveller."""
+    rule = table.rule_for(country)
+    passport = _choose_passport(traveler, rule, departure)
+
+    if passport is None:
+        return TravelerBorder(
+            traveler.id,
+            rule.country,
+            rule.international_transit,
+            None,
+            0.0,
+            authorization_status=AuthorizationStatus.INELIGIBLE,
+            note=f"{traveler.id} has no passport valid on {departure}",
+        )
+
+    # Time first, authorization second — and the authorization question is asked on
+    # every path, because a traveller can be waved through a Schengen-internal
+    # border and still need an authorization elsewhere.
+    regime = rule.international_transit
+    time_note = ""
+    if regime is Regime.AIRSIDE_WITHIN:
+        if passport in rule.bloc_members:
+            added = 0.0
+            time_note = f"{passport} passport: no control ({rule.bloc or 'bloc'} internal)"
+        else:
+            regime = Regime.ENTRY_REQUIRED
+            added = rule.entry_from_outside_min
+            time_note = f"entry into {rule.bloc or rule.country} from outside: {added:.0f}m"
+    else:
+        added = (
+            rule.added_time_min
+            if is_transit
+            else rule.entry_from_outside_min or rule.added_time_min
+        )
+
+    if rule.requires_authorization is None:
+        return TravelerBorder(
+            traveler.id, rule.country, regime, passport, added, note=time_note
+        )
+
+    auth = table.authorizations.get(rule.requires_authorization)
+    if auth is None:
+        return TravelerBorder(
+            traveler.id,
+            rule.country,
+            Regime.UNKNOWN,
+            passport,
+            added,
+            authorization_kind=rule.requires_authorization,
+            authorization_status=AuthorizationStatus.NOT_NEEDED,
+            note=f"authorization {rule.requires_authorization!r} not in the table — verify",
+        )
+
+    # Exemptions, checked before "do they hold one?" — an exempt traveller has
+    # nothing to hold:
+    #   * citizens of the destination (nobody needs permission to come home),
+    #   * whole blocs where freedom of movement applies (an EU/EEA citizen needs no
+    #     ETIAS in *any* member state, not merely their own),
+    #   * named nationalities exempt by treaty (Irish citizens for the UK ETA).
+    # Bloc exemption is per-authorization, not automatic: the UK ETA does apply to
+    # EU nationals, so `exempt_bloc_members` is false there.
+    exempt = auth.exempt_nationalities | {rule.country}
+    if auth.exempt_bloc_members:
+        exempt |= rule.bloc_members
+    exempt_held = [n for n in traveler.nationalities if n in exempt]
+    if exempt_held:
+        return TravelerBorder(
+            traveler.id,
+            rule.country,
+            regime,
+            exempt_held[0],
+            added,
+            authorization_kind=auth.kind,
+            authorization_status=AuthorizationStatus.NOT_NEEDED,
+            note=f"{exempt_held[0]} passport: no {auth.kind.upper()} required",
+        )
+
+    if traveler.holds(auth.kind, passport, departure):
+        return TravelerBorder(
+            traveler.id,
+            rule.country,
+            regime,
+            passport,
+            added,
+            authorization_kind=auth.kind,
+            authorization_status=AuthorizationStatus.HELD,
+            note=f"{auth.kind.upper()} held on the {passport} passport",
+        )
+
+    # Some passports cannot get the authorization at all — a different problem from
+    # simply not having applied yet, and one that a second passport may solve.
+    eligible_passports = [
+        p.nationality
+        for p in traveler.passports
+        if p.valid_on(departure)
+        and (
+            auth.eligible_nationalities is None or p.nationality in auth.eligible_nationalities
+        )
+    ]
+    if not eligible_passports:
+        return TravelerBorder(
+            traveler.id,
+            rule.country,
+            regime,
+            passport,
+            added,
+            authorization_kind=auth.kind,
+            authorization_status=AuthorizationStatus.INELIGIBLE,
+            note=(
+                f"{traveler.id}: no passport eligible for {auth.kind.upper()} "
+                f"({', '.join(traveler.nationalities)}). {auth.ineligible_note}".strip()
+            ),
+        )
+
+    # Prefer an eligible passport, even if another would have been marginally
+    # cheaper at the border: eligibility beats queue time.
+    if passport not in eligible_passports:
+        passport = eligible_passports[0]
+        if traveler.holds(auth.kind, passport, departure):
+            return TravelerBorder(
+                traveler.id,
+                rule.country,
+                regime,
+                passport,
+                added,
+                authorization_kind=auth.kind,
+                authorization_status=AuthorizationStatus.HELD,
+                note=f"{auth.kind.upper()} held on the {passport} passport",
+            )
+
+    full = auth.fee + auth.effort_hours * wage_rate_per_hour
+    amortized = full / max(1, auth.expected_uses) if auth.amortize else full
+    days_out = (departure - date.today()).days
+
+    if days_out < auth.lead_time_days:
+        return TravelerBorder(
+            traveler.id,
+            rule.country,
+            regime,
+            passport,
+            added,
+            authorization_kind=auth.kind,
+            authorization_status=AuthorizationStatus.TOO_LATE,
+            money_cost=amortized,
+            money_cost_full=full,
+            effort_hours=auth.effort_hours,
+            note=(
+                f"{auth.kind.upper()} needs {auth.lead_time_days} days; departure is "
+                f"in {days_out} — infeasible, not merely expensive"
+            ),
+        )
+
+    urgency = (
+        f" — apply now, {days_out} days to departure" if days_out <= auth.apply_now_days else ""
+    )
+    return TravelerBorder(
+        traveler.id,
+        rule.country,
+        regime,
+        passport,
+        added,
+        authorization_kind=auth.kind,
+        authorization_status=AuthorizationStatus.OBTAINABLE,
+        money_cost=amortized,
+        money_cost_full=full,
+        effort_hours=auth.effort_hours,
+        note=(
+            f"{auth.kind.upper()} needed on {passport} (~{auth.effort_hours:g}h, "
+            f"{full:.0f} one-off, {amortized:.0f} amortized over {auth.expected_uses} "
+            f"trips, valid {auth.validity_years:g}y){urgency}"
+        ),
+    )
+
+
+def resolve_party(
+    party: Party,
+    country: str,
+    *,
+    table: RegimeTable,
+    departure: date,
+    wage_rate_per_hour: float,
+    is_transit: bool = True,
+) -> PartyBorder:
+    per = [
+        resolve_traveler(
+            t,
+            country,
+            table=table,
+            departure=departure,
+            wage_rate_per_hour=wage_rate_per_hour,
+            is_transit=is_transit,
+        )
+        for t in party.travelers
+    ]
+    regime = per[0].regime if per else Regime.UNKNOWN
+    return PartyBorder(country.upper(), regime, per)
+
+
+def validity_window(rule: AuthorizationRule, granted: date) -> tuple[date, date]:
+    """Convenience for the report: an authorization's coverage period."""
+    return granted, granted + timedelta(days=int(365.25 * rule.validity_years))

layover/cost/connection.py

@@ -0,0 +1,173 @@
+"""Connection feasibility: required buffers, built rather than looked up (DESIGN §8.9).
+
+A self-transfer — two tickets, no airline responsible, nothing through-checked —
+needs materially more time than a protected connection, and how much more depends
+on baggage, on the border regime in the middle of it, and on when the inbound leg
+lands. The same gap that is comfortable at 09:00 is not comfortable at 19:00,
+because the inbound is statistically 20 minutes later.
+
+The composer calls this *before* pricing anything: an infeasible connection is not
+an expensive plan, it is not a plan.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from layover.cost.delay import DelayEstimate
+from layover.models import Connection, Protection
+from layover.prefs.profile import FeasibilityPrefs
+
+
+@dataclass(frozen=True, slots=True)
+class BufferBreakdown:
+    """Why the required buffer is what it is — printed in the report verbatim."""
+
+    base_minutes: float
+    bag_recheck_minutes: float
+    border_minutes: float
+    delay_allowance_minutes: float
+    multiplier: float
+
+    @property
+    def required_minutes(self) -> float:
+        raw = (
+            self.base_minutes
+            + self.bag_recheck_minutes
+            + self.border_minutes
+            + self.delay_allowance_minutes
+        )
+        return raw * self.multiplier
+
+    def explain(self) -> str:
+        parts = [f"base {self.base_minutes:.0f}m"]
+        if self.bag_recheck_minutes:
+            parts.append(f"bag re-check {self.bag_recheck_minutes:.0f}m")
+        if self.border_minutes:
+            parts.append(f"border {self.border_minutes:.0f}m")
+        if self.delay_allowance_minutes:
+            parts.append(f"delay allowance {self.delay_allowance_minutes:.0f}m")
+        tail = f" x{self.multiplier:g}" if self.multiplier != 1.0 else ""
+        return " + ".join(parts) + tail
+
+
+@dataclass(frozen=True, slots=True)
+class FeasibilityVerdict:
+    feasible: bool
+    required_minutes: float
+    gap_minutes: float
+    breakdown: BufferBreakdown
+    reason: str = ""
+
+    @property
+    def slack_minutes(self) -> float:
+        return self.gap_minutes - self.required_minutes
+
+
+def required_buffer(
+    connection: Connection,
+    prefs: FeasibilityPrefs,
+    *,
+    checked_bag: bool,
+    inbound_delay: DelayEstimate,
+    border_minutes: float = 0.0,
+    entry_required: bool = False,
+    carrier_mct_minutes: float = 45.0,
+    stake_multiplier: float = 1.0,
+) -> BufferBreakdown:
+    """Build the minimum connection time for one gap.
+
+    Protected connections use the airline's own MCT unmodified — the airline owns
+    the risk, and second-guessing its published minimum adds nothing.
+
+    `stake_multiplier` is how the stakes of a downstream hard constraint reach this
+    calculation: a connection standing between you and an unmissable event needs more
+    cushion than the same connection on a trip where being late costs a taxi. It
+    replaces the old per-trip "business mode" multiplier, which inflated every buffer
+    on a trip regardless of what was actually at risk.
+    """
+    if connection.protection is Protection.SINGLE_TICKET:
+        return BufferBreakdown(carrier_mct_minutes, 0.0, 0.0, 0.0, 1.0)
+
+    if connection.airport_change:
+        base = prefs.airport_change_h * 60
+    elif entry_required:
+        base = max(
+            prefs.self_transfer_entry_required_h * 60,
+            prefs.self_transfer_bag_recheck_h * 60,
+        )
+    elif checked_bag:
+        base = prefs.self_transfer_bag_recheck_h * 60
+    else:
+        base = prefs.self_transfer_same_airport_h * 60
+
+    # A checked bag on a separate ticket means claim, queue, re-check. When the base
+    # already assumes a re-check (or a border forces one), don't charge it twice.
+    bag = 0.0
+    if checked_bag and not entry_required and base <= prefs.self_transfer_same_airport_h * 60:
+        bag = (prefs.self_transfer_bag_recheck_h - prefs.self_transfer_same_airport_h) * 60
+
+    # Twice the inbound's mean slip: an evening inbound needs about an hour more
+    # than a morning one, which is the honest way to encode "evenings are worse".
+    delay_allowance = 2 * inbound_delay.mean_min
+
+    return BufferBreakdown(
+        base_minutes=base,
+        bag_recheck_minutes=bag,
+        border_minutes=border_minutes,
+        delay_allowance_minutes=delay_allowance,
+        multiplier=stake_multiplier,
+    )
+
+
+def assess(
+    connection: Connection,
+    prefs: FeasibilityPrefs,
+    *,
+    checked_bag: bool,
+    inbound_delay: DelayEstimate,
+    border_minutes: float = 0.0,
+    entry_required: bool = False,
+    carrier_mct_minutes: float = 45.0,
+    stopover_requested: bool = False,
+    stake_multiplier: float = 1.0,
+) -> FeasibilityVerdict:
+    """Decide whether a connection can be composed at all."""
+    breakdown = required_buffer(
+        connection,
+        prefs,
+        checked_bag=checked_bag,
+        inbound_delay=inbound_delay,
+        border_minutes=border_minutes,
+        entry_required=entry_required,
+        carrier_mct_minutes=carrier_mct_minutes,
+        stake_multiplier=stake_multiplier,
+    )
+    gap = connection.gap_minutes
+    required = breakdown.required_minutes
+
+    if not connection.is_protected:
+        if prefs.require_protected:
+            return FeasibilityVerdict(
+                False, required, gap, breakdown, "this run accepts protected itineraries only"
+            )
+        # The absolute floor is not negotiable downward: below it, no combination of
+        # optimism makes the connection real.
+        floor = prefs.absolute_floor_h * 60
+        if gap < floor:
+            return FeasibilityVerdict(
+                False, required, gap, breakdown, f"below the {prefs.absolute_floor_h:g}h floor"
+            )
+        # An airport change is no longer gated by a flag: it is priced (discomfort
+        # plus the ground leg) and has its own physical minimum, so the objective can
+        # decide. A requested stopover there makes it ordinary rather than overhead.
+
+    if gap < required:
+        return FeasibilityVerdict(
+            False,
+            required,
+            gap,
+            breakdown,
+            f"needs {required / 60:.1f}h ({breakdown.explain()}), has {gap / 60:.1f}h",
+        )
+    return FeasibilityVerdict(True, required, gap, breakdown)