docs/deployment_guide.md

# Deployment Guide - Hugging Face Spaces

This guide walks you through deploying the Plant Disease Detection app to Hugging Face Spaces.

## Prerequisites

- Hugging Face account (free): https://huggingface.co/join
- Trained model weights
- Git installed locally

## Deployment Options

You have three options for deploying your model:

### Option 1: Upload Model Weights to Space (Recommended)
**Pros:** Simple, no external dependencies
**Cons:** Weights are part of the repo

### Option 2: Load from Hugging Face Model Hub
**Pros:** Separate model versioning, smaller Space repo
**Cons:** Need to upload model separately

### Option 3: Fetch from ClearML
**Pros:** Direct integration with training pipeline
**Cons:** Requires ClearML credentials in Space secrets

## Step-by-Step: Option 1 (Upload Weights)

### 1. Create a Hugging Face Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in details:
   - **Name:** `plant-disease-detection`
   - **License:** Apache 2.0
   - **Space SDK:** Gradio
   - **Visibility:** Public
4. Click "Create Space"

### 2. Prepare Files for Deployment

Create a new directory for your Space:

```bash
mkdir hf-space-deployment
cd hf-space-deployment
```

Copy and flatten the UI structure:

```bash
# Copy main app file
cp ../ui/app.py ./

# Copy supporting files
cp ../ui/config.py ./
cp ../ui/model_loader.py ./
cp ../ui/utils.py ./
cp ../models/mock_model.py ./

# Copy requirements
cp ../requirements.txt ./

# Copy your trained model weights
cp ../path/to/best_model.pth ./
```

### 3. Modify app.py for Deployment

Edit `app.py` to work with the flat structure:

```python
# Change imports at the top of app.py
import config
from model_loader import ModelLoader
from utils import preprocess_image, postprocess_predictions, ...
from mock_model import create_mock_predictions

# At the bottom, change:
demo = create_interface(use_mock=False)  # Use real model
demo.launch()  # Remove server_name and server_port
```

### 4. Modify model_loader.py

Update the model loading to use your actual architecture:

```python
# In _load_real_model method, replace mock model with your actual model:

def _load_real_model(self, model_name, model_path=None):
    if model_config["model_type"] == "cnn":
        # Import your actual model class
        from your_model_module import YourCNNModel
        model = YourCNNModel(num_classes=len(config.CLASS_NAMES))

    # Load weights
    if model_path:
        model.load_state_dict(torch.load(model_path, map_location=self.device))
    else:
        # Load default model
        model.load_state_dict(torch.load("best_model.pth", map_location=self.device))

    return model
```

### 5. Create README for Space

Create `README.md` in the deployment directory:

```markdown
---
title: Plant Disease Detection
emoji: 🌱
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: apache-2.0
---

# 🌱 Plant Disease Detection

AI-powered plant disease detection from leaf images.

## About

This application uses a Convolutional Neural Network (CNN) trained on the PlantVillage
dataset to identify plant diseases from leaf images.

**Developed by:** [Your Team Name]
**Course:** 5CCSAGAP - AI Group Project, King's College London
**Academic Year:** 2024-2025

## Features

- Upload plant leaf images for disease detection
- Support for 39 different plant disease categories
- Multiple model options (CNN, Transfer Learning)
- Batch processing capability
- Confidence threshold adjustment

## How to Use

1. Go to the "Single Image" tab
2. Upload a photo of a plant leaf
3. Click "Predict Disease"
4. View the top predictions with confidence scores

## Dataset

Trained on the [PlantVillage dataset](https://huggingface.co/datasets/EdBianchi/plant-village)
containing 55,400 images across 39 disease categories.

## Model Performance

- **Test Accuracy:** [Add your test accuracy]
- **Architecture:** Custom CNN / ResNet18 Transfer Learning
- **Training Framework:** PyTorch
- **Experiment Tracking:** ClearML

## Links

- **GitHub:** [Add your repo link]
- **Team Project:** [Add project documentation link]

---

**Disclaimer:** This is an educational project. Predictions should be verified by agricultural experts.
```

### 6. Upload to Hugging Face Space

Initialize Git and push:

```bash
# Initialize git
git init

# Add Hugging Face Space as remote
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/plant-disease-detection

# Create .gitignore
cat > .gitignore << EOF
__pycache__/
*.pyc
.DS_Store
EOF

# Add files
git add .

# Commit
git commit -m "Initial deployment of Plant Disease Detection app"

# Push to Hugging Face
git push origin main
```

You'll be prompted for credentials:
- **Username:** Your HF username
- **Password:** Your HF access token (create at https://huggingface.co/settings/tokens)

### 7. Verify Deployment

1. Go to your Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/plant-disease-detection`
2. Wait for the build to complete (check "Building" status)
3. Test the app with sample images

## Step-by-Step: Option 2 (HF Model Hub)

### 1. Upload Model to HF Model Hub

```python
from huggingface_hub import HfApi, create_repo

# Create repository for model
repo_id = "YOUR_USERNAME/plant-disease-cnn"
create_repo(repo_id=repo_id, repo_type="model", exist_ok=True)

# Upload model
api = HfApi()
api.upload_file(
    path_or_fileobj="path/to/best_model.pth",
    path_in_repo="pytorch_model.pth",
    repo_id=repo_id,
    repo_type="model"
)

# Create model card
model_card = """
---
license: apache-2.0
tags:
- image-classification
- plant-disease
- pytorch
---

# Plant Disease CNN

CNN model for plant disease detection, trained on PlantVillage dataset.

## Model Details

- **Architecture:** Custom CNN
- **Framework:** PyTorch
- **Classes:** 39 plant disease categories
- **Input Size:** 256x256 RGB images
- **Test Accuracy:** [Add your accuracy]

## Usage

```python
import torch
from huggingface_hub import hf_hub_download

model_path = hf_hub_download(
    repo_id="YOUR_USERNAME/plant-disease-cnn",
    filename="pytorch_model.pth"
)
model.load_state_dict(torch.load(model_path))
```
"""

api.upload_file(
    path_or_fileobj=model_card.encode(),
    path_in_repo="README.md",
    repo_id=repo_id,
    repo_type="model"
)
```

### 2. Modify model_loader.py

```python
# In model_loader.py, set default to load from HF:

def _load_real_model(self, model_name, model_path=None):
    if model_path is None:
        # Download from HF Hub
        from huggingface_hub import hf_hub_download
        model_path = hf_hub_download(
            repo_id="YOUR_USERNAME/plant-disease-cnn",
            filename="pytorch_model.pth"
        )

    # Load model architecture
    model = YourCNNModel(num_classes=39)
    model.load_state_dict(torch.load(model_path, map_location=self.device))

    return model
```

### 3. Deploy to Space

Follow steps 1-7 from Option 1, but you don't need to include the .pth file.

## Step-by-Step: Option 3 (ClearML)

### 1. Get ClearML Credentials

1. Log in to https://5ccsagap.er.kcl.ac.uk/
2. Go to Settings → Workspace → Create new credentials
3. Copy the credentials

### 2. Add Secrets to Space

1. Go to your Space settings
2. Click "Repository secrets"
3. Add three secrets:
   - `CLEARML_API_HOST`: `https://5ccsagap.er.kcl.ac.uk`
   - `CLEARML_API_ACCESS_KEY`: Your access key
   - `CLEARML_API_SECRET_KEY`: Your secret key

### 3. Modify model_loader.py

```python
def _load_real_model(self, model_name, model_path=None):
    if model_path is None:
        # Load from ClearML
        import os
        from clearml import Task, Model

        # Initialize ClearML with environment variables
        Task.init(
            project_name="Plant Disease Detection",
            task_name="UI Model Loading",
            api_host=os.environ.get("CLEARML_API_HOST"),
            api_access_key=os.environ.get("CLEARML_API_ACCESS_KEY"),
            api_secret_key=os.environ.get("CLEARML_API_SECRET_KEY")
        )

        # Get the model
        model_id = "YOUR_MODEL_ID"  # Get this from ClearML
        model_obj = Model(model_id)
        model_path = model_obj.get_local_copy()

    # Load model
    model = YourCNNModel(num_classes=39)
    model.load_state_dict(torch.load(model_path, map_location=self.device))

    return model
```

## Troubleshooting

### Build Failures

**Error: "Out of Memory"**
- Your model might be too large
- Try using a smaller model or quantization

**Error: "Module not found"**
- Check all dependencies are in requirements.txt
- Verify imports work with flat file structure

### Runtime Errors

**Error: "Model file not found"**
- Verify the .pth file is uploaded
- Check file path in model_loader.py

**Error: "Incompatible architecture"**
- Ensure your model class definition matches the saved weights
- Check num_classes=39

## Updating the Deployment

To update your deployed app:

```bash
# Make changes to files
# Commit and push
git add .
git commit -m "Update: description of changes"
git push origin main
```

The Space will automatically rebuild.

## Best Practices

1. **Test locally first:** Always test the app locally before deploying
2. **Use small example images:** Don't upload large images to the repo
3. **Version your models:** Tag model versions in HF Hub or ClearML
4. **Monitor usage:** Check Space analytics to see usage patterns
5. **Update README:** Keep the model card and space README up to date

## Resources

- [HF Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Gradio Documentation](https://gradio.app/docs/)
- [HF Hub Python API](https://huggingface.co/docs/huggingface_hub/)

## Support

If you encounter issues:
1. Check the Space build logs
2. Test locally with the exact same file structure
3. Consult the course TAs
4. Check HF Community forums