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 Guide
            Create a functional assistant with URL grounding and example prompts.
            
            **Workflow:**
            1. **Configure** space settings and system prompt
            2. **Enable** URL grounding tools
            3. **Preview** and test configuration
            4. **Generate** deployment package
            5. **Deploy** to HuggingFace
            
            **Prerequisites:**
            - HuggingFace account (free)
            - OpenRouter API key
            - Basic AI chatbot knowledge
            """)
        
        with gr.Accordion("⚙️ Basic Configuration", open=False):
            gr.Markdown("""
            ### Essential Settings
            
            **Space Title & Description** - Name and purpose
            
            **Model Selection:**
            - **Gemini 2.0 Flash** - Fast, reliable (recommended)
            - **Gemma 3 27B** - Open-source, cost-effective
            - **Claude 3.5 Haiku** - Advanced reasoning
            
            **API Key Variable** - Default: `OPENROUTER_API_KEY`
            
            **Access Code** - Optional student protection
            """)
        
        with gr.Accordion("🤖 Assistant Setup", open=False):
            gr.Markdown("""
            ### System Prompt & Templates
            
            **Templates (Easy Start):**
            - **Research Template** - Academic work, citations, fact-checking
            - **Socratic Template** - Teaching through questions, critical thinking
            - **Custom** - Write your own (advanced)
            
            ### Quick Copy-Paste Prompts
            
            **Course Assistant:**
            ```
            You are a [SUBJECT] teaching assistant for [LEVEL] students. Help with concepts, assignments, and study questions. Explain complex topics simply and encourage critical thinking.
            ```
            
            **Research Helper:**
            ```
            You are a research assistant. Help with citations, source analysis, and academic writing. Focus on proper documentation and evidence-based responses.
            ```
            
            **Study Buddy:**
            ```
            You are a friendly study companion. Help students understand concepts, practice problems, and prepare for exams. Use encouraging language and break down complex ideas step-by-step.
            ```
            
            **Tips:**
            - Replace [SUBJECT] and [LEVEL] with your specifics
            - Be clear about the assistant's role
            - Mention your target audience
            """)
        
        with gr.Accordion("🔬 Preview Tab Usage", open=False):
            gr.Markdown("""
            ### Testing Before Deployment
            
            **Preview Features:**
            - Real API integration
            - Configuration display
            - URL testing (up to 4 URLs)
            - Chat export
            - Clear function
            
            **Preview Steps:**
            1. Complete Configuration tab setup
            2. Click "Preview Deployment Package"
            3. Test chat interface
            4. Test URL grounding
            5. Export conversations for analysis
            
            **Requirements:**
            - Set `OPENROUTER_API_KEY` environment variable
            - Without API key: shows configuration only
            
            **Best Practices:**
            - Test various query types
            - Verify URL grounding works
            - Confirm system prompt behavior
            - Export successful conversations
            """)
        
        with gr.Accordion("💬 Example Prompts", open=False):
            gr.Markdown("""
            ### Quick Start Examples
            
            **Guidelines:** One prompt per line, under 100 characters, show capabilities
            
            **Course Assistant:**
            ```
            Can you explain [topic] in simple terms?
            Help me prepare for the midterm exam
            What are the key concepts I should focus on?
            ```
            
            **Research Assistant:**
            ```
            Analyze this source: [URL]
            Help me fact-check this claim
            What citation format should I use?
            ```
            
            **Study Helper:**
            ```
            Quiz me on chapter 5 concepts
            Explain this problem step-by-step
            Help me create a study plan
            ```
            """)
        
        with gr.Accordion("🔧 Tool Settings & Configuration", open=False):
            gr.Markdown("""
            ### Configuration Structure
            
            **Main Fields:**
            - Space Title & Description
            - Model Selection
            - API Key Variable
            - Access Code (optional)
            
            **Assistant Setup:**
            - System Prompt
            - Template Selection
            - URL Grounding (2-4 URLs)
            - Example Prompts
            
            **Advanced Settings:**
            - Temperature (0.0-2.0)
            - Max Tokens (50-4096)
            
            **URL Grounding (Static)**
            - 2-4 URLs for consistent context
            - Content cached during generation
            - Perfect for syllabi, policies, references
            
            **Dynamic URL Fetching**
            - Always enabled
            - Processes URLs in conversations
            - Limited content size for performance
            """)
        
        with gr.Accordion("🎛️ Advanced Settings", open=False):
            gr.Markdown("""
            ### Model Parameters
            
            **Temperature (0.0 - 2.0)**
            - **0.0-0.3**: Focused, deterministic
            - **0.4-0.7**: Balanced (recommended)
            - **0.8-1.2**: Creative, varied
            - **1.3-2.0**: Highly creative
            
            **Max Response Tokens (50-4096)**
            - **50-200**: Short answers
            - **200-750**: Medium (recommended: 750)
            - **750-1500**: Detailed explanations
            - **1500+**: Extended analysis
            
            **Token Notes:**
            - Includes input (prompt + context) and output
            - URLs increase input tokens
            - Consider costs with high limits
            """)
        
        with gr.Accordion("🚀 Deployment Process", open=False):
            gr.Markdown("""
            ### Deployment Guide
            
            **Steps:** Generate → Create Space → Add Secrets → Go Live
            
            **1. Generate & Upload**
            - Click "Generate Deployment Package", download zip
            - Create Space at huggingface.co/spaces (Gradio SDK)
            - Upload `app.py` and `requirements.txt`
            
            **2. Add API Key**
            - Settings → Variables and secrets → New secret
            - Name: `OPENROUTER_API_KEY`
            - Value: Your API key (starts with `sk-or-`)
            
            **3. Access Control (Optional)**
            - Add secret: `SPACE_ACCESS_CODE`
            - Students enter code to access chatbot
            - Delete secret to disable protection
            """)
            
            # Add the secret configuration image (flush left)
            with gr.Row():
                with gr.Column(scale=1):
                    gr.Image(
                        value="https://drive.google.com/uc?export=view&id=1z67BZrYlJkpvHJ0Dp6vvIWAkN2iwUxCv",
                        label="HuggingFace Secret Configuration Interface",
                        show_label=False,
                        interactive=False,
                        width=400,
                        height=300,
                        container=False
                    )
                with gr.Column(scale=2):
                    gr.Markdown("""
                    **Secret Configuration Interface:**
                    - **Name**: Your variable name (e.g., `OPENROUTER_API_KEY`)
                    - **Value**: Your API key or access code
                    - **Add** button to save the secret
                    
                    **Required Secrets:**
                    - `OPENROUTER_API_KEY`: Your API key (always required)
                    - `SPACE_ACCESS_CODE`: Access code (only if using access control)
                    """)
            
            gr.Markdown("""
            **4. Deploy & Test**
            - Wait for build (1-2 minutes)
            - Test with example prompts
            - Share URL when working
            """)
        
        with gr.Accordion("🔧 Troubleshooting", open=False):
            gr.Markdown("""
            ### Common Issues and Solutions
            
            **"Please set your API key" message**
            - Check that you added the API key secret in Space settings
            - Verify the secret name matches your configuration
            - Ensure your OpenRouter account has credits
            
            **Building Failed**
            - Check `requirements.txt` formatting (no extra spaces/characters)
            - Verify all required dependencies are listed
            - Try reuploading files if build gets stuck
            
            **Error 401 (Unauthorized)**
            - Invalid API key or incorrect secret name
            - Check OpenRouter account status and credits
            - Regenerate API key if needed
            
            **Error 429 (Too Many Requests)**
            - Rate limit exceeded
            - Wait a few minutes before trying again
            - Consider upgrading OpenRouter plan for higher limits
            
            **Assistant not responding**
            - Check browser console for JavaScript errors
            - Verify model name is correct and available
            - Test with simple prompts first
            
            **Access code not working**
            - Verify `SPACE_ACCESS_CODE` secret is set correctly
            - Check for typos in the access code
            - Case-sensitive matching
            
            **URLs not fetching content**
            - Check URLs are publicly accessible
            - Some sites block automated requests
            - Verify dynamic URL fetching is enabled if needed
            """)
        
        with gr.Accordion("💡 Best Practices", open=False):
            gr.Markdown("""
            ### Optimization Tips
            
            **Performance**
            - Use appropriate model
            - Set reasonable token limits
            - Cache static content with URL grounding
            
            **User Experience**
            - Write clear example prompts
            - Include usage instructions
            - Test thoroughly before sharing
            - Provide clear access instructions
            
            **Security**
            - Never include API keys in code
            - Use environment variables for secrets
            - Set appropriate access controls
            - Monitor usage and costs
            
            **Maintenance**
            - Check for model updates
            - Monitor feedback and usage
            - Update grounding URLs
            - Keep documentation current
            
            **Cost Management**
            - Start with lower token limits
            - Monitor OpenRouter dashboard
            - Set usage alerts
            - Educate efficient prompting
            """)
        
        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('name'):
            markdown_content += f"**Assistant Name:** {config_metadata['name']}\n"
        if config_metadata.get('description'):
            markdown_content += f"**Description:** {config_metadata['description']}\n"
        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