style: polish SHAP labels and optimize NLP cache retry logic

api/main.py

@@ -160,6 +160,24 @@ def startup_event():
         model_global.load_model(MODEL_PATH)
         expected_cols_global = model_global.feature_names_in_
 
+def _format_feature_label(f: str) -> str:
+    """Converts raw model feature names to boardroom-ready English."""
+    mapping = {
+        'Highest_Market_Value_In_Eur': 'Peak Historical Valuation',
+        'Highest MarketValue In Eur': 'Peak Historical Valuation',
+        'Contract_Years_Left': 'Contractual Duration',
+        'Contract YearsLeft': 'Contractual Duration',
+        'Injury_Days_Total_24m': 'Physical Availability Risk',
+        'Injury Days Total 24M': 'Physical Availability Risk',
+        'League_Index': 'League Quality Index',
+        'height_in_cm': 'Aerial/Physical Profile',
+        'Height In Cm': 'Aerial/Physical Profile',
+        'international_caps': 'International Experience',
+        'market_value_in_eur': 'Baseline Market Valuation',
+    }
+    # Fallback to Title Case with underscores replaced by spaces
+    return mapping.get(f, f.replace('_', ' ').title())
+
 
 # ── NLP Intelligence Cache (TTL = 1 hour) ────────────────────────────────────
 # Fixed: previously ran 3 live DDGS searches on every API call — caused
@@ -178,8 +196,16 @@ def _fetch_nlp_intelligence(
     """
     cache_key = f"{player_name.lower()}|{current_club.lower()}"
     cached = _nlp_cache.get(cache_key)
-    if cached and (time.time() - cached.get('_ts', 0)) < _NLP_CACHE_TTL:
-        return {**cached, '_from_cache': True}
+    
+    # Logic: If we have a cached result with real data, keep it for 1 hour.
+    # If the cached result was "Empty" (no news found), allow a retry after 5 mins.
+    if cached:
+        age = time.time() - cached.get('_ts', 0)
+        has_signals = cached.get('_found_any', False)
+        
+        if age < _NLP_CACHE_TTL:
+            if has_signals or age < 300: # 300s = 5 mins
+                return {**cached, '_from_cache': True}
 
     ddgs = DDGS()
     axes = {
@@ -327,7 +353,7 @@ async def evaluate_player(req: PlayerEvaluateRequest):
     # ── SHAP Feature Contribution Table ──────────────────────────────────────
     shap_data = sorted(
         [
-            {"feature": f.replace('_', ' ').title(), "impact": float(s)}
+            {"feature": _format_feature_label(f), "impact": float(s)}
             for f, s in zip(expected_cols_global, feature_shaps)
         ],
         key=lambda x: abs(x['impact']),