QUICKSTART.md

# Quick Start: Fix ZeroGPU CUDA Error

## The Problem
```
RuntimeError: CUDA has been initialized before importing the `spaces` package.
```

## The Solution (Applied ✅)

### 1. Import `spaces` FIRST in app.py
```python
# BEFORE (❌ Wrong):
import os
import torch
import spaces  # Too late!

# AFTER (✅ Fixed):
import spaces  # MUST BE FIRST!
import os
import torch
```

### 2. Add GPU Decorators
```python
@spaces.GPU
def sam_refine(...):
    initialize_models()  # Lazy load
    # ... processing

@spaces.GPU(duration=120)  # 2 minutes for video processing
def run_videomama_with_sam2(...):
    initialize_models()  # Lazy load
    # ... processing
```

### 3. Lazy Load Models
```python
# Don't load at startup:
if __name__ == "__main__":
    # initialize_models()  # ❌ Remove this
    demo.launch()

# Load on first use instead:
@spaces.GPU
def inference_function():
    initialize_models()  # ✅ Load here
    # ...
```

### 4. Update requirements.txt
```txt
spaces  # Add this at the top
torch>=2.0.0
gradio==4.31.0
# ... rest
```

### 5. Update README.md
```yaml
---
hardware: zero-a10g  # For ZeroGPU Pro
sdk_version: 4.31.0
---
```

## All Changes Applied ✅

The following files have been updated:
- ✅ `app.py` - Added `import spaces` at top, GPU decorators, lazy loading
- ✅ `requirements.txt` - Added `spaces` package
- ✅ `README.md` - Added hardware configuration

## Deploy Now

Simply push to your Hugging Face Space:

```bash
git add app.py requirements.txt README.md
git commit -m "Fix ZeroGPU CUDA initialization error"
git push
```

## Test Result

Your Space should now:
1. ✅ Start without CUDA errors
2. ✅ Allocate GPU only when needed (clicks or processing)
3. ✅ Work with ZeroGPU Pro subscription

## Need Help?

See `HUGGINGFACE_DEPLOY.md` for detailed documentation.