support_docs.py

"""
Support documentation module with accordion-style help sections
"""

import gradio as gr
from datetime import datetime


def create_support_docs():
    """Create the support documentation interface with accordion menus"""
    
    with gr.Column():
        gr.Markdown("# ChatUI Helper Documentation")
        gr.Markdown("Welcome to ChatUI Helper! This tool helps you create customizable AI chat interfaces for deployment on HuggingFace Spaces.")
        
        with gr.Accordion("📖 Quick Start Guide", open=True):
            gr.Markdown("""
            ## Overview

            1. **Configure** your assistant using templates or custom settings
            2. **Preview** your configuration to test it works
            3. **Generate** your deployment package
            4. **Deploy** to HuggingFace Spaces

            **Requirements:**
            - HuggingFace account (free)
            - OpenRouter API key
            - Basic understanding of AI assistants
            """)
        
        with gr.Accordion("📝 Step 1: Configure & Preview Your Space", open=False):
            gr.Markdown("""
            ### Configuration Tab Overview
            
            Configure your assistant through various sections in the Configuration tab, then test it in the Preview tab before generating your deployment package.
            """)
            
            with gr.Accordion("Step 1a: Templates & Identity", open=False):
                gr.Markdown("""
                **Quick Start Templates**
                - Choose from pre-configured academic templates (Socratic Research Chat, STEM Adventure Games, etc.)
                - Or select "None (Custom)" for a blank slate
                
                **Space Identity**
                - **Assistant Name**: Give your assistant a memorable name
                - **Tagline**: Brief description (max 60 characters) for HuggingFace YAML frontmatter
                - **Description**: Full markdown description for the README
                - **Theme**: Select from Gradio themes (Default, Soft, Glass, Monochrome, Base)
                """)
            
            with gr.Accordion("Step 1b: System Configuration", open=False):
                gr.Markdown("""
                **System Prompt**
                - Define your assistant's role, context, and behavior
                - Set guardrails and creative constraints
                - Specify audience and terms of engagement
                
                **Model Selection**
                - Choose from available models (Gemini, Claude, GPT, Mistral, etc.)
                - Or enter a custom model ID
                
                **Language Support**
                - Configure language through system prompt instructions
                - Assistant can be instructed to respond exclusively in any language
                - See "Language Learning Partner" template for Italian example
                
                **Sampling Parameters**
                - **Temperature** (0-2): Controls response variability
                - **Max Tokens** (50-4096): Limits response length
                """)
            
            with gr.Accordion("Step 1c: Example Prompts", open=False):
                gr.Markdown("""
                **Example Prompts**
                - Add 3-5 starter prompts that showcase your assistant's capabilities
                - These appear as quick-start buttons for users
                - Help users understand how to interact with your assistant
                - Use the ➕/➖ buttons to add or remove examples
                """)
            
            with gr.Accordion("Step 1d: URL Grounding", open=False):
                gr.Markdown("""
                **Grounding URLs**
                - Add up to 10 reference URLs to provide context
                - **Primary Sources (URLs 1-2)**: Always loaded, up to 8000 characters each
                - **Secondary Sources (URLs 3+)**: Supplementary context, up to 2500 characters each
                - URLs are fetched and included in the system prompt
                - Assistant will cite specific URLs when using grounded information
                - Use the ➕/➖ buttons to manage URLs
                """)
            
            with gr.Accordion("Step 1e: API Configuration", open=False):
                gr.Markdown("""
                **Required Secrets**
                - **API_KEY**: Your OpenRouter API key (must start with `sk-or-`)
                  - Get from: https://openrouter.ai/keys
                  - Configure in HuggingFace Space settings
                
                **Optional Secrets**
                - **HF_TOKEN** (Recommended): Enables configuration editor in deployed Space
                  - Get from: https://huggingface.co/settings/tokens
                  - Select "write" permissions when creating
                  - Allows updating configuration without redeployment
                
                - **ACCESS_CODE**: Password-protect your Space
                  - Set any password value
                  - Users will need this code to access
                  - Leave unset for public access
                """)
            
            with gr.Accordion("Step 1f: Upload Configuration", open=False):
                gr.Markdown("""
                **Upload Existing Configuration**
                - Have a previous `config.json` file?
                - Use the "Upload Configuration" accordion
                - Drag and drop or click to upload
                - All settings will be restored automatically
                """)
            
            with gr.Accordion("Step 1g: Preview Your Assistant", open=False):
                gr.Markdown("""
                **Testing in Preview Tab**
                - Click "💬 Preview Configuration" to prepare your assistant
                - Switch to the Preview tab
                - Test with real queries and example prompts
                - Upload files if file upload is enabled
                - Export conversation history as markdown
                
                **Preview Features**
                - Real-time API responses (requires API key in environment)
                - Grounding context from configured URLs
                - Language-specific responses
                - File upload handling
                - Conversation export
                """)
        
        with gr.Accordion("🗳️ Step 2: Generate & Deploy", open=False):
            gr.Markdown("""
            ### Deployment Package & HuggingFace Space Setup
            
            **Package Contents:**
            - `app.py`: Complete Gradio application
            - `requirements.txt`: Python dependencies
            - `config.json`: Configuration backup
            - `README.md`: Deployment instructions
            
            **Deployment Overview:** Generate Package → Create Space → Upload Files → Configure Secrets → Monitor Build
            """)
            
            with gr.Accordion("Step 2a: Generate & Create Space", open=False):
                gr.Markdown("""
                **Generate Deployment Package**
                1. Click "🗳️ Generate Deployment Package" in Configuration tab
                2. Download the generated ZIP file
                3. Extract files: `app.py`, `config.json`, `requirements.txt`, `README.md`
                
                **Create New Space**
                1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
                2. Click "Create new Space"
                3. Name your Space
                4. Select **Gradio** SDK
                5. Choose **Blank** template
                6. Select hardware (CPU Basic is free)
                7. Click "Create Space"
                """)
            
            with gr.Accordion("Step 2b: Upload Files", open=False):
                gr.Markdown("""
                **Upload Project Files**
                1. Navigate to the **Files** tab in your new Space
                2. Click "Add file" → "Upload files"
                3. Select all 4 files from your extracted package:
                   - `README.md`
                   - `app.py`
                   - `config.json`
                   - `requirements.txt`
                4. Commit directly to main branch
                5. Your Space will automatically start building
                """)
            
            with gr.Accordion("Step 2c: Configure Secrets", open=False):
                gr.Markdown("""
                **Navigate to Settings**
                1. Click the **Settings** tab in your Space
                2. Find **Variables and secrets** section
                3. Click **New secret**
                
                **Add Required Secret**
                - **Name**: `API_KEY` (or your configured variable name)
                - **Value**: Your OpenRouter API key
                - Must start with `sk-or-`
                
                **Add Optional Secrets (if desired)**
                - **HF_TOKEN**: Your HuggingFace token with write permissions
                  - Enables the configuration editor in your Space
                  - Get from: https://huggingface.co/settings/tokens
                
                - **ACCESS_CODE**: Any password value
                  - Restricts access to authorized users
                  - Do NOT set an empty value
                  - Either set a code or don't create the secret
                """)
            
            with gr.Accordion("Step 2d: Verify & Iterate", open=False):
                gr.Markdown("""
                **Monitor Build Process**
                1. Return to the **App** tab
                2. Watch for "Building..." status
                3. Check build logs for any errors
                4. Wait 1-3 minutes for completion
                5. Space will show "Running" when ready
                
                **Test Your Deployment**
                1. Try the example prompts
                2. Test different types of queries
                3. Verify grounding URLs are working
                4. Check language responses (if configured)
                
                **Iterate Configuration (with HF_TOKEN)**
                1. Go to ⚙️ Configuration tab in your Space
                2. Enter your HF_TOKEN to authenticate
                3. Modify settings as needed
                4. Click "Save Configuration"
                5. Space will automatically rebuild
                6. Test new configuration
                """)
      
        with gr.Accordion("🔧 Troubleshooting", open=False):
            gr.Markdown("""
            ### Common Issues and Solutions
            
            Find solutions to common problems organized by category.
            """)
            
            with gr.Accordion("Build Errors", open=False):
                gr.Markdown("""
                **Requirements Compatibility**
                - Ensure Gradio version ≥ 5.39.0 in requirements.txt
                - Check all dependencies are spelled correctly
                - Verify version numbers are compatible
                
                **Common Build Failures**
                - Missing dependencies: Add to requirements.txt
                - Import errors: Check module names and casing
                - Syntax errors: Review app.py for Python syntax issues
                """)
            
            with gr.Accordion("API Errors", open=False):
                gr.Markdown("""
                **API Key Issues**
                - Verify API_KEY is set in HuggingFace Secrets
                - Ensure key starts with 'sk-or-' for OpenRouter
                - Check for extra spaces or quotes in the secret value
                
                **API Response Errors**
                - 401 Unauthorized: Invalid API key
                - 402 Payment Required: No API credits remaining
                - 429 Rate Limited: Too many requests, wait and retry
                - 500 Server Error: OpenRouter service issue
                """)
            
            with gr.Accordion("Access Control Issues", open=False):
                gr.Markdown("""
                **ACCESS_CODE Problems**
                - Code must match exactly (case-sensitive)
                - Don't include quotes around the password
                - Check for trailing spaces in the secret
                - To disable: Delete the ACCESS_CODE secret entirely
                
                **Authentication Flow**
                - Users enter code on first visit
                - Code is stored in browser session
                - Clear cookies to re-prompt for code
                """)
            
            with gr.Accordion("Preview Tab Not Working", open=False):
                gr.Markdown("""
                **Local Testing**
                - Set API_KEY in your local .env file
                - Format: `API_KEY=sk-or-your-key-here`
                - Restart the app after adding environment variable
                
                **Preview Issues**
                - Click "💬 Preview Configuration" first
                - Check browser console (F12) for JavaScript errors
                - Ensure all required fields are filled
                - Try refreshing the page
                """)
            
            with gr.Accordion("Configuration Status Shows ❌", open=False):
                gr.Markdown("""
                **Status Check Failures**
                - Red X means configuration issue detected
                - Usually indicates missing or invalid API key
                
                **Resolution Steps**
                1. Verify secret name matches your configuration
                2. Default is API_KEY, check if you changed it
                3. Regenerate API key at openrouter.ai/keys
                4. Update secret in HuggingFace Space settings
                5. Wait 30 seconds and refresh
                """)
            
            with gr.Accordion("Space Not Loading", open=False):
                gr.Markdown("""
                **Infinite Loading**
                - Check Space logs for error messages
                - Common cause: Missing required secrets
                - Verify all files uploaded correctly
                
                **Gradio App Errors**
                - Component version mismatches
                - Update to latest Gradio version
                - Check for deprecated components
                - Review migration guides for Gradio 5.x
                """)
        
        with gr.Accordion("📚 Additional Resources", open=False):
            gr.Markdown("""
            ### Documentation Links
            
            **HuggingFace**
            - [Spaces Overview](https://huggingface.co/docs/hub/spaces-overview)
            - [Gradio on Spaces](https://huggingface.co/docs/hub/spaces-gradio)
            - [Environment Variables](https://huggingface.co/docs/hub/spaces-overview#managing-secrets)
            
            **OpenRouter**
            - [API Keys](https://openrouter.ai/keys)
            - [Model Comparison](https://openrouter.ai/models)
            - [Pricing](https://openrouter.ai/docs#models)
            
            **Gradio**
            - [Chat Interface](https://gradio.app/docs/chatinterface)
            - [Components](https://gradio.app/docs/)
            - [Sharing Apps](https://gradio.app/sharing-your-app/)
            
            **Community Support**
            - [HuggingFace Forums](https://discuss.huggingface.co/)
            - [Gradio Discord](https://discord.gg/feTf9x3ZSB)
            """)

def export_conversation_to_markdown(conversation_history, config_metadata=None):
    """Export conversation history to markdown format with configuration metadata"""
    if not conversation_history:
        return "No conversation to export."
    
    markdown_content = f"""# Conversation Export
Generated on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}

"""
    
    # Add configuration metadata if provided
    if config_metadata:
        markdown_content += """## Configuration Information

"""
        
        # Add basic configuration details
        if config_metadata.get('model'):
            markdown_content += f"**Model:** {config_metadata['model']}\n"
        if config_metadata.get('temperature'):
            markdown_content += f"**Temperature:** {config_metadata['temperature']}\n"
        if config_metadata.get('max_tokens'):
            markdown_content += f"**Max Tokens:** {config_metadata['max_tokens']}\n"
        
        # Add URL grounding information
        grounding_urls = []
        for i in range(1, 5):
            url = config_metadata.get(f'url{i}')
            if url and url.strip():
                grounding_urls.append(url.strip())
        
        if grounding_urls:
            markdown_content += f"\n**URL Grounding ({len(grounding_urls)} URLs):**\n"
            for i, url in enumerate(grounding_urls, 1):
                markdown_content += f"- URL {i}: {url}\n"
        
        # Add feature flags
        if config_metadata.get('enable_dynamic_urls'):
            markdown_content += f"\n**Dynamic URL Fetching:** Enabled\n"
        
        # Add system prompt
        if config_metadata.get('system_prompt'):
            system_prompt = config_metadata['system_prompt']
            markdown_content += f"\n**System Prompt:**\n```\n{system_prompt}\n```\n"
        
        markdown_content += "\n---\n\n"
    else:
        markdown_content += "---\n\n"
    
    for i, message in enumerate(conversation_history):
        if isinstance(message, dict):
            role = message.get('role', 'unknown')
            content = message.get('content', '')
            
            if role == 'user':
                markdown_content += f"## User Message {(i//2) + 1}\n\n{content}\n\n"
            elif role == 'assistant':
                markdown_content += f"## Assistant Response {(i//2) + 1}\n\n{content}\n\n---\n\n"
    
    return markdown_content