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

   git clone https://huggingface.co/spaces/YOUR_USERNAME/ppt-script-generator
   cd ppt-script-generator
   

3. Add Files

   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

   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

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

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

   # Make changes to files
   git add .
   git commit -m "Updated generation prompt"
   git push
   

Common Customizations

Change Model:

self.client = InferenceClient(
    model="different-model-name",
    token=os.getenv("HF_TOKEN")
)

Adjust Defaults:

num_slides = gr.Slider(
    minimum=3,
    maximum=15,  # Changed from 10
    value=7,     # Changed from 5
    ...
)

Add More Examples:

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:

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

<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