docs.md

# 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>