f1verse 0.3.0__py3-none-any.whl

f1verse/__init__.py

@@ -0,0 +1,45 @@
+"""f1verse — the story layer for Formula 1 data.
+
+Native (no FastF1 required, seasons 2023+):
+
+>>> import f1verse
+>>> race = f1verse.load(2026, 12)
+>>> race.laps_led()              # {'NOR': 31, 'ANT': 32, ...}
+>>> race.story()                 # whole race as JSON-safe dict
+>>> race.championship_prediction()   # the feed everyone throws away
+
+FastF1 adapter (``pip install f1verse[fastf1]``) for telemetry, qualifying
+segments and pre-2023 seasons:
+
+>>> story = f1verse.analyze(fastf1_session)
+"""
+from . import http
+from ._json import jsonsafe
+from .feeds import championship_prediction, team_radio, timing_stats
+from .gaps import format_gap
+from .crosscheck import crosscheck
+from .race import Race, load
+
+__version__ = "0.3.0"
+_FASTF1_API = {"analyze", "leader_runs", "laps_led", "timeline", "stints",
+               "race_pace", "results", "interruption_bands",
+               "integrity_report"}
+
+
+def __getattr__(name):
+    if name in _FASTF1_API:
+        try:
+            from . import integrity, story
+        except ImportError as e:
+            raise ImportError(
+                f"f1verse.{name} needs the FastF1 adapter: "
+                "pip install f1verse[fastf1]") from e
+        mod = integrity if name == "integrity_report" else story
+        return getattr(mod, name)
+    raise AttributeError(name)
+
+
+enable_cache = http.enable_cache
+__all__ = ["load", "Race", "format_gap", "jsonsafe", "enable_cache",
+           "championship_prediction", "team_radio", "timing_stats",
+           "crosscheck", *sorted(_FASTF1_API)]

f1verse/_json.py

@@ -0,0 +1,52 @@
+"""JSON-safe conversion — every public f1verse output passes through here.
+
+Works with or without numpy/pandas installed: the native loader returns
+plain Python already; the FastF1 adapter returns numpy scalars and pandas
+timestamps that ``json.dumps`` rejects.
+"""
+import datetime
+import math
+
+try:
+    import numpy as _np
+except ImportError:          # zero-dep native install
+    _np = None
+try:
+    import pandas as _pd
+except ImportError:
+    _pd = None
+
+
+def jsonsafe(obj):
+    """Recursively convert *obj* to plain JSON-serializable Python types."""
+    if obj is None or isinstance(obj, (bool, str)):
+        return obj
+    if _np is not None and isinstance(obj, _np.integer):
+        return int(obj)
+    if isinstance(obj, int):
+        return obj
+    if (_np is not None and isinstance(obj, _np.floating)) or isinstance(obj, float):
+        f = float(obj)
+        return None if math.isnan(f) else f
+    if isinstance(obj, datetime.timedelta):
+        return obj.total_seconds()
+    if isinstance(obj, (datetime.datetime, datetime.date)):
+        return obj.isoformat()
+    if _pd is not None:
+        if isinstance(obj, _pd.Timedelta):
+            return None if obj is _pd.NaT else obj.total_seconds()
+        if isinstance(obj, _pd.Timestamp):
+            return obj.isoformat()
+        if obj is _pd.NaT:
+            return None
+    if isinstance(obj, dict):
+        return {str(k): jsonsafe(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple, set)):
+        return [jsonsafe(v) for v in obj]
+    if _np is not None and isinstance(obj, _np.ndarray):
+        return [jsonsafe(v) for v in obj.tolist()]
+    if _pd is not None and isinstance(obj, _pd.Series):
+        return [jsonsafe(v) for v in obj.tolist()]
+    if _pd is not None and _pd.isna(obj):
+        return None
+    return str(obj)

f1verse/crosscheck.py

@@ -0,0 +1,110 @@
+"""Cross-validation layer — publish only when independent sources agree.
+
+One wrong number costs a data project its credibility. ``crosscheck`` runs
+a race through independent checks and returns a machine-readable verdict a
+publishing pipeline can gate on:
+
+- **sector_sum** — s1+s2+s3 must equal the lap time within 3 ms
+  (the same tolerance FastF1 uses internally, recomputed natively).
+- **lap_count** — winner's classified lap count vs the lap table.
+- **gap_monotonic** — classified numeric gaps must increase with position;
+  this is the check that catches the classic lapped-car corruption
+  (``P8 +36.049`` printed above ``P7 +1:19.915``).
+- **lapped_convention** — every ``+N LAP`` row completed fewer laps.
+- **leader_vs_overtakes** — every on-track pass for P1 (independent
+  ``/overtakes`` endpoint) must appear in the position-stream lead changes.
+  The two are *not* equal by design: leads gained through pit cycles are
+  lead changes but not overtakes.
+- **stints_vs_pits** — stint splits explained by pit stops (red-flag tyre
+  changes legitimately add stints without a pit stop; reported, not failed).
+"""
+
+from .sources import openf1
+
+
+def _check(name, ok, detail):
+    return {"name": name, "status": "ok" if ok else "mismatch",
+            "detail": detail}
+
+
+def crosscheck(race) -> dict:
+    checks = []
+
+    # -- lap_count ----------------------------------------------------------
+    winner = next((r for r in race.result if r.get("position") == 1), {})
+    table_max = race.total_laps
+    ok = winner.get("number_of_laps") == table_max
+    checks.append(_check("lap_count", ok,
+                         f"winner classified {winner.get('number_of_laps')} laps,"
+                         f" lap table max {table_max}"))
+
+    # -- sector_sum (FastF1's 3 ms tolerance, recomputed natively) ----------
+    bad = total = 0
+    for l in race.laps:
+        s = (l.get("duration_sector_1"), l.get("duration_sector_2"),
+             l.get("duration_sector_3"), l.get("lap_duration"))
+        if all(x is not None for x in s):
+            total += 1
+            if abs(s[0] + s[1] + s[2] - s[3]) > 0.003:
+                bad += 1
+    checks.append(_check("sector_sum", bad / max(total, 1) < 0.02,
+                         f"{bad}/{total} laps off by >3ms"))
+
+    # -- gap_monotonic (the lapped-car trap, as an invariant) ---------------
+    prev, breaks = None, []
+    for r in race.results():
+        g = r["gap"]
+        if g.startswith("+") and "LAP" not in g:
+            sec = (lambda s: sum(float(x) * m for x, m in
+                                 zip(reversed(s.rstrip("s").lstrip("+").split(":")),
+                                     (1, 60))))(g)
+            if prev is not None and sec < prev:
+                breaks.append(r["abbr"])
+            prev = sec
+    checks.append(_check("gap_monotonic", not breaks,
+                         f"out-of-order gaps: {breaks or 'none'}"))
+
+    # -- lapped_convention --------------------------------------------------
+    wrong = [r["abbr"] for r in race.results()
+             if "LAP" in r["gap"] and (r.get("laps") or 0) >= table_max]
+    checks.append(_check("lapped_convention", not wrong,
+                         f"'+N LAP' rows with full distance: {wrong or 'none'}"))
+
+    # -- leader_vs_overtakes (independent endpoint) -------------------------
+    runs = [r["abbr"] for r in race.leader_runs()]
+    ot = sorted(openf1.get("overtakes", session_key=race.session_key,
+                           position=1), key=lambda o: o["date"])
+    seq, prev_n = [], None
+    for o in ot:
+        n = o["overtaking_driver_number"]
+        if n != prev_n:
+            seq.append(race.abbr(n))
+            prev_n = n
+    # on-track P1 passes must be a subsequence of all lead changes —
+    # pit-cycle lead changes legitimately have no matching overtake
+    changes = [b for a, b in zip([None] + runs, runs) if a != b][1:]
+    passes = [b for a, b in zip([None] + seq, seq) if a != b]
+    it = iter(changes)
+    ok = all(any(p == c for c in it) for p in passes)
+    checks.append(_check(
+        "leader_vs_overtakes", ok,
+        f"on-track P1 passes {passes} ⊆ lead changes {changes}"
+        + ("" if ok else " — FAILED")))
+
+    # -- stints_vs_pits (informational) -------------------------------------
+    pit_per = {}
+    for p in race.pits:
+        pit_per[p["driver_number"]] = pit_per.get(p["driver_number"], 0) + 1
+    unexplained = []
+    for num, sts in ((n, [s for s in race.stints_raw
+                          if s["driver_number"] == n])
+                     for n in race.drivers):
+        extra = (len(sts) - 1) - pit_per.get(num, 0)
+        if extra > 1:  # >1 non-pit stint split is suspicious even with a red flag
+            unexplained.append(race.abbr(num))
+    checks.append(_check("stints_vs_pits", not unexplained,
+                         f"suspicious stint splits: {unexplained or 'none'}"))
+
+    mismatches = [c["name"] for c in checks if c["status"] != "ok"]
+    return {"checks": checks, "mismatches": mismatches,
+            "publishable": not mismatches}

f1verse/feeds.py

@@ -0,0 +1,72 @@
+"""Harvest live-timing feeds that FastF1 knows about but never parses.
+
+The official archive names 21 topics; FastF1 parses ~13. Three of the
+dropped feeds are genuinely valuable:
+
+- ``ChampionshipPrediction`` — per-lap "if the race ended now" projection.
+- ``TeamRadio`` — timestamped team-radio clip paths (URLs only, no media).
+- ``TimingStats`` — personal bests and speed-trap figures.
+
+Every function accepts either a loaded FastF1 ``Session`` or an
+``f1verse.Race`` — anything exposing ``.api_path``.
+"""
+import copy
+
+from ._json import jsonsafe
+from .sources.livetiming import BASE, deepmerge, fetch_stream
+
+
+def _path(session) -> str:
+    p = getattr(session, "api_path", None)
+    if not p:
+        raise TypeError("expected a FastF1 Session or f1verse.Race")
+    return p
+
+
+def championship_prediction(session) -> dict:
+    """Live championship projection through the race.
+
+    Returns ``{"series", "final", "leader_changes"}`` where
+    ``leader_changes`` are the moments the *projected champion* changed —
+    the moments no broadcast graphic shows.
+    """
+    series, state = [], {}
+    for t, patch in fetch_stream(_path(session), "ChampionshipPrediction.jsonStream"):
+        state = deepmerge(state, patch)
+        if state.get("Drivers"):
+            series.append({"t": t, "state": copy.deepcopy(state)})
+    changes, prev = [], None
+    for snap in series:
+        drivers = snap["state"].get("Drivers", {})
+        leader = min((d for d in drivers.values() if d.get("PredictedPosition")),
+                     key=lambda d: d["PredictedPosition"], default=None)
+        num = leader and leader.get("RacingNumber")
+        if num and num != prev:
+            if prev is not None:
+                changes.append({"t": snap["t"], "to": num, "from": prev})
+            prev = num
+    return jsonsafe({"series": series,
+                     "final": series[-1]["state"] if series else {},
+                     "leader_changes": changes})
+
+
+def team_radio(session) -> list:
+    """Timestamped team-radio clips: URLs only, nothing downloaded."""
+    clips, path = [], _path(session)
+    for t, patch in fetch_stream(path, "TeamRadio.jsonStream"):
+        caps = patch.get("Captures")
+        items = caps.values() if isinstance(caps, dict) else (caps or [])
+        for c in items:
+            if isinstance(c, dict) and c.get("Path"):
+                clips.append({"t": t, "utc": c.get("Utc"),
+                              "driver_number": c.get("RacingNumber"),
+                              "url": BASE + path + c["Path"]})
+    return jsonsafe(clips)
+
+
+def timing_stats(session) -> dict:
+    """Final personal bests / best sectors / speed-trap figures per driver."""
+    state = {}
+    for _, patch in fetch_stream(_path(session), "TimingStats.jsonStream"):
+        state = deepmerge(state, patch)
+    return jsonsafe(state.get("Lines", {}))

f1verse/gaps.py

@@ -0,0 +1,43 @@
+"""Broadcast-convention gap formatting.
+
+FastF1's ``results['Time']`` is **not** a gap for lapped cars — the raw value
+can be *smaller* than a car that finished ahead on the lead lap::
+
+    P7  LAW  +1:19.915   Status=Finished
+    P8  HUL    +36.049   Status=Lapped    <- looks ahead of P7!
+
+No error, no warning — naive tables are silently wrong. ``format_gap``
+applies the convention every broadcast uses instead.
+"""
+import math
+
+
+def _seconds(td):
+    if td is None:
+        return None
+    try:
+        s = td.total_seconds()
+    except AttributeError:
+        s = float(td)
+    return None if math.isnan(s) else s
+
+
+def format_seconds(total: float) -> str:
+    if total >= 60:
+        return f"+{int(total // 60)}:{total % 60:06.3f}"
+    return f"+{total:.3f}s"
+
+
+def format_gap(status, time_delta, position=None, laps_down=None) -> str:
+    """Human gap string for one classified result row (broadcast convention)."""
+    if position == 1:
+        return "WINNER"
+    if status == "Lapped":
+        n = int(laps_down) if laps_down else 1
+        return f"+{n} LAP" if n == 1 else f"+{n} LAPS"
+    if status == "Disqualified":
+        return "DSQ"
+    if status != "Finished":
+        return "DNF"
+    s = _seconds(time_delta)
+    return "" if s is None else format_seconds(s)

f1verse/http.py

@@ -0,0 +1,49 @@
+"""Tiny cached HTTP layer — standard library only, zero dependencies.
+
+One on-disk cache, BOM-safe JSON, polite pacing, gzip support.
+Completed-session responses are immutable, so caching is aggressive.
+"""
+import gzip
+import hashlib
+import json
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+_UA = "f1verse (+https://github.com/jinsim/f1verse)"
+_cache_dir = Path.home() / ".cache" / "f1verse"
+_last_request = 0.0
+
+
+def enable_cache(path) -> None:
+    """Override the cache directory (default ``~/.cache/f1verse``)."""
+    global _cache_dir
+    _cache_dir = Path(path)
+
+
+def get_text(url: str, params: dict | None = None) -> str:
+    global _last_request
+    if params:
+        url = url + "?" + urllib.parse.urlencode(params)
+    f = _cache_dir / hashlib.sha256(url.encode()).hexdigest()[:24]
+    if f.exists():
+        return f.read_text()
+    wait = 0.5 - (time.monotonic() - _last_request)
+    if wait > 0:
+        time.sleep(wait)
+    req = urllib.request.Request(
+        url, headers={"User-Agent": _UA, "Accept-Encoding": "gzip"})
+    with urllib.request.urlopen(req, timeout=60) as r:
+        raw = r.read()
+        if r.headers.get("Content-Encoding") == "gzip":
+            raw = gzip.decompress(raw)
+    _last_request = time.monotonic()
+    text = raw.decode("utf-8-sig")  # livetiming serves BOM-prefixed JSON
+    _cache_dir.mkdir(parents=True, exist_ok=True)
+    f.write_text(text)
+    return text
+
+
+def get_json(url: str, params: dict | None = None):
+    return json.loads(get_text(url, params))

f1verse/integrity.py

@@ -0,0 +1,32 @@
+"""Machine-readable data-quality report.
+
+FastF1 logs warnings like ``Driver 41: Lap timing integrity check failed``
+as *text* — an automated publishing pipeline cannot act on text. This module
+re-surfaces the same information as structured data so a pipeline can hold
+publication, exclude laps, or annotate output.
+"""
+import pandas as pd
+
+from ._json import jsonsafe
+
+
+def integrity_report(session) -> dict:
+    laps = session.laps
+    rep = {"drivers": {}, "total_laps": int(len(laps)),
+           "inaccurate_laps": 0, "deleted_laps": 0, "generated_laps": 0}
+    for drv in session.results["Abbreviation"]:
+        d = laps.pick_drivers(drv)
+        bad = d[~d["IsAccurate"].astype(bool)]
+        deleted = d[d["Deleted"] == True] if "Deleted" in d else d.iloc[0:0]  # noqa: E712
+        gen = d[d["FastF1Generated"] == True] if "FastF1Generated" in d else d.iloc[0:0]  # noqa: E712
+        rep["drivers"][drv] = {
+            "laps": int(len(d)),
+            "inaccurate": [int(x) for x in bad["LapNumber"].dropna()],
+            "deleted": [int(x) for x in deleted["LapNumber"].dropna()],
+            "generated": [int(x) for x in gen["LapNumber"].dropna()],
+        }
+        rep["inaccurate_laps"] += len(bad)
+        rep["deleted_laps"] += len(deleted)
+        rep["generated_laps"] += len(gen)
+    rep["publishable"] = rep["inaccurate_laps"] / max(rep["total_laps"], 1) < 0.35
+    return jsonsafe(rep)

f1verse/race.py

@@ -0,0 +1,231 @@
+"""Native multi-source race loader — no FastF1 required.
+
+``f1verse.load(year, round)`` builds a :class:`Race` from public REST data
+(OpenF1) plus the official live-timing archive for the feeds nobody else
+parses. FastF1 remains available as an optional adapter (``f1verse.analyze``)
+for telemetry, qualifying segments, and pre-2023 seasons.
+"""
+from datetime import datetime
+from statistics import median
+
+from . import feeds
+from ._json import jsonsafe
+from .gaps import format_seconds
+from .sources import livetiming, openf1
+
+
+def _iso(s: str) -> datetime:
+    return datetime.fromisoformat(s)
+
+
+class Race:
+    def __init__(self, year: int, rnd: int):
+        self.year, self.round = year, rnd
+        s = openf1.resolve_race(year, rnd)
+        self.session_key = s["session_key"]
+        self.meeting = s["meeting"]
+        self.info = s
+        self._api_path = None
+
+        key = {"session_key": self.session_key}
+        self.drivers = {d["driver_number"]: d for d in openf1.get("drivers", **key)}
+        self.laps = sorted(openf1.get("laps", **key),
+                           key=lambda l: (l["driver_number"], l["lap_number"]))
+        self.result = openf1.get("session_result", **key)
+        self.race_control = openf1.get("race_control", **key)
+        self.stints_raw = openf1.get("stints", **key)
+        self.pits = openf1.get("pit", **key)
+        self._p1 = sorted(openf1.get("position", position=1, **key),
+                          key=lambda p: p["date"])
+        self.total_laps = max((l["lap_number"] for l in self.laps), default=0)
+
+    # -- identity helpers ---------------------------------------------------
+    def abbr(self, num) -> str:
+        d = self.drivers.get(num, {})
+        return d.get("name_acronym") or str(num)
+
+    @property
+    def api_path(self) -> str:
+        """Live-timing archive path (resolved lazily, cached)."""
+        if self._api_path is None:
+            self._api_path = livetiming.api_path(
+                self.year, self.meeting["meeting_name"])
+        return self._api_path
+
+    # -- story --------------------------------------------------------------
+    def leader_runs(self) -> list:
+        """Lead spells on the lap axis, from the P1 position stream."""
+        events, prev = [], None
+        for p in self._p1:
+            if p["driver_number"] != prev:
+                events.append((_iso(p["date"]), p["driver_number"]))
+                prev = p["driver_number"]
+        by_drv = {}
+        for l in self.laps:
+            if l.get("date_start"):
+                by_drv.setdefault(l["driver_number"], []).append(
+                    (_iso(l["date_start"]), l["lap_number"]))
+        runs = []
+        for t, num in events:
+            lap = 1
+            for ts, ln in by_drv.get(num, []):
+                if ts <= t:
+                    lap = ln
+                else:
+                    break
+            if runs and runs[-1]["abbr"] == self.abbr(num):
+                continue
+            if runs:
+                runs[-1]["to"] = max(lap - 1, runs[-1]["from"])
+            runs.append({"abbr": self.abbr(num), "from": lap, "to": lap})
+        if runs:
+            runs[-1]["to"] = self.total_laps
+        return runs
+
+    def laps_led(self) -> dict:
+        led = {}
+        for r in self.leader_runs():
+            led[r["abbr"]] = led.get(r["abbr"], 0) + r["to"] - r["from"] + 1
+        return dict(sorted(led.items(), key=lambda kv: -kv[1]))
+
+    def interruptions(self) -> dict:
+        """SC/VSC lap bands and red-flag laps from race control."""
+        bands, red, start = [], [], None
+        for m in sorted(self.race_control, key=lambda m: m["date"]):
+            msg, lap = (m.get("message") or "").upper(), m.get("lap_number")
+            if "RED FLAG" in msg and lap:
+                red.append(int(lap))
+            if ("SAFETY CAR DEPLOYED" in msg or "VSC DEPLOYED" in msg
+                    or "VIRTUAL SAFETY CAR DEPLOYED" in msg):
+                start = int(lap or 1)
+            if start is not None and ("ENDING" in msg or "IN THIS LAP" in msg
+                                      or "CLEAR" in msg and "TRACK" in msg):
+                bands.append([start, int(lap or start)])
+                start = None
+        if start is not None:
+            bands.append([start, self.total_laps])
+        return {"sc_vsc_bands": bands, "red_flag_laps": sorted(set(red))}
+
+    def stints(self) -> dict:
+        out = {}
+        for s in sorted(self.stints_raw,
+                        key=lambda s: (s["driver_number"], s["stint_number"])):
+            out.setdefault(self.abbr(s["driver_number"]), []).append({
+                "compound": s.get("compound"),
+                "from": s.get("lap_start"), "to": s.get("lap_end"),
+                "laps": (s.get("lap_end") or 0) - (s.get("lap_start") or 0) + 1})
+        return out
+
+    def race_pace(self, threshold: float = 1.07) -> dict:
+        """Median representative pace. Domain rules by default:
+        pit-out laps, pit-in laps, SC/VSC laps and quicklap threshold."""
+        bad = {l for a, b in self.interruptions()["sc_vsc_bands"]
+               for l in range(a, b + 1)}
+        pit_in = {(p["driver_number"], p["lap_number"]) for p in self.pits}
+        per = {}
+        for l in self.laps:
+            d = l.get("lap_duration")
+            if (not d or l.get("is_pit_out_lap")
+                    or l["lap_number"] in bad
+                    or (l["driver_number"], l["lap_number"]) in pit_in):
+                continue
+            per.setdefault(l["driver_number"], []).append(d)
+        out = {}
+        for num, ds in per.items():
+            m = median(ds)
+            quick = [x for x in ds if x <= m * threshold]
+            if len(quick) >= 3:
+                out[self.abbr(num)] = round(median(quick), 3)
+        return dict(sorted(out.items(), key=lambda kv: kv[1]))
+
+    def results(self) -> list:
+        """Classified results; OpenF1 already applies '+1 LAP' convention.
+        FIA gives DNFs no position — ordered by laps completed after that."""
+        rows = sorted(self.result,
+                      key=lambda r: (r.get("position") is None,
+                                     r.get("position") or 0,
+                                     -(r.get("number_of_laps") or 0)))
+        out = []
+        for r in rows:
+            g = r.get("gap_to_leader")
+            if r.get("dsq"):
+                gap = "DSQ"
+            elif r.get("dnf") or r.get("dns"):
+                gap = "DNS" if r.get("dns") else "DNF"
+            elif r.get("position") == 1:
+                gap = "WINNER"
+            elif isinstance(g, str):
+                gap = g if g.startswith("+") else f"+{g}"
+            elif g is None:
+                gap = ""
+            else:
+                gap = format_seconds(float(g))
+            d = self.drivers.get(r["driver_number"], {})
+            out.append({"position": r.get("position"),
+                        "abbr": self.abbr(r["driver_number"]),
+                        "name": d.get("full_name"),
+                        "team": d.get("team_name"),
+                        "gap": gap, "points": r.get("points") or 0.0,
+                        "laps": r.get("number_of_laps")})
+        return out
+
+    def timeline(self) -> list:
+        ev = []
+        for r in self.result:
+            if r.get("dnf"):
+                ab = self.abbr(r["driver_number"])
+                last = max((l["lap_number"] for l in self.laps
+                            if l["driver_number"] == r["driver_number"]),
+                           default=0)
+                ev.append({"lap": last, "kind": "out", "abbr": ab,
+                           "title": f"{ab} out"})
+        inter = self.interruptions()
+        ev += [{"lap": l, "kind": "red", "title": "Red flag"}
+               for l in inter["red_flag_laps"]]
+        ev += [{"lap": a, "kind": "sc", "title": f"SC/VSC (laps {a}-{b})"}
+               for a, b in inter["sc_vsc_bands"]]
+        runs = self.leader_runs()
+        ev += [{"lap": cur["from"], "kind": "lead", "abbr": cur["abbr"],
+                "over": prev["abbr"],
+                "title": f"{cur['abbr']} leads (from {prev['abbr']})"}
+               for prev, cur in zip(runs, runs[1:])]
+        return sorted(ev, key=lambda e: (e["lap"], e["kind"]))
+
+    def crosscheck(self) -> dict:
+        """Independent-source validation — gate publication on this."""
+        from .crosscheck import crosscheck
+        return crosscheck(self)
+
+    # -- dropped-feed harvest ------------------------------------------------
+    def championship_prediction(self) -> dict:
+        return feeds.championship_prediction(self)
+
+    def team_radio(self) -> list:
+        return feeds.team_radio(self)
+
+    def timing_stats(self) -> dict:
+        return feeds.timing_stats(self)
+
+    def story(self) -> dict:
+        """One call, whole story — JSON-safe, no FastF1 involved."""
+        m = self.meeting
+        return jsonsafe({
+            "event": {"name": m["meeting_name"],
+                      "location": self.info.get("location"),
+                      "round": self.round, "year": self.year,
+                      "date": (self.info.get("date_start") or "")[:10],
+                      "total_laps": self.total_laps},
+            "results": self.results(),
+            "leader_runs": self.leader_runs(),
+            "laps_led": self.laps_led(),
+            "timeline": self.timeline(),
+            "stints": self.stints(),
+            "race_pace": self.race_pace(),
+            "interruptions": self.interruptions(),
+            "sources": ["openf1", "livetiming-index"],
+        })
+
+
+def load(year: int, rnd: int) -> Race:
+    """``f1verse.load(2026, 12)`` → :class:`Race` (2023+ seasons)."""
+    return Race(year, rnd)

f1verse/sources/__init__.py

@@ -0,0 +1 @@
+from . import livetiming, openf1  # noqa: F401

f1verse/sources/livetiming.py

@@ -0,0 +1,48 @@
+"""Direct client for the official live-timing static archive.
+
+This is the same public host FastF1 reads. f1verse only needs three files
+FastF1 never parses; session paths are discovered via the season Index.json,
+so no third-party library is involved. Nothing is redistributed — clips stay
+as URLs.
+"""
+import json
+import re
+
+from .. import http
+
+BASE = "https://livetiming.formula1.com"
+_LINE = re.compile(r"^(\d{2}):(\d{2}):(\d{2}\.\d{3})(.*)$")
+
+
+def api_path(year: int, meeting_name: str, session_name: str = "Race") -> str:
+    idx = http.get_json(f"{BASE}/static/{year}/Index.json")
+    for m in idx.get("Meetings", []):
+        if meeting_name.lower() in m.get("Name", "").lower():
+            for s in m.get("Sessions", []):
+                if s.get("Name") == session_name and s.get("Path"):
+                    return "/static/" + s["Path"]
+    raise LookupError(f"{year} {meeting_name!r} {session_name!r} not in Index")
+
+
+def fetch_stream(path: str, filename: str) -> list:
+    """A ``.jsonStream`` file → ``[(t_seconds, payload_dict), ...]``."""
+    out = []
+    for line in http.get_text(BASE + path + filename).splitlines():
+        m = _LINE.match(line.strip())
+        if not m:
+            continue
+        t = int(m.group(1)) * 3600 + int(m.group(2)) * 60 + float(m.group(3))
+        try:
+            out.append((t, json.loads(m.group(4))))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def deepmerge(base, patch):
+    """Streams send one snapshot, then partial patches."""
+    if not isinstance(base, dict) or not isinstance(patch, dict):
+        return patch
+    for k, v in patch.items():
+        base[k] = deepmerge(base.get(k), v)
+    return base

f1verse/sources/openf1.py

@@ -0,0 +1,25 @@
+"""Thin OpenF1 REST client (https://openf1.org) — coverage from 2023 season."""
+from .. import http
+
+BASE = "https://api.openf1.org/v1/"
+
+
+def get(endpoint: str, **params) -> list:
+    return http.get_json(BASE + endpoint, params)
+
+
+def resolve_race(year: int, rnd: int) -> dict:
+    """(year, round) → race session dict. Rounds count real GP meetings only."""
+    meetings = sorted(get("meetings", year=year), key=lambda m: m["date_start"])
+    gps = [m for m in meetings
+           if "test" not in m["meeting_name"].lower()
+           and not m.get("is_cancelled")]
+    if not 1 <= rnd <= len(gps):
+        raise ValueError(f"round {rnd} out of range (1..{len(gps)})")
+    m = gps[rnd - 1]
+    race = get("sessions", meeting_key=m["meeting_key"], session_name="Race")
+    if not race:
+        raise LookupError(f"no Race session for {m['meeting_name']}")
+    s = race[0]
+    s["meeting"] = m
+    return s

f1verse/story.py

@@ -0,0 +1,163 @@
+"""Turn a loaded FastF1 session into a race story.
+
+FastF1 is excellent at *fetching and tidying* data. It deliberately stops
+short of *telling you what happened*: there is no API for lead changes,
+laps led, or an event timeline — every analyst reinvents them in a notebook,
+and each reinvents them slightly differently. ``analyze`` computes them once,
+with F1 domain rules applied by default, and returns plain JSON-safe data.
+"""
+import numpy as np
+import pandas as pd
+
+from ._json import jsonsafe
+from .gaps import format_gap
+
+
+def leader_runs(session) -> list:
+    """Contiguous stretches of race leadership: [{abbr, from, to}]."""
+    laps = session.laps
+    lead = (laps[laps["Position"] == 1][["LapNumber", "Driver"]]
+            .dropna().sort_values("LapNumber"))
+    runs, cur, start, prev = [], None, None, None
+    for _, r in lead.iterrows():
+        if r["Driver"] != cur:
+            if cur is not None:
+                runs.append({"abbr": cur, "from": int(start), "to": int(prev)})
+            cur, start = r["Driver"], r["LapNumber"]
+        prev = r["LapNumber"]
+    if cur is not None:
+        runs.append({"abbr": cur, "from": int(start), "to": int(prev)})
+    return runs
+
+
+def laps_led(session) -> dict:
+    """Laps led per driver, most first. The stat that catches false headlines:
+    the driver who led the most laps is not always the winner."""
+    led = {}
+    for r in leader_runs(session):
+        led[r["abbr"]] = led.get(r["abbr"], 0) + r["to"] - r["from"] + 1
+    return dict(sorted(led.items(), key=lambda kv: -kv[1]))
+
+
+def interruption_bands(session) -> dict:
+    """SC/VSC bands and red-flag laps, on the leader's lap axis."""
+    laps = session.laps
+    lead = laps[laps["Position"] == 1].dropna(subset=["LapNumber"])
+    bad = sorted(lead[lead["TrackStatus"].astype(str)
+                 .str.contains(r"[467]", na=False)]["LapNumber"].astype(int))
+    bands, s = [], None
+    for i, n in enumerate(bad):
+        if s is None:
+            s = p = n
+        elif n == p + 1:
+            p = n
+        else:
+            bands.append([s, p]); s = p = n
+        if i == len(bad) - 1:
+            bands.append([s, p])
+    red = []
+    rcm = getattr(session, "race_control_messages", None)
+    if rcm is not None and len(rcm):
+        red = [int(x) for x in
+               rcm[rcm["Message"].str.contains("RED FLAG", na=False)]["Lap"]
+               .dropna().unique()]
+    return {"sc_vsc_bands": bands, "red_flag_laps": red}
+
+
+def stints(session) -> dict:
+    """Per-driver stint list with lap ranges — red-flag-truncated stints kept
+    as-is so the caller can see the restart split."""
+    st = (session.laps[["Driver", "Stint", "Compound", "LapNumber"]]
+          .dropna(subset=["Stint"])
+          .groupby(["Driver", "Stint", "Compound"])["LapNumber"]
+          .agg(["min", "max", "count"]).reset_index())
+    out = {}
+    for _, r in st.sort_values(["Driver", "min"]).iterrows():
+        out.setdefault(r["Driver"], []).append({
+            "compound": r["Compound"], "from": int(r["min"]),
+            "to": int(r["max"]), "laps": int(r["count"])})
+    return out
+
+
+def race_pace(session, threshold: float = 1.07) -> dict:
+    """Median representative lap per driver.
+
+    Domain rules applied by default (this is the point):
+    in/out laps excluded, SC/VSC laps excluded, quicklap threshold applied,
+    AND FastF1's own 4-way accuracy check (``pick_accurate``) applied.
+    """
+    bands = interruption_bands(session)["sc_vsc_bands"]
+    bad = {l for a, b in bands for l in range(a, b + 1)}
+    q = session.laps.pick_accurate().pick_quicklaps(threshold)
+    q = q[~q["LapNumber"].isin(bad)]
+    med = {}
+    for drv in session.results["Abbreviation"]:
+        d = q.pick_drivers(drv)["LapTime"].dt.total_seconds().dropna()
+        if len(d) >= 3:
+            med[drv] = round(float(np.median(d)), 3)
+    return dict(sorted(med.items(), key=lambda kv: kv[1]))
+
+
+def results(session) -> list:
+    """Classified results with broadcast-convention gap strings baked in."""
+    total = int(session.laps["LapNumber"].max())
+    out = []
+    for _, r in session.results.sort_values("Position").iterrows():
+        drv_laps = session.laps.pick_drivers(r["Abbreviation"])
+        last = int(drv_laps["LapNumber"].max()) if len(drv_laps) else 0
+        down = total - last if r["Status"] == "Lapped" else None
+        out.append({
+            "position": int(r["Position"]) if pd.notna(r["Position"]) else None,
+            "abbr": r["Abbreviation"], "name": r["FullName"],
+            "team": r["TeamName"],
+            "grid": int(r["GridPosition"]) if pd.notna(r["GridPosition"]) else None,
+            "status": r["Status"],
+            "gap": format_gap(r["Status"], r["Time"],
+                              int(r["Position"]) if pd.notna(r["Position"]) else None,
+                              laps_down=down),
+            "points": float(r["Points"]) if pd.notna(r["Points"]) else 0.0,
+            "last_lap": last,
+        })
+    return out
+
+
+def timeline(session) -> list:
+    """Chronological event list: retirements, red flags, SC/VSC, lead changes."""
+    ev = []
+    res = session.results
+    for _, r in res[~res["Status"].isin(["Finished", "Lapped"])].iterrows():
+        d = session.laps.pick_drivers(r["Abbreviation"])
+        ev.append({"lap": int(d["LapNumber"].max()) if len(d) else 0,
+                   "kind": "out", "abbr": r["Abbreviation"],
+                   "title": f"{r['Abbreviation']} out"})
+    bands = interruption_bands(session)
+    for lap in bands["red_flag_laps"]:
+        ev.append({"lap": lap, "kind": "red", "title": "Red flag"})
+    for a, b in bands["sc_vsc_bands"]:
+        ev.append({"lap": a, "kind": "sc",
+                   "title": f"SC/VSC (laps {a}-{b})"})
+    runs = leader_runs(session)
+    for prev, cur in zip(runs, runs[1:]):
+        ev.append({"lap": cur["from"], "kind": "lead",
+                   "abbr": cur["abbr"], "over": prev["abbr"],
+                   "title": f"{cur['abbr']} leads (from {prev['abbr']})"})
+    return sorted(ev, key=lambda e: (e["lap"], e["kind"]))
+
+
+def analyze(session) -> dict:
+    """One call, whole story. Returns a plain JSON-safe dict."""
+    e = session.event
+    story = {
+        "event": {"name": str(e["EventName"]), "location": str(e["Location"]),
+                  "round": int(e["RoundNumber"]),
+                  "date": str(e["EventDate"].date()),
+                  "total_laps": int(session.laps["LapNumber"].max())},
+        "results": results(session),
+        "leader_runs": leader_runs(session),
+        "laps_led": laps_led(session),
+        "timeline": timeline(session),
+        "stints": stints(session),
+        "race_pace": race_pace(session),
+        "interruptions": interruption_bands(session),
+    }
+    return jsonsafe(story)

f1verse-0.3.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: f1verse
+Version: 0.3.0
+Summary: The story layer for Formula 1 data — zero-dependency race narratives: lead changes, stints, race pace, live championship projection, team radio index. Optional FastF1 adapter.
+Author: f1verse contributors
+License: MIT
+Project-URL: Homepage, https://github.com/f1verse/f1verse
+Keywords: f1,formula1,formula-1,fastf1,openf1,motorsport,racing,telemetry,live-timing,race-analysis,data-analysis,grand-prix
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: fastf1
+Requires-Dist: fastf1>=3.4; extra == "fastf1"
+Dynamic: license-file
+
+# f1verse
+
+**The story layer for Formula 1 data.** Data libraries fetch and tidy —
+f1verse tells you *what happened*: lead changes, laps led, event timelines,
+stint strategy, true race pace, and the live championship projection that
+broadcasts never show.
+
+**Zero dependencies.** Standard library only, seasons 2023+.
+
+```bash
+pip install f1verse
+```
+
+```python
+import f1verse
+
+race = f1verse.load(2026, 12)        # year, round — no other library needed
+
+race.laps_led()      # {'ANT': 32, 'NOR': 31, 'HAM': 9}
+race.leader_runs()   # [{'abbr': 'NOR', 'from': 1, 'to': 4}, ...]
+race.results()[7]    # {'abbr': 'HUL', 'gap': '+1 LAP', ...}
+race.race_pace()     # median pace — pit/SC/VSC laps excluded by default
+race.story()         # one call, whole story, plain JSON
+
+race.championship_prediction()   # per-lap "if it ended now" title projection
+race.team_radio()                # timestamped clip URLs (nothing downloaded)
+```
+
+Using FastF1 already? Keep your workflow — the adapter takes a loaded
+session (`pip install f1verse[fastf1]`, adds telemetry & pre-2023 seasons):
+
+```python
+story = f1verse.analyze(fastf1_session)
+```
+
+## Why this exists
+
+Everyone who builds on FastF1 rediscovers the same traps, and each fixes
+them slightly differently:
+
+- **`results['Time']` is not a gap for lapped cars.** The raw value can be
+  *smaller* than a car that finished ahead (`P7 +1:19.915` vs `P8 +36.049`).
+  No error, no warning — naive tables are silently wrong.
+  → `f1verse.format_gap` applies the broadcast convention (`+1 LAP`).
+- **There is no API for "who led the race".** Lead changes, laps led,
+  overtake-for-the-lead moments — every notebook reinvents them.
+  → `leader_runs`, `laps_led`, `timeline`.
+- **Race pace needs domain rules**, not just a quicklap threshold: in/out
+  laps, SC/VSC laps, and laps failing FastF1's own 4-way accuracy check
+  must go. → `race_pace` applies all of it by default.
+- **numpy scalars break `json.dumps`.** Every f1verse output is plain
+  JSON-safe Python. → pipe results straight into web or video pipelines.
+- **Data-quality warnings are only logged as text.**
+  → `integrity_report` returns them as structured data your pipeline can
+  act on (hold publication, exclude laps, annotate).
+
+## The feeds FastF1 throws away
+
+The official live-timing archive contains more than FastF1 parses.
+f1verse harvests three of the dropped feeds (through FastF1's own cache,
+same rate-limit etiquette):
+
+```python
+f1verse.championship_prediction(session)
+# per-lap "if the race ended now" projection of both championships,
+# including the moments the projected champion changed
+
+f1verse.team_radio(session)
+# timestamped team-radio clips: [{'t', 'utc', 'driver_number', 'url'}]
+# URLs only — nothing is downloaded or redistributed
+
+f1verse.timing_stats(session)
+# personal bests, best sectors, speed-trap figures
+```
+
+## Design rules
+
+1. **Zero required dependencies.** The native loader speaks to public REST
+   endpoints (OpenF1) and the official live-timing archive directly, with
+   its own on-disk cache and polite pacing.
+2. **FastF1 is respected, not replaced** — optional adapter for telemetry,
+   qualifying segments and pre-2023 history.
+3. **Everything returned is plain JSON-safe Python.**
+4. **F1 domain rules are defaults, not options.**
+5. **Cross-checked where possible** — e.g. lapped-car gaps are computed by
+   convention *and* confirmed against a second source.
+6. **Code only.** No timing data, media, or images are bundled or
+   redistributed; data is fetched by the end user.
+
+## Roadmap
+
+- Full cross-validation layer (publish only when two sources agree)
+- Overtake timeline ([OpenF1](https://openf1.org) `/overtakes`) & undercut/overcut detection
+- Circuit & driver metadata joins ([Jolpica](https://github.com/jolpica/jolpica-f1), [f1db](https://github.com/f1db/f1db))
+- Korean localization package (`f1verse-ko`)
+- Chart & vertical-video templates consuming f1verse JSON
+
+---
+
+*Unofficial fan project. Not affiliated with, endorsed by, or associated
+with Formula 1, FIA, FOM, or any F1 team. F1, FORMULA 1 and related marks
+are trademarks of Formula One Licensing BV. This library contains code
+only — no timing data, media, or images are included or redistributed;
+data is fetched by the end user from publicly accessible endpoints,
+subject to the respective providers' terms. Built on
+[FastF1](https://github.com/theOehrly/Fast-F1) (MIT).*

f1verse-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+f1verse/__init__.py,sha256=kd0VGw4Db9a967PtM3PJ0QN2XJ0Z3tqrxHAE38qtrzI,1542
+f1verse/_json.py,sha256=G4heUcehAWfyDwPNyT1fqwClSaQ5rI04ZmyBaFHd45k,1819
+f1verse/crosscheck.py,sha256=0PkvS3z5JeyfJ4OzDcAOpljQ0CEL40cUzzYMewg15G4,5072
+f1verse/feeds.py,sha256=EJur3u25VmCzp938XRYrgWHkWzzIsj5PeIQGKelyxqo,2871
+f1verse/gaps.py,sha256=cqzyYUwLf7N6AQNMJROQrn9aBEdJQ34kiRVczKV1xl8,1287
+f1verse/http.py,sha256=4Mk7_LAvh3bXnKKIo4PFmcp5BIBq6QtIA807HwR_c94,1546
+f1verse/integrity.py,sha256=GQWybJKYij8-AJ4UqbVtH73h6i1MTQhtFFjGpR8wUks,1414
+f1verse/race.py,sha256=7wPDeAkYcyjZykZZ0ApTpRNGtML9XKkau8LHUR_3RGE,9723
+f1verse/story.py,sha256=HbS8BOwbB8xAtG5BFLu1VgJQeXy3wIDSDIaVEyCHhHs,6783
+f1verse/sources/__init__.py,sha256=jw6DuvvOwGCaX_OtjJOp02A5CY6GD7bAKR_tBwqPSNE,47
+f1verse/sources/livetiming.py,sha256=NP1OLvgrxfBd8om9vMBiX7oV_3hBV2fqBeoSV4S_F1o,1704
+f1verse/sources/openf1.py,sha256=Jo6_cD4Asct79A886vxWJJfWAfP6XP496ddDK8WUvJw,912
+f1verse-0.3.0.dist-info/licenses/LICENSE,sha256=fCJ3HbN7I0wp80aPf0QxILiIyO5hJAFiXbGlM6oDw4U,1077
+f1verse-0.3.0.dist-info/METADATA,sha256=vmTVRbkTrMizH2_J0r3k9r_5RAaJecQPtp8RUPDnEUs,5329
+f1verse-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+f1verse-0.3.0.dist-info/top_level.txt,sha256=DnPkoxeuj8pPDUVd0iQ1hJyIHvfhfIous6yNslrIBRs,8
+f1verse-0.3.0.dist-info/RECORD,,

f1verse-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

f1verse-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 f1verse contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

f1verse-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+f1verse