openrunner-sdk 2.38.3__tar.gz → 2.40.0__tar.gz

{openrunner_sdk-2.38.3 → openrunner_sdk-2.40.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrunner-sdk
-Version: 2.38.3
+Version: 2.40.0
 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.3 → openrunner_sdk-2.40.0}/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.3"
+__version__ = "2.40.0"
 
 logger = logging.getLogger("openrunner")
 

{openrunner_sdk-2.38.3 → openrunner_sdk-2.40.0}/openrunner/cli.py

@@ -4244,8 +4244,8 @@ def gpu_run(command, provider, gpu, gpu_count, image, disk_gb, env, ssh_keys, pr
     """
     from openrunner.gpu.runner import run_governed_sync, run_on_gpu_sync
 
-    if provider != "forge" and not gpu:
-        click.echo("Error: --gpu is required (except for forge).", err=True)
+    if provider not in ("forge", "modal") and not gpu:
+        click.echo("Error: --gpu is required (except for forge/modal).", err=True)
         raise SystemExit(1)
 
     settings = _load_settings()
@@ -4289,22 +4289,30 @@ def gpu_run(command, provider, gpu, gpu_count, image, disk_gb, env, ssh_keys, pr
         except Exception:  # noqa: BLE001
             pass
 
-    # Forge is serverless — it has no pod to provision or SSH into. Dispatch to
-    # the native forge client (COMMAND is the App script); the fleet Run auto-
-    # terminates when the function returns. Credentials come from the org's stored
-    # Forge credential (or FORGE_TOKEN / -e FORGE_TOKEN=..).
-    if provider == "forge":
-        from openrunner.gpu.runner import run_forge_sync
-
+    # Forge/Modal are serverless client-side engines — no pod to provision. By
+    # default they run GOVERNED: submit a runner job whose engine token is
+    # injected server-side (the token never touches this machine). COMMAND is the
+    # App script. A caller who explicitly supplies the token via -e (FORGE_TOKEN /
+    # MODAL_TOKEN_SECRET) opts into running the engine client locally instead.
+    if provider in ("forge", "modal"):
+        _DEFAULT_IMAGE = "pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime"
+        local_tok = env_dict.get("FORGE_TOKEN") if provider == "forge" else env_dict.get("MODAL_TOKEN_SECRET")
         try:
-            result = run_forge_sync(
-                command=command,
-                api_key=env_dict.get("FORGE_TOKEN"),
-                api_url=env_dict.get("FORGE_API_URL"),
-                project=project,
-                env=env_dict,
-                emit=lambda m: click.echo(m),
-            )
+            if provider == "forge" and local_tok:
+                from openrunner.gpu.runner import run_forge_sync
+                result = run_forge_sync(
+                    command=command, api_key=env_dict.get("FORGE_TOKEN"),
+                    api_url=env_dict.get("FORGE_API_URL"), project=project,
+                    env=env_dict, emit=lambda m: click.echo(m),
+                )
+            else:
+                # Governed: the SERVER runs the engine via the engine-executor
+                # (token stays in OpenRunner; nothing runs here, no runner needed).
+                from openrunner.gpu.runner import run_engine_serverside_sync
+                result = run_engine_serverside_sync(
+                    provider=provider, command=command, project=project,
+                    emit=lambda m: click.echo(m),
+                )
         except Exception as exc:  # noqa: BLE001
             click.echo(f"gpu run failed: {exc}", err=True)
             raise SystemExit(1)

{openrunner_sdk-2.38.3 → openrunner_sdk-2.40.0}/openrunner/gpu/api_integration.py

@@ -331,6 +331,83 @@ class GpuAPIClient:
             logger.warning("get_credentials failed: %s", e)
             return None
 
+    # ------------------------------------------------------------------
+    # Governed runner jobs (client-side engines: forge/modal). The engine
+    # token is injected server-side into the runner's claim response — the
+    # client submits the job WITHOUT it and never sees it.
+    # ------------------------------------------------------------------
+
+    def submit_job(
+        self,
+        *,
+        provider: str | None,
+        command: str,
+        image: str,
+        env: dict[str, str] | None = None,
+        target_labels: list[str] | None = None,
+        project_id: str | None = None,
+        run_id: str | None = None,
+        gpu_count: int = 0,
+    ) -> dict[str, Any] | None:
+        """POST /api/v1/jobs -- enqueue a runner job. For a governed engine pass
+        ``provider`` ('forge'/'modal'); the API injects the org's decrypted token
+        into the runner's env at claim time. Returns the job dict or None."""
+        org = self.org_id()
+        if not org:
+            logger.warning("submit_job: no org resolved")
+            return None
+        body: dict[str, Any] = {
+            "type": "exec", "image": image, "command": command,
+            "gpu_count": gpu_count, "target_labels": target_labels or [],
+        }
+        if provider:
+            body["provider"] = provider
+        if env:
+            body["env"] = env
+        if project_id:
+            body["project_id"] = project_id
+        if run_id:
+            body["run_id"] = run_id
+        try:
+            r = self._client.post("/jobs", params={"org_id": org}, json=body)
+            r.raise_for_status()
+            return r.json()
+        except Exception as e:
+            detail = getattr(getattr(e, "response", None), "text", "") or str(e)
+            logger.warning("submit_job failed: %s", detail)
+            return None
+
+    def engine_run_stream(
+        self, *, engine: str, script_b64: str, name: str, args: list[str] | None = None,
+    ):
+        """POST /api/v1/gpu/engine/run and YIELD stdout lines. The server runs the
+        engine (Forge/Modal) via the executor with the org's decrypted token — the
+        token never comes here. A ``__ENGINE_EXIT__ <code>`` sentinel line ends it."""
+        org = self.org_id()
+        body = {"engine": engine, "script_b64": script_b64, "name": name,
+                "args": args or []}
+        with self._client.stream(
+            "POST", "/gpu/engine/run", params={"org_id": org}, json=body,
+        ) as r:
+            if r.status_code >= 400:
+                r.read()
+                yield f"[openrunner] server error {r.status_code}: {r.text[:300]}"
+                yield "__ENGINE_EXIT__ 1"
+                return
+            for line in r.iter_lines():
+                yield line
+
+    def get_job(self, job_id: str) -> dict[str, Any] | None:
+        """GET /api/v1/jobs/{id} -- poll a job's status/logs_tail/exit_code."""
+        try:
+            r = self._client.get(f"/jobs/{job_id}", params={"org_id": self.org_id()})
+            if r.status_code >= 400:
+                return None
+            return r.json()
+        except Exception as e:
+            logger.warning("get_job failed: %s", e)
+            return None
+
     # ------------------------------------------------------------------
     # Lifecycle
     # ------------------------------------------------------------------

{openrunner_sdk-2.38.3 → openrunner_sdk-2.40.0}/openrunner/gpu/runner.py

@@ -411,3 +411,163 @@ def run_forge_sync(
     exit_code = forge_exec(command, run_env, say)
     say(f"[openrunner] forge run finished (exit={exit_code}); serverless — nothing to terminate.")
     return {"exit_code": exit_code, "terminated": False}
+
+
+# ---------------------------------------------------------------------------
+# Governed client-side engines (Forge, Modal) — run on a runner, token injected
+# server-side. The user's machine never holds the engine token.
+# ---------------------------------------------------------------------------
+
+# Per-engine container recipe. The token env vars are injected by the API at
+# claim time (FORGE_TOKEN / MODAL_TOKEN_ID+SECRET) — not set here.
+_ENGINE_JOB_SPEC: dict[str, dict[str, str]] = {
+    "forge": {
+        "image": "python:3.13-slim",
+        "bootstrap": "pip install -q forge-shadow --extra-index-url https://forge.shadow-paas.com/sdk/",
+        "run": "forge run",
+    },
+    "modal": {
+        "image": "python:3.11-slim",
+        "bootstrap": "pip install -q modal",
+        "run": "modal run",
+    },
+}
+
+
+def run_engine_job_sync(
+    *,
+    provider: str,
+    command: str,
+    project: str | None = None,
+    image: str | None = None,
+    target_labels: list[str] | None = None,
+    env: dict[str, str] | None = None,
+    emit: Callable[[str], None] | None = None,
+    poll_interval: float = 3.0,
+    queue_warn_after: float = 20.0,
+) -> dict[str, Any]:
+    """Governed run of a client-side engine (Forge/Modal) via the runner-job
+    system. ``command`` is ``<local_script.py> [args...]``; the script is shipped
+    inline (base64) and run with ``<engine> run <script>`` inside the engine's
+    container ON A RUNNER. The API injects the org's decrypted token into the
+    runner's env at claim time — this machine never holds it. Returns
+    ``{"job_id","exit_code"}``.
+    """
+    import base64 as _b64
+    import os as _os
+
+    from openrunner.gpu import _get_api_client
+
+    say = emit or (lambda m: print(m, flush=True))
+    spec = _ENGINE_JOB_SPEC.get(provider)
+    if spec is None:
+        raise RuntimeError(f"'{provider}' is not a governed client-side engine")
+
+    parts = shlex.split(command)
+    if not parts:
+        raise RuntimeError("no script given")
+    script_path, args = parts[0], parts[1:]
+    try:
+        with open(script_path, "rb") as fh:
+            script_b64 = _b64.b64encode(fh.read()).decode()
+    except OSError as exc:
+        raise RuntimeError(f"cannot read script '{script_path}': {exc}") from exc
+    name = _os.path.basename(script_path) or "app.py"
+    arg_str = (" " + " ".join(shlex.quote(a) for a in args)) if args else ""
+    # Runner runs this via `sh -c`. Clean dir (engine snapshots cwd), install the
+    # client, materialize the script, run it.
+    container_cmd = (
+        f"set -e; mkdir -p /w && cd /w; {spec['bootstrap']}; "
+        f"printf %s '{script_b64}' | base64 -d > {shlex.quote(name)}; "
+        f"{spec['run']} {shlex.quote(name)}{arg_str}"
+    )
+
+    client = _get_api_client()
+    if client is None:
+        raise RuntimeError("Not logged in. Run 'openrunner login' first.")
+
+    say(f"[openrunner] submitting governed {provider} job (token injected "
+        "server-side; this machine never holds it) ...")
+    job = client.submit_job(
+        provider=provider, command=container_cmd, image=image or spec["image"],
+        env=env or None, target_labels=target_labels, project_id=project,
+        gpu_count=0,  # the entrypoint runs on CPU; the engine's fleet has the GPU
+    )
+    if not job or not job.get("id"):
+        raise RuntimeError(
+            f"failed to submit {provider} job — need an org {provider} credential "
+            f"(openrunner gpu credentials add --provider {provider} ...) and a "
+            "registered runner (openrunner runner start)."
+        )
+    jid = job["id"]
+    say(f"[openrunner] job {jid} queued — waiting for a runner to claim it ...")
+
+    seen = 0
+    warned = False
+    start = time.monotonic()
+    while True:
+        time.sleep(poll_interval)
+        j = client.get_job(jid) or {}
+        logs = j.get("logs_tail") or ""
+        if len(logs) > seen:
+            say(logs[seen:].rstrip("\n"))
+            seen = len(logs)
+        status = j.get("status")
+        if status in ("succeeded", "failed", "canceled"):
+            code = j.get("exit_code")
+            if code is None:
+                code = 0 if status == "succeeded" else 1
+            say(f"[openrunner] {provider} job {status} (exit={code}).")
+            return {"job_id": jid, "exit_code": int(code)}
+        if (not warned and status in (None, "queued")
+                and time.monotonic() - start > queue_warn_after):
+            warned = True
+            say("[openrunner] still queued — is a runner online? "
+                "`openrunner runner start` on a box in this org (needs Docker).")
+
+
+def run_engine_serverside_sync(
+    *,
+    provider: str,
+    command: str,
+    project: str | None = None,
+    emit: Callable[[str], None] | None = None,
+) -> dict[str, Any]:
+    """Governed run of a client-side engine (Forge/Modal) where the SERVER runs
+    it. Ships the App script to the API, which launches `forge run`/`modal run`
+    on the internal engine-executor with the org's decrypted token and streams
+    stdout back. The token never touches this machine and no runner is needed.
+    ``command`` is ``<local_script.py> [args...]``. Returns {"exit_code"}."""
+    import base64 as _b64
+    import os as _os
+
+    from openrunner.gpu import _get_api_client
+
+    say = emit or (lambda m: print(m, flush=True))
+    parts = shlex.split(command)
+    if not parts:
+        raise RuntimeError("no script given")
+    script_path, args = parts[0], parts[1:]
+    try:
+        with open(script_path, "rb") as fh:
+            b64 = _b64.b64encode(fh.read()).decode()
+    except OSError as exc:
+        raise RuntimeError(f"cannot read script '{script_path}': {exc}") from exc
+    name = _os.path.basename(script_path) or "app.py"
+
+    client = _get_api_client()
+    if client is None:
+        raise RuntimeError("Not logged in. Run 'openrunner login' first.")
+
+    say(f"[openrunner] launching {provider} server-side "
+        "(token stays in OpenRunner; nothing runs on this machine) ...")
+    exit_code = 1
+    for line in client.engine_run_stream(engine=provider, script_b64=b64, name=name, args=args):
+        if line.startswith("__ENGINE_EXIT__"):
+            try:
+                exit_code = int(line.split()[1])
+            except Exception:
+                exit_code = 1
+            continue
+        say(line.rstrip("\n"))
+    return {"exit_code": exit_code}

{openrunner_sdk-2.38.3 → openrunner_sdk-2.40.0}/openrunner/install_commands.py

@@ -3209,13 +3209,18 @@ Forge (shadow-paas.com) is a **serverless GPU fleet** -- like Modal. You deploy
 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
+- Governed (DEFAULT — token never touches your machine): 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:
+  `openrunner gpu run --provider forge <script.py>`. This submits a runner job;
+  the API injects the org's decrypted token into the runner server-side. COMMAND
+  is the App SCRIPT (GPU declared inside it, so no `--gpu`); the Run
+  auto-terminates. Needs a **registered runner** in the org
+  (`openrunner runner start`, needs Docker) — else the job sits queued.
+- Native client (runs locally, token on this box): `forge run <script.py>` (needs
+  the `forge-shadow` client on Python 3.13 + `FORGE_TOKEN`; install:
   `pip install forge-shadow --extra-index-url https://forge.shadow-paas.com/sdk/`).
+  `openrunner gpu run --provider forge -e FORGE_TOKEN=fg_.. <script>` also runs
+  local.
 
 ## How the function runs (mental model)
 `forge run script.py` runs `@app.local_entrypoint()` on YOUR machine; each

{openrunner_sdk-2.38.3 → openrunner_sdk-2.40.0}/pyproject.toml

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

openrunner_sdk-2.40.0/tests/test_gpu/test_engine_serverside.py

@@ -0,0 +1,30 @@
+"""SDK server-side engine run: streams the server's stdout, token never local."""
+from __future__ import annotations
+from unittest.mock import patch
+from openrunner.gpu import runner as R
+
+
+class _Fake:
+    def __init__(self, lines): self.args=None; self._lines=lines
+    def engine_run_stream(self, **kwargs):
+        self.args=kwargs
+        yield from self._lines
+
+
+def test_serverside_streams_and_parses_exit(tmp_path):
+    s=tmp_path/"app.py"; s.write_text("print('x')\n")
+    fake=_Fake(["step 1","step 2","__ENGINE_EXIT__ 0"])
+    out=[]
+    with patch("openrunner.gpu._get_api_client", return_value=fake):
+        res=R.run_engine_serverside_sync(provider="forge", command=str(s), emit=out.append)
+    assert res=={"exit_code":0}
+    assert fake.args["engine"]=="forge" and fake.args["name"]=="app.py"
+    assert "script_b64" in fake.args  # script shipped, no token
+    assert "step 2" in out and not any("__ENGINE_EXIT__" in l for l in out)
+
+
+def test_serverside_nonzero_exit(tmp_path):
+    s=tmp_path/"m.py"; s.write_text("x=1\n")
+    with patch("openrunner.gpu._get_api_client", return_value=_Fake(["boom","__ENGINE_EXIT__ 5"])):
+        res=R.run_engine_serverside_sync(provider="modal", command=str(s), emit=lambda _l:None)
+    assert res["exit_code"]==5

openrunner_sdk-2.40.0/tests/test_gpu/test_governed_jobs.py

@@ -0,0 +1,74 @@
+"""SDK governed engine run: submits a runner job (no token) + streams logs."""
+
+from __future__ import annotations
+
+import base64
+from unittest.mock import patch
+
+from openrunner.gpu import runner as R
+
+
+class _FakeClient:
+    def __init__(self, statuses):
+        self.submitted = None
+        self._statuses = list(statuses)
+
+    def submit_job(self, **kwargs):
+        self.submitted = kwargs
+        return {"id": "job-1"}
+
+    def get_job(self, job_id):
+        return self._statuses.pop(0) if self._statuses else {"status": "succeeded", "exit_code": 0}
+
+
+def test_run_engine_job_builds_inline_script_and_streams(tmp_path):
+    script = tmp_path / "app.py"
+    script.write_text("print('hi')\n")
+    fake = _FakeClient([
+        {"status": "running", "logs_tail": "step 1\n"},
+        {"status": "running", "logs_tail": "step 1\nstep 2\n"},
+        {"status": "succeeded", "exit_code": 0, "logs_tail": "step 1\nstep 2\ndone\n"},
+    ])
+    lines: list[str] = []
+    with patch("openrunner.gpu._get_api_client", return_value=fake):
+        result = R.run_engine_job_sync(
+            provider="forge", command=str(script),
+            emit=lines.append, poll_interval=0,
+        )
+    assert result["exit_code"] == 0 and result["job_id"] == "job-1"
+    # Governed: provider marker set, NO token in the submitted env, gpu_count 0.
+    s = fake.submitted
+    assert s["provider"] == "forge"
+    assert s["gpu_count"] == 0
+    assert "FORGE_TOKEN" not in (s.get("env") or {})
+    # Script shipped inline (base64) + run via the forge client in a clean dir.
+    b64 = base64.b64encode(b"print('hi')\n").decode()
+    assert b64 in s["command"]
+    assert "forge run app.py" in s["command"]
+    assert s["image"] == "python:3.13-slim"
+    # Incremental log deltas streamed (not the whole buffer each poll).
+    assert any("done" in ln for ln in lines)
+
+
+def test_run_engine_job_modal_defaults(tmp_path):
+    script = tmp_path / "m.py"
+    script.write_text("x=1\n")
+    fake = _FakeClient([{"status": "failed", "exit_code": 3, "logs_tail": "boom\n"}])
+    with patch("openrunner.gpu._get_api_client", return_value=fake):
+        result = R.run_engine_job_sync(provider="modal", command=str(script),
+                                       emit=lambda _l: None, poll_interval=0)
+    assert result["exit_code"] == 3
+    assert fake.submitted["image"] == "python:3.11-slim"
+    assert "modal run m.py" in fake.submitted["command"]
+
+
+def test_run_engine_job_missing_script_errors():
+    fake = _FakeClient([])
+    with patch("openrunner.gpu._get_api_client", return_value=fake):
+        try:
+            R.run_engine_job_sync(provider="forge", command="/no/such.py",
+                                  emit=lambda _l: None, poll_interval=0)
+        except RuntimeError as e:
+            assert "cannot read script" in str(e)
+        else:
+            raise AssertionError("expected RuntimeError")