layover 0.1.0.dev0__py3-none-any.whl

layover/cost/constraints.py

@@ -0,0 +1,213 @@
+"""Hard constraints, kept separate from soft preferences (DESIGN §8.1).
+
+The old model had one switch per trip — business or holiday — and real trips are
+not like that. A conference in Bogotá starts at a fixed hour, which is as hard as a
+constraint gets; but the way *there* was wide open, which is how a few days in Punta
+Cana ended up in the itinerary. One trip, strict at one end and exploratory at the
+other.
+
+So the two kinds of requirement are modelled separately and never mixed:
+
+* **Hard constraints** (this module) are facts about the world: be in Bogotá before
+  the conference opens, be home before Monday, do not depart before the last exam.
+  They are checked, not priced. A plan that violates one is not an expensive plan —
+  it is not a plan.
+* **Soft preferences** (`prefs/profile.py`) are prices: what an hour, a night, or a
+  day of slippage is worth. They can differ per leg, because time on the way to
+  something can be worth more than time on the way home.
+
+A constraint also carries **stakes** (`criticality`). That is what makes "definitely
+arrive by 20:00" mean something: a schedule check alone passes any plan that intends
+to be on time, however likely it is to slip. Stakes turn that probability into money,
+which is what the old business/holiday switch was crudely approximating.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from enum import StrEnum
+
+from layover.models import TripPlan
+
+
+class ConstraintKind(StrEnum):
+    ARRIVE_BY = "arrive_by"
+    """Be at this place, on the ground, before this moment. The conference."""
+
+    DEPART_AFTER = "depart_after"
+    """Cannot leave before this: a exam, a handover, a delivery."""
+
+    HOME_BY = "home_by"
+    """Be back at the origin before this. Monday morning, usually."""
+
+
+class Criticality(StrEnum):
+    """How bad it is to miss this. The whole point of the class.
+
+    A schedule check alone treats "arrive by 20:00" as satisfied by any plan that
+    *intends* to arrive at 14:00 — including one with a 15% chance of arriving
+    tomorrow. Stakes are what make "definitely" mean something: they turn a
+    probability of missing into a cost, so a risky plan loses on the objective
+    instead of needing a mode flag to forbid it.
+    """
+
+    INCONVENIENT = "inconvenient"
+    """A day of leave, a rebooked dinner. Annoying, survivable."""
+
+    SERIOUS = "serious"
+    """A missed day of a paid conference, a non-refundable booking."""
+
+    UNMISSABLE = "unmissable"
+    """Your own talk, a wedding, the last connection to a cruise."""
+
+
+@dataclass(frozen=True, slots=True)
+class HardConstraint:
+    """A requirement that is checked, never priced — plus the stakes of missing it.
+
+    `buffer_hours` is the part people forget: arriving 40 minutes before a conference
+    opens satisfies the letter of the constraint and fails the point of it. The
+    default of 12 hours means "the evening before".
+
+    `criticality` (or an explicit `violation_cost`) is what replaces the old
+    business/holiday distinction: cushion, risk appetite and the rejection of clever
+    itineraries all follow from how much missing this would cost.
+    """
+
+    kind: ConstraintKind
+    when: datetime
+    place: str | None = None
+    """None means "wherever the plan ends" (HOME_BY) or "anywhere" (DEPART_AFTER)."""
+    buffer_hours: float = 12.0
+    label: str = ""
+    """Human name — "IETF 129 opening session" beats "constraint 2" in a report."""
+    criticality: Criticality = Criticality.SERIOUS
+    violation_cost: float | None = None
+    """Overrides the criticality price when the real number is known."""
+
+    def cost_of_missing(self, prices: object) -> float:
+        """What missing this costs, in the normalization currency.
+
+        `prices` is a `ConstraintPrefs`; it is typed loosely to keep this module free
+        of a preferences import (constraints are facts, preferences are valuations).
+        """
+        if self.violation_cost is not None:
+            return self.violation_cost
+        return float(getattr(prices, self.criticality.value))
+
+    def stake_weight(self, prices: object) -> float:
+        """0..1 — how close to unmissable this is, for buffer inflation (§8.9)."""
+        top = float(getattr(prices, Criticality.UNMISSABLE.value))
+        if top <= 0:
+            return 0.0
+        return min(1.0, self.cost_of_missing(prices) / top)
+
+    @property
+    def effective_deadline(self) -> datetime:
+        if self.kind is ConstraintKind.DEPART_AFTER:
+            return self.when + timedelta(hours=self.buffer_hours)
+        return self.when - timedelta(hours=self.buffer_hours)
+
+    def describe(self) -> str:
+        name = self.label or self.place or ""
+        where = f" at {self.place}" if self.place else ""
+        buffer = f" (+{self.buffer_hours:g}h buffer)" if self.buffer_hours else ""
+        return f"{self.kind}{where} {self.when:%Y-%m-%d %H:%M}{buffer}" + (
+            f" — {name}" if self.label else ""
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ConstraintViolation:
+    constraint: HardConstraint
+    detail: str
+
+    def __str__(self) -> str:
+        return f"{self.constraint.describe()}: {self.detail}"
+
+
+def _arrival_at(plan: TripPlan, place: str) -> datetime | None:
+    """When the plan first puts the traveller on the ground at `place`."""
+    for segment in plan.segments:
+        if segment.destination == place:
+            return segment.arrive
+    return None
+
+
+def check(plan: TripPlan, constraints: list[HardConstraint]) -> list[ConstraintViolation]:
+    """Every way this plan fails a hard requirement.
+
+    All violations are returned rather than the first, because "this plan misses the
+    conference *and* gets you home a day late" is more useful than either half.
+    """
+    violations: list[ConstraintViolation] = []
+
+    for constraint in constraints:
+        deadline = constraint.effective_deadline
+
+        if constraint.kind is ConstraintKind.ARRIVE_BY:
+            if constraint.place is None:
+                arrival = plan.arrive
+            else:
+                arrival = _arrival_at(plan, constraint.place)
+                if arrival is None:
+                    violations.append(
+                        ConstraintViolation(
+                            constraint, f"the plan never reaches {constraint.place}"
+                        )
+                    )
+                    continue
+            if arrival > deadline:
+                late = (arrival - deadline).total_seconds() / 3600
+                violations.append(
+                    ConstraintViolation(
+                        constraint,
+                        f"arrives {arrival:%Y-%m-%d %H:%M}, {late:.1f}h past the "
+                        f"{constraint.buffer_hours:g}h buffer",
+                    )
+                )
+
+        elif constraint.kind is ConstraintKind.DEPART_AFTER:
+            if plan.depart < deadline:
+                early = (deadline - plan.depart).total_seconds() / 3600
+                violations.append(
+                    ConstraintViolation(
+                        constraint,
+                        f"departs {plan.depart:%Y-%m-%d %H:%M}, {early:.1f}h too early",
+                    )
+                )
+
+        elif constraint.kind is ConstraintKind.HOME_BY and plan.arrive > deadline:
+            late = (plan.arrive - deadline).total_seconds() / 3600
+            violations.append(
+                ConstraintViolation(
+                    constraint,
+                    f"home {plan.arrive:%Y-%m-%d %H:%M}, {late:.1f}h late",
+                )
+            )
+
+    return violations
+
+
+def slack_before(plan: TripPlan, constraint: HardConstraint) -> float | None:
+    """Hours of room a plan has against one constraint.
+
+    This is what makes discovered stopovers possible on a work trip: a conference
+    that opens Thursday morning leaves days of slack on the way out, and slack is
+    exactly what a stopover spends. Returns None when the constraint does not apply
+    to this plan.
+    """
+    deadline = constraint.effective_deadline
+    if constraint.kind is ConstraintKind.ARRIVE_BY:
+        arrival = (
+            plan.arrive if constraint.place is None else _arrival_at(plan, constraint.place)
+        )
+        if arrival is None:
+            return None
+        return (deadline - arrival).total_seconds() / 3600
+    if constraint.kind is ConstraintKind.DEPART_AFTER:
+        return (plan.depart - deadline).total_seconds() / 3600
+    if constraint.kind is ConstraintKind.HOME_BY:
+        return (deadline - plan.arrive).total_seconds() / 3600
+    return None

layover/cost/curve.py

@@ -0,0 +1,145 @@
+"""One curve, used by everything that has a min, an ideal and a max (§8.4).
+
+Departure, arrival and length are the same shape of preference. You state the
+earliest that is possible at all, the value you actually want, and the latest — and
+everything between is priced by how far it is from the ideal, in units of a tolerance
+breadth:
+
+    cost = scale × ((value − ideal) / tolerance)²
+
+Quadratic rather than linear because that is how the preference behaves: the first
+step off target barely registers, the last one before the hard edge is expensive. The
+tolerance defaults, per side, to the distance from the ideal to that bound — so the
+edges cost exactly `scale`, and where the ideal sits inside the window *is* the
+statement about which side is tighter. No asymmetry syntax required.
+
+Everything here is in one unit. Callers convert first: days or hours for moments,
+nights for lengths. That is the whole reason this module knows nothing about dates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Bounds:
+    """A window's three values, after the missing ones have been filled in."""
+
+    low: float
+    ideal: float
+    high: float
+    inferred: tuple[str, ...] = ()
+    """Which of the three were not stated — the report says so rather than pretending."""
+
+    def contains(self, value: float) -> bool:
+        return self.low <= value <= self.high
+
+
+def resolve(
+    low: float | None,
+    ideal: float | None,
+    high: float | None,
+    *,
+    spread: float | None = None,
+) -> Bounds:
+    """Fill in whichever of min/ideal/max were left out.
+
+    Two of the three is usually what someone actually knows — "no earlier than the
+    22nd, ideally the 24th", or "between five and nine nights" — and requiring the
+    third would only invite a made-up number. The rules:
+
+    * **min and max, no ideal.** The middle. Nothing was said to prefer either end.
+    * **one bound and an ideal.** Mirror the stated side. "Ideally Tuesday, no later
+      than Friday" says three days late is the limit, and says nothing about early;
+      treating early as unbounded would let the search wander off, and treating it as
+      forbidden would rule out Monday for no reason. Symmetry is the reading that
+      invents least.
+    * **an ideal alone.** A `spread` if the caller has one (`plus_minus_days`), else a
+      window of exactly one value — which is a legitimate thing to want.
+
+    Nothing at all is an error; a window has to be about something.
+    """
+    inferred: list[str] = []
+    if ideal is None:
+        if low is not None and high is not None:
+            ideal = (low + high) / 2
+            inferred.append("ideal")
+        elif low is not None or high is not None:
+            ideal = low if low is not None else high
+            inferred.append("ideal")
+        else:
+            raise ValueError("a window needs at least one of min, ideal or max")
+
+    if low is None and high is None and spread is not None:
+        low, high = ideal - spread, ideal + spread
+    if low is None:
+        low = ideal - (high - ideal) if high is not None else ideal
+        inferred.append("min")
+    if high is None:
+        high = ideal + (ideal - low)
+        inferred.append("max")
+
+    if low > high:
+        raise ValueError(f"window is empty: min {low} is after max {high}")
+    if not low <= ideal <= high:
+        raise ValueError(f"ideal {ideal} lies outside min {low}..max {high}")
+    return Bounds(low, ideal, high, tuple(inferred))
+
+
+def tolerance_for(bounds: Bounds, *, earlier: bool, stated: float | None = None) -> float:
+    """The breadth of the curve on one side, in the caller's unit."""
+    if stated is not None:
+        return stated
+    return (bounds.ideal - bounds.low) if earlier else (bounds.high - bounds.ideal)
+
+
+def cost(
+    value: float,
+    bounds: Bounds,
+    *,
+    scale: float,
+    tolerance: float | None = None,
+    offset: float = 0.0,
+) -> float | None:
+    """What this value costs. None means outside the window — not merely expensive.
+
+    Outside the bounds there is no window at all, which every caller must read as
+    "this does not exist" rather than "this is dear". Hard edges stay hard (§8.1).
+
+    `offset` moves the whole curve vertically, which is how a stop that is *worth
+    having* is expressed: a fortnight in Punta Cana at −800 rises through zero and
+    eventually goes positive, because the square swamps any offset in the end. That
+    is what bounds a desirable stay without needing a hard maximum — and it is only
+    meaningful for lengths. Moments are relative (you must depart at some point, so
+    only differences matter); lengths are absolute, since not stopping at all is a
+    real alternative (§8.3).
+    """
+    if not bounds.contains(value):
+        return None
+    delta = value - bounds.ideal
+    if not delta:
+        return offset
+    breadth = tolerance_for(bounds, earlier=delta < 0, stated=tolerance)
+    if not breadth:
+        # The bound and the ideal coincide on this side, so anything off-target is
+        # already at the limit of what was allowed.
+        return offset + scale
+    return offset + scale * (delta / breadth) ** 2
+
+
+def breakeven(
+    bounds: Bounds, *, scale: float, tolerance: float | None = None, offset: float = 0.0
+) -> tuple[float, float] | None:
+    """Where an offset curve crosses zero — the range over which a stop pays for itself.
+
+    The answerable form of the question §10 asks: not "do you like Santorini?" but
+    "three to eleven nights pays for itself; past eleven it stops". None when the curve
+    never crosses, which means either the stop is never worth it or always is.
+    """
+    if offset >= 0:
+        return None
+    low = tolerance_for(bounds, earlier=True, stated=tolerance)
+    high = tolerance_for(bounds, earlier=False, stated=tolerance)
+    reach = (-offset / scale) ** 0.5 if scale > 0 else float("inf")
+    return bounds.ideal - low * reach, bounds.ideal + high * reach

layover/cost/delay.py

@@ -0,0 +1,173 @@
+"""Delay priors and punctuality blending (DESIGN §8.5).
+
+Delay is systematic, not noise: the first rotation leaves on time because the
+aircraft slept there, slip accumulates through the day, and evening departures are
+worst with no recovery flight left. A coarse prior by local departure hour is
+enough to make an 07:20 departure beat a 19:05 one at equal fare.
+
+For shortlisted flights the prior is *refined* by observed punctuality, never
+replaced by it: four recent flights should nudge an estimate, sixty should decide
+it. That is Bayesian shrinkage with the prior worth k pseudo-observations.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class DelayEstimate:
+    """Expected slip and the tail probability that decides connections."""
+
+    mean_min: float
+    p_over_60: float
+    cancelled_pct: float = 1.5
+    samples: int = 0
+    source: str = "prior"
+
+    @property
+    def is_observed(self) -> bool:
+        return self.samples > 0
+
+
+@dataclass(frozen=True, slots=True)
+class PunctualityObservation:
+    """What a punctuality oracle reported for one flight (ORACLES §8)."""
+
+    mean_delay_min: float
+    p_over_60: float
+    samples: int
+    cancelled_pct: float = 0.0
+    window_days: int = 90
+    same_season: bool = True
+    source: str = "unknown"
+
+
+class DelayTable:
+    """Hour-bucket prior, loaded from `reference/delay_profiles.toml`."""
+
+    def __init__(
+        self,
+        buckets: dict[tuple[int, int], DelayEstimate],
+        *,
+        long_haul_mean_multiplier: float = 1.1,
+        long_haul_p_multiplier: float = 0.8,
+        cancellation_prior_pct: float = 1.5,
+        as_of: str = "unknown",
+        source: str = "unknown",
+    ) -> None:
+        if not buckets:
+            raise ValueError("delay table needs at least one hour bucket")
+        self._buckets = buckets
+        self.long_haul_mean_multiplier = long_haul_mean_multiplier
+        self.long_haul_p_multiplier = long_haul_p_multiplier
+        self.cancellation_prior_pct = cancellation_prior_pct
+        self.as_of = as_of
+        self.source = source
+
+    @classmethod
+    def from_toml(cls, path: Path) -> DelayTable:
+        raw = tomllib.loads(path.read_text())
+        buckets: dict[tuple[int, int], DelayEstimate] = {}
+        cancel = float((raw.get("cancellation") or {}).get("prior_pct", 1.5))
+        for span, body in (raw.get("by_local_departure_hour") or {}).items():
+            start, _, end = span.partition("-")
+            buckets[(int(start), int(end))] = DelayEstimate(
+                mean_min=float(body["mean_min"]),
+                p_over_60=float(body["p_over_60"]),
+                cancelled_pct=cancel,
+            )
+        long_haul = raw.get("long_haul") or {}
+        return cls(
+            buckets,
+            long_haul_mean_multiplier=float(long_haul.get("mean_min_multiplier", 1.1)),
+            long_haul_p_multiplier=float(long_haul.get("p_over_60_multiplier", 0.8)),
+            cancellation_prior_pct=cancel,
+            as_of=str(raw.get("as_of", "unknown")),
+            source=str(raw.get("source", "unknown")),
+        )
+
+    @classmethod
+    def fallback(cls) -> DelayTable:
+        """Built-in prior, so the cost model works before reference data is wired."""
+        return cls(
+            {
+                (0, 5): DelayEstimate(18, 0.10),
+                (5, 9): DelayEstimate(8, 0.04),
+                (9, 13): DelayEstimate(14, 0.07),
+                (13, 18): DelayEstimate(20, 0.11),
+                (18, 24): DelayEstimate(28, 0.16),
+            },
+            as_of="built-in",
+            source="built-in fallback prior",
+        )
+
+    def prior_for_hour(self, hour: int, *, long_haul: bool = False) -> DelayEstimate:
+        hour %= 24
+        for (start, end), bucket in sorted(self._buckets.items()):
+            if start <= hour < end:
+                estimate = bucket
+                break
+        else:  # pragma: no cover — buckets are expected to cover the clock
+            estimate = max(self._buckets.items())[1]
+        if not long_haul:
+            return estimate
+        return DelayEstimate(
+            mean_min=estimate.mean_min * self.long_haul_mean_multiplier,
+            p_over_60=min(1.0, estimate.p_over_60 * self.long_haul_p_multiplier),
+            cancelled_pct=estimate.cancelled_pct,
+            source="prior (long-haul adjusted)",
+        )
+
+
+def blend(
+    prior: DelayEstimate,
+    observed: PunctualityObservation | None,
+    *,
+    pseudo_observations: int = 10,
+) -> DelayEstimate:
+    """Shrink observed punctuality toward the prior.
+
+    With k=10, four samples move the estimate ~29% of the way to what was
+    observed and sixty samples move it ~86%. Small samples nudge; large samples
+    decide. An out-of-season window is discounted by halving its effective weight,
+    because a January sample says little about August.
+    """
+    if observed is None or observed.samples <= 0:
+        return prior
+
+    k = max(1, pseudo_observations)
+    weight = observed.samples * (1.0 if observed.same_season else 0.5)
+    total = k + weight
+
+    return DelayEstimate(
+        mean_min=(k * prior.mean_min + weight * observed.mean_delay_min) / total,
+        p_over_60=(k * prior.p_over_60 + weight * observed.p_over_60) / total,
+        cancelled_pct=(k * prior.cancelled_pct + weight * observed.cancelled_pct) / total,
+        samples=observed.samples,
+        source=f"blended: {observed.source} ({observed.samples} samples, k={k})",
+    )
+
+
+def p_miss(estimate: DelayEstimate, cushion_minutes: float) -> float:
+    """Probability an unprotected connection is missed, given its total cushion.
+
+    `cushion_minutes` is *all* the absorbing time the connection has: the slack
+    beyond the required buffer plus the delay allowance already built into that
+    buffer (§8.9). Callers must not pass bare slack — the buffer already contains
+    an allowance, and double-counting it the other way would make every connection
+    look doomed.
+
+    `p_over_60` anchors the curve: P(delay > t) = p_over_60 ** (t / 60). Crude on
+    purpose — a delay distribution is not knowable from two numbers — but it has
+    the properties that matter: monotonically decreasing in cushion, never zero,
+    and exactly the observed hourly tail at 60 minutes.
+    """
+    if cushion_minutes <= 0:
+        # No absorbing time at all: the connection needs an on-time arrival, which
+        # even good flights cannot promise.
+        return 1.0
+    anchor = min(max(estimate.p_over_60, 1e-4), 0.99)
+    return float(min(1.0, anchor ** (cushion_minutes / 60.0)))