tribunal-kit 9.2.3 → 9.2.5

package/skills/huggingface-spaces/references/debugging.md

@@ -0,0 +1,236 @@
+# Debugging and iteration
+
+How to iterate cheaply, read logs, and smoke-test. Dev mode + SSH exists as a last resort (covered at the bottom).
+
+## The rung ladder
+
+Pick the cheapest update mechanism that fits the change. Going one rung too high wastes 30 s – 15 min per cycle.
+
+| Rung | When | Command | Cost |
+|---|---|---|---|
+| 1. Hot-reload | Pure Python edit on a Gradio Space (SDK 6.1+), **no new deps** | `hf spaces hot-reload <id> -f app.py` | seconds, no rebuild |
+| 2. `hf upload` | Code-only change hot-reload can't handle (`gr.Server`, Streamlit, Docker entrypoint, non-Python file) | `hf upload <id> . --repo-type space --include '<file>'` | 30–90 s app restart |
+| 3. Full rebuild | `requirements.txt`, `Dockerfile`, README frontmatter, or hardware change | `hf upload <id> . --repo-type space --exclude "**/__pycache__/**" && hf spaces logs <id> --build --follow` | 1–15 min |
+
+`hf upload` defaults to a **model** repo — always pass `--repo-type space`, or it uploads to (and silently creates) a model repo of the same name. Also `--exclude "**/__pycache__/**"` so local bytecode caches don't get committed into the Space.
+| 4. Factory reboot | Container in inconsistent state (broken pip env, etc.) | `hf spaces restart <id> --factory-reboot` | full rebuild + cold start |
+
+### How hot-reload works
+
+`hf spaces hot-reload <id> -f app.py` patches the running Python process in place via `jurigged` (vendored inside the `spaces` package), then commits the change to the repo with a hot-reload marker that tells the platform to skip its usual restart. Seconds, no rebuild.
+
+Applies cleanly to function-body changes and new top-level symbols. Does **not** rerun module-level imports or one-time init — the model was loaded when `app.py` first ran and jurigged won't re-execute that load. New pip deps, README frontmatter, `Dockerfile`, and hardware changes need a full rebuild (rung 3).
+
+Independent of dev mode. Marked experimental in the CLI. Requires Gradio SDK 6.1+.
+
+### Footguns
+
+- **Hot-reload poisons factory reboot.** A commit that's only a hot-reload leaves runtime metadata that's valid only while the hot process is alive. `--factory-reboot` on top of one can fail with `fatal: could not read Username for 'https://huggingface.co'`. Recovery: push any normal `hf upload` commit (even a one-line no-op) first, then restart.
+- **`runtime.sha` lags repo SHA on restart.** `hf upload` succeeds → repo updates → `hf spaces info` keeps reporting the *previous* commit's SHA under `runtime` for several minutes while the new container loads. Poll `runtime.sha`, not just `stage`, and don't issue another restart until it flips.
+- **Concurrent uploads or restart-while-uploading collide.** Wait for one to finish.
+- **"Let me try locally first"** for anything that depends on the Space's Python / torch / CUDA env. The Space environment is the only one that matters. `python3 -m py_compile app.py` is the maximum local check worth doing before pushing.
+
+## Reading logs
+
+```bash
+hf spaces info <id> --expand runtime           # stage at a glance
+hf spaces logs <id> --build --follow           # build log, live
+hf spaces logs <id> --follow                   # run log, live
+hf spaces logs <id> --build --tail 500         # bigger window — default is small
+```
+
+Find the **first** error in the build log, not the last. Cascading errors after the first are noise.
+
+State machine (terminal states in bold):
+
+```
+BUILDING → APP_STARTING → RUNNING
+                      ↘ RUNTIME_ERROR
+        ↘ BUILD_ERROR
+        ↘ CONFIG_ERROR
+```
+
+For stage-specific lookups, see [`known-errors.md`](known-errors.md).
+
+## Smoke-test patterns
+
+A Space isn't done until a `gradio_client` call against the live URL exercises the endpoint end-to-end. Four steps in order — keep `hf spaces logs <id> --follow` running in another terminal throughout, so any silent fallback (model snapping to a different size, missing optional dep, dtype downgrade) surfaces.
+
+### A. Alive?
+
+```bash
+hf spaces info <id> --expand runtime --format json \
+  | python3 -c "import json,sys; r=json.load(sys.stdin)['runtime']; \
+                print(r['stage'], r.get('hardware','?'))"
+# expect: RUNNING zero-a10g
+```
+
+If `requested_hardware` is `cpu-basic` when you wanted GPU, your `--flavor` was rejected silently. Fix with `hf spaces settings <id> --hardware zero-a10g`.
+
+### B. Logs clean post-boot?
+
+```bash
+hf spaces logs <id> --tail 200
+```
+
+Confirm the model finished loading, no import warnings, no "falling back to CPU" / dtype-downgrade messages, no failing health checks the platform forgave. Do this before calling the API — many silent failures (a config typo loading the wrong model, a missing optional dep, a one-time init that errored but didn't crash boot) are only visible here.
+
+### C. API actually functions?
+
+Default — sync `gr.Interface` / `gr.Blocks` / `gr.ChatInterface` / `gr.Server` `@app.api`:
+
+```python
+from gradio_client import Client, handle_file
+import os
+
+c = Client("<ns>/<name>", token=os.environ["HF_TOKEN"],
+           httpx_kwargs={"timeout": 600})   # ≥ @spaces.GPU duration + 60s
+
+print(c.view_api())                          # discover endpoints — don't guess api_name
+
+result = c.predict(
+    handle_file("test.png"),                 # file inputs need handle_file()
+    "short prompt",
+    api_name="/generate",                    # matches @app.api(name=...) or the function name
+)
+```
+
+**Streaming endpoints** (function uses `yield` or `TextIteratorStreamer`) — `.predict()` returns only the final value. Iterate chunks via `.submit()`:
+
+```python
+job = c.submit("short prompt", api_name="/chat")
+for chunk in job: print(chunk, end="")
+# or job.result() for the final value
+```
+
+**`gr.Server` custom `@app.get/post(...)` routes** don't appear in `view_api()`. Hit them with plain HTTP:
+
+```python
+import httpx
+r = httpx.post(f"https://<subdomain>.hf.space/your_route",
+               json={...}, timeout=600,
+               headers={"Authorization": f"Bearer {os.environ['HF_TOKEN']}"})
+```
+
+**OAuth-gated Spaces** (`hf_oauth: true` + `gr.LoginButton`) — anonymous `Client` can't authenticate. Test interactively after sign-in, or capture a session token and pass via `httpx_kwargs={"headers": {...}}`.
+
+**MCP server mode** (`launch(mcp_server=True)`) — different protocol. Use an MCP client.
+
+### D. Output bytes AND logs look right?
+
+HTTP 200 ≠ correct output. Sniff both the returned file and the run log emitted during the call.
+
+```python
+head = open(path, "rb").read(16)
+# b'glTF...'          → glb
+# b'\x89PNG'          → png
+# b'\xff\xd8'         → jpeg
+# b'RIFF...WEBP'      → webp
+# b'RIFF...WAVE'      → wav
+# head[4:8]==b'ftyp'  → mp4
+# b'ply\n'            → ply
+```
+
+For text: non-empty, not all `<think>...</think>` (thinking-model leak), length reasonable. For images: returned dimensions match what was requested (some models snap to nearest preset).
+
+Look at the tailed run log alongside — silent fallbacks (model snapping resolution, missing optional dep falling back to a slower path, dtype downgrade) only show up there.
+
+### What NOT to do
+
+- **Don't launch Playwright / headless browser** to verify backend logic. The Gradio UI calls the same API `gradio_client` does — one `predict` tests both.
+- **Don't build mock-mode + local-server harnesses** before pushing. Local-green ≠ Space-green.
+- **Don't smoke-test with full-budget inputs.** Smallest input that exercises the GPU code path — short prompt, small image, low step count. You're verifying wiring, not quality.
+
+## Iterating on the Space, not locally
+
+The Space env is the only one that matters: Python, torch, CUDA, file paths, env vars, gradio version, the `spaces` hijack all differ from your laptop.
+
+Workflow:
+
+1. Decide SDK + hardware. Write the smallest `app.py` / `Dockerfile` + `requirements.txt` + README frontmatter — just enough that the entry point loads.
+2. Push immediately. Don't build a Playwright / mock harness first.
+3. Once `RUNNING`: verify with `gradio_client` against the real Space. That's your test loop.
+4. Iterate via the cheapest rung.
+
+`python3 -m py_compile app.py` is the maximum local check worth doing.
+
+## Last resort: dev mode + SSH
+
+Use only when:
+
+- A failure is non-deterministic (device-side asserts, OOM under specific shapes, race conditions).
+- You need `CUDA_LAUNCH_BLOCKING=1` or `gdb` to localize a CUDA error.
+- You'd burn 4+ build cycles trying variations from outside.
+
+Reading logs + grepping [`known-errors.md`](known-errors.md) + a tight `gradio_client` smoke loop solves the vast majority of issues. Dev mode is a heavy hammer.
+
+### Prerequisites
+
+1. **PRO / Team / Enterprise plan** — dev mode is a paid feature.
+2. **An SSH key registered on the user's HF profile.** Without this, SSH refuses the connection. If the user doesn't have one yet, they need to:
+   - Generate a keypair locally: `ssh-keygen -t ed25519 -f ~/.ssh/hf_dev -N ''` (no passphrase keeps automation simple; user can pick differently if they prefer).
+   - Add the **public** key (`~/.ssh/hf_dev.pub`) at https://huggingface.co/settings/keys.
+   - Keep the **private** key (`~/.ssh/hf_dev`) on the machine they'll SSH from.
+3. **The Space must be in `RUNNING` or `RUNTIME_ERROR`** before dev mode lets you in — not `BUILD_ERROR`. If it's in build error, push a stub `app.py` that boots cleanly first (e.g. `import gradio as gr; gr.Interface(lambda: 'ok', None, 'text').launch()`), then enable dev mode.
+
+### Enable
+
+No `huggingface_hub` Python wrapper yet — use the REST endpoint:
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://huggingface.co/api/spaces/<ns>/<space>/dev-mode" \
+  -d '{"enabled": true}'
+```
+
+### SSH in
+
+```bash
+ssh -i ~/.ssh/hf_dev -o BatchMode=yes -o StrictHostKeyChecking=accept-new \
+    <ns>-<space>@ssh.hf.space
+```
+
+Username is `<namespace>-<space>` **lowercase**, with `-` replacing `/`. Dots in the Space name become hyphens too.
+
+### Inside the VM
+
+It's a normal container at `/home/user/app/`. You can edit files, `pip install`, run repros, call `@spaces.GPU`-decorated functions interactively (they get a real GPU window).
+
+**`nvidia-smi` in the bare terminal will fail** with `NVML: Unknown Error`. Expected — ZeroGPU only exposes the real GPU inside `@spaces.GPU` calls. Don't assume the GPU is broken.
+
+**Edits in `/home/user/app/` don't survive** a restart, sleep, or dev-mode-disable. Only commits persist.
+
+### Smoke-test the fix inside the container
+
+Before exiting dev mode, verify the fix actually works under a real GPU window:
+
+```bash
+cat > /home/user/app/_devtest.py <<'PY'
+import spaces, torch
+from app import predict   # or whatever your @spaces.GPU function is
+print(predict(<realistic-args>))
+PY
+python3 _devtest.py
+```
+
+### Persist + exit
+
+Commit + push from inside the container (`git config user.email / user.name` first; the HF git remote works). Then disable dev mode:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $HF_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://huggingface.co/api/spaces/<ns>/<space>/dev-mode" \
+  -d '{"enabled": false}'
+```
+
+**Factory-reboot** to apply the pushed state (in dev mode the Space won't rebuild on commits):
+
+```python
+from huggingface_hub import HfApi
+HfApi(token=HF_TOKEN).restart_space("<ns>/<space>", factory_reboot=True)
+```
+
+Then re-run the outside-the-container smoke test. Dev-mode success does **not** guarantee post-rebuild success — different image, different process tree.

package/skills/huggingface-spaces/references/gradio.md

@@ -0,0 +1,200 @@
+# Gradio for Spaces
+
+Patterns and quirks specific to running Gradio inside a Space. Assumes you're already comfortable with stock Gradio components and `gr.Blocks` / `gr.Interface`.
+
+For deeper Gradio API guidance — components, layouts, event listeners, chatbots, the Gradio 5→6 migration — use the dedicated `huggingface-gradio` skill. Install it with `hf skills add huggingface-gradio` (add `--claude --global` to also install for Claude Code, user-level).
+
+For ZeroGPU-specific decorator + worker semantics, see [`zerogpu.md`](zerogpu.md).
+
+## Themes and layout
+
+- Default theme preference: `gr.themes.Citrus()`. Alternatives: `gr.themes.Soft()` or no theme. Pick once and don't over-style.
+- For apps that don't need full-width, constrain with CSS so they're readable on 4K displays:
+  ```python
+  CSS = """
+  #col-container { max-width: 1100px; margin: 0 auto; }
+  .dark .gradio-container { color: var(--body-text-color); }
+  """
+  with gr.Blocks(theme=gr.themes.Citrus(), css=CSS) as demo: ...
+  ```
+  Always include the `.dark .gradio-container` override with `gr.themes.Citrus()` — without it Citrus's dark mode renders dark text on a dark background (text inherits unset colors). The same fix is harmless (and worth keeping) under other themes.
+- Width-cap with `!important` if Gradio 6's own breakpoints fight you — target `main`, `.gradio-container`, and the inner fillable wrapper, otherwise the width caps but goes flush-left.
+
+## Minimal layout most demos converge to
+
+```python
+with gr.Row():
+    prompt = gr.Textbox(show_label=False, placeholder="…", container=False, scale=4)
+    run = gr.Button("Run", variant="primary", scale=1)
+output = gr.Image(...)
+with gr.Accordion("Advanced settings", open=False):
+    ...
+```
+
+`container=False` on the inline Textbox removes the default outer border for a tighter look.
+
+## `gr.Markdown` for the intro
+
+Be succinct. Title, one-line description, a links section. Don't over-explain how it works — that's what the model card is for.
+
+## `gr.Examples`
+
+**Add `gr.Examples` whenever it makes sense** (the app takes user input and representative inputs exist). It's the first thing a visitor clicks and it doubles as an instant smoke test. Prefer examples that mirror the **official examples from the original repo / model card** — the prompts, images, and settings the authors showcase — over inventing your own.
+
+Keep each example row to the **few variables a user actually changes** (the prompt, the input image). Give the handler **default values for everything else** (steps, guidance, seed, …) so an example row is `["a cat on a windowsill"]`, not a wall of knobs. Design the signature so the interesting inputs come first and the rest default:
+
+```python
+@spaces.GPU(duration=60)
+def generate(prompt, seed=42, steps=28, guidance=5.0):   # only `prompt` varies in examples
+    ...
+
+gr.Examples(
+    examples=[
+        ["a cat sitting on a windowsill"],
+        ["mountains at sunset, photorealistic"],
+    ],
+    inputs=[prompt],          # just the varied inputs; the rest use the handler defaults
+    outputs=output,
+    fn=generate,
+    cache_examples=True,
+    cache_mode="lazy",
+)
+```
+
+Why these flags:
+
+- `cache_examples=True` makes example clicks instant (no re-inference per visitor).
+- **`cache_mode="lazy"`** — caches on first user click for each example. **Required on ZeroGPU** (Gradio's default on ZeroGPU is already lazy via `GRADIO_CACHE_MODE=lazy`). Eager would pre-run every example at app startup, but ZeroGPU has no GPU attached at startup — it'd fail and burn the creator's daily quota.
+- `cache_examples=True` silently disables `run_on_click` / `run_examples_on_click`. If your app relies on click-only behavior, set `cache_examples=False`.
+
+The cache key is the **example row's file path**, not a content hash. Regenerating an asset in place serves the stale cached output forever. If you replace example files, bump a `cache_version` marker or wipe `.gradio/cached_examples/<id>/`.
+
+Hot-reload (rung 1) does **not** rebuild the cache. A `cache_version` bump needs a real commit + restart.
+
+## Streaming and generators
+
+`gr.Interface(fn=...)` and `.click(fn=...)` both accept generator functions. Each `yield` pushes a new value:
+
+```python
+@spaces.GPU(duration=120)
+def generate(prompt):
+    yield gr.update(value=None, label="Starting…")
+    for k in range(num_steps):
+        yield gr.update(value=preview(k), label=f"Step {k+1}/{num_steps}")
+    yield gr.update(value=final, label="Done")
+```
+
+Use `gr.update(label=...)` for status narration — feels like a status line without a separate component.
+
+**Caveat**: `gr.Progress(track_tqdm=True)` and `yield` partial outputs fight each other — pick one streaming mechanism.
+
+## Useful UX bits
+
+- `progress=gr.Progress(track_tqdm=True)` in the GPU function gives a free tqdm-driven progress bar.
+- Pair a "Randomize seed" checkbox with the seed input, and write the actually-used seed back so users can re-run deterministically:
+  ```python
+  randomize = gr.Checkbox(label="Randomize seed", value=True)
+  seed = gr.Number(label="Seed", value=0, precision=0)
+
+  @spaces.GPU
+  def gen(..., seed, randomize_seed):
+      if randomize_seed:
+          seed = random.randint(0, 2**31 - 1)
+      seed = int(seed)
+      yield ..., gr.update(value=seed)   # write back into the Seed input
+      ...
+
+  run.click(gen, inputs=[..., seed, randomize], outputs=[..., seed])
+  ```
+
+## Custom HTML components
+
+Stock Gradio components cover 95% of cases. When they don't, `gr.HTML(...)` lets you build contextual custom UI without leaving the Gradio Space (no need to switch to Docker).
+
+Guide: https://www.gradio.app/guides/custom-HTML-components
+Example with a 3D camera-angle picker that makes sense in context: https://huggingface.co/spaces/multimodalart/qwen-image-multiple-angles-3d-camera
+
+Don't reach for this if a stock component covers the need.
+
+## Custom frontends — `gr.Server`
+
+For fully custom frontends with their own HTML/JS, while keeping Gradio's queue + GPU scheduling:
+
+```python
+from gradio import Server
+from fastapi.responses import HTMLResponse
+
+app = Server(title="my-app")
+
+@spaces.GPU(duration=60)
+def _run_gpu(prompt): return inference(prompt)
+
+@app.api(name="generate", concurrency_limit=1, time_limit=180)
+def generate(prompt: str) -> str:
+    return _run_gpu(prompt)        # @app.api wraps, doesn't stack with @spaces.GPU
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage():
+    return open("index.html").read()
+
+demo = app                          # HF runtime expects `demo`
+if __name__ == "__main__":
+    demo.launch(ssr_mode=False)
+```
+
+Required for the custom `/` route to actually serve:
+
+```bash
+hf spaces variables add <ns>/<name> --env GRADIO_SSR_MODE=false
+```
+
+`launch(ssr_mode=False)` is ignored on HF — must be the env var.
+
+Valid `@app.api` kwargs: `name`, `description`, `concurrency_limit`, `concurrency_id`, `queue`, `batch`, `max_batch_size`, `api_visibility`, `time_limit`, `stream_every`.
+
+**Don't stack `@spaces.GPU` and `@app.api`** on the same function — silently breaks request flow. Keep them on separate functions.
+
+**Two-ceiling coordination**: both `@spaces.GPU(duration=N)` and `@app.api(time_limit=M)` apply; the lower wins. Set `time_limit` to your max duration across modes — a too-low `time_limit` kills the request even if GPU duration would have allowed it.
+
+Hot-reload (rung 1 in [`debugging.md`](debugging.md)) does **not** work with `gr.Server` — always `hf upload` or commit.
+
+Reference Space: https://huggingface.co/spaces/huggingface-projects/rf-detr-realtime-webcam
+
+## Slow-startup Gradio (big-model Spaces)
+
+For Spaces that take 10–20 min to load weights:
+
+- Set `startup_duration_timeout: 1h` in README frontmatter (default 30 min).
+- Disable SSR: `hf spaces variables add <id> --env GRADIO_SSR_MODE=false`. Otherwise the SSR health check times out before the app finishes loading.
+
+## Expose the Space as an MCP server
+
+Launch with `demo.launch(mcp_server=True)` (Gradio 5+) so every API endpoint is also exposed as an MCP tool — free, and makes the Space usable by agents. For it to be useful:
+
+- **Every API-triggered function needs a docstring and type hints.** Each Gradio event handler is auto-exposed over the API; Gradio turns the signature into the MCP tool's input schema and the docstring into its description. A function without them still works but surfaces as an opaque, unusable tool.
+- Give the important endpoints stable names (`api_name="generate"` on the `.click(...)`, or `@app.api(name=...)`), so tool names don't churn.
+- MCP mode can pull in extra deps (`gradio[mcp]`); if `launch` complains, see the pin note in [`known-errors.md`](known-errors.md).
+
+```python
+@spaces.GPU(duration=60)
+def generate(prompt: str, seed: int = 42) -> str:
+    """Generate an image from a text prompt.
+
+    Args:
+        prompt: what to generate.
+        seed: RNG seed for reproducibility.
+    """
+    ...
+
+btn.click(generate, inputs=[prompt, seed], outputs=out, api_name="generate")
+demo.launch(mcp_server=True)
+```
+
+## Don't
+
+- `gr.Button(text="X")` — `text=` was removed; use `gr.Button("X")`.
+- `gr.Button(type="button")` — drop the kwarg.
+- `.click(..., _js=share_js)` — renamed to `js=`.
+- `.style(height=...)` — removed in gradio 4+.
+- `gr.ImageMask(brush_color=...)` — kwarg removed.
+- `demo.launch(mcp_server=True)` on gradio 4.x — only valid on 5+.

package/skills/huggingface-spaces/references/grants.md

@@ -0,0 +1,63 @@
+# Community GPU grants
+
+When a user has a good use case (open research demo, hobbyist project, educational tool, institutional showcase) and can't pay for the hardware it needs, they can request a free community grant from Hugging Face.
+
+Free personal accounts already get 2 ZeroGPU Spaces, so a grant is now for the cases that go past that:
+
+- a **dedicated GPU** ZeroGPU can't cover (non-PyTorch main model with heavy init, model too big for 96 GB, always-on serving);
+- a **Gradio Space beyond the free 2-ZeroGPU cap**, without subscribing to PRO.
+
+## The flow
+
+1. **Build the Space.** If the user still has a free ZeroGPU slot, create it as `--flavor zero-a10g` and iterate normally with real inference before applying.
+
+   If they're out of slots, create a **Static** Space instead (`--space-sdk static` — free for everyone) and push the app there; the SDK can be switched to `gradio` in the README frontmatter once the grant lands. Code the app for ZeroGPU anyway — `import spaces`, `@spaces.GPU`, module-scope `.to("cuda")`. In this mode you **can't iterate-with-real-inference** before the grant, so just get the code in place and submit.
+
+   For a dedicated-GPU grant, get the app to BUILD cleanly and reach `RUNNING` (even if the runtime would OOM on real input), then submit.
+
+2. **Submit a Community Tab discussion** on the Space. Title:
+
+   ```
+   Apply for a GPU community grant: <Personal|Company|Academic> project
+   ```
+
+   Pick the closest fit. Body:
+
+   ```
+   Description of the app: one paragraph on what it does + who it's for.
+   Justification: one paragraph on why this should run on ZeroGPU
+   (open-source, research, educational, etc.). 
+   ```
+
+   If the user didn't give you a justification, a reasonable default is "Public open-source demo, can't cover the hardware cost — happy to provide more context if helpful."
+
+3. **Wait.** Open and publicly-facing applications by researchers, tinkerers, and institutions are typically approved. Approval can take days.
+
+4. **Once approved**, the hardware is attached automatically — no code change needed (a Static holding Space still needs its `sdk:` flipped to `gradio`). The user comes back and you can iterate / refine with real GPU access.
+
+## When to suggest this
+
+- The use case is a clear public ML demo (not a private tool) and the user is out of free ZeroGPU slots.
+- The model needs more than ZeroGPU offers — beyond 48 GB `large` / 96 GB `xlarge`, or a non-PyTorch runtime — and the user can't pay.
+
+## When NOT to suggest this
+
+- The user is on a free account and this is their 1st or 2nd Space — they can create it on ZeroGPU directly; no grant needed.
+- Private / commercial / closed-source projects — push the user toward PRO instead.
+- `canPay=True` users who just need paid hardware — they can attach it directly.
+
+## Posting the request programmatically
+
+```python
+from huggingface_hub import HfApi
+
+api = HfApi(token="hf_...")
+api.create_discussion(
+    repo_id="<ns>/<space>",
+    repo_type="space",
+    title="Apply for a GPU community grant: Personal project",
+    description="<description and justification>",
+)
+```
+
+The Community Tab must be enabled on the Space (default — keep it on).

package/skills/huggingface-spaces/references/inference-providers.md

@@ -0,0 +1,97 @@
+# Inference Providers — when not to host the model
+
+Some Spaces don't need a GPU at all. If the model is available through HF Inference Providers (Cerebras, Fireworks, Together, Replicate, OpenRouter, etc.), the Space can be a thin Gradio shell that proxies to a hosted endpoint:
+
+- Zero VRAM, no real work inside `@spaces.GPU`, no model download.
+- Works for models too large to fit on ZeroGPU (120B+).
+- No GPU at all — see [Hardware](#hardware) below for which flavor to pick.
+
+## When to use this pattern
+
+- **Stateless chat or text completion** with a big model.
+- **The user wants a public demo of a frontier-scale model** that obviously doesn't fit on a single 48 GB MIG.
+- **The user wants to ship something fast** without worrying about quantization / sharding.
+
+## When NOT to use this pattern
+
+- The model isn't available on any Inference Provider. Check with:
+  ```bash
+  curl "https://huggingface.co/api/models/<ns>/<repo>?expand[]=inferenceProviderMapping"
+  ```
+- The Space needs **custom decoding** (special sampling, tool use, retrieval, anything stateful or interactive across calls).
+- The Space needs **multimodal** beyond what the provider exposes.
+- The user explicitly wants to own the inference stack (model loading, decoding, performance tuning).
+
+For those, host the model yourself on ZeroGPU — see [`zerogpu.md`](zerogpu.md).
+
+## Two billing modes
+
+Choose based on who pays for inference.
+
+### Mode A — Space creator pays (simple)
+
+Set `HF_TOKEN` as a Space secret. The Space uses `InferenceClient` directly. Every visitor's call is billed to the Space creator's account.
+
+```python
+import os, gradio as gr
+from huggingface_hub import InferenceClient
+
+client = InferenceClient(api_key=os.environ["HF_TOKEN"], provider="fireworks-ai")
+
+def chat(msg, history):
+    return client.chat_completion(
+        model="<org>/<model>",
+        messages=[*history, {"role": "user", "content": msg}],
+        max_tokens=512,
+    ).choices[0].message.content
+
+gr.ChatInterface(chat).launch()
+```
+
+Use when you want users to "just click and try it" — no sign-in friction. Cost is on you.
+
+### Mode B — Visitor pays (recommended for public demos)
+
+`gr.LoginButton` + `gr.load("models/...")` with `accept_token=button`. Each visitor signs in with their HF account; inference is billed to **their** account.
+
+```python
+import gradio as gr
+
+with gr.Blocks(fill_height=True) as demo:
+    with gr.Sidebar():
+        button = gr.LoginButton("Sign in")
+    gr.load("models/<org>/<model>", accept_token=button, provider="fireworks-ai")
+demo.launch()
+```
+
+README frontmatter needs:
+
+```yaml
+hf_oauth: true
+hf_oauth_scopes:
+  - inference-api
+```
+
+This is the **recommended pattern for public demos** — sustainable cost-wise, and visitors get to use their own provider quotas (which most have paid for or get free).
+
+## Hardware
+
+No GPU needed, so `cpu-basic` is the natural fit — but it requires a paid plan.
+
+On a free account, create the Space with `--flavor zero-a10g` instead. ZeroGPU refuses to start without at least one decorated function, so add a no-op one and leave the provider calls outside it:
+
+```python
+import spaces
+
+@spaces.GPU(duration=1)
+def _noop():  # ZeroGPU requires ≥1 decorated function; never called
+    pass
+```
+
+Nothing ever requests a GPU, so no quota is burned. Just remember the Space still counts against the free 2-Space ZeroGPU cap — don't spend a slot here if the user is saving it for a real GPU demo.
+
+## Anti-pattern: `@spaces.GPU` wrapping a provider call
+
+If you do use Inference Providers, do **not** wrap the call in `@spaces.GPU`. The decorator reserves a GPU slot on your Space for the full `duration=`, but the function does no GPU work — just an HTTP call out. You burn your own ZeroGPU quota for nothing.
+
+Whatever hardware a provider-proxy Space sits on, no provider call belongs inside `@spaces.GPU`.