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

wherobots/models.py

@@ -0,0 +1,1080 @@
+"""Typed data models for the Wherobots Jobs API.
+
+All models use dataclasses with ``from_dict`` / ``to_dict`` helpers
+for JSON round-tripping without requiring pydantic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from wherobots.enums import (
+    AppStatus,
+    AppType,
+    DependencyFileType,
+    DependencyType,
+    JobStatus,
+)
+
+# ---------------------------------------------------------------------------
+# Dependency models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PyPiDependency:
+    """A PyPI package dependency."""
+
+    library_name: str
+    library_version: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with ``sourceType``, ``libraryName``, and
+            ``libraryVersion``.
+        """
+        return {
+            "sourceType": DependencyType.PYPI.value,
+            "libraryName": self.library_name,
+            "libraryVersion": self.library_version,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PyPiDependency:
+        """Deserialize from API JSON.
+
+        Permissive: missing fields default to empty strings. The API's
+        own validation surfaces real errors via ``WherobotsAPIError``.
+
+        Args:
+            data: Dictionary containing ``libraryName`` and
+                ``libraryVersion``.
+
+        Returns:
+            A new ``PyPiDependency`` instance.
+        """
+        return cls(
+            library_name=data.get("libraryName") or "",
+            library_version=data.get("libraryVersion") or "",
+        )
+
+
+@dataclass
+class FileDependency:
+    """A file-based dependency (JAR, wheel, zip, etc.)."""
+
+    file_path: str
+    file_type: DependencyFileType | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with ``sourceType``, ``filePath``, and optionally
+            ``fileType``.
+        """
+        d: dict[str, Any] = {
+            "sourceType": DependencyType.FILE.value,
+            "filePath": self.file_path,
+        }
+        if self.file_type is not None:
+            d["fileType"] = self.file_type.value
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FileDependency:
+        """Deserialize from API JSON.
+
+        Permissive: missing ``filePath`` defaults to empty string;
+        unknown ``fileType`` values survive as ``None``.
+
+        Args:
+            data: Dictionary containing ``filePath`` and optionally
+                ``fileType``.
+
+        Returns:
+            A new ``FileDependency`` instance.
+        """
+        file_type = None
+        if data.get("fileType") is not None:
+            try:
+                file_type = DependencyFileType(data["fileType"])
+            except ValueError:
+                file_type = None
+        return cls(
+            file_path=data.get("filePath") or "",
+            file_type=file_type,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Run environment / payload models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RunEnvironment:
+    """Environment configuration for a job run."""
+
+    spark_configs: dict[str, str] | None = None
+    dependencies: list[dict[str, Any]] | None = None
+    spark_driver_disk_gb: int | None = None
+    spark_executor_disk_gb: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with Spark configs, dependencies, and disk settings.
+            Only non-``None`` fields are included.
+        """
+        d: dict[str, Any] = {}
+        if self.spark_configs:
+            d["sparkConfigs"] = self.spark_configs
+        if self.dependencies:
+            d["dependencies"] = self.dependencies
+        if self.spark_driver_disk_gb is not None:
+            d["sparkDriverDiskGB"] = self.spark_driver_disk_gb
+        if self.spark_executor_disk_gb is not None:
+            d["sparkExecutorDiskGB"] = self.spark_executor_disk_gb
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunEnvironment:
+        """Deserialize from API JSON.
+
+        Args:
+            data: Dictionary with optional ``sparkConfigs``,
+                ``dependencies``, ``sparkDriverDiskGB``, and
+                ``sparkExecutorDiskGB``.
+
+        Returns:
+            A new ``RunEnvironment`` instance.
+        """
+        return cls(
+            spark_configs=data.get("sparkConfigs"),
+            dependencies=data.get("dependencies"),
+            spark_driver_disk_gb=data.get("sparkDriverDiskGB"),
+            spark_executor_disk_gb=data.get("sparkExecutorDiskGB"),
+        )
+
+
+@dataclass
+class RunPythonPayload:
+    """Python script execution payload."""
+
+    uri: str
+    args: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with ``uri`` and ``args``.
+        """
+        return {"uri": self.uri, "args": self.args}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunPythonPayload:
+        """Deserialize from API JSON.
+
+        Permissive: missing ``uri`` defaults to empty string.
+
+        Args:
+            data: Dictionary containing ``uri`` and optionally ``args``.
+
+        Returns:
+            A new ``RunPythonPayload`` instance.
+        """
+        return cls(uri=data.get("uri") or "", args=data.get("args") or [])
+
+
+@dataclass
+class RunJarPayload:
+    """JAR execution payload.
+
+    Note: per the API spec, ``mainClass`` is optional on responses
+    (the server may infer it). Kept as a string here with ``""`` as
+    the "unset" sentinel so existing callers who read the field
+    unconditionally continue to work.
+    """
+
+    uri: str
+    main_class: str = ""
+    args: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with ``uri``, ``mainClass``, and ``args``. ``mainClass``
+            is omitted when empty so requests don't override server-side
+            inference.
+        """
+        d: dict[str, Any] = {"uri": self.uri, "args": self.args}
+        if self.main_class:
+            d["mainClass"] = self.main_class
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunJarPayload:
+        """Deserialize from API JSON.
+
+        Permissive: all fields default; the API owns field-level
+        validation.
+
+        Args:
+            data: Dictionary containing ``uri``, ``mainClass``, and
+                optionally ``args``.
+
+        Returns:
+            A new ``RunJarPayload`` instance.
+        """
+        return cls(
+            uri=data.get("uri") or "",
+            main_class=data.get("mainClass") or "",
+            args=data.get("args") or [],
+        )
+
+
+@dataclass
+class CreateRunPayload:
+    """Full payload for ``POST /runs``."""
+
+    runtime: str
+    name: str
+    version: str = "latest"
+    timeout_seconds: int = 3600
+    run_python: RunPythonPayload | None = None
+    run_jar: RunJarPayload | None = None
+    environment: RunEnvironment | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict suitable for ``POST /runs`` request body.
+        """
+        d: dict[str, Any] = {
+            "runtime": self.runtime,
+            "name": self.name,
+            "version": self.version,
+            "timeoutSeconds": self.timeout_seconds,
+        }
+        if self.run_python is not None:
+            d["runPython"] = self.run_python.to_dict()
+        if self.run_jar is not None:
+            d["runJar"] = self.run_jar.to_dict()
+        if self.environment is not None:
+            env_dict = self.environment.to_dict()
+            if env_dict:
+                d["environment"] = env_dict
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CreateRunPayload:
+        """Deserialize from API JSON.
+
+        Args:
+            data: Dictionary containing ``runtime``, ``name``, and
+                optional nested ``runPython``, ``runJar``, and
+                ``environment`` objects.
+
+        Returns:
+            A new ``CreateRunPayload`` instance.
+        """
+        run_python = None
+        if "runPython" in data and data["runPython"] is not None:
+            run_python = RunPythonPayload.from_dict(data["runPython"])
+        run_jar = None
+        if "runJar" in data and data["runJar"] is not None:
+            run_jar = RunJarPayload.from_dict(data["runJar"])
+        environment = None
+        if "environment" in data and data["environment"] is not None:
+            environment = RunEnvironment.from_dict(data["environment"])
+        return cls(
+            runtime=data.get("runtime", ""),
+            name=data.get("name", ""),
+            version=data.get("version", "latest"),
+            timeout_seconds=data.get("timeoutSeconds", 3600),
+            run_python=run_python,
+            run_jar=run_jar,
+            environment=environment,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Run view / response models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RunAppMeta:
+    """Application metadata attached to a run (OpenAPI ``RunAppMeta``)."""
+
+    spark_ui_url: str | None = None
+    spark_eventlogs_url: str | None = None
+    resolved_version: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunAppMeta:
+        """Deserialize from API JSON.
+
+        Args:
+            data: Dictionary with optional ``spark_ui_url``,
+                ``spark_eventlogs_url``, and ``resolved_version``.
+
+        Returns:
+            A new ``RunAppMeta`` instance.
+        """
+        return cls(
+            spark_ui_url=data.get("spark_ui_url"),
+            spark_eventlogs_url=data.get("spark_eventlogs_url"),
+            resolved_version=data.get("resolved_version"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Uses the API's own snake_case keys.
+        """
+        d: dict[str, Any] = {}
+        if self.spark_ui_url is not None:
+            d["spark_ui_url"] = self.spark_ui_url
+        if self.spark_eventlogs_url is not None:
+            d["spark_eventlogs_url"] = self.spark_eventlogs_url
+        if self.resolved_version is not None:
+            d["resolved_version"] = self.resolved_version
+        return d
+
+
+@dataclass
+class RunEventMeta:
+    """Timestamp window attached to a ``KubeAppEvent`` (OpenAPI ``RunEventMeta``)."""
+
+    start_timestamp: int | None = None
+    end_timestamp: int | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunEventMeta:
+        return cls(
+            start_timestamp=data.get("start_timestamp"),
+            end_timestamp=data.get("end_timestamp"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {}
+        if self.start_timestamp is not None:
+            d["start_timestamp"] = self.start_timestamp
+        if self.end_timestamp is not None:
+            d["end_timestamp"] = self.end_timestamp
+        return d
+
+
+@dataclass
+class KubeAppEvent:
+    """Kubernetes application event (OpenAPI ``KubeAppEvent``)."""
+
+    id: str = ""
+    create_time: str = ""
+    update_time: str = ""
+    code: str | None = None
+    message: str | None = None
+    event_meta: RunEventMeta | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> KubeAppEvent:
+        event_meta = None
+        if data.get("eventMeta") is not None:
+            event_meta = RunEventMeta.from_dict(data["eventMeta"])
+        return cls(
+            id=data.get("id") or "",
+            create_time=data.get("createTime") or "",
+            update_time=data.get("updateTime") or "",
+            code=data.get("code"),
+            message=data.get("message"),
+            event_meta=event_meta,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "createTime": self.create_time,
+            "updateTime": self.update_time,
+        }
+        if self.code is not None:
+            d["code"] = self.code
+        if self.message is not None:
+            d["message"] = self.message
+        if self.event_meta is not None:
+            d["eventMeta"] = self.event_meta.to_dict()
+        return d
+
+
+@dataclass
+class RunKubeApp:
+    """Kubernetes application details for a run (OpenAPI ``RunKubeApp``).
+
+    Forward-compat: ``app_type`` and ``status`` round-trip unknown
+    server values as raw strings rather than silently dropping them.
+    """
+
+    id: str = ""
+    create_time: str = ""
+    update_time: str = ""
+    instance_id: str = ""
+    app_type: AppType | str | None = None
+    status: AppStatus | str | None = None
+    created_by_id: str | None = None
+    api_payload: dict[str, Any] | None = None
+    app_meta: RunAppMeta | None = None
+    events: list[KubeAppEvent] = field(default_factory=list)
+    cpu_usage: int = 0
+    region_name: str = ""
+    message: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunKubeApp:
+        app_type: AppType | str | None = None
+        raw_app_type = data.get("appType")
+        if raw_app_type:
+            try:
+                app_type = AppType(raw_app_type)
+            except ValueError:
+                app_type = raw_app_type
+
+        status: AppStatus | str | None = None
+        raw_status = data.get("status")
+        if raw_status:
+            try:
+                status = AppStatus(raw_status)
+            except ValueError:
+                status = raw_status
+
+        app_meta = None
+        if data.get("appMeta") is not None:
+            app_meta = RunAppMeta.from_dict(data["appMeta"])
+
+        events = [KubeAppEvent.from_dict(e) for e in (data.get("events") or [])]
+
+        return cls(
+            id=data.get("id") or "",
+            create_time=data.get("createTime") or "",
+            update_time=data.get("updateTime") or "",
+            instance_id=data.get("instanceId") or "",
+            app_type=app_type,
+            status=status,
+            created_by_id=data.get("createdById"),
+            api_payload=data.get("apiPayload"),
+            app_meta=app_meta,
+            events=events,
+            cpu_usage=data.get("cpuUsage") or 0,
+            region_name=data.get("regionName") or "",
+            message=data.get("message"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "createTime": self.create_time,
+            "updateTime": self.update_time,
+            "instanceId": self.instance_id,
+            "cpuUsage": self.cpu_usage,
+            "regionName": self.region_name,
+        }
+        if isinstance(self.app_type, AppType):
+            d["appType"] = self.app_type.value
+        elif isinstance(self.app_type, str):
+            d["appType"] = self.app_type
+        if isinstance(self.status, AppStatus):
+            d["status"] = self.status.value
+        elif isinstance(self.status, str):
+            d["status"] = self.status
+        if self.created_by_id is not None:
+            d["createdById"] = self.created_by_id
+        if self.api_payload is not None:
+            d["apiPayload"] = self.api_payload
+        if self.app_meta is not None:
+            d["appMeta"] = self.app_meta.to_dict()
+        if self.events:
+            d["events"] = [e.to_dict() for e in self.events]
+        if self.message is not None:
+            d["message"] = self.message
+        return d
+
+
+@dataclass
+class OrganizationCustomer:
+    """A user/customer in the organization (OpenAPI ``OrganizationCustomer``).
+
+    Returned on ``RunView.triggeredBy`` to identify the user who
+    submitted a run.
+    """
+
+    id: str = ""
+    create_time: str = ""
+    update_time: str = ""
+    email: str | None = None
+    name: str | None = None
+    roles: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> OrganizationCustomer:
+        return cls(
+            id=data.get("id") or "",
+            create_time=data.get("createTime") or "",
+            update_time=data.get("updateTime") or "",
+            email=data.get("email"),
+            name=data.get("name"),
+            roles=list(data.get("roles") or []),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "createTime": self.create_time,
+            "updateTime": self.update_time,
+            "roles": list(self.roles),
+        }
+        if self.email is not None:
+            d["email"] = self.email
+        if self.name is not None:
+            d["name"] = self.name
+        return d
+
+
+@dataclass
+class RunView:
+    """Complete view of a job run (``GET /runs/{id}`` response).
+
+    The Wherobots API nests payload fields (``runtime``, ``runPython``,
+    ``runJar``, ``timeoutSeconds``, ``environment``) under a ``"payload"``
+    key.  ``from_dict`` transparently flattens these so callers can access
+    e.g. ``view.runtime`` directly.
+
+    Timestamp fields from the API use ``createTime`` / ``startTime`` /
+    ``completeTime``; for convenience the parser also accepts the legacy
+    ``createdAt`` / ``startedAt`` / ``completedAt`` aliases.
+
+    Forward-compat:
+
+    * ``status`` is typed as ``JobStatus | str | None`` so a status value
+      the SDK doesn't know about yet (e.g. a new terminal state added
+      server-side) round-trips as the raw string instead of silently
+      disappearing. Use :func:`is_terminal_status` to check terminality
+      without assuming the enum.
+    * ``raw`` holds the full server response dict, so newly added fields
+      are always reachable even when the typed surface hasn't caught up.
+    """
+
+    id: str
+    name: str
+    status: JobStatus | str | None = None
+    runtime: str | None = None
+    region: str | None = None
+    version: str | None = None
+    timeout_seconds: int | None = None
+    create_time: str | None = None
+    update_time: str | None = None
+    start_time: str | None = None
+    complete_time: str | None = None
+    run_python: RunPythonPayload | None = None
+    run_jar: RunJarPayload | None = None
+    environment: RunEnvironment | None = None
+    app_meta: RunAppMeta | None = None
+    kube_app: RunKubeApp | None = None
+    triggered_by: OrganizationCustomer | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    # Legacy aliases ---------------------------------------------------
+    @property
+    def created_at(self) -> str | None:
+        """Alias kept for backward compatibility."""
+        return self.create_time
+
+    @property
+    def started_at(self) -> str | None:
+        """Alias kept for backward compatibility."""
+        return self.start_time
+
+    @property
+    def completed_at(self) -> str | None:
+        """Alias kept for backward compatibility."""
+        return self.complete_time
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunView:
+        """Deserialize from API JSON, flattening the nested ``payload``.
+
+        Args:
+            data: Full API response dictionary for a single run.
+
+        Returns:
+            A new ``RunView`` instance with payload fields promoted to
+            top-level attributes.
+        """
+        # The API nests payload fields under "payload"; flatten them.
+        payload: dict[str, Any] = data.get("payload") or {}
+
+        status: JobStatus | str | None = None
+        raw_status = data.get("status")
+        if raw_status:
+            try:
+                status = JobStatus(raw_status)
+            except ValueError:
+                # Preserve unknown status strings verbatim so callers
+                # can still see the value and react (e.g. log it).
+                status = raw_status
+
+        # Helper: look in payload first, then top-level (for flexibility).
+        def _get(key: str, default: Any = None) -> Any:
+            if key in payload:
+                return payload[key]
+            return data.get(key, default)
+
+        run_python = None
+        rp = _get("runPython")
+        if rp is not None:
+            run_python = RunPythonPayload.from_dict(rp)
+
+        run_jar = None
+        rj = _get("runJar")
+        if rj is not None:
+            run_jar = RunJarPayload.from_dict(rj)
+
+        environment = None
+        env = _get("environment")
+        if env is not None:
+            environment = RunEnvironment.from_dict(env)
+
+        app_meta = None
+        # appMeta may live inside kubeApp or at top level
+        am = data.get("appMeta")
+        if am is not None:
+            app_meta = RunAppMeta.from_dict(am)
+
+        kube_app = None
+        ka = data.get("kubeApp")
+        if ka is not None:
+            kube_app = RunKubeApp.from_dict(ka)
+            # appMeta can also be nested in kubeApp
+            if app_meta is None and ka.get("appMeta") is not None:
+                app_meta = RunAppMeta.from_dict(ka["appMeta"])
+
+        triggered_by = None
+        if data.get("triggeredBy") is not None:
+            triggered_by = OrganizationCustomer.from_dict(data["triggeredBy"])
+
+        known_keys = {
+            "id",
+            "name",
+            "status",
+            "runtime",
+            "region",
+            "version",
+            "timeoutSeconds",
+            "payload",
+            # API timestamp keys
+            "createTime",
+            "updateTime",
+            "startTime",
+            "completeTime",
+            # Legacy timestamp keys
+            "createdAt",
+            "startedAt",
+            "completedAt",
+            "runPython",
+            "runJar",
+            "environment",
+            "appMeta",
+            "kubeApp",
+            "triggeredBy",
+        }
+        extra = {k: v for k, v in data.items() if k not in known_keys}
+
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name") or payload.get("name", ""),
+            status=status,
+            runtime=_get("runtime"),
+            region=data.get("region"),
+            version=_get("version"),
+            timeout_seconds=_get("timeoutSeconds"),
+            create_time=data.get("createTime", data.get("createdAt")),
+            update_time=data.get("updateTime"),
+            start_time=data.get("startTime", data.get("startedAt")),
+            complete_time=data.get("completeTime", data.get("completedAt")),
+            run_python=run_python,
+            run_jar=run_jar,
+            environment=environment,
+            app_meta=app_meta,
+            kube_app=kube_app,
+            triggered_by=triggered_by,
+            extra=extra,
+            raw=dict(data),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with all run fields. Only non-``None`` fields are
+            included. Extra (unknown) fields are merged at the top
+            level.
+        """
+        d: dict[str, Any] = {"id": self.id, "name": self.name}
+        if isinstance(self.status, JobStatus):
+            d["status"] = self.status.value
+        elif isinstance(self.status, str):
+            d["status"] = self.status
+        if self.runtime is not None:
+            d["runtime"] = self.runtime
+        if self.region is not None:
+            d["region"] = self.region
+        if self.version is not None:
+            d["version"] = self.version
+        if self.timeout_seconds is not None:
+            d["timeoutSeconds"] = self.timeout_seconds
+        if self.create_time is not None:
+            d["createTime"] = self.create_time
+        if self.update_time is not None:
+            d["updateTime"] = self.update_time
+        if self.start_time is not None:
+            d["startTime"] = self.start_time
+        if self.complete_time is not None:
+            d["completeTime"] = self.complete_time
+        if self.run_python is not None:
+            d["runPython"] = self.run_python.to_dict()
+        if self.run_jar is not None:
+            d["runJar"] = self.run_jar.to_dict()
+        if self.environment is not None:
+            d["environment"] = self.environment.to_dict()
+        if self.app_meta is not None:
+            d["appMeta"] = self.app_meta.to_dict()
+        if self.kube_app is not None:
+            d["kubeApp"] = self.kube_app.to_dict()
+        if self.triggered_by is not None:
+            d["triggeredBy"] = self.triggered_by.to_dict()
+        if self.extra:
+            d.update(self.extra)
+        return d
+
+
+# ---------------------------------------------------------------------------
+# Logs models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class LogItem:
+    """A single log entry.
+
+    The ``timestamp`` field is typed as ``Union[int, str, None]`` because
+    the Wherobots API returns integer epoch values (e.g. ``0``) while
+    other sources may use ISO-8601 strings.
+    """
+
+    raw: str = ""
+    timestamp: int | str | None = None
+    level: str | None = None
+    message: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> LogItem:
+        """Deserialize from API JSON.
+
+        Args:
+            data: Dictionary with ``raw`` and optional ``timestamp``,
+                ``level``, ``message`` fields. Unknown keys are
+                captured in ``extra``.
+
+        Returns:
+            A new ``LogItem`` instance.
+        """
+        known_keys = {"raw", "timestamp", "level", "message"}
+        extra = {k: v for k, v in data.items() if k not in known_keys}
+        return cls(
+            raw=data.get("raw", ""),
+            timestamp=data.get("timestamp"),
+            level=data.get("level"),
+            message=data.get("message"),
+            extra=extra,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with log entry fields. Only non-``None`` fields are
+            included. Extra fields are merged at the top level.
+        """
+        d: dict[str, Any] = {"raw": self.raw}
+        if self.timestamp is not None:
+            d["timestamp"] = self.timestamp
+        if self.level is not None:
+            d["level"] = self.level
+        if self.message is not None:
+            d["message"] = self.message
+        if self.extra:
+            d.update(self.extra)
+        return d
+
+
+@dataclass
+class LogsResponse:
+    """Response from ``GET /runs/{id}/logs``.
+
+    The API returns ``current_page`` (int) and ``next_page`` (int) for
+    cursor-based pagination. ``raw`` holds the original server response
+    so callers can reach new fields without a SDK release.
+    """
+
+    items: list[LogItem] = field(default_factory=list)
+    next_page: int | str | None = None
+    current_page: int | str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> LogsResponse:
+        """Deserialize from API JSON.
+
+        Args:
+            data: Dictionary with ``items`` list and optional
+                ``next_page`` / ``current_page`` cursors. Accepts
+                both snake_case and camelCase key variants.
+
+        Returns:
+            A new ``LogsResponse`` instance.
+        """
+        raw_items = data.get("items")
+        items = [LogItem.from_dict(i) for i in (raw_items or [])]
+        next_page = data.get("next_page", data.get("nextPage"))
+        current_page = data.get("current_page", data.get("currentPage"))
+        return cls(
+            items=items,
+            next_page=next_page,
+            current_page=current_page,
+            raw=dict(data),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with serialized ``items`` and pagination cursors.
+        """
+        d: dict[str, Any] = {"items": [i.to_dict() for i in self.items]}
+        if self.next_page is not None:
+            d["next_page"] = self.next_page
+        if self.current_page is not None:
+            d["current_page"] = self.current_page
+        return d
+
+
+# ---------------------------------------------------------------------------
+# Metrics models
+# ---------------------------------------------------------------------------
+#
+# The OpenAPI spec types the metrics blobs as plain ``object`` with
+# no fixed per-metric shape, so the SDK intentionally does not expose
+# typed ``SeriesMetric`` / ``InstantMetric`` / ``MetricDetail`` /
+# ``DataValue`` dataclasses. Use ``RunMetricsResponse.series_metrics`` /
+# ``instant_metrics`` (keyed by metric name) for ergonomic lookup and
+# ``RunMetricsResponse.raw`` to see exactly what the server returned.
+
+
+@dataclass
+class RunMetricsResponse:
+    """Response from ``GET /runs/{id}/metrics``.
+
+    Per the OpenAPI spec the metrics blobs use snake_case keys
+    (``series_metrics`` / ``instant_metrics``) and are typed as plain
+    ``object`` (the server's internal metric shape is not stable enough
+    to type against). The SDK exposes them as untyped dicts keyed by
+    metric name; callers can inspect ``raw`` for any new fields the
+    server adds.
+    """
+
+    series_metrics: dict[str, Any] = field(default_factory=dict)
+    instant_metrics: dict[str, Any] = field(default_factory=dict)
+    extra: dict[str, Any] = field(default_factory=dict)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunMetricsResponse:
+        """Deserialize from API JSON.
+
+        Args:
+            data: Dictionary with ``series_metrics`` / ``instant_metrics``
+                (also accepts camelCase variants for robustness).
+                Unknown keys are captured in ``extra``.
+
+        Returns:
+            A new ``RunMetricsResponse`` instance.
+        """
+        known_keys = {"series_metrics", "seriesMetrics", "instant_metrics", "instantMetrics"}
+        extra = {k: v for k, v in data.items() if k not in known_keys}
+        raw_series = data.get("series_metrics", data.get("seriesMetrics", {})) or {}
+        raw_instant = data.get("instant_metrics", data.get("instantMetrics", {})) or {}
+        return cls(
+            series_metrics=dict(raw_series) if isinstance(raw_series, dict) else {},
+            instant_metrics=dict(raw_instant) if isinstance(raw_instant, dict) else {},
+            extra=extra,
+            raw=dict(data),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Uses the snake_case keys the API itself uses.
+        """
+        d: dict[str, Any] = {
+            "series_metrics": dict(self.series_metrics),
+            "instant_metrics": dict(self.instant_metrics),
+        }
+        if self.extra:
+            d.update(self.extra)
+        return d
+
+
+# ---------------------------------------------------------------------------
+# Pagination
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RunListPage:
+    """Paginated list of runs (``GET /runs`` response).
+
+    The Wherobots API returns string-based pagination cursors:
+    ``next_page``, ``previous_page``, ``current_page``,
+    ``current_page_backwards``.
+    """
+
+    items: list[RunView] = field(default_factory=list)
+    total: int = 0
+    next_page: str | None = None
+    previous_page: str | None = None
+    current_page: str | None = None
+    current_page_backwards: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    # Legacy alias for backward compatibility
+    @property
+    def cursor(self) -> str | None:
+        """Alias for ``next_page`` — kept for backward compatibility."""
+        return self.next_page
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RunListPage:
+        """Deserialize from API JSON.
+
+        Args:
+            data: Dictionary with ``items`` list, ``total`` count, and
+                optional pagination cursors. Also accepts legacy
+                ``cursor`` key as fallback for ``next_page``.
+
+        Returns:
+            A new ``RunListPage`` instance.
+        """
+        raw_items = data.get("items")
+        items = [RunView.from_dict(i) for i in (raw_items or [])]
+        return cls(
+            items=items,
+            total=data.get("total", len(items)),
+            next_page=data.get("next_page", data.get("cursor")),
+            previous_page=data.get("previous_page"),
+            current_page=data.get("current_page"),
+            current_page_backwards=data.get("current_page_backwards"),
+            raw=dict(data),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with serialized ``items``, ``total``, and pagination
+            cursors.
+        """
+        d: dict[str, Any] = {
+            "items": [i.to_dict() for i in self.items],
+            "total": self.total,
+        }
+        if self.next_page is not None:
+            d["next_page"] = self.next_page
+        if self.previous_page is not None:
+            d["previous_page"] = self.previous_page
+        if self.current_page is not None:
+            d["current_page"] = self.current_page
+        if self.current_page_backwards is not None:
+            d["current_page_backwards"] = self.current_page_backwards
+        return d
+
+
+# =========================================================================== #
+# Storage Integration Models
+# =========================================================================== #
+
+
+@dataclass
+class StorageIntegration:
+    """A user-configured S3 storage integration.
+
+    Represents a connection between the Wherobots organization and an
+    external S3 bucket, as returned by ``GET /storage``.
+    """
+
+    id: str
+    name: str
+    path: str
+    region: str
+    create_time: str | None = None
+    update_time: str | None = None
+    role_arn: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> StorageIntegration:
+        """Deserialize from the Wherobots API JSON format.
+
+        Args:
+            data: Dictionary from the API response.
+
+        Returns:
+            A new ``StorageIntegration`` instance.
+        """
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            path=data.get("path", ""),
+            region=data.get("region", ""),
+            create_time=data.get("createTime"),
+            update_time=data.get("updateTime"),
+            role_arn=data.get("roleArn"),
+            raw=dict(data),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the Wherobots API JSON format.
+
+        Returns:
+            Dict with camelCase keys matching the API contract.
+        """
+        d: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "path": self.path,
+            "region": self.region,
+        }
+        if self.create_time is not None:
+            d["createTime"] = self.create_time
+        if self.update_time is not None:
+            d["updateTime"] = self.update_time
+        if self.role_arn is not None:
+            d["roleArn"] = self.role_arn
+        return d