rsc-universal 0.1.1

package/skills/runpod/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — runpod
+
+These cases are a manual sanity check on routing and coverage, not an automated harness.
+To run them, read `cases.yaml` and confirm three things by hand: a fresh agent fires this
+skill on every `should_trigger` prompt (including the cost-symptom and cold-start ones that
+never say "serverless"); it defers to the named `route_to` sibling on each
+`should_not_trigger` prompt instead of grabbing the work; and given the `capability`
+scenario it produces an answer hitting every item in the `must_include` rubric (flex over a
+24/7 Pod with reasoning, a right-sized GPU instead of H100, bounded Max Workers, explicit
+idle/execution timeouts, FlashBoot, a `runpod.serverless.start` handler or worker-vllm, env
+API key, and a local test step). No network or RunPod account is involved.

package/skills/runpod/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: runpod
+
+should_trigger:
+  - prompt: "Deploy my fine-tuned Llama as a RunPod serverless endpoint with vLLM."
+    why: Direct serverless deployment plus the worker-vllm path — core of the skill.
+  - prompt: "My RunPod bill exploded this month and the workers never seem to scale down."
+    why: Cost / idle-timeout / max-workers symptom with no 'serverless' keyword; the non-obvious cost-control trigger.
+  - prompt: "Write me a handler(job) function and start the serverless worker."
+    why: Handler authoring — the runpod.serverless.start pattern.
+  - prompt: "Necesito entrenar un modelo en una GPU H100 por horas, ¿pod o serverless en RunPod?"
+    why: Spanish phrasing of the Pod-vs-Serverless decision plus SKU pick.
+  - prompt: "Should I use a network volume or bake the weights into the container image on RunPod?"
+    why: Volume-vs-image decision; non-obvious framing of the storage/template tradeoff.
+  - prompt: "Cold starts on my endpoint are 20 seconds, how do I make them faster?"
+    why: FlashBoot / active-worker tuning; non-obvious, no provider named but RunPod endpoint context.
+
+should_not_trigger:
+  - prompt: "Deploy this model with Python-native autoscaling and snapshots, no Dockerfile."
+    route_to: modal
+    why: Snapshot autoscaling with no container is Modal's niche, not RunPod's image-based workers.
+  - prompt: "Call the SDXL endpoint on Replicate and get the image URL back."
+    route_to: replicate
+    why: Hosted prebuilt model API the user does not self-host — not RunPod GPU rental.
+  - prompt: "Download Mistral-7B weights from the Hub and push my fine-tune back."
+    route_to: huggingface
+    why: Hub artifact transfer, not GPU compute.
+  - prompt: "Run Llama 3 locally on my Mac with Ollama."
+    route_to: ollama
+    why: Local on-device inference, not cloud GPU.
+  - prompt: "Containerize my FastAPI service with a multi-stage Dockerfile."
+    route_to: docker
+    why: Generic containerization unrelated to RunPod's worker image shape.
+  - prompt: "Build a cross-provider GPU spend dashboard across AWS, GCP and RunPod."
+    route_to: cost-tracking
+    why: Provider-agnostic cost attribution, not RunPod-specific knobs.
+
+capability:
+  - scenario: "I serve a 7B LLM, about 100k requests/day at ~2s each, bursty during business hours. Set up a cost-efficient RunPod serverless endpoint."
+    must_include:
+      - Recommends Serverless (flex) over a 24/7 Pod for bursty traffic, with utilization reasoning.
+      - Picks a right-sized GPU (e.g. RTX 4090 or L40S), not H100 by default.
+      - Sets Max Workers as a bounded cost ceiling (~20% over peak).
+      - Sets Idle Timeout and Execution Timeout explicitly rather than leaving defaults.
+      - Enables FlashBoot to cut cold-start cost on flex workers.
+      - Worker uses runpod.serverless.start and reads job["input"], or uses worker-vllm with MODEL_NAME env var.
+      - Reads the API key from RUNPOD_API_KEY env, never hardcoded.
+      - Mentions local test (python worker.py --rp_serve_api or test_input.json) before deploying.

package/skills/runpod/references/cost-and-scaling.md

@@ -0,0 +1,85 @@
+# Cost & scaling
+
+Full pricing and the math behind the SKILL.md "Cost control" section. All figures dated
+**2026-06-02**; Community Cloud runs lower than Secure Cloud, so treat these as upper bounds.
+Always reprice against https://www.runpod.io/pricing before committing.
+
+## Pod pricing (per hour)
+
+| GPU | VRAM | ~$/hr |
+| --- | --- | --- |
+| H100 SXM | 80GB | $3.29 |
+| H100 PCIe | 80GB | $2.89 |
+| A100 80GB PCIe | 80GB | $1.39 |
+| L40S | 48GB | $0.86 |
+| RTX 4090 | 24GB | $0.69 |
+| A40 | 48GB | $0.44 |
+| L4 | 24GB | $0.39 |
+
+## Serverless pricing (per-hour equivalent, billed per second rounded up)
+
+Billed only while a worker is active, from start to full stop. Roughly 2-3x the pod rate.
+
+| GPU | VRAM | ~$/hr equiv |
+| --- | --- | --- |
+| H100 | 80GB | $4.18 |
+| A100 | 80GB | $2.72 |
+| L40 / L40S | 48GB | $1.90 |
+| RTX 4090 | 24GB | $1.10 |
+| L4 / A5000 / RTX 3090 | 24GB | $0.69 |
+
+## Storage pricing
+
+| Storage | ~$/GB/mo |
+| --- | --- |
+| Container disk | $0.10 |
+| Network volume, standard, under 1TB | $0.07 |
+| Network volume, standard, over 1TB | $0.05 |
+| Network volume, high-performance | $0.14 |
+| Pod volume disk, running | $0.10 |
+| Pod volume disk, idle (stopped pod) | $0.20 |
+
+The idle rate is **double** the running rate. A volume left on a stopped pod is a silent
+leak. Network volumes also lock the endpoint/pod to a single data center, shrinking GPU
+availability and adding network latency.
+
+## Active vs flex math
+
+- **Flex workers** spin up on demand → cold start, but bill nothing while idle. Best when
+  traffic has real gaps.
+- **Active workers** stay always-warm → zero cold start, but bill every second 24/7 at a
+  **~40% discount** vs the flex rate.
+
+Break-even intuition: an active worker pays off versus flex only when it would otherwise be
+spun up often enough that paying the discounted always-warm rate beats paying flex's
+per-request seconds plus idle-timeout tails. For genuinely bursty traffic, flex + FlashBoot
+almost always wins.
+
+## Worked monthly scenarios
+
+Assume RTX 4090: pod $0.69/hr, serverless $1.10/hr equiv.
+
+1. **Bursty inference, 100k req/day, 2s each, business hours.**
+   ~55.5 GPU-hours/day of real work → ~$61/day on flex serverless plus small idle-timeout
+   tails. A 24/7 pod is ~$497/mo flat. With work concentrated in ~8 hours, **flex wins** —
+   you do not pay for the 16 idle hours.
+
+2. **Steady 24/7 inference at high utilization.**
+   If the GPU is busy >60% of every hour, the serverless 2-3x premium overtakes a flat pod.
+   **A dedicated Pod (~$497/mo) wins.** If a latency SLA forbids cold starts but utilization
+   is moderate, active serverless (40% off flex) is the middle ground.
+
+3. **Fine-tuning, single 6-hour run, A100 80GB.**
+   ~6 × $1.39 = ~$8.34 on a Pod. On serverless the 600s default execution timeout would kill
+   the job outright, and the premium rate makes it pointless. **Pod, always.**
+
+## Scaling strategy knobs
+
+Endpoints scale workers up by one of two scalers:
+
+- **Queue Delay** — add a worker when requests wait longer than a threshold. Smooths latency.
+- **Request Count** — add a worker per N queued requests. Predictable throughput scaling.
+
+Always pair either with **Max Workers ~20% above expected peak** as the hard cost ceiling,
+and **Active Workers** only when an SLA forbids cold starts. Enable **FlashBoot** on flex to
+make scale-from-zero cheap.

package/skills/runpod/references/serverless-workers.md

@@ -0,0 +1,101 @@
+# Serverless workers — fuller patterns
+
+Depth for the SKILL.md "Serverless worker handler" section. The `runpod` Python SDK drives
+all of this.
+
+## start() options
+
+```python
+import runpod
+
+runpod.serverless.start({
+    "handler": handler,                 # required: sync or async callable
+    "return_aggregate_stream": True,    # generator handlers: also expose joined output via /runsync
+    "concurrency_modifier": adjust,     # callable -> max concurrent jobs this worker takes
+})
+```
+
+## Async handler
+
+Use `async def` when the handler awaits I/O (model server, HTTP, DB). The runtime awaits it.
+
+```python
+import runpod
+
+async def handler(job):
+    job_input = job["input"]
+    result = await run_model(job_input["prompt"])
+    return {"output": result}
+
+runpod.serverless.start({"handler": handler})
+```
+
+## Streaming via async generator
+
+`yield` chunks instead of returning once. Clients read them from the `/stream/<id>` endpoint.
+Set `return_aggregate_stream: True` if you also want the joined result on `/runsync`.
+
+```python
+import runpod
+
+async def handler(job):
+    for token in generate(job["input"]["prompt"]):
+        yield {"token": token}
+
+runpod.serverless.start({"handler": handler, "return_aggregate_stream": True})
+```
+
+## Concurrency modifier
+
+By default a worker takes one job at a time. For lightweight or batched work, let one worker
+hold several concurrent jobs — fewer cold starts, lower bill. Return the max concurrency
+given the current count.
+
+```python
+def adjust_concurrency(current_concurrency):
+    # Cap at 4 concurrent jobs per worker.
+    return min(current_concurrency + 1, 4)
+
+runpod.serverless.start({"handler": handler, "concurrency_modifier": adjust_concurrency})
+```
+
+## Error shape
+
+Raise to fail a job, or return a dict with an `error` key. Failed jobs surface in the
+endpoint status; a worker that errors repeatedly can be refresh-cycled.
+
+```python
+def handler(job):
+    job_input = job["input"]
+    if "prompt" not in job_input:
+        return {"error": "missing 'prompt' in input"}
+    return {"output": run(job_input["prompt"])}
+```
+
+## Local testing
+
+Always exercise the handler locally before building/pushing an image.
+
+- **One-shot:** create `test_input.json`, then `python worker.py`. The SDK detects the file,
+  runs the handler once against its `input`, prints the output, and exits.
+
+  ```json
+  { "input": { "prompt": "hello" } }
+  ```
+
+- **HTTP server:** `python worker.py --rp_serve_api` starts a local server at
+  `http://localhost:8000` emulating the deployed endpoint, so you can POST to `/runsync` and
+  `/run` exactly as the platform would.
+
+## Endpoint HTTP API
+
+Once deployed, an endpoint exposes (auth with your API key as a bearer token):
+
+| Endpoint | Purpose |
+| --- | --- |
+| `POST /run` | Submit an async job, returns a job id immediately. |
+| `POST /runsync` | Submit and block for the result (short jobs, ~90s ceiling). |
+| `GET /stream/<id>` | Pull streamed chunks from a generator handler. |
+| `GET /status/<id>` | Poll an async job's status + output. |
+| `POST /cancel/<id>` | Cancel a queued or running job. |
+| `GET /health` | Worker counts and queue depth for the endpoint. |

package/skills/runpod/scripts/verify.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: bash scripts/verify.sh [TARGET_DIR]   (default: .)
+# Statically lints a RunPod worker directory. Pure grep/parse — no network, no RunPod
+# account, never writes or installs anything. Read-only.
+#
+# Exit 0 = all applicable checks passed (or the target has nothing to check — an empty or
+# non-worker dir is NOT a failure). Non-zero = a real problem found in present files.
+# Portable to stock macOS bash 3.2: no mapfile, arrays guarded under set -u.
+
+TARGET="${1:-.}"
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1 && [ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]; then
+  YELLOW="$(tput setaf 3)"; RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; RESET="$(tput sgr0)"
+else
+  YELLOW=""; RED=""; GREEN=""; RESET=""
+fi
+
+rc=0
+pass() { printf '%s[PASS]%s %s\n' "$GREEN" "$RESET" "$1"; }
+warn() { printf '%s[WARN]%s %s\n' "$YELLOW" "$RESET" "$1" >&2; }
+fail() { printf '%s[FAIL]%s %s\n' "$RED" "$RESET" "$1" >&2; rc=1; }
+
+if [ ! -d "$TARGET" ]; then
+  fail "target dir not found: $TARGET"
+  exit 1
+fi
+
+# Prune patterns as a literal arg array — each token is its own quoted word, so the shell
+# can never word-split them or glob-expand them against the cwd. (Unquoted `$PRUNE` here
+# silently corrupts find when run from a real project root containing node_modules/.git/venv,
+# emptying the file lists so every check — including the hardcoded-key check — passes.)
+PRUNE=( '(' -path '*/node_modules/*' -o -path '*/.venv/*' -o -path '*/venv/*' -o -path '*/.git/*' ')' -prune -o )
+
+# Collect file lists (newline-delimited; bash 3.2 safe — arrays only used as literal argv).
+PY_FILES="$(find "$TARGET" "${PRUNE[@]}" -name '*.py' -print 2>/dev/null || true)"
+DOCKERFILES="$(find "$TARGET" "${PRUNE[@]}" -iname 'Dockerfile*' -print 2>/dev/null || true)"
+CONFIGS="$(find "$TARGET" "${PRUNE[@]}" \( -name '*.json' -o -name '*.yaml' -o -name '*.yml' \) -print 2>/dev/null || true)"
+
+checked=0
+
+# 1. Python worker: runpod.serverless.start present, and a handler with return/yield.
+if [ -n "$PY_FILES" ]; then
+  if printf '%s\n' "$PY_FILES" | xargs grep -lE 'runpod\.serverless\.start\(' 2>/dev/null | grep -q .; then
+    checked=1
+    pass "found runpod.serverless.start( in a worker file"
+    # Any handler-ish def with a body that returns or yields.
+    if printf '%s\n' "$PY_FILES" | xargs grep -lE '\b(return|yield)\b' 2>/dev/null | grep -q .; then
+      pass "handler returns or yields a result"
+    else
+      fail "no handler 'return' or 'yield' found — worker would produce no output"
+    fi
+  else
+    warn "no runpod.serverless.start( found — not a serverless worker dir, skipping worker checks"
+  fi
+
+  # 2. No hardcoded API key. Flag literal string assignments to api_key / RUNPOD_API_KEY.
+  if printf '%s\n' "$PY_FILES" | xargs grep -nE '(runpod\.api_key|RUNPOD_API_KEY)[[:space:]]*=[[:space:]]*["'"'"'][A-Za-z0-9_-]+["'"'"']' 2>/dev/null | grep -q .; then
+    checked=1
+    fail "hardcoded API key literal found — read it from os.environ['RUNPOD_API_KEY']"
+  else
+    [ -n "$PY_FILES" ] && pass "no hardcoded API key literal in Python sources"
+  fi
+fi
+
+# 3. Serverless config (json/yaml) — bounded max_workers + timeout keys present.
+if [ -n "$CONFIGS" ]; then
+  CFG_WITH_MW="$(printf '%s\n' "$CONFIGS" | xargs grep -lEi 'max[_-]?workers' 2>/dev/null || true)"
+  if [ -n "$CFG_WITH_MW" ]; then
+    checked=1
+    # Must be a finite positive int — fail on missing/0/negative/inf.
+    if printf '%s\n' "$CFG_WITH_MW" | xargs grep -hEi 'max[_-]?workers' 2>/dev/null \
+        | grep -qE 'max[_-]?[Ww]orkers["'"'"']?[[:space:]]*[:=][[:space:]]*[1-9][0-9]*'; then
+      pass "max_workers is a bounded positive integer"
+    else
+      fail "max_workers present but not a bounded positive int (set a finite ceiling)"
+    fi
+    if printf '%s\n' "$CFG_WITH_MW" | xargs grep -qiE 'idle[_-]?timeout' 2>/dev/null; then
+      pass "idle timeout set in config"
+    else
+      fail "config has max_workers but no idle timeout — set it explicitly"
+    fi
+    if printf '%s\n' "$CFG_WITH_MW" | xargs grep -qiE 'execution[_-]?timeout' 2>/dev/null; then
+      pass "execution timeout set in config"
+    else
+      fail "config has max_workers but no execution timeout — a hung job can run for days"
+    fi
+  fi
+fi
+
+# 4. Dockerfile — pinned FROM (not bare/:latest) and a CMD/ENTRYPOINT.
+if [ -n "$DOCKERFILES" ]; then
+  while IFS= read -r df; do
+    [ -n "$df" ] || continue
+    checked=1
+    fromline="$(grep -iE '^[[:space:]]*FROM[[:space:]]' "$df" 2>/dev/null | head -1 || true)"
+    if [ -z "$fromline" ]; then
+      fail "$df: no FROM line"
+    elif printf '%s' "$fromline" | grep -qiE ':latest([[:space:]]|$)'; then
+      fail "$df: FROM uses :latest — pin a version tag"
+    elif printf '%s' "$fromline" | grep -qE '[^[:space:]]+:[^[:space:]]+'; then
+      pass "$df: FROM is pinned to a tag"
+    else
+      fail "$df: FROM has no tag — pin a version"
+    fi
+    if grep -qiE '^[[:space:]]*(CMD|ENTRYPOINT)[[:space:]]' "$df" 2>/dev/null; then
+      pass "$df: has CMD/ENTRYPOINT"
+    else
+      fail "$df: no CMD or ENTRYPOINT — worker has no entrypoint"
+    fi
+  done <<EOF
+$DOCKERFILES
+EOF
+fi
+
+if [ "$checked" -eq 0 ]; then
+  warn "no RunPod worker artifacts found in '$TARGET' — nothing to lint"
+fi
+
+if [ "$rc" -ne 0 ]; then
+  printf '%sverify.sh: FAILED%s\n' "$RED" "$RESET" >&2
+  exit "$rc"
+fi
+printf '%sverify.sh: OK%s\n' "$GREEN" "$RESET"
+exit 0