Enhance deployment package with robust API key validation and error handling

Features added:
- API key whitespace trimming and validation
- Startup logging with configuration status display
- Enhanced error messages with step-by-step troubleshooting
- Specific error handling for 401, 429, 400, timeout, and connection errors
- Configuration status accordion that opens when API key not configured
- Better logging for debugging API issues
- HTTP headers for better provider compatibility

app.py

@@ -144,8 +144,38 @@ ENABLE_DYNAMIC_URLS = {enable_dynamic_urls}
 ENABLE_VECTOR_RAG = {enable_vector_rag}
 RAG_DATA = {rag_data_json}
 
-# Get API key from environment - customizable variable name
+# Get API key from environment - customizable variable name with validation
 API_KEY = os.environ.get("{api_key_var}")
+if API_KEY:
+    API_KEY = API_KEY.strip()  # Remove any whitespace
+    if not API_KEY:  # Check if empty after stripping
+        API_KEY = None
+        
+# API Key validation and logging
+def validate_api_key():
+    """Validate API key configuration with detailed logging"""
+    if not API_KEY:
+        print(f"⚠️  API KEY CONFIGURATION ERROR:")
+        print(f"   Variable name: {api_key_var}")
+        print(f"   Status: Not set or empty")
+        print(f"   Action needed: Set '{api_key_var}' in HuggingFace Space secrets")
+        print(f"   Expected format: sk-or-xxxxxxxxxx")
+        return False
+    elif not API_KEY.startswith('sk-or-'):
+        print(f"⚠️  API KEY FORMAT WARNING:")
+        print(f"   Variable name: {api_key_var}")
+        print(f"   Current value: {API_KEY[:10]}..." if len(API_KEY) > 10 else API_KEY)
+        print(f"   Expected format: sk-or-xxxxxxxxxx")
+        print(f"   Note: OpenRouter keys should start with 'sk-or-'")
+        return True  # Still try to use it
+    else:
+        print(f"✅ API Key configured successfully")
+        print(f"   Variable: {api_key_var}")
+        print(f"   Format: Valid OpenRouter key")
+        return True
+
+# Validate on startup
+API_KEY_VALID = validate_api_key()
 
 def fetch_url_content(url):
     """Fetch and extract text content from a URL using requests and BeautifulSoup"""
@@ -261,8 +291,17 @@ else:
 def generate_response(message, history):
     """Generate response using OpenRouter API"""
     
+    # Enhanced API key validation with helpful messages
     if not API_KEY:
-        return "Please set your {api_key_var} in the Space settings."
+        error_msg = f"🔑 **API Key Required**\\n\\n"
+        error_msg += f"Please configure your OpenRouter API key:\\n"
+        error_msg += f"1. Go to Settings (⚙️) in your HuggingFace Space\\n"
+        error_msg += f"2. Click 'Variables and secrets'\\n"
+        error_msg += f"3. Add secret: **{api_key_var}**\\n"
+        error_msg += f"4. Value: Your OpenRouter API key (starts with `sk-or-`)\\n\\n"
+        error_msg += f"Get your API key at: https://openrouter.ai/keys"
+        print(f"❌ API request failed: No API key configured for {api_key_var}")
+        return error_msg
     
     # Get grounding context
     grounding_context = get_grounding_context()
@@ -306,29 +345,105 @@ def generate_response(message, history):
     # Add current message
     messages.append({{"role": "user", "content": message}})
     
-    # Make API request
+    # Make API request with enhanced error handling
     try:
+        print(f"🔄 Making API request to OpenRouter...")
+        print(f"   Model: {{MODEL}}")
+        print(f"   Messages: {{len(messages)}} in conversation")
+        
         response = requests.post(
             url="https://openrouter.ai/api/v1/chat/completions",
             headers={{
                 "Authorization": f"Bearer {{API_KEY}}",
-                "Content-Type": "application/json"
+                "Content-Type": "application/json",
+                "HTTP-Referer": "https://huggingface.co",  # Required by some providers
+                "X-Title": "HuggingFace Space"  # Helpful for tracking
             }},
             json={{
                 "model": MODEL,
                 "messages": messages,
                 "temperature": {temperature},
                 "max_tokens": {max_tokens}
-            }}
+            }},
+            timeout=30
         )
         
+        print(f"📡 API Response: {{response.status_code}}")
+        
         if response.status_code == 200:
-            return response.json()['choices'][0]['message']['content']
+            result = response.json()
+            content = result['choices'][0]['message']['content']
+            print(f"✅ API request successful")
+            return content
+        elif response.status_code == 401:
+            error_msg = f"🔐 **Authentication Error**\\n\\n"
+            error_msg += f"Your API key appears to be invalid or expired.\\n\\n"
+            error_msg += f"**Troubleshooting:**\\n"
+            error_msg += f"1. Check that your **{api_key_var}** secret is set correctly\\n"
+            error_msg += f"2. Verify your API key at: https://openrouter.ai/keys\\n"
+            error_msg += f"3. Ensure your key starts with `sk-or-`\\n"
+            error_msg += f"4. Check that you have credits on your OpenRouter account"
+            print(f"❌ API authentication failed: {{response.status_code}} - {{response.text[:200]}}")
+            return error_msg
+        elif response.status_code == 429:
+            error_msg = f"⏱️ **Rate Limit Exceeded**\\n\\n"
+            error_msg += f"Too many requests. Please wait a moment and try again.\\n\\n"
+            error_msg += f"**Troubleshooting:**\\n"
+            error_msg += f"1. Wait 30-60 seconds before trying again\\n"
+            error_msg += f"2. Check your OpenRouter usage limits\\n"
+            error_msg += f"3. Consider upgrading your OpenRouter plan"
+            print(f"❌ Rate limit exceeded: {{response.status_code}}")
+            return error_msg
+        elif response.status_code == 400:
+            try:
+                error_data = response.json()
+                error_message = error_data.get('error', {{}}).get('message', 'Unknown error')
+            except:
+                error_message = response.text
+            
+            error_msg = f"⚠️ **Request Error**\\n\\n"
+            error_msg += f"The API request was invalid:\\n"
+            error_msg += f"`{{error_message}}`\\n\\n"
+            if "model" in error_message.lower():
+                error_msg += f"**Model Issue:** The model `{{MODEL}}` may not be available.\\n"
+                error_msg += f"Try switching to a different model in your Space configuration."
+            print(f"❌ Bad request: {{response.status_code}} - {{error_message}}")
+            return error_msg
         else:
-            return f"Error: {{response.status_code}} - {{response.text}}"
+            error_msg = f"🚫 **API Error {{response.status_code}}**\\n\\n"
+            error_msg += f"An unexpected error occurred. Please try again.\\n\\n"
+            error_msg += f"If this persists, check:\\n"
+            error_msg += f"1. OpenRouter service status\\n"
+            error_msg += f"2. Your API key and credits\\n"
+            error_msg += f"3. The model availability"
+            print(f"❌ API error: {{response.status_code}} - {{response.text[:200]}}")
+            return error_msg
             
+    except requests.exceptions.Timeout:
+        error_msg = f"⏰ **Request Timeout**\\n\\n"
+        error_msg += f"The API request took too long (30s limit).\\n\\n"
+        error_msg += f"**Troubleshooting:**\\n"
+        error_msg += f"1. Try again with a shorter message\\n"
+        error_msg += f"2. Check your internet connection\\n"
+        error_msg += f"3. Try a different model"
+        print(f"❌ Request timeout after 30 seconds")
+        return error_msg
+    except requests.exceptions.ConnectionError:
+        error_msg = f"🌐 **Connection Error**\\n\\n"
+        error_msg += f"Could not connect to OpenRouter API.\\n\\n"
+        error_msg += f"**Troubleshooting:**\\n"
+        error_msg += f"1. Check your internet connection\\n"
+        error_msg += f"2. Check OpenRouter service status\\n"
+        error_msg += f"3. Try again in a few moments"
+        print(f"❌ Connection error to OpenRouter API")
+        return error_msg
     except Exception as e:
-        return f"Error: {{str(e)}}"
+        error_msg = f"❌ **Unexpected Error**\\n\\n"
+        error_msg += f"An unexpected error occurred:\\n"
+        error_msg += f"`{{str(e)}}`\\n\\n"
+        error_msg += f"Please try again or contact support if this persists."
+        print(f"❌ Unexpected error: {{str(e)}}")
+        return error_msg
 
 # Access code verification
 access_granted = gr.State(False)
@@ -369,11 +484,45 @@ def export_conversation(history):
     
     return gr.update(value=temp_file, visible=True)
 
+# Configuration status display
+def get_configuration_status():
+    \"\"\"Generate a configuration status message for display\"\"\"
+    status_parts = []
+    
+    if API_KEY_VALID:
+        status_parts.append("✅ **API Key:** Configured and valid")
+    else:
+        status_parts.append("❌ **API Key:** Not configured - Set `{api_key_var}` in Space secrets")
+    
+    status_parts.append(f"🤖 **Model:** {{MODEL}}")
+    status_parts.append(f"🌡️ **Temperature:** {temperature}")
+    status_parts.append(f"📝 **Max Tokens:** {max_tokens}")
+    
+    if GROUNDING_URLS:
+        status_parts.append(f"🔗 **URL Grounding:** {{len(GROUNDING_URLS)}} URLs configured")
+    
+    if ENABLE_DYNAMIC_URLS:
+        status_parts.append("🔄 **Dynamic URLs:** Enabled")
+    
+    if ENABLE_VECTOR_RAG:
+        status_parts.append("📚 **Document RAG:** Enabled")
+    
+    if ACCESS_CODE:
+        status_parts.append("🔐 **Access Control:** Enabled")
+    else:
+        status_parts.append("🌐 **Access:** Public")
+    
+    return "\\n".join(status_parts)
+
 # Create interface with access code protection
 with gr.Blocks(title=SPACE_NAME) as demo:
     gr.Markdown(f"# {{SPACE_NAME}}")
     gr.Markdown(SPACE_DESCRIPTION)
     
+    # Configuration status (always visible)
+    with gr.Accordion("📊 Configuration Status", open=not API_KEY_VALID):
+        gr.Markdown(get_configuration_status())
+    
     # Access code section (shown only if ACCESS_CODE is set)
     with gr.Column(visible=bool(ACCESS_CODE)) as access_section:
         gr.Markdown("### 🔐 Access Required")