runbay 0.1.0__py3-none-any.whl

runbay/__init__.py

@@ -0,0 +1,46 @@
+"""RunBay SDK — deploy and call serverless GPU endpoints."""
+
+from .client import Endpoint, Job
+from .decorator import (
+    CpuGroup,
+    CpuInstanceType,
+    EndpointFunction,
+    GpuGroup,
+    asgi_app,
+    endpoint,
+    fastapi_endpoint,
+    web_server,
+)
+from .dict import Dict
+from .entrypoint import LocalEntrypoint, is_local, local_entrypoint
+from .environment import Environment
+from .exceptions import (
+    ApiError,
+    AuthError,
+    Error,
+    InsufficientBalanceError,
+    JobError,
+    NotFoundError,
+    RemoteError,
+    SandboxError,
+    TimeoutError,
+)
+from .queue import Queue
+from .retries import Retries
+from .sandbox import Sandbox, SandboxSnapshot, Tunnel
+from .schedule import Cron, Period
+from .secret import Secret
+from .volume import Volume
+from . import serverless
+
+__version__ = "0.1.0"
+__all__ = [
+    "endpoint", "asgi_app", "web_server", "fastapi_endpoint", "local_entrypoint", "LocalEntrypoint", "is_local",
+    "GpuGroup", "CpuGroup", "CpuInstanceType", "Cron", "Period", "Retries",
+    "EndpointFunction", "Endpoint", "Job", "Sandbox", "SandboxSnapshot", "Tunnel",
+    "Secret", "Volume", "Dict", "Queue", "Environment",
+    # exceptions
+    "Error", "ApiError", "AuthError", "NotFoundError", "InsufficientBalanceError",
+    "SandboxError", "JobError", "RemoteError", "TimeoutError",
+    "serverless",
+]

runbay/api.py

@@ -0,0 +1,384 @@
+"""Management API client (auth, endpoints CRUD, artifact upload)."""
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+import requests
+
+from .config import get_api_url, get_auth_token
+# Re-exported so `from .api import ApiError` (and callers) keep working.
+from .exceptions import ApiError, api_error
+
+
+class ManagementClient:
+    def __init__(self, api_url: Optional[str] = None, token: Optional[str] = None):
+        self.api_url = (api_url or get_api_url()).rstrip("/")
+        self.token = token or get_auth_token()
+        self.session = requests.Session()
+        # explicit UA: proxies (e.g. Cloudflare) may block default python UAs
+        self.session.headers["User-Agent"] = "runbay-sdk/0.1.0"
+
+    def _headers(self, auth: bool = True) -> Dict[str, str]:
+        # requests sets Content-Type itself when json= is passed; sending it
+        # on body-less POSTs makes Fastify reject the empty body with a 400
+        headers: Dict[str, str] = {}
+        if auth:
+            if not self.token:
+                raise ApiError(401, "Not logged in — run 'rb login' or set RB_API_KEY")
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def _request(self, method: str, path: str, auth: bool = True, **kwargs) -> Any:
+        res = self.session.request(
+            method,
+            f"{self.api_url}{path}",
+            headers=self._headers(auth),
+            timeout=kwargs.pop("timeout", 60),
+            **kwargs,
+        )
+        if res.status_code >= 400:
+            try:
+                message = res.json().get("error", res.text)
+            except ValueError:
+                message = res.text
+            raise api_error(res.status_code, message)
+        return res.json() if res.text else {}
+
+    # ---- auth ----
+
+    def register(self, email: str, name: str, password: str) -> Dict[str, Any]:
+        return self._request(
+            "POST", "/user/register", auth=False,
+            json={"email": email, "name": name, "password": password},
+        )
+
+    def login(self, email: str, password: str) -> Dict[str, Any]:
+        return self._request(
+            "POST", "/user/login", auth=False, json={"email": email, "password": password}
+        )
+
+    def create_api_key(self, name: str = "default") -> Dict[str, Any]:
+        return self._request("POST", "/user/apikey", json={"name": name})
+
+    def me(self) -> Dict[str, Any]:
+        return self._request("GET", "/user/me")
+
+    def balance(self) -> Dict[str, Any]:
+        return self._request("GET", "/user/balance")
+
+    def usage(self, limit: int = 50) -> Dict[str, Any]:
+        return self._request("GET", "/user/usage", params={"limit": str(limit)})
+
+    def gpus(self) -> list:
+        """Merged compute catalog (GPU + CPU entries, each with a `kind` field).
+
+        Backend returns `{gpus: [...], cpus: [...]}`; we merge into one list so
+        callers reading `kind` stay backward compatible.
+        """
+        data = self._request("GET", "/api/gpus")
+        return [*data.get("gpus", []), *data.get("cpus", [])]
+
+    # ---- sandboxes ----
+
+    def create_sandbox(self, spec: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/api/sandboxes", json=spec)["sandbox"]
+
+    def list_sandboxes(self, include_terminated: bool = False) -> list:
+        params = {"all": "true"} if include_terminated else {}
+        return self._request("GET", "/api/sandboxes", params=params)["sandboxes"]
+
+    def get_sandbox(self, sandbox_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/sandboxes/{sandbox_id}")["sandbox"]
+
+    def terminate_sandbox(self, sandbox_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/api/sandboxes/{sandbox_id}")
+
+    # ---- sandbox snapshots ----
+
+    def create_sandbox_snapshot(self, sandbox_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/api/sandboxes/{sandbox_id}/snapshot")["snapshot"]
+
+    def list_sandbox_snapshots(self, sandbox_id: Optional[str] = None) -> list:
+        params = {"sandboxId": sandbox_id} if sandbox_id else {}
+        return self._request("GET", "/api/sandbox-snapshots", params=params)["snapshots"]
+
+    def get_sandbox_snapshot(self, snapshot_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/sandbox-snapshots/{snapshot_id}")["snapshot"]
+
+    def delete_sandbox_snapshot(self, snapshot_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/api/sandbox-snapshots/{snapshot_id}")
+
+    # ---- endpoints ----
+
+    def create_endpoint(self, spec: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/api/endpoints", json=spec)["endpoint"]
+
+    def list_endpoints(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/endpoints", params=params)["endpoints"]
+
+    # ---- environments ----
+
+    def list_environments(self) -> list:
+        return self._request("GET", "/api/environments")["environments"]
+
+    def create_environment(self, name: str, web_suffix: str = "") -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if web_suffix:
+            body["webSuffix"] = web_suffix
+        return self._request("POST", "/api/environments", json=body)["environment"]
+
+    def update_environment(
+        self,
+        name: str,
+        set_name: Optional[str] = None,
+        set_web_suffix: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if set_name is not None:
+            body["setName"] = set_name
+        if set_web_suffix is not None:
+            body["setWebSuffix"] = set_web_suffix
+        if not body:
+            raise ValueError("update_environment requires set_name or set_web_suffix")
+        return self._request("PATCH", f"/api/environments/{name}", json=body)["environment"]
+
+    def delete_environment(self, name: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/api/environments/{name}")
+
+    def storage(self) -> Dict[str, Any]:
+        return self._request("GET", "/user/storage")["storage"]
+
+    def get_endpoint(self, endpoint_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/endpoints/{endpoint_id}")["endpoint"]
+
+    def update_endpoint(self, endpoint_id: str, spec: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("PATCH", f"/api/endpoints/{endpoint_id}", json=spec)["endpoint"]
+
+    def delete_endpoint(self, endpoint_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/api/endpoints/{endpoint_id}")
+
+    def list_jobs(self, endpoint_id: str, status: Optional[str] = None, limit: int = 50) -> list:
+        params = {"limit": str(limit)}
+        if status:
+            params["status"] = status
+        return self._request("GET", f"/api/endpoints/{endpoint_id}/jobs", params=params)["jobs"]
+
+    def list_workers(self, endpoint_id: str) -> list:
+        return self._request("GET", f"/api/endpoints/{endpoint_id}/workers")["workers"]
+
+    # ---- volumes ----
+
+    def create_volume(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if environment is not None:
+            body["environment"] = environment
+        return self._request("POST", "/api/volumes", json=body)["volume"]
+
+    def list_volumes(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/volumes", params=params)["volumes"]
+
+    def get_volume(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/volumes/{name}", params=params)["volume"]
+
+    def delete_volume(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/volumes/{name}", params=params)
+
+    def rename_volume(self, old_name: str, new_name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("PATCH", f"/api/volumes/{old_name}", params=params, json={"name": new_name})["volume"]
+
+    def list_volume_files(self, name: str, prefix: str = "", environment: Optional[str] = None) -> list:
+        params: Dict[str, str] = {}
+        if prefix:
+            params["prefix"] = prefix
+        if environment is not None:
+            params["environment"] = environment
+        return self._request("GET", f"/api/volumes/{name}/files", params=params)["files"]
+
+    def delete_volume_path(self, name: str, path: str, recursive: bool = False, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/volumes/{name}/files", params=params, json={"path": path, "recursive": recursive})
+
+    def get_volume_upload_url(self, name: str, path: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/volumes/{name}/upload-url", params=params, json={"path": path})
+
+    def get_volume_download_url(self, name: str, path: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/volumes/{name}/download-url", params=params, json={"path": path})
+
+    # ---- dicts ----
+
+    def create_dict(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if environment is not None:
+            body["environment"] = environment
+        return self._request("POST", "/api/dicts", json=body)["dict"]
+
+    def list_dicts(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/dicts", params=params)["dicts"]
+
+    def get_dict(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/dicts/{name}", params=params)["dict"]
+
+    def rename_dict(self, old_name: str, new_name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("PATCH", f"/api/dicts/{old_name}", params=params, json={"name": new_name})["dict"]
+
+    def delete_dict(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/dicts/{name}", params=params)
+
+    def list_dict_entries(
+        self, name: str, limit: int = 100, search: str = "", environment: Optional[str] = None
+    ) -> Dict[str, Any]:
+        params: Dict[str, str] = {"limit": str(limit)}
+        if search:
+            params["search"] = search
+        if environment is not None:
+            params["environment"] = environment
+        return self._request("GET", f"/api/dicts/{name}/entries", params=params)
+
+    def get_dict_entry(self, name: str, key: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/dicts/{name}/entries/{quote(key, safe='')}", params=params)
+
+    def put_dict_entry(self, name: str, key: str, value: Any, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request(
+            "PUT", f"/api/dicts/{name}/entries/{quote(key, safe='')}", params=params, json={"value": value}
+        )
+
+    def put_dict_entries(self, name: str, entries: Dict[str, Any], environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/dicts/{name}/entries", params=params, json={"entries": entries})
+
+    def delete_dict_entry(self, name: str, key: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/dicts/{name}/entries/{quote(key, safe='')}", params=params)
+
+    def clear_dict(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/dicts/{name}/clear", params=params)
+
+    # ---- queues ----
+
+    def create_queue(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if environment is not None:
+            body["environment"] = environment
+        return self._request("POST", "/api/queues", json=body)["queue"]
+
+    def list_queues(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/queues", params=params)["queues"]
+
+    def get_queue(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/queues/{name}", params=params)["queue"]
+
+    def rename_queue(self, old_name: str, new_name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("PATCH", f"/api/queues/{old_name}", params=params, json={"name": new_name})["queue"]
+
+    def delete_queue(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/queues/{name}", params=params)
+
+    def queue_put(self, name: str, items: List[Any], environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/queues/{name}/put", params=params, json={"items": items})
+
+    def queue_pop(self, name: str, n: int = 1, environment: Optional[str] = None) -> List[Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/queues/{name}/pop", params=params, json={"n": n})["items"]
+
+    def queue_peek(self, name: str, limit: int = 50, environment: Optional[str] = None) -> list:
+        params: Dict[str, str] = {"limit": str(limit)}
+        if environment is not None:
+            params["environment"] = environment
+        return self._request("GET", f"/api/queues/{name}/peek", params=params)["entries"]
+
+    def queue_len(self, name: str, environment: Optional[str] = None) -> int:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/queues/{name}/len", params=params)["length"]
+
+    def clear_queue(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/queues/{name}/clear", params=params)
+
+    # ---- secrets ----
+
+    def create_secret(self, name: str, values: Dict[str, str], environment: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name, "values": values}
+        if environment is not None:
+            body["environment"] = environment
+        return self._request("POST", "/api/secrets", json=body)["secret"]
+
+    def list_secrets(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/secrets", params=params)["secrets"]
+
+    def get_secret(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/secrets/{name}", params=params)["secret"]
+
+    def update_secret(
+        self,
+        name: str,
+        *,
+        new_name: Optional[str] = None,
+        values: Optional[Dict[str, str]] = None,
+        environment: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if new_name is not None:
+            body["name"] = new_name
+        if values is not None:
+            body["values"] = values
+        params = {"environment": environment} if environment else {}
+        return self._request("PATCH", f"/api/secrets/{name}", params=params, json=body)["secret"]
+
+    def delete_secret(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/secrets/{name}", params=params)
+
+    # ---- deploy ----
+
+    def get_upload_url(self, endpoint_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/api/endpoints/{endpoint_id}/artifact/upload-url")
+
+    def upload_artifact(self, upload_url: str, bundle_path: str) -> None:
+        with open(bundle_path, "rb") as f:
+            res = requests.put(
+                upload_url, data=f, headers={"Content-Type": "application/gzip"}, timeout=600
+            )
+        if res.status_code >= 400:
+            raise ApiError(res.status_code, f"artifact upload failed: {res.text[:500]}")
+
+    def commit_artifact(
+        self,
+        endpoint_id: str,
+        key: str,
+        version: int,
+        handler: Optional[str] = None,
+        python: Optional[str] = None,
+        packages: Optional[List[Any]] = None,
+        files: Optional[List[Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"key": key, "version": version}
+        if handler:
+            body["handler"] = handler
+        if python:
+            body["python"] = python
+        if packages is not None:
+            body["packages"] = packages
+        if files is not None:
+            body["files"] = files
+        return self._request("POST", f"/api/endpoints/{endpoint_id}/artifact/commit", json=body)

runbay/cli/__init__.py

@@ -0,0 +1,5 @@
+"""RunBay CLI (`rb`) — command package."""
+
+from .main import main
+
+__all__ = ["main"]

runbay/cli/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m runbay.cli` entry point."""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

runbay/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules (each owns its Click group/commands)."""

runbay/cli/commands/account.py

@@ -0,0 +1,94 @@
+"""Account commands: login, whoami, register(hidden), apikey(hidden)."""
+
+import getpass
+from typing import Any, Dict, Optional
+
+import click
+
+from ...api import ApiError, ManagementClient
+from ...config import save_credentials
+from ..utils.client import _browser_login, _client, _save_login
+from ..utils.output import _die, _print_json
+from ..utils.rich_help import RichCommand as _Cmd
+
+
+@click.command(cls=_Cmd)
+@click.argument("api_key", required=False)
+@click.option("--browser", "use_browser", is_flag=True, help="Authorize through the web console")
+@click.option("--api-url", default=None, help="Backend API URL (persisted)")
+def login(api_key: Optional[str], use_browser: bool, api_url: Optional[str]) -> None:
+    """Log in — through the browser (default) or with an API key.
+
+    rb login                 interactive: browser or paste an API key
+    rb login --browser       straight to browser authorization
+    rb login rb_...          use an existing API key
+    """
+    if api_key:
+        return _save_login(api_key, api_url)
+    if use_browser:
+        return _browser_login(api_url)
+
+    choice = click.prompt(
+        "how do you want to authenticate?\n  [1] browser (opens the web console)\n  [2] paste an API key\n",
+        type=click.Choice(["1", "2"]),
+        default="1",
+        show_choices=False,
+    )
+    if choice == "1":
+        return _browser_login(api_url)
+
+    api_key = getpass.getpass("API key (rb_...): ").strip()
+    if not api_key:
+        _die("an API key is required")
+    _save_login(api_key, api_url)
+
+
+@click.command(cls=_Cmd, hidden=True)
+@click.option("--email", prompt=True)
+@click.option("--name", prompt=True)
+@click.option("--api-url", default=None, help="Backend API URL (persisted)")
+def register(email: str, name: str, api_url: Optional[str]) -> None:
+    """Create an account and an initial API key."""
+    password = getpass.getpass("Password: ")
+    client = ManagementClient(api_url=api_url)
+    try:
+        data = client.register(email, name, password)
+        # mint the first API key with the fresh session and store it
+        session = ManagementClient(api_url=api_url, token=data["token"])
+        key = session.create_api_key("default")["apiKey"]
+    except ApiError as exc:
+        _die(str(exc))
+
+    creds: Dict[str, Any] = {"api_key": key, "email": email}
+    if api_url:
+        creds["api_url"] = api_url
+    save_credentials(creds)
+    click.secho(f"account created for {email}", fg="green")
+    click.echo(f"API key (default): {key}")
+    click.secho("store it now — it cannot be retrieved again (saved to ~/.runbay)", fg="yellow")
+
+
+@click.command(cls=_Cmd, hidden=True)
+@click.option("--name", default="default", help="Label for the key")
+@click.option("--save/--no-save", default=True, help="Store the key in ~/.runbay")
+def apikey(name: str, save: bool) -> None:
+    """Create a new API key."""
+    try:
+        data = _client().create_api_key(name)
+    except ApiError as exc:
+        _die(str(exc))
+    click.echo(f"API key ({name}): {data['apiKey']}")
+    click.secho("store it now — it cannot be retrieved again", fg="yellow")
+    if save:
+        save_credentials({"api_key": data["apiKey"]})
+        click.echo("saved to ~/.runbay/config.json (used for future CLI/SDK calls)")
+
+
+@click.command(cls=_Cmd)
+def whoami() -> None:
+    """Show the logged-in account."""
+    try:
+        data = _client().me()
+    except ApiError as exc:
+        _die(str(exc))
+    _print_json(data)

runbay/cli/commands/billing.py

@@ -0,0 +1,66 @@
+"""Billing commands (hidden from `rb --help`): gpus, balance.
+
+The catalog and usage live in the web console; these stay for power users.
+"""
+
+import click
+
+from ...api import ApiError
+from ..utils.client import _client
+from ..utils.output import _die, _format_bytes, _print_table
+from ..utils.rich_help import RichCommand as _Cmd
+
+
+@click.command(cls=_Cmd, hidden=True)
+def gpus() -> None:
+    """List available compute types (GPU and CPU) and pricing."""
+    try:
+        catalog = _client().gpus()
+    except ApiError as exc:
+        _die(str(exc))
+    # group by kind (gpu first, then cpu) so the two sections read clearly
+    catalog.sort(key=lambda g: (0 if g.get("kind", "gpu") == "gpu" else 1, g["pricePerHour"]))
+    _print_table(
+        ["TYPE", "KIND", "NAME", "MEMORY", "PRICE/HR"],
+        [
+            [g["id"], g.get("kind", "gpu"), g["name"], f"{g['memoryGb']} GB", f"${g['pricePerHour']:.2f}"]
+            for g in catalog
+        ],
+    )
+
+
+@click.command(cls=_Cmd, hidden=True)
+@click.option("--limit", default=15, help="Usage records to show")
+def balance(limit: int) -> None:
+    """Show balance and recent GPU usage (billed per second)."""
+    try:
+        data = _client().usage(limit=limit)
+    except ApiError as exc:
+        _die(str(exc))
+    click.echo(f"balance:     ${data['balance']:.4f}")
+    try:
+        storage = _client().storage()
+        gb = storage["totalBytes"] / (1024 ** 3)
+        click.echo(
+            f"storage:     {gb:.2f} GB used ({storage['freeGb']} GB free tier, "
+            f"${storage['pricePerGbMonth']:.2f}/GB/mo -> est ${storage['estMonthlyUsd']:.2f}/mo)"
+        )
+    except ApiError:
+        pass
+    click.echo(f"total spent: ${data['totalSpent']:.4f} ({int(data['totalSeconds'])}s of GPU time)")
+    if data["usage"]:
+        click.echo("")
+        _print_table(
+            ["WHEN", "KIND", "REF", "GPU", "SECONDS", "COST"],
+            [
+                [
+                    str(u.get("startedAt", ""))[:19],
+                    u.get("kind", ""),
+                    u.get("refId", ""),
+                    f"{u.get('gpuType', '')} x{u.get('gpuNum', 1)}",
+                    str(int(u.get("seconds", 0))),
+                    f"${u.get('amount', 0):.4f}",
+                ]
+                for u in data["usage"][:limit]
+            ],
+        )

runbay/cli/commands/build_utils/__init__.py

@@ -0,0 +1,16 @@
+"""Deploy build utilities: handler scaffolding, source scanning, resource configs, manifest."""
+
+from .handler_generator import generate_handler
+from .manifest import finalize_manifest, RB_REQUIREMENTS_FILE, ARTIFACT_NAME
+from .resource_config_generator import build_resource
+from .scanner import discover, DiscoveredFn
+
+__all__ = [
+    "generate_handler",
+    "finalize_manifest",
+    "build_resource",
+    "discover",
+    "DiscoveredFn",
+    "RB_REQUIREMENTS_FILE",
+    "ARTIFACT_NAME",
+]

runbay/cli/commands/build_utils/handler_generator.py

@@ -0,0 +1,29 @@
+"""Generate the starter `handler.py` for `rb init`."""
+
+_HANDLER_TEMPLATE = '''\
+from runbay import endpoint
+
+
+@endpoint(
+    name="{name}",
+    # gpu=GpuGroup.ADA_24,          # GPU product id or alias (platform default if omitted)
+    workers=1,                      # max concurrent workers
+    idle_timeout=60,                # seconds idle before scale-down (to zero)
+    dependencies=[],                # pip packages installed on the worker
+)
+def {fn_name}(name="world"):
+    """Runs on a serverless GPU worker. Return anything JSON-serializable."""
+    return {{"greeting": f"Hello, {{name}}!"}}
+
+
+if __name__ == "__main__":
+    # local test:      python handler.py
+    # deploy:          rb deploy
+    # remote call:     {fn_name}("RunBay")  (after deploy, from any script)
+    print({fn_name}.local(name="local"))
+'''
+
+
+def generate_handler(name: str, fn_name: str) -> str:
+    """Render the starter handler source for an endpoint named `name`."""
+    return _HANDLER_TEMPLATE.format(name=name, fn_name=fn_name)