rsc-universal 0.1.1

package/skills/replicate/references/cog-packaging.md

@@ -0,0 +1,89 @@
+# Cog packaging — full reference
+
+Cog (open source, https://github.com/replicate/cog · https://cog.run) packages an ML model into a
+production Docker container. Two files drive it: `cog.yaml` (build + which predictor) and a Python
+module with a `BasePredictor`. `cog predict` runs it locally; `cog push r8.im/owner/model` builds and
+ships it, and Replicate auto-generates the API server on its GPU cluster. Building needs Docker.
+
+## Full `cog.yaml`
+
+```yaml
+build:
+  gpu: true                       # provisions a CUDA base image; omit/false for CPU-only
+  python_version: "3.11"          # quoted — "3.10" not 3.10
+  system_packages:                # apt packages baked into the image
+    - "ffmpeg"
+    - "libgl1-mesa-glx"
+  python_packages:                # pinned pip deps
+    - "torch==2.4.0"
+    - "transformers==4.44.0"
+    - "pillow==10.4.0"
+  run:                            # extra build steps, run after pip install
+    - "pip install --no-cache-dir flash-attn==2.6.3"
+predict: "predict.py:Predictor"   # module path : class name
+```
+
+Notes:
+- Quote `python_version` and every package version. Unpinned packages make builds non-reproducible.
+- `build.gpu: true` selects a CUDA image automatically — do not hand-install CUDA in `run:`.
+- `system_packages` is apt; `python_packages` is pip; `run:` is for anything neither covers.
+- For LLMs, you can add a `concurrency.max` to allow batched concurrent predict calls per instance.
+
+## Full `predict.py`
+
+```python
+from cog import BasePredictor, Input, Path
+import torch
+
+class Predictor(BasePredictor):
+    def setup(self) -> None:
+        """Runs ONCE per instance boot. Load weights here."""
+        self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        self.model = torch.load("weights/model.pth", map_location=self.device)
+        self.model.eval()
+
+    def predict(
+        self,
+        prompt: str = Input(description="Text prompt"),
+        guidance: float = Input(description="Guidance scale", default=7.5, ge=1.0, le=20.0),
+        seed: int = Input(description="Random seed; -1 = random", default=-1),
+    ) -> Path:
+        """Runs PER request. Keep it pure inference."""
+        if seed == -1:
+            seed = int(torch.randint(0, 2**31 - 1, (1,)).item())
+        result = self.model.generate(prompt, guidance=guidance, seed=seed)
+        out = Path("/tmp/out.png")
+        result.save(out)
+        return out                  # Cog uploads it and returns a FileOutput to callers
+```
+
+Rules that matter:
+- **`setup()` once, `predict()` every call.** Weight loading, model compilation, and warmup belong in
+  `setup()`. Putting them in `predict()` makes every request pay the load cost.
+- Type every `predict()` argument and wrap it in `Input(...)` — Cog turns these into the model's API
+  schema, validation, and the website's input form. Use `default=`, `ge`/`le`, `choices=[...]`.
+- Return `Path` for file outputs (Cog uploads them), or a JSON-serializable value / `list[Path]`.
+- Bake weights into the image or download them in `setup()` to a cached path — never per request.
+
+## Local run, build, push
+
+```bash
+cog predict -i prompt="a cat" -i guidance=6.0     # run locally end to end (needs Docker)
+cog build -t my-model                              # build the image without pushing
+cog push r8.im/owner/model                         # build + push; creates a new version
+cog login                                          # if you haven't authenticated the CLI
+```
+
+Each `cog push` creates an immutable **version** (a SHA). Pin to a specific version in production calls
+(`owner/model:<version>`) so a later push does not silently change behavior; deployments target a
+version explicitly.
+
+## Common build failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `cog push` hangs / OOM on build | Huge weights copied into image | Download weights in `setup()` instead of baking, or use a slimmer base |
+| CUDA / torch version mismatch | `gpu: true` CUDA vs pinned torch wheel | Pin a torch build that matches the CUDA the image ships |
+| `predict.py:Predictor` not found | Wrong module path or class name in `predict:` | Match `file.py:ClassName` exactly |
+| Local works, push image broken | Relying on host files not in the image | Ensure weights/assets are in the build context or fetched in `setup()` |
+| `flash-attn` build error | Compiled against missing toolchain | Install via `run:` after torch, or use a prebuilt wheel |

package/skills/replicate/references/deployments-api.md

@@ -0,0 +1,87 @@
+# Deployments API — full reference
+
+Source: https://replicate.com/docs/topics/deployments (accessed 2026-06-02).
+
+A deployment is a private, dedicated endpoint pointing at one model version. It autoscales from zero
+to hundreds of instances, keeps a warm floor if you ask, caps spend with a ceiling, and lets you swap
+hardware without touching `predict.py`. Updates roll out with no downtime.
+
+## Config fields
+
+| Field | Meaning | Cost/latency effect |
+|---|---|---|
+| `model` | `owner/model` the deployment serves | — |
+| `version` | the immutable version SHA to run | pin it; bump via update |
+| `hardware` | e.g. `gpu-t4`, `gpu-a100-large`, `gpu-h100` | bigger = faster + pricier |
+| `min_instances` | warm floor (>=0) | >0 kills cold starts but bills idle 24/7 |
+| `max_instances` | concurrency ceiling | the hard spend cap under spikes |
+
+Start `min_instances: 0` (scale to zero) and only raise it when measured cold-start latency hurts
+users. Set `max_instances` deliberately — it is your protection against a traffic spike becoming a
+surprise bill.
+
+## Create / update via HTTP API
+
+```bash
+# create
+curl -s -X POST https://api.replicate.com/v1/deployments \
+  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-endpoint",
+    "model": "owner/model",
+    "version": "<version-sha>",
+    "hardware": "gpu-a100-large",
+    "min_instances": 1,
+    "max_instances": 5
+  }'
+
+# update (rolling — bump version or rescale with no downtime)
+curl -s -X PATCH https://api.replicate.com/v1/deployments/owner/my-endpoint \
+  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"version": "<new-version-sha>", "min_instances": 2}'
+```
+
+## Via the Python client
+
+```python
+client = replicate.Client()
+
+client.deployments.create(
+    name="my-endpoint",
+    model="owner/model",
+    version="<version-sha>",
+    hardware="gpu-a100-large",
+    min_instances=1,
+    max_instances=5,
+)
+
+# scale or roll a new version
+client.deployments.update("owner/my-endpoint", min_instances=2, version="<new-sha>")
+```
+
+## Calling a deployment
+
+You call it like any model — the deployment just routes to your private instances:
+
+```python
+deployment = client.deployments.get("owner/my-endpoint")
+prediction = deployment.predictions.create(input={"prompt": "..."})
+prediction.reload()
+```
+
+Async + webhook works the same: pass `webhook=` / `webhook_events_filter=` to the deployment's
+`predictions.create`.
+
+## Rolling updates
+
+Updating `version` rolls new instances in and drains old ones with no downtime. Because versions are
+immutable SHAs, you can roll back by updating `version` to the previous SHA. Never depend on "latest" —
+pin the SHA so a teammate's `cog push` does not silently change what the endpoint serves.
+
+## Monitoring
+
+The dashboard and API expose per-deployment **latency, throughput, error rate, and GPU memory**. Watch
+GPU memory to right-size hardware, and error rate after every rolling update — a spike right after a
+version bump means roll back to the prior SHA.

package/skills/replicate/references/webhooks-and-async.md

@@ -0,0 +1,110 @@
+# Webhooks & async — full reference
+
+Source: https://replicate.com/docs/topics/webhooks/verify-webhook and the client READMEs
+(accessed 2026-06-02).
+
+## Event filters
+
+`webhook_events_filter` controls which lifecycle events POST to your URL. Filter to what you need —
+`["completed"]` for most apps, add `"start"`/`"output"`/`"logs"` only if you stream progress.
+
+```python
+client.predictions.create(
+    model="owner/model",
+    input={"prompt": "..."},
+    webhook="https://your.app/hooks/replicate",
+    webhook_events_filter=["completed"],
+)
+```
+
+## Signature verification — Python
+
+Replicate signs every delivery. The secret (fetch once from the API / dashboard) has a `whsec_`
+prefix. Signed content is `{webhook-id}.{webhook-timestamp}.{raw-body}`. Verify before trusting:
+
+```python
+import base64, hashlib, hmac
+
+def verify_replicate_webhook(headers: dict, raw_body: bytes, signing_secret: str) -> bool:
+    webhook_id = headers["webhook-id"]
+    timestamp  = headers["webhook-timestamp"]
+    signature_header = headers["webhook-signature"]   # e.g. "v1,<b64sig> v1,<b64sig2>"
+
+    secret_bytes = base64.b64decode(signing_secret.split("_", 1)[1])  # strip "whsec_"
+    signed_content = f"{webhook_id}.{timestamp}.{raw_body.decode()}".encode()
+    expected = base64.b64encode(
+        hmac.new(secret_bytes, signed_content, hashlib.sha256).digest()
+    ).decode()
+
+    # header may carry multiple space-separated "v1,<sig>" tokens; match any
+    for token in signature_header.split():
+        _, _, sig = token.partition(",")
+        if hmac.compare_digest(sig, expected):
+            return True
+    return False
+```
+
+- Use the **raw** request body bytes, not a re-serialized JSON dict — re-serialization changes bytes
+  and breaks the HMAC.
+- Always `hmac.compare_digest` (constant time), never `==` — `==` leaks timing.
+- Optionally validate the `webhook-timestamp` is recent (reject if older than ~5 min) to blunt replay.
+
+## Signature verification — Node
+
+```javascript
+import crypto from "node:crypto";
+
+export function verifyReplicateWebhook(headers, rawBody, signingSecret) {
+  const id = headers["webhook-id"];
+  const timestamp = headers["webhook-timestamp"];
+  const sigHeader = headers["webhook-signature"]; // "v1,<b64> v1,<b64>"
+
+  const secretBytes = Buffer.from(signingSecret.split("_")[1], "base64"); // strip "whsec_"
+  const signedContent = `${id}.${timestamp}.${rawBody}`;
+  const expected = crypto.createHmac("sha256", secretBytes)
+    .update(signedContent).digest("base64");
+
+  return sigHeader.split(" ").some((tok) => {
+    const sig = tok.split(",")[1];
+    const a = Buffer.from(sig);
+    const b = Buffer.from(expected);
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+  });
+}
+```
+
+The official clients also expose a built-in helper — prefer it when available; the manual recipe above
+is for frameworks where you only have raw headers + body.
+
+## Idempotency
+
+Webhooks can be delivered more than once. Dedupe on the `webhook-id` header (store processed ids,
+skip repeats) so a retry does not double-charge a user or re-run side effects.
+
+## 5xx and retries
+
+Return `2xx` fast once you have verified + enqueued the work. If your handler returns a `5xx`,
+Replicate retries — so keep the handler thin (verify, persist, enqueue) and do heavy work
+asynchronously. A handler that does slow work inline risks timing out and getting retried, compounding
+load.
+
+## Polling loop with backoff (when you don't use webhooks)
+
+```python
+import time
+
+def wait_for(client, prediction, max_wait=600):
+    deadline = time.monotonic() + max_wait
+    delay = 1.0
+    while prediction.status not in ("succeeded", "failed", "canceled"):
+        if time.monotonic() > deadline:
+            prediction.cancel()
+            raise TimeoutError("prediction exceeded max_wait")
+        time.sleep(delay)
+        delay = min(delay * 1.5, 10.0)   # capped exponential backoff
+        prediction.reload()
+    return prediction
+```
+
+Prefer webhooks for long jobs — polling ties up a process. Set a server-side prediction **deadline**
+too so a job auto-cancels even if your poller dies.

package/skills/replicate/scripts/verify.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static lint for a Replicate/Cog artifact dir (read-only, network-free).
+#
+# WHAT IT DOES (never edits, builds, or runs Docker)
+#   Points at a directory you emitted (default: current dir) and checks the
+#   things that are mechanically wrong before any Cog build:
+#     1. cog.yaml present -> must declare a top-level `build:` and a `predict:`
+#        key. A present-but-malformed cog.yaml is a HARD failure.
+#     2. predict.py present -> should define a `Predictor` class with both
+#        `setup` and `predict` methods (warn if missing — naming is conventional
+#        but Cog needs the class your cog.yaml names).
+#     3. requirements/pyproject pinning -> an unpinned `replicate` dep warns
+#        (a fresh resolve can pull the 2.0 alpha).
+#     4. FileOutput misuse -> Python that writes a run()/predict output object
+#        directly to a text file (e.g. write(output[0])) without .read()/.url
+#        warns.
+#
+#   Only a malformed cog.yaml is a hard failure. A dir with no cog.yaml and no
+#   Python (nothing to check) exits 0 — never a false failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # check current directory
+#   ./verify.sh path/to/dir     # check a specific artifact dir
+#   ./verify.sh dir --strict    # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, warnings-only (without --strict), or nothing to check
+#   1  a hard failure (malformed cog.yaml) — or any warning under --strict
+#   2  bad usage (target dir does not exist)
+#
+# Runs on stock macOS bash 3.2.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+DIR="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --strict) STRICT=1; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) DIR="$1"; shift ;;
+  esac
+done
+
+if [ ! -d "$DIR" ]; then
+  printf '%starget dir not found: %s%s\n' "$RED" "$DIR" "$NC" >&2; exit 2
+fi
+
+printf 'replicate verify — %s\n\n' "$DIR"
+
+checked_anything=0
+
+# --- 1. cog.yaml: build: + predict: keys (hard) -------------------------------
+COG="$DIR/cog.yaml"
+if [ -f "$COG" ]; then
+  checked_anything=1
+  missing=""
+  grep -Eq '^[[:space:]]*build[[:space:]]*:' "$COG" || missing="build:"
+  if ! grep -Eq '^[[:space:]]*predict[[:space:]]*:' "$COG"; then
+    missing="${missing:+$missing and }predict:"
+  fi
+  if [ -n "$missing" ]; then
+    fail "cog.yaml is missing required key(s): $missing"
+  else
+    ok "cog.yaml declares build: and predict:"
+  fi
+else
+  ok "no cog.yaml in $DIR — skipping Cog config checks"
+fi
+
+# --- 2. predict.py: Predictor with setup + predict ----------------------------
+# Find a predictor module: prefer predict.py, else any *.py with a BasePredictor.
+PRED=""
+if [ -f "$DIR/predict.py" ]; then
+  PRED="$DIR/predict.py"
+else
+  PRED="$(grep -rlE 'BasePredictor|class[[:space:]]+Predictor' "$DIR" --include='*.py' 2>/dev/null | head -1 || true)"
+fi
+if [ -n "$PRED" ] && [ -f "$PRED" ]; then
+  checked_anything=1
+  has_class=0; has_setup=0; has_predict=0
+  grep -Eq 'class[[:space:]]+\w+\(.*Predictor.*\)|class[[:space:]]+Predictor' "$PRED" && has_class=1
+  grep -Eq '^[[:space:]]*def[[:space:]]+setup[[:space:]]*\(' "$PRED" && has_setup=1
+  grep -Eq '^[[:space:]]*def[[:space:]]+predict[[:space:]]*\(' "$PRED" && has_predict=1
+  if [ "$has_class" -eq 1 ] && [ "$has_setup" -eq 1 ] && [ "$has_predict" -eq 1 ]; then
+    ok "$(basename "$PRED") has a Predictor with setup() and predict()"
+  else
+    [ "$has_class" -eq 0 ]   && warn "$(basename "$PRED"): no Predictor class found"
+    [ "$has_setup" -eq 0 ]   && warn "$(basename "$PRED"): no setup() — load weights once here, not per request"
+    [ "$has_predict" -eq 0 ] && warn "$(basename "$PRED"): no predict() method found"
+  fi
+fi
+
+# --- 3. unpinned replicate dependency -----------------------------------------
+DEPFILES="$(grep -rlE '(^|[^a-zA-Z_-])replicate([^a-zA-Z_-]|$)' \
+  "$DIR" --include='requirements*.txt' --include='pyproject.toml' 2>/dev/null || true)"
+if [ -n "$DEPFILES" ]; then
+  checked_anything=1
+  flagged=0
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    # a line declaring replicate as a dep but with no version constraint
+    if grep -Eq '^[[:space:]"'"'"']*replicate[[:space:]"'"'"',]*$' "$f"; then
+      warn "$(basename "$f") declares 'replicate' unpinned — pin 'replicate>=1,<2' (2.0 is alpha)"
+      flagged=1
+    fi
+  done <<EOF
+$DEPFILES
+EOF
+  [ "$flagged" -eq 0 ] && ok "replicate dependency is pinned or constrained"
+fi
+
+# --- 4. FileOutput written as a string ----------------------------------------
+PYFILES="$(find "$DIR" -name '*.py' 2>/dev/null || true)"
+if [ -n "$PYFILES" ]; then
+  MISUSE="$(grep -rEn "open\([^)]*['\"]w['\"][^)]*\)\.write\([a-zA-Z_]" "$DIR" --include='*.py' 2>/dev/null \
+    | grep -vE '\.read\(\)|\.url' || true)"
+  if [ -n "$MISUSE" ]; then
+    checked_anything=1
+    while IFS= read -r m; do
+      [ -n "$m" ] && warn "possible FileOutput-as-string: ${m} — use .read() for bytes or .url for the link"
+    done <<EOF
+$MISUSE
+EOF
+  fi
+fi
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$checked_anything" -eq 0 ] && [ "$fail_count" -eq 0 ]; then
+  ok "nothing to check in $DIR"
+  exit 0
+fi
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  if [ "$STRICT" -eq 1 ]; then
+    printf '%s%d warning(s) — failing under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+    exit 1
+  fi
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0