Initial ECG-FM API deployment

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.10-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    HF_HOME=/root/.cache/huggingface \
+    PORT=7860
+
+RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt && \
+    pip install --no-cache-dir git+https://github.com/bowang-lab/fairseq-signals.git
+
+COPY . .
+EXPOSE 7860
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,153 @@
+# ECG-FM API Deployment
+
+This directory contains the complete setup for deploying the ECG-FM (ECG Foundation Model) as a REST API on Hugging Face Spaces.
+
+## What is ECG-FM?
+
+ECG-FM is a transformer-based foundation model for electrocardiogram analysis, pretrained on 2.5 million ECG samples. It can be used for various ECG interpretation tasks.
+
+## Files Overview
+
+- **`Dockerfile`** - Container configuration for Hugging Face Spaces
+- **`requirements.txt`** - Python dependencies
+- **`server.py`** - FastAPI server with ECG-FM inference endpoints
+- **`test_client.py`** - Test script to verify API functionality
+- **`README.md`** - This documentation
+
+## API Endpoints
+
+### Health Check
+- **GET** `/healthz` - Returns API health status and model loading status
+
+### Root
+- **GET** `/` - Returns basic API information
+
+### Prediction
+- **POST** `/predict` - Main inference endpoint
+
+#### Input Format
+```json
+{
+  "signal": [
+    [0.1, 0.2, 0.3, ...],  // Lead I - 5000 samples
+    [0.2, 0.1, 0.4, ...],  // Lead II - 5000 samples
+    [0.3, 0.2, 0.1, ...],  // Lead III - 5000 samples
+    [0.1, 0.3, 0.2, ...],  // Lead aVR - 5000 samples
+    [0.2, 0.1, 0.3, ...],  // Lead aVL - 5000 samples
+    [0.3, 0.2, 0.1, ...],  // Lead aVF - 5000 samples
+    [0.1, 0.2, 0.3, ...],  // Lead V1 - 5000 samples
+    [0.2, 0.1, 0.4, ...],  // Lead V2 - 5000 samples
+    [0.3, 0.2, 0.1, ...],  // Lead V3 - 5000 samples
+    [0.1, 0.3, 0.2, ...],  // Lead V4 - 5000 samples
+    [0.2, 0.1, 0.3, ...],  // Lead V5 - 5000 samples
+    [0.3, 0.2, 0.1, ...]   // Lead V6 - 5000 samples
+  ],
+  "fs": 500  // Sampling frequency in Hz (optional)
+}
+```
+
+#### Output Format
+```json
+{
+  "output": [...],           // Model predictions
+  "input_shape": [1, 12, 5000],  // Input tensor shape
+  "output_shape": [...]      // Output shape
+}
+```
+
+## Deployment Steps
+
+### 1. Local Testing (Optional)
+```bash
+# Install dependencies
+pip install -r requirements.txt
+pip install git+https://github.com/bowang-lab/fairseq-signals.git
+
+# Run server locally
+python server.py
+
+# Test API
+python test_client.py
+```
+
+### 2. Deploy to Hugging Face Spaces
+1. Create a new Space on [huggingface.co/spaces](https://huggingface.co/spaces)
+   - SDK: Docker
+   - Template: Blank
+   - Hardware: CPU Basic (free tier)
+
+2. Clone the Space repository:
+   ```bash
+   git clone https://huggingface.co/spaces/YOUR_USERNAME/ecg-fm-api
+   cd ecg-fm-api
+   ```
+
+3. Copy all files from this directory to the cloned repo
+
+4. Push to trigger build:
+   ```bash
+   git add .
+   git commit -m "Initial ECG-FM API deployment"
+   git push
+   ```
+
+### 3. Test Deployed API
+```python
+import requests
+import numpy as np
+
+# Replace with your actual Space URL
+SPACE_URL = "https://YOUR_USERNAME-ecg-fm-api.hf.space"
+
+# Test with dummy data
+dummy_signal = np.random.randn(12, 5000).astype(np.float32).tolist()
+payload = {"signal": dummy_signal, "fs": 500}
+
+r = requests.post(f"{SPACE_URL}/predict", json=payload)
+print(r.status_code, r.json())
+```
+
+## Configuration
+
+### Environment Variables
+- **`MODEL_REPO`** - Hugging Face model repository (default: "wanglab/ecg-fm")
+- **`CKPT`** - Checkpoint filename (default: "mimic_iv_ecg_physionet_pretrained.pt")
+- **`CFG`** - Config filename (default: "mimic_iv_ecg_physionet_pretrained.yaml")
+- **`HF_TOKEN`** - Hugging Face token (optional, for private repos)
+
+### Model Checkpoints
+Available checkpoints in `wanglab/ecg-fm`:
+- `mimic_iv_ecg_physionet_pretrained.pt` - Pretrained on MIMIC-IV-ECG and PhysioNet
+- `physionet_finetuned.pt` - Fine-tuned on PhysioNet 2021
+
+## Performance Notes
+
+### Free Tier Limitations (CPU Basic)
+- **Hardware**: 2 vCPUs, 16 GB RAM
+- **Expected latency**: 30 seconds to 2 minutes per inference
+- **Concurrency**: Limited to 1-2 concurrent requests
+- **Cold starts**: Model loads on first request after inactivity
+
+### Optimization Tips
+- Use shorter input windows (e.g., 5 seconds instead of 10)
+- Consider ONNX export for faster CPU inference
+- Use int8 quantization for memory efficiency
+
+## Troubleshooting
+
+### Common Issues
+1. **Build fails on fairseq-signals**: Check build logs, may need specific Git commit
+2. **Out of memory**: Reduce input size or use smaller checkpoint
+3. **Model loading fails**: Verify HF_TOKEN if repo is private
+4. **Slow inference**: Expected on free CPU tier; consider GPU upgrade
+
+### Next Steps
+- **For production**: Move to RunPod GPU for better latency
+- **For optimization**: Export to ONNX, add quantization
+- **For scaling**: Add authentication, rate limiting, input validation
+
+## Support
+
+- ECG-FM Paper: [arxiv.org/abs/2408.05178](https://arxiv.org/abs/2408.05178)
+- ECG-FM Repository: [github.com/bowang-lab/ECG-FM](https://github.com/bowang-lab/ECG-FM)
+- fairseq-signals: [github.com/bowang-lab/fairseq-signals](https://github.com/bowang-lab/fairseq-signals)

deploy.ps1

@@ -0,0 +1,57 @@
+# ECG-FM API Deployment Script (PowerShell)
+# This script helps deploy your ECG-FM API to Hugging Face Spaces
+
+Write-Host "🚀 ECG-FM API Deployment Script" -ForegroundColor Green
+Write-Host "================================" -ForegroundColor Green
+
+# Check if we're in the right directory
+if (-not (Test-Path "server.py") -or -not (Test-Path "Dockerfile") -or -not (Test-Path "requirements.txt")) {
+    Write-Host "❌ Error: Please run this script from the ECG-FM directory containing server.py, Dockerfile, and requirements.txt" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "✅ Found all required files" -ForegroundColor Green
+Write-Host ""
+
+# Check if git is initialized
+if (-not (Test-Path ".git")) {
+    Write-Host "📁 Initializing git repository..." -ForegroundColor Yellow
+    git init
+    git remote add origin https://huggingface.co/spaces/mystic-cbk/ecg-fm-api
+    Write-Host "✅ Git repository initialized" -ForegroundColor Green
+} else {
+    Write-Host "✅ Git repository already exists" -ForegroundColor Green
+}
+
+Write-Host ""
+Write-Host "📋 Current git status:" -ForegroundColor Cyan
+git status
+
+Write-Host ""
+Write-Host "🔧 Adding all files to git..." -ForegroundColor Yellow
+git add .
+
+Write-Host ""
+Write-Host "💾 Committing changes..." -ForegroundColor Yellow
+git commit -m "Update ECG-FM API deployment"
+
+Write-Host ""
+Write-Host "🚀 Pushing to Hugging Face Spaces..." -ForegroundColor Yellow
+git push origin main
+
+Write-Host ""
+Write-Host "✅ Deployment initiated!" -ForegroundColor Green
+Write-Host ""
+Write-Host "📊 Next steps:" -ForegroundColor Cyan
+Write-Host "1. Go to: https://huggingface.co/spaces/mystic-cbk/ecg-fm-api" -ForegroundColor White
+Write-Host "2. Watch the build logs in the 'Build logs' tab" -ForegroundColor White
+Write-Host "3. Wait for build to complete (5-15 minutes)" -ForegroundColor White
+Write-Host "4. Test your API with: python test_client.py" -ForegroundColor White
+Write-Host ""
+Write-Host "🌐 Your API will be available at:" -ForegroundColor Cyan
+Write-Host "   https://mystic-cbk-ecg-fm-api.hf.space" -ForegroundColor White
+Write-Host ""
+Write-Host "📱 Test endpoints:" -ForegroundColor Cyan
+Write-Host "   - Health: https://mystic-cbk-ecg-fm-api.hf.space/healthz" -ForegroundColor White
+Write-Host "   - Root: https://mystic-cbk-ecg-fm-api.hf.space/" -ForegroundColor White
+Write-Host "   - Predict: POST https://mystic-cbk-ecg-fm-api.hf.space/predict" -ForegroundColor White

deploy.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# ECG-FM API Deployment Script
+# This script helps deploy your ECG-FM API to Hugging Face Spaces
+
+echo "🚀 ECG-FM API Deployment Script"
+echo "================================"
+
+# Check if we're in the right directory
+if [ ! -f "server.py" ] || [ ! -f "Dockerfile" ] || [ ! -f "requirements.txt" ]; then
+    echo "❌ Error: Please run this script from the ECG-FM directory containing server.py, Dockerfile, and requirements.txt"
+    exit 1
+fi
+
+echo "✅ Found all required files"
+echo ""
+
+# Check if git is initialized
+if [ ! -d ".git" ]; then
+    echo "📁 Initializing git repository..."
+    git init
+    git remote add origin https://huggingface.co/spaces/mystic-cbk/ecg-fm-api
+    echo "✅ Git repository initialized"
+else
+    echo "✅ Git repository already exists"
+fi
+
+echo ""
+echo "📋 Current git status:"
+git status
+
+echo ""
+echo "🔧 Adding all files to git..."
+git add .
+
+echo ""
+echo "💾 Committing changes..."
+git commit -m "Update ECG-FM API deployment"
+
+echo ""
+echo "🚀 Pushing to Hugging Face Spaces..."
+git push origin main
+
+echo ""
+echo "✅ Deployment initiated!"
+echo ""
+echo "📊 Next steps:"
+echo "1. Go to: https://huggingface.co/spaces/mystic-cbk/ecg-fm-api"
+echo "2. Watch the build logs in the 'Build logs' tab"
+echo "3. Wait for build to complete (5-15 minutes)"
+echo "4. Test your API with: python test_client.py"
+echo ""
+echo "🌐 Your API will be available at:"
+echo "   https://mystic-cbk-ecg-fm-api.hf.space"
+echo ""
+echo "📱 Test endpoints:"
+echo "   - Health: https://mystic-cbk-ecg-fm-api.hf.space/healthz"
+echo "   - Root: https://mystic-cbk-ecg-fm-api.hf.space/"
+echo "   - Predict: POST https://mystic-cbk-ecg-fm-api.hf.space/predict"

requirements.txt

@@ -0,0 +1,7 @@
+fastapi
+uvicorn[standard]
+numpy
+huggingface-hub
+pyyaml
+einops
+torch==2.3.1 --index-url https://download.pytorch.org/whl/cpu

server.py

@@ -0,0 +1,80 @@
+import os
+import numpy as np
+import torch
+from fastapi import FastAPI
+from pydantic import BaseModel
+from typing import List, Optional
+from huggingface_hub import hf_hub_download
+from fairseq_signals.models import build_model_from_checkpoint
+
+# Configuration
+MODEL_REPO = os.getenv("MODEL_REPO", "wanglab/ecg-fm")
+CKPT = os.getenv("CKPT", "mimic_iv_ecg_physionet_pretrained.pt")
+CFG = os.getenv("CFG", "mimic_iv_ecg_physionet_pretrained.yaml")
+HF_TOKEN = os.getenv("HF_TOKEN")  # optional if repo is public
+
+class ECGPayload(BaseModel):
+    signal: List[List[float]]  # shape: [leads, samples], e.g., [12, 5000]
+    fs: Optional[int] = None   # sampling rate (optional)
+
+app = FastAPI(title="ECG-FM API", description="ECG Foundation Model API")
+
+model = None
+
+def load_model():
+    print(f"Loading model from {MODEL_REPO}...")
+    try:
+        ckpt = hf_hub_download(MODEL_REPO, CKPT, token=HF_TOKEN)
+        cfg = hf_hub_download(MODEL_REPO, CFG, token=HF_TOKEN)
+        print(f"Checkpoint: {ckpt}")
+        print(f"Config: {cfg}")
+        
+        m = build_model_from_checkpoint(checkpoint_path=ckpt, config_path=cfg)
+        m.eval()
+        print("Model loaded successfully!")
+        return m
+    except Exception as e:
+        print(f"Error loading model: {e}")
+        raise
+
+@app.on_event("startup")
+def _startup():
+    global model
+    model = load_model()
+
+@app.get("/")
+def root():
+    return {"message": "ECG-FM API is running", "model": MODEL_REPO}
+
+@app.get("/healthz")
+def healthz():
+    return {"status": "ok", "model_loaded": model is not None}
+
+@app.post("/predict")
+def predict(p: ECGPayload):
+    if model is None:
+        return {"error": "Model not loaded"}
+    
+    try:
+        # Convert input to tensor [1, leads, samples]
+        x = torch.tensor(p.signal, dtype=torch.float32).unsqueeze(0)
+        print(f"Input shape: {x.shape}")
+        
+        with torch.no_grad():
+            y = model(x)
+        
+        # Handle model output format
+        if isinstance(y, (list, tuple)):
+            y = y[0]
+        if hasattr(y, "detach"):
+            y = y.detach()
+        
+        out = torch.as_tensor(y).cpu().numpy().tolist()
+        return {"output": out, "input_shape": x.shape, "output_shape": [len(out)]}
+        
+    except Exception as e:
+        return {"error": str(e)}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

test_client.py

@@ -0,0 +1,104 @@
+import requests
+import numpy as np
+import json
+
+def test_api(base_url="http://localhost:7860"):
+    """Test the ECG-FM API endpoints"""
+    
+    print(f"Testing API at: {base_url}")
+    
+    # Test 1: Health check
+    print("\n1. Testing health endpoint...")
+    try:
+        r = requests.get(f"{base_url}/healthz")
+        print(f"   Health status: {r.status_code}")
+        if r.status_code == 200:
+            print(f"   Response: {r.json()}")
+        else:
+            print(f"   Error: {r.text}")
+    except Exception as e:
+        print(f"   Health check failed: {e}")
+        return False
+    
+    # Test 2: Root endpoint
+    print("\n2. Testing root endpoint...")
+    try:
+        r = requests.get(f"{base_url}/")
+        print(f"   Root status: {r.status_code}")
+        if r.status_code == 200:
+            print(f"   Response: {r.json()}")
+        else:
+            print(f"   Error: {r.text}")
+    except Exception as e:
+        print(f"   Root check failed: {e}")
+    
+    # Test 3: Predict endpoint with dummy data
+    print("\n3. Testing predict endpoint...")
+    
+    # Create dummy 12-lead ECG data (12 leads, 5000 samples)
+    # This simulates 10 seconds of ECG at 500 Hz
+    dummy_signal = np.random.randn(12, 5000).astype(np.float32).tolist()
+    
+    payload = {
+        "signal": dummy_signal,
+        "fs": 500
+    }
+    
+    try:
+        r = requests.post(f"{base_url}/predict", json=payload)
+        print(f"   Predict status: {r.status_code}")
+        if r.status_code == 200:
+            result = r.json()
+            print(f"   Success! Output shape: {result.get('output_shape', 'unknown')}")
+            print(f"   Input shape: {result.get('input_shape', 'unknown')}")
+            print(f"   Output length: {len(result.get('output', []))}")
+        else:
+            print(f"   Error: {r.text}")
+    except Exception as e:
+        print(f"   Predict failed: {e}")
+    
+    return True
+
+def test_with_real_data(base_url="http://localhost:7860"):
+    """Test with more realistic ECG-like data"""
+    print("\n4. Testing with realistic ECG-like data...")
+    
+    # Create more realistic ECG-like signal (sine wave with noise)
+    t = np.linspace(0, 10, 5000)  # 10 seconds, 500 Hz
+    realistic_signal = []
+    
+    for lead in range(12):
+        # Create a sine wave with some variation per lead
+        freq = 1.0 + 0.1 * lead  # Different frequency per lead
+        signal = np.sin(2 * np.pi * freq * t) * 0.5
+        # Add some noise
+        signal += np.random.normal(0, 0.1, len(t))
+        realistic_signal.append(signal.tolist())
+    
+    payload = {
+        "signal": realistic_signal,
+        "fs": 500
+    }
+    
+    try:
+        r = requests.post(f"{base_url}/predict", json=payload)
+        print(f"   Realistic data test status: {r.status_code}")
+        if r.status_code == 200:
+            result = r.json()
+            print(f"   Success! Output shape: {result.get('output_shape', 'unknown')}")
+        else:
+            print(f"   Error: {r.text}")
+    except Exception as e:
+        print(f"   Realistic data test failed: {e}")
+
+if __name__ == "__main__":
+    # Test locally first
+    print("=== Testing Local API ===")
+    test_api("http://localhost:7860")
+    
+    # Test with realistic data
+    test_with_real_data("http://localhost:7860")
+    
+    print("\n=== Testing Complete ===")
+    print("\nTo test your deployed Hugging Face Space, update the base_url:")
+    print("test_api('https://mystic-cbk-ecg-fm-api.hf.space')")