README.md

---
title: ChatUI Helper
emoji: 💬
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.37.0
app_file: app.py
pinned: true
license: gpl-3.0
short_description: Create AI chat interfaces for HuggingFace Spaces
---

# ChatUI Helper

A comprehensive tool for creating, configuring, and deploying customizable AI chat interfaces on HuggingFace Spaces. Designed for educators and developers to quickly generate pedagogically-focused AI assistants.

## 🎯 Key Features

### Configuration & Templates
- **Academic Templates**: Pre-configured templates for educational use cases
  - Socratic Research Chat
  - STEM Adventure Games
  - Course Assistant Example
  - Language Learning Partner
- **Custom Configuration**: Build from scratch with full control
- **Multi-Language Support**: Configure assistants to respond in any language
- **Theme Selection**: Choose from Gradio themes (Default, Soft, Glass, Monochrome, Base)

### URL Grounding & Context
- **Grounding URLs**: Add up to 10 reference URLs for contextual responses
  - Primary sources (URLs 1-2): 8000 character limit
  - Secondary sources (URLs 3+): 2500 character limit
- **Dynamic URL Extraction**: Automatically fetch content from URLs in user messages
- **Smart Content Processing**: HTML parsing with BeautifulSoup

### Security & Access Control
- **Access Codes**: Password-protect your Space for controlled access
- **API Key Management**: Secure handling of OpenRouter API keys
- **HuggingFace Token Integration**: Enable configuration updates without redeployment

### Preview & Testing
- **Live Preview**: Test your assistant before deployment
- **Real-time Configuration**: See changes instantly
- **File Upload Support**: Test document processing capabilities
- **Conversation Export**: Download chat history as markdown

## 🚀 Quick Start

### Local Development
```bash
# Clone the repository
git clone https://huggingface.co/spaces/milwright/chatui-helper

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

### Environment Variables (Optional)
```bash
# For preview functionality
API_KEY=sk-or-your-openrouter-key

# For HuggingFace integration
HF_TOKEN=your-huggingface-token
```

## 📦 Generated Space Contents

Each generated package includes:
- **app.py**: Complete Gradio 5.x application
- **requirements.txt**: All necessary dependencies
- **config.json**: Your configuration settings
- **README.md**: Deployment instructions

### Supported Models
Through OpenRouter integration:
- Google Gemini (Flash, Pro)
- OpenAI GPT-4, GPT-3.5
- Anthropic Claude 3 series
- Meta Llama 3 models
- Mistral/Mixtral models
- DeepSeek reasoning models
- Nvidia Llama optimizations
- Qwen multilingual models

## 📚 Documentation

### [📖 Full Documentation](docs.md)
Complete step-by-step guide with screenshots and detailed instructions.

The application includes comprehensive built-in documentation:
- **Step 1**: Configure & Preview Your Space
  - Templates & Identity
  - System Configuration
  - Example Prompts
  - URL Grounding
  - API Configuration
  - Upload Configuration
  - Preview Testing
- **Step 2**: Generate & Deploy
  - Package Generation
  - Space Creation
  - File Upload
  - Secret Configuration
  - Verification & Iteration
- **Troubleshooting**: Common issues and solutions
- **Additional Resources**: Links to relevant documentation

## 🏗️ Architecture

### Core Components
- **SpaceGenerator**: Handles configuration and package generation
- **ConfigurationManager**: Manages settings with automatic backups
- **Support Documentation**: Nested accordion interface for easy navigation
- **Template System**: String-based templating for code generation

### File Structure
```
chatui-helper/
├── app.py                    # Main application
├── space_template.py         # Template for generated spaces
├── utils.py                  # Shared utilities
├── support_docs.py          # Documentation interface
├── academic_templates.json   # Pre-configured templates
├── requirements.txt         # Dependencies
└── CLAUDE.md               # Development guidance
```

## 🤝 Contributing

This project is designed for educational use. Contributions that enhance pedagogical value are welcome:
- New academic templates
- Improved documentation
- Bug fixes and optimizations
- Accessibility improvements

## 📄 License

GPL-3.0 - See LICENSE file for details

## 🔗 Links

- [HuggingFace Spaces Documentation](https://huggingface.co/docs/hub/spaces-overview)
- [Gradio Documentation](https://gradio.app/docs/)
- [OpenRouter API](https://openrouter.ai/)

---

Built with ❤️ for educators and learners