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()`.
