proper type hinting for tool functions

tools.py

@@ -1,5 +1,5 @@
 """
-Here we implement the MCP tools
+This module provides tools for interacting with Formula 1 data using the FastF1 library.
 
 Tools to implement
 - driver info
@@ -25,8 +25,23 @@ from utils.constants import (
 gp = Union[str, int]
 session_type = Union[str, int, None]
 
+### FastF1 tools ###
+
 def get_session(year: int, round: gp, session_type: session_type) -> Session:
-    """ Returns a session specified by year, round and session type """
+    """Retrieve a specific Formula 1 session.
+    
+    Args:
+        year (int): The season year (e.g., 2024)
+        round (str | int): The race round number or name (e.g., 1 or 'Monaco')
+        session_type (str | int | None): Type of session (e.g., 'FP1', 'Q', 'R')
+        
+    Returns:
+        Session: A FastF1 Session object for the specified parameters
+        
+    Note:
+        If session_type is a string and not in AVAILABLE_SESSION_TYPES,
+        returns an error message string instead.
+    """
 
     # Check if session type is valid
     if isinstance(session_type, str):
@@ -36,12 +51,28 @@ def get_session(year: int, round: gp, session_type: session_type) -> Session:
     return fastf1.get_session(year, round, session_type)
 
 def get_season_calendar(year: int) -> str:
-    """ Returns the season calendar for the given year """
+    """Get the complete race calendar for a specific F1 season.
+    
+    Args:
+        year (int): The season year to get the calendar for
+        
+    Returns:
+        str: Formatted string containing the season calendar
+    """
     season_calendar = fastf1.get_event_schedule(year)
     return parser_utils.parse_season_calendar(season_calendar)
 
 def get_event_info(year: int, round: gp, format: str) -> str:
-    """ Returns the event info for the specified session """
+    """Retrieve information about a specific Formula 1 event.
+    
+    Args:
+        year (int): The season year
+        round (str | int): The race round number or name
+        format (str): Output format ('human' for readable text, 'LLM' for structured data)
+        
+    Returns:
+        str: Formatted event information based on the specified format
+    """
 
     event = fastf1.get_session(year, round, "race").event # Event object is the same for all sessions, so hardcode "race"
     if format == "human":
@@ -53,12 +84,37 @@ def get_event_info(year: int, round: gp, format: str) -> str:
 
 
 def get_constructor_standings(year: int) -> str:
+    """Retrieve constructor championship standings for a given year.
+    
+    Args:
+        year (int): The season year
+        
+    Returns:
+        str: Constructor championship standings
+    """
     pass
 
-def get_driver_standings(year: int) -> str: 
+def get_driver_standings(year: int) -> str:
+    """Retrieve driver championship standings for a given year.
+    
+    Args:
+        year (int): The season year
+        
+    Returns:
+        str: Driver championship standings
+    """
     pass
 
 def driver_championship_standings(year: int, driver_name: str) -> str:
+    """Get the championship standing for a specific driver in a given year.
+    
+    Args:
+        year (int): The season year
+        driver_name (str): Full name of the driver (e.g., 'Lewis Hamilton')
+        
+    Returns:
+        str: Formatted string with driver's position, points, and wins
+    """
 
     with open("assets/driver_abbreviations.json") as f:
         driver_abbreviations = json.load(f)
@@ -72,6 +128,15 @@ def driver_championship_standings(year: int, driver_name: str) -> str:
     return standings_string
     
 def constructor_championship_standings(year: int, constructor_name: str) -> str:
+    """Get the championship standing for a specific constructor in a given year.
+    
+    Args:
+        year (int): The season year
+        constructor_name (str): Name of the constructor team (e.g., 'Mercedes')
+        
+    Returns:
+        str: Formatted string with constructor's position, points, and wins
+    """
 
     team_mapping = {
     "McLaren": "McLaren",
@@ -95,7 +160,18 @@ def constructor_championship_standings(year: int, constructor_name: str) -> str:
     standings_string = f"{constructor_name} are {constructor_standing['position'].iloc[0]}{suffix} with {constructor_standing['points'].iloc[0]} points and {constructor_standing['wins'].iloc[0]} wins"
     return standings_string
 
-def track_visualization(year: int, round: gp, visualization_type: str, driver_name: str) -> Image:
+def track_visualization(year: int, round: gp, visualization_type: str, driver_name: str) -> Image.Image:
+    """Generate a visualization of the track with specified data.
+    
+    Args:
+        year (int): The season year
+        round (str | int): The race round number or name
+        visualization_type (str): Type of visualization ('speed', 'corners', or 'gear')
+        driver_name (str): Name of the driver for driver-specific visualizations
+        
+    Returns:
+        Image.Image: A PIL Image object containing the visualization
+    """
 
     session = get_session(year, round, "race")
     session.load()
@@ -108,6 +184,19 @@ def track_visualization(year: int, round: gp, visualization_type: str, driver_na
         return track_utils.create_track_gear_visualization(session)
 
 def get_session_results(year: int, round: gp, session_type: session_type) -> pd.DataFrame:
+    """Retrieve and format the results of a specific session.
+    
+    Args:
+        year (int): The season year
+        round (str | int): The race round number or name
+        session_type (str | int | None): Type of session (e.g., 'Q', 'R', 'Sprint')
+        
+    Returns:
+        pd.DataFrame: DataFrame containing the session results
+        
+    Raises:
+        gr.Error: If the session type is not supported for the specified round
+    """
 
     try:
         session = get_session(year, round, session_type)
@@ -130,10 +219,23 @@ def get_session_results(year: int, round: gp, session_type: session_type) -> pd.
     return df
 
 def get_driver_info(driver_name: str) -> str:
+    """Retrieve detailed information about a specific driver.
+    
+    Args:
+        driver_name (str): Full name of the driver (e.g., 'Max Verstappen')
+        
+    Returns:
+        str: Formatted string with driver's details including name, team, number,
+             nationality, and a brief summary
+    """
     driver = DRIVER_DETAILS[driver_name]
     driver_info_string = f"{driver_name} ({driver['birth_date']})\n{driver['team']} #{driver['number']}\n{driver['nationality']}\n\n{driver['summary']}"
     return driver_info_string
     
+### OpenF1 tools ###
+
+
+
 
 
 if __name__ == "__main__":