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("# Support Documentation")
        gr.Markdown("Step-by-step guidance for creating and deploying chat interfaces with HuggingFace Spaces.")
        
        with gr.Accordion("🚀 Getting Started", open=True):
            gr.Markdown("""
            # Quick Start

            Build a functional assistant with URL grounding.

            **Steps:**
            1. Configure space settings and system prompt
            2. Enable URL grounding tools
            3. Preview and test
            4. Generate deployment package
            5. Deploy to HuggingFace

            **Requirements:**
            - HuggingFace account (free)
            - OpenRouter API key
            - Basic AI chatbot knowledge
            """)
        
        with gr.Accordion("⚙️ Configuration Guide", open=False):
            gr.Markdown("""
            ### Essential Settings
            
            **System Prompt** - Define your assistant's role, behavior, and capabilities
            
            **Model Selection:**
            - **Gemini 2.0 Flash** - Fast, reliable (recommended)
            - **Gemma 3 27B** - Open-source, cost-effective
            - **Claude 3.5 Haiku** - Advanced reasoning
            
            **System Prompt & Templates:**
            - **Custom** - Write your own specific instructions
            - **Research Template** - Academic work, citations, fact-checking
            - **Socratic Template** - Teaching through questions, critical thinking
            
            **URL Grounding (up to 10 URLs)** - Static content for consistent context
            
            **URL Priority System:**
            - **Primary URLs (2)**: Main references (syllabus, textbook) - always processed first with highest priority
            - **Secondary URLs (8)**: Supplementary sources - additional context as needed
            
            The system processes URLs in order of priority, ensuring your most important content is always included in the assistant's context.
            
            **Example Prompts Guidelines:**
            - One prompt per line, under 100 characters
            - Show assistant capabilities
            - Examples: "Explain [topic] in simple terms", "Help prepare for exam", "Analyze this source: [URL]"
            
            **Advanced Parameters:**
            - **Temperature (0.0-2.0)**: 0.0-0.3 (focused), 0.4-0.7 (balanced), 0.8+ (creative)
            - **Max Tokens (50-4096)**: 750 recommended for balanced responses
            - **API Key Variable**: Default `OPENROUTER_API_KEY`
            - **Access Code**: Optional student protection
            """)

        with gr.Accordion("🔬 Preview & Testing", open=False):
            gr.Markdown("""
            ### Pre-Deployment Testing
            
            **Preview Steps:**
            1. Complete Configuration tab setup
            2. Click "Preview Deployment Package"
            3. Test chat interface and URL grounding
            4. Export conversations for documentation
            
            **Requirements:** Set `OPENROUTER_API_KEY` environment variable for full testing
            
            **Test Checklist:**
            - Various query types and assistant responses
            - URL grounding functionality (if enabled)
            - System prompt behavior matches expectations
            - Example prompts work correctly
            """)
        
        with gr.Accordion("🚀 HuggingFace Space Deployment", open=False):
            gr.Markdown("""
            ### Complete Deployment Workflow
            
            **Overview:** Generate Package → Create Space → Upload Files → Configure Secrets → Monitor Build → Verify Configuration
            """)
            
            with gr.Accordion("Step 1: Generate & Create Space", open=False):
                gr.Markdown("""
                **1.1 Generate Deployment Package**
                - Click "Generate Deployment Package" and download zip
                - Extract files: `app.py`, `config.json`, `requirements.txt`
                
                **1.2 Create New Space**
                - Go to [huggingface.co/spaces](https://huggingface.co/spaces)
                - Click "New Space"
                - Choose Gradio SDK
                - Select hardware (CPU Basic is free)
                """)
                
                with gr.Row():
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/img17.png",
                            label="Space Creation Form",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/img16.png",
                            label="Hardware Selection",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
            
            with gr.Accordion("Step 2: Upload Files", open=False):
                gr.Markdown("""
                **2.1 Upload Project Files**
                - Navigate to Files tab
                - Click "Upload files" or drag and drop
                - Upload: `app.py`, `config.json`, `requirements.txt`
                - Commit directly to main branch
                """)
                
                with gr.Row():
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/img12.png",
                            label="File Upload",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/img8.png",
                            label="Files After Upload",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
            
            with gr.Accordion("Step 3: Configure API Secrets", open=False):
                gr.Markdown("""
                **3.1 Configure HuggingFace Spaces Secrets**
                - Go to Settings → Variables and secrets
                - Click "New secret"
                
                **Required Secret:**
                - **OPENROUTER_API_KEY**: Set this to your OpenRouter API key value
                
                **Optional Secret:**
                - **SPACE_ACCESS_CODE**: Set this to your desired access code value for student access control
                
                **Access Control Notes:**
                - If you don't create the `SPACE_ACCESS_CODE` secret, your Space will be publicly accessible
                - To enable access control, create the `SPACE_ACCESS_CODE` secret with your chosen code value
                - To disable access control, delete the `SPACE_ACCESS_CODE` secret entirely
                - 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/img4.png",
                            label="Navigating to Settings",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
                        
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/img4.png",
                            label="Settings Variables and Secrets",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
                        
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/img3.png",
                            label="API Key Secret Configuration",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
            
            with gr.Accordion("Step 4: Monitor Build & Verify Configuration", open=False):
                gr.Markdown("""
                **4.1 Build Monitoring**
                - Space will show "Building..." status
                - Monitor build logs for errors
                - Wait 1-3 minutes for completion
                
                **4.2 Configuration Verification**
                - Check Configuration Status panel
                - API Key should show "Configured and valid" ✅
                - Test chat interface with example prompts
                """)
                
                with gr.Row():
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/img7.png",
                            label="Build Process",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
                    with gr.Column(scale=1):
                        gr.Image(
                            value="img/img1.png",
                            label="Successful Configuration",
                            show_label=True,
                            interactive=False,
                            width=400,
                            container=False
                        )
                
                gr.Markdown("""
                **Configuration Status Indicators:**
                - ❌ Red X: API key not configured or invalid
                - ✅ Green check: All settings configured correctly
                - 🔄 Building: Space is updating with new changes
                """)
      
        with gr.Accordion("🔧 Troubleshooting", open=False):
            gr.Markdown("""
            ### Common Issues and Solutions
            
            **Configuration Status Shows Red X:**
            - Verify API key secret name matches configuration (usually `OPENROUTER_API_KEY`)
            - Check OpenRouter account has credits
            - Regenerate API key if needed
            
            **Build Failed:**
            - Check `requirements.txt` formatting (no extra spaces)
            - Try reuploading files if build gets stuck
            - Monitor build logs for specific errors
            
            **API Errors:**
            - **401 Unauthorized**: Invalid API key or incorrect secret name
            - **429 Rate Limited**: Wait a few minutes, consider upgrading OpenRouter plan
            
            **Access Issues:**
            - **Access code not working**: Verify `SPACE_ACCESS_CODE` secret is set correctly (case-sensitive)
            - **URLs not fetching**: Check URLs are publicly accessible, some sites block automated requests
            """)
        
        with gr.Accordion("📚 Additional Resources", open=False):
            gr.Markdown("""
            ### Helpful Links
            
            **HuggingFace Documentation**
            - [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 Documentation**
            - [API Keys](https://openrouter.ai/keys)
            - [Model Comparison](https://openrouter.ai/models)
            - [Pricing](https://openrouter.ai/docs#models)
            
            **Gradio Documentation**
            - [Chat Interface](https://gradio.app/docs/chatinterface)
            - [Components](https://gradio.app/docs/)
            - [Sharing Apps](https://gradio.app/sharing-your-app/)
            
            **Community Support**
            - [HuggingFace Community Forums](https://discuss.huggingface.co/)
            - [Gradio Discord](https://discord.gg/feTf9x3ZSB)
            
            **Educational Use Cases**
            - Course assistants for Q&A
            - Research writing support
            - Study guide generation
            - Document analysis tools
            - Language practice partners
            """)

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