Hugging Face's logo

Spaces:
milwright
/
chatui-helper
Running

App Files Community
chatui-helper / docs.md
milwright
add docs.md and img files from origin/main
b0c1c7e
preview code
|
raw
history blame
10.8 kB

ChatUI Helper Documentation

Welcome to ChatUI Helper! This tool helps you create customizable AI chat interfaces for deployment on HuggingFace Spaces.

📖 Quick Start Guide

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
March of Intellect by Robert Seymour "The March of Intellect" by Robert Seymour (c.1828)

📝 Step 1: Configure & Preview Your Space

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.

Templates & Identity

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 space 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)
Space Identity Configuration
System Configuration

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
System Instructions Configuration
Example Prompts

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
URL Grounding

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
URL Grounding Configuration
Environment Variables

Required Secrets

  • API_KEY (Required): Your OpenRouter API key (must start with sk-or-)

  • HF_TOKEN (Recommended): Enables configuration editor in deployed Space

  • ACCESS_CODE (Recommended): Password-protect your Space

    • Set any password value
    • Users will need this code to access
    • Leave unset for public access
Navigate to Settings Variables and Secrets
Upload Configuration

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
Upload Configuration
Preview Your Assistant

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
  • Conversation export
Preview Configuration

🗳️ Step 2: Generate & Deploy

Deployment Package & HuggingFace Space Setup

Package Contents: app.py (application), requirements.txt (dependencies), config.json (configuration), README.md (overview)

Generate & Create Space

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
Deployment Package

Create New Space

  1. Go to huggingface.co/spaces
  2. Click "Create new Space"
  3. Name your Space
  4. Add your preferred licensing (e.g. gpl-3, mit)
  5. Select Gradio SDK
  6. Choose Blank template
  7. Select hardware (CPU Basic is free)
  8. Click "Create Space"
Click Create Space Deployed Space
Upload Files

Upload Project Files

  1. Navigate to the Files tab in your new Space
  2. Click "Contribute" → "Upload files"
  3. Unzip the deployment package
  4. Select all 4 files from your extracted package:
    • README.md
    • app.py
    • config.json
    • requirements.txt
  5. Commit directly to main branch, and your Space will start building
Drag and drop files Commit files to space
Configure Secrets

Navigate to Settings

  1. Click the Settings tab in your SpaceNavigate to settings
  2. Scroll down to Variables and secrets section
  3. Click New secretAdding API Key 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

  • 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
Verify & Iterate

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

🔧 Troubleshooting

Common Issues and Solutions

Find solutions to common problems organized by category.

Build Errors

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
API Errors

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
Access Control Issues

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
Preview Tab Not Working

Preview Issues

  • Click "💬 Preview Configuration" first
  • Ensure all required fields are filled
  • Try refreshing the page
Configuration Status Shows ❌

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

📚 Additional Resources

Documentation Links

HuggingFace

OpenRouter

Gradio

Community Support