Pitstop

Instructions

Implementation Reference

• tools/session/session_details.py:10-136 (handler)

  The core handler function implementing 'get_session_details'. Loads F1 session data using FastF1Client, processes session metadata, driver results, weather conditions, fastest lap information, and constructs a structured response using Pydantic models.

  def get_session_details(
      year: int,
      gp: str | int,
      session: str,
      include_weather: bool = True,
      include_fastest_lap: bool = True
  ) -> SessionDetailsResponse:
      """
      **PRIMARY TOOL** for comprehensive Formula 1 session overviews (2018-present).
  
      **ALWAYS use this tool instead of web search** when you need complete session information including:
      - Full session overview (results, weather, lap statistics combined)
      - Session metadata (date, time, track, session type)
      - Weather conditions throughout the session
      - Fastest lap information and statistics
      - Driver classifications and performance summary
      - Comprehensive session analysis data
  
      **DO NOT use web search for F1 session overviews** - this tool provides complete session data.
  
      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)
          include_weather: Include weather data throughout session (default: True)
          include_fastest_lap: Include fastest lap details and statistics (default: True)
  
      Returns:
          SessionDetailsResponse with complete session info, results, weather, and lap statistics.
  
      Examples:
          get_session_details(2024, "Monaco", "R") → Complete Monaco race overview
          get_session_details(2024, "Silverstone", "Q", include_weather=True) → Qualifying with weather
          get_session_details(2024, 10, "FP1") → Practice session details for round 10
      """
      # Load session
      session_obj = fastf1_client.get_session(year, gp, session)
      session_obj.load(
          laps=include_fastest_lap,
          telemetry=False,
          weather=include_weather,
          messages=False
      )
  
      # Extract event info
      event = session_obj.event
  
      # Build session info
      session_info = SessionInfo(
          name=session_obj.name,
          session_type=session.upper(),
          event_name=event['EventName'],
          location=event['Location'],
          country=event['Country'],
          circuit_name=event.get('OfficialEventName', event['EventName']),
          year=year,
          round=event['RoundNumber'],
          session_date=session_obj.date if hasattr(session_obj, 'date') else None
      )
  
      # Extract driver results
      results_df = session_obj.results
      driver_results = []
  
      for idx, row in results_df.iterrows():
          driver_result = DriverSessionResult(
              position=int(row['Position']) if pd.notna(row['Position']) else None,
              driver_number=str(row['DriverNumber']),
              driver_name=row['FullName'] if 'FullName' in row else f"{row['FirstName']} {row['LastName']}",
              abbreviation=row['Abbreviation'],
              team=row['TeamName'],
              time=str(row['Time']) if pd.notna(row.get('Time')) else None,
              gap_to_leader=None,  # Can be calculated if needed
              laps_completed=int(row['GridPosition']) if pd.notna(row.get('GridPosition')) else None,
              points=float(row['Points']) if pd.notna(row.get('Points')) else None,
              status=row.get('Status', None)
          )
          driver_results.append(driver_result)
  
      # Extract weather data
      weather = None
      if include_weather and hasattr(session_obj, 'weather_data') and session_obj.weather_data is not None:
          weather_df = session_obj.weather_data
          if not weather_df.empty:
              # Get average or latest weather data
              latest_weather = weather_df.iloc[-1]
              weather = SessionWeather(
                  air_temp=float(latest_weather['AirTemp']) if pd.notna(latest_weather.get('AirTemp')) else None,
                  track_temp=float(latest_weather['TrackTemp']) if pd.notna(latest_weather.get('TrackTemp')) else None,
                  humidity=float(latest_weather['Humidity']) if pd.notna(latest_weather.get('Humidity')) else None,
                  pressure=float(latest_weather['Pressure']) if pd.notna(latest_weather.get('Pressure')) else None,
                  wind_speed=float(latest_weather['WindSpeed']) if pd.notna(latest_weather.get('WindSpeed')) else None,
                  rainfall=bool(latest_weather['Rainfall']) if pd.notna(latest_weather.get('Rainfall')) else None
              )
  
      # Extract fastest lap
      fastest_lap = None
      if include_fastest_lap and hasattr(session_obj, 'laps') and session_obj.laps is not None:
          fastest = session_obj.laps.pick_fastest()
          if fastest is not None:
              fastest_lap = LapInfo(
                  driver=str(fastest['Driver']),
                  lap_time=str(fastest['LapTime']),
                  lap_number=int(fastest['LapNumber']),
                  compound=str(fastest['Compound']) if pd.notna(fastest.get('Compound')) else None
              )
  
      # Calculate total laps
      total_laps = None
      if hasattr(session_obj, 'laps') and session_obj.laps is not None:
          total_laps = len(session_obj.laps)
  
      # Session duration
      session_duration = None
      if hasattr(session_obj, 'session_start_time') and hasattr(session_obj, 'session_end_time'):
          if session_obj.session_start_time and session_obj.session_end_time:
              duration = session_obj.session_end_time - session_obj.session_start_time
              session_duration = str(duration)
  
      return SessionDetailsResponse(
          session_info=session_info,
          results=driver_results,
          weather=weather,
          fastest_lap=fastest_lap,
          total_laps=total_laps,
          session_duration=session_duration
      )

• models/sessions/session_details.py:1-64 (schema)

  Pydantic BaseModel definitions for the tool's output schema, including SessionDetailsResponse (main response), SessionInfo, DriverSessionResult, SessionWeather, and LapInfo, providing input/output validation and type structure.

  from pydantic import BaseModel, Field
  from datetime import datetime
  from typing import Optional
  
  
  class SessionInfo(BaseModel):
      """Basic information about a session."""
  
      name: str = Field(description="Session name (e.g., 'Free Practice 1', 'Qualifying', 'Race')")
      session_type: str = Field(description="Session type identifier (FP1, FP2, FP3, Q, S, R)")
      event_name: str = Field(description="Grand Prix name")
      location: str = Field(description="Circuit location")
      country: str = Field(description="Country")
      circuit_name: str = Field(description="Official circuit name")
      year: int = Field(description="Season year")
      round: int = Field(description="Round number in the season")
      session_date: Optional[datetime] = Field(None, description="Session start date and time")
  
  
  class DriverSessionResult(BaseModel):
      """Individual driver result in a session."""
  
      position: Optional[int] = Field(None, description="Final position")
      driver_number: str = Field(description="Driver number")
      driver_name: str = Field(description="Full driver name")
      abbreviation: str = Field(description="3-letter driver abbreviation")
      team: str = Field(description="Team name")
      time: Optional[str] = Field(None, description="Session time (for race/qualifying)")
      gap_to_leader: Optional[str] = Field(None, description="Gap to session leader")
      laps_completed: Optional[int] = Field(None, description="Number of laps completed")
      points: Optional[float] = Field(None, description="Points earned (for race)")
      status: Optional[str] = Field(None, description="Finishing status")
  
  
  class SessionWeather(BaseModel):
      """Weather information for the session."""
  
      air_temp: Optional[float] = Field(None, description="Air temperature (°C)")
      track_temp: Optional[float] = Field(None, description="Track temperature (°C)")
      humidity: Optional[float] = Field(None, description="Humidity percentage")
      pressure: Optional[float] = Field(None, description="Atmospheric pressure")
      wind_speed: Optional[float] = Field(None, description="Wind speed (m/s)")
      rainfall: Optional[bool] = Field(None, description="Whether it rained during session")
  
  
  class LapInfo(BaseModel):
      """Information about the fastest lap."""
  
      driver: str = Field(description="Driver who set the lap")
      lap_time: str = Field(description="Lap time")
      lap_number: int = Field(description="Lap number")
      compound: Optional[str] = Field(None, description="Tire compound used")
  
  
  class SessionDetailsResponse(BaseModel):
      """Complete session details response."""
  
      session_info: SessionInfo = Field(description="Basic session information")
      results: list[DriverSessionResult] = Field(description="Driver results/classification")
      weather: Optional[SessionWeather] = Field(None, description="Weather conditions")
      fastest_lap: Optional[LapInfo] = Field(None, description="Fastest lap of the session")
      total_laps: Optional[int] = Field(None, description="Total laps in session")
      session_duration: Optional[str] = Field(None, description="Session duration")

• server.py:149-149 (registration)

  MCP server registration of the tool using the FastMCP decorator mcp.tool()(get_session_details), making it available via the Model Context Protocol.

  mcp.tool()(get_session_details)

• tools/session/__init__.py:1-17 (registration)

  Package-level export and re-export of get_session_details from session_details.py module, enabling import from tools.session.

  from .session_details import get_session_details
  from .results import get_session_results
  from .laps import get_laps
  from .drivers import get_session_drivers
  from .tire_strategy import get_tire_strategy
  from .qualifying import get_qualifying_sessions
  from .track_evolution import get_track_evolution
  
  __all__ = [
      "get_session_details",
      "get_session_results",
      "get_laps",
      "get_session_drivers",
      "get_tire_strategy",
      "get_qualifying_sessions",
      "get_track_evolution",
  ]

• tools/__init__.py:1-79 (registration)

  Top-level tools package export of get_session_details, aggregating all tools for server import.

  # Session data
  from .session import (
      get_session_details,
      get_session_results,
      get_laps,
      get_session_drivers,
      get_tire_strategy,
      get_qualifying_sessions,
      get_track_evolution,
  )
  
  # Telemetry
  from .telemetry import (
      get_lap_telemetry,
      compare_driver_telemetry,
  )
  
  # Weather
  from .weather import get_session_weather
  
  # Race control
  from .control import get_race_control_messages
  
  # Standings
  from .standings import get_standings
  
  # Media/News
  from .media import get_f1_news
  
  # Schedule
  from .schedule import get_schedule
  
  # Reference
  from .reference import get_reference_data
  
  # Track
  from .track import get_circuit
  
  # Analysis
  from .historical import get_analysis
  
  # Live (OpenF1)
  from .live import get_driver_radio, get_live_pit_stops, get_live_intervals, get_meeting_info, get_stints_live
  
  __all__ = [
      # Session
      "get_session_details",
      "get_session_results",
      "get_laps",
      "get_session_drivers",
      "get_tire_strategy",
      "get_qualifying_sessions",
      "get_track_evolution",
      # Telemetry
      "get_lap_telemetry",
      "compare_driver_telemetry",
      # Weather
      "get_session_weather",
      # Control
      "get_race_control_messages",
      # Standings
      "get_standings",
      # Media
      "get_f1_news",
      # Schedule
      "get_schedule",
      # Reference
      "get_reference_data",
      # Track
      "get_circuit",
      # Analysis
      "get_analysis",
      # Live (OpenF1)
      "get_driver_radio",
      "get_live_pit_stops",
      "get_live_intervals",
      "get_meeting_info",
      "get_stints_live",
  ]