# HuggingFace Deployment Checklist

Use this checklist to ensure your project is fully prepared for deployment to HuggingFace Spaces.

## Pre-Deployment Checks

### ✅ Code & Configuration
- [ ] `app.py` exists and has correct entry point
- [ ] `requirements.txt` is updated with all dependencies
- [ ] `src/main.py` has proper type annotations for Gradio compatibility
- [ ] `spaces.yaml` is configured for your resource needs
- [ ] `.gitignore` includes common Python ignore patterns
- [ ] `.gitattributes` has LFS configuration for `.pth` files

### ✅ Documentation
- [ ] `README.md` has HuggingFace Space headers (title, emoji, sdk, python_version, app_file)
- [ ] `README.md` includes usage instructions and feature descriptions
- [ ] `DEPLOYMENT.md` provides comprehensive deployment guide
- [ ] `.env.example` shows available environment variables
- [ ] `LICENSE` file is present (MIT recommended for open-source)

### ✅ Model & Data Files
- [ ] Model weights directory: `data/weights/TO_BE_USED/` exists
- [ ] At least one model file found and accessible (*.pth files)
- [ ] Preprocessing data files exist: `data/preprocess_data/` with:
  - [ ] `label_encoder_pad_20.pickle`
  - [ ] `ohe_pad_20.pickle`
  - [ ] `scaler_pad_20.pickle`
- [ ] Total project size < 25 GB (HF Spaces limit)
- [ ] `.pth` files tracked with Git LFS in `.gitattributes`

### ✅ Dependencies
- [ ] PyTorch version is specified (torch==2.4.1)
- [ ] Gradio version is compatible (gradio==4.44.1)
- [ ] All imports in code are in `requirements.txt`
- [ ] No local-only dependencies or custom packages
- [ ] `opencv-python-headless` used instead of `opencv-python` (for headless servers)

### ✅ Code Quality
- [ ] No hardcoded local paths (use `os.path` relative paths)
- [ ] No local file system access outside of project directory
- [ ] No network calls to external APIs that require authentication
- [ ] Proper error handling for missing model files
- [ ] App handles gracefully when run on CPU-only systems

### ✅ Performance
- [ ] Model loading is lazy (not at import/startup time)
- [ ] Model caching implemented to avoid reloading
- [ ] Queue enabled in Gradio for concurrent request handling
- [ ] Gradio version supports queue() method

### ✅ Git & Version Control
- [ ] Project is a Git repository (`git init` if needed)
- [ ] Remote added for HuggingFace: `git remote add origin https://huggingface.co/spaces/<user>/<space>`
- [ ] All source files are tracked: `git add .`
- [ ] Initial commit created: `git commit -m "Initial commit"`
- [ ] No `.git/config` with wrong remote URL

### ✅ HuggingFace Account Setup
- [ ] HuggingFace account created and verified
- [ ] Git credentials configured: `huggingface-cli login`
- [ ] SSH keys set up (if using SSH) or token saved
- [ ] Write access to target Space confirmed

## Deployment Steps

1. **Create Space on HuggingFace**
   - [ ] Go to https://huggingface.co/new
   - [ ] Name: `skin-lesion-explainability` (or preferred name)
   - [ ] Type: **Space** (not Model or Dataset)
   - [ ] SDK: **Gradio**
   - [ ] Python Version: **3.10**
   - [ ] Visibility: **Public** (or Private)

2. **Clone & Configure**
   ```bash
   [ ] git clone https://huggingface.co/spaces/<username>/<space-name>
   [ ] cp -r /path/to/project/* .
   [ ] cd <space-name>
   ```

3. **Verify Files**
   ```bash
   [ ] ls -la app.py
   [ ] ls -la requirements.txt
   [ ] ls -la README.md
   [ ] ls -la spaces.yaml
   [ ] ls -la src/
   [ ] ls -la data/
   ```

4. **Push to HuggingFace**
   ```bash
   [ ] git add .
   [ ] git commit -m "Initial deployment"
   [ ] git push origin main
   ```

5. **Monitor Build**
   - [ ] Go to https://huggingface.co/spaces/<username>/<space-name>
   - [ ] Check "Runtime" tab for build status
   - [ ] Watch logs for errors
   - [ ] Wait for "Running" status

## Post-Deployment Verification

### ✅ Functional Testing
- [ ] App loads without errors (check Logs tab)
- [ ] Gradio interface appears in browser
- [ ] All input fields render correctly
- [ ] Model dropdown populated with choices
- [ ] Can select metadata groups
- [ ] Image upload works

### ✅ Feature Testing
- [ ] Upload test image succeeds
- [ ] Model inference completes (~30 sec first run, 5-15 sec cached)
- [ ] Attention heatmap generates correctly
- [ ] Metadata CSV preview displays
- [ ] Clear button resets all fields
- [ ] No errors in browser console (F12 to check)

### ✅ Performance Monitoring
- [ ] First inference: 30-60 seconds (acceptable with model loading)
- [ ] Subsequent inferences: 5-15 seconds
- [ ] Queue works with concurrent requests (if multiple users)
- [ ] Memory usage stable (check Runtime/Logs)

## Troubleshooting Guide

### Build Fails with ImportError
**Solution**:
1. Check `requirements.txt` - ensure all imports are listed
2. Read full error in Logs tab
3. Verify Python 3.10 is specified in `spaces.yaml`

### Models Not Found at Runtime
**Solution**:
1. Verify `data/weights/TO_BE_USED/` directory in repository
2. Check file sizes in Logs during startup
3. Ensure `.pth` files are fetched (Git LFS resolution)

### CUDA Out of Memory
**Solution**:
1. Add to `spaces.yaml`: `gpu: "A10G"` 
2. Or remove GPU line for CPU-only
3. Set env var: `PYTORCH_CUDA_PER_PROCESS_MEMORY_FRACTION=0.5`

### App Loads but Inference Fails
**Solution**:
1. Check browser console for errors (F12)
2. Check Logs tab for Python errors
3. Verify all preprocessing files exist in `data/preprocess_data/`

## Optimization Tips

### Speed Up First Inference
- Pin GPU instance in `spaces.yaml` (if budget allows)
- Pre-load one model at startup (modify `inference.py`)

### Reduce Memory Usage
- Use CPU-only mode (remove gpu line in spaces.yaml)
- Quantize models (advanced)

### Handle More Concurrent Users
- Increase `GRADIO_QUEUE_SIZE` in environment
- Add GPU for faster inference
- Implement request timeout

## Security Considerations

- [ ] No API keys/secrets in code
- [ ] Use `.env.example` for configuration templates
- [ ] Avoid downloading from untrusted sources
- [ ] Review third-party packages for vulnerabilities
- [ ] Model predictions should not persist user data

## Documentation

- [ ] README.md has clear feature description
- [ ] DEPLOYMENT.md has step-by-step guide
- [ ] Code includes docstrings (especially inference.py)
- [ ] Comments explain non-obvious logic
- [ ] Example outputs shown in README

## Final Checklist

- [ ] All items above are checked
- [ ] Tested locally: `python app.py` works
- [ ] Committed to git: `git status` shows clean
- [ ] Pushed to HuggingFace: `git push origin main`
- [ ] Build completed: Space shows "Running" status
- [ ] App functional: Can upload, select options, generate predictions
- [ ] Performance adequate: Inference completes in reasonable time
- [ ] Logs clean: No errors in Logs tab

## Support Resources

- **HuggingFace Spaces Docs**: https://huggingface.co/docs/hub/spaces
- **Gradio Documentation**: https://gradio.app/docs
- **PyTorch Hub**: https://pytorch.org/hub/
- **Community Forum**: https://discuss.huggingface.co/

---

**Status**: ⏳ Ready to Deploy (after checking all boxes)

**Last Verified**: March 2026