gmi-agentbox-sdk 0.1.0b1__tar.gz

gmi_agentbox_sdk-0.1.0b1/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+.pytest_cache/
+.mypy_cache/
+ce-tot-env
+ie-pro-env
+ce-tot-env.example
+ie-pro-env.example
+docs/todo.md
+examples/test.py
+.env
+.env.*
+!.env.example

gmi_agentbox_sdk-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GMI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gmi_agentbox_sdk-0.1.0b1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: gmi-agentbox-sdk
+Version: 0.1.0b1
+Summary: GMI AgentBox SDK for Python.
+Project-URL: Homepage, https://www.gmicloud.ai/
+Author: GMI
+License: MIT
+License-File: LICENSE
+Keywords: agentbox,gmi,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: certifi>=2024.0.0
+Requires-Dist: websocket-client>=1.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# GMI AgentBox SDK for Python
+
+Thin Python client for AgentBox.
+
+Public names are **Agent** (registered template) and **Sandbox** (launched
+container). Registering an Agent does not start anything.
+
+- [Usage](docs/usage.md) — install, auth, register, launch, wait, cleanup
+- [Reference](docs/reference.md) — client, methods, models, errors
+
+## Install
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Requires Python 3.9+.
+
+## Auth
+
+```bash
+export GMI_AGENTBOX_API_KEY="your-api-key"
+```
+
+`GMI_AGENTBOX_API_KEY` is required (or pass `api_key=`).
+`GMI_AGENTBOX_BASE_URL` is optional and defaults to production
+`https://console.gmicloud.ai`.
+
+## Quickstart
+
+```python
+from agentbox_sdk import AgentBoxClient
+
+client = AgentBoxClient()
+
+# Discover available IDCs and SKUs, then pass explicit values.
+# The SDK does not pick IDC or instance_type for you.
+idc_id = "us-central-iowa1"
+instance_type = "gmi.container.intel.x4660.large"
+
+agent = client.agents.create(
+    title="agentbox-demo",
+    image_url="docker.io/library/alpine:3.20",
+    idc=idc_id,
+)
+# generated_api_key is plaintext only on this response
+
+sandbox = agent.launch(instance_type=instance_type)
+sandbox.wait_until_running()  # default timeout 300s
+print(sandbox.endpoint_url)
+
+print(sandbox.logs())
+sandbox.delete()
+agent.delete()  # does not stop remaining sandboxes
+```
+
+`GET /products?idc_name=` takes an **idcId** from `GET /idcs`, not a region
+label. Launch cannot change the Agent's IDC.
+
+`sandboxes.list()` omits `stopped` and `deleted` unless you pass `status`.
+
+Against production (bills the account):
+
+```bash
+set -a && source ./ie-pro-env && set +a
+PYTHONPATH=src python examples/live_smoke.py
+```
+
+For the runtime E2E (build, command execution, file round trip, and
+asynchronous cancellation), select a matching runtime/IDC/SKU and run:
+
+```bash
+export GMI_AGENTBOX_RUNTIME="sandbox"  # or "container"
+PYTHONPATH=src python examples/sandbox_e2e.py
+```
+
+`GMI_AGENTBOX_BASE_URL` is optional. The E2E defaults
+`GMI_AGENTBOX_RUNTIME` to `sandbox`; `GMI_AGENTBOX_IDC` and
+`GMI_AGENTBOX_INSTANCE_TYPE` must always be set to values for the selected
+runtime.
+
+Set `GMI_AGENTBOX_TEST_SHELL=1` to include a WebSocket shell-connect check.
+The E2E asserts its data-plane operations for either runtime; it does not skip
+them according to Sandbox capabilities. Set `GMI_AGENTBOX_VALIDATE_CATALOGUE=1`
+to enable the optional runtime eligibility/IDC/SKU preflight.
+
+Sandbox runtimes also support command execution, file upload/download, and an
+interactive WebSocket shell. See the reference for `sandbox.execute()`,
+`sandbox.upload_file()`, `sandbox.download_file()`, and `sandbox.shell()`.

gmi_agentbox_sdk-0.1.0b1/README.md

@@ -0,0 +1,89 @@
+# GMI AgentBox SDK for Python
+
+Thin Python client for AgentBox.
+
+Public names are **Agent** (registered template) and **Sandbox** (launched
+container). Registering an Agent does not start anything.
+
+- [Usage](docs/usage.md) — install, auth, register, launch, wait, cleanup
+- [Reference](docs/reference.md) — client, methods, models, errors
+
+## Install
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Requires Python 3.9+.
+
+## Auth
+
+```bash
+export GMI_AGENTBOX_API_KEY="your-api-key"
+```
+
+`GMI_AGENTBOX_API_KEY` is required (or pass `api_key=`).
+`GMI_AGENTBOX_BASE_URL` is optional and defaults to production
+`https://console.gmicloud.ai`.
+
+## Quickstart
+
+```python
+from agentbox_sdk import AgentBoxClient
+
+client = AgentBoxClient()
+
+# Discover available IDCs and SKUs, then pass explicit values.
+# The SDK does not pick IDC or instance_type for you.
+idc_id = "us-central-iowa1"
+instance_type = "gmi.container.intel.x4660.large"
+
+agent = client.agents.create(
+    title="agentbox-demo",
+    image_url="docker.io/library/alpine:3.20",
+    idc=idc_id,
+)
+# generated_api_key is plaintext only on this response
+
+sandbox = agent.launch(instance_type=instance_type)
+sandbox.wait_until_running()  # default timeout 300s
+print(sandbox.endpoint_url)
+
+print(sandbox.logs())
+sandbox.delete()
+agent.delete()  # does not stop remaining sandboxes
+```
+
+`GET /products?idc_name=` takes an **idcId** from `GET /idcs`, not a region
+label. Launch cannot change the Agent's IDC.
+
+`sandboxes.list()` omits `stopped` and `deleted` unless you pass `status`.
+
+Against production (bills the account):
+
+```bash
+set -a && source ./ie-pro-env && set +a
+PYTHONPATH=src python examples/live_smoke.py
+```
+
+For the runtime E2E (build, command execution, file round trip, and
+asynchronous cancellation), select a matching runtime/IDC/SKU and run:
+
+```bash
+export GMI_AGENTBOX_RUNTIME="sandbox"  # or "container"
+PYTHONPATH=src python examples/sandbox_e2e.py
+```
+
+`GMI_AGENTBOX_BASE_URL` is optional. The E2E defaults
+`GMI_AGENTBOX_RUNTIME` to `sandbox`; `GMI_AGENTBOX_IDC` and
+`GMI_AGENTBOX_INSTANCE_TYPE` must always be set to values for the selected
+runtime.
+
+Set `GMI_AGENTBOX_TEST_SHELL=1` to include a WebSocket shell-connect check.
+The E2E asserts its data-plane operations for either runtime; it does not skip
+them according to Sandbox capabilities. Set `GMI_AGENTBOX_VALIDATE_CATALOGUE=1`
+to enable the optional runtime eligibility/IDC/SKU preflight.
+
+Sandbox runtimes also support command execution, file upload/download, and an
+interactive WebSocket shell. See the reference for `sandbox.execute()`,
+`sandbox.upload_file()`, `sandbox.download_file()`, and `sandbox.shell()`.

gmi_agentbox_sdk-0.1.0b1/docs/reference.md

@@ -0,0 +1,392 @@
+# Reference
+
+Package: `gmi-agentbox-sdk`  
+Import: `agentbox_sdk`
+
+See [Usage](usage.md) for workflows.
+
+## Configuration
+
+### `AgentBoxClient`
+
+```python
+AgentBoxClient(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    *,
+    timeout: float = 30.0,
+)
+```
+
+| Argument | Default | Notes |
+|---|---|---|
+| `api_key` | `GMI_AGENTBOX_API_KEY` | Required API key. Raises `ValueError` if unset |
+| `base_url` | `GMI_AGENTBOX_BASE_URL` or `DEFAULT_BASE_URL` | Optional service origin. Production origin if unset |
+| `timeout` | `30.0` | Per HTTP call, seconds |
+
+`DEFAULT_BASE_URL` is
+`https://console.gmicloud.ai`.
+`DEFAULT_WAIT_TIMEOUT` is `300.0` seconds (`sandbox.wait_until_running`).
+
+Collections on the client: `agents`, `sandboxes`, `idcs`, `products`.
+Also `client.eligibility()`.
+
+#### `client.health() -> dict`
+
+Returns local client configuration.
+
+```python
+{"status": "ok", "baseUrl": "...", "authenticated": True}
+```
+
+#### `client.eligibility() -> Eligibility`
+
+Returns the organization's available runtimes and data centers.
+
+### Environment variables
+
+| Variable | Used by |
+|---|---|
+| `GMI_AGENTBOX_API_KEY` | Required API key |
+| `GMI_AGENTBOX_BASE_URL` | Optional service origin; defaults to `DEFAULT_BASE_URL` |
+
+Errors expose `message`, `code`, and `details` when supplied by the service.
+
+## Agents
+
+### `client.agents`
+
+#### `create(*, title, ...) -> Agent`
+
+| Parameter | Required | Details |
+|---|---|---|
+| `title` | yes | Agent name |
+| `image_url` | no | Container image |
+| `idc` | Sandbox: yes; otherwise no | Data center identifier; required with `runtime="sandbox"` |
+| `runtime` | no | `"container"` or `"sandbox"`; defaults to the service default |
+| `start_cmd` | no | Startup command for a Sandbox |
+| `env` | no | Environment-variable definitions |
+| `ports` | no | Port definitions |
+| `instance_type` | Sandbox: yes; otherwise no | Required with `runtime="sandbox"` |
+| `assign_public_ip` | no | Whether to request a public IP |
+| `image_credential` | no | Private-registry credentials: `{"username": "...", "secret": "..."}` |
+| `short_desc` | no | Short description |
+| `share_storage_mount_path` | no | Shared-storage mount path |
+| `clone_source_id` | no | Source Agent ID to clone |
+
+Create does not start a container.
+
+#### `list(*, page=1, page_size=20) -> Page`
+
+Pagination is 1-indexed. API default page size is 20, max 100.
+
+#### `get(slug) -> Agent`
+
+#### `update(slug, **fields) -> Agent`
+
+PATCH passthrough. Only send fields the API accepts; locked fields return `422`.
+
+#### `delete(slug) -> None`
+
+Does not stop or delete running sandboxes of that Agent.
+
+### `Agent`
+
+Represents an Agent.
+
+| Property | Type | Notes |
+|---|---|---|
+| `id` | `str` | Agent ID |
+| `slug` | `str` | Stable Agent identifier |
+| `title` | `str \| None` | |
+| `idc` | `str \| None` | Data center identifier |
+| `image_url` | `str \| None` | |
+| `runtime` | `str \| None` | Selected runtime |
+| `template_build_status` | `str \| None` | Sandbox image-build status |
+| `template_build_error` | `str \| None` | Sandbox image-build error |
+| `env` | `list` | Copy of `env` |
+| `revision` | `int \| None` | |
+| `generated_api_key` | `str \| None` | Plaintext MaaS key on **create** only |
+| `launchable` | `bool` | Whether the Agent can be launched |
+
+#### `agent.refresh() -> Agent`
+
+Reloads the Agent.
+
+#### `agent.update(**fields) -> Agent`
+
+Same as `client.agents.update(agent.slug, **fields)`.
+
+#### `agent.delete() -> None`
+
+#### `agent.launch(*, instance_type, idc_name=None, env=None, display_name=None, assign_public_ip=None, ports=None, storages=None) -> Sandbox`
+
+`idc_name` defaults to `agent.idc`. Raises `ValueError` if neither is set.
+Launch cannot change region; `idc_name` must match the Agent's data center.
+
+Launch returns immediately. Call `refresh()` or `wait_until_running()` for
+current state.
+
+#### `agent.sandboxes(*, page=1, page_size=20) -> Page`
+
+Sandboxes for this Agent.
+
+## Sandboxes
+
+### `client.sandboxes`
+
+#### `launch(slug, *, instance_type, idc_name, ...) -> Sandbox`
+
+Same body as `agent.launch`. `idc_name` is required here.
+
+#### `list(*, agent_id=None, status=None, page=1, page_size=20) -> Page`
+
+| Parameter | Query |
+|---|---|
+| `agent_id` | Restrict results to one Agent |
+| `status` | `status`; a sequence is joined with commas |
+| `page` / `page_size` | pagination |
+
+If `status` is omitted, the API **excludes** `stopped` and `deleted`.
+
+#### `get(sandbox_id) -> Sandbox`
+
+#### `delete(sandbox_id) -> None`
+
+One-way. The sandbox cannot be restarted.
+
+#### `logs(sandbox_id) -> str`
+
+Returns the `logs` string from the response payload, or `""`.
+
+#### `metrics(sandbox_id, *, start, end, kinds=None, step=None) -> MetricsBatch`
+
+`start` / `end` are unix seconds. `kinds` is
+a string or sequence (`cpu,memory`); omit for all 8 charts. `step` default
+on the API is 60s (min 5, max 3600).
+
+#### `metrics_timeseries(sandbox_id, *, kind, start, end, step=None) -> MetricSeries`
+
+`kind` is one of `gpu_util`,
+`gpu_mem`, `cpu`, `memory`, `disk_read`, `disk_write`, `net_rx`, `net_tx`.
+
+#### `stream(sandbox_id, *, timeout=None) -> Iterator[StreamEvent]`
+
+Yields `StreamEvent(event, data, raw)`.
+Comment lines (`: ping`) are `event="heartbeat"`. `timeout=None` means the
+socket has no idle timeout. 4xx/5xx raise the same `APIError` types as
+other calls.
+
+Logs, metrics, and stream methods require the corresponding Sandbox
+capability to be available.
+
+#### `execute(sandbox_id, command, *, wait=True, wait_timeout_seconds=None) -> Execution`
+
+Runs a command in a Sandbox. A completed command returns `accepted=False`; an
+accepted asynchronous command returns `accepted=True`.
+
+#### `get_execution(sandbox_id, execution_id) -> Execution`
+
+Retrieves the latest execution state.
+
+#### `cancel_execution(sandbox_id, execution_id) -> Execution`
+
+Requests cancellation of an execution.
+
+#### `upload_file(sandbox_id, *, path, file) -> list[dict]`
+
+Uploads bytes, a local path, or a binary file object to an absolute Sandbox
+path.
+
+#### `download_file(sandbox_id, *, path) -> FileDownload`
+
+Downloads a file from an absolute Sandbox path.
+
+#### `shell(sandbox_id, *, timeout=None)`
+
+Opens an interactive shell connection.
+
+### `Sandbox`
+
+Represents a Sandbox.
+
+| Property | Type | Notes |
+|---|---|---|
+| `id` | `str` | Sandbox ID |
+| `status` | `str \| None` | Current lifecycle status |
+| `endpoint_url` | `str \| None` | Empty string becomes `None` |
+| `agent_id` | `str \| None` | Owning Agent ID |
+| `agent_slug` | `str \| None` | Owning Agent slug |
+| `display_name` | `str \| None` | |
+| `instance_type` | `str \| None` | Billing SKU, not the product object name |
+| `idc_name` | `str \| None` | Data center identifier |
+| `status_stale` | `bool` | |
+| `last_error` | `str \| None` | |
+| `runtime` | `str \| None` | Runtime name, e.g. `sandbox` |
+| `capabilities` | `dict` | Server-derived enabled surfaces |
+| `expires_at` | `str \| None` | Sandbox expiry timestamp |
+
+#### `sandbox.refresh() -> Sandbox`
+
+#### `sandbox.logs() -> str`
+
+#### `sandbox.metrics(*, start, end, kinds=None, step=None) -> MetricsBatch`
+
+#### `sandbox.metrics_timeseries(*, kind, start, end, step=None) -> MetricSeries`
+
+#### `sandbox.stream(*, timeout=None) -> Iterator[StreamEvent]`
+
+#### `sandbox.execute(command, *, wait=True, wait_timeout_seconds=None) -> Execution`
+
+Runs a command. `Execution.accepted` is true when execution continues
+asynchronously; use `get_execution()` to poll it, or `cancel_execution()`
+to request cancellation. `wait_timeout_seconds` is omitted when `wait=False`.
+
+#### `sandbox.get_execution(execution_id) -> Execution`
+
+#### `sandbox.cancel_execution(execution_id) -> Execution`
+
+#### `sandbox.upload_file(path, file) -> list[dict]`
+
+Accepts bytes, a local
+path, or a binary file object. `sandbox.download_file(path=...)` returns
+`FileDownload(content, filename, headers)`. Paths must be absolute and cannot
+contain `.` or `..` segments.
+
+#### `sandbox.download_file(path) -> FileDownload`
+
+#### `sandbox.shell(*, timeout=None)`
+
+Returns an interactive connection supporting `send`, `recv`, and `close`.
+
+#### `sandbox.delete() -> None`
+
+#### `sandbox.wait_until_running(*, timeout=300.0, poll_interval=2.0) -> Sandbox`
+
+Polls until `status == "running"`.
+
+| Outcome | Result |
+|---|---|
+| `running` | returns `self` |
+| `error`, `deleted`, `stopped`, `stopping` | raises `SandboxFailed` |
+| timeout | raises `SandboxWaitTimeout` |
+
+`SandboxFailed.status` is the sandbox status; `SandboxFailed.message` is
+`last_error` when set.
+
+## Catalog
+
+### `client.idcs`
+
+#### `list(*, runtime=None) -> list[Idc]`
+
+### `Idc`
+
+| Property | Description |
+|---|---|
+| `idc_id` | Data center identifier |
+| `name` | `name` |
+
+Use `idc_id` when selecting an Agent or Sandbox location.
+
+### `client.products`
+
+#### `list(*, idc_name=None, runtime=None) -> list[Product]`
+
+`idc_name` is a data center identifier from `idcs.list()`, not a region label.
+
+### `Product`
+
+| Property | Description |
+|---|---|
+| `instance_type` | SKU identifier |
+| `price` | `price` |
+
+## Result types
+
+### `Page`
+
+```python
+@dataclass
+class Page:
+    items: list  # Agent or Sandbox
+    total: int
+    page: int
+    page_size: int
+```
+
+### `Execution`
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `str \| None` | Execution identifier |
+| `status` | `str \| None` | Current execution status |
+| `exit_code` | `int \| None` | Process exit code when complete |
+| `accepted` | `bool` | True when execution continues asynchronously |
+| `data` | `dict` | Execution details, including command output when provided |
+
+### `FileDownload`
+
+| Property | Type | Description |
+|---|---|---|
+| `content` | `bytes` | Downloaded file content |
+| `filename` | `str \| None` | Download filename |
+| `headers` | mapping | Response metadata |
+
+## Errors
+
+All SDK errors subclass `AgentBoxSDKError`.
+
+| Type | When |
+|---|---|
+| `TransportError` | The service could not be reached |
+| `APIError` | A service error not mapped below |
+| `BadRequestError` | Invalid request |
+| `AuthenticationError` | Invalid or missing API key |
+| `PermissionDeniedError` | Insufficient permission |
+| `NotFoundError` | Requested resource was not found |
+| `ConflictError` | Request conflicts with resource state |
+| `UnprocessableError` | Request could not be processed |
+| `RateLimitError` | Too many requests |
+| `ServerError` | Service-side failure |
+| `SandboxFailed` | Wait hit a terminal non-running status |
+| `SandboxWaitTimeout` | Wait exceeded `timeout` |
+
+`APIError` attributes: `status_code`, `message`, `code`, `details`.
+
+
+## Public exports
+
+```python
+from agentbox_sdk import (
+    DEFAULT_BASE_URL,
+    Agent,
+    AgentBoxClient,
+    AgentBoxSDKError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    Eligibility,
+    Execution,
+    FileDownload,
+    Idc,
+    MetricSeries,
+    MetricsBatch,
+    NotFoundError,
+    Page,
+    PermissionDeniedError,
+    Product,
+    RateLimitError,
+    Sandbox,
+    SandboxFailed,
+    SandboxWaitTimeout,
+    ServerError,
+    StreamEvent,
+    TransportError,
+    UnprocessableError,
+)
+```
+
+`__version__` is the installed `gmi-agentbox-sdk` version, or `"0.0.0"` if
+the package metadata is missing.