wherobots-python-sdk 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

wherobots/__init__.py

@@ -39,6 +39,7 @@ from wherobots.models import (
     RunPythonPayload,
     RunView,
     StorageIntegration,
+    UtilizationStats,
 )
 
 # Convenience alias
@@ -84,4 +85,5 @@ __all__ = [
     "PyPiDependency",
     "FileDependency",
     "StorageIntegration",
+    "UtilizationStats",
 ]

wherobots/__version__.py

@@ -1,5 +1,5 @@
 """Version information."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 __author__ = "Wherobots"
 __email__ = "support@wherobots.com"

wherobots/api/runs.py

@@ -101,15 +101,15 @@ class RunsAPI:
     def create(
         self,
         payload: CreateRunPayload,
-        region: str = "aws-us-west-2",
+        region: str | None = None,
     ) -> RunView:
         """Submit a new job run (``POST /runs``).
 
         Args:
             payload: The run configuration including script/JAR
                 details, runtime, and resource settings.
-            region: Wherobots deployment region (default
-                ``"aws-us-west-2"``).
+            region: Wherobots deployment region. When omitted, the API
+                applies the organization's configured default region.
 
         Returns:
             A ``RunView`` representing the created run.
@@ -117,9 +117,11 @@ class RunsAPI:
         Raises:
             WherobotsAPIError: On HTTP or JSON-parsing failures.
         """
-        params = {"region": region}
+        params = {}
+        if region:
+            params["region"] = region
         body = payload.to_dict()
-        logger.info("Creating run '%s' in %s", payload.name, region)
+        logger.info("Creating run '%s' in %s", payload.name, region or "org default")
         response = self._client.post("/runs", params=params, json_body=body)
         return RunView.from_dict(self._parse_json(response))
 

wherobots/client.py

@@ -29,6 +29,8 @@ from wherobots.models import (
     RunMetricsResponse,
     RunPythonPayload,
     RunView,
+    UtilizationStats,
+    extract_instant_value,
 )
 from wherobots.utils.logger import get_logger
 from wherobots.utils.validation import validate_name
@@ -52,13 +54,60 @@ class WherobotsJob:
 
     Manages the lifecycle of Wherobots job runs including submission,
     monitoring, log streaming, and cancellation.
+
+    Use :meth:`from_run_id` to attach to an existing run for read-only
+    log/metrics access without binding a script.
     """
 
+    # Candidate metric key names. The metrics endpoint is server-defined
+    # and untyped (see ``RunMetricsResponse``); the UPPERCASE names are
+    # the current production keys, with lowercase fallbacks kept for
+    # forward-compat. Confirmed against run gt3oirei5widjk (2026-06-11).
+    _CPU_METRIC_KEYS: tuple[str, ...] = ("CPU_UTILIZATION_PERCENT", "cpu_usage", "cpu")
+    _MEM_METRIC_KEYS: tuple[str, ...] = (
+        "MEMORY_UTILIZATION_PERCENT",
+        "memory_usage",
+        "mem_usage",
+    )
+    _COST_METRIC_KEYS: tuple[str, ...] = ("COST_USD", "cost_usd")
+    _SU_METRIC_KEYS: tuple[str, ...] = ("CONSUMED_SPATIAL_UNITS", "consumed_spatial_units")
+
+    # Instance attribute type declarations. ``_init_defaults`` (called
+    # by both ``__init__`` and ``from_run_id``) assigns initial values
+    # for every name listed here. Adding a new instance attribute means
+    # one declaration here + one assignment in ``_init_defaults`` —
+    # both constructor paths then pick it up automatically.
+    script: str | None
+    name: str | None
+    runtime: str | None
+    region: str | None
+    version: str | None
+    timeout_seconds: int
+    args: list[str]
+    spark_configs: dict[str, str]
+    dependencies: list[dict[str, Any]]
+    spark_driver_disk_gb: int | None
+    spark_executor_disk_gb: int | None
+    s3_bucket: str | None
+    s3_prefix: str | None
+    jar_main_class: str | None
+    auto_upload: bool
+    is_jar: bool
+    run_id: str | None
+    # Status may be a string when the server returns a value the
+    # SDK's JobStatus enum doesn't recognize yet (forward-compat).
+    status: JobStatus | str | None
+    _last_log_cursor: int | str
+    _script_uri: str | None
+    _attached: bool
+    _config: WherobotsConfig
+    _api: RunsAPI
+
     def __init__(
         self,
         script: str,
         name: str,
-        runtime: str | Runtime = "tiny",
+        runtime: str | Runtime | None = None,
         region: str | Region | None = None,
         api_key: str | None = None,
         version: str | None = None,
@@ -82,8 +131,19 @@ class WherobotsJob:
             script: Path to Python script (.py) or JAR file (.jar).
                    Can be local path or S3 URI (s3://bucket/key)
             name: Job name (8-255 chars, alphanumeric, _, -, .)
-            runtime: Compute runtime size (default: "tiny")
-            region: AWS region (default: from config or env)
+            runtime: The compute runtime to use. Accepts a ``Runtime`` enum
+                value or a raw string; strings are passed to the API as-is.
+                Override the default runtime set for your organization — only
+                set this if you need a specific runtime instead of the one your
+                administrator has configured. When omitted, your organization's
+                default runtime is used.
+            region: The compute region to run in. Accepts a ``Region`` enum
+                value or a raw string (e.g. a BYOC region such as
+                ``byoc-acme-us-east-1``); strings are passed to the API as-is.
+                Override the default region set for your organization — only set
+                this if you intend to use a specific region instead of the one
+                your administrator has configured. When omitted, your
+                organization's default region is used.
             api_key: Wherobots API key (or set WHEROBOTS_API_KEY env var)
             version: Wherobots version ("latest" or "preview")
             timeout_seconds: Job timeout in seconds (default: 3600)
@@ -119,9 +179,8 @@ class WherobotsJob:
                 f"spark_executor_disk_gb must be non-negative, got {spark_executor_disk_gb}"
             )
 
-        self.script = script
-        self.name = validate_name(name)
-        self.runtime = runtime.value if isinstance(runtime, Runtime) else runtime
+        self._init_defaults()
+
         region_value = region.value if isinstance(region, Region) else region
 
         # Deprecation warnings for s3_bucket / s3_prefix are emitted by
@@ -138,7 +197,12 @@ class WherobotsJob:
             request_timeout_seconds=request_timeout_seconds,
         )
 
-        self.region = region_value or self._config.region or "aws-us-west-2"
+        self.script = script
+        self.name = validate_name(name)
+        self.runtime = runtime.value if isinstance(runtime, Runtime) else runtime
+        # No hardcoded fallback: when neither the argument nor the config
+        # supplies a region, leave it unset so the API applies the org default.
+        self.region = region_value or self._config.region
         self.version = version or self._config.version
         self.timeout_seconds = timeout_seconds
         self.args = args or []
@@ -151,20 +215,44 @@ class WherobotsJob:
         self.jar_main_class = jar_main_class
         self.auto_upload = auto_upload
 
-        self.run_id: str | None = None
-        # Status may be a string when the server returns a value the
-        # SDK's JobStatus enum doesn't recognize yet (forward-compat).
-        self.status: JobStatus | str | None = None
-        self._last_log_cursor: int | str = 0
-        self._script_uri: str | None = None
-
         self.is_jar = script.lower().endswith(".jar")
         if self.is_jar and not jar_main_class:
             raise WherobotsValidationError("jar_main_class is required for JAR files")
 
-        # Build the API layer
         self._api = RunsAPI.from_config(self._config)
 
+    def _init_defaults(self) -> None:
+        """Initialize instance attributes shared by every construction path.
+
+        Both ``__init__`` and :meth:`from_run_id` MUST call this first,
+        then override the subset of fields they own. Any new instance
+        attribute that lives on every ``WherobotsJob`` belongs here
+        (and in the class-level type declarations above) — adding it
+        in only one constructor would leave the other in a
+        partially-constructed state.
+        """
+        self.script = None
+        self.name = None
+        self.runtime = None
+        self.region = None
+        self.version = None
+        self.timeout_seconds = 0
+        self.args = []
+        self.spark_configs = {}
+        self.dependencies = []
+        self.spark_driver_disk_gb = None
+        self.spark_executor_disk_gb = None
+        self.s3_bucket = None
+        self.s3_prefix = None
+        self.jar_main_class = None
+        self.auto_upload = False
+        self.is_jar = False
+        self.run_id = None
+        self.status = None
+        self._last_log_cursor = 0
+        self._script_uri = None
+        self._attached = False
+
     # ------------------------------------------------------------------ #
     # Upload helpers
     # ------------------------------------------------------------------ #
@@ -187,6 +275,10 @@ class WherobotsJob:
         if self._script_uri:
             return self._script_uri
 
+        # Only reachable from submit(), which raises in attached mode
+        # before getting here. The asserts narrow ``str | None`` -> ``str``.
+        assert self.script is not None, "script must be set in submit-mode"
+
         if self._is_s3_uri(self.script):
             self._script_uri = self.script
         elif self.auto_upload:
@@ -227,6 +319,10 @@ class WherobotsJob:
     # ------------------------------------------------------------------ #
 
     def _build_payload(self) -> CreateRunPayload:
+        # Only reachable from submit(); attached instances raise earlier.
+        # Runtime is optional — the API applies the org default when unset.
+        assert self.name is not None, "name must be set in submit-mode"
+
         script_uri = self._prepare_script_uri()
 
         run_python: RunPythonPayload | None = None
@@ -265,6 +361,99 @@ class WherobotsJob:
             environment=environment,
         )
 
+    # ------------------------------------------------------------------ #
+    # Attach
+    # ------------------------------------------------------------------ #
+
+    @classmethod
+    def from_run_id(
+        cls,
+        run_id: str,
+        *,
+        api_key: str | None = None,
+        config: WherobotsConfig | None = None,
+        base_url: str | None = None,
+        region: str | None = None,
+        request_timeout_seconds: int | None = None,
+    ) -> WherobotsJob:
+        """Attach to an existing run for read-only log/metric access.
+
+        Unlike the regular constructor this does not require a script
+        or name — only a ``run_id``. The returned instance is read-only:
+        :meth:`submit` will raise. All other read methods (``get_logs``,
+        ``iter_logs``, ``poll_for_logs``, ``get_metrics``,
+        ``get_cpu_utilization``, ``get_mem_utilization``, ``get_status``,
+        ``cancel``, ``wait_for_completion``) work normally.
+
+        Args:
+            run_id: Run identifier from a prior submission, the CLI, or
+                the Wherobots UI.
+            api_key: Wherobots API key (or set ``WHEROBOTS_API_KEY``).
+            config: Pre-built ``WherobotsConfig`` to use instead of the
+                environment.
+            base_url: Override the API base URL.
+            region: AWS region override.
+            request_timeout_seconds: HTTP request timeout in seconds.
+
+        Returns:
+            A ``WherobotsJob`` bound to *run_id* with descriptive
+            fields (name, runtime, status, ...) hydrated from the API.
+
+        Raises:
+            WherobotsValidationError: If *run_id* is empty.
+            WherobotsAPIError: If the initial refresh fails.
+        """
+        if not run_id:
+            raise WherobotsValidationError("run_id must not be None or empty")
+
+        self = cls.__new__(cls)
+        self._init_defaults()
+
+        self._config = config or WherobotsConfig.from_env(
+            api_key=api_key,
+            region=region,
+            base_url=base_url,
+            request_timeout_seconds=request_timeout_seconds,
+        )
+        self._api = RunsAPI.from_config(self._config)
+
+        # Attached-mode overrides on top of _init_defaults().
+        self.run_id = run_id
+        self._attached = True
+        self.region = region or self._config.region
+        self.version = self._config.version
+        self.s3_bucket = self._config.s3_bucket
+        self.s3_prefix = self._config.s3_prefix
+
+        self.refresh()
+        return self
+
+    def refresh(self) -> RunView:
+        """Re-fetch the run from the API and update local fields.
+
+        Updates ``status``, ``name``, ``runtime``, ``region``, and
+        ``version`` in place. Works in both attached and submitted modes.
+
+        Returns:
+            The freshly fetched ``RunView``.
+
+        Raises:
+            WherobotsJobError: If ``run_id`` is not set.
+        """
+        if not self.run_id:
+            raise WherobotsJobError("No run_id bound. Call submit() or use from_run_id().")
+        run_view = self._api.get(self.run_id)
+        self.status = run_view.status
+        if run_view.name:
+            self.name = run_view.name
+        if run_view.runtime:
+            self.runtime = run_view.runtime
+        if run_view.region:
+            self.region = run_view.region
+        if run_view.version:
+            self.version = run_view.version
+        return run_view
+
     # ------------------------------------------------------------------ #
     # Lifecycle
     # ------------------------------------------------------------------ #
@@ -293,6 +482,10 @@ class WherobotsJob:
         Returns:
             Run ID
         """
+        if self._attached:
+            raise WherobotsValidationError(
+                "Cannot submit a job attached via from_run_id(); this instance is read-only."
+            )
         if self.run_id:
             logger.warning("Job already submitted with run_id: %s", self.run_id)
             return self.run_id
@@ -355,6 +548,52 @@ class WherobotsJob:
 
         return self._api.get_metrics(self.run_id)
 
+    def get_cpu_utilization(self) -> UtilizationStats:
+        """Get aggregated CPU utilization for the run.
+
+        Returns:
+            ``UtilizationStats`` with ``latest``/``max``/``avg``/``series``.
+            All fields are ``None``/empty when the CPU metric is absent
+            from the server response.
+        """
+        metrics = self.get_metrics()
+        return UtilizationStats.from_metric(
+            metrics.instant_metrics, metrics.series_metrics, self._CPU_METRIC_KEYS
+        )
+
+    def get_mem_utilization(self) -> UtilizationStats:
+        """Get aggregated memory utilization for the run.
+
+        Returns:
+            ``UtilizationStats`` with ``latest``/``max``/``avg``/``series``.
+            All fields are ``None``/empty when the memory metric is
+            absent from the server response.
+        """
+        metrics = self.get_metrics()
+        return UtilizationStats.from_metric(
+            metrics.instant_metrics, metrics.series_metrics, self._MEM_METRIC_KEYS
+        )
+
+    def get_cost(self) -> float | None:
+        """Get the run's total cost in USD.
+
+        Returns:
+            Cost in USD (e.g. ``16.90``), or ``None`` if the server did
+            not surface a cost for this run (typical for runs that are
+            still running or have not yet been billed).
+        """
+        metrics = self.get_metrics()
+        return extract_instant_value(metrics.instant_metrics, self._COST_METRIC_KEYS)
+
+    def get_consumed_spatial_units(self) -> float | None:
+        """Get the spatial units (SUs) consumed by the run.
+
+        Returns:
+            SUs consumed (e.g. ``11.27``), or ``None`` if not reported.
+        """
+        metrics = self.get_metrics()
+        return extract_instant_value(metrics.instant_metrics, self._SU_METRIC_KEYS)
+
     def iter_logs(
         self,
         cursor: int | str = 0,
@@ -429,6 +668,7 @@ class WherobotsJob:
                 )
 
             try:
+                prev_cursor = self._last_log_cursor
                 logs = self.get_logs(cursor=self._last_log_cursor)
 
                 for item in logs.items:
@@ -440,7 +680,12 @@ class WherobotsJob:
                 consecutive_errors = 0  # Reset on success
 
                 if not follow:
-                    break
+                    # Drain remaining pages, then exit. Mirror iter_logs:
+                    # stop when next_page is missing or the cursor doesn't
+                    # advance (server-side loop guard).
+                    if logs.next_page is None or logs.next_page == prev_cursor:
+                        break
+                    continue  # fetch the next page immediately, no sleep
 
                 run_view = self.get_status()
                 if is_terminal_status(run_view.status):
@@ -461,13 +706,13 @@ class WherobotsJob:
                     raise
                 consecutive_errors += 1
                 logger.error("Error polling logs (%d/%d): %s", consecutive_errors, max_errors, exc)
-                if consecutive_errors >= max_errors or not follow:
+                if consecutive_errors >= max_errors:
                     raise
                 time.sleep(interval)
             except Exception as exc:
                 consecutive_errors += 1
                 logger.error("Error polling logs (%d/%d): %s", consecutive_errors, max_errors, exc)
-                if consecutive_errors >= max_errors or not follow:
+                if consecutive_errors >= max_errors:
                     raise
                 time.sleep(interval)
 

wherobots/models.py

@@ -244,8 +244,8 @@ class RunJarPayload:
 class CreateRunPayload:
     """Full payload for ``POST /runs``."""
 
-    runtime: str
     name: str
+    runtime: str | None = None
     version: str = "latest"
     timeout_seconds: int = 3600
     run_python: RunPythonPayload | None = None
@@ -259,11 +259,13 @@ class CreateRunPayload:
             Dict suitable for ``POST /runs`` request body.
         """
         d: dict[str, Any] = {
-            "runtime": self.runtime,
             "name": self.name,
             "version": self.version,
             "timeoutSeconds": self.timeout_seconds,
         }
+        # Omit runtime when unset so the API applies the org default.
+        if self.runtime is not None:
+            d["runtime"] = self.runtime
         if self.run_python is not None:
             d["runPython"] = self.run_python.to_dict()
         if self.run_jar is not None:
@@ -296,7 +298,7 @@ class CreateRunPayload:
         if "environment" in data and data["environment"] is not None:
             environment = RunEnvironment.from_dict(data["environment"])
         return cls(
-            runtime=data.get("runtime", ""),
+            runtime=data.get("runtime"),
             name=data.get("name", ""),
             version=data.get("version", "latest"),
             timeout_seconds=data.get("timeoutSeconds", 3600),
@@ -942,6 +944,146 @@ class RunMetricsResponse:
         return d
 
 
+@dataclass
+class UtilizationStats:
+    """Aggregated utilization for a single metric (e.g. CPU or memory).
+
+    ``series`` is the raw time-series of ``(timestamp, value)`` points
+    as returned by the server, normalized to floats. ``latest`` /
+    ``max`` / ``avg`` are derived from that series for convenience.
+    All fields are ``None`` / empty when the metric was not present in
+    the response.
+    """
+
+    latest: float | None = None
+    max: float | None = None
+    avg: float | None = None
+    series: list[tuple[float, float]] = field(default_factory=list)
+
+    @classmethod
+    def from_metric(
+        cls,
+        instant: dict[str, Any],
+        series: dict[str, Any],
+        keys: tuple[str, ...],
+    ) -> UtilizationStats:
+        """Build stats from the server's untyped metric dicts.
+
+        Args:
+            instant: ``RunMetricsResponse.instant_metrics``.
+            series: ``RunMetricsResponse.series_metrics``.
+            keys: Candidate metric names to look up, in priority order.
+                The first key found in *series* (or *instant* as a
+                fallback) is used. Multiple candidates are supported
+                because metric names are server-defined and untyped.
+
+        Returns:
+            A populated ``UtilizationStats``, or an empty instance if
+            none of the candidate keys are present.
+
+        Note:
+            Tie-break is "first key with ≥1 parseable point wins" — once
+            we begin parsing a given key we do not fall through to
+            subsequent candidates, even if some points within that key
+            are malformed. In practice the primary (UPPERCASE) production
+            key matches and the lowercase aliases only get tried when the
+            primary key is entirely absent from the response.
+        """
+        points = cls._extract_series(series, keys)
+        if points:
+            values = [v for _, v in points]
+            return cls(
+                latest=values[-1],
+                max=max(values),
+                avg=sum(values) / len(values),
+                series=points,
+            )
+
+        instant_value = extract_instant_value(instant, keys)
+        if instant_value is not None:
+            return cls(latest=instant_value, max=instant_value, avg=instant_value)
+
+        return cls()
+
+    @staticmethod
+    def _extract_series(
+        series: dict[str, Any],
+        keys: tuple[str, ...],
+    ) -> list[tuple[float, float]]:
+        for key in keys:
+            raw = series.get(key)
+            if raw is None:
+                continue
+            data = _unwrap_metric_envelope(raw)
+            points: list[tuple[float, float]] = []
+            for item in data if isinstance(data, list) else []:
+                point = UtilizationStats._coerce_point(item)
+                if point is not None:
+                    points.append(point)
+            if points:
+                return points
+        return []
+
+    @staticmethod
+    def _coerce_point(item: Any) -> tuple[float, float] | None:
+        """Coerce a single series entry to ``(timestamp, value)``.
+
+        Accepts ``[ts, value]`` / ``(ts, value)`` tuples and dicts
+        with ``timestamp``/``value`` (or ``t``/``v``) keys. Returns
+        ``None`` for shapes that can't be coerced — silently skipped.
+        """
+        if isinstance(item, (list, tuple)) and len(item) == 2:
+            ts, value = item
+        elif isinstance(item, dict):
+            ts = item.get("timestamp", item.get("t"))
+            value = item.get("value", item.get("v"))
+        else:
+            return None
+        try:
+            return float(ts), float(value)
+        except (TypeError, ValueError):
+            return None
+
+
+def _unwrap_metric_envelope(value: Any) -> Any:
+    """Strip the server's ``{display_name, metric: {data, format}}`` wrapper.
+
+    The Wherobots metrics endpoint wraps each metric as
+    ``{"display_name": ..., "metric": {"data": ..., "format": ...}}``.
+    Returns ``data`` if present, otherwise the value untouched (so
+    callers tolerate raw lists/scalars too).
+    """
+    if isinstance(value, dict) and "metric" in value:
+        metric = value.get("metric")
+        if isinstance(metric, dict) and "data" in metric:
+            return metric["data"]
+    return value
+
+
+def extract_instant_value(
+    instant: dict[str, Any],
+    keys: tuple[str, ...],
+) -> float | None:
+    """Pull a scalar from ``instant_metrics`` by candidate key name.
+
+    Handles both the server's wrapped shape
+    (``{metric: {data: {value, timestamp}}}``) and a bare numeric
+    value. Returns ``None`` if no key matched or coercion failed.
+    """
+    for key in keys:
+        raw = instant.get(key)
+        if raw is None:
+            continue
+        data = _unwrap_metric_envelope(raw)
+        if isinstance(data, dict) and "value" in data:
+            data = data["value"]
+        try:
+            return float(data)
+        except (TypeError, ValueError):
+            continue
+    return None
+
+
 # ---------------------------------------------------------------------------
 # Pagination
 # ---------------------------------------------------------------------------

{wherobots_python_sdk-0.1.0.dist-info → wherobots_python_sdk-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.1.0
+Version: 0.2.1
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -130,7 +130,7 @@ The API key can also be set via the `WHEROBOTS_API_KEY` environment variable.
 | Variable                           | Description                     | Default                              |
 |------------------------------------|---------------------------------|--------------------------------------|
 | `WHEROBOTS_API_KEY`                | API key                         | *(required)*                         |
-| `WHEROBOTS_REGION`                 | Default AWS region              | `aws-us-west-2`                      |
+| `WHEROBOTS_REGION`                 | Region override (else org default) | *(none — org default)*            |
 | `WHEROBOTS_API_BASE_URL`          | API base URL                    | `https://api.cloud.wherobots.com`    |
 | `WHEROBOTS_VERSION`               | Wherobots version               | `latest`                             |
 | `WHEROBOTS_REQUEST_TIMEOUT_SECONDS`| HTTP request timeout (seconds) | `30`                                 |
@@ -176,8 +176,8 @@ The primary class for managing job runs.
 WherobotsJob(
     script: str,                             # Path or S3 URI to .py or .jar
     name: str,                               # Job name (8-255 chars, [a-zA-Z0-9_\-.]+)
-    runtime: str | Runtime = "tiny",         # Compute size
-    region: str | Region | None = None,      # AWS region
+    runtime: str | Runtime | None = None,    # Compute size (None -> org default)
+    region: str | Region | None = None,      # Region; str passed as-is (None -> org default)
     api_key: str | None = None,              # API key (or env var)
     version: str | None = None,              # "latest" | "preview"
     timeout_seconds: int = 3600,             # Job timeout
@@ -202,6 +202,11 @@ WherobotsJob(
 | `get_status()` | `RunView` | Get current job status and full details. |
 | `get_logs(cursor=0, size=100)` | `LogsResponse` | Fetch a page of log entries. |
 | `get_metrics()` | `RunMetricsResponse` | Fetch CPU/memory metrics for the run. |
+| `get_cpu_utilization()` | `UtilizationStats` | Aggregated CPU utilization (`latest`, `max`, `avg`, `series`). |
+| `get_mem_utilization()` | `UtilizationStats` | Aggregated memory utilization (`latest`, `max`, `avg`, `series`). |
+| `get_cost()` | `float \| None` | Total run cost in USD, or `None` if not yet billed. |
+| `get_consumed_spatial_units()` | `float \| None` | Spatial Units (SUs) consumed by the run. |
+| `refresh()` | `RunView` | Re-fetch from the API and update `status`/`name`/`runtime`/`region`/`version` in place. |
 | `iter_logs(cursor=0, size=100)` | `Iterator[dict]` | Iterate over all log entries, handling pagination automatically. |
 | `poll_for_logs(follow=True, interval=2.0, log_handler=None, max_errors=10)` | `None` | Poll and print logs. If `follow=True`, continues until job completes. `max_errors` sets the max consecutive transient errors before giving up. |
 | `cancel()` | `bool` | Request cancellation. Returns `True` on success. |
@@ -227,10 +232,40 @@ with WherobotsJob(script="s3://bucket/script.py", name="my-job") as job:
 
 | Method | Returns | Description |
 |--------|---------|-------------|
+| `from_run_id(run_id, api_key=None, ...)` | `WherobotsJob` | Attach to an existing run for read-only log/metric access. No script required. `submit()` is disabled on the returned instance. |
 | `list_runs(...)` | `RunListPage` | List runs with optional filters. No instance required. |
 | `add_pypi_dependency(name, version)` | `dict` | Create a PyPI dependency dict for the `dependencies` parameter. |
 | `add_file_dependency(file_path)` | `dict` | Create a file dependency dict (`.jar`, `.whl`, `.zip`, `.json`). |
 
+#### Attaching to an Existing Run
+
+If you already have a `run_id` (from the CLI, the Wherobots UI, or a prior SDK
+session) you can attach without a script:
+
+```python
+from wherobots import WherobotsJob
+
+job = WherobotsJob.from_run_id("run-abc-123")
+print(job.status, job.name)
+
+# Stream remaining logs
+job.poll_for_logs(follow=False)
+
+# Or paginate
+for entry in job.iter_logs(size=200):
+    print(entry["raw"])
+
+# Aggregated utilization for a completed run
+cpu = job.get_cpu_utilization()
+print(f"CPU peak {cpu.max}, avg {cpu.avg}, samples {len(cpu.series)}")
+
+# Billing
+print(f"cost ${job.get_cost():.2f}, SUs {job.get_consumed_spatial_units()}")
+```
+
+Calling `job.submit()` on an attached instance raises
+`WherobotsValidationError` — these instances are read-only.
+
 #### Listing Runs
 
 ```python

{wherobots_python_sdk-0.1.0.dist-info → wherobots_python_sdk-0.2.1.dist-info}/RECORD

@@ -1,20 +1,20 @@
-wherobots/__init__.py,sha256=UGvPiw86dJwrZiA-7u-Nx4thyZj7QmdOio343-vscHg,1754
-wherobots/__version__.py,sha256=gdQx5awJ980s8gFK_3u0b4RogasTty0-FJ6cROVHjZo,111
-wherobots/client.py,sha256=go2-usZMWm74zUXupiy5k-M3Faprn_WJaH1wK0Sr0po,23467
+wherobots/__init__.py,sha256=vUSHeAhv2Vk26evXDuOdTjlJAG6sTM0DV1DVvI1XsPc,1800
+wherobots/__version__.py,sha256=kDkfSolu4vWo-Y2a1tCbG94akdaRELoEhg9L_Ko-mwQ,111
+wherobots/client.py,sha256=NJFw8Okb7i416iuVh-buqDk6XKm1eP4scTD5bNdoQaE,33406
 wherobots/config.py,sha256=Ib20Y5mGsE4aP_g99ZKEyZvV8q-aOXq7RVpYP8i0lpo,6679
 wherobots/enums.py,sha256=YsxXN3ZcY99aoEsUtjYs4otHDevsSPizAgCp-vShds8,4154
 wherobots/exceptions.py,sha256=ERoTU7Edf-dFCE4-ScyuEcC-2O2d5JRa8issQWc-PNA,1296
-wherobots/models.py,sha256=RKmxMpHTLzhOdb3FcvxWLgrxjpSCBpuc9l-BacbqLl4,35673
+wherobots/models.py,sha256=gs8X3husFp5k_EBxYp-_7WFTMI99tuwL_bw53Ffg5bM,40786
 wherobots/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wherobots/api/__init__.py,sha256=jUb587jazP_FA-sH_6yCYfvGxsNiUOyIYAPb3CHOYtQ,218
 wherobots/api/base.py,sha256=IiT3k17G19bT0rM2zYZs9Tpob8pgTrSLAWdKlLUVM1o,8769
 wherobots/api/files.py,sha256=c2yGQ-yQKzvp1O-47JrFp1H6Uj7FDCBRiyJ0ym8g-TE,14040
-wherobots/api/runs.py,sha256=25Hz0evE0gfu7YCQma77AcxAbrk89iKgzdoE0XFJr7U,8442
+wherobots/api/runs.py,sha256=ef5ouPGUsuaIIpBW3sHjkOXxfxTuOA6ieFjkMIuNAyc,8542
 wherobots/utils/__init__.py,sha256=cTM2QNJDauQWyGBTJPE5yH4ULc4Ucg_4KFzemjM3HaA,193
 wherobots/utils/logger.py,sha256=eclhD9Vf2LsSm4engRzT3jE2v0wdHJH01OfeI3ml4HM,1103
 wherobots/utils/validation.py,sha256=R0iG4OqzER4prdP8-TOQV_pQFJ3emEQyWYYuc3aCefU,890
-wherobots_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=U1EH466XmvxbqaWOY0cax49w0R87_6w6yJLyV14v4bc,10767
-wherobots_python_sdk-0.1.0.dist-info/METADATA,sha256=EH_LfjKliEImWBAi3a2t2a5HvbvokyzpIsqV0p-jqWI,21512
-wherobots_python_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-wherobots_python_sdk-0.1.0.dist-info/top_level.txt,sha256=oL-n-9GIG0rmUeukuytUqdN6yfROIsVh8bNrgZsOdxw,10
-wherobots_python_sdk-0.1.0.dist-info/RECORD,,
+wherobots_python_sdk-0.2.1.dist-info/licenses/LICENSE,sha256=U1EH466XmvxbqaWOY0cax49w0R87_6w6yJLyV14v4bc,10767
+wherobots_python_sdk-0.2.1.dist-info/METADATA,sha256=YHfG_yTnllcs-I6gfo-LVd8-QmIm2JtkcwOrRGiVS54,23068
+wherobots_python_sdk-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+wherobots_python_sdk-0.2.1.dist-info/top_level.txt,sha256=oL-n-9GIG0rmUeukuytUqdN6yfROIsVh8bNrgZsOdxw,10
+wherobots_python_sdk-0.2.1.dist-info/RECORD,,