DEPLOYMENT_GUIDE.md

# 🚀 HuggingFace Spaces Deployment Guide

## Quick Deployment Steps

### Option 1: Using HuggingFace Web Interface (Easiest)

1. **Go to HuggingFace Spaces**
   - Visit: https://huggingface.co/spaces
   - Click "Create new Space"

2. **Configure Your Space**
   - **Space name**: `ppt-script-generator` (or your choice)
   - **License**: MIT
   - **SDK**: Gradio
   - **Visibility**: Public (or Private)
   - Click "Create Space"

3. **Upload Files**
   - Click "Files" tab
   - Upload these files:
     - `app.py`
     - `requirements_hf.txt` (rename to `requirements.txt` when uploading)
     - `README_HF.md` (rename to `README.md` when uploading)

4. **Wait for Build**
   - HuggingFace will automatically build your Space
   - Takes 1-2 minutes
   - Status shown at top of page

5. **Access Your App**
   - Once built, click "App" tab
   - Your app is live at: `https://huggingface.co/spaces/YOUR_USERNAME/ppt-script-generator`
   - Share this URL with anyone!

---

### Option 2: Using Git (For Developers)

1. **Create Space on HuggingFace**
   - Visit: https://huggingface.co/new-space
   - Fill in details as above

2. **Clone Repository**
   ```bash
   git clone https://huggingface.co/spaces/YOUR_USERNAME/ppt-script-generator
   cd ppt-script-generator
   ```

3. **Add Files**
   ```bash
   cp path/to/app.py .
   cp path/to/requirements_hf.txt requirements.txt
   cp path/to/README_HF.md README.md
   ```

4. **Commit and Push**
   ```bash
   git add .
   git commit -m "Initial commit: PPT Script Generator"
   git push
   ```

5. **Check Deployment**
   - Visit your Space URL
   - Check build logs if needed

---

## 📂 Required Files

Your Space needs exactly 3 files:

### 1. `app.py` (Main Application)
- Contains the complete Gradio interface
- Uses HuggingFace Inference API
- No local model download needed

### 2. `requirements.txt` (Dependencies)
```
gradio
huggingface_hub
```

### 3. `README.md` (Space Description)
- Shown on your Space's landing page
- Must have YAML frontmatter at top
- Describes your app

---

## ⚙️ Configuration Options

### In README.md Frontmatter

```yaml
---
title: PowerPoint Script Generator    # Your app name
emoji: 🎤                              # Icon for your Space
colorFrom: purple                      # Gradient start color
colorTo: blue                          # Gradient end color
sdk: gradio                            # Always 'gradio'
sdk_version: 4.44.0                    # Gradio version
app_file: app.py                       # Main file name
pinned: false                          # Pin to your profile?
license: mit                           # License type
---
```

### Visibility Options

- **Public**: Anyone can view and use
- **Private**: Only you (and collaborators) can access

---

## 🔍 Testing Your Deployment

### Before Deploying

Test locally first:
```bash
python app.py
```

Should show:
```
Running on local URL:  http://127.0.0.1:7860
```

### After Deploying

1. **Check Build Status**
   - Look for green checkmark
   - If red X, check logs

2. **Test the App**
   - Try example topics
   - Test with custom topic
   - Verify output quality

3. **Common Issues**
   - **Build fails**: Check requirements.txt
   - **App crashes**: Check app.py for errors
   - **Slow generation**: Normal for free tier
   - **API errors**: Wait and retry (rate limits)

---

## 📊 Usage Limits (Free Tier)

HuggingFace Spaces free tier has:
- **Compute**: Limited CPU/RAM
- **API calls**: Rate limited
- **Uptime**: May sleep after inactivity
- **Build time**: A few minutes

**For production use**, consider upgrading to a paid tier.

---

## 🎨 Customization After Deployment

### Update Your Space

1. **Via Web Interface**
   - Go to "Files" tab
   - Click file to edit
   - Make changes
   - Click "Commit changes"
   - Space rebuilds automatically

2. **Via Git**
   ```bash
   # Make changes to files
   git add .
   git commit -m "Updated generation prompt"
   git push
   ```

### Common Customizations

**Change Model:**
```python
self.client = InferenceClient(
    model="different-model-name",
    token=os.getenv("HF_TOKEN")
)
```

**Adjust Defaults:**
```python
num_slides = gr.Slider(
    minimum=3,
    maximum=15,  # Changed from 10
    value=7,     # Changed from 5
    ...
)
```

**Add More Examples:**
```python
gr.Examples(
    examples=[
        ["Your new topic", 5, "Students", "Educational"],
        # Add more here
    ],
    ...
)
```

---

## 🐛 Troubleshooting

### Build Errors

**Error: "No module named 'gradio'"**
- Fix: Check `requirements.txt` has `gradio`

**Error: "Cannot find app.py"**
- Fix: Ensure `app_file: app.py` in README.md frontmatter

### Runtime Errors

**Error: "API rate limit exceeded"**
- Wait 60 seconds and try again
- Consider upgrading Space tier

**Error: "Model timeout"**
- Normal for long generations
- Reduce number of slides
- Reduce max_tokens

**App shows "Sleeping"**
- Free tier sleeps after inactivity
- Click to wake it up (takes 10-20 seconds)

---

## 📈 Monitoring Your Space

### Check Analytics

- Visit your Space page
- Click "Analytics" tab
- See:
  - Number of users
  - Usage patterns
  - Popular features

### View Logs

- Click "Logs" tab
- See real-time app output
- Debug errors
- Monitor performance

---

## 🔒 Security Best Practices

### API Tokens

- Never hardcode tokens in code
- Use `os.getenv("HF_TOKEN")`
- HF Spaces provides this automatically

### Rate Limiting

- Implement client-side delays
- Show loading messages
- Handle API errors gracefully

### Input Validation

Already implemented in `app.py`:
```python
if not topic.strip():
    return "⚠️ Please enter a presentation topic."
```

---

## 🌟 Making Your Space Popular

### 1. Good Description
- Clear README.md
- Screenshots/GIFs
- Use cases

### 2. Example Content
- Provide good examples
- Show various use cases
- Make it easy to try

### 3. Share It
- Social media
- GitHub repos
- Blog posts
- Communities

### 4. Maintain It
- Fix bugs quickly
- Update dependencies
- Improve based on feedback

---

## 📱 Embedding Your Space

### In a Website

```html
<gradio-app src="https://huggingface.co/spaces/YOUR_USERNAME/ppt-script-generator"></gradio-app>
<script type="module" src="https://gradio.s3-us-west-2.amazonaws.com/4.44.0/gradio.js"></script>
```

### In a Blog Post

Use the embed code from your Space settings.

---

## 🚀 Next Steps After Deployment

1. **Test thoroughly**
   - Try various topics
   - Different audiences
   - Edge cases

2. **Gather feedback**
   - Share with users
   - Collect suggestions
   - Iterate and improve

3. **Add features**
   - Export to PDF
   - Save templates
   - Multi-language support

4. **Optimize performance**
   - Cache common requests
   - Optimize prompts
   - Reduce token usage

---

## 📞 Getting Help

### Resources

- **HuggingFace Docs**: https://huggingface.co/docs/hub/spaces
- **Gradio Docs**: https://gradio.app/docs
- **Community Forum**: https://discuss.huggingface.co

### Common Questions

**Q: How long does deployment take?**
A: Usually 1-2 minutes for first build

**Q: Can I use private models?**
A: Yes, with HF Pro subscription

**Q: What's the API rate limit?**
A: Varies by tier; free tier is limited

**Q: Can I upgrade my Space?**
A: Yes, upgrade to PRO or Enterprise

---

## ✅ Pre-Deployment Checklist

Before you deploy, ensure:

- [ ] `app.py` runs locally without errors
- [ ] `requirements.txt` has all dependencies
- [ ] `README.md` has correct YAML frontmatter
- [ ] Example topics work correctly
- [ ] Error handling is in place
- [ ] Loading messages are shown
- [ ] Output is properly formatted
- [ ] All features work as expected

---

## 🎉 You're Ready!

Your Space will be live at:
```
https://huggingface.co/spaces/YOUR_USERNAME/ppt-script-generator
```

**Share it with the world!** 🌍

---

*Last Updated: January 2026*