DEPLOYMENT.md

Deploying to HuggingFace Spaces

This guide walks you through deploying the HPMOR Q&A chatbot to HuggingFace Spaces.

Prerequisites

1. HuggingFace account (create at https://huggingface.co)
2. Groq API key (get free at https://console.groq.com)
3. HuggingFace CLI installed and authenticated (hf auth login)

Quick Deployment Steps

1. Create a HuggingFace Space

cd hpmor_qa

# Create a new Space
hf space create chat-with-harry --sdk gradio --space_sdk_version 5.49.1

Or manually create it on the HuggingFace website:

• Go to https://huggingface.co/new-space
• Choose a name (e.g., "chat-with-harry")
• Select SDK: Gradio
• Select SDK version: 5.49.1
• Choose Public or Private

2. Prepare Files for Deployment

The following files are needed for HuggingFace Spaces:

• app.py - Main application file ✅ (created)
• requirements_hf.txt - Python dependencies ✅ (created, rename to requirements.txt)
• README_HF.md - Space README with metadata ✅ (created, rename to README.md)
• src/ - Source code directory ✅ (existing)
• data/ - Data directory ✅ (existing)
• .env - Environment variables (will be set as Space secrets)

3. Set Up Space Secrets

Add your Groq API key as a secret in your Space:

Option A: Via Web Interface

1. Go to your Space settings
2. Navigate to "Repository secrets"
3. Add secret:
   • Name: GROQ_API_KEY
   • Value: your_actual_groq_api_key

Option B: Via CLI

# Set the GROQ_API_KEY secret
hf space secret set GROQ_API_KEY your_actual_groq_api_key --space-id YOUR_USERNAME/chat-with-harry

4. Deploy to HuggingFace

cd hpmor_qa

# Initialize git repo if not already done
git init
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/chat-with-harry

# Copy and rename files for deployment
cp README_HF.md README.md
cp requirements_hf.txt requirements.txt

# Add files
git add app.py README.md requirements.txt src/ data/ .gitignore

# Commit
git commit -m "Initial deployment: HPMOR Q&A chatbot"

# Push to HuggingFace
git push --force space main

5. Alternative: Automated Deployment Script

Save this as deploy.sh and run it:

#!/bin/bash
set -e

# Configuration
SPACE_NAME="chat-with-harry"
HF_USERNAME="YOUR_USERNAME"  # Change this!

echo "🚀 Deploying HPMOR Q&A to HuggingFace Spaces..."

# Check if logged in
if ! hf whoami &> /dev/null; then
    echo "❌ Not logged in to HuggingFace. Run: hf auth login"
    exit 1
fi

# Create Space if it doesn't exist
echo "📦 Creating HuggingFace Space..."
hf space create $SPACE_NAME --sdk gradio --space_sdk_version 5.49.1 || echo "Space may already exist"

# Copy files for deployment
echo "📝 Preparing deployment files..."
cp README_HF.md README.md
cp requirements_hf.txt requirements.txt

# Initialize git if needed
if [ ! -d .git ]; then
    git init
fi

# Add HuggingFace remote
git remote remove space 2>/dev/null || true
git remote add space https://huggingface.co/spaces/${HF_USERNAME}/${SPACE_NAME}

# Stage files
echo "📦 Staging files..."
git add app.py README.md requirements.txt src/ data/ .gitignore

# Commit
git commit -m "Deploy: HPMOR Q&A chatbot" || echo "Nothing new to commit"

# Push
echo "🚀 Pushing to HuggingFace Spaces..."
git push --force space main

echo "✅ Deployment complete!"
echo "🌐 Your Space: https://huggingface.co/spaces/${HF_USERNAME}/${SPACE_NAME}"
echo ""
echo "⚠️  Don't forget to set GROQ_API_KEY in Space secrets!"

Make it executable and run:

chmod +x deploy.sh
./deploy.sh

Post-Deployment Checklist

• Space is building successfully
• GROQ_API_KEY secret is set
• Data files are present (check Space files tab)
• App loads without errors
• Can ask questions and get responses
• Sources are displayed correctly

Troubleshooting

Build Failures

Problem: Dependencies fail to install

• Check requirements.txt for version conflicts
• Try removing version pins
• Check Space build logs

Problem: Out of memory during build

• Reduce chunk size in config
• Use smaller embedding model
• Request GPU Space (Settings → Hardware)

Runtime Errors

Problem: "GROQ_API_KEY not found"

• Set the secret in Space settings
• Restart the Space

Problem: "No processed documents found"

• Ensure data/raw/hpmor.html is included
• Check file paths in app.py
• The app should auto-setup on first run

Problem: Slow responses

• Upgrade to GPU Space (Settings → Hardware)
• Reduce TOP_K_RETRIEVAL
• Consider using smaller model

File Structure for Deployment

hpmor_qa/
├── app.py                  # Main Gradio app (HF Spaces entry point)
├── README.md               # Space description with metadata
├── requirements.txt        # Python dependencies
├── .gitignore             # Git ignore rules
├── src/
│   ├── __init__.py
│   ├── config.py          # Configuration
│   ├── document_processor.py
│   ├── vector_store.py
│   ├── model_chain.py     # Uses Groq only
│   ├── rag_engine.py
│   └── harry_personality.py
└── data/
    └── raw/
        └── hpmor.html     # Source text (ensure this is included!)

Important Notes

1. No Ollama: The cloud version only uses Groq API (no local models)
2. Groq API Key: Must be set as a Space secret
3. Data Files: Ensure data/raw/hpmor.html is committed to the repo
4. First Run: The app will auto-process documents on first launch
5. Persistent Storage: ChromaDB will persist in Space storage

Updating Your Space

To update your deployed Space:

# Make changes to your code
git add .
git commit -m "Update: description of changes"
git push space main

Custom Domain (Optional)

HuggingFace provides a default URL, but you can:

1. Use HF's subdomain: your-username-chat-with-harry.hf.space
2. Request a custom domain (Pro feature)

Monitoring

• View logs: Space interface → "Logs" tab
• Check status: Space interface → "Settings" tab
• Usage stats: HuggingFace dashboard

Getting Help

If you encounter issues:

1. Check Space build logs
2. Review HuggingFace Spaces documentation: https://huggingface.co/docs/hub/spaces
3. Check Gradio documentation: https://gradio.app/docs/
4. Open an issue on the project repository

Cost Considerations

• Free Tier:

  • CPU Spaces are free
  • 2 CPU cores, 16GB RAM
  • May be slow for large queries

• Upgraded Hardware (Paid):

  • GPU Spaces for faster inference
  • More RAM for larger embeddings
  • Pricing: https://huggingface.co/pricing

Next Steps

After deployment:

1. Test the chatbot thoroughly
2. Share your Space link!
3. Gather feedback and iterate
4. Consider adding analytics
5. Add more features (streaming responses, etc.)

Enjoy your deployed HPMOR chatbot! 🧙‍♂️