webapp/README_DEPLOYMENT.md

# 🚀 Deployment Guide: Hugging Face Spaces

This guide will help you deploy your Multi-Personality Chatbot to Hugging Face Spaces for **free public access**.

## 📋 Prerequisites

1. **Hugging Face Account** (free)
   - Sign up at: https://huggingface.co/join
   - Verify your email

2. **Git and Git LFS installed**
   - Git: https://git-scm.com/downloads
   - Git LFS: https://git-lfs.github.com/

## 🎯 Step-by-Step Deployment

### Step 1: Create a Hugging Face Space

1. Go to https://huggingface.co/spaces
2. Click **"Create new Space"**
3. Fill in:
   - **Space name**: `personality-chatbot` (or your preferred name)
   - **License**: MIT or Apache 2.0
   - **Select SDK**: Choose **Gradio**
   - **Hardware**: Start with **CPU basic** (free), upgrade to GPU if needed
   - **Visibility**: Public (so anyone can access)
4. Click **"Create Space"**

### Step 2: Set Up Local Repository

Open PowerShell in your project folder:

```powershell
# Navigate to your project
cd C:\Users\dcast\LLM\Project3\llm-project

# Initialize git (if not already done)
git init

# Install Git LFS (for large model files)
git lfs install

# Track large files with Git LFS
git lfs track "*.safetensors"
git lfs track "*.bin"
git lfs track "*.json"

# Add all files
git add .gitattributes
git add .

# Commit
git commit -m "Initial commit: Multi-personality chatbot"
```

### Step 3: Push to Hugging Face

Replace `YOUR_USERNAME` and `YOUR_SPACE_NAME` with your actual values:

```powershell
# Add Hugging Face remote
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

# Push to Hugging Face
git push --set-upstream space main
```

**Authentication**: You'll be prompted for username and password
- **Username**: Your Hugging Face username
- **Password**: Use your **Hugging Face Access Token** (not your account password)
  - Get token at: https://huggingface.co/settings/tokens
  - Create a **Write** token

### Step 4: Wait for Build

1. Go to your Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
2. The Space will automatically build (takes 5-15 minutes first time)
3. You'll see build logs in the "Logs" tab
4. Once done, your app will be live! 🎉

### Step 5: Share Your App

Your app will be accessible at:
```
https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
```

Anyone can access this URL without authentication!

## 🐛 Troubleshooting

### "Repository too large" error

**Problem**: Adapter files are too big for free tier

**Solution**: Upload adapters to Hugging Face Model Hub separately

1. Create model repos for each adapter:
   ```powershell
   # Install huggingface-hub
   pip install huggingface-hub
   
   # Upload each adapter (run in Python)
   python -c "from huggingface_hub import HfApi; api = HfApi(); api.upload_folder(folder_path='pirate-lora-adapter', repo_id='YOUR_USERNAME/pirate-lora', repo_type='model')"
   ```

2. Update `app.py` to load from Hub:
   ```python
   ADAPTERS = {
       "🏴‍☠️ Pirate": "YOUR_USERNAME/pirate-lora",
       "🧙 Yoda": "YOUR_USERNAME/yoda-lora",
       "🤓 Nerd": "YOUR_USERNAME/nerd-lora",
       "🧠 Brainrot": "YOUR_USERNAME/brainrot-lora",
   }
   ```

### "Out of memory" on CPU

**Solution**: Upgrade to GPU hardware
1. Go to Space Settings
2. Click "Change hardware"
3. Select **"GPU - T4 small"** (free tier)

### Build fails with "Module not found"

**Solution**: Check `requirements.txt` has all dependencies
```
gradio>=4.0.0
torch>=2.0.0
transformers>=4.35.0
peft>=0.7.0
accelerate>=0.24.0
safetensors>=0.4.0
```

## 🎨 Customization

### Change app title/description
Edit `app.py` - modify the `gr.Markdown()` sections

### Add more personalities
1. Train a new adapter
2. Add to `ADAPTERS` dict in `app.py`
3. Upload the new adapter folder
4. Push changes: `git add . && git commit -m "Add new personality" && git push space main`

### Improve performance
- Use GPU hardware (Space settings)
- Reduce `max_tokens` default
- Add response caching

## 📊 Free Tier Limits

**Hugging Face Spaces Free Tier:**
- ✅ CPU: Unlimited (but slow for LLMs)
- ✅ GPU T4: Limited hours/month (check your account)
- ✅ Storage: 50GB total
- ✅ Persistence: 24/7 uptime
- ✅ Public access: Unlimited users

**Tips to stay within limits:**
- Start with CPU, upgrade to GPU if too slow
- Keep model size small (Qwen2-0.5B is perfect)
- Monitor usage in Space Settings

## 🔗 Useful Links

- Hugging Face Spaces Docs: https://huggingface.co/docs/hub/spaces
- Gradio Docs: https://www.gradio.app/docs
- Git LFS Guide: https://git-lfs.github.com/

## 🆘 Need Help?

If you encounter issues:
1. Check Space logs (Logs tab)
2. Check build status
3. Ask in Hugging Face Discord: https://discuss.huggingface.co/

---

**That's it!** Your chatbot is now publicly accessible to anyone with the URL. 🎉