Fix HF Spaces initialization and add comprehensive diagnostics

This commit addresses the root cause of the "Failed to initialize LLM client" error
on Hugging Face Spaces with multiple improvements:

1. **Updated requirements.txt for HF Spaces compatibility**
- Upgraded anthropic from 0.18.1 to >=0.34.0 (modern API support)
- Added explicit httpx>=0.24.0 dependency
- Fixes version mismatch causing initialization failures

2. **Made AnthropicClient backward compatible**
- Added version detection for http_client parameter
- Graceful fallback for older SDK versions
- Better error handling with informative messages

3. **Added API key validation**
- Validates API key format (must start with 'sk-ant-')
- Provides clear error messages for invalid keys
- Helps users quickly identify configuration issues

4. **Enhanced diagnostics in web UI**
- Added expandable System Diagnostics panel in sidebar
- Shows API key status, package versions, and system info
- Displays detailed error tracebacks for debugging
- Auto-selects Local Be.FM when no API key detected

5. **Created comprehensive HF Spaces setup guide**
- Step-by-step instructions for configuring secrets
- Troubleshooting section for common issues
- Alternative options (Local Be.FM model)

These changes ensure the app works correctly on HF Spaces with proper error
reporting and clear guidance for users to fix configuration issues.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

HF_SPACES_SETUP.md

@@ -0,0 +1,91 @@
+# Hugging Face Spaces Setup Guide
+
+This guide explains how to properly configure your AI Personas app on Hugging Face Spaces.
+
+## Required Configuration
+
+### 1. Add Anthropic API Key to Secrets
+
+Your Anthropic API key must be added to your Space's secrets:
+
+1. Go to your Space's page on Hugging Face
+2. Click on **Settings** (gear icon)
+3. Navigate to **Variables and secrets** section
+4. Click **Add a new secret**
+5. Enter:
+   - **Name:** `ANTHROPIC_API_KEY`
+   - **Value:** Your Anthropic API key (starts with `sk-ant-`)
+6. Click **Save**
+7. Restart your Space
+
+### 2. Verify API Key Format
+
+Make sure your API key:
+- Starts with `sk-ant-`
+- Has no extra spaces or quotes
+- Is a valid, non-expired key
+
+You can get an API key from: https://console.anthropic.com/
+
+### 3. Check the Diagnostics
+
+Once deployed, check the **🔍 System Diagnostics** section in the sidebar:
+- Should show "✓ Found" for API Key Status
+- Should show your API key preview (first 15 characters)
+- Should show the Anthropic SDK version
+
+## Troubleshooting
+
+### Error: "Failed to initialize LLM client"
+
+**Possible causes:**
+
+1. **Missing API Key**
+   - Solution: Add `ANTHROPIC_API_KEY` to Space secrets (see step 1 above)
+
+2. **Invalid API Key Format**
+   - Error will show: "Invalid Anthropic API key format"
+   - Solution: Verify your key starts with `sk-ant-`
+
+3. **Expired or Invalid API Key**
+   - Solution: Generate a new key from Anthropic Console
+
+4. **Wrong Secret Name**
+   - Solution: Make sure the secret is named exactly `ANTHROPIC_API_KEY` (case-sensitive)
+
+### Using Local Be.FM Model Instead
+
+If you don't want to use the Anthropic API:
+1. Select **"Local Be.FM"** from the model dropdown
+2. Note: First run will download ~16GB model
+3. Requires GPU-enabled Space (not available on free tier)
+
+## Alternative: Use .env File (Local Development Only)
+
+For local development, you can use a `.env` file:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...your-key-here...
+LLM_MODEL=claude-3-haiku-20240307
+LLM_MAX_TOKENS=2048
+LLM_TEMPERATURE=0.7
+```
+
+**Note:** The `.env` file is ignored by git and won't be deployed to HF Spaces.
+
+## Checking Deployment Status
+
+After deploying or changing secrets:
+
+1. Wait for Space to rebuild (usually 1-2 minutes)
+2. Check the **Build logs** for any errors
+3. Open the app and check the sidebar for error messages
+4. Use the **🔍 System Diagnostics** expander to verify configuration
+
+## Need Help?
+
+If you're still having issues:
+1. Check the detailed error in the expandable "🔍 Show detailed error" section
+2. Verify your API key is valid at https://console.anthropic.com/
+3. Make sure you've restarted the Space after adding secrets
+4. Check that the secret name is exactly `ANTHROPIC_API_KEY` (case-sensitive)

requirements.txt

@@ -3,8 +3,9 @@ python-dotenv==1.0.0
 pydantic==2.5.0
 pydantic-settings==2.1.0
 
-# LLM Integration
-anthropic==0.18.1
+# LLM Integration - Updated for HF Spaces compatibility
+anthropic>=0.34.0
+httpx>=0.24.0
 
 # API Framework
 fastapi==0.109.0

src/llm/anthropic_client.py

@@ -34,21 +34,41 @@ class AnthropicClient:
                 "Anthropic API key must be provided or set in ANTHROPIC_API_KEY env var"
             )
 
+        # Validate API key format (should start with sk-ant-)
+        if not self.api_key.startswith("sk-ant-"):
+            raise ValueError(
+                f"Invalid Anthropic API key format. Key should start with 'sk-ant-' but got '{self.api_key[:10]}...'"
+            )
+
         self.model = model or os.getenv("LLM_MODEL", "claude-3-5-sonnet-20241022")
         self.max_tokens = int(os.getenv("LLM_MAX_TOKENS", max_tokens))
         self.temperature = float(os.getenv("LLM_TEMPERATURE", temperature))
 
         # Initialize Anthropic client with custom httpx client to avoid proxy issues
         # This is needed for compatibility with some hosting environments (like HF Spaces)
-        import httpx
-
-        # Create httpx client without default proxy configuration
-        http_client = httpx.Client(
-            timeout=httpx.Timeout(60.0, connect=10.0),
-            limits=httpx.Limits(max_keepalive_connections=5, max_connections=10),
-        )
-
-        self.client = Anthropic(api_key=self.api_key, http_client=http_client)
+        # Note: http_client parameter is only supported in newer versions (>=0.34.0)
+        try:
+            import httpx
+            import inspect
+
+            # Check if Anthropic client supports http_client parameter
+            sig = inspect.signature(Anthropic.__init__)
+            supports_http_client = 'http_client' in sig.parameters
+
+            if supports_http_client:
+                # Create httpx client without default proxy configuration
+                http_client = httpx.Client(
+                    timeout=httpx.Timeout(60.0, connect=10.0),
+                    limits=httpx.Limits(max_keepalive_connections=5, max_connections=10),
+                )
+                self.client = Anthropic(api_key=self.api_key, http_client=http_client)
+            else:
+                # Fallback for older versions
+                self.client = Anthropic(api_key=self.api_key)
+        except Exception as e:
+            # If httpx setup fails, use basic client
+            print(f"Warning: Could not set up custom HTTP client: {e}")
+            self.client = Anthropic(api_key=self.api_key)
 
     def generate_response(
         self,

web_app.py

@@ -113,6 +113,30 @@ llm_client = None  # Initialize to None to avoid NameError
 with st.sidebar:
     st.title("🤖 LLM Model")
 
+    # Diagnostics (can be expanded if needed)
+    with st.expander("🔍 System Diagnostics"):
+        api_key = os.getenv("ANTHROPIC_API_KEY")
+        st.write(f"**API Key Status:** {'✓ Found' if api_key else '✗ Missing'}")
+        if api_key:
+            st.write(f"**API Key Preview:** `{api_key[:15]}...`")
+
+        # Show package versions
+        try:
+            import anthropic
+            st.write(f"**Anthropic SDK:** v{anthropic.__version__}")
+        except:
+            st.write("**Anthropic SDK:** Not installed")
+
+        try:
+            import torch
+            st.write(f"**PyTorch:** v{torch.__version__}")
+            st.write(f"**Device:** {torch.device('mps' if torch.backends.mps.is_available() else 'cpu')}")
+        except:
+            st.write("**PyTorch:** Not installed")
+
+        st.write(f"**Python:** {sys.version.split()[0]}")
+        st.write(f"**Streamlit:** v{st.__version__}")
+
     # Check API key availability
     api_key_available = bool(os.getenv("ANTHROPIC_API_KEY"))
     if not api_key_available: