added context helpers to SDKs

Author: james-rl

README-SDK.md

@@ -4,22 +4,36 @@ The `RunloopSDK` builds on top of the underlying REST client and provides a Pyth
 
 ## Table of Contents
 
-- [Installation](#installation)
-- [Quickstart (synchronous)](#quickstart-synchronous)
-- [Quickstart (asynchronous)](#quickstart-asynchronous)
-- [Core Concepts](#core-concepts)
-- [Devbox](#devbox)
-- [Blueprint](#blueprint)
-- [Snapshot](#snapshot)
-- [StorageObject](#storageobject)
-- [Mounting Storage Objects to Devboxes](#mounting-storage-objects-to-devboxes)
-- [Accessing the Underlying REST Client](#accessing-the-underlying-rest-client)
-- [Error Handling](#error-handling)
-- [Advanced Configuration](#advanced-configuration)
-- [Async Usage](#async-usage)
-- [Polling Configuration](#polling-configuration)
-- [Complete API Reference](#complete-api-reference)
-- [Feedback](#feedback)
+- [Runloop SDK – Python Object-Oriented Client](#runloop-sdk--python-object-oriented-client)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Quickstart (synchronous)](#quickstart-synchronous)
+  - [Quickstart (asynchronous)](#quickstart-asynchronous)
+  - [Core Concepts](#core-concepts)
+    - [RunloopSDK](#runloopsdk)
+    - [Available Resources](#available-resources)
+    - [Devbox](#devbox)
+      - [Command Execution](#command-execution)
+      - [Execution Management](#execution-management)
+      - [Execution Results](#execution-results)
+      - [Streaming Command Output](#streaming-command-output)
+      - [File Operations](#file-operations)
+      - [Network Operations](#network-operations)
+      - [Snapshot Operations](#snapshot-operations)
+      - [Devbox Lifecycle Management](#devbox-lifecycle-management)
+      - [Context Manager Support](#context-manager-support)
+    - [Blueprint](#blueprint)
+    - [Snapshot](#snapshot)
+    - [StorageObject](#storageobject)
+      - [Storage Object Upload Helpers](#storage-object-upload-helpers)
+    - [Mounting Storage Objects to Devboxes](#mounting-storage-objects-to-devboxes)
+  - [Accessing the Underlying REST Client](#accessing-the-underlying-rest-client)
+  - [Error Handling](#error-handling)
+  - [Advanced Configuration](#advanced-configuration)
+  - [Async Usage](#async-usage)
+  - [Polling Configuration](#polling-configuration)
+  - [Complete API Reference](#complete-api-reference)
+  - [Feedback](#feedback)
 
 ## Installation
 
@@ -409,6 +423,44 @@ blueprint = runloop.blueprint.create(
     system_setup_commands=["pip install numpy pandas"],
 )
 
+# Or create a blueprint with a Docker build context from a local directory
+from pathlib import Path
+from runloop_api_client.lib.context_loader import build_docker_context_tar
+
+context_root = Path("./my-app")
+tar_bytes = build_docker_context_tar(context_root)
+
+build_ctx_obj = runloop.storage_object.upload_from_bytes(
+    data=tar_bytes,
+    name="my-app-context.tar.gz",
+    content_type="tgz",
+)
+
+shared_root = Path("./shared-lib")
+shared_tar = build_docker_context_tar(shared_root)
+
+shared_ctx_obj = runloop.storage_object.upload_from_bytes(
+    data=shared_tar,
+    name="shared-lib-context.tar.gz",
+    content_type="tgz",
+)
+
+blueprint_with_context = runloop.blueprint.create(
+    name="my-blueprint-with-context",
+    dockerfile=\"\"\"\
+FROM ubuntu:22.04
+WORKDIR /app
+# use the named context
+RUN --mount=type=bind,from=shared,source=/,target=/shared ls -R /shared
+\"\"\",
+    # Primary build context
+    build_context=build_ctx_obj.as_build_context(),
+    # Additional named build contexts (for Docker buildx-style usage)
+    named_build_contexts={
+        "shared": shared_ctx_obj.as_build_context(),
+    },
+)
+
 # Or get an existing one
 blueprint = runloop.blueprint.from_id(blueprint_id="bpt_123")
 

src/runloop_api_client/sdk/async_storage_object.py

@@ -158,6 +158,17 @@ async def upload_content(self, content: str | bytes) -> None:
         response = await self._client._client.put(url, content=content)
         response.raise_for_status()
 
+    def as_build_context(self) -> dict[str, str]:
+        """Return this object in the shape expected for a Blueprint build context.
+
+        The returned dict can be passed directly to ``build_context`` or
+        ``named_build_contexts`` when creating a blueprint.
+        """
+        return {
+            "object_id": self._id,
+            "type": "object",
+        }
+
     def _ensure_upload_url(self) -> str:
         """Return the upload URL, ensuring it exists.
 

src/runloop_api_client/sdk/storage_object.py

@@ -158,6 +158,17 @@ def upload_content(self, content: str | bytes) -> None:
         response = self._client._client.put(url, content=content)
         response.raise_for_status()
 
+    def as_build_context(self) -> dict[str, str]:
+        """Return this object in the shape expected for a Blueprint build context.
+
+        The returned dict can be passed directly to ``build_context`` or
+        ``named_build_contexts`` when creating a blueprint.
+        """
+        return {
+            "object_id": self._id,
+            "type": "object",
+        }
+
     def _ensure_upload_url(self) -> str:
         """Return the upload URL, ensuring it is present.
 

tests/sdk/test_async_clients.py

@@ -327,6 +327,15 @@ async def test_upload_from_file_missing_path(self, mock_async_client: AsyncMock,
         with pytest.raises(OSError, match="Failed to read file"):
             await client.upload_from_file(missing_file)
 
+    def test_as_build_context(self, mock_async_client: AsyncMock, object_view: MockObjectView) -> None:
+        """as_build_context should return the correct dict shape."""
+        obj = AsyncStorageObject(mock_async_client, object_view.id, upload_url=None)
+
+        assert obj.as_build_context() == {
+            "object_id": object_view.id,
+            "type": "object",
+        }
+
 
 class TestAsyncRunloopSDK:
     """Tests for AsyncRunloopSDK class."""

tests/sdk/test_clients.py

@@ -306,6 +306,15 @@ def test_upload_from_file_missing_path(self, mock_client: Mock, tmp_path: Path)
         with pytest.raises(OSError, match="Failed to read file"):
             client.upload_from_file(missing_file)
 
+    def test_as_build_context(self, mock_client: Mock, object_view: MockObjectView) -> None:
+        """as_build_context should return the correct dict shape."""
+        obj = StorageObject(mock_client, object_view.id, upload_url=None)
+
+        assert obj.as_build_context() == {
+            "object_id": object_view.id,
+            "type": "object",
+        }
+
 
 class TestRunloopSDK:
     """Tests for RunloopSDK class."""