From 1d37fdfc9a22b9f21d552e6a2d1c01d442e0ef4c Mon Sep 17 00:00:00 2001
From: Greg V <greg.vannoni@gmail.com>
Date: Mon, 30 Mar 2026 11:59:55 -0700
Subject: [PATCH] Add mentor opportunities support to leaderboard API

- Filter mentor_opportunity type from team achievements to prevent mixing
- Add categorize_mentor_opportunities() to extract and serve boost entries
- Return mentorOpportunities in leaderboard analytics response
- Include mentorOpportunities in empty response fallback

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 api/leaderboard/leaderboard_service.py | 35 +++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/api/leaderboard/leaderboard_service.py b/api/leaderboard/leaderboard_service.py
index 4102cee..56d339e 100644
--- a/api/leaderboard/leaderboard_service.py
+++ b/api/leaderboard/leaderboard_service.py
@@ -387,7 +387,8 @@ def categorize_team_achievements(achievements: List[Dict], contributors: List[Di
         List of team achievements
     """
     # Check if there are any team achievements in the achievements list
-    team_achievements = [a for a in achievements if "team" in a and "person" not in a]
+    # Exclude mentor_opportunity entries — those are handled separately
+    team_achievements = [a for a in achievements if "team" in a and "person" not in a and a.get("type") != "mentor_opportunity"]
     
     # If we have team achievements, use them
     if team_achievements:
@@ -480,6 +481,29 @@ def categorize_team_achievements(achievements: List[Dict], contributors: List[Di
     
     return calculated_team_achievements[:4]
 
+def categorize_mentor_opportunities(achievements: List[Dict]) -> List[Dict]:
+    """
+    Extract mentor opportunity entries (teams that could use support).
+
+    Args:
+        achievements: List of achievement objects
+
+    Returns:
+        List of mentor opportunity entries
+    """
+    opportunities = [a for a in achievements if a.get("type") == "mentor_opportunity"]
+
+    # Ensure each entry has required fields
+    for opp in opportunities:
+        if "icon" not in opp:
+            opp["icon"] = "rocket_launch"
+        if "value" not in opp:
+            opp["value"] = "-"
+        if "description" not in opp:
+            opp["description"] = "This team might benefit from some mentor guidance to get rolling!"
+
+    return opportunities
+
 def get_leaderboard_analytics(event_id: str, contributors: List[Dict], achievements: List[Dict]) -> Dict[str, Any]:
     """
     Generate leaderboard analytics including statistics and achievements.
@@ -516,13 +540,15 @@ def get_leaderboard_analytics(event_id: str, contributors: List[Dict], achieveme
     # Process achievements
     individual_achievements = categorize_individual_achievements(achievements)
     team_achievements = categorize_team_achievements(achievements, contributors)
-    
+    mentor_opportunities = categorize_mentor_opportunities(achievements)
+
     return {
         "eventName": event_name,
         "githubOrg": github_org,
         "generalStats": general_stats,
         "individualAchievements": individual_achievements,
-        "teamAchievements": team_achievements
+        "teamAchievements": team_achievements,
+        "mentorOpportunities": mentor_opportunities
     }
 
 def get_github_leaderboard(event_id: str) -> Dict[str, Any]:
@@ -553,7 +579,8 @@ def get_github_leaderboard(event_id: str) -> Dict[str, Any]:
             "github_achievements": [],
             "generalStats": [],
             "individualAchievements": [],
-            "teamAchievements": []
+            "teamAchievements": [],
+            "mentorOpportunities": []
         }
     
     repos_start = time.time()