PUSH.md

Pushing to ashu-1069/matter on Hugging Face Spaces

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

One-time setup

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

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

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