fix: Improved agent diagnostics for API troubleshooting

backend/app/services/llm.py

@@ -114,8 +114,19 @@ def generate_mock_analysis(tender: Tender, company: CompanyProfile) -> AnalysisR
     )
 
 def generate_analysis(tender: Tender, company: CompanyProfile, document_text: str | None = None) -> AnalysisResult:
+    if not settings.gemini_api_key:
+        analysis = generate_mock_analysis(tender, company)
+        analysis.audit_log = ["⚠️ Error: GEMINI_API_KEY is not configured.", "Fallback: Using deterministic mock analysis."]
+        return analysis
+
     prompt = _build_analysis_prompt(tender, company, document_text)
     output = call_gemini(prompt)
+    
+    if not output:
+        analysis = generate_mock_analysis(tender, company)
+        analysis.audit_log = ["❌ Error: Gemini API returned an empty response.", "Check quota or region restrictions.", "Fallback: Using mock analysis."]
+        return analysis
+
     parse_result = _parse_gemini_response(output)
     
     if parse_result:
@@ -125,7 +136,11 @@ def generate_analysis(tender: Tender, company: CompanyProfile, document_text: st
             return AnalysisResult(**parse_result)
         except Exception as e:
             print(f"Error mapping to AnalysisResult: {e}")
+            error_msg = f"🔍 Data Mapping Error: {str(e)[:50]}..."
+    else:
+        error_msg = "🧩 Format Error: Gemini response was not valid JSON."
     
     analysis = generate_mock_analysis(tender, company)
-    analysis.audit_log.append("Fallback: Gemini no retornó un análisis válido.")
+    analysis.audit_log.append(error_msg)
+    analysis.audit_log.append("Fallback: Reverting to system default analysis.")
     return analysis