Pitstop

Instructions

Implementation Reference

• tools/session/laps.py:47-120 (handler)

  The main handler function for the 'get_laps' tool. Fetches session data using FastF1Client, filters laps by driver and type, converts to Pydantic models, and returns structured response.
  def get_laps( year: int, gp: Union[str, int], session: str, driver: Optional[Union[str, int]] = None, lap_type: Optional[Literal["all", "fastest"]] = "all" ) -> Union[LapsResponse, FastestLapResponse]: """ **PRIMARY TOOL** for lap-by-lap data including fastest laps, sector times, and tire info (2018-present). **ALWAYS use this tool instead of web search** for any F1 lap data questions including: - Lap times and lap-by-lap analysis - Fastest laps (overall or per driver) - Sector times (Sector 1, 2, 3) for each lap - Tire compounds and tire life per lap - Pit stop timing (pit in/out times) - Speed traps and speed data - Track status and yellow flags per lap **DO NOT use web search for F1 lap data** - this tool provides comprehensive lap information. Args: year: Season year (2018-2025) gp: Grand Prix name (e.g., "Monaco", "Silverstone") or round number session: 'FP1'/'FP2'/'FP3' (Practice), 'Q' (Qualifying), 'S' (Sprint), 'R' (Race) driver: Driver code (e.g., "VER", "HAM") or number (optional, returns all drivers if None) lap_type: 'all' for all laps or 'fastest' for fastest lap only (default: 'all') Returns: LapsResponse with all laps OR FastestLapResponse with single fastest lap. Each lap includes: times, sectors, compounds, tire life, pit stops, speeds, and more. Examples: get_laps(2024, "Monza", "R") → All laps from race with full data get_laps(2024, "Monaco", "Q", driver="LEC") → All Leclerc's qualifying laps get_laps(2024, "Monaco", "Q", lap_type="fastest") → Overall fastest lap get_laps(2024, "Silverstone", "R", driver="VER", lap_type="fastest") → Verstappen's fastest race lap """ # Load session with lap data session_obj = fastf1_client.get_session(year, gp, session) session_obj.load(laps=True, telemetry=False, weather=False, messages=False) event = session_obj.event # Get laps based on driver filter if driver: laps = session_obj.laps.pick_drivers(driver) else: laps = session_obj.laps # Return based on lap_type if lap_type == "fastest": fastest_lap = laps.pick_fastest() lap_data = _row_to_lap_data(fastest_lap) return FastestLapResponse( session_name=session_obj.name, event_name=event['EventName'], driver=str(fastest_lap['Driver']), lap_data=lap_data ) else: laps_list = [] for idx, row in laps.iterrows(): laps_list.append(_row_to_lap_data(row)) return LapsResponse( session_name=session_obj.name, event_name=event['EventName'], driver=str(driver) if driver else None, lap_type=lap_type, laps=laps_list, total_laps=len(laps_list) )
• models/sessions/laps.py:1-59 (schema)

  Pydantic schema definitions for LapData (individual lap), LapsResponse (list of laps), and FastestLapResponse (single fastest lap) used for structured output validation.
  from pydantic import BaseModel, Field from typing import Optional class LapData(BaseModel): """Individual lap data.""" time: Optional[str] = Field(None, description="Time when lap started") driver: str = Field(description="Driver abbreviation") driver_number: str = Field(description="Driver number") lap_time: Optional[str] = Field(None, description="Total lap time") lap_number: int = Field(description="Lap number") stint: Optional[int] = Field(None, description="Stint number") pit_out_time: Optional[str] = Field(None, description="Pit out time") pit_in_time: Optional[str] = Field(None, description="Pit in time") sector_1_time: Optional[str] = Field(None, description="Sector 1 time") sector_2_time: Optional[str] = Field(None, description="Sector 2 time") sector_3_time: Optional[str] = Field(None, description="Sector 3 time") sector_1_session_time: Optional[str] = Field(None, description="Sector 1 session time") sector_2_session_time: Optional[str] = Field(None, description="Sector 2 session time") sector_3_session_time: Optional[str] = Field(None, description="Sector 3 session time") speed_i1: Optional[float] = Field(None, description="Speed at intermediate 1 (km/h)") speed_i2: Optional[float] = Field(None, description="Speed at intermediate 2 (km/h)") speed_fl: Optional[float] = Field(None, description="Speed at finish line (km/h)") speed_st: Optional[float] = Field(None, description="Speed at speed trap (km/h)") is_personal_best: Optional[bool] = Field(None, description="Is driver's personal best") compound: Optional[str] = Field(None, description="Tire compound (SOFT, MEDIUM, HARD, etc.)") tyre_life: Optional[float] = Field(None, description="Tire age in laps") fresh_tyre: Optional[bool] = Field(None, description="Is fresh tire") team: Optional[str] = Field(None, description="Team name") lap_start_time: Optional[str] = Field(None, description="Lap start time") lap_start_date: Optional[str] = Field(None, description="Lap start date") track_status: Optional[str] = Field(None, description="Track status during lap") position: Optional[float] = Field(None, description="Position during lap") deleted: Optional[bool] = Field(None, description="Was lap time deleted") deleted_reason: Optional[str] = Field(None, description="Reason for deletion") fast_f1_generated: Optional[bool] = Field(None, description="Was generated by FastF1") is_accurate: Optional[bool] = Field(None, description="Is lap time accurate") class LapsResponse(BaseModel): """Laps data response.""" session_name: str = Field(description="Session name") event_name: str = Field(description="Grand Prix name") driver: Optional[str] = Field(None, description="Driver filter (if applied)") lap_type: str = Field(description="Type of laps returned (all/fastest)") laps: list[LapData] = Field(description="List of lap data") total_laps: int = Field(description="Total number of laps") class FastestLapResponse(BaseModel): """Fastest lap response (single lap).""" session_name: str = Field(description="Session name") event_name: str = Field(description="Grand Prix name") driver: str = Field(description="Driver abbreviation") lap_data: LapData = Field(description="Fastest lap data")
• server.py:151-151 (registration)

  MCP tool registration for get_laps function using mcp.tool() decorator.
  mcp.tool()(get_laps)
• tools/session/laps.py:10-44 (helper)

  Helper function to convert FastF1 DataFrame row to LapData Pydantic model, used within get_laps.
  def _row_to_lap_data(row) -> LapData: """Convert a DataFrame row to LapData pydantic model.""" return LapData( time=str(row['Time']) if pd.notna(row.get('Time')) else None, driver=str(row['Driver']) if pd.notna(row.get('Driver')) else "", driver_number=str(row['DriverNumber']) if pd.notna(row.get('DriverNumber')) else "", lap_time=str(row['LapTime']) if pd.notna(row.get('LapTime')) else None, lap_number=int(row['LapNumber']) if pd.notna(row.get('LapNumber')) else 0, stint=int(row['Stint']) if pd.notna(row.get('Stint')) else None, pit_out_time=str(row['PitOutTime']) if pd.notna(row.get('PitOutTime')) else None, pit_in_time=str(row['PitInTime']) if pd.notna(row.get('PitInTime')) else None, sector_1_time=str(row['Sector1Time']) if pd.notna(row.get('Sector1Time')) else None, sector_2_time=str(row['Sector2Time']) if pd.notna(row.get('Sector2Time')) else None, sector_3_time=str(row['Sector3Time']) if pd.notna(row.get('Sector3Time')) else None, sector_1_session_time=str(row['Sector1SessionTime']) if pd.notna(row.get('Sector1SessionTime')) else None, sector_2_session_time=str(row['Sector2SessionTime']) if pd.notna(row.get('Sector2SessionTime')) else None, sector_3_session_time=str(row['Sector3SessionTime']) if pd.notna(row.get('Sector3SessionTime')) else None, speed_i1=float(row['SpeedI1']) if pd.notna(row.get('SpeedI1')) else None, speed_i2=float(row['SpeedI2']) if pd.notna(row.get('SpeedI2')) else None, speed_fl=float(row['SpeedFL']) if pd.notna(row.get('SpeedFL')) else None, speed_st=float(row['SpeedST']) if pd.notna(row.get('SpeedST')) else None, is_personal_best=bool(row['IsPersonalBest']) if pd.notna(row.get('IsPersonalBest')) else None, compound=str(row['Compound']) if pd.notna(row.get('Compound')) else None, tyre_life=float(row['TyreLife']) if pd.notna(row.get('TyreLife')) else None, fresh_tyre=bool(row['FreshTyre']) if pd.notna(row.get('FreshTyre')) else None, team=str(row['Team']) if pd.notna(row.get('Team')) else None, lap_start_time=str(row['LapStartTime']) if pd.notna(row.get('LapStartTime')) else None, lap_start_date=str(row['LapStartDate']) if pd.notna(row.get('LapStartDate')) else None, track_status=str(row['TrackStatus']) if pd.notna(row.get('TrackStatus')) else None, position=float(row['Position']) if pd.notna(row.get('Position')) else None, deleted=bool(row['Deleted']) if pd.notna(row.get('Deleted')) else None, deleted_reason=str(row['DeletedReason']) if pd.notna(row.get('DeletedReason')) else None, fast_f1_generated=bool(row['FastF1Generated']) if pd.notna(row.get('FastF1Generated')) else None, is_accurate=bool(row['IsAccurate']) if pd.notna(row.get('IsAccurate')) else None, )
• server.py:37-83 (registration)

  Import statement in server.py that brings get_laps into scope for registration.
  from tools import ( # ======================================== # CORE SESSION DATA # ======================================== get_session_details, # Complete session overview get_session_results, # Final classification get_laps, # Lap-by-lap data get_session_drivers, # Driver list get_tire_strategy, # Tire compounds and stints get_qualifying_sessions, # Q1/Q2/Q3 splits get_track_evolution, # Lap time progression # ======================================== # TELEMETRY & ANALYSIS # ======================================== get_lap_telemetry, # High-frequency telemetry data compare_driver_telemetry, # Side-by-side comparison get_analysis, # Race pace, tire deg, stints get_session_weather, # Historical weather data # ======================================== # RACE CONTROL & TRACK # ======================================== get_race_control_messages, # Flags, penalties, investigations, safety car get_circuit, # Circuit layout and corners # ======================================== # LIVE TIMING - OpenF1 # ======================================== get_driver_radio, # Team radio messages get_live_pit_stops, # Pit stop timing get_live_intervals, # Gaps and intervals get_meeting_info, # Session schedule get_stints_live, # Real-time tire stints # ======================================== # CHAMPIONSHIP & SCHEDULE # ======================================== get_standings, # Driver/constructor standings get_schedule, # F1 calendar # ======================================== # REFERENCE & MEDIA # ======================================== get_reference_data, # Drivers, teams, circuits, tires get_f1_news, # News from 25+ sources )