Improve API error handling and add setup instructions

- Add visible warning banner when API key not configured
- Better error messages for auth, rate limit, and connection errors
- Clear setup instructions for users
- Cleaner startup logging

app.py

@@ -6,14 +6,18 @@ import gradio as gr
 import anthropic
 import os
 
-# Debug: Print env var names containing relevant keywords at startup
-print("=== STARTUP: Checking for API key ===")
-relevant_keys = [k for k in os.environ.keys() if any(x in k.lower() for x in ['api', 'key', 'anthrop', 'secret', 'token'])]
-print(f"  Relevant env var NAMES found: {relevant_keys}")
-api_key = os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("anthropic_key")
-print(f"  ANTHROPIC_API_KEY exists: {bool(os.environ.get('ANTHROPIC_API_KEY'))}")
-print(f"  anthropic_key exists: {bool(os.environ.get('anthropic_key'))}")
-print("=== END STARTUP CHECK ===")
+# Check for API key at startup
+def check_api_key():
+    """Check if API key is configured"""
+    return bool(
+        os.environ.get("ANTHROPIC_API_KEY") or
+        os.environ.get("anthropic_key") or
+        os.environ.get("ANTHROPIC_KEY") or
+        os.environ.get("anthropic_api_key")
+    )
+
+API_KEY_CONFIGURED = check_api_key()
+print(f"=== STARTUP: API key configured: {API_KEY_CONFIGURED} ===")
 
 # ============ CONSTANTS ============
 
@@ -574,10 +578,7 @@ def call_claude(system_prompt, messages, context=""):
     client = get_client()
 
     if client is None:
-        # Show helpful message about which env vars we checked
-        checked = ["ANTHROPIC_API_KEY", "anthropic_key", "ANTHROPIC_KEY", "anthropic_api_key"]
-        available = [k for k in os.environ.keys() if 'key' in k.lower() or 'api' in k.lower() or 'anthrop' in k.lower()]
-        return f"API key not found. Checked: {checked}. Found env vars containing 'key'/'api'/'anthrop': {available}. Please add ANTHROPIC_API_KEY in Space Settings > Repository secrets, then restart the Space."
+        return None  # Return None to indicate API not available
 
     if context:
         user_content = f"{context}\n\nUser message: {messages[-1]['content']}" if messages else context
@@ -595,6 +596,18 @@ def call_claude(system_prompt, messages, context=""):
 
 # ============ STAGE PROCESSING ============
 
+API_ERROR_MESSAGE = """**API Configuration Required**
+
+To use this NVC practice tool, the Space owner needs to add an Anthropic API key:
+
+1. Go to **Settings** (gear icon) in this Space
+2. Click **Repository secrets**
+3. Add a new secret named `ANTHROPIC_API_KEY`
+4. Paste your API key from [console.anthropic.com](https://console.anthropic.com)
+5. **Restart the Space** (Factory reboot)
+
+If you're the Space owner and have already added the key, try restarting the Space."""
+
 def process_stage(user_input, stage, session_data, somatic_enabled):
     """Process current stage and return response"""
 
@@ -610,8 +623,20 @@ def process_stage(user_input, stage, session_data, somatic_enabled):
             [{"role": "user", "content": user_input}],
             context
         )
+
+        # Check if API key was not configured
+        if response is None:
+            return "", stage, session_data, API_ERROR_MESSAGE
+
+    except anthropic.AuthenticationError:
+        return "", stage, session_data, "**Invalid API Key** - The API key appears to be invalid. Please check that you've entered a valid Anthropic API key in the Space secrets."
+    except anthropic.RateLimitError:
+        return "", stage, session_data, "**Rate Limited** - Too many requests. Please wait a moment and try again."
+    except anthropic.APIConnectionError:
+        return "", stage, session_data, "**Connection Error** - Unable to connect to the Anthropic API. Please try again in a moment."
     except Exception as e:
-        return "", stage, session_data, f"Error calling Claude: {str(e)}"
+        error_type = type(e).__name__
+        return "", stage, session_data, f"**Error** ({error_type}): {str(e)}"
 
     session_data = update_session_data(stage, user_input, session_data)
     next_stage = stage + 1 if stage < 13 else 1
@@ -866,6 +891,17 @@ def create_app():
         </div>
         """)
 
+        # Show warning if API key not configured
+        if not API_KEY_CONFIGURED:
+            gr.HTML("""
+            <div style="background: #FEF3C7; border: 2px solid #F59E0B; border-radius: 12px; padding: 1rem 1.5rem; margin-bottom: 1.5rem;">
+                <p style="color: #92400E; margin: 0; font-weight: 500;">
+                    <strong>Setup Required:</strong> This Space needs an Anthropic API key to function.
+                    If you're the owner, go to Settings > Repository secrets > Add <code>ANTHROPIC_API_KEY</code>, then restart the Space.
+                </p>
+            </div>
+            """)
+
         gr.HTML("""
         <div class="intro-text">
             Write a raw message you want to send someone. This practice will guide you through

requirements.txt

@@ -1,2 +1,2 @@
-gradio==5.9.1
+gradio>=5.12.0
 anthropic>=0.18.0