# Building ML Demos with Hugging Face Spaces
### Overview
Today we'll build a complete ML demo from scratch and deploy it to Hugging Face Spaces. We'll focus on the **process** of creating demos, not the ML model itself.

---

## Part 1: Project Setup & Structure 

### Starting from Scratch
**Talking Points:**
- "Let's say you have a trained model and want to share it with the world"
- "The goal is to create a web interface that anyone can use"
- "We'll use Gradio - it's perfect for ML demos"

### Project Structure
```
simple-vpr-demo/
├── app.py              # Main Gradio application
├── model.py            # Model loading logic
├── dataset.py          # Data handling
├── requirements.txt    # Dependencies
├── README.md           # HF Spaces metadata + docs
└── data/               # Sample data
    ├── database/       # Reference images
    ├── query/          # Test images
    └── ground_truth.json
```

**Key Points:**
- **Modular design**: Separate concerns (UI, model, data)
- **Clean structure**: Easy to understand and extend
- **Data organization**: Logical folder structure

---

## Part 2: Understanding Gradio 

### What is Gradio?
**Talking Points:**
- "Gradio is like Flask for ML - but much simpler"
- "It automatically creates web interfaces from Python functions"
- "Perfect for demos, prototypes, and sharing ML models"

### Core Concepts

#### 1. Components
```python
# Input components
gr.Image(type="pil", label="Upload Image")     # File upload
gr.Slider(1, 10, value=5, step=1)              # Range input
gr.Button("Process")                            # Action trigger

# Output components  
gr.Textbox(lines=10, interactive=False)         # Display text
gr.Gallery()                                    # Image grid
```

**Talking Points:**
- "Components are like HTML elements, but for ML"
- "Each component has specific parameters for customization"
- "Input components collect data, output components display results"

#### 2. Layout System
```python
with gr.Blocks() as demo:
    gr.Markdown("# Title")                      # Header
    
    with gr.Row():                             # Horizontal layout
        with gr.Column():                       # Left column
            # Input controls
        with gr.Column():                       # Right column  
            # Output display
```

**Talking Points:**
- "gr.Blocks() gives you full control over layout"
- "gr.Row() and gr.Column() create responsive layouts"
- "Alternative: gr.Interface() for simpler, auto-generated layouts"

#### 3. Event Handling
```python
button.click(
    fn=my_function,                    # Function to call
    inputs=[input1, input2],          # Input components
    outputs=[output1, output2]        # Output components
)
```

**Talking Points:**
- "This is the magic - connecting UI to your ML code"
- "Function signature must match: my_function(input1, input2)"
- "Return values automatically update the output components"

### Gradio vs Alternatives
**Talking Points:**
- **Streamlit**: Great for data apps, but more complex for ML demos
- **Flask/FastAPI**: Full control but requires frontend knowledge
- **Gradio**: Perfect balance - simple but powerful

---

## Part 3: Building the Application 

### The Demo Function
```python
def demo_interface(query_image, top_k):
    # 1. Process the input
    query_tensor = transform(query_image)
    
    # 2. Run your ML model
    matches = find_matches(query_tensor, int(top_k))
    
    # 3. Format results
    result_text = "Top Matches:\n\n"
    result_images = []
    for match in matches:
        result_text += f"Similarity: {match['similarity']:.4f}\n"
        result_images.append(match['image'])
    
    # 4. Return outputs (must match output components)
    return result_text, result_images
```

**Key Points:**
- **Input processing**: Convert UI inputs to model format
- **Model inference**: Run your ML pipeline
- **Output formatting**: Make results user-friendly
- **Return matching**: Must match your output components

### Performance Optimization
**Talking Points:**
- "Notice we pre-compute database features on startup"
- "This makes the demo fast - no waiting for users"
- "Always optimize for user experience in demos"

---

## Part 4: Hugging Face Spaces Deployment 

### What are Hugging Face Spaces?
**Talking Points:**
- "Think of it as GitHub for ML demos"
- "Free hosting for Gradio, Streamlit, and Docker apps"
- "Automatic deployment from Git repositories"
- "Built-in GPU support for complex models"

### Required Files

#### 1. README.md (Critical!)
```yaml
---
title: Visual Place Recognition Demo
emoji: 🗺️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
short_description: Upload a query image to find similar places
---
```

**Talking Points:**
- "This metadata tells HF Spaces how to deploy your app"
- "Must be at the top of README.md"
- "sdk: gradio tells HF this is a Gradio app"
- "app_file: app.py points to your main file"

#### 2. requirements.txt
```txt
torch>=1.9.0
torchvision>=0.10.0
gradio>=3.0.0,<4.0.0
huggingface_hub>=0.19.4,<0.20.0
Pillow>=8.0.0
numpy>=1.21.0
tqdm>=4.60.0
```

**Talking Points:**
- "Pin your versions! This prevents deployment issues"
- "Notice the huggingface_hub version pin - this prevents the HfFolder error"
- "Only include what you actually import"

#### 3. app.py
**Talking Points:**
- "This is your main application file"
- "Must be named exactly as specified in README.md"
- "HF Spaces will run: python app.py"

### Deployment Process (Git Approach)

#### Step 1: Create Repository
```bash
# Initialize git repo
git init
git add .
git commit -m "Initial commit"

# Create repo on GitHub/Hugging Face
# Copy the remote URL
git remote add origin https://github.com/username/repo-name.git
git push -u origin main
```

#### Step 2: Create HF Space
1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Fill in details:
   - **Space name**: `your-demo-name`
   - **SDK**: `Gradio`
   - **Hardware**: `CPU` (or `GPU` if needed)
   - **Visibility**: `Public`

#### Step 3: Connect Repository
1. Choose "Git Repository" option
2. Enter your GitHub repo URL
3. Click "Create Space"

**Talking Points:**
- "HF Spaces will automatically clone your repo"
- "It reads your README.md metadata"
- "Installs dependencies from requirements.txt"
- "Runs your app.py file"

#### Step 4: Monitor Deployment
**Talking Points:**
- "Watch the logs for any errors"
- "Common issues: missing dependencies, import errors"
- "The HfFolder error we saw earlier is a perfect example"

### Common Deployment Issues

#### 1. Dependency Conflicts
```txt
# Problem: Gradio tries to import HfFolder (removed in HF Hub 0.20+)
# Solution: Pin compatible versions
huggingface_hub>=0.19.4,<0.20.0
gradio>=3.0.0,<4.0.0
```

#### 2. Missing Files
- Ensure all files are committed to git
- Check file paths are correct
- Verify app.py exists and is executable

#### 3. Memory Issues
- Use CPU hardware for simple demos
- Optimize model loading (pre-compute features)
- Consider model quantization for large models

---

## Part 5: Best Practices & Tips (2 minutes)

### Demo Design Principles
1. **Keep it simple**: Focus on core functionality
2. **Make it fast**: Pre-compute what you can
3. **Handle errors**: Graceful failure messages
4. **Clear UI**: Intuitive interface design

### Code Organization
1. **Separate concerns**: UI, model, data handling
2. **Document everything**: Comments for seminar audiences
3. **Version control**: Pin dependencies
4. **Test locally**: Run `python app.py` before deploying

### Hugging Face Spaces Features
- **Automatic updates**: Push to git = auto-deploy
- **Public sharing**: Easy to share with anyone
- **GPU support**: For compute-intensive models
- **Custom domains**: Professional URLs
- **Analytics**: Usage statistics

---

## Demo Script (Live Coding)

### 1. Show the Working Demo (2 minutes)
- "Let's see what we're building"
- Upload a query image
- Show the results
- Explain the user experience

### 2. Walk Through the Code (5 minutes)
- Open app.py
- Explain the Gradio components
- Show the function signature matching
- Highlight the layout structure

### 3. Deploy Live (3 minutes)
- Show the git repository
- Create a new HF Space
- Connect the repository
- Watch it deploy

### 4. Test Deployment (2 minutes)
- Open the deployed app
- Test the same functionality
- Show it's identical to local version

---

## Key Takeaways

1. **Gradio makes ML demos accessible** - No frontend knowledge needed
2. **HF Spaces provides free hosting** - Perfect for sharing ML work
3. **Git-based deployment** - Version control + automatic updates
4. **Dependency management matters** - Pin versions to avoid conflicts
5. **User experience is key** - Fast, intuitive interfaces

## Questions & Discussion

**Common Questions:**
- "Can I use my own models?" → Yes, any Python ML library
- "What about GPU costs?" → HF Spaces provides free GPU hours
- "How do I handle large models?" → Use model quantization or HF Hub
- "Can I customize the UI?" → Yes, CSS and custom components
- "What about authentication?" → Gradio supports user management

---

## Resources

- [Gradio Documentation](https://gradio.app/docs/)
- [Hugging Face Spaces](https://huggingface.co/spaces)
- [Gradio Examples](https://gradio.app/gallery)
- [HF Spaces Documentation](https://huggingface.co/docs/hub/spaces)

---

*This seminar demonstrates the complete workflow from local development to public deployment, emphasizing the tools and processes that make ML demos accessible to everyone.*