mlclaw 0.1.0 → 0.2.1

package/assets/hf-tooling/skills/huggingface-zerogpu/references/how-quota-works.md

@@ -0,0 +1,74 @@
+# How ZeroGPU duration and quota are checked
+
+Mechanism for `duration` validation and quota pre-checks. Useful when choosing `duration` values, debugging `illegal duration` vs `quota exceeded` errors, and understanding why the default 60s is pessimistic for short tasks.
+
+For per-tier numerical thresholds (free vs Pro vs Team vs Enterprise quota minutes), the daily quota window length, runs-per-day limits, and pay-as-you-go pricing, see [the ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu) — those values change over time and are deliberately kept out of this skill.
+
+## What `duration` actually requests
+
+Whatever value is passed to `@spaces.GPU(duration=N)` (or the default 60s when unspecified) becomes the `requested duration` the platform checks against. For `xlarge`, the request is doubled internally:
+
+```
+requested = N * 2 if size == "xlarge" else N
+```
+
+So `@spaces.GPU(duration=60, size="xlarge")` is internally a 120-second request — both for the tier-max check and the quota pre-check below.
+
+## Two distinct error modes
+
+Two failure messages can come back from the scheduler before the call runs:
+
+| Error | Trigger | What helps |
+|---|---|---|
+| **`ZeroGPU illegal duration`** | `requested duration > visitor's tier per-call cap` | Lower `duration`. Sign in / upgrade tier. **Waiting does not help.** |
+| **`ZeroGPU quota exceeded`** | `remaining quota < requested duration`, OR runs-per-day cap reached | Wait for the quota window to reset. For Pro / Team / Enterprise, pay-as-you-go credits cover the overflow. |
+
+The error wording for `quota exceeded` includes the explicit numbers, e.g.:
+
+```
+You have exceeded your Pro ZeroGPU quota
+(60s requested vs. 30s left). Try again in 1:23:45.
+```
+
+The comparison is **`requested` vs `remaining`** — not `actual run time` vs `remaining`. A 10-second task left at the default 60s requests 60s of quota; once `remaining < 60s` the call fails even though the actual work would have fit.
+
+## Why the default 60s is pessimistic for short tasks
+
+`DEFAULT_SCHEDULE_DURATION` in the `spaces` package is **60 seconds**. So an undecorated `@spaces.GPU` (or `@spaces.GPU()` with no `duration=`) requests 60s of quota.
+
+For a task that actually takes ~10 seconds:
+
+- The user's 60s quota gets reserved up front.
+- Once their remaining quota drops below 60s, your Space fails for them — even though they could have run many more 10s tasks if the request matched reality.
+- Your call also ranks lower in the queue than equivalent calls declaring smaller durations.
+
+The fix is to declare the realistic duration explicitly:
+
+```python
+@spaces.GPU(duration=15)
+def fast_task(...):
+    ...
+```
+
+For workloads where runtime depends on inputs, use a callable (per-request estimator):
+
+```python
+def estimate_duration(prompt, steps):
+    return int(steps * 3.5)
+
+@spaces.GPU(duration=estimate_duration)
+def variable_task(prompt, steps):
+    ...
+```
+
+This preserves quota for light inputs and reserves more only when needed.
+
+## Quota window: 24h fixed from first use
+
+The quota window's TTL is set when the first call of a fresh window lands and counts down unconditionally — it is not a sliding window, not a calendar-day reset, and not extended by subsequent use. A user who runs a call at 14:00 sees their next reset at 14:00 the following day, regardless of how heavily or lightly they use the Space in between.
+
+For exact tier thresholds, runs-per-day caps, and pay-as-you-go billing rates, see the [ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu).
+
+## Queue priority
+
+The queue is **node-level** — requests from every Space scheduled on the same physical node compete for that node's GPU slots. Among queued requests, **shorter declared `duration` ranks higher**. So tight per-request `duration` estimates serve two goals at once: they preserve the user's quota and move the request up the queue.

package/assets/hf-tooling/skills/huggingface-zerogpu/references/how-zerogpu-works.md

@@ -0,0 +1,50 @@
+# How ZeroGPU works (mechanism)
+
+Conceptual lifecycle of model weights, processes, and worker reuse on ZeroGPU. Useful when reasoning about cold-starts, why module-scope warmup does not carry over to requests, why returning CUDA tensors hangs the call, or why `gr.State` mutations do not persist across the worker boundary.
+
+For numerical limits (concurrency slots per Space, queue priority by tier, etc.), see [the ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu) — those values change over time and are deliberately kept out of this skill.
+
+## Two processes, two lifetimes
+
+A ZeroGPU Space runs as **two separate processes**:
+
+- **Main web process** — long-lived. Imports `app.py`, launches Gradio, stays up for the life of the Space. Holds no VRAM and, after the startup "pack" step, holds no model weights in RAM either.
+- **GPU worker processes** — short-lived. Forked per `@spaces.GPU` request (or reused if warm). Run the task and are eventually killed by the ZeroGPU scheduler when another Space needs the GPU slot. Your Space code never kills its own worker.
+
+## Module-scope `.to("cuda")` is captured to disk
+
+When `import spaces` is active, `model.to("cuda")` at module scope is intercepted. The call is rewritten to `to("cpu")`, so the tensor data physically lives in main process RAM at this point. A "fake" CUDA-presenting tensor is registered alongside the original CPU tensor.
+
+At a startup "pack" step, the backend writes those original CPU tensors to disk via direct I/O (`O_DIRECT`), then frees the corresponding RAM. After pack, the main process holds no model weights anywhere — the data lives only on disk.
+
+This is why module-scope `pipe(...)` / `model.generate(...)` / `model(...)` calls do not run on a real GPU: there is no GPU attached to the main process, and after pack there are no weights to compute against either. Such calls either fail or silently fall back to CPU on the fake tensors.
+
+## Worker init: disk → pinned memory → VRAM
+
+When a `@spaces.GPU` call lands, the scheduler routes it to a worker:
+
+1. **Cold worker** — forked from the main process. The patched torch is unpatched, real CUDA is initialized, and weights are read from the disk offload directory into pinned host memory and streamed onto VRAM through a double-buffered pipeline (essentially `pin_memory().cuda(non_blocking=True)` per batch). This is the "cold-start" cost.
+2. **Warm worker (reused)** — an alive worker bound to the same GPU slot is reused if the scheduler reports it idle. Init is skipped; weights stay on VRAM from the previous call. Subsequent requests within a burst hit this path.
+
+A warm worker is eventually killed by the scheduler when another Space needs the GPU slot. The next call after that point pays the disk → VRAM cost again. Occasional cold-starts on a low-traffic Space are normal.
+
+## Why module-scope warmup does not help
+
+A common instinct is to call `pipe("warmup")` at module scope to "prepare" the model. This does not work on ZeroGPU:
+
+- At module scope, no real GPU is attached. The fake CUDA tensors do not have data after pack, so `pipe(...)` either fails or silently runs on something other than a real GPU.
+- Even if you wrap the warmup in `@spaces.GPU`, the worker that ran the warmup will eventually be killed before the first real user request lands — leaving them with a cold worker anyway.
+
+The right answer is to load eagerly at module scope (`pipe = pipeline(..., device="cuda")`) and accept that the first user request after a quiet period will be a cold worker. Cold-start is fast on ZeroGPU because of the pinned-memory disk pipeline; it is not free, but it is not "minutes of model download" either.
+
+## Why returning CUDA tensors hangs the call
+
+The main process never has a CUDA context — it has no GPU attached and its torch never initialized CUDA. When a worker returns a CUDA tensor, unpickling it in the main process triggers `torch.cuda._lazy_init()`, which would attempt to initialize CUDA in the main process. ZeroGPU blocks this, and the call hangs.
+
+The fix is purely client-side: convert to CPU before returning (`.cpu()`, `.cpu().numpy()`, etc.). See "Process Isolation and Pickle" in SKILL.md.
+
+## Why `gr.State` does not share by reference across the boundary
+
+Worker processes are forked separately and exchange data with the main process via pickle. `gr.State` values cross this boundary on every yield, so mutations inside a `@spaces.GPU` generator are local to the worker until the mutated state is explicitly yielded back. The main process gets a fresh deserialized copy each time — `id()` differs, in-place mutations are invisible across the boundary.
+
+See "Process Isolation and Pickle" in SKILL.md for the practical implications and `references/concurrency.md` for related parallel-handler concerns.

package/assets/hf-tooling/templates/.agents/mcp/huggingface.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "huggingface": {
+      "type": "http",
+      "url": "https://huggingface.co/mcp",
+      "headers": {
+        "Authorization": "Bearer ${HF_TOKEN}"
+      }
+    }
+  }
+}

package/assets/hf-tooling/templates/.env.example

@@ -0,0 +1,5 @@
+# ML Claw exposes these in the gateway runtime.
+HF_TOKEN=
+HUGGINGFACE_HUB_TOKEN=
+OPENCLAW_HF_STATE_BUCKET=
+OPENCLAW_MODEL=huggingface/google/gemma-4-26B-A4B-it

package/assets/hf-tooling/templates/examples/huggingface/README.md

@@ -0,0 +1,16 @@
+# Hugging Face Examples
+
+This workspace starts with the Hugging Face CLI, `hf-discover`, `uv`,
+`huggingface_hub`, `datasets`, and `safetensors` available.
+
+Useful checks:
+
+```bash
+hf auth whoami
+hf repos list
+hf-discover --version
+python -c "import datasets, safetensors; from huggingface_hub import HfApi"
+```
+
+Do not put secrets in this directory. Use the Space or local gateway secrets
+managed by ML Claw.

package/assets/hf-tooling/templates/examples/huggingface/bucket-sync.md

@@ -0,0 +1,19 @@
+# Storage Bucket Sync
+
+The durable ML Claw state bucket is available as:
+
+```bash
+echo "$OPENCLAW_HF_STATE_BUCKET"
+```
+
+List buckets:
+
+```bash
+hf buckets list
+```
+
+Upload a file to an explicit bucket path:
+
+```bash
+hf buckets cp ./local-file.txt "hf://buckets/$OPENCLAW_HF_STATE_BUCKET/examples/local-file.txt"
+```

package/assets/hf-tooling/templates/examples/huggingface/dataset-upload.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+from huggingface_hub import HfApi
+
+
+def main() -> None:
+    api = HfApi()
+    repo_id = "USERNAME_OR_ORG/example-dataset"
+    path = Path("sample.txt")
+    path.write_text("hello from ML Claw\n", encoding="utf-8")
+
+    api.create_repo(repo_id=repo_id, repo_type="dataset", exist_ok=True, private=True)
+    api.upload_file(
+        path_or_fileobj=str(path),
+        path_in_repo="sample.txt",
+        repo_id=repo_id,
+        repo_type="dataset",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/assets/hf-tooling/templates/examples/huggingface/hf-discover.md

@@ -0,0 +1,13 @@
+# hf-discover
+
+Search for Hugging Face resources and agent skills:
+
+```bash
+hf-discover search "train a model" --kind skill --json
+```
+
+If your installed `hf` CLI exposes the discovery extension, this may also work:
+
+```bash
+hf discover "help me train a model" --json
+```

package/assets/hf-tooling/templates/examples/huggingface/runtime-inspection.py

@@ -0,0 +1,9 @@
+import importlib.metadata as metadata
+import os
+
+
+for package in ["huggingface_hub", "datasets", "safetensors"]:
+    print(f"{package}=={metadata.version(package)}")
+
+print("OPENCLAW_MODEL=", os.environ.get("OPENCLAW_MODEL", ""))
+print("OPENCLAW_HF_STATE_BUCKET=", os.environ.get("OPENCLAW_HF_STATE_BUCKET", ""))