f1verse

f1verse

ドキュメント · MCP サーバー · llms.txt · 変更履歴 · コントリビューション · セキュリティ · ライセンス

Formula 1 データのストーリーレイヤーです。 データライブラリが取得して整理するのに対し、f1verse は 何が起きたか を伝えます。首位交代、周回リード数、イベントのタイムライン、スティント戦略、レースペース、そして 次に何が起きるか。独自のバックテストを備えたシーズンシミュレーションから、タイトル獲得確率を算出します。

依存関係はゼロです。 標準ライブラリのみを使用します。2023 年以降のライブタイミングデータを完全にカバーし、周回ごとのレースデータは 1996 年まで、ピットストップは 2011 年まで、リザルト、予選、ランキングは 1950 年までさかのぼります。各回答には、どの時代のデータに基づくか、その時代のデータに何が含まれていないかが示されます。

pip install f1verse

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)

f1verse.championship_projection(2026)   # who wins the title, 20,000 seasons
f1verse.title_scenarios(2026)           # and who is mathematically out

AI エージェントに渡す

f1verse には独自の MCP サーバーが付属します。インストール手順も依存関係もありません。

{"mcpServers": {"f1verse": {"command": "uvx", "args": ["--from", "f1verse", "f1verse-mcp"]}}}

セットアップはこれだけです。サーバーは標準ライブラリのみを使用するため、使い捨ての環境に科学計算用のスタックを展開することなく、約 140 ms で起動し、tools/list に応答します。ツールは 80 個ではなく 8 個なので、モデルが適切なものを選べます。

ほかの LLM パイプライン向けには、ライブラリ自身が説明を提供します。

f1verse.tools()                  # MCP-dialect JSON schemas
f1verse.tools("openai")          # function-calling dialect
f1verse.call_tool("f1_race_story", {"year": 2026, "round": 12})

エラーは、このページを読まずに修正しなければならない呼び出し元に向けて書かれています。

f1verse.call_tool("f1_race_summary", {})
# LookupError: unknown tool 'f1_race_summary' — available: f1_race_story, ...
f1verse.load_session(2026, 12, "Qualy")
# LookupError: ... listing the sessions that weekend actually had

レースだけでなく、週末全体を

f1verse.sessions(2026, 12)
# Practice 1 · Sprint Qualifying · Sprint · Qualifying · Race

q = f1verse.load_session(2026, 12, "Qualifying")
q.results()[0]
# {'abbr': 'NOR', 'q1': 72.695, 'q1_gap': 0.085, 'q3': 71.163, 'q3_gap': 0.0,
#  'best': 71.163, 'eliminated_in': None, ...}

q.segments()["q1"]
# {'fastest': 'PIA', 'advanced': [...16 codes...], 'eliminated': [...],
#  'cut_margin': 0.022}

各セッションは、実際の形式に応じて分類されます。予選のタイム差は、そのセグメントの最速ラップとの差です。上記のポールシッターは Q1 では 0.085 秒遅れていたためです。「リーダーとの差」という列を一つ設けるだけでは、セッションの実態を誤って伝えてしまいます。スプリントは Race として読み込まれ、フリー走行はベストラップの表になります。

このデータは公開しても安全ですか？

race.quality_report()
# {'state': 'final',            # provisional → settled → final, or corrected
#  'coverage': {'overall': 0.9955, 'sectors': 0.9824, 'compound': 1.0},
#  'missing': ['STR.lap_46.lap_duration', ...],
#  'source_age_seconds': 312,
#  'revisions': [],             # source rewrites this install has observed
#  'crosscheck': {...},
#  'publishable': True}

crosscheck は、独立した情報源同士で一致しているか を答えます。quality_report は、その判定だけでは分からない 3 つの点を加えます。データの完全性、コピーの古さ、そして順位がまだ暫定かどうかです。

チェッカーフラッグが振られても、順位はまだ確定ではありません。車検による失格やペナルティは数時間後に確定し、既存の行を書き換えることがあります。そのため、スチュワードが変更できる行はセッションが確定するまで永久にキャッシュされません。また、検出した変更はすべて記録されます。

before = race.snapshot()          # hashed, comparable, JSON — you persist it
...
f1verse.diff(before, race.refresh().snapshot())
# {'changed': True,
#  'changes': [{'abbr': 'HAM', 'field': 'position', 'before': 4, 'after': None},
#              {'abbr': 'HAM', 'field': 'gap', 'before': '+8.1s', 'after': 'DSQ'}]}

f1verse.revisions()               # every source rewrite observed, with the
f1verse.vintage(rec)              # superseded body when it was small enough

意図的に as_of= による過去時点の参照機能はありません。f1verse が伝えられるのは、現在確認できる内容と、値の変更を確認した時刻です。ここで一度も取得されていない値を再構成することはできません。

レースの実際の展開

race = f1verse.load(2025, 24)

race.running_order()[30]
# ['PIA', 'VER', 'NOR', 'LEC', 'RUS', ...]   who was where, lap by lap

race.position_changes()[1]
# {'lap': 2, 'moves': 18, 'biggest': {'abbr': 'PIA', 'gained': 17,
#                                     'from': 19, 'to': 2}}

race.battles()[0]
# {'ahead': 'HAD', 'behind': 'OCO', 'from': 2, 'to': 14, 'laps': 13,
#  'closest': 0.529}      <- a thirteen-lap fight the results table hides

battles は、少なくとも 3 周にわたって 1.5 秒以内の間隔で連続して順位を保ったペアを見つけます。レースの 3 分の 1 にわたって続いた 8 位争いは、順位表には現れません。しかし、午後のレースで最も見応えのある場面であることもよくあります。

ライブフィード以前のレース

old = f1verse.load_archive(2008, 18)     # Brazil, the last-corner title

old.coverage
# {'lap_times': True, 'pit_stops': False, 'stints': False,
#  'note': 'lap times only'}

old.leader_runs()
# [{'abbr': 'MAS', 'from': 1, 'to': 9}, {'abbr': 'TRU', 'from': 10, 'to': 11},
#  {'abbr': 'MAS', 'from': 12, 'to': 38}, ...]

old.laps_led()          # {'MAS': 64, 'TRU': 2, 'ALO': 2, 'RAI': 3}

coverage ブロックは飾りではありません。2008 年にはスティントデータがどこにもないため、ArchiveRace には stints() がありません。「ピットストップがなかった」と読めてしまう空の辞書を返す代わりに、そのようにしています。その時代に記録されている情報を返し、記録されていない情報についてはそう明示します。

シーズンを比較する

f1verse.season_shape(2025)
# {'rounds': 24, 'final_margin': 2.0,
#  'lead_changes': [{'round': 5, 'from': 'NOR', 'to': 'PIA'},
#                   {'round': 20, 'from': 'PIA', 'to': 'NOR'}], ...}

f1verse.title_margins(top=5)
# 2025  NOR 423.0 vs VER 421.0   margin 2.0   (0.08 of a win)
# 2008  HAM  98.0 vs MAS  97.0   margin 1.0   (0.10 of a win)
# 2012  VET 281.0 vs ALO 278.0   margin 3.0   (0.12 of a win)

ポイント制度は何度も変更されているため、単純な得点差では時代を超えた比較はできません。1958 年の 1 ポイントは、優勝の大半に相当しました。各行には、ルール変更を経ても比較可能な指標である、勝利数で測った差も含まれています。

オーバーテイクが起きた場所

f1verse.overtake_hotspots(race)[0]
# {'from_s': 3510.0, 'to_s': 3540.0, 'signals': 69, 'drivers': [...]}

タイミングフィードは、ほとんど変化しない OvertakeState を各マシンについて配信します。1万9千件の記録のうち、遷移は約100回しかありません。この疎さこそが価値です。レースを計時する同じフィードから、注目すべき瞬間のインデックスを無料で得られます。「ここで何かが起きた」と捉え、running_order と照合して確認してください。

1つのレースを超えて

f1verse.career("max_verstappen")
# {'starts': 245, 'wins': 71, 'podiums': 131, 'poles': 48, ...}  1950-present

f1verse.milestones("max_verstappen")
# [{'stat': 'poles', 'current': 48, 'target': 50, 'remaining': 2}]

f1verse.circuit_profile(2026, 13)
# corners, marshal sectors, track outline, and pit loss split by track state
# {'normal': 25.43, 'sc': 16.11, 'vsc': 18.4}  <- what an undercut costs here
# plus historic record: 75 races held, pole-to-win rate 0.30

# Geometry is also interpreted, but never overclaimed: every corner carries
# its lap position, preceding-run share and local heading deflection; mini-
# and marshal-sector boundaries carry lap percentages.
profile = f1verse.circuit_profile(2026, 13)
profile["layout"]["corners"][0]
# {'number': 1, 'progress_pct': 8.412, 'local_deflection_deg': 72.6, ...}

# What a map cannot say, the cars can. This measures the circuit from the
# session's own telemetry: the height profile, where overtakes actually
# happen, how much of the lap is flat out and where it is braked, and every
# numbered corner as the car experienced it.
f1verse.circuit_survey(2026, 13)["corners"]["corners"][0]
# {'corner': 1, 'apex_speed_kph': 103, 'radius_m': 40.0,
#  'lateral_load_g': 2.09, 'gear_at_apex': 2, 'severity': 'medium'}

# Published specifications are stored rather than derived, and the
# measurement audits them rather than replacing them.
f1verse.circuit_profile(2026, 13, measure=True)["audit"]
# {'verdict': 'agrees', 'checked_age_days': 0,
#  'checks': [{'field': 'length_m', 'published': 4259, 'measured': 4274.4,
#              'off_by_percent': 0.36, 'state': 'agrees'}, ...]}

# The published facts and the audit are reachable on their own, so a caller
# can ask what is claimed without paying for a telemetry survey.
f1verse.circuit_facts("Austin")
# {'length_m': 5513, 'race_laps': 56, 'race_distance_km': 308.405,
#  'provenance': {'length_m': 'curated', ...},
#  'source': 'formula1.com official circuit page, 2026 united-states',
#  'checked': '2026-09-01'}
# None for a circuit nobody has curated yet - it does not invent a length

f1verse.circuit_audit(2026, 13)
# the same verdict as profile(measure=True)["audit"], on its own

f1verse.circuit_directory()
# every venue recorded in F1 results, with stable id, city, country and
# coordinates; unlike a current map, it does not pretend an old layout has
# today's geometry

f1verse.circuit_history("monza")
# every F1 event at the venue, recent winners and starting positions,
# pole-to-win conversion, and the drivers with the most wins

f1verse.head_to_head(2026)
# teammate quali/race scores per constructor

f1verse.standings(2026)

タイヤの寿命と、スチュワードが取り消した内容

f1verse.stint_degradation(race)[3]
# {'driver': 'NOR', 'stint': 2, 'compound': 'HARD', 'tyre_age_at_start': 0,
#  'clean_laps_used': 18, 'degradation_s_per_lap': 0.041}

f1verse.circuit_abrasion(race)
# {'factor': 1.4, 'verdict': 'abrasive', 'samples': 55}

f1verse.tyre_outlook(race)          # projected to the cliff

マシンは燃料を消費するにつれてレース中ずっと速くなるため、生のラップタイムではすべてのスティントのデグラデーションが過小評価されます。レートの計算には燃料補正済みのクリーンラップのみを使用します。該当するラップが少なすぎるスティントでは、ノイズに合わせた数値を返すのではなく、{'degradation_s_per_lap': None, 'reason': 'too few clean laps'} を返します。

f1verse.lap_deletions(session.race_control)
# [{'car_number': 55, 'lap_time': '1:25.773', 'stands': True,
#   'reason': 'TRACK LIMITS AT TURN 3 LAP 3', ...}]

復活したラップでは、取り消しがひっそりと削除されるのではなく、その経緯が見えるようになっています。最速ラップや予選順位を確定済みとして扱う前に、これを確認してください。

ライブタイミングを直接受信

from f1verse.sources import liveclient

with liveclient.LiveFeed() as feed:
    for topic, patch, stamp in feed.messages():
        ...

liveclient.run("session-{n}.jsonl")   # record, rotate on turnover, reconnect

標準ライブラリで記述された WebSocket を通じて、公式 SignalR フィードに接続します。WebSocket パッケージも SignalR クライアントも必要ありません。接続には、文書化されていない3つの作法があります（プリフライトリクエストにのみ返されるアフィニティクッキー、公式アプリケーションのユーザーエージェント、サブスクリプションの呼び出し ID）。これらは1か所にまとめられており、呼び出し元がそれぞれ見つけ直す必要はありません。

記録されたフレームにはミリ秒単位の受信タイムスタンプが付いています。これが、アーカイブとスクリーンショットの違いです。そのため、replay() ではセッションを実際の速度で再生できます。ストリームはラップテーブルではないため、f1verse.sources.timing.laps_from_stream でラップテーブルを再構築します。受信順は実際の順序とは異なり、セクタータイムは次のラップが始まってから届くことがあり、予選では実際には2回の走行間のギャップである見かけ上のラップタイムが含まれます。再構築された各ラップ行には、その出所が記録されます。

スケジュールに沿って実行する

f1verse.status(2026)
# {'latest_race': {'round': 12, 'meeting': 'Dutch Grand Prix'},
#  'next': {'round': 13, 'session': 'Practice 1'}, 'next_in_hours': 125.7}

f1verse.due(2026, processed=[...session keys you already handled...])
# sessions finished, settled (45 min past the flag) and not yet processed —
# nothing published twice, nothing missed after downtime

キャッシュは一律ではなく、ポリシーに基づいています。ラップデータとテレメトリーデータは不変のため無期限にキャッシュされます。スケジュールは数時間ごとに期限切れになります。シーズン中ずっとカレンダーをキャッシュすると、ラウンドの中止がその年の残りの期間ずっと反映されなくなるためです。スチュワードがまだ変更できる行は、セッションが確定するまで期限切れになります。運用担当者向けに f1verse.cache_info() と f1verse.clear_cache(older_than=...) が用意されています。clear_cache がリビジョンジャーナルを削除することはありません。

テレメトリー、トラック上の位置、コンディション

f1verse.lap_telemetry(race, "NOR", 40)
# per-sample speed, throttle, brake, gear, RPM and DRS state for one lap

f1verse.lap_trace(race, "NOR", 40)      # x/y/z coordinates of that lap
f1verse.top_speeds(race)                # fastest reading per driver

f1verse.weather_summary(race)
# {'track_c': {'min': 25.8, 'max': 38.2}, 'rain': True, 'samples': 191}

テレメトリーは高頻度のデータであるため、これらの機能では範囲を指定し、セッション全体をダウンロードしてローカルで絞り込むのではなく、サーバー側でフィルタリングします。

根拠に基づくナレーション

facts = f1verse.race_facts(race)       # all numbers computed and formatted here
f1verse.brief(race)                    # deterministic text, no model required

result = f1verse.narrate(
    race,
    generate=lambda prompt: my_model(prompt),
    cache_dir=".cache/narration",
)
# {'text': '...', 'source': 'generated' | 'cache' | 'template', ...}

narrate は任意のテキスト生成コールバックを受け付けます。f1verse はモデル SDK に依存しません。生成文は構造化されたファクトシートと照合されます。不明な数値やドライバーコードは拒否され、生成は最大2回まで再試行されます。それでも検証に失敗した場合は、決定論的な要約が返されます。任意で使用できるキャッシュは完全一致のみを対象とし、検証済みのテキストを保存します。

チャンピオンになるのは誰か――そして、まだ可能性があるのは誰か

これは別々の2つの問いです。混同すると、計算上はまだ可能性があるのに、誰かが脱落したかのような予測になってしまいます。

f1verse.title_scenarios(2026)
# arithmetic, not a forecast — maximum points left is a fixed number
# {'rounds_left': 11, 'sprints_left': 1, 'max_points_available': 283,
#  'drivers': [{'driver': 'RUS', 'gap_to_leader': 59.0,
#               'still_possible': True, 'needs_avg_per_round': 5.4}, ...],
#  'still_alive': 23}

f1verse.championship_projection(2026)
# the rest of the season, played out 20,000 times
# {'drivers': [{'driver': 'ANT', 'title_probability': 0.954,
#               'points_now': 242.0, 'projected_points_median': 446,
#               'projected_points_p10': 390, 'projected_points_p90': 490,
#               'races_in_sample': 11, 'measured_dnf_rate': 0.08}, ...],
#  'assumptions': {'ignores': ['car development', 'weather', ...], ...}}

シミュレーションでの最終順位は、平均順位の周りに分布する曲線から抽出するのではなく、そのドライバーが実際に記録した順位から再サンプリングします。この違いがチャンピオンシップの予測を左右します。勝利とリタイアを交互に繰り返すのと、毎週末4位でフィニッシュするのとでは、平均が同じでも状況は異なります。リタイアは各ドライバーの実測発生率に基づいて反映され、スプリントは独自のポイント表に基づいて採点され、同点の場合はレギュレーションどおり、勝利数、次に2位の回数で順位を決めます。

各シミュレーションでは、まずドライバー自身の実力を再抽出します。つまり、シーズンをそのドライバーの結果でブートストラップしてから、そのバージョンのドライバーとシーズンを戦います。12レースは小さなサンプルであり、それを確定した真実として扱うと、予測が本来よりも確信に満ちたものになってしまいます。

f1verse.backtest_projection()      # does the model deserve to be believed?
# {'by_confidence': {'over_90': {'n': 5, 'correct': 5, 'rate': 1.0},
#                    'under_60': {'n': 2, 'correct': 0, 'rate': 0.0}}, ...}

2019～2025年の第12戦時点で再検証したところ、勝率90％以上と予測したシーズンは5回中5回的中しました。外れたのは、どちらも予測勝率を53％、57％としていたシーズンで、いずれも最終戦まで決着がつきませんでした。見出しではなく、確率の区分を見てください。55％と予測して外れたとしても、モデルに問題があったわけではありません。

feeds の championship_prediction は別のもので、F1独自の「今終了した場合」のリアルタイム順位表です。championship_projection はこのモデルです。一方は現状を報告し、もう一方は予測します。

予測、ピットストップの判定、公式ドキュメント

f1verse.win_probabilities({"NOR": 1, "ANT": 2, "RUS": 3},
                          year=2026, upto_round=12, circuit_id="monza")
# every probability ships with its own evidence:
#   grid base rate measured over 233 real races (pole wins 54.1%)
#   blended with that circuit's pole-to-win conversion (Monza: 0.30)
#   scaled by recent form (average finish over the last 5 rounds)

f1verse.pit_exchanges(race, pit_loss_s=22.74)
# [{'lap': 17, 'driver': 'RUS', 'rival': 'PIA', 'verdict': 'worked',
#   'gain_s': 3.54}, ...]
# neutralised laps (red flag / SC / VSC) and same-lap covering stops are
# excluded — calling those undercuts would be wrong

f1verse.fia_documents(2026)          # stewards' decisions, classified
f1verse.power_unit_documents(2026)   # "who changed which engine part"

このプロジェクトの目的

生のタイミングデータを理解するには、多くの専門知識が必要です。

• 周回遅れのマシン同士では、確定順位のタイム差を比較できません。 1周遅れのマシンが、同一周回でフィニッシュしたマシンより小さな数値で表示されることがあります。→ format_gap は放送で使われる表記（+1 LAP）を適用します。
• 「誰がレースをリードしたか」は、データから導き出す必要があります。 首位交代、リードした周回数、その発生時刻は、そのまま公開されていません。 → leader_runs、laps_led、timeline。
• レースペースの算出には、単なるしきい値ではなくルールが必要です。 アウトラップとインラップ、SC／VSC中の周回を除外しなければ、数値に意味がなくなります。 → race_pace はデフォルトでこれらのルールを適用します。
• ウェブや動画のパイプラインには、プレーンなJSONが必要です。 f1verse の出力はすべてシリアライズ可能な、JSONセーフのPythonオブジェクトです。
• データ品質はログを読むのではなく、コードで確認できるべきです。 → crosscheck と quality_report は、構造化された判定結果を返します。
• 結果はチェッカーフラッグ後に変更されることがあります。 確定順位を不変として扱うキャッシュでは、スチュワードの裁定が反映されません。 → 修正可能な行はセッションが確定するまで有効期限が切れるようにし、変更を記録します。

追加のリアルタイムタイミングフィード

公式のリアルタイムタイミングアーカイブでは、あまり紹介されていない複数のフィードが公開されています。f1verse はそのうち3つを、ライブラリの他の機能と同じキャッシュおよびレート制限への配慮を適用して解析します。

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

継続的に実行する

キャッシュポリシー、レート制限、スケジュール設定については、OPERATIONS.md を参照してください。

テスト

pip install -e ".[test]" && pytest -q

データソース

レイヤー	提供されるデータ
レースデータ	ラップ、スティント、ピット、順位、結果、オーバーテイク
リアルタイムタイミングアーカイブ	チャンピオンシップ予測、チームラジオ、タイミング統計
過去の記録	キャリア、サーキット記録、順位表――1950年以降
サーキット形状データ	トラック外形、コーナー、マーシャルセクター、ピットロス

すべて実行時に公開エンドポイントから取得します。正確なホストについては src/f1verse/sources/ を、上流データの権利とこのプロジェクト独自のライセンスとの関係については NOTICE を参照してください。

設計方針

1. 必須の依存関係はゼロです。 ネイティブローダーは、独自のディスクキャッシュと適切な間隔制御を使用して、公開RESTエンドポイントと公式のリアルタイムタイミングアーカイブを直接読み取ります。
2. 返されるデータはすべて、JSONセーフのプレーンなPythonオブジェクトです。
3. F1固有のルールは、オプションではなくデフォルトです。
4. 可能な場合は相互検証します。 たとえば、周回遅れのマシンのタイム差は慣例に基づいて計算し、2つ目のデータソースでも確認します。
5. コードのみです。 タイミングデータ、メディア、画像は同梱も再配布もされません。データはエンドユーザーが取得します。

ライセンス

Apache-2.0。詳細はLICENSEおよびNOTICEをご覧ください。

私的または商用で利用できます。内容の閲覧、変更、再配布が可能で、これを基に製品やホスト型サービスを構築することもできます。ライセンスと通知を保持し、重要な変更を明記したうえで、ライセンスの特許条項を遵守してください。f1verseを利用するソフトウェアやサービスに、ソースコードの開示義務はありません。

このライセンスの対象は、f1verse独自のソースコードです。実行時に読み込まれるFormula 1のデータは、それぞれの権利者に帰属し、各権利者の条件が適用されます。

ロードマップ

• クロスバリデーションの対象範囲を拡大
• 偏差の検出：想定範囲、実測値、根拠
• ローカライズパッケージ

---

非公式のファンプロジェクトです。Formula 1、FIA、FOM、またはいずれのF1チームとも提携、承認、関係はありません。F1、FORMULA 1、および関連する標章はFormula One Licensing BVの商標です。このライブラリにはコードのみが含まれ、タイミングデータ、メディア、画像は収録も再配布もされていません。データはエンドユーザーが公開エンドポイントから取得し、それぞれの提供元の条件に従います。