openrunner-sdk 2.38.0__tar.gz → 2.38.2__tar.gz

{openrunner_sdk-2.38.0 → openrunner_sdk-2.38.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrunner-sdk
-Version: 2.38.0
+Version: 2.38.2
 Summary: OpenRunner SDK - W&B-compatible ML experiment tracking client
 Project-URL: Homepage, https://github.com/jqueguiner/openrunner
 Project-URL: Repository, https://github.com/jqueguiner/openrunner

{openrunner_sdk-2.38.0 → openrunner_sdk-2.38.2}/openrunner/__init__.py

@@ -181,7 +181,7 @@ launch.from_run = _launch_from_run  # type: ignore[attr-defined]
 # openrunner.trace.patch_openai() syntax
 trace.patch_openai = _patch_openai  # type: ignore[attr-defined]
 
-__version__ = "2.38.0"
+__version__ = "2.38.2"
 
 logger = logging.getLogger("openrunner")
 

{openrunner_sdk-2.38.0 → openrunner_sdk-2.38.2}/openrunner/install_commands.py

@@ -2017,6 +2017,14 @@ allowed-tools:
 
 Create a dataset on OpenRunner following the standard pattern (e.g. `paralinguistics-speech-labels-*`): a **managed** dataset bound to a storage connection, with `modality`, `format`, `tasks`, `languages`, `license_use`, a **structured card**, and optionally its files uploaded + linked to a run for lineage.
 
+!!! danger "Media datasets MUST be preview-playable — never a bare tar + a separate labels file"
+    Every **Audio / Video / Image** dataset has to end up **browsable and playable in the UI**: each clip visible and playable **next to its label** (transcript, caption…). The UI never joins a side manifest — the label must live IN the rows the UI reads. There are exactly two correct layouts:
+
+    - **Sharded** (default, 1k+ clips): media in `shards/*.tar` + a top-level **`index.jsonl`** with one row per clip carrying `key, shard, offset, size, content_type` **and** the label columns (`text`, `dur`, …); then set `metadata.sharded=true` + `shard_index` and run `index_dataset(text_columns=[...])`. The UI plays each clip via a Range GET on the shard using `key/shard/offset`.
+    - **Non-sharded** (small): individual clip files + a root **`dataset.jsonl`** whose `audio` column is the repo-relative object path, **plus** the label columns on the same row.
+
+    **Anti-pattern that produces NO preview and NO playback (do not do this):** uploading a bare `audio.tar` (or a folder of clips) alongside a SEPARATE `labels.jsonl`. The UI joins nothing → an empty, unplayable dataset. If you already did it, use the *repair* path in Step 5 (build `index.jsonl` with offsets + label columns, or `reconcile_shards`) — you do not need to re-upload the media.
+
 `$ARGUMENTS`: `[org/name] [--connection NAME] [--upload DIR] [--link-run RUN_ID]` (ask for what's missing).
 
 ## Process
@@ -2323,7 +2331,7 @@ cat "$CACHE" 2>/dev/null
 
 LAUNCH_GPU_CMD = """---
 name: {prefix}launch-gpu
-description: Provision a remote cloud GPU (RunPod, Vast.ai, Lambda) and run a training job on it end-to-end -- governed compute, auto cost tracking, auto-terminate
+description: Provision a remote cloud GPU (RunPod, Vast.ai, Lambda, OVH) or run on a serverless fleet (Modal, Forge via `--provider forge <script>`) and run a training job end-to-end -- governed compute, auto cost tracking, auto-terminate. "on forge"/"on modal" = a provider, not an ssh host.
 argument-hint: "[provider] [gpu] -- <training command>"
 allowed-tools:
   - Bash
@@ -3078,7 +3086,7 @@ Surface a clear message on 403 (needs admin) or 404 (already gone).
 
 TRAIN_CMD = """---
 name: {prefix}train
-description: Train on the right infra from a plain-English request -- lists ALL available compute (registered self-hosted workers + cloud provider offers RunPod/Vast/Lambda), interprets your NL intent ("cheapest A100", "my 4090 box", "runpod H100 x2") to pick the target, confirms, then launches the training governed (server-side key, auto cost + terminate)
+description: Train on the right infra from a plain-English request -- lists ALL available compute (registered self-hosted workers + cloud provider offers RunPod/Vast/Lambda/OVH + serverless Modal/Forge), interprets your NL intent ("cheapest A100", "my 4090 box", "runpod H100 x2", "on forge") to pick the target, confirms, then launches the training governed (server-side key, auto cost + terminate)
 argument-hint: "[natural-language infra + training request]"
 allowed-tools:
   - Bash
@@ -3104,9 +3112,14 @@ Gather the real options (don't hardcode):
 
 ## Step 2 -- interpret the NL request (map intent -> concrete target)
 From the user's phrasing, resolve a single target + shape:
+- **A bare/unknown target name is a PROVIDER, not an ssh host.** If the user says
+  "on forge", "launch on modal", "use runpod", match it against the provider set
+  (runpod, vastai, lambda, ovhcloud, modal, forge) + `openrunner gpu credentials
+  ls` FIRST. Don't conclude the target "doesn't exist" just because it's not in
+  `~/.ssh/config` or `hosts ls` -- serverless providers have no host at all.
 - **Named worker** ("my 4090 box", "the a100 rig") -> match a registered host by
   name / GPU.
-- **Provider** ("on runpod", "vast") -> that provider's offers.
+- **Provider** ("on runpod", "vast", "on forge/modal") -> that provider's offers.
 - **GPU class** ("an A100 80G", "H100 x2") -> gpu type + count.
 - **Constraints**: "cheapest" -> min $/hr that fits; "fits <model>" -> enough VRAM
   (read the model card's measured peak VRAM if a model is named; label estimates);
@@ -3132,11 +3145,17 @@ Two ways to run, by target. **Choose based on SSH reachability** (see Step 4b):
 - **B. Registered self-hosted HOST (real SSH)**: a `hosts`-registered box with
   direct SSH (e.g. a bare-metal box you control) -- run over SSH
   `ssh USER@HOST -p PORT "<docker run / train cmd>"`.
-- **C. Cloud provider (RunPod, ...)**:
+- **C. Cloud pod provider (RunPod, Vast.ai, Lambda, OVH)**:
   `openrunner gpu run --provider P --gpu GPU [--gpu-count N] --project ORG/NAME
   [-e KEY=VAL ...] "<train command>"`. Governed (key server-side, cost-tracked,
   auto-terminate). Deliver code/data inside the command (git clone / artifact
   fetch) -- it runs a command, doesn't sync the cwd.
+- **D. Serverless fleet (Modal, Forge)** -- no pod, no SSH, no runner to find:
+  `openrunner gpu run --provider forge <app_script.py>`. COMMAND is the App
+  SCRIPT (not a shell command); the GPU is declared inside it
+  (`@app.function(gpu=...)`), so `--gpu` is omitted; the Run auto-terminates when
+  the function returns. Use this whenever the target is `forge`/`modal` -- do NOT
+  fall back to searching for an SSH host or registered runner.
 - Forward `OPENRUNNER_API_KEY` (+ project) into the job env so training logs back.
 
 ## Step 4b -- SSH not coming up? (RunPod SECURE pods)
@@ -3175,6 +3194,112 @@ directly SSH-reachable** (`publicIp:22`): SSH is only via the **proxy**
 """
 
 
+FORGE_CMD = """---
+name: {prefix}forge
+description: Run or write a Python function on the Forge (Shadow-PaaS) serverless GPU fleet. Use for "run/launch/train on forge", "forge GPU", or writing an @app.function. Forge is a serverless PROVIDER (like Modal) -- NOT an ssh host or runner, so don't hunt ~/.ssh/config or `hosts ls`.
+argument-hint: "[run <script.py> | new <name> | explain]"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+
+Forge (shadow-paas.com) is a **serverless GPU fleet** -- like Modal. You deploy an
+**App** exposing **@app.function**s; each call is a **Run** on a GPU container that
+auto-terminates. It is NOT an ssh box or a registered runner.
+
+## Run an App
+- Governed (token stored server-side, cost-tracked): store once with
+  `openrunner gpu credentials add --provider forge --api-key fg_..`, then
+  `openrunner gpu run --provider forge <script.py>` -- COMMAND is the App SCRIPT
+  (the GPU is declared inside it, so no `--gpu`); the Run auto-terminates.
+- Native client: `forge run <script.py>` (needs the `forge-shadow` client on a
+  Python 3.13 interpreter + `FORGE_TOKEN`; install:
+  `pip install forge-shadow --extra-index-url https://forge.shadow-paas.com/sdk/`).
+
+## How the function runs (mental model)
+`forge run script.py` runs `@app.local_entrypoint()` on YOUR machine; each
+`fn.remote(args)` is the boundary -- Forge cloudpickles the function + args into a
+fresh GPU container (the App's image), runs it ON the fleet, streams stdout back,
+and cloudpickles the RETURN value back. The container is torn down when the
+function returns. Therefore:
+- args + return value cross a **pickle boundary** -> keep them small & picklable;
+  download a dataset/checkpoint INSIDE the function (from a URI), don't pass it as
+  an arg, and return a metrics dict / an uploaded URL, not a multi-GB tensor.
+- heavy **imports + file reads go INSIDE** the function (they resolve in the
+  container, not your laptop).
+- the **GPU is set per function** via `gpu=` on the decorator.
+- local Python must be **3.13** to match the image or every run errors
+  `PYTHON_VERSION_MISMATCH`.
+
+## Write the App -- training shape
+```python
+import forge
+
+app = forge.App("lora-finetune", image="forge/torch")  # forge/torch = PyTorch+CUDA
+
+
+@app.function(gpu="A100-80GB")
+def train(cfg: dict) -> dict:
+    import torch                                  # import INSIDE the function
+    from urllib.request import urlretrieve
+
+    urlretrieve(cfg["data_url"], "/tmp/train.pt")  # fetch data IN-container
+    data = torch.load("/tmp/train.pt", map_location="cuda")
+    # ... build model, run your training loop, print progress (streams live) ...
+    return {{"final_loss": 0.1234, "steps": cfg["steps"]}}   # small, picklable
+
+
+@app.local_entrypoint()
+def main():
+    cfg = {{"data_url": "https://.../train.pt", "lr": 3e-4, "steps": 500}}
+    print(train.remote(cfg))                       # runs on the fleet A100
+```
+
+Run it: `forge run train.py` (or `openrunner gpu run --provider forge train.py`).
+To log to OpenRunner FROM the fleet, put the api key + project in `cfg` and call
+`openrunner.init(...)` / `openrunner.log(...)` INSIDE `train` -- your local env
+vars do NOT cross the `.remote()` boundary.
+
+## Serve an inference API (a DEPLOYMENT, not a one-shot Run)
+`@app.web_endpoint` / `@app.asgi_app` turn a function into an **autoscaled HTTP
+endpoint**. Ship it with `forge deploy api.py` (versioned, long-lived; `forge app`
+manages it) -- NOT `forge run` (that's for a one-shot entrypoint).
+```python
+import forge
+
+app = forge.App("whisper-api", image="forge/torch")
+
+
+@app.function(gpu="A100-80GB")
+@app.asgi_app(public=True, min_replicas=1, max_replicas=4)  # 1 warm, burst to 4
+def api():
+    from fastapi import FastAPI, UploadFile   # imports resolve IN-container
+    import whisperx
+
+    web = FastAPI()
+    model = whisperx.load_model("large-v3", device="cuda")  # loaded once PER replica
+
+    @web.post("/transcribe")
+    async def transcribe(file: UploadFile):
+        audio = decode(await file.read())      # your decode
+        return {{"text": model.transcribe(audio)["text"]}}
+
+    return web                                 # asgi_app returns the ASGI app
+```
+Deploy: `forge deploy api.py` -> prints the public URL + autoscale bounds. Notes:
+- the model is loaded **once per replica** (module/handler scope), not per request;
+- `min_replicas>=1` avoids cold starts; it scales to `max_replicas` under load;
+- `public=True` exposes it without auth (omit for a workspace-scoped endpoint);
+- for a single handler instead of a whole app, use
+  `@app.web_endpoint(path="/predict", methods=["POST"])` on the function directly.
+
+Gotchas: run `forge run` from a CLEAN directory (it snapshots the cwd -- a managed
+repo with unreadable files aborts with `PermissionError [Errno 13]`); the first run
+pulls the GPU image (~a minute), then it's fast.
+"""
+
+
 DEPLOY_CMD = """---
 name: {prefix}deploy
 description: Interactively deploy a project's model image on serverless GPUs -- reads the model card's measured results to RECOMMEND a GPU (VRAM headroom) + platform (price/availability), asks you to confirm platform + GPU, sets replica bounds/autoscale, creates the deployment and watches it roll out
@@ -3387,6 +3512,7 @@ def install_claude_code() -> list[str]:
         "unregister-machine.md": UNREGISTER_MACHINE_CMD,
         "train.md": TRAIN_CMD,
         "deploy.md": DEPLOY_CMD,
+        "forge.md": FORGE_CMD,
     }
 
     files = []
@@ -3450,14 +3576,28 @@ or annotation rules:
 - Run `/openrunner:gt-recommendations [run_id]` for a structured rule report.
 
 When the user asks to start / run / launch a TRAINING on a remote or cloud GPU
-(RunPod, Vast.ai, Lambda), or mentions a "distant GPU":
+(RunPod, Vast.ai, Lambda, OVH; serverless: Modal, Forge), names a provider, or
+mentions a "distant GPU":
+- FIRST: a bare target name the user gives ("on forge", "launch on modal",
+  "runpod H100") is almost always a GPU **provider**, NOT an ssh host. Do NOT
+  conclude it "doesn't exist" after checking ~/.ssh/config or `hosts ls` --
+  check `openrunner gpu credentials ls` and the provider registry
+  (runpod, vastai, lambda, ovhcloud, modal, forge) and use `--provider <name>`.
 - Run `/openrunner:launch-gpu` for the full guided flow (auth -> provider key ->
   pick GPU/image -> launch -> monitor -> terminate).
-- The one-shot is `openrunner gpu run --provider runpod --gpu A100_80GB
-  --project ORG/PROJECT "<train cmd>"`: provisions a pod server-side, streams
-  logs, auto-terminates. Provider keys are stored encrypted with
-  `openrunner gpu credentials add`; list/kill with `openrunner gpu ls` /
-  `openrunner gpu terminate`. Governed compute -- the key never leaves the API.
+- Pod providers (RunPod/Vast/Lambda/OVH): the one-shot is
+  `openrunner gpu run --provider runpod --gpu A100_80GB --project ORG/PROJECT
+  "<train cmd>"` -- provisions a pod server-side, streams logs, auto-terminates.
+- Serverless fleets (**Modal, Forge**): no pod / no SSH -- they run a function on
+  demand. Forge:
+  `openrunner gpu run --provider forge <app_script.py>` -- COMMAND is the App
+  SCRIPT (GPU is declared in `@app.function(gpu=...)`, so no `--gpu`), the Run
+  auto-terminates when the function returns. Don't hunt for an SSH host/runner.
+  For native Forge use, the `forge-deploy` skill covers install/auth/write/run.
+- Provider keys are stored encrypted with `openrunner gpu credentials add`
+  (e.g. `--provider forge --api-key fg_..`); list/kill pods with
+  `openrunner gpu ls` / `openrunner gpu terminate`. Governed compute -- the key
+  never leaves the API.
 """
     import re
     if claude_md.exists():
@@ -3598,6 +3738,7 @@ def _install_all_commands_to_dir(cmd_dir: Path, prefix: str = "openrunner:") ->
         "unregister-machine.md": UNREGISTER_MACHINE_CMD,
         "train.md": TRAIN_CMD,
         "deploy.md": DEPLOY_CMD,
+        "forge.md": FORGE_CMD,
     }
 
     files = []

{openrunner_sdk-2.38.0 → openrunner_sdk-2.38.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openrunner-sdk"
-version = "2.38.0"
+version = "2.38.2"
 description = "OpenRunner SDK - W&B-compatible ML experiment tracking client"
 readme = "README.md"
 license = {text = "MIT"}