Update main.py

main.py

@@ -715,7 +715,7 @@ def get_available_seasons_util(num_seasons=6):
     current_year = datetime.now().year
     current_month = datetime.now().month
     latest_season_end_year = current_year
-    if current_month >= 7:
+    if current_month >= 7: # Assuming season flips around July
         latest_season_end_year += 1
     seasons_list = []
     for i in range(num_seasons):
@@ -750,16 +750,17 @@ def get_player_index_brscraper():
         return df
 
 def _scrape_player_index_brscraper():
-    seasons_to_try_for_index = get_available_seasons_util(num_seasons=2)
+    seasons_to_try_for_index = get_available_seasons_util(num_seasons=2) # Try last 2 completed/current seasons
     
     for season_str in seasons_to_try_for_index:
         end_year = int(season_str.split('–')[1])
         try:
             logging.info(f"Attempting to get player index for year: {end_year} from BRScraper...")
-            df = nba.get_stats(end_year, info='per_game', rename=False)
+            df = nba.get_stats(end_year, info='per_game', rename=False) # Get per_game stats for the season
             
             if not df.empty and 'Player' in df.columns:
                 player_names = df['Player'].dropna().unique().tolist()
+                # Normalize names immediately after fetching
                 player_names = [normalize_string(name) for name in player_names]
                 logging.info(f"Successfully retrieved {len(player_names)} players for index from {season_str}.")
                 return pd.DataFrame({'name': player_names})
@@ -771,13 +772,13 @@ def _scrape_player_index_brscraper():
     logging.error("Failed to fetch player index from recent seasons. Falling back to curated common players list.")
     common_players = [
         'LeBron James', 'Stephen Curry', 'Kevin Durant', 'Giannis Antetokounmpo',
-        'Nikola Jokic',
-        'Joel Embiid', 'Jayson Tatum', 'Luka Doncic',
+        'Nikola Jokic', # Added
+        'Joel Embiid', 'Jayson Tatum', 'Luka Doncic', # Added
         'Damian Lillard', 'Jimmy Butler', 'Kawhi Leonard', 'Paul George',
         'Anthony Davis', 'Rudy Gobert', 'Donovan Mitchell', 'Trae Young',
         'Devin Booker', 'Karl-Anthony Towns', 'Zion Williamson', 'Ja Morant',
-        'Shai Gilgeous-Alexander', 'Tyrese Maxey', 'Anthony Edwards', 'Victor Wembanyama',
-        'Jalen Brunson', 'Paolo Banchero', 'Franz Wagner', 'Cade Cunningham'
+        'Shai Gilgeous-Alexander', 'Tyrese Maxey', 'Anthony Edwards', 'Victor Wembanyama', # Added
+        'Jalen Brunson', 'Paolo Banchero', 'Franz Wagner', 'Cade Cunningham' # Added
     ]
     return pd.DataFrame({'name': common_players})
 
@@ -786,33 +787,36 @@ def get_player_career_stats_brscraper(player_name, seasons_to_fetch: list[str],
         logging.error("BRScraper is not available. Cannot fetch player career stats.")
         return pd.DataFrame()
     
-    normalized_player_name = normalize_string(player_name)
+    normalized_player_name = normalize_string(player_name) # Normalize input player name once
     all_rows = []
 
     for season_str in seasons_to_fetch:
         end_year = int(season_str.split('–')[1])
         
+        # Define cache key based on normalized name, year, and playoff status
         cache_key = f"{normalized_player_name}_{end_year}_{'playoffs' if playoffs else 'regular'}"
         db_ref = db.reference(f'scraped_data/player_season_stats/{cache_key}')
 
         if FIREBASE_INITIALIZED:
             cached_data = db_ref.get()
-            if cached_data and not is_data_stale(cached_data.get('last_updated'), max_age_hours=24*7):
+            if cached_data and not is_data_stale(cached_data.get('last_updated'), max_age_hours=24*7): # Cache for 7 days
                 logging.info(f"Loading stats for {player_name} in {season_str} (playoffs: {playoffs}) from Firebase cache.")
                 all_rows.append(pd.DataFrame.from_records(cached_data['data']))
                 continue # Skip scraping for this season if found in cache
             else:
                 logging.info(f"Stats for {player_name} in {season_str} cache stale or not found. Scraping...")
 
-        for attempt in range(3):
+        # Retry mechanism for scraping
+        for attempt in range(3): # Try up to 3 times
             try:
                 logging.info(f"DEBUG: Attempt {attempt+1} for nba.get_stats for player '{player_name}' in season {season_str} (year: {end_year}, playoffs: {playoffs})...")
                 
+                # Fetch all player stats for the given season and type (regular/playoffs)
                 df_season = nba.get_stats(end_year, info='per_game', playoffs=playoffs, rename=False)
                 
                 if df_season.empty:
                     logging.warning(f"DEBUG: nba.get_stats returned empty DataFrame for {player_name} in {season_str} on attempt {attempt+1}. Retrying...")
-                    time.sleep(1)
+                    time.sleep(1) # Wait before retrying
                     continue 
                 
                 if 'Player' not in df_season.columns:
@@ -820,13 +824,14 @@ def get_player_career_stats_brscraper(player_name, seasons_to_fetch: list[str],
                     time.sleep(1)
                     continue
 
+                # Normalize player names from the scraped data for matching
                 df_season['Player_Normalized'] = df_season['Player'].apply(normalize_string)
                 row = df_season[df_season['Player_Normalized'] == normalized_player_name]
                 
                 if not row.empty:
-                    row = row.copy()
-                    row['Season'] = season_str
-                    row = row.drop(columns=['Player_Normalized'], errors='ignore')
+                    row = row.copy() # Avoid SettingWithCopyWarning
+                    row['Season'] = season_str # Add the season string
+                    row = row.drop(columns=['Player_Normalized'], errors='ignore') # Drop helper column
                     
                     if FIREBASE_INITIALIZED:
                         df_cleaned_for_firebase = clean_df_for_firebase(row.copy())
@@ -838,20 +843,23 @@ def get_player_career_stats_brscraper(player_name, seasons_to_fetch: list[str],
                     
                     all_rows.append(row)
                     logging.info(f"DEBUG: Found stats for {player_name} in {season_str} on attempt {attempt+1}. Appending row.")
-                    break
+                    break # Success, exit retry loop for this season
                 else:
+                    # This case means the season data was fetched, but the specific player wasn't in it.
                     logging.info(f"DEBUG: Player {player_name} not found in {season_str} stats (after getting season data) on attempt {attempt+1}. Retrying...")
                     time.sleep(1)
+                    # If player not found after fetching season data, retrying might not help unless BRScraper has intermittent issues.
+                    # Consider breaking if player not found in a valid scrape. For now, let it retry.
                     continue
 
             except Exception as e:
                 logging.warning(f"DEBUG: Exception on attempt {attempt+1} when fetching {season_str} {'playoff' if playoffs else 'regular season'} stats for {player_name}: {e}")
-                time.sleep(1)
-                if attempt == 2:
+                time.sleep(1) # Wait before retrying
+                if attempt == 2: # Last attempt failed
                     logging.error(f"DEBUG: All 3 attempts failed for {player_name} in {season_str}. Giving up on this season.")
-                continue
+                continue # Go to next attempt or next season if all attempts failed
 
-        time.sleep(0.5) # Delay between seasons
+        time.sleep(0.5) # Small delay between fetching different seasons to be polite to the server
         
     if not all_rows:
         logging.warning(f"DEBUG: No stats found for {player_name} in the requested seasons: {seasons_to_fetch}. Returning empty DataFrame.")
@@ -859,6 +867,7 @@ def get_player_career_stats_brscraper(player_name, seasons_to_fetch: list[str],
     
     df = pd.concat(all_rows, ignore_index=True)
 
+    # Standardize column names
     mapping = {
         'G':'GP','GS':'GS','MP':'MIN', 'FG%':'FG_PCT','3P%':'FG3_PCT','FT%':'FT_PCT',
         'TRB':'REB','AST':'AST','STL':'STL','BLK':'BLK','TOV':'TO',
@@ -869,13 +878,14 @@ def get_player_career_stats_brscraper(player_name, seasons_to_fetch: list[str],
     }
     df = df.rename(columns={o:n for o,n in mapping.items() if o in df.columns})
 
-    non_num = {'Season','Player','Tm','Lg','Pos'}
+    # Convert stats to numeric, coercing errors
+    non_num = {'Season','Player','Tm','Lg','Pos'} # Columns that should remain non-numeric
     for col in df.columns:
         if col not in non_num:
             df[col] = pd.to_numeric(df[col], errors='coerce')
 
-    df['Player'] = player_name
-    df = df.replace({np.nan: None})
+    df['Player'] = player_name # Ensure original (non-normalized) player name is in the final DataFrame
+    df = df.replace({np.nan: None}) # Replace NaN with None for JSON compatibility
     return df
 
 def get_dashboard_info_brscraper():
@@ -896,7 +906,7 @@ def get_dashboard_info_brscraper():
     else:
         logging.info("Scraping dashboard info (cache stale or not found).")
         data = _scrape_dashboard_info_brscraper()
-        if data:
+        if data: # Only cache if data was successfully scraped
             db_ref.set({
                 'last_updated': datetime.utcnow().isoformat(),
                 'data': data
@@ -907,27 +917,29 @@ def get_dashboard_info_brscraper():
 def _scrape_dashboard_info_brscraper():
     dashboard_data = {}
     try:
+        # Attempt to get MVP votings for 2025 (likely to be empty or error if too early)
         mvp_2025_df = nba.get_award_votings('mvp', 2025)
         if not mvp_2025_df.empty:
-            if 'Share' in mvp_2025_df.columns:
+            if 'Share' in mvp_2025_df.columns: # Standardize 'Share' to 'Votes'
                 mvp_2025_df = mvp_2025_df.rename(columns={'Share': 'Votes'})
-            if 'Votes' in mvp_2025_df.columns:
+            if 'Votes' in mvp_2025_df.columns: # Convert votes to percentage if it's a decimal
                 mvp_2025_df['Votes'] = pd.to_numeric(mvp_2025_df['Votes'], errors='coerce') * 100
             
             mvp_2025_df = clean_df_for_firebase(mvp_2025_df)
             dashboard_data['mvp_2025_votings'] = mvp_2025_df.replace({np.nan: None}).to_dict(orient='records')
         else:
-            dashboard_data['mvp_2025_votings'] = []
+            dashboard_data['mvp_2025_votings'] = [] # Ensure key exists even if no data
             logging.warning("Could not retrieve 2025 MVP votings.")
 
+        # Playoff probabilities
         east_probs_df = nba.get_playoffs_probs('east')
         if not east_probs_df.empty:
             if 'Eastern Conference' in east_probs_df.columns:
                 east_probs_df = east_probs_df.rename(columns={'Eastern Conference': 'Team'})
-            elif 'Tm' in east_probs_df.columns:
+            elif 'Tm' in east_probs_df.columns: # Fallback if column name is 'Tm'
                 east_probs_df = east_probs_df.rename(columns={'Tm': 'Team'})
             
-            if 'Team' in east_probs_df.columns:
+            if 'Team' in east_probs_df.columns: # Clean team names
                 east_probs_df['Team'] = east_probs_df['Team'].astype(str).apply(clean_team_name)
 
             east_probs_df = clean_df_for_firebase(east_probs_df)
@@ -984,23 +996,23 @@ def ask_perp(prompt, system=NBA_ANALYST_SYSTEM_PROMPT, max_tokens=1000, temp=0.2
     }
 
     payload = {
-        "model": "sonar-pro",
+        "model": "sonar-pro", # Ensure this model is appropriate and available
         "messages": [
             {"role": "system", "content": system},
-            {"role": "user", "content": f"BASKETBALL ONLY: {prompt}"}
+            {"role": "user", "content": f"BASKETBALL ONLY: {prompt}"} # Reinforce context
         ],
         "max_tokens": max_tokens,
         "temperature": temp,
-        "web_search_options": {
-            "search_context_size": "high",
-            "search_domain_filter": ["nba.com", "espn.com", "basketball-reference.com"]
+        "web_search_options": { # Added web search options for more current data
+            "search_context_size": "high", # "low", "medium", "high"
+            "search_domain_filter": ["nba.com", "espn.com", "basketball-reference.com"] # Focus search
         },
-        "emit_sources": True
+        "emit_sources": True # Request sources if available
     }
 
     try:
-        response = requests.post(PERP_URL, json=payload, headers=headers, timeout=45)
-        response.raise_for_status()
+        response = requests.post(PERP_URL, json=payload, headers=headers, timeout=45) # Increased timeout
+        response.raise_for_status() # Will raise HTTPError for bad responses (4XX, 5XX)
         return response.json().get("choices", [])[0].get("message", {}).get("content", "")
     except requests.exceptions.RequestException as e:
         error_message = f"Error communicating with Perplexity API: {e}"
@@ -1008,11 +1020,11 @@ def ask_perp(prompt, system=NBA_ANALYST_SYSTEM_PROMPT, max_tokens=1000, temp=0.2
             try:
                 error_detail = e.response.json().get("error", {}).get("message", e.response.text)
                 error_message = f"Perplexity API error: {e.response.status_code} - {e.response.reason}"
-            except ValueError:
+            except ValueError: # If response is not JSON
                 error_message = f"Perplexity API error: {e.response.status_code} - {e.response.reason}"
         logging.error(f"Perplexity API request failed: {error_message}")
         return f"Error from AI: {error_message}"
-    except Exception as e:
+    except Exception as e: # Catch any other unexpected errors
         logging.error(f"An unexpected error occurred with Perplexity API: {e}")
         return f"An unexpected error occurred with AI: {str(e)}"
 
@@ -1103,11 +1115,15 @@ def get_player_stats():
 
         comparison_df_raw = pd.concat(all_player_season_data, ignore_index=True)
 
+        # Basic stats for display
         basic_display_df = comparison_df_raw.copy()
         basic_cols = ['Player', 'Season', 'GP', 'MIN', 'PTS', 'REB', 'AST', 'STL', 'BLK', 'FG_PCT', 'FT_PCT', 'FG3_PCT']
+        # Ensure only existing columns are selected and then round
         basic_display_df = basic_display_df[[c for c in basic_cols if c in basic_display_df.columns]].round(2)
 
+        # Advanced stats calculation (e.g., TS%)
         advanced_df = comparison_df_raw.copy()
+        # Ensure necessary columns for TS% are numeric and handle potential missing columns
         advanced_df['FGA'] = pd.to_numeric(advanced_df.get('FGA', 0), errors='coerce').fillna(0)
         advanced_df['FTA'] = pd.to_numeric(advanced_df.get('FTA', 0), errors='coerce').fillna(0)
         advanced_df['PTS'] = pd.to_numeric(advanced_df.get('PTS', 0), errors='coerce').fillna(0)
@@ -1115,7 +1131,7 @@ def get_player_stats():
             lambda r: r['PTS'] / (2 * (r['FGA'] + 0.44 * r['FTA'])) if (r['FGA'] + 0.44 * r['FTA']) else 0,
             axis=1
         )
-        advanced_cols = ['Player', 'Season', 'PTS', 'REB', 'AST', 'FG_PCT', 'TS_PCT']
+        advanced_cols = ['Player', 'Season', 'PTS', 'REB', 'AST', 'FG_PCT', 'TS_PCT'] # Example advanced stats
         advanced_display_df = advanced_df[[c for c in advanced_cols if c in advanced_df.columns]].round(3)
 
         return jsonify({
@@ -1141,6 +1157,7 @@ def get_player_playoff_stats():
         all_player_season_data = []
         players_with_no_data = []
 
+        # Handle individual player stats (1 player, 1 season)
         if len(selected_players) == 1 and len(selected_seasons) == 1:
             player_name = selected_players[0]
             season_str = selected_seasons[0]
@@ -1153,6 +1170,7 @@ def get_player_playoff_stats():
                 players_with_no_data.append(player_name)
                 logging.info(f"No playoff data found for {player_name} in {season_str}.")
 
+        # Handle comparison (2 players, 2 seasons)
         elif len(selected_players) == 2 and len(selected_seasons) == 2:
             player1_name = selected_players[0]
             player1_season = selected_seasons[0]
@@ -1219,8 +1237,8 @@ def get_team_stats():
     logging.info("DEBUG: Request successfully entered get_team_stats function!")
     try:
         data = request.get_json()
-        selected_teams_abbrs = data.get('teams')
-        selected_season_str = data.get('season')
+        selected_teams_abbrs = data.get('teams') # Expecting list of abbreviations e.g., ['LAL', 'BOS']
+        selected_season_str = data.get('season') # Expecting "YYYY-YY" format
 
         if not selected_teams_abbrs or not selected_season_str:
             return jsonify({'error': 'Teams and season are required'}), 400
@@ -1231,6 +1249,7 @@ def get_team_stats():
         if tm_df.empty:
             return jsonify({'error': f'No team data available for {selected_season_str}'}), 404
 
+        # Map abbreviations to full names for lookup in BRScraper data
         full_team_names_map = {
             "ATL": "Atlanta Hawks", "BOS": "Boston Celtics", "BRK": "Brooklyn Nets",
             "CHO": "Charlotte Hornets", "CHI": "Chicago Bulls", "CLE": "Cleveland Cavaliers",
@@ -1249,12 +1268,14 @@ def get_team_stats():
         teams_with_no_data = []
 
         for team_full_name_lookup in selected_teams_full_names:
-            df_row = tm_df[tm_df.Team == team_full_name_lookup].copy()
+            # Match on the 'Team' column which should have full names after cleaning
+            df_row = tm_df[tm_df.Team == team_full_name_lookup].copy() # Use .copy()
             if not df_row.empty:
                 df_dict = df_row.iloc[0].to_dict()
-                df_dict['Season'] = selected_season_str
+                df_dict['Season'] = selected_season_str # Add season back
                 stats.append(df_dict)
             else:
+                # Find original abbreviation if lookup failed
                 original_abbr = next((abbr for abbr, name in full_team_names_map.items() if name == team_full_name_lookup), team_full_name_lookup)
                 teams_with_no_data.append(original_abbr)
 
@@ -1265,10 +1286,11 @@ def get_team_stats():
             }), 404
 
         comp = pd.DataFrame(stats)
-        for col in ['WINS', 'LOSSES', 'WIN_LOSS_PCT', 'RANK']:
+        # Ensure key stats are numeric
+        for col in ['WINS', 'LOSSES', 'WIN_LOSS_PCT', 'RANK']: # Add other numeric stats if needed
             if col in comp.columns:
                 comp[col] = pd.to_numeric(comp[col], errors='coerce')
-        comp = comp.replace({np.nan: None})
+        comp = comp.replace({np.nan: None}) # For JSON compatibility
 
         return jsonify({
             'team_stats': comp.to_dict(orient='records'),
@@ -1279,7 +1301,7 @@ def get_team_stats():
         return jsonify({'error': str(e)}), 500
 
 @app.route('/api/nba/dashboard_info', methods=['GET'])
-@credit_required(cost=0)
+@credit_required(cost=0) # No cost for dashboard info
 @cross_origin()
 def dashboard_info():
     if not FIREBASE_INITIALIZED:
@@ -1288,7 +1310,7 @@ def dashboard_info():
 
     try:
         dashboard_data = get_dashboard_info_brscraper()
-        if not dashboard_data:
+        if not dashboard_data: # Check if the dictionary itself is empty
             return jsonify({'error': 'Could not retrieve dashboard information.'}), 500
         return jsonify(dashboard_data)
     except Exception as e:
@@ -1311,16 +1333,18 @@ def perplexity_explain():
             return jsonify({'error': 'Prompt is required'}), 400
         
         explanation = ask_perp(prompt)
-        if "Error from AI" in explanation:
+        if "Error from AI" in explanation: # Check for specific error message from ask_perp
             return jsonify({'error': explanation}), 500
         
+        # Store analysis if Firebase is up
         auth_header = request.headers.get('Authorization', '')
         token = auth_header.split(' ')[1]
         uid = verify_token(token)
 
+        analysis_id = str(uuid.uuid4()) # Generate ID regardless of Firebase status for return
+
         if FIREBASE_INITIALIZED:
             user_analyses_ref = db.reference(f'user_analyses/{uid}')
-            analysis_id = str(uuid.uuid4())
             analysis_data = {
                 'prompt': prompt,
                 'explanation': explanation,
@@ -1337,7 +1361,7 @@ def perplexity_explain():
         return jsonify({'error': str(e)}), 500
 
 @app.route('/api/user/analyses', methods=['GET'])
-@credit_required(cost=0)
+@credit_required(cost=0) # No cost to view own analyses
 @cross_origin()
 def get_user_analyses():
     if not FIREBASE_INITIALIZED:
@@ -1349,7 +1373,7 @@ def get_user_analyses():
         token = auth_header.split(' ')[1]
         uid = verify_token(token)
 
-        if not FIREBASE_INITIALIZED:
+        if not FIREBASE_INITIALIZED: # Double check, though credit_required should handle
             return jsonify({'error': 'Firebase not initialized. Cannot retrieve analyses.'}), 500
 
         user_analyses_ref = db.reference(f'user_analyses/{uid}')
@@ -1364,6 +1388,7 @@ def get_user_analyses():
                 'created_at': data.get('created_at')
             })
         
+        # Sort by creation date, newest first
         analyses_list.sort(key=lambda x: x.get('created_at', ''), reverse=True)
 
         return jsonify({'analyses': analyses_list})
@@ -1372,7 +1397,7 @@ def get_user_analyses():
         return jsonify({'error': str(e)}), 500
 
 @app.route('/api/user/analyses/<string:analysis_id>', methods=['DELETE'])
-@credit_required(cost=0)
+@credit_required(cost=0) # No cost to delete own analysis
 @cross_origin()
 def delete_user_analysis(analysis_id):
     if not FIREBASE_INITIALIZED:
@@ -1388,7 +1413,7 @@ def delete_user_analysis(analysis_id):
             return jsonify({'error': 'Firebase not initialized. Cannot delete analysis.'}), 500
 
         analysis_ref = db.reference(f'user_analyses/{uid}/{analysis_id}')
-        analysis_data = analysis_ref.get()
+        analysis_data = analysis_ref.get() # Check if it exists before deleting
 
         if not analysis_data:
             return jsonify({'error': 'Analysis not found or does not belong to this user'}), 404
@@ -1418,14 +1443,15 @@ def perplexity_chat():
         
         auth_header = request.headers.get('Authorization', '')
         token = auth_header.split(' ')[1]
-        uid = verify_token(token)
+        uid = verify_token(token) # Get UID for chat history
 
         response_content = ask_perp(prompt)
         if "Error from AI" in response_content:
             return jsonify({'error': response_content}), 500
         
+        # Store chat history if Firebase is up
         if FIREBASE_INITIALIZED:
-            user_chat_ref = db.reference(f'users/{uid}/chat_history')
+            user_chat_ref = db.reference(f'users/{uid}/chat_history') # Store under user's profile
             user_chat_ref.push({
                 'role': 'user',
                 'content': prompt,
@@ -1455,8 +1481,8 @@ def awards_predictor():
 
     try:
         data = request.get_json()
-        award_type = data.get('award_type')
-        criteria = data.get('criteria')
+        award_type = data.get('award_type') # e.g., "MVP", "Rookie of the Year"
+        criteria = data.get('criteria') # e.g., "early season performance", "team success"
         
         if not award_type or not criteria:
             return jsonify({'error': 'Award type and criteria are required'}), 400
@@ -1519,7 +1545,7 @@ def similar_players():
     try:
         data = request.get_json()
         target_player = data.get('target_player')
-        criteria = data.get('criteria')
+        criteria = data.get('criteria') # Expecting a list of strings
 
         if not target_player or not criteria:
             return jsonify({'error': 'Target player and criteria are required'}), 400
@@ -1529,6 +1555,7 @@ def similar_players():
         if "Error from AI" in similar_players_analysis:
             return jsonify({'error': similar_players_analysis}), 500
         
+        # Store analysis
         auth_header = request.headers.get('Authorization', '')
         token = auth_header.split(' ')[1]
         uid = verify_token(token)
@@ -1538,10 +1565,10 @@ def similar_players():
         if FIREBASE_INITIALIZED:
             user_analyses_ref = db.reference(f'user_analyses/{uid}')
             analysis_data = {
-                'type': 'similar_players',
+                'type': 'similar_players', # Add a type for easier filtering later if needed
                 'target_player': target_player,
                 'criteria': criteria,
-                'prompt': prompt,
+                'prompt': prompt, # Store the exact prompt for record
                 'explanation': similar_players_analysis,
                 'created_at': datetime.utcnow().isoformat()
             }
@@ -1567,16 +1594,18 @@ def manual_player_compare():
     try:
         data = request.get_json()
         player1_name = data.get('player1_name')
-        player1_season = data.get('player1_season')
+        player1_season = data.get('player1_season') # Optional
         player2_name = data.get('player2_name')
-        player2_season = data.get('player2_season')
+        player2_season = data.get('player2_season') # Optional
 
         if not player1_name or not player2_name:
             return jsonify({'error': 'Both player names are required'}), 400
 
+        # Construct player strings for the prompt
         player1_str = f"{player1_name} ({player1_season} season)" if player1_season else player1_name
         player2_str = f"{player2_name} ({player2_season} season)" if player2_season else player2_name
 
+        # Define comparison context based on provided seasons
         comparison_context = "Statistical comparison"
         if player1_season and player2_season:
             comparison_context += f" (specifically {player1_season} vs {player2_season} seasons)"