get_circuit

Instructions

Implementation Reference

• tools/track/track.py:15-140 (handler)

  Main handler function implementing the get_circuit tool logic. Fetches circuit layout, corners, and track status data using FastF1 client.

  def get_circuit(
      year: int,
      gp: Union[str, int],
      data_type: Literal["circuit_info", "track_status"] = "circuit_info",
      session: Optional[str] = None,
  ) -> CircuitDataResponse:
      """
      Get circuit layout, corners, or track status (flags, safety car).
  
      Args:
          year: Season year (2018+)
          gp: Grand Prix name or round
          data_type: 'circuit_info' (layout/corners) or 'track_status' (flags)
          session: Required for track_status ('FP1', 'FP2', 'FP3', 'Q', 'S', 'R')
  
      Returns:
          CircuitDataResponse with circuit details or track status changes
  
      Examples:
          get_circuit(2024, "Monaco", "circuit_info") → Circuit layout and corners
          get_circuit(2024, "Monaco", "track_status", session="R") → Flag periods
      """
      # Get event information
      event = fastf1_client.get_event(year, gp)
  
      if data_type == "circuit_info":
          # Load a session to get circuit info (use Race or first available session)
          if session:
              session_obj = fastf1_client.get_session(year, gp, session)
          else:
              # Try to get race session, fallback to any available
              try:
                  session_obj = fastf1_client.get_session(year, gp, 'R')
              except Exception:
                  try:
                      session_obj = fastf1_client.get_session(year, gp, 'Q')
                  except Exception:
                      session_obj = fastf1_client.get_session(year, gp, 1)
  
          session_obj.load()
  
          # Get circuit information
          try:
              circuit_info = session_obj.get_circuit_info()
  
              # Extract corner information
              corners_list = []
              if circuit_info.corners is not None and len(circuit_info.corners) > 0:
                  for idx, corner in circuit_info.corners.iterrows():
                      corners_list.append(
                          CornerInfo(
                              number=int(corner['Number']) if pd.notna(corner.get('Number')) else idx,
                              letter=str(corner['Letter']) if pd.notna(corner.get('Letter')) else None,
                              distance=float(corner['Distance']) if pd.notna(corner.get('Distance')) else None,
                              x=float(corner['X']) if pd.notna(corner.get('X')) else None,
                              y=float(corner['Y']) if pd.notna(corner.get('Y')) else None,
                          )
                      )
  
              circuit_details = CircuitDetails(
                  circuit_key=int(circuit_info.circuit_key) if hasattr(circuit_info, 'circuit_key') and circuit_info.circuit_key else None,
                  circuit_name=str(event['EventName']) if event is not None else None,
                  location=str(event['Location']) if event is not None else None,
                  country=str(event['Country']) if event is not None else None,
                  rotation=float(circuit_info.rotation) if hasattr(circuit_info, 'rotation') and circuit_info.rotation else None,
                  corners=corners_list if corners_list else None,
              )
          except Exception as e:
              # If circuit info not available, provide basic event info
              circuit_details = CircuitDetails(
                  circuit_name=str(event['EventName']) if event is not None else None,
                  location=str(event['Location']) if event is not None else None,
                  country=str(event['Country']) if event is not None else None,
              )
  
          return CircuitDataResponse(
              year=year,
              event_name=str(event['EventName']) if event is not None else "",
              session_name=None,
              circuit_details=circuit_details,
              data_type=data_type,
          )
  
      elif data_type == "track_status":
          if not session:
              raise ValueError("session parameter is required for track_status data type")
  
          # Load session with track status data
          session_obj = fastf1_client.get_session(year, gp, session)
          session_obj.load()
  
          # Get track status data
          track_status_df = session_obj.track_status
          track_status_list = []
  
          if track_status_df is not None and len(track_status_df) > 0:
              for idx, row in track_status_df.iterrows():
                  # Map status codes to messages
                  status_code = str(row['Status'])
                  status_messages = {
                      '1': 'Green Flag / Track Clear',
                      '2': 'Yellow Flag / Caution',
                      '3': 'Green Flag (after SC)',
                      '4': 'Safety Car',
                      '5': 'Red Flag / Session Stopped',
                      '6': 'Virtual Safety Car (VSC)',
                      '7': 'VSC Ending',
                  }
                  message = status_messages.get(status_code, f'Status Code {status_code}')
  
                  track_status_list.append(
                      TrackStatusInfo(
                          time=str(row['Time']) if pd.notna(row.get('Time')) else "",
                          status=status_code,
                          message=message,
                      )
                  )
  
          return CircuitDataResponse(
              year=year,
              event_name=str(event['EventName']) if event is not None else "",
              session_name=session_obj.name if hasattr(session_obj, 'name') else session,
              track_status=track_status_list,
              data_type=data_type,
          )

• models/track/track.py:1-49 (schema)

  Pydantic BaseModel definitions for the tool's input parameters (via function signature) and output response (CircuitDataResponse and supporting models).

  from pydantic import BaseModel, Field
  from typing import Optional
  
  
  class CornerInfo(BaseModel):
      """Information about a corner on the circuit."""
  
      number: int = Field(..., description="Corner number")
      letter: Optional[str] = Field(None, description="Corner letter (if applicable)")
      distance: Optional[float] = Field(None, description="Distance from start line in meters")
      x: Optional[float] = Field(None, description="X coordinate")
      y: Optional[float] = Field(None, description="Y coordinate")
  
  
  class CircuitDetails(BaseModel):
      """Detailed circuit information."""
  
      circuit_key: Optional[int] = Field(None, description="Circuit key/ID")
      circuit_name: Optional[str] = Field(None, description="Circuit name")
      location: Optional[str] = Field(None, description="Circuit location")
      country: Optional[str] = Field(None, description="Country")
      rotation: Optional[float] = Field(None, description="Circuit rotation angle")
      corners: Optional[list[CornerInfo]] = Field(None, description="List of corners on the circuit")
  
  
  class TrackStatusInfo(BaseModel):
      """Track status information during a session."""
  
      time: str = Field(..., description="Time of status")
      status: str = Field(..., description="Track status code (1=Green, 2=Yellow, 4=SC, 5=Red, 6=VSC, 7=VSC Ending)")
      message: Optional[str] = Field(None, description="Human-readable status message")
  
  
  class CircuitDataResponse(BaseModel):
      """Response containing circuit and track information."""
  
      year: int = Field(..., description="Season year")
      event_name: str = Field(..., description="Event name")
      session_name: Optional[str] = Field(None, description="Session name (if session-specific)")
  
      # Circuit details
      circuit_details: Optional[CircuitDetails] = Field(None, description="Circuit layout and corner information")
  
      # Track status (session-specific)
      track_status: Optional[list[TrackStatusInfo]] = Field(None, description="Track status changes during session")
  
      # Metadata
      data_type: str = Field(..., description="Type: 'circuit_info' or 'track_status'")

• server.py:165-165 (registration)

  Registration of the get_circuit tool using the FastMCP decorator mcp.tool().

  mcp.tool()(get_circuit)