PRIVATE_REPO_SETUP.md

# Private Model Repository Setup

Your model repository `gpue/foundationpose-weights` is currently **PRIVATE** 🔒

This document explains your options for using it with your Space.

---

## Quick Answer

**Yes, your Space needs a token** if the model repo stays private.

**No token needed** if you make the repo public.

---

## Option 1: Make Repository Public (Easiest) ✅

### Why Choose This?
- ✅ No token management
- ✅ Simpler Space setup
- ✅ Anyone can use your weights
- ✅ No secrets to manage
- ✅ Faster downloads (no auth overhead)

### How to Make Public

**Via CLI:**
```bash
/Users/georgpuschel/repos/robot-ml/training/.venv/bin/huggingface-cli repo update \
  gpue/foundationpose-weights \
  --visibility public \
  --repo-type model
```

**Via Web:**
1. Go to https://huggingface.co/gpue/foundationpose-weights/settings
2. Under "Change repository visibility"
3. Select "Public"
4. Click "Update repository"

**Then:**
- Just deploy your Space - no additional setup needed!
- Weights will download automatically

---

## Option 2: Keep Private + Add Token 🔒

### Why Choose This?
- 🔒 Control access to weights
- 🔒 Keep it between your Spaces
- 🔒 Track who downloads

### Setup Steps

#### 1. Create HF Token

Go to https://huggingface.co/settings/tokens and create a new token:

- **Name:** `foundationpose-space` (or any name you want)
- **Type:** `Read` (not Write)
- **Permissions:**
  - ✅ Read access to repos

Copy the token (starts with `hf_...`)

#### 2. Add Token to Space

Go to your Space settings:
https://huggingface.co/spaces/gpue/foundationpose/settings

Scroll to **"Repository secrets"** and add:

| Name | Value |
|------|-------|
| `HF_TOKEN` | `hf_xxxxxxxxxxxxx` (your token) |

#### 3. Verify

The code already supports token authentication:
- `download_weights.py` will automatically use `HF_TOKEN` if available
- No code changes needed!

#### 4. Test

Deploy your Space and check the logs:
```
🔒 Using HF_TOKEN for authentication (private repository)
Downloading model weights...
✓ Download complete!
```

---

## Current Status

✅ **Model repo uploaded:** 258MB (2 weight files + configs + README)
✅ **Token support added:** Code updated to use `HF_TOKEN` env var
✅ **Dockerfile configured:** Points to your model repo by default
❌ **Repository visibility:** Currently PRIVATE

---

## Recommendation

For a public inference Space like this, I recommend **making the model repo public**:

**Pros:**
- Simpler setup
- No token management
- Aligns with open-source spirit
- Easier for others to use

**Cons:**
- Anyone can download the weights (but they're from official FoundationPose anyway)

The FoundationPose weights are already public on Google Drive, so there's no confidentiality concern.

---

## Testing

### Verify Current Access

```bash
cd /Users/georgpuschel/repos/robot-ml/foundationpose

# Test without token (will fail if private)
unset HF_TOKEN
/Users/georgpuschel/repos/robot-ml/training/.venv/bin/python verify_weights.py

# Test with token (will work if token valid)
export HF_TOKEN="hf_your_token_here"
/Users/georgpuschel/repos/robot-ml/training/.venv/bin/python verify_weights.py
```

### After Making Public

```bash
# Should work without token
/Users/georgpuschel/repos/robot-ml/training/.venv/bin/python verify_weights.py
```

---

## What I've Done

1. ✅ Uploaded weights to `gpue/foundationpose-weights` (258MB)
2. ✅ Added README.md to model repo with citation and usage
3. ✅ Updated `download_weights.py` to support `HF_TOKEN`
4. ✅ Updated Dockerfile to point to your model repo
5. ✅ Created `verify_weights.py` to test access
6. ✅ Improved error messages for auth failures

---

## Next Steps (Choose One)

### If Making Public:
```bash
# 1. Make repo public
huggingface-cli repo update gpue/foundationpose-weights --visibility public --repo-type model

# 2. Deploy Space
cd /Users/georgpuschel/repos/robot-ml/foundationpose
git add .
git commit -m "Configure for model repo download"
git push origin main

# 3. Done! No token needed.
```

### If Keeping Private:
```bash
# 1. Get token from: https://huggingface.co/settings/tokens

# 2. Add HF_TOKEN to Space secrets:
#    https://huggingface.co/spaces/gpue/foundationpose/settings

# 3. Deploy Space
cd /Users/georgpuschel/repos/robot-ml/foundationpose
git add .
git commit -m "Configure for model repo download"
git push origin main

# 4. Space will authenticate with token automatically
```

---

## FAQ

**Q: What if I forget to add the token?**
A: Space will run in placeholder mode (empty results but API works).

**Q: Can I change visibility later?**
A: Yes! You can switch between public/private anytime.

**Q: Does the token expire?**
A: Tokens can expire if you set an expiration date. Use "No expiration" for Spaces.

**Q: What if someone steals my token?**
A: They can only READ your model repos. Revoke and create a new token if compromised.

**Q: Can I use the same token for multiple Spaces?**
A: Yes! Same token works across all your Spaces.

---

**Recommendation:** Make the repo public for simplicity. The weights are already public via Google Drive anyway.