MODEL_HUB_SETUP.md

# Setting Up Model Hub for Checkpoints

## Step-by-Step Guide

### Step 1: Create Model Hub Repository

1. **Go to**: https://huggingface.co/new
2. **Select**: "Model" (not Space or Dataset)
3. **Fill in**:
   - **Repository name**: `starflow-3b-checkpoint`
   - **Owner**: `GlobalStudio` (or your username)
   - **Visibility**: Private (recommended) or Public
4. **Click**: "Create repository"

### Step 2: Upload Checkpoint to Model Hub

1. **Go to your Model repository**: 
   https://huggingface.co/GlobalStudio/starflow-3b-checkpoint

2. **Click**: "Files" tab

3. **Click**: "Add file" → "Upload files"

4. **Upload**: `starflow_3B_t2i_256x256.pth` (14GB)
   - Drag and drop or browse
   - Wait for upload (30-60 minutes)
   - ✅ No storage limit issues in Model Hub!

### Step 3: Update app.py (Already Done!)

The app is already configured! Just make sure the repo ID matches:

```python
IMAGE_CHECKPOINT_REPO = "GlobalStudio/starflow-3b-checkpoint"
```

If your repo name is different, update this line in `app.py`.

### Step 4: Test Your Space

1. **Go to your Space**: https://huggingface.co/spaces/GlobalStudio/starflow
2. **Wait for rebuild** (if app.py was updated)
3. **Open the Gradio interface**
4. **Enter a prompt** (no need to upload checkpoint!)
5. **Click "Generate Image"**
6. **First time**: Will download checkpoint (one-time, ~5-10 minutes)
7. **After that**: Uses cached checkpoint (fast!)

## How It Works

1. **First Request**:
   - App checks for local checkpoint → Not found
   - Downloads from Model Hub → `/tmp/checkpoints/`
   - Caches it for future use

2. **Subsequent Requests**:
   - Uses cached checkpoint → Fast!
   - No download needed

3. **Cache Location**: `/tmp/checkpoints/` (persists in Space)

## Benefits

✅ **No storage limit** - Model Hub designed for large files
✅ **Free** - No cost for Model Hub storage
✅ **Automatic caching** - Downloads once, uses forever
✅ **Version control** - Can update checkpoints easily
✅ **Shareable** - Can use across multiple Spaces

## Troubleshooting

### Issue: "Repository not found"
- **Solution**: Make sure repo ID matches exactly: `"username/repo-name"`
- Check: https://huggingface.co/GlobalStudio/starflow-3b-checkpoint exists

### Issue: "Download failed"
- **Solution**: Check internet connection, repo visibility (private repos need auth)
- For private repos, set HF_TOKEN in Space settings

### Issue: "Checkpoint not found"
- **Solution**: Verify filename matches exactly: `starflow_3B_t2i_256x256.pth`
- Check Model Hub Files tab to confirm filename

## For Video Model (Optional)

If you also have the video checkpoint:

1. **Create another Model repo**: `starflow-v-7b-checkpoint`
2. **Upload**: `starflow-v_7B_t2v_caus_480p_v3.pth`
3. **Update app.py**:
   ```python
   VIDEO_CHECKPOINT_REPO = "GlobalStudio/starflow-v-7b-checkpoint"
   ```

## Summary

1. ✅ Create Model Hub repo
2. ✅ Upload checkpoint (14GB, no limit!)
3. ✅ App already configured
4. ✅ Test and enjoy!

The app will automatically download and cache the checkpoint on first use! 🎉