HF_MODEL_SETUP.md

# Quick Guide: Setting Up Model Weights on Hugging Face

**TL;DR:** Host your FoundationPose weights in a HF model repository instead of your Space. It's easier, faster, and better.

## Why This Way is Better

| Method | Pros | Cons |
|--------|------|------|
| **HF Model Repo** ✅ | Fast CDN downloads, version control, share across Spaces, no git-lfs needed | Initial setup required |
| Git-LFS in Space | All-in-one repo | Slow, complex, Space bloat, hard to share |
| Manual upload to Space files | Simple | Not version controlled, no programmatic access |

## 5-Minute Setup

### 1. Download Weights (One-Time)

```bash
# Download from Google Drive:
# https://drive.google.com/drive/folders/1GCyGE-LbFGgRC-FuGsF3a1zeBuzsQ1Da

# You need:
# - 2023-10-28-18-33-37/ (~900MB)
# - 2024-01-11-20-02-45/ (~900MB)
```

### 2. Create Model Repo

```bash
pip install huggingface_hub
huggingface-cli login
huggingface-cli repo create foundationpose-weights --type model
```

Or create at: https://huggingface.co/new (select "Model")

### 3. Upload Weights

```bash
cd /path/to/your/downloaded/weights

huggingface-cli upload YOUR_USERNAME/foundationpose-weights \
  ./2023-10-28-18-33-37 \
  2023-10-28-18-33-37

huggingface-cli upload YOUR_USERNAME/foundationpose-weights \
  ./2024-01-11-20-02-45 \
  2024-01-11-20-02-45
```

### 4. Configure Your Space

Add to your Space's environment variables (Settings → Variables and secrets):

```
FOUNDATIONPOSE_MODEL_REPO=YOUR_USERNAME/foundationpose-weights
USE_HF_WEIGHTS=true
USE_REAL_MODEL=true
```

### 5. Deploy

```bash
cd foundationpose
git push origin main
```

Your Space will automatically download weights on first run!

## Verify It Works

Check your Space logs at:
`https://huggingface.co/spaces/YOUR_USERNAME/foundationpose/logs`

Look for:
```
Downloading from Hugging Face Model Repository
Repository: YOUR_USERNAME/foundationpose-weights
✓ Download complete!
```

## Example Model Repo Structure

Your model repo should look like:

```
YOUR_USERNAME/foundationpose-weights/
├── README.md
├── 2023-10-28-18-33-37/
│   ├── model_0000000.pth
│   ├── config.json
│   └── ...
└── 2024-01-11-20-02-45/
    ├── model_0000000.pth
    ├── config.json
    └── ...
```

## Use in Other Projects

Anyone can now use your weights:

```python
from huggingface_hub import snapshot_download

# Download weights
snapshot_download(
    repo_id="YOUR_USERNAME/foundationpose-weights",
    local_dir="./weights"
)
```

## Make It Public or Private?

**Public (Recommended):**
- ✅ Anyone can use (including your Space)
- ✅ No token needed
- ✅ Community can benefit

**Private:**
- ✅ Control access
- ❌ Need HF token in Space secrets
- ❌ More complex setup

For private repos, add `HF_TOKEN` to Space secrets.

## Common Issues

**"Repository not found"**
→ Check name matches: `YOUR_USERNAME/foundationpose-weights`

**"Access denied"**
→ Make repo public or add HF_TOKEN secret

**"Download slow"**
→ First download is cached, subsequent runs are instant

**"Out of space"**
→ Free tier: ~50GB. Upgrade or use smaller models.

## Complete Example

```bash
# Assuming weights downloaded to ~/Downloads/foundationpose-weights/

# 1. Login
huggingface-cli login

# 2. Create repo
huggingface-cli repo create foundationpose-weights --type model

# 3. Upload
cd ~/Downloads/foundationpose-weights
huggingface-cli upload gpue/foundationpose-weights . .

# 4. Done! Configure your Space:
# FOUNDATIONPOSE_MODEL_REPO=gpue/foundationpose-weights
# USE_HF_WEIGHTS=true
# USE_REAL_MODEL=true
```

---

**Full details:** See [UPLOAD_WEIGHTS.md](UPLOAD_WEIGHTS.md) for comprehensive guide.