Upload 23 files

DEPLOYMENT.md

@@ -36,15 +36,15 @@ Upload these files to your Space:
 - `USAGE_GUIDE.md` - User guide
 - `test_app.py` - Testing script
 
-#### 3. Configure Environment Variables
+#### 3. Configure Environment Variables (Optional)
 
-In your Space settings, add environment variables:
+**Default Configuration (Recommended for Quick Start):**
 
-**For HuggingFace Inference API (Free Tier):**
-```
-LLM_PROVIDER=huggingface
-# HF_TOKEN is automatically available in Spaces
-```
+No configuration needed! The app automatically uses HuggingFace Inference API with the built-in `HF_TOKEN`.
+
+**Optional: Use Premium Providers**
+
+For better performance, you can add these environment variables in Space Settings:
 
 **For OpenAI:**
 ```
@@ -58,6 +58,12 @@ LLM_PROVIDER=anthropic
 ANTHROPIC_API_KEY=your-key-here
 ```
 
+**For Custom HuggingFace Model:**
+```
+LLM_MODEL=mistralai/Mistral-7B-Instruct-v0.2
+# LLM_PROVIDER defaults to huggingface
+```
+
 #### 4. Space Will Auto-Deploy
 
 - HuggingFace will automatically build and deploy

README.md

@@ -37,6 +37,9 @@ Battle the blank page, reach global audiences, and uncover insights with AI assi
 
 ## 🚀 Quick Start
 
+**On HuggingFace Spaces:** Works immediately with zero configuration! Uses the free HF Inference API.
+
+**Workflow:**
 1. **Generate a Survey**: Start with an outline or topic description
 2. **Translate**: Select target languages to reach global audiences
 3. **Collect Responses**: Use the generated survey with your participants
@@ -44,12 +47,35 @@ Battle the blank page, reach global audiences, and uncover insights with AI assi
 
 ## 🔧 Configuration
 
-ConversAI supports multiple LLM providers. Configure via environment variables:
+### HuggingFace Spaces (Default)
+
+**No configuration needed!** The app automatically uses HuggingFace's Inference API.
+
+- Uses built-in `HF_TOKEN` (automatically available in Spaces)
+- Default model: `mistralai/Mixtral-8x7B-Instruct-v0.1`
+- Free tier available
+
+### Optional: Use Other LLM Providers
 
-- `OPENAI_API_KEY` - For OpenAI models (GPT-4, GPT-3.5)
-- `ANTHROPIC_API_KEY` - For Claude models
-- `HUGGINGFACE_API_KEY` or `HF_TOKEN` - For HuggingFace Inference API
-- `LM_STUDIO_URL` - For local LM Studio instance
+For better performance, you can configure alternative providers via environment variables:
+
+**OpenAI (Recommended for production):**
+```bash
+LLM_PROVIDER=openai
+OPENAI_API_KEY=sk-your-key-here
+```
+
+**Anthropic Claude:**
+```bash
+LLM_PROVIDER=anthropic
+ANTHROPIC_API_KEY=your-key-here
+```
+
+**Custom HuggingFace Model:**
+```bash
+LLM_PROVIDER=huggingface
+LLM_MODEL=your-preferred-model
+```
 
 The app automatically detects which provider to use based on available credentials.
 

app.py

@@ -23,29 +23,59 @@ current_responses = []
 def initialize_backend():
     """Initialize LLM backend based on environment"""
     try:
-        # Try to detect available provider from environment
-        if os.getenv("OPENAI_API_KEY"):
+        # Check for explicit provider setting
+        provider_env = os.getenv("LLM_PROVIDER", "").lower()
+
+        # Priority 1: Explicitly set provider
+        if provider_env == "openai" and os.getenv("OPENAI_API_KEY"):
             return LLMBackend(provider=LLMProvider.OPENAI)
-        elif os.getenv("ANTHROPIC_API_KEY"):
+        elif provider_env == "anthropic" and os.getenv("ANTHROPIC_API_KEY"):
             return LLMBackend(provider=LLMProvider.ANTHROPIC)
-        elif os.getenv("HUGGINGFACE_API_KEY") or os.getenv("HF_TOKEN"):
-            # Use HF_TOKEN which is automatically set in HF Spaces
+        elif provider_env == "huggingface" and (os.getenv("HUGGINGFACE_API_KEY") or os.getenv("HF_TOKEN")):
             api_key = os.getenv("HUGGINGFACE_API_KEY") or os.getenv("HF_TOKEN")
             return LLMBackend(provider=LLMProvider.HUGGINGFACE, api_key=api_key)
-        else:
-            # Fallback to LM Studio for local development
+        elif provider_env == "lm_studio":
             return LLMBackend(provider=LLMProvider.LM_STUDIO)
+
+        # Priority 2: Auto-detect based on available credentials
+        # HF_TOKEN is automatically available in HF Spaces, so check it first
+        if os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACE_API_KEY"):
+            api_key = os.getenv("HUGGINGFACE_API_KEY") or os.getenv("HF_TOKEN")
+            print(f"Auto-detected HuggingFace credentials, using HF Inference API")
+            return LLMBackend(provider=LLMProvider.HUGGINGFACE, api_key=api_key)
+        elif os.getenv("OPENAI_API_KEY"):
+            print(f"Auto-detected OpenAI credentials")
+            return LLMBackend(provider=LLMProvider.OPENAI)
+        elif os.getenv("ANTHROPIC_API_KEY"):
+            print(f"Auto-detected Anthropic credentials")
+            return LLMBackend(provider=LLMProvider.ANTHROPIC)
+        else:
+            # No credentials found - return None to show error in UI
+            print("WARNING: No LLM provider credentials found!")
+            print("Please set one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, HUGGINGFACE_API_KEY, or HF_TOKEN")
+            return None
+
     except Exception as e:
-        print(f"Warning: Backend initialization issue: {e}")
-        # Return a default backend
-        return LLMBackend(provider=LLMProvider.LM_STUDIO)
+        print(f"Error during backend initialization: {e}")
+        import traceback
+        traceback.print_exc()
+        return None
 
 
 # Initialize components
 llm_backend = initialize_backend()
-survey_gen = SurveyGenerator(llm_backend)
-survey_trans = SurveyTranslator(llm_backend)
-data_analyzer = DataAnalyzer(llm_backend)
+
+# Only initialize if backend is available
+if llm_backend:
+    survey_gen = SurveyGenerator(llm_backend)
+    survey_trans = SurveyTranslator(llm_backend)
+    data_analyzer = DataAnalyzer(llm_backend)
+    print(f"✓ ConversAI initialized with {llm_backend.provider.value} provider")
+else:
+    survey_gen = None
+    survey_trans = None
+    data_analyzer = None
+    print("✗ ConversAI initialization incomplete - no LLM credentials found")
 
 
 # ===========================
@@ -56,6 +86,18 @@ def generate_survey_from_outline(outline: str, survey_type: str, num_questions:
     """Generate survey from user outline"""
     global current_survey
 
+    # Check if backend is initialized
+    if not survey_gen:
+        return (
+            "❌ LLM backend not configured. Please set up API credentials:\n"
+            "- For HuggingFace Spaces: HF_TOKEN is auto-available\n"
+            "- For OpenAI: Set OPENAI_API_KEY\n"
+            "- For Anthropic: Set ANTHROPIC_API_KEY\n"
+            "- For HuggingFace: Set HUGGINGFACE_API_KEY",
+            "",
+            None
+        )
+
     if not outline or not outline.strip():
         return "❌ Please provide an outline or topic description.", "", None
 
@@ -125,6 +167,14 @@ def translate_current_survey(target_languages: List[str]):
     """Translate the current survey to selected languages"""
     global current_survey
 
+    # Check if backend is initialized
+    if not survey_trans:
+        return (
+            "❌ LLM backend not configured. Please set up API credentials in Settings.",
+            "",
+            None
+        )
+
     if not current_survey:
         return "❌ Please generate or upload a survey first.", "", None
 
@@ -186,6 +236,14 @@ def get_language_choices():
 
 def analyze_survey_data(responses_json: str, questions_json: str = None):
     """Analyze survey responses"""
+    # Check if backend is initialized
+    if not data_analyzer:
+        return (
+            "❌ LLM backend not configured. Please set up API credentials in Settings.",
+            "",
+            None
+        )
+
     if not responses_json or not responses_json.strip():
         return "❌ Please provide survey responses in JSON format.", "", None
 
@@ -271,6 +329,16 @@ def create_interface():
         Battle the blank page, reach global audiences, and uncover insights with AI assistance.
         """)
 
+        # Show backend status
+        if llm_backend:
+            status_msg = f"✅ **Active LLM Provider:** {llm_backend.provider.value.upper()} | Model: {llm_backend.model}"
+            status_color = "green"
+        else:
+            status_msg = "⚠️ **No LLM Provider Configured** - Please set API credentials (see About tab for instructions)"
+            status_color = "orange"
+
+        gr.Markdown(f'<div style="background-color: rgba(255, 165, 0, 0.1); padding: 10px; border-radius: 5px; margin: 10px 0;">{status_msg}</div>')
+
         with gr.Tabs() as tabs:
 
             # ========== SURVEY GENERATION TAB ==========
@@ -443,20 +511,39 @@ def create_interface():
                 - Identify patterns and trends
                 - Generate actionable insights
 
-                ### 🔧 Technical Details
+                ### 🔧 Configuration Guide
+
+                **For HuggingFace Spaces (Recommended):**
+
+                No configuration needed! The app automatically uses the HF Inference API with the built-in `HF_TOKEN`.
+
+                **Supported Models:**
+                - Default: `mistralai/Mixtral-8x7B-Instruct-v0.1`
+                - You can change by setting `LLM_MODEL` environment variable
+
+                **For Other LLM Providers:**
+
+                Add these environment variables in your Space Settings:
+
+                1. **OpenAI** (Best quality, paid):
+                   - `LLM_PROVIDER=openai`
+                   - `OPENAI_API_KEY=sk-your-key`
+
+                2. **Anthropic Claude** (Best reasoning, paid):
+                   - `LLM_PROVIDER=anthropic`
+                   - `ANTHROPIC_API_KEY=your-key`
+
+                3. **Custom HuggingFace Model**:
+                   - `LLM_PROVIDER=huggingface`
+                   - `LLM_MODEL=your-model-name`
+
+                **💡 Pro Tip:** For production use, we recommend OpenAI or Anthropic for faster, more reliable results.
 
                 **Supported LLM Providers:**
-                - OpenAI (GPT-4, GPT-3.5)
-                - Anthropic (Claude)
-                - HuggingFace Inference API
-                - LM Studio (local)
-
-                **Configuration:**
-                Set environment variables to configure your LLM provider:
-                - `OPENAI_API_KEY` - For OpenAI models
-                - `ANTHROPIC_API_KEY` - For Claude models
-                - `HUGGINGFACE_API_KEY` or `HF_TOKEN` - For HuggingFace
-                - `LM_STUDIO_URL` - For local LM Studio (default: http://192.168.1.245:1234/v1/chat/completions)
+                - HuggingFace Inference API (Free tier available)
+                - OpenAI (GPT-4, GPT-4o-mini, GPT-3.5)
+                - Anthropic (Claude 3.5 Sonnet, Claude 3 Opus)
+                - LM Studio (local development only)
 
                 ### 📄 Data Privacy