vonargo/mosAIc

1# Deploying MosAIc as a HuggingFace Static Space2 3The model path — sign in → type a task → a model emits the overlay, billed to the viewer — only runs on a **deployed Space**: it needs the OAuth app HF provisions from the README front-matter. The examples and the Composer work anywhere, but this is how the real thing comes alive. ~10 minutes.4 5## Prereqs6 7- A HuggingFace account (free is fine).8- A **write** access token: [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) → *New token* → type **Write** (or fine-grained with write access to your Spaces). Copy it.9 10## 1. Create the Space11 12[huggingface.co](https://huggingface.co) → your avatar → **New Space**:13 14- **Owner:** you · **Space name:** e.g. `mosaic`15- **SDK:** **Static** (matches `sdk: static` in our README)16- **Visibility:** Public (so it's forkable / credible)17 18Create. HF makes a git repo at `https://huggingface.co/spaces/<you>/mosaic` (with an auto-generated README we'll overwrite).19 20## 2. Push this repo to it21 22From the project root:23 24```bash25git remote add space https://huggingface.co/spaces/<you>/mosaic26git push space main27# username: <your HF username>   password: <paste the write token>28```29 30The Space starts with its own initial commit (an auto README + `.gitattributes`), so the first push may be rejected as non-fast-forward. Override it — ours replaces theirs:31 32```bash33git push space main --force34```35 36(Force is safe here: it's a brand-new Space with nothing worth keeping.)37 38## 3. Confirm it's live + OAuth provisioned39 40- Open `https://huggingface.co/spaces/<you>/mosaic`. Static builds in seconds; you should land on **Start Here**.41- Because `hf_oauth: true` is in the front-matter, HF auto-creates the OAuth app and injects `OAUTH_CLIENT_ID` — so the command-bar **Sign in** goes live (it's deliberately inert locally).42- If sign-in misbehaves inside the embedded preview, open the Space in its **own tab** (the ⛶ button, or `https://<you>-mosaic.hf.space`) — avoids iframe-cookie quirks.43 44## 4. The real test45 46Sign in (HF consent — grant the `inference-api` scope) → type a task → a model emits an overlay and the surface reshapes, billed to **your** account. That's the end-to-end the local build couldn't exercise. Try a few shapes:47 48- `explain this repo` · `plan a weekend in Rome` · `debug a null pointer`49 50## Cost (keep it modest)51 52- Inference Providers gives registered accounts a **small monthly free credit**; beyond it, pay-as-you-go (add a card at [settings/billing](https://huggingface.co/settings/billing)). Check that page for the current allowance.53- Each overlay generation is **cents** — a few-thousand-token prompt + ~1k out. A handful of test calls is well within "not nuts."54- Cheaper still: before deploying, change `MODEL` in `js/llm.js` from `meta-llama/Llama-3.3-70B-Instruct` to a small one (e.g. `meta-llama/Llama-3.1-8B-Instruct`) — much cheaper per call, fine for overlay generation. (Each *viewer* pays their own way regardless.)55 56## Troubleshooting57 58- **Sign in does nothing / "available on the Space" toast** → `OAUTH_CLIENT_ID` isn't injected. Confirm the front-matter (`hf_oauth: true`, `hf_oauth_scopes: [inference-api]`) actually pushed and the Space rebuilt; the OAuth app shows in Space **Settings**.59- **401 / 403 on a task** → the token lacks inference permission; re-consent and confirm the `inference-api` scope was granted.60- **Model/provider error** → `provider: "auto"` routes to whoever serves the model; if none do, switch `MODEL` in `js/llm.js` or pin a `provider`.61- **A weird overlay** → unrelated to deploy; the validator degrades a bad emit to a message by design.62 63## After deploy (parked — don't rabbit-hole)64 65Once it's live and verified, *then* make the profile credible: avatar + bio, a sharp Space short-description, a good thumbnail, pin the Space. That's a separate pass — after delivery, not before.66