# 🚀 Hugging Face Spaces Deployment Guide

## Overview
This guide will walk you through deploying the ECG-FM API directly to Hugging Face Spaces, bypassing local Docker testing.

## ✅ **Pre-Deployment Status**
- **Migration Complete**: All files updated with robust fairseq fallback system
- **HF Ready**: `app.py` created as entry point
- **Docker Optimized**: Dockerfile configured for HF Spaces environment
- **Fallback System**: 4-level fallback ensures reliability

## 🎯 **Deployment Steps**

### Step 1: Create Hugging Face Space
1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
2. Click **"Create new Space"**
3. Configure your space:
   - **Owner**: Your username
   - **Space name**: `ecg-fm-api` (or your preferred name)
   - **SDK**: **Docker** (this is crucial!)
   - **Template**: **Blank**
   - **Hardware**: **CPU Basic** (free tier, sufficient for testing)
   - **License**: Choose appropriate license

### Step 2: Clone the Space Repository
```bash
# Clone your new HF Space
git clone https://huggingface.co/spaces/YOUR_USERNAME/ecg-fm-api
cd ecg-fm-api

# Verify it's a fresh repository
ls -la
```

### Step 3: Copy Migration Files
Copy these files from your current directory to the HF Space repo:

**Essential Files:**
- ✅ `app.py` - HF Spaces entry point
- ✅ `server.py` - Main FastAPI server with fallback logic
- ✅ `requirements.txt` - Dependencies
- ✅ `Dockerfile` - Container configuration
- ✅ `README.md` - Documentation

**Supporting Files:**
- ✅ `test_imports.py` - Testing script
- ✅ `test_client.py` - API testing
- ✅ `.gitattributes` - File handling configuration

### Step 4: Push to Trigger Build
```bash
# Add all files
git add .

# Commit with descriptive message
git commit -m "Complete ECG-FM migration with robust fairseq fallback system

- Migrated from fairseq-signals to main fairseq package
- Implemented 4-level fallback system
- Enhanced error handling and monitoring
- Ready for production deployment"

# Push to trigger automatic build
git push origin main
```

## 🔍 **What Happens Next**

### Automatic Build Process
1. **HF Spaces detects** the Dockerfile and starts building
2. **Dependencies installed** including fairseq with fallback versions
3. **Container built** with Python 3.11 and all requirements
4. **API deployed** and accessible via HF Spaces URL

### Expected Build Time
- **First build**: 10-15 minutes (downloading dependencies)
- **Subsequent builds**: 5-8 minutes (cached layers)

## 🧪 **Testing Your Deployed API**

### Step 1: Check Build Status
1. Go to your HF Space dashboard
2. Monitor the build logs for any errors
3. Wait for "Build completed successfully"

### Step 2: Test API Endpoints
Once deployed, test these endpoints:

#### Health Check
```bash
curl https://YOUR_USERNAME-ecg-fm-api.hf.space/healthz
```
**Expected Response:**
```json
{
  "status": "ok",
  "model_loaded": true,
  "fairseq_available": true
}
```

#### Root Information
```bash
curl https://YOUR_USERNAME-ecg-fm-api.hf.space/
```
**Expected Response:**
```json
{
  "message": "ECG-FM API is running",
  "model": "wanglab/ecg-fm",
  "status": "Model loaded",
  "fairseq_available": true
}
```

#### ECG Prediction
```bash
curl -X POST https://YOUR_USERNAME-ecg-fm-api.hf.space/predict \
  -H "Content-Type: application/json" \
  -d '{
    "signal": [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
    "fs": 500
  }'
```

## 🚨 **Troubleshooting Common Issues**

### Issue 1: Build Fails on fairseq Installation
**Symptoms**: Build fails during fairseq installation
**Solution**: Our fallback system handles this automatically

### Issue 2: Model Loading Fails
**Symptoms**: API starts but model doesn't load
**Check**: `/healthz` endpoint for detailed status
**Solution**: Check HF token if repo is private

### Issue 3: API Not Accessible
**Symptoms**: Build succeeds but endpoints return errors
**Check**: HF Space logs for runtime errors
**Solution**: Verify `app.py` is properly configured

## 📊 **Monitoring and Maintenance**

### Real-time Status
- **Health Endpoint**: `/healthz` shows system status
- **HF Dashboard**: Monitor resource usage and logs
- **API Response**: All responses include `fairseq_available` flag

### Performance Notes
- **Free Tier**: CPU Basic (2 vCPUs, 16 GB RAM)
- **Cold Start**: Model loads on first request after inactivity
- **Latency**: 30 seconds to 2 minutes per inference (expected on CPU)

## 🎉 **Success Indicators**

Your deployment is successful when:
1. ✅ **Build completes** without errors
2. ✅ **API accessible** via HF Spaces URL
3. ✅ **Health endpoint** returns `"model_loaded": true`
4. ✅ **Model inference** works correctly
5. ✅ **Fallback system** reports `"fairseq_available": true`

## 🔄 **Next Steps After Deployment**

1. **Test thoroughly** with various ECG signal inputs
2. **Monitor performance** and resource usage
3. **Scale up** if needed (GPU upgrade for production)
4. **Add features** like authentication, rate limiting
5. **Optimize** with ONNX export for better performance

## 💡 **Pro Tips**

- **Use descriptive commit messages** for easier debugging
- **Monitor build logs** for any dependency issues
- **Test with real ECG data** after deployment
- **Keep HF token secure** if using private model repos
- **Consider GPU upgrade** for production workloads

---

## 🚀 **Ready to Deploy?**

Your ECG-FM API is fully prepared for Hugging Face Spaces deployment! The migration is complete, and all fallback systems are in place.

**Next action**: Create your HF Space and push the code to trigger the automatic build and deployment.

**Questions?** Check the build logs or refer to the comprehensive migration documentation.