Spaces:
Running
Running
| # 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 | |
| <img src="img/march.png" alt="March of Intellect by Robert Seymour" width="500"> | |
| <i>"The March of Intellect" by Robert Seymour (c.1828)</i> | |
| --- | |
| --- | |
| ## 📝 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. | |
| <details> | |
| <summary><b>Templates & Identity</b></summary> | |
| **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) | |
| <img src="img/identity.png" alt="Space Identity Configuration" width="500"> | |
| </details> | |
| <details> | |
| <summary><b>System Configuration</b></summary> | |
| **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 | |
| <img src="img/instructions.png" alt="System Instructions Configuration" width="600"> | |
| </details> | |
| <details> | |
| <summary><b>Example Prompts</b></summary> | |
| **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 | |
| </details> | |
| <details> | |
| <summary><b>URL Grounding</b></summary> | |
| **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 | |
| <img src="img/grounding.png" alt="URL Grounding Configuration" width="300"> | |
| </details> | |
| <details> | |
| <summary><b>Environment Variables</b></summary> | |
| **Required Secrets** | |
| - **API_KEY** (Required): Your OpenRouter API key (must start with `sk-or-`) | |
| - Get from: https://openrouter.ai/keys | |
| - Configure in HuggingFace Space settings | |
| - **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** (Recommended): Password-protect your Space | |
| - Set any password value | |
| - Users will need this code to access | |
| - Leave unset for public access | |
| <img src="img/settings.png" alt="Navigate to Settings" width="500"> | |
| <img src="img/add-secret-api.png" alt="Variables and Secrets" width="500"> | |
| </details> | |
| <details> | |
| <summary><b>Upload Configuration</b></summary> | |
| **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 | |
| <img src="img/upload.png" alt="Upload Configuration" width="500"> | |
| </details> | |
| <details> | |
| <summary><b>Preview Your Assistant</b></summary> | |
| **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 | |
| <img src="img/preview-config.png" alt="Preview Configuration" width="500"> | |
| </details> | |
| --- | |
| --- | |
| ## 🗳️ Step 2: Generate & Deploy | |
| ### Deployment Package & HuggingFace Space Setup | |
| **Package Contents:** `app.py` (application), `requirements.txt` (dependencies), `config.json` (configuration), `README.md` (overview) | |
| <details> | |
| <summary><b>Generate & Create Space</b></summary> | |
| **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` | |
| <img src="img/deployment.png" alt="Deployment Package" width="500"> | |
| **Create New Space** | |
| 1. Go to [huggingface.co/spaces](https://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" | |
| <img src="img/create-space.png" alt="Click Create Space" width="500"> | |
| <img src="img/space.png" alt="Deployed Space" width="500"> | |
| </details> | |
| <details> | |
| <summary><b>Upload Files</b></summary> | |
| **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 | |
| <img src="img/drop-files.png" alt="Drag and drop files" width="500"> | |
| <img src="img/uploading.png" alt="Commit files to space" width="500"> | |
| </details> | |
| <details> | |
| <summary><b>Configure Secrets</b></summary> | |
| **Navigate to Settings** | |
| 1. Click the **Settings** tab in your Space | |
| <img src="img/settings.png" alt="Navigate to settings" width="500"> | |
| 2. Scroll down to **Variables and secrets** section | |
| 3. Click **New secret** | |
| <img src="img/add-secret-api.png" alt="Adding API Key Secret" width="500"> | |
| **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 | |
| </details> | |
| <details> | |
| <summary><b>Verify & Iterate</b></summary> | |
| **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 | |
| </details> | |
| --- | |
| --- | |
| ## 🔧 Troubleshooting | |
| ### Common Issues and Solutions | |
| Find solutions to common problems organized by category. | |
| <details> | |
| <summary><b>Build Errors</b></summary> | |
| **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 | |
| </details> | |
| <details> | |
| <summary><b>API Errors</b></summary> | |
| **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 | |
| </details> | |
| <details> | |
| <summary><b>Access Control Issues</b></summary> | |
| **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 | |
| </details> | |
| <details> | |
| <summary><b>Preview Tab Not Working</b></summary> | |
| **Preview Issues** | |
| - Click "💬 Preview Configuration" first | |
| - Ensure all required fields are filled | |
| - Try refreshing the page | |
| </details> | |
| <details> | |
| <summary><b>Configuration Status Shows ❌</b></summary> | |
| **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 | |
| </details> | |
| --- | |
| --- | |
| ## 📚 Additional Resources | |
| ### 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) | |
| </details> |