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
            """)

        gr.Markdown(""" 
        ---
        """)
        
        with gr.Accordion("📝 Step 1: Configure Your Space", open=False):
            gr.Markdown("""
            ### Configuration Steps
    
            #### 1a. Templates & Identity
            Included are several pre-populated templates to get you started with playful (but applied) configurations. Or start with the "None (Custom)" option for a blank slate. Personalize the chat u/i and giving it a name, header (max 60 char) and a markdown description for the `README.md` file, then select from Gradio themes like Default, Soft, Glass, Monochrome, or Base.
            """)
            
            with gr.Row():
                gr.Image(
                    value="img/quick-start-template.png",
                    label="Templates & Identity Configuration",
                    interactive=True,
                    width=600
                )
    
            gr.Markdown("""
            #### 1b. Model Configuration
            Craft a system prompt that steers your model's behavior using a well-defined role, context and audience, code of conduct, and/or terms of engagement——think of guardrails as creative constraints. Afterward select a model ID from the menu of options, then experiment with sampling parameters, adjusting temperature (values from 0 to 2) to control response variability and/or setting a token response limit (between 50-4096) to cap output.
            """)
            
            with gr.Row():
                with gr.Column(scale=1):
                    gr.Image(
                        value="img/model-selection.jpg",
                        label="System Prompt Configuration",
                        interactive=False,
                        width=400
                    )
                with gr.Column(scale=1):
                    gr.Image(
                        value="img/system-configuration.jpeg",
                        label="Model Selection",
                        interactive=False,
                        width=400
                    )
    
            gr.Markdown("""
            #### 1c. Example Prompts
            Add 3 to 5 starter prompts that showcase the purpose and design of your space. These examples appear as quick-start buttons for users to try and meant to help them get started.
            """)
            
            with gr.Row():
                gr.Image(
                    value="img/example-prompts.png",
                    label="Example Prompts Configuration",
                    interactive=True,
                    width=600
                )
    
            gr.Markdown("""
            #### 1d. URL Grounding
            Add up to 10 reference URLs that ground the model in the context of different webpages. The first 2 URLs function as primary sources that will always be loaded with each query, while other URLs serve as supplementary context. Note that only 4096 total characters from URLs are appended to the system prompt.
    
            #### 1e. API Key and HuggingFace Token
            
            - **Required**: Provide the required OpenAI-standard API key (`sk-`) and name for its variable (`API_KEY`) to call the model through a provider like OpenRouter.
            - **Recommended**: Add a HuggingFace token (`HF_TOKEN`) to make your space customizable over time through a configuration editor. 
            - **Optional**: Set an optional password (`ACCESS_CODE`) to limit who can access your space. Any value goes.
    
            #### 1f. Upload `config.json`
            Done this before? Upload your `config.json` files to redeploy your Space with new settings and recent versions.
            """)
            
            with gr.Row():
                gr.Image(
                    value="img/upload-config.png",
                    label="Upload Configuration",
                    interactive=False,
                    width=600
                )

        with gr.Accordion("💬 Step 2: Preview Your Assistant", open=False):
            gr.Markdown("""
            In the Preview tab test your assistant with real-time requests, try example prompts, upload files if enabled, and export your conversation history. Tinker with a variety of queries, models, and configurations to find the most appropriate fit for you and your people.
            """)
            
            with gr.Row():
                with gr.Column(scale=1):
                    gr.Image(
                        value="img/preview-config.png",
                        label="Preview Configuration",
                        interactive=False,
                        width=400
                    )
                with gr.Column(scale=1):
                    gr.Image(
                        value="img/preview-config-screen.png",
                        label="Preview Interface",
                        interactive=False,
                        width=400
                    )
        
        with gr.Accordion("🗳️ Step 3: Generate & Deploy", open=True):
            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 and Create Space → Upload Files and Configure Secrets → Monitor Build and Verify
            """)
            
            with gr.Accordion("Step 3a: Generate & Create Space", open=False):
                gr.Markdown("""
                **Generate Deployment Package**
                - Click "🗳️ Generate Deployment Package" in Configuration tab
                - Download the generated ZIP file
                - Extract files: `app.py`, `config.json`, `requirements.txt`, `README.md`
                
                **Create New Space**
                - Go to [huggingface.co/spaces](https://huggingface.co/spaces)
                - Click "New Space"
                - Choose Gradio SDK (Blank)
                - Select hardware (CPU Basic is free)
                """)
                
                with gr.Row():
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/new-space-gradio-blank.png",
                            label="Space Creation Form",
                            interactive=False,
                            width=400
                        )
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/space-hardware.png",
                            label="Hardware Selection",
                            interactive=False,
                            width=400
                        )
            
            with gr.Accordion("Step 3b: Upload Files", open=False):
                gr.Markdown("""
                **2.1 Upload Project Files**
                - Navigate to Files tab
                - Click "Upload files" or drag and drop
                - Upload: `README.md`, `app.py`, `config.json`, `requirements.txt`
                - Commit directly to main branch
                """)
                
                with gr.Row():
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/upload-files.png",
                            label="File Upload",
                            interactive=False,
                            width=400
                        )
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/highlight-files.png",
                            label="Files After Upload",
                            interactive=False,
                            width=400
                        )
            
            with gr.Accordion("Step 3c: Configure API Secrets", open=False):
                gr.Markdown("""
                **Configure HuggingFace Spaces Secrets**
                - Go to Settings → Variables and secrets
                - Click "New secret"
                
                **Required Secret:**
                - `API_KEY` (or your configured variable name)
                  - Must start with: `sk-or-`
                  - Add in: *Settings* → *Variables and secrets*
                
                **Optional Secrets:**
                - `HF_TOKEN` (Recommended): Enables persistent updates & customization 
                  - Get from: https://huggingface.co/settings/tokens
                  - Enable *write* permissions

                - `ACCESS_CODE`: Password protects your Space
                  - To enable add secret `ACCESS_CODE` with a custom value
                  - To disable delete `ACCESS_CODE` secret entirely from *Variables and Secrets*
                  - Share with authorized users only
                
                **Access Control Notes:**
                - Do NOT set an empty value - either set a code or don't create the secret at all
                """)
                
                with gr.Row():

                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/go-to-settings.png",
                            label="Navigating to Settings",
                            interactive=False,
                            width=400
                        )
                        
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/variables-and-secrets.png",
                            label="API Key Secret Configuration",
                            interactive=False,
                            width=400
                        )
            
            with gr.Accordion("Step 3d: Verify Build & Iterate", open=False):
                gr.Markdown("""
                **Verify Build**
                - Space will show "Building..." status
                - Monitor build logs for errors
                - Wait 1-3 minutes for completion
                - Test chat interface with example prompts
                            
                **Iterate Configuration**
                - Use the configuration editor to make changes
                - Click "Save Configuration" to update
                - Wait for the space to rebuild
                - Test again with new settings
                """)
        
        gr.Markdown(""" 
        ---
        """)
      
        with gr.Accordion("🔧 Troubleshooting", open=False):
            gr.Markdown("""
            ### Common Issues and Solutions
            
            **Build Errors**
            - Check requirements.txt compatibility
            - Ensure Gradio version ≥ 5.39.0
            - Verify all dependencies are available
            
            **API Errors**
            - Verify API_KEY is set correctly
            - Check API key starts with 'sk-or-'
            - Ensure you have API credits
            
            **Access Issues**
            - ACCESS_CODE must match exactly
            - Check for extra spaces in password
            - Verify secret is properly saved
            
            **Preview Not Working**
            - Set API_KEY in local environment
            - Check browser console for errors
            - Ensure configuration is saved
            
            **Configuration Status Shows Red X:**
            - Verify API key secret name matches configuration
            - Check OpenRouter account has credits
            - Regenerate API key if needed
            """)
        
        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