PUSH.md

# Pushing to `ashu-1069/matter` on Hugging Face Spaces

Space URL: https://huggingface.co/spaces/ashu-1069/matter

## One-time setup

```bash
cd space
bash sync.sh                 # pulls matter/ + spec/ + examples/ from upstream

git init
git remote add origin https://huggingface.co/spaces/ashu-1069/matter
git fetch origin

# pull the existing Space contents (HF auto-creates a README on Space creation)
# then overlay our files
git checkout -b main origin/main 2>/dev/null || git checkout -b main

# auth — pick one:
#   1) huggingface-cli login            (token with write to ashu-1069)
#   2) embed token in remote URL:
#      git remote set-url origin https://ashu-1069:HF_TOKEN@huggingface.co/spaces/ashu-1069/matter
```

If `git fetch origin` fails with auth errors:
- Get a write token: https://huggingface.co/settings/tokens (role: `write`)
- `huggingface-cli login` and paste it

If the Space already has a `README.md` from creation, our `README.md` will overwrite it — that's expected.

## Every push

```bash
cd space
bash sync.sh
git add -A
git commit -m "matter: <what changed>"
git push origin main
```

The Space rebuilds automatically. First build takes ~5 min (torch + transformers).
Cold-start GPU load adds ~30 s on the first **Live** click after that.

## Space settings to set in the HF UI

- **Hardware**: ZeroGPU (free; spins up an H200 on demand)
- **Visibility**: Public (for the Impact Challenge submission)
- **Variables and secrets** (all optional):
  - `MATTER_MODEL_ID` — override default `google/gemma-4-E2B-it`
  - `MATTER_LORA_ID` — A/B the E1 QLoRA adapter (off by default; it regressed
    on real NYC images)
  - `MATTER_MAX_NEW_TOKENS` — default `512`

## Sanity-check locally before pushing

```bash
cd space
bash sync.sh
uv venv
uv pip install -r requirements.txt
uv run python app.py
# → http://127.0.0.1:7860
```

Demo mode works without a GPU. Live mode needs a CUDA GPU locally — easier to
just push and test on the Space.

## Authorization troubleshooting

If `git push` fails with `403 Forbidden`:
1. Verify you own the Space owner namespace `ashu-1069` (the username with the
   hyphen — not `ashu1069`).
2. Token must have **write** scope, not just read.
3. If using `huggingface-cli login`, run `huggingface-cli whoami` to confirm the
   token resolves to `ashu-1069`.
4. As a fallback, embed the token in the remote URL:
   ```
   git remote set-url origin https://ashu-1069:hf_xxx@huggingface.co/spaces/ashu-1069/matter
   ```