layover 0.1.0.dev0__py3-none-any.whl

layover/prefs/profile.py

@@ -0,0 +1,333 @@
+"""Preference profile: the money-denominated valuations (DESIGN §8).
+
+Every field here is a **price** — per hour, per night, per event — never a weight.
+That is what keeps the objective a single comparable scalar and lets a report explain
+a ranking in euros.
+
+These are the *soft* half. Hard requirements ("be in Bogotá before the conference
+opens") live in `cost/constraints.py`, are checked rather than priced, and carry the
+stakes of missing them. There is deliberately **no trip type**: "business" turned out
+to be a bundle of things that either belong to a constraint (a deadline, and how much
+cushion its stakes deserve) or are plain numbers that may differ per leg.
+
+Three families, kept apart because they answer different questions:
+
+1. **Time** (`[time]`) — what an hour is worth, times how much of the hour you get
+   back. The factors here are *productivity* only: in-flight time is discounted
+   because you can sleep or work, lounge time because you can work.
+2. **Discomfort** (`[discomfort]`) — what unpleasantness is worth, as fixed amounts
+   scaled by one `scale` knob. Deliberately **not** multiplied by the wage rate: how
+   much you mind a broken night or dragging bags across a city does not depend on what
+   your hour is worth. This is the comfort axis, and it is separate on purpose.
+3. **Risk** — no longer configured as premiums. It is computed: the probability of
+   missing a connection times what missing it costs, including the stakes of any hard
+   constraint it would break.
+
+Loading order (later wins, per key):
+    1. repo `config/preferences.toml`         — shipped defaults
+    2. `~/.config/layover/preferences.toml`   — the owner's values
+    3. per-intent or per-leg overrides        — plain nested dicts
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Strict(BaseModel):
+    """Base for every preference model: unknown keys are errors, not noise.
+
+    Pydantic ignores extra fields by default, which meant a mistyped or
+    wrongly-nested config key was silently dropped and the shipped default used
+    instead — a wrong ranking that looks right. Forbidding extras turns that into a
+    startup error naming the key.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class TimePrefs(Strict):
+    """The price of time, and how much of each hour you actually get back."""
+
+    wage_rate_per_hour: float = 25.0
+    in_flight_factor: float = 0.6
+    """You can sleep, read, work. Productivity, not comfort."""
+    layover_factor: float = 1.0
+    """The reference unit: an hour you get nothing back from."""
+    ground_transfer_factor: float = 1.0
+    """A train between airports is about as usable as a gate area."""
+
+
+class DiscomfortPrefs(Strict):
+    """What unpleasantness costs, independent of what an hour is worth.
+
+    Fixed amounts rather than time multipliers, because most of these are not
+    proportional to duration: a broken night is a broken night whether the flight is
+    two hours or twelve, and the stress of a 45-minute connection is not 45 minutes of
+    anything. Each is multiplied by `scale` — the single comfort knob: 0.5 if airports
+    genuinely don't bother you, 2.0 for an easy trip at almost any price.
+    """
+
+    scale: float = 1.0
+
+    red_eye_per_flight: float = 25.0
+    """Departing 23:00–05:00: a night you don't get back."""
+    red_eye_from_hour: int = 23
+    red_eye_to_hour: int = 5
+
+    tight_connection: float = 12.0
+    """Running for a gate. Fixed, not per minute."""
+    tight_connection_minutes: int = 90
+
+    night_in_terminal: float = 90.0
+    """Sleeping in an airport, per night."""
+
+    bag_recheck: float = 10.0
+    """Claim, queue, re-drop."""
+
+    self_transfer: float = 25.0
+    """Managing your own connection: watching the clock, nobody helping if it slips."""
+    separate_ticket: float = 30.0
+    """Two contracts instead of one — rebooking is yours to do. This is the *hassle*
+    of it; the money risk is computed from probabilities, not set here."""
+    third_party_guarantee: float = 10.0
+    """Aggregator-guaranteed self-transfer: covered, but you handle the claim."""
+    airport_change: float = 45.0
+    """Crossing a city with luggage between two flights."""
+    border_entry_exit: float = 40.0
+    """Immigration, customs and re-screening in the middle of a journey."""
+    lcc_bag_gauge: float = 10.0
+    """The gate-side sizer lottery."""
+
+    def cost(self, amount: float) -> float:
+        """Apply the comfort scale to one discomfort amount."""
+        return amount * self.scale
+
+
+class OvernightPrefs(Strict):
+    """Where an overnight gap is spent: the terminal's misery is discomfort, the hotel
+    is real money."""
+
+    airport_hotel_cost: float = 90.0
+    hotel_transfer_hours: float = 1.5
+    window_from_hour: int = 22
+    window_to_hour: int = 7
+    min_night_hours: float = 5.0
+    """Shorter than this is a late wait, not a lost night."""
+
+
+class LoungePrefs(Strict):
+    wait_factor: float = 0.35
+    """A lounge gives most of the hour back — productivity, so it belongs with time."""
+    min_wait_to_use_h: float = 1.5
+    overage_price: float = 30.0
+    trips_per_year: int = 8
+    use: str = "if_worth_it"
+    """if_worth_it | never. There is no "always": a lounge is taken when it pays for
+    itself, and its absence makes a plan slightly worse — never infeasible."""
+
+
+class StopoverPrefs(Strict):
+    """What a stop is worth, as one signed number per place (§8.3).
+
+    Net, always: hotel minus whatever being there is worth. A hotel rate is guessable
+    and what a place is worth to *you* is not, and only the difference ever ranks
+    anything — so the model asks for the difference and nothing else.
+    """
+
+    candidate_min_hours: float = 10.0
+    """Gaps at least this long are offered as stopovers (DESIGN §8.3). Below it the
+    question is noise: nobody takes a hotel for a six-hour connection."""
+    offer: bool = True
+    """Whether unexpected long gaps are offered at all. Slack decides whether there is
+    anything to offer; this only silences the question for a run."""
+    net: dict[str, float] = Field(default_factory=dict)
+    """Standing wishlist, place -> net cost of a stay there. **Negative means wanted.**
+
+    A routing through one of these is a wanted stop without asking — the owner
+    answered in advance. Zero is the honest default for a place never mentioned: a
+    wash, neither hunted for nor penalized."""
+
+
+class FlexibilityPrefs(Strict):
+    date_cost_at_tolerance: float = 60.0
+    """What the edge of a date window costs when the intent does not price it itself.
+
+    The scale of the quadratic in §8.4: `cost = this × ((when − ideal) / tolerance)²`,
+    with the tolerance defaulting to the distance from the ideal to each bound. A trip
+    that cares unusually much (or little) about its dates overrides it per window;
+    this is the standing answer to "what is a day of slippage worth to me"."""
+    length_cost_at_tolerance: float = 40.0
+    """The same, for windows counted in nights: trip length and stopover length.
+
+    Its own number because "a day later than I wanted to leave" and "a night longer
+    than I wanted to stay" are not the same regret — the second one you are at least
+    somewhere, which is why this is the smaller of the two."""
+    date_deviation_cost_per_day: float = 12.0
+    """Only for windows written with the older flat per-day sugar."""
+    duration_deviation_cost_per_night: float = 10.0
+    """Symmetric fallback, used when neither direction below is set."""
+    extra_day_away_cost: float | None = None
+    """Each night longer than preferred: leave days, a second hotel, the dog.
+
+    This is the number a discovered stopover has to beat — leaving three days early
+    for Punta Cana costs three days away from home, and the value of being there must
+    cover them."""
+    missing_day_cost: float | None = None
+    """Each night shorter than preferred: less trip than you wanted."""
+    time_of_day: dict[str, dict[str, float]] = Field(default_factory=dict)
+
+    def duration_cost(self, nights: int, preferred: int) -> float:
+        """Price the gap between a trip's length and the length that was wanted.
+
+        Asymmetric on purpose: an extra day away and a day short of the trip you
+        planned are different kinds of loss.
+        """
+        if nights == preferred:
+            return 0.0
+        if nights > preferred:
+            rate = (
+                self.extra_day_away_cost
+                if self.extra_day_away_cost is not None
+                else self.duration_deviation_cost_per_night
+            )
+            return (nights - preferred) * rate
+        rate = (
+            self.missing_day_cost
+            if self.missing_day_cost is not None
+            else self.duration_deviation_cost_per_night
+        )
+        return (preferred - nights) * rate
+
+
+class DelayPrefs(Strict):
+    misconnect_replacement_cost: float = 180.0
+    """Fallback price of a replacement ticket when the onward leg's real price is not
+    known. This is the *money* consequence of a miss."""
+    prior_pseudo_observations: int = 10
+    """Weight of the static prior when blending observed punctuality."""
+    recovery_hours: float = 6.0
+    """How much later you realistically arrive after missing a connection."""
+    recovery_hours_overnight: float = 20.0
+    """...and when the missed flight was the last departure of the day."""
+
+
+class ConstraintPrefs(Strict):
+    """What missing a hard requirement costs (DESIGN §8.1).
+
+    This is what "definitely arrive by 20:00" actually means. A schedule check alone
+    would pass any plan that *plans* to arrive at 14:00, however likely it is to slip
+    to tomorrow. Stakes make risky plans lose on cost, and make the composer demand
+    more cushion — which is the job the old business/holiday switch was doing badly.
+    """
+
+    inconvenient: float = 150.0
+    serious: float = 800.0
+    unmissable: float = 3000.0
+    stake_buffer_max_multiplier: float = 1.5
+    """Required buffers inflate up to this much as stakes rise (§8.9). At
+    `unmissable` this reproduces the old business-mode 1.5x — for the right reason."""
+
+    def cost_of(self, criticality: str) -> float:
+        value = getattr(self, criticality, None)
+        if value is None:
+            raise KeyError(f"unknown criticality {criticality!r}")
+        return float(value)
+
+
+class FeasibilityPrefs(Strict):
+    """Physical minimums: whether a connection is *makeable*.
+
+    Whether it is *wise* is the objective's judgement, via expected cost — which is
+    why the old `allow_self_transfer` / `buffer_multiplier` knobs are gone.
+    """
+
+    absolute_floor_h: float = 2.0
+    self_transfer_same_airport_h: float = 3.0
+    self_transfer_bag_recheck_h: float = 4.0
+    self_transfer_entry_required_h: float = 5.0
+    airport_change_h: float = 5.0
+    require_protected: bool = False
+    """For a run where only single-ticket itineraries are acceptable at any price. A
+    blunt instrument, rarely needed now that risk is priced against stakes."""
+    protected_connection: str = "carrier_mct"
+    carrier_mct_default_minutes: float = 45.0
+
+
+class GroundPrefs(Strict):
+    default_metro_transfer_cost: float = 25.0
+    default_metro_transfer_hours: float = 1.25
+
+
+class VerificationPrefs(Strict):
+    shortlist_size: int = 5
+    changed_threshold_fraction: float = 0.01
+    changed_threshold_absolute: float = 5.0
+
+
+class PreferenceProfile(Strict):
+    normalize_currency: str = "EUR"
+    label: str | None = None
+    """Optional name for a saved set of overrides, for the report only. It carries no
+    meaning in the model — there is no trip type."""
+    time: TimePrefs = Field(default_factory=TimePrefs)
+    discomfort: DiscomfortPrefs = Field(default_factory=DiscomfortPrefs)
+    overnight: OvernightPrefs = Field(default_factory=OvernightPrefs)
+    lounge: LoungePrefs = Field(default_factory=LoungePrefs)
+    stopover: StopoverPrefs = Field(default_factory=StopoverPrefs)
+    flexibility: FlexibilityPrefs = Field(default_factory=FlexibilityPrefs)
+    delay: DelayPrefs = Field(default_factory=DelayPrefs)
+    constraints: ConstraintPrefs = Field(default_factory=ConstraintPrefs)
+    feasibility: FeasibilityPrefs = Field(default_factory=FeasibilityPrefs)
+    ground: GroundPrefs = Field(default_factory=GroundPrefs)
+    verification: VerificationPrefs = Field(default_factory=VerificationPrefs)
+
+    def with_overrides(self, overrides: dict[str, Any]) -> PreferenceProfile:
+        """Return a copy with a nested dict merged in (per key, not per section).
+
+        This is also how a per-leg difference is expressed: a leg is not a "mode", it
+        is these numbers with a few of them changed.
+        """
+        return PreferenceProfile.model_validate(_deep_merge(self.model_dump(), overrides))
+
+
+def _deep_merge(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for key, value in overlay.items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _deep_merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def load_preferences(
+    paths: list[Path],
+    *,
+    overrides: dict[str, Any] | None = None,
+) -> PreferenceProfile:
+    """Compose a profile from config files, then overrides.
+
+    Missing files are skipped: the shipped defaults are a complete configuration, so a
+    first run works before anything is customized.
+    """
+    merged: dict[str, Any] = {}
+    for path in paths:
+        if path.is_file():
+            merged = _deep_merge(merged, tomllib.loads(path.read_text()))
+    if overrides:
+        merged = _deep_merge(merged, overrides)
+    return PreferenceProfile.model_validate(merged)
+
+
+def default_config_paths(repo_config: Path | None = None) -> list[Path]:
+    """Shipped defaults first, then the owner's overrides."""
+    paths: list[Path] = []
+    if repo_config is not None:
+        paths.append(repo_config / "preferences.toml")
+    paths.append(Path.home() / ".config" / "layover" / "preferences.toml")
+    return paths

layover/prefs/travelers.py

@@ -0,0 +1,125 @@
+"""Travellers and parties (DESIGN §8.6, §13.9).
+
+Identity and entitlements only, loaded from its own file — never the repo, never
+mixed with valuations. No document numbers: nationality, expiry and authorization
+validity are everything the cost model needs, and nothing here books anything.
+
+A party is 1–2 adults on one itinerary. The combining rules matter more than they
+look: time takes the party's *maximum* (a couple clears immigration together, at
+the slower queue), money and applications are *per person*, and one traveller who
+cannot be admitted makes the routing infeasible for everyone.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from datetime import date
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class Passport(BaseModel):
+    nationality: str = Field(min_length=2, max_length=2)
+    expires: date | None = None
+
+    def valid_on(self, day: date) -> bool:
+        return self.expires is None or self.expires > day
+
+
+class Authorization(BaseModel):
+    """A travel authorization (ESTA, UK ETA, eTA, ETIAS, or a full visa).
+
+    Bound to the passport it was issued against, because that is how it works —
+    and because a spouse holding IT+BR can only ever hang a US authorization off
+    the IT passport.
+    """
+
+    kind: str
+    passport: str = Field(min_length=2, max_length=2)
+    expires: date | None = None
+
+    def covers(self, nationality: str, day: date) -> bool:
+        return self.passport == nationality and (self.expires is None or self.expires > day)
+
+
+class LoungeMembership(BaseModel):
+    program: str = "none"
+    annual_quota: int = 0
+    quota_used: int = 0
+    year_resets_on: date | None = None
+
+    @property
+    def quota_remaining(self) -> int:
+        return max(0, self.annual_quota - self.quota_used)
+
+    @property
+    def has_program(self) -> bool:
+        return self.program != "none" and self.annual_quota > 0
+
+
+class Traveler(BaseModel):
+    id: str
+    passports: list[Passport] = Field(default_factory=list)
+    held_authorizations: list[Authorization] = Field(default_factory=list)
+    lounge: LoungeMembership = Field(default_factory=LoungeMembership)
+
+    @property
+    def nationalities(self) -> list[str]:
+        return [p.nationality for p in self.passports]
+
+    def passport_valid_on(self, nationality: str, day: date) -> bool:
+        return any(p.nationality == nationality and p.valid_on(day) for p in self.passports)
+
+    def holds(self, kind: str, nationality: str, day: date) -> bool:
+        return any(
+            a.kind == kind and a.covers(nationality, day) for a in self.held_authorizations
+        )
+
+
+class Party(BaseModel):
+    """The travellers on one search."""
+
+    travelers: list[Traveler] = Field(min_length=1)
+
+    @property
+    def size(self) -> int:
+        return len(self.travelers)
+
+    @property
+    def ids(self) -> list[str]:
+        return [t.id for t in self.travelers]
+
+    def get(self, traveler_id: str) -> Traveler:
+        for t in self.travelers:
+            if t.id == traveler_id:
+                return t
+        raise KeyError(f"no traveller {traveler_id!r} in party {self.ids}")
+
+
+def load_travelers(path: Path) -> dict[str, Traveler]:
+    """Load `travelers.toml`. Absent file = no travellers configured."""
+    if not path.is_file():
+        return {}
+    raw = tomllib.loads(path.read_text())
+    out: dict[str, Traveler] = {}
+    for traveler_id, body in (raw.get("traveler") or {}).items():
+        data = dict(body)
+        lounge = data.pop("lounge", None)
+        out[traveler_id] = Traveler.model_validate(
+            {
+                "id": traveler_id,
+                **data,
+                **({"lounge": lounge} if lounge else {}),
+            }
+        )
+    return out
+
+
+def default_travelers_path() -> Path:
+    return Path.home() / ".config" / "layover" / "travelers.toml"
+
+
+def solo(traveler_id: str = "owner", **kwargs) -> Party:
+    """A one-person party — the common case, and handy in tests."""
+    return Party(travelers=[Traveler(id=traveler_id, **kwargs)])