tribunal-kit 9.2.1 → 9.2.4

package/.agent/skills/huggingface-papers/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: huggingface-papers
+description: Look up and read Hugging Face paper pages in markdown, and use the papers API for structured metadata such as authors, linked models/datasets/spaces, Github repo and project page. Use when the user shares a Hugging Face paper page URL, an arXiv URL or ID, or asks to summarize, explain, or analyze an AI research paper.
+---
+
+# Hugging Face Paper Pages
+
+Hugging Face Paper pages (hf.co/papers) is a platform built on top of arXiv (arxiv.org), specifically for research papers in the field of artificial intelligence (AI) and computer science. Hugging Face users can submit their paper at hf.co/papers/submit, which features it on the Daily Papers feed (hf.co/papers). Each day, users can upvote papers and comment on papers. Each paper page allows authors to:
+- claim their paper (by clicking their name on the `authors` field). This makes the paper page appear on their Hugging Face profile.
+- link the associated model checkpoints, datasets and Spaces by including the HF paper or arXiv URL in the model card, dataset card or README of the Space
+- link the Github repository and/or project page URLs
+- link the HF organization. This also makes the paper page appear on the Hugging Face organization page.
+
+Whenever someone mentions a HF paper or arXiv abstract/PDF URL in a model card, dataset card or README of a Space repository, the paper will be automatically indexed. Note that not all papers indexed on Hugging Face are also submitted to daily papers. The latter is more a manner of promoting a research paper. Papers can only be submitted to daily papers up until 14 days after their publication date on arXiv.
+
+The Hugging Face team has built an easy-to-use API to interact with paper pages. Content of the papers can be fetched as markdown, or structured metadata can be returned such as author names, linked models/datasets/spaces, linked Github repo and project page.
+
+## When to Use
+
+- User shares a Hugging Face paper page URL (e.g. `https://huggingface.co/papers/2602.08025`)
+- User shares a Hugging Face markdown paper page URL (e.g. `https://huggingface.co/papers/2602.08025.md`)
+- User shares an arXiv URL (e.g. `https://arxiv.org/abs/2602.08025` or  `https://arxiv.org/pdf/2602.08025`)
+- User mentions a arXiv ID (e.g. `2602.08025`)
+- User asks you to summarize, explain, or analyze an AI research paper
+
+## Parsing the paper ID
+
+It's recommended to parse the paper ID (arXiv ID) from whatever the user provides:
+
+| Input | Paper ID |
+| --- | --- |
+| `https://huggingface.co/papers/2602.08025` | `2602.08025` |
+| `https://huggingface.co/papers/2602.08025.md` | `2602.08025` |
+| `https://arxiv.org/abs/2602.08025` | `2602.08025` |
+| `https://arxiv.org/pdf/2602.08025` | `2602.08025` |
+| `2602.08025v1` | `2602.08025v1` |
+| `2602.08025` | `2602.08025` |
+
+This allows you to provide the paper ID into any of the hub API endpoints mentioned below.
+
+### Fetch the paper page as markdown
+
+The content of a paper can be fetched as markdown like so:
+
+```bash
+curl -s "https://huggingface.co/papers/{PAPER_ID}.md"
+```
+
+This should return the Hugging Face paper page as markdown. This relies on the HTML version of the paper at https://arxiv.org/html/{PAPER_ID}.
+
+There are 2 exceptions:
+- Not all arXiv papers have an HTML version. If the HTML version of the paper does not exist, then the content falls back to the HTML of the Hugging Face paper page.
+- If it results in a 404, it means the paper is not yet indexed on hf.co/papers. See [Error handling](#error-handling) for info.
+
+Alternatively, you can request markdown from the normal paper page URL, like so:
+
+```bash
+curl -s -H "Accept: text/markdown" "https://huggingface.co/papers/{PAPER_ID}"
+```
+
+### Paper Pages API Endpoints
+
+All endpoints use the base URL `https://huggingface.co`.
+
+#### Get structured metadata
+
+Fetch the paper metadata as JSON using the Hugging Face REST API:
+
+```bash
+curl -s "https://huggingface.co/api/papers/{PAPER_ID}"
+```
+
+This returns structured metadata that can include:
+
+- authors (names and Hugging Face usernames, in case they have claimed the paper)
+- media URLs (uploaded when submitting the paper to Daily Papers)
+- summary (abstract) and AI-generated summary
+- project page and GitHub repository
+- organization and engagement metadata (number of upvotes)
+
+To find models linked to the paper, use:
+
+```bash
+curl https://huggingface.co/api/models?filter=arxiv:{PAPER_ID}
+```
+
+To find datasets linked to the paper, use:
+
+```bash
+curl https://huggingface.co/api/datasets?filter=arxiv:{PAPER_ID}
+```
+
+To find spaces linked to the paper, use:
+
+```bash
+curl https://huggingface.co/api/spaces?filter=arxiv:{PAPER_ID}
+```
+
+#### Claim paper authorship
+
+Claim authorship of a paper for a Hugging Face user:
+
+```bash
+curl "https://huggingface.co/api/settings/papers/claim" \
+  --request POST \
+  --header "Content-Type: application/json" \
+  --header "Authorization: Bearer $HF_TOKEN" \
+  --data '{
+    "paperId": "{PAPER_ID}",
+    "claimAuthorId": "{AUTHOR_ENTRY_ID}",
+    "targetUserId": "{USER_ID}"
+  }'
+```
+
+- Endpoint: `POST /api/settings/papers/claim`
+- Body:
+  - `paperId` (string, required): arXiv paper identifier being claimed
+  - `claimAuthorId` (string): author entry on the paper being claimed, 24-char hex ID
+  - `targetUserId` (string): HF user who should receive the claim, 24-char hex ID
+- Response: paper authorship claim result, including the claimed paper ID
+
+#### Get daily papers
+
+Fetch the Daily Papers feed:
+
+```bash
+curl -s -H "Authorization: Bearer $HF_TOKEN" \
+  "https://huggingface.co/api/daily_papers?p=0&limit=20&date=2017-07-21&sort=publishedAt"
+```
+
+- Endpoint: `GET /api/daily_papers`
+- Query parameters:
+  - `p` (integer): page number
+  - `limit` (integer): number of results, between 1 and 100
+  - `date` (string): RFC 3339 full-date, for example `2017-07-21`
+  - `week` (string): ISO week, for example `2024-W03`
+  - `month` (string): month value, for example `2024-01`
+  - `submitter` (string): filter by submitter
+  - `sort` (enum): `publishedAt` or `trending`
+- Response: list of daily papers
+
+#### List papers
+
+List arXiv papers sorted by published date:
+
+```bash
+curl -s -H "Authorization: Bearer $HF_TOKEN" \
+  "https://huggingface.co/api/papers?cursor={CURSOR}&limit=20"
+```
+
+- Endpoint: `GET /api/papers`
+- Query parameters:
+  - `cursor` (string): pagination cursor
+  - `limit` (integer): number of results, between 1 and 100
+- Response: list of papers
+
+#### Search papers
+
+Perform hybrid semantic and full-text search on papers:
+
+```bash
+curl -s -H "Authorization: Bearer $HF_TOKEN" \
+  "https://huggingface.co/api/papers/search?q=vision+language&limit=20"
+```
+
+This searches over the paper title, authors, and content.
+
+- Endpoint: `GET /api/papers/search`
+- Query parameters:
+  - `q` (string): search query, max length 250
+  - `limit` (integer): number of results, between 1 and 120
+- Response: matching papers
+
+#### Index a paper
+
+Insert a paper from arXiv by ID. If the paper is already indexed, only its authors can re-index it:
+
+```bash
+curl "https://huggingface.co/api/papers/index" \
+  --request POST \
+  --header "Content-Type: application/json" \
+  --header "Authorization: Bearer $HF_TOKEN" \
+  --data '{
+    "arxivId": "{ARXIV_ID}"
+  }'
+```
+
+- Endpoint: `POST /api/papers/index`
+- Body:
+  - `arxivId` (string, required): arXiv ID to index, for example `2301.00001`
+- Pattern: `^\d{4}\.\d{4,5}$`
+- Response: empty JSON object on success
+
+#### Update paper links
+
+Update the project page, GitHub repository, or submitting organization for a paper. The requester must be the paper author, the Daily Papers submitter, or a papers admin:
+
+```bash
+curl "https://huggingface.co/api/papers/{PAPER_OBJECT_ID}/links" \
+  --request POST \
+  --header "Content-Type: application/json" \
+  --header "Authorization: Bearer $HF_TOKEN" \
+  --data '{
+    "projectPage": "https://example.com",
+    "githubRepo": "https://github.com/org/repo",
+    "organizationId": "{ORGANIZATION_ID}"
+  }'
+```
+
+- Endpoint: `POST /api/papers/{paperId}/links`
+- Path parameters:
+  - `paperId` (string, required): Hugging Face paper object ID
+- Body:
+  - `githubRepo` (string, nullable): GitHub repository URL
+  - `organizationId` (string, nullable): organization ID, 24-char hex ID
+  - `projectPage` (string, nullable): project page URL
+- Response: empty JSON object on success
+
+## Error Handling
+
+- **404 on `https://huggingface.co/papers/{PAPER_ID}` or `md` endpoint**: the paper is not indexed on Hugging Face paper pages yet.
+- **404 on `/api/papers/{PAPER_ID}`**: the paper may not be indexed on Hugging Face paper pages yet.
+- **Paper ID not found**: verify the extracted arXiv ID, including any version suffix
+
+### Fallbacks
+
+If the Hugging Face paper page does not contain enough detail for the user's question:
+
+- Check the regular paper page at `https://huggingface.co/papers/{PAPER_ID}`
+- Fall back to the arXiv page or PDF for the original source:
+  - `https://arxiv.org/abs/{PAPER_ID}`
+  - `https://arxiv.org/pdf/{PAPER_ID}`
+
+## Notes
+
+- No authentication is required for public paper pages.
+- Write endpoints such as claim authorship, index paper, and update paper links require `Authorization: Bearer $HF_TOKEN`.
+- Prefer the `.md` endpoint for reliable machine-readable output.
+- Prefer `/api/papers/{PAPER_ID}` when you need structured JSON fields instead of page markdown.

package/.agent/skills/huggingface-spaces/README.md

@@ -0,0 +1,9 @@
+# Hugging Face Spaces skill
+
+To add the Hugging Face Space creation skill for your agent, [Install the hf CLI](https://huggingface.co/docs/huggingface_hub/guides/cli#getting-started), login with `hf auth login` and run
+
+```
+hf skills add huggingface-spaces --claude --global
+```
+
+Or just point your agent here https://github.com/huggingface/skills/tree/main/skills/huggingface-spaces and it will know what to do

package/.agent/skills/huggingface-spaces/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: huggingface-spaces
+description: Build, deploy, and maintain applications on Hugging Face Spaces — Gradio / Docker / Static SDKs, ZeroGPU and dedicated hardware, model loading, debugging, buckets, inference providers, community grants. Use whenever the user asks to create or host an app on Hugging Face, port code onto ZeroGPU, fix a Space that won't build or run, or otherwise work with `hf spaces …`, `@spaces.GPU`, Space README frontmatter, or the `spaces` Python package.
+---
+
+# Hugging Face Spaces
+
+Hugging Face Spaces host machine-learning applications. There are 1M+ today; each Space is a git repo. This skill covers creating, building, debugging, and maintaining them.
+
+## 0. Getting ready
+
+Before anything else:
+
+1. Check the `hf` CLI is installed: `which hf`. If not, `pip install -U huggingface_hub`.
+2. Check the user is logged in: `hf auth whoami`. If not, run `hf auth login` — it prints a URL and a one-time code; ask the user to open the URL and enter the code, then login completes automatically (OAuth, no token needed). Alternatively, pass a write-scoped token from https://huggingface.co/settings/tokens with `--token`.
+3. Note `whoami`'s `canPay` and `isPro` flags — they gate hardware choices below. A free (`isPro=False`) account can only host Static Spaces and up to 2 ZeroGPU Spaces.
+
+The `hf-cli` skill teaches an agent every `hf` command and is the recommended companion to this one. Install it with `hf skills add hf-cli` (add `--claude --global` to install for Claude Code as well, user-level).
+
+## 1. What a Space is
+
+A Space is a git repo with three possible SDKs:
+
+- **Gradio** — most Spaces. Python, fast iteration, supports ZeroGPU.
+- **Docker** — arbitrary container. Use when you need a non-Python stack or a pre-built template (Streamlit, Argilla, Shiny, etc. — full list at https://huggingface.co/docs/hub/spaces-sdks-docker). Does **not** support ZeroGPU.
+- **Static** — plain HTML, or a React/Svelte/Vue project built at deploy time. Use for in-browser ML (transformers.js / WebGPU / WebAssembly / onnxruntime-web), project pages, interactive reports, or Spaces that orchestrate other Spaces. No hardware needed.
+
+### Hardware tiers
+
+Static Spaces are free for everyone and need no hardware. **Gradio and Docker Spaces run on compute and require a paid plan to create** — PRO for personal accounts, Team or Enterprise for organizations — with one exception: **free personal accounts in good standing (verified email, account older than 30 days) can host up to 2 ZeroGPU Spaces.**
+
+So on a free account ZeroGPU is the *only* way to host a Gradio Space. `cpu-basic` is not the safe fallback it used to be — it is gated too.
+
+**ZeroGPU (`zero-a10g`)** — dynamic, per-request GPU allocation on NVIDIA RTX PRO 6000 Blackwell (sm_120). Two sizes: `large` (half MIG, 48 GB, 1× quota) and `xlarge` (full, 96 GB, 2× quota). Free for the Space creator; Space visitors consume their own daily quota (~5 min free / 40 min Pro / 60 min Enterprise). **Gradio-only**, **PyTorch-first**. Hosting caps per account: **2** free personal, **10** PRO, **50** Team / Enterprise org.
+
+**`cpu-basic`** — 2 vCPU / 16 GB, no hourly cost but needs a paid plan. For data viz, API-proxy Spaces, small CPU-bound models.
+
+**Dedicated GPU** (T4, L4, A10G, L40S, A100, H200) — billed to the Space creator by the hour. List + pricing: `hf spaces hardware`. Only the creator can attach these, and only if `canPay=True`. Use when ZeroGPU genuinely doesn't fit — non-PyTorch main model with heavy init, very-large-model long-context inference, etc.
+
+If the user needs hardware they can't pay for — a dedicated GPU, or a Gradio Space beyond the free 2-ZeroGPU cap — they can still create a **Static** Space (free for everyone), push the app there, and request a community grant. See [`references/grants.md`](references/grants.md).
+
+For the authoritative reference: https://huggingface.co/docs/hub/spaces-overview
+
+## 2. Look for an existing demo first
+
+Before deciding how to build anything, search for prior art:
+
+```bash
+hf spaces search "<model name or task>" --sdk gradio --limit 10
+```
+
+If someone has built a similar Space, read its `app.py` and `requirements.txt` — that gives you the working pattern. Saves a lot of blind iteration. Mention to the user what you found before committing to an approach.
+
+## 3. Decide SDK and hardware
+
+Follow the user's explicit request first. If they were vague:
+
+- **Default for a public ML demo**: Gradio + ZeroGPU. Use this unless something below applies.
+- **The model's only inference path is non-PyTorch** (ONNX / TF / JAX / vLLM as the MAIN model, with heavy init): dedicated GPU.
+  - But: marginal non-torch tools (a small ONNX preprocessor, a TF utility) inside a torch-main pipeline are fine on ZeroGPU. The hijack only patches torch; init the non-torch lib inside `@spaces.GPU` and pay the short per-call init cost.
+- **Tiny / CPU-bound model, or API-proxy Space**: `cpu-basic` — but it needs a paid plan. On a free account, put it on `zero-a10g` with a no-op decorated function (ZeroGPU requires at least one) and keep the real work outside it — nothing ever requests a GPU, so no quota is burned. See [`references/inference-providers.md`](references/inference-providers.md).
+- **Browser-side ML or project page**: Static.
+- **Container with non-Python stack**: Docker.
+
+### Sourcing the model
+
+- **GitHub repo** — clone locally to read structure. If it already has a Gradio demo, the minimal viable path is to adapt it onto ZeroGPU (see [`references/zerogpu.md`](references/zerogpu.md)). Otherwise: read the README + inference code, prefer the PyTorch path, estimate VRAM (bf16 ≈ `params_B × 2` GB; 48 GB fits ≤24B params at bf16, or much larger with quantization — see [`references/zerogpu.md`](references/zerogpu.md) for quantization on ZeroGPU).
+- **HF model repo** — read its README, follow any linked GitHub.
+- **Paper / blog post** — look for an official or unofficial implementation. Don't reimplement unless trivial or the user explicitly asks.
+- **Vague request** — search Spaces first; surface results.
+
+If the model genuinely won't fit, check **Inference Providers** as an alternative: see [`references/inference-providers.md`](references/inference-providers.md). This avoids hosting the model at all.
+
+## 4. Create the Space
+
+```bash
+hf repos create <namespace>/<name> --type space --space-sdk <gradio|docker|static> \
+    [--flavor zero-a10g|cpu-basic|<paid-flavor>] \
+    [--secrets KEY=val] [--env KEY=val] \
+    --public|--private|--protected \
+    --exist-ok
+```
+
+- `--space-sdk` is required.
+- `--flavor` selects hardware. `zero-a10g` is the (legacy) identifier for ZeroGPU. Omitting it gives `cpu-basic` — which is itself gated behind a paid plan, so on a free account pass `--flavor zero-a10g` explicitly. Run `hf spaces hardware` for the full paid list and pricing.
+- Visibility: `--public` (anyone can view), `--private` (only you), `--protected` (app is reachable but git repo / Files tab is private).
+- `--secrets KEY=val` becomes an environment variable inside the Space and is **not** visible to visitors. Use for API keys, gated-repo tokens (`HF_TOKEN=hf_…`), etc. Can also be set later via `hf spaces secrets set <id> KEY=val`.
+- `--env KEY=val` is **visible to visitors** — use only for non-sensitive config (`GRADIO_SSR_MODE=false`, `PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True`, etc.).
+
+> Note: `hardware:` in the README YAML is silently ignored — hardware is only set via `--flavor` at creation, or later via `hf spaces settings <id> --hardware <name>`.
+
+## 5. Build the app
+
+The Space now exists at `https://huggingface.co/spaces/<namespace>/<name>` but is empty.
+
+### README.md frontmatter
+
+Always required:
+
+```yaml
+---
+title: ...
+emoji: 🚀                # pick something representative
+colorFrom: blue          # red|yellow|green|blue|indigo|purple|pink|gray (only these)
+colorTo: indigo
+sdk: gradio              # gradio | docker | static
+sdk_version: 6.15.1      # latest stable unless you have a reason*
+app_file: app.py         # gradio only (docker / static use Dockerfile / index.html)
+short_description: ...   # ≤ 60 chars (server rejects longer)
+python_version: "3.12"   # ZeroGPU officially supports 3.10.13 and 3.12.12
+startup_duration_timeout: 30m   # default; bump to 1h for big LLMs / heavy downloads
+---
+```
+
+\* Default to the current latest stable, and **look up what that is** (`pip index versions gradio`, or the version a freshly-created Space defaults to) — the number above is a placeholder that goes stale, don't reuse it. Only pin older when the latest genuinely doesn't work for this Space: a custom component pins it, or you're adapting an existing demo and don't want to rewrite for 5.x→6.x breaking changes. If you need a 5.x, pick `5.50.0` (latest of the series; still supports custom components).
+
+All frontmatter options: https://huggingface.co/docs/hub/spaces-config-reference
+
+### Minimal ZeroGPU Gradio app
+
+```python
+import spaces           # MUST come before torch / diffusers / transformers
+import torch
+import gradio as gr
+from diffusers import DiffusionPipeline
+
+pipe = DiffusionPipeline.from_pretrained("<repo>", torch_dtype=torch.bfloat16).to("cuda")
+
+@spaces.GPU(duration=60)
+def generate(prompt: str):
+    """Generate an image from a text prompt."""   # docstring → API / MCP tool description
+    return pipe(prompt).images[0]
+
+gr.Interface(fn=generate, inputs=gr.Text(), outputs=gr.Image()).launch(mcp_server=True)
+```
+
+Three rules — full treatment in [`references/zerogpu.md`](references/zerogpu.md):
+
+1. **`import spaces` before torch / any CUDA-touching import.** It monkey-patches `torch.cuda.*`; once CUDA is initialized in the main process, it's too late.
+2. **Load the model at module scope, `.to("cuda")` eagerly.** ZeroGPU intercepts the call, packs weights to disk, and streams them into VRAM on the first `@spaces.GPU` entry. Lazy loading inside the decorator costs every user.
+3. **Decorate the function Gradio binds.** Estimate `duration` to the realistic worst case (smaller = higher queue priority and tighter quota check). For input-dependent runtime, pass a callable.
+
+### Examples, docstrings, and MCP
+
+- **Add `gr.Examples` whenever it makes sense** (the app takes input and representative inputs exist) — prefer the model/repo's own official examples. Keep example rows to the few inputs a user actually varies (prompt, image) and give the handler defaults for the rest (steps, seed, guidance) so a row is `["a prompt"]`, not a wall of knobs. Use `cache_examples=True, cache_mode="lazy"`. See [`references/gradio.md`](references/gradio.md).
+- **Give every API-triggered function a docstring and type hints.** Each Gradio event handler is exposed over the API; the docstring + signature are what a caller — and the MCP tool schema — sees.
+- **Launch with `demo.launch(mcp_server=True)`** (Gradio 5+) so the Space doubles as an MCP server: each API function becomes an MCP tool described by its docstring and hints.
+
+### requirements.txt
+
+Short version:
+
+- **Do NOT list**: `gradio`, `spaces`, `huggingface_hub` (preinstalled and platform-managed; pinning them causes resolution failures or silently breaks the ZeroGPU runtime).
+- **Do list if you use them**: `torchvision`, `torchaudio` (not preinstalled), plus everything else (`diffusers`, `transformers`, `accelerate`, `sentencepiece`, …).
+- ZeroGPU only accepts torch `2.8.0`, `2.9.1`, `2.10.0`, `2.11.0`. Default to leaving torch unpinned (the runtime preinstalls the latest). Only pin when a dep forces it.
+- For prebuilt CUDA-extension wheels (`flash_attn`, `xformers`, `pytorch3d`, `nvdiffrast`, `diff_gaussian_rasterization`, `torchmcubes`): use the prebuilt Blackwell wheels at `https://huggingface.co/datasets/multimodalart/zerogpu-blackwell-wheels/tree/main/wheels`. Full mapping + caveats in [`references/requirements.md`](references/requirements.md).
+
+### Per-SDK depth
+
+- **Gradio patterns** (themes, `gr.Examples`, streaming, custom HTML components, `gr.Server`): [`references/gradio.md`](references/gradio.md).
+- **Docker**: https://huggingface.co/docs/hub/spaces-sdks-docker. Examples: `hf spaces list --filter docker`.
+- **Static**: https://huggingface.co/docs/hub/spaces-sdks-static. For built SPAs, set `app_build_command: npm run build` and `app_file: dist/index.html` in frontmatter.
+- **ZeroGPU specifics** (decorator semantics, sizing, AoTI, generators, concurrency, pickle / `gr.State` across the worker boundary): [`references/zerogpu.md`](references/zerogpu.md) — read this whenever the Space targets ZeroGPU.
+
+
+## 6. Iterate on the Space, not locally
+
+Try to build a release candidate from the user quest locally and push it — then use the live URL as your test loop. The Space environment is the only one that matters; do not try to test locally. `python3 -m py_compile app.py` is the maximum local check worth doing before pushing.
+
+Push files with `hf upload <namespace>/<name> . --repo-type space`. **`--repo-type space` is required** — `hf upload` defaults to a *model* repo and will otherwise upload to (and silently create) a model repo of the same name. Add `--exclude "**/__pycache__/**"` so local bytecode caches aren't committed into the Space.
+
+Once pushed, pick the cheapest update mechanism for each change — hot-reload for pure Python edits, `hf upload` for code-only files hot-reload can't touch, full rebuild only when `requirements.txt` / `Dockerfile` / README frontmatter actually changed. Full ladder + footguns (hot-reload poisoning factory reboot, runtime.sha lag, etc.) in [`references/debugging.md`](references/debugging.md).
+
+## 7. Verify
+
+Don't trust `RUNNING` alone — the app can be running but broken. Four steps, in order:
+
+**A. Alive?** Stage + hardware:
+```bash
+hf spaces info <ns>/<name> --expand runtime
+```
+
+**B. Logs clean post-boot?** Read the run log to confirm startup finished without warnings or silent fallbacks:
+```bash
+hf spaces logs <ns>/<name> --tail 200
+```
+Look for model-load completion, no import warnings, no "falling back to CPU" / dtype downgrade messages, no `RUNNING` masking a half-broken app.
+
+**C. API actually responds.** With logs still tailing in another terminal (`hf spaces logs <ns>/<name> --follow`), call the endpoint:
+```python
+from gradio_client import Client, handle_file
+import os
+c = Client("<ns>/<name>", token=os.environ["HF_TOKEN"], httpx_kwargs={"timeout": 600})
+print(c.view_api())                    # discover endpoints — don't guess
+result = c.predict(..., api_name="/generate")
+```
+
+**D. Sniff output AND logs.** HTTP 200 ≠ correct output. Check both:
+```python
+head = open(result, "rb").read(16)
+# glTF / \x89PNG / RIFF…WEBP / RIFF…WAVE / [4:8]==b"ftyp" → png/jpg/webp/wav/mp4
+```
+And look at the run log emitted during the call — silent fallbacks (model snapping to a different size, missing optional dep, dtype downgrade) only show up there.
+
+Full smoke-test patterns (streaming endpoints, OAuth-gated Spaces, `gr.Server` custom routes): [`references/debugging.md`](references/debugging.md).
+
+## 8. Permanent storage (buckets)
+
+Spaces are stateless — `/data` is wiped on restart. If the Space needs to persist user uploads, generations, logs, or interact with a long-lived store, mount a **bucket**:
+
+```bash
+hf buckets create <ns>/<bucket-name>                                          # --private optional
+hf spaces volumes set <ns>/<space> -v hf://buckets/<ns>/<bucket-name>:/data   # read-write at /data
+```
+
+Buckets are paid storage; check `canPay` and confirm with the user. Full patterns (read-fast / write-durable, public bucket URLs, model-cache anti-pattern): [`references/buckets.md`](references/buckets.md).
+
+## 9. When things break
+
+Order of operations:
+
+1. Read the logs: `hf spaces logs <id> --build --follow` (build error) or `hf spaces logs <id> --follow` (runtime error). Find the **first** error, not the last.
+2. Grep [`references/known-errors.md`](references/known-errors.md) for the error string. Check if this is a known issue before trying your own fix — most common ZeroGPU / Gradio / dependency errors have a 1–2 line fix there.
+3. Iterate using the cheapest rung from [`references/debugging.md`](references/debugging.md). The vast majority of issues resolve with log-reading + smoke-test loops; interactive dev mode + SSH is a heavy-hammer last resort.
+
+If you solve an error that wasn't in the known-errors list, suggest the user PR it back to this skill so future runs benefit.
+
+---
+
+## Reference index
+
+| When to read | File |
+|---|---|
+| **How ZeroGPU works** + correct patterns (decorator, sizing, pickle, generators, real-time, AoTI) | [`references/zerogpu.md`](references/zerogpu.md) |
+| **Iterate + debug**: logs, rung ladder, smoke testing (and dev mode + SSH as a last resort) | [`references/debugging.md`](references/debugging.md) |
+| **Error-string lookup** — the single place for all error symptoms (Spaces, ZeroGPU, Gradio, deps) | [`references/known-errors.md`](references/known-errors.md) |
+| Pinning deps, picking wheels, torch-family alignment | [`references/requirements.md`](references/requirements.md) |
+| `gr.Examples` (add when it makes sense), themes, custom HTML components, `gr.Server`, MCP server (`mcp_server=True`) | [`references/gradio.md`](references/gradio.md) |
+| Persistent storage, public bucket URLs | [`references/buckets.md`](references/buckets.md) |
+| Community grant requests (hardware the user can't pay for) | [`references/grants.md`](references/grants.md) |
+| Provider proxy (zero-VRAM big LLM via Cerebras / Fireworks / Together / etc.) | [`references/inference-providers.md`](references/inference-providers.md) |
+| **3D Spaces: generation, CUDA extensions, output formats, and model recipes (incl. gaussian splatting)** | [`references/3d-generation.md`](references/3d-generation.md) |

package/.agent/skills/huggingface-spaces/references/3d-cuda-extensions.md

@@ -0,0 +1,109 @@
+# CUDA extensions for 3D Spaces on ZeroGPU
+
+General ZeroGPU rules live in [`zerogpu.md`](zerogpu.md); wheel-tag anatomy and the prebuilt Blackwell wheel dataset live in [`requirements.md`](requirements.md). This file covers what makes 3D generation models harder than diffusion image models: native CUDA/C++ extensions and heavyweight multi-stage pipelines.
+
+## The core constraint: no nvcc at build time
+
+The ZeroGPU build container has **no CUDA toolkit and no GPU**. Any package that compiles CUDA at pip-install time (nvdiffrast, diff-gaussian-rasterization, torchmcubes, spconv-from-source, custom rasterizers, flash-attn sdist) **cannot be installed from `requirements.txt`** the normal way. At *runtime*, a CUDA toolkit is mounted at `/cuda-image/usr/local/cuda-13.0` (nvcc available once the app process is up), and the GPUs are RTX PRO 6000 Blackwell (**sm_120**).
+
+Every working 3D Space uses one of three strategies, in order of preference:
+
+### Strategy 1 — prebuilt wheels in requirements.txt (best)
+
+Direct wheel URLs whose tags match the runtime exactly. Check sources in this order:
+
+1. **The `multimodalart/zerogpu-blackwell-wheels` dataset** — covers `nvdiffrast`, `diff_gaussian_rasterization` (upstream Inria API), `torchmcubes`, `flash_attn`, `xformers`, `pytorch3d`. Cell-picking rules and per-package caveats in [`requirements.md`](requirements.md).
+2. **The official Space for your model family** — its requirements.txt often links wheels for the model's bespoke extensions (e.g. `microsoft/TRELLIS.2` links Blackwell wheels for `flex_gemm`, `nvdiffrast`, `nvdiffrec_render`, `cumesh`, `o_voxel` on GitHub Releases).
+3. **Build one yourself** on any CUDA machine (`TORCH_CUDA_ARCH_LIST="12.0+PTX" pip wheel .`) and host it in a Hub repo or commit it to the Space. No CUDA machine at hand? **Build it on HF Jobs** — pick a devel image matching the target runtime and let the job upload the wheel to a Hub repo:
+
+   ```bash
+   hf jobs run --flavor rtx-pro-6000 --timeout 30m --secrets HF_TOKEN \
+     pytorch/pytorch:2.11.0-cuda13.0-cudnn9-devel \
+     bash -c 'export TORCH_CUDA_ARCH_LIST="12.0+PTX" && \
+              pip wheel --no-build-isolation --no-deps \
+                  git+https://github.com/<org>/<extension>.git -w /tmp/wheels && \
+              pip install -U huggingface_hub && \
+              hf upload <user>/zerogpu-wheels /tmp/wheels wheels --repo-type dataset'
+   ```
+
+   Then reference `https://huggingface.co/datasets/<user>/zerogpu-wheels/resolve/main/wheels/<file>.whl` in requirements.txt, or download and commit the wheel to the Space (Strategy 2). Three things to line up: the image's **torch + CUDA** must match the Space's pins (the tag above matches today's torch 2.11/cu130 ZeroGPU runtime — adjust as it moves), and the image's **Python** sets the wheel's cp tag, so check it matches the Space's `python_version:`. The `rtx-pro-6000` flavor is the same Blackwell sm_120 silicon as ZeroGPU, so the same job can `pip install` the fresh wheel and smoke-test the kernel before uploading; a cheaper flavor also works for compile-only (the arch comes from `TORCH_CUDA_ARCH_LIST`, not the attached GPU). Jobs bill by the minute and require a paid plan — a typical extension builds in well under 30 minutes.
+
+When requirements contain a wheel URL, **pin `torch==` and `python_version:` to match its tags** (see `requirements.md`) — otherwise a base-image bump silently breaks the wheel. A tag mismatch is an `ImportError` (or a kernel-launch crash for a missing arch) at first import.
+
+### Strategy 2 — wheel file committed to the Space repo
+
+Same as Strategy 1 but the `.whl` lives in the Space repo and is installed at module-import time in `app.py` (the Hunyuan3D pattern, for their bespoke `custom_rasterizer`):
+
+```python
+import subprocess, shlex
+subprocess.run(shlex.split("pip install custom_rasterizer-0.1-cp310-cp310-linux_x86_64.whl"), check=True)
+```
+
+Use when you built the wheel yourself and don't want an external URL dependency. The cp tag dictates `python_version:`.
+
+### Strategy 3 — JIT compile at startup (fallback, e.g. for forks with no wheel)
+
+**CPU-only extensions** (pybind11, plain C++): compile at module import with g++ — seconds, no GPU needed. Hunyuan3D's mesh painter:
+
+```python
+os.system("cd /home/user/app/hy3dpaint/DifferentiableRenderer && bash compile_mesh_painter.sh")
+# the script is one line: c++ -O3 -shared -std=c++11 -fPIC $(python -m pybind11 --includes) x.cpp -o x$(python3-config --extension-suffix)
+```
+
+**CUDA extensions**, two variants seen in production:
+
+*At module import, no GPU attached* (TripoSR's torchmcubes before its wheel existed, SF3D's texture_baker). Compiling needs only nvcc/headers, not a GPU — but you **must force the arch list** since nvcc can't probe a device:
+
+```python
+subprocess.run(
+    shlex.split("pip install --no-build-isolation ./texture_baker"),
+    env={**os.environ, "TORCH_CUDA_ARCH_LIST": "12.0+PTX"},
+    check=True,
+)
+```
+
+*Inside a one-shot `@spaces.GPU(duration=600)` setup function called at module import* (`trellis-community/TRELLIS`, `dylanebert/LGM-mini` — the latter for the ashawkey diff-gaussian-rasterization fork that has no wheel). The full pattern: point `CUDA_HOME` at `/cuda-image/usr/local/cuda-13.0`, silence torch's CUDA-version check (torch cu128 vs nvcc 13.0) via a `sitecustomize.py` that no-ops `torch.utils.cpp_extension._check_cuda_version`, `pip install --no-build-isolation --no-deps git+<repo>`, then preload `ctypes.CDLL(".../libcudart.so.13", mode=ctypes.RTLD_GLOBAL)`. Copy it verbatim from one of those Spaces; don't reinvent it.
+
+JIT costs: slower cold starts, a burned GPU allocation (second variant), and breakage when the runtime image moves. Prefer wheels; when you do JIT-build, log clearly so failures are diagnosable from the run logs — **a failed `os.system("pip install ...")` does not kill the app**; it resurfaces later as an ImportError or a silently degraded feature.
+
+## Attention backends on Blackwell
+
+Covered in [`requirements.md`](requirements.md) (flash_attn / xformers wheels, FA3-on-sm_120 crashes) and [`zerogpu.md`](zerogpu.md) → Attention backends. 3D-specific note: when a model exposes a backend env var (`ATTN_BACKEND` in TRELLIS: `xformers|flash_attn|sdpa|naive`), `sdpa` is the zero-dependency safe choice; set it before importing the model library.
+
+## Durations for 3D workloads
+
+Declared duration is billed against quota as requested (not actual runtime) and drives queue priority — declare honestly:
+
+| Task | duration |
+|---|---|
+| Fast-tier single forward (TripoSR, SF3D), splat decode (TripoSplat, LGM) | default 60 (or lower for queue priority) |
+| Hunyuan3D shape-only | 40–60 |
+| TRELLIS / TRELLIS.2 generation; GLB extraction | 120 each |
+| Hunyuan3D shape + RGB texture | 90 |
+| Hunyuan3D-2.1 shape + PBR texture | 180 |
+
+Multi-stage pipelines: split stages into separate `@spaces.GPU` functions **only when the user can act between them** (TRELLIS's generate → re-extract-at-different-quality split). Otherwise one decorated function per user action — each GPU entry costs a queue pass and a pickle round-trip.
+
+## Passing 3D data across the GPU boundary
+
+`@spaces.GPU` functions run in a forked process; args/returns cross via pickle (full rules in [`zerogpu.md`](zerogpu.md)). For 3D specifically:
+
+- **Meshes/splats**: write files to a per-session temp path inside the GPU function, return the path string. Gaussian objects in these codebases are custom classes (CUDA tensors, sometimes locks) — they can never cross the boundary; do preprocess → sample → decode → file-write in one decorated function and return only paths.
+- **Intermediate latents between GPU calls**: CPU numpy dicts in `gr.State` (the TRELLIS pattern), rebuilt on cuda in the next call.
+- **`torch.cuda.empty_cache()` at the end of each GPU function** — 3D pipelines fragment VRAM fast on warm workers.
+- Never decorate bound methods (ml-sharp's `ModelWrapper` holds a non-picklable `threading.RLock`; wrap module-level functions instead).
+
+## Memory
+
+ZeroGPU `large` (48 GB) fits everything covered here (heaviest: Hunyuan3D-2.1 full PBR ~29 GB, TRELLIS.2 ≥24 GB). Don't request `size="xlarge"` unless a real OOM shows in the run logs. `PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True` (before importing torch) is the first fix for fragmentation OOMs on multi-stage pipelines.
+
+## Failure checklist for 3D Spaces
+
+(Also grep [`known-errors.md`](known-errors.md) — general errors are catalogued there.)
+
+1. `ImportError: ...so: undefined symbol` / `cannot open shared object` → wheel-tag mismatch. Re-check torch pin, `python_version:`, CUDA suffix.
+2. `RuntimeError: CUDA error: invalid argument` at first attention call → FA3-on-Blackwell dispatch; see `requirements.md`.
+3. `nvcc not found` in **build** logs → a source CUDA dep leaked into requirements.txt; move it to a wheel or startup compile.
+4. `No space left on device` → offload-disk overflow; too many model variants/stages pinned at module scope.
+5. Hang at first request right after generation completes → a CUDA tensor (often nested in a dict/dataclass) crossed the pickle boundary.
+6. App RUNNING but a feature is missing (e.g. texture button gone) → a startup `pip install`/compile failed silently; read the run log from the top.