initial llm work

Author: sid-rl

README-SDK.md

@@ -0,0 +1,149 @@
+# Runloop SDK – Python Object-Oriented Client
+
+The `RunloopSDK` builds on top of the generated REST client and provides a Pythonic, object-oriented API for managing devboxes, blueprints, snapshots, and storage objects. The SDK exposes synchronous and asynchronous variants to match your runtime requirements.
+
+> **Installation**  
+> The SDK ships with the `runloop_api_client` package—no extra dependencies are required.
+
+```bash
+pip install runloop_api_client
+```
+
+## Quickstart (synchronous)
+
+```python
+from runloop_api_client import RunloopSDK
+
+sdk = RunloopSDK()
+
+# Create a ready-to-use devbox
+with sdk.devbox.create(name="my-devbox") as devbox:
+    result = devbox.cmd.exec("echo 'Hello from Runloop!'")
+    print(result.stdout())
+
+    # Stream stdout in real time
+    devbox.cmd.exec(
+        "ls -la",
+        stdout=lambda line: print("stdout:", line),
+        output=lambda line: print("combined:", line),
+    )
+
+# Blueprints
+blueprint = sdk.blueprint.create(
+    name="my-blueprint",
+    dockerfile="FROM ubuntu:22.04\nRUN echo 'Hello' > /hello.txt\n",
+)
+devbox = blueprint.create_devbox(name="dev-from-blueprint")
+
+# Storage objects
+obj = sdk.storage_object.upload_from_text("Hello world!", name="greeting.txt")
+print(obj.download_as_text())
+```
+
+## Quickstart (asynchronous)
+
+```python
+import asyncio
+from runloop_api_client import AsyncRunloopSDK
+
+async def main():
+    sdk = AsyncRunloopSDK()
+    async with sdk.devbox.create(name="async-devbox") as devbox:
+        result = await devbox.cmd.exec("pwd")
+        print(await result.stdout())
+
+        async def capture(line: str) -> None:
+            print(">>", line)
+
+        await devbox.cmd.exec("ls", stdout=capture)
+
+asyncio.run(main())
+```
+
+## Available Resources
+
+- **Devbox / AsyncDevbox**
+  - Creation helpers (`create`, `create_from_blueprint_id`, `create_from_snapshot`, `from_id`)
+  - Lifecycle management (`await_running`, `suspend`, `resume`, `keep_alive`, `shutdown`)
+  - Command execution (`cmd.exec`, `cmd.exec_async`) with optional streaming callbacks
+  - File operations (`read`, `write`, `upload`, `download`)
+  - Network helpers (`net.create_ssh_key`, `net.create_tunnel`, `net.remove_tunnel`)
+
+- **Blueprint / AsyncBlueprint**
+  - Build orchestration (`create`)
+  - Fetch metadata & logs (`get_info`, `logs`)
+  - Spawn devboxes from existing blueprints (`create_devbox`)
+
+- **Snapshot / AsyncSnapshot**
+  - List and inspect snapshots (`list`, `get_info`, `await_completed`)
+  - Metadata updates (`update`), deletion (`delete`)
+  - Provision new devboxes from snapshots (`create_devbox`)
+
+- **StorageObject / AsyncStorageObject**
+  - Object creation (`create`, `from_id`, `list`)
+  - Convenience uploads (`upload_from_file`, `upload_from_text`, `upload_from_bytes`)
+  - Manual uploads via presigned URLs (`upload_content`, `complete`)
+  - Downloads (`download_as_text`, `download_as_bytes`)
+
+All objects expose the low-level REST ID through the `id` property, making it easy to cross-reference with existing tooling.
+
+## Streaming Command Output
+
+Pass callbacks into `cmd.exec` / `cmd.exec_async` to process logs in real time. Synchronous callbacks receive strings; asynchronous callbacks may return either `None` or `Awaitable[None]`.
+
+```python
+def handle_output(line: str) -> None:
+    print("LOG:", line)
+
+result = devbox.cmd.exec(
+    "python train.py",
+    stdout=handle_output,
+    stderr=lambda line: print("ERR:", line),
+    output=lambda line: print("ANY:", line),
+)
+print("exit code:", result.exit_code)
+```
+
+Async example:
+
+```python
+async def capture(line: str) -> None:
+    await log_queue.put(line)
+
+await devbox.cmd.exec(
+    "tail -f /var/log/app.log",
+    stdout=capture,
+)
+```
+
+## Storage Object Upload Helpers
+
+The storage helpers manage the multi-step upload flow (create → PUT to presigned URL → complete):
+
+```python
+from pathlib import Path
+
+# Upload local file with content-type detection
+obj = sdk.storage_object.upload_from_file(Path("./report.csv"))
+
+# Manual control
+obj = sdk.storage_object.create("data.bin", content_type="binary")
+obj.upload_content(b"\xDE\xAD\xBE\xEF")
+obj.complete()
+```
+
+## Accessing the Generated REST Client
+
+The SDK always exposes the underlying generated client through the `.api` attribute:
+
+```python
+sdk = RunloopSDK()
+raw_devbox = sdk.api.devboxes.create()
+```
+
+This makes it straightforward to mix high-level helpers with low-level calls whenever you need advanced control.
+
+## Feedback
+
+The object-oriented SDK is new for Python—feedback and ideas are welcome! Please open an issue or pull request on GitHub if you spot gaps, bugs, or ergonomic improvements.
+

README.md

@@ -26,6 +26,10 @@ pip install runloop_api_client
 
 The full API of this library can be found in [api.md](api.md).
 
+### Object-Oriented SDK
+
+For a higher-level, Pythonic interface, check out the new [`RunloopSDK`](README-SDK.md) which layers an object-oriented API on top of the generated client (including synchronous and asynchronous variants).
+
 ```python
 import os
 from runloop_api_client import Runloop

src/runloop_api_client/__init__.py

@@ -3,6 +3,7 @@
 import typing as _t
 
 from . import types
+from .sdk import RunloopSDK, AsyncRunloopSDK
 from ._types import NOT_GIVEN, Omit, NoneType, NotGiven, Transport, ProxiesTypes, omit, not_given
 from ._utils import file_from_path
 from ._client import Client, Stream, Runloop, Timeout, Transport, AsyncClient, AsyncStream, AsyncRunloop, RequestOptions
@@ -39,6 +40,8 @@
     "NotGiven",
     "NOT_GIVEN",
     "not_given",
+    "RunloopSDK",
+    "AsyncRunloopSDK",
     "Omit",
     "omit",
     "RunloopError",

src/runloop_api_client/sdk/__init__.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from ._sync import RunloopSDK
+from ._async import AsyncRunloopSDK
+from .devbox import Devbox, DevboxClient
+from .snapshot import Snapshot, SnapshotClient
+from .blueprint import Blueprint, BlueprintClient
+from .execution import Execution
+from .async_devbox import AsyncDevbox, AsyncDevboxClient
+from .async_snapshot import AsyncSnapshot, AsyncSnapshotClient
+from .storage_object import StorageObject, StorageObjectClient
+from .async_blueprint import AsyncBlueprint, AsyncBlueprintClient
+from .async_execution import AsyncExecution
+from .execution_result import ExecutionResult
+from .async_storage_object import AsyncStorageObject, AsyncStorageObjectClient
+from .async_execution_result import AsyncExecutionResult
+
+__all__ = [
+    "RunloopSDK",
+    "AsyncRunloopSDK",
+    "Devbox",
+    "DevboxClient",
+    "Execution",
+    "ExecutionResult",
+    "Blueprint",
+    "BlueprintClient",
+    "Snapshot",
+    "SnapshotClient",
+    "StorageObject",
+    "StorageObjectClient",
+    "AsyncDevbox",
+    "AsyncDevboxClient",
+    "AsyncExecution",
+    "AsyncExecutionResult",
+    "AsyncBlueprint",
+    "AsyncBlueprintClient",
+    "AsyncSnapshot",
+    "AsyncSnapshotClient",
+    "AsyncStorageObject",
+    "AsyncStorageObjectClient",
+]

src/runloop_api_client/sdk/_async.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Mapping
+
+import httpx
+
+from .._types import Timeout, NotGiven, not_given
+from .._client import AsyncRunloop
+from .async_devbox import AsyncDevboxClient
+from .async_snapshot import AsyncSnapshotClient
+from .async_blueprint import AsyncBlueprintClient
+from .async_storage_object import AsyncStorageObjectClient
+
+
+class AsyncRunloopSDK:
+    """
+    High-level asynchronous entry point for the Runloop SDK.
+
+    The generated async REST client remains available via the ``api`` attribute.
+    Higher-level helpers will be introduced incrementally.
+    """
+
+    api: AsyncRunloop
+    devbox: AsyncDevboxClient
+    blueprint: AsyncBlueprintClient
+    snapshot: AsyncSnapshotClient
+    storage_object: AsyncStorageObjectClient
+
+    def __init__(
+        self,
+        *,
+        client: AsyncRunloop | None = None,
+        bearer_token: str | None = None,
+        base_url: str | httpx.URL | None = None,
+        timeout: float | Timeout | None | NotGiven = not_given,
+        max_retries: int | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        _strict_response_validation: bool = False,
+    ) -> None:
+        """
+        Create an asynchronous Runloop SDK instance.
+
+        Arguments mirror :class:`runloop_api_client.AsyncRunloop`.
+        """
+        if client is None:
+            runloop_kwargs: dict[str, object] = {
+                "bearer_token": bearer_token,
+                "base_url": base_url,
+                "timeout": timeout,
+                "default_headers": default_headers,
+                "default_query": default_query,
+                "http_client": http_client,
+                "_strict_response_validation": _strict_response_validation,
+            }
+            if max_retries is not None:
+                runloop_kwargs["max_retries"] = max_retries
+
+            self.api = AsyncRunloop(**runloop_kwargs)
+            self._owns_client = True
+        else:
+            self.api = client
+            self._owns_client = False
+
+        self.devbox = AsyncDevboxClient(self.api)
+        self.blueprint = AsyncBlueprintClient(self.api, self.devbox)
+        self.snapshot = AsyncSnapshotClient(self.api, self.devbox)
+        self.storage_object = AsyncStorageObjectClient(self.api)
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP client."""
+        if self._owns_client:
+            await self.api.close()
+
+    async def __aenter__(self) -> "AsyncRunloopSDK":
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.aclose()

src/runloop_api_client/sdk/_helpers.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import io
+import os
+from typing import Union
+from pathlib import Path
+
+from .._types import FileTypes
+from .._utils import file_from_path
+
+UploadInput = Union[FileTypes, str, os.PathLike[str], Path, bytes, bytearray, io.IOBase]
+
+
+def normalize_upload_input(file: UploadInput) -> FileTypes:
+    """
+    Normalize a variety of Python file representations into the generated client's FileTypes.
+    """
+    if isinstance(file, tuple):
+        return file
+    if isinstance(file, bytes):
+        return file
+    if isinstance(file, bytearray):
+        return bytes(file)
+    if isinstance(file, (str, Path, os.PathLike)):
+        return file_from_path(file)
+    if isinstance(file, io.TextIOBase):
+        return file.read().encode("utf-8")
+    if isinstance(file, io.BufferedIOBase) or isinstance(file, io.RawIOBase):
+        return file
+    if isinstance(file, io.IOBase) and hasattr(file, "read"):
+        data = file.read()
+        if isinstance(data, str):
+            return data.encode("utf-8")
+        return data
+    raise TypeError("Unsupported file type for upload. Provide path, bytes, or file-like object.")