Skip to content

Commit 24d1bff

Browse files
authored
docs(sdk): improve usage guide and package metadata (#23)
Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
1 parent 1c75ba7 commit 24d1bff

3 files changed

Lines changed: 152 additions & 58 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,28 @@ virtual environment. `mise tasks` lists every task. The ones you need most:
2020
| `mise run format` | Format the code |
2121
| `mise run test` | Unit tests; `UV_PYTHON=3.11` picks the interpreter |
2222
| `mise run build` | Build the wheel and sdist, verify them, and install them on Python 3.11 |
23-
| `mise run e2e` | E2E tests against a running gateway; see the README for setup |
23+
| `mise run e2e` | E2E tests against a running gateway; see below for setup |
2424
| `mise run proto:gen` | Regenerate the bindings from core at the pinned ref |
2525
| `mise run core:version` | Print the pinned core version |
2626

2727
CI runs the unit tests on every Python version the package supports (3.11 to
2828
3.14).
2929

30+
## E2E tests
31+
32+
`tests/e2e` runs against a real gateway; `mise run test` skips it. CI runs it against the published gateway of the pinned core version, with the Docker compute driver. To run it locally, you need Docker with the compose plugin:
33+
34+
```shell
35+
mise run e2e:image
36+
scripts/e2e/start-gateway.sh "$(mise run -q core:version)" --default-image openshell/e2e-python:dev
37+
OPENSHELL_GATEWAY=e2e mise run e2e
38+
scripts/e2e/stop-gateway.sh
39+
```
40+
41+
`e2e:image` builds the sandbox image from `tests/e2e/Dockerfile.workload`, a copy of core's, with the Python version from `.python-version` and `cloudpickle`, so `Sandbox.exec_python` can run the client's callables.
42+
43+
`start-gateway.sh` is meant for throwaway hosts. It registers `e2e` as the active gateway, and `stop-gateway.sh` removes every sandbox container labelled with core's default namespace. Set `XDG_CONFIG_HOME` to keep your own gateway registrations apart.
44+
3045
## Commits and pull requests
3146

3247
- Use [Conventional Commits](https://www.conventionalcommits.org/):
@@ -45,6 +60,8 @@ core ref, `OPENSHELL_CORE_REF` in `mise.toml`, and committed. Don't edit
4560
generated files; change the pin and run `mise run proto:gen`.
4661
`mise run proto:check` fails when the committed bindings don't match the pin.
4762

63+
Building a wheel or sdist needs neither a core checkout nor network access because the generated bindings are committed. A change to the core pin makes the generated API changes visible in the diff.
64+
4865
Shared test fixtures come from core's `sdk/conformance/` and are copied into
4966
`tests/fixtures/`. `mise run conformance:check` compares them with core at the
5067
pinned ref.

‎README.md‎

Lines changed: 131 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,154 @@
1-
# OpenShell Python SDK
1+
<picture>
2+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NVIDIA/OpenShell/main/docs/brand/assets/openshell-banner-dark.png">
3+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NVIDIA/OpenShell/main/docs/brand/assets/openshell-banner-light.png">
4+
<img alt="OpenShell" src="https://raw.githubusercontent.com/NVIDIA/OpenShell/main/docs/brand/assets/openshell-banner-light.png" width="430">
5+
</picture>
26

3-
The `openshell` package is the Python client for the
4-
[OpenShell](https://github.com/NVIDIA/OpenShell) gateway: sandbox lifecycle,
5-
templates, workspaces, exec, and provider credentials, plus the generated gRPC
6-
bindings under `openshell._proto`.
7+
# Python SDK for OpenShell
8+
9+
[![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/ai-openshell/sdk-python/blob/main/LICENSE)
10+
[![PyPI](https://img.shields.io/pypi/v/openshell?logo=pypi)](https://pypi.org/project/openshell/)
11+
[![Security policy](https://img.shields.io/badge/Security-Report%20a%20Vulnerability-red)](https://github.com/ai-openshell/sdk-python/blob/main/SECURITY.md)
12+
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen)](https://docs.nvidia.com/openshell/latest/sdk/python)
13+
14+
Use the Python SDK to manage [OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes from applications, notebooks, and automation. Create sandboxes, run commands and Python functions, and manage templates, workspaces, and provider credentials through the gateway.
15+
16+
See the [Python SDK documentation](https://docs.nvidia.com/openshell/latest/sdk/python) for connection options, authentication, and generated gRPC bindings.
17+
18+
## Installation
19+
20+
The SDK requires Python 3.11 or later and a [running OpenShell gateway](https://docs.nvidia.com/openshell/latest/about/installation). Installing the `openshell` package installs only the Python client.
21+
22+
With uv, add the SDK to your project:
723

824
```shell
9-
pip install openshell
25+
uv add openshell
1026
```
1127

12-
The SDK moved here from NVIDIA/OpenShell. The package name, import paths, and
13-
API are unchanged, including `openshell._proto`. Releases published from
14-
NVIDIA/OpenShell stay on PyPI.
28+
Or install it with pip:
1529

16-
## Development
30+
```shell
31+
pip install -U openshell
32+
```
1733

18-
Tools are managed by [mise](https://mise.jdx.dev/) and dependencies by
19-
[uv](https://docs.astral.sh/uv/). The Python version is pinned in
20-
`.python-version`, which both read. See [CONTRIBUTING.md](CONTRIBUTING.md) for
21-
setup, commit rules and the release model, and [SECURITY.md](SECURITY.md) to
22-
report a vulnerability.
34+
## Quickstart
2335

24-
```shell
25-
mise run ci # checks, tests, build, and install smoke test
26-
mise run check # format, lint, typecheck, proto and fixture drift
27-
mise run test # unit tests; UV_PYTHON=3.11 picks the interpreter
28-
mise run proto:gen # regenerate src/openshell/_proto from the pinned protos
29-
mise run core:version
36+
Before running this example, [start a gateway](https://docs.nvidia.com/openshell/latest/about/installation) or [register an existing running gateway](https://docs.nvidia.com/openshell/latest/how-it-works/gateways/overview#register-an-existing-gateway). Then select it with the CLI. The SDK reuses its endpoint, TLS configuration, and authentication state.
37+
38+
```python
39+
from openshell import Sandbox
40+
41+
with Sandbox(workspace="default") as sandbox:
42+
result = sandbox.exec(["echo", "Hello from OpenShell"])
43+
print(result.stdout, end="")
44+
if result.exit_code != 0:
45+
raise RuntimeError(result.stderr)
3046
```
3147

32-
## Core version and generated bindings
48+
`Sandbox` creates a sandbox, waits for readiness, and deletes it when the context exits. This example uses the gateway's default workload image and the `default` workspace.
3349

34-
The bindings are generated from `proto/` in NVIDIA/OpenShell at the ref in
35-
`OPENSHELL_CORE_REF` (`mise.toml`, currently `v0.1.7`) and committed under
36-
`src/openshell/_proto`. `buf export` fetches the protos, the same way sdk-go
37-
reads them, and `grpcio-tools` generates the bindings:
50+
## Usage examples
3851

39-
- Building a wheel or sdist needs neither a core checkout nor network access.
40-
- A change of the pin shows the effect on the generated API in its diff.
41-
- `mise run proto:check` fails when the committed bindings differ from the
42-
pinned protos, and `mise run conformance:check` does the same for the
43-
vendored test fixtures and `tests/e2e/Dockerfile.workload`.
52+
### Check SDK and gateway versions
4453

45-
## E2E tests
54+
Connect to the active gateway and print both versions:
4655

47-
`tests/e2e` runs against a real gateway; `mise run test` skips it. CI runs it
48-
against the published gateway of the pinned core version, with the Docker
49-
compute driver. To run it locally, you need Docker with the compose plugin:
56+
```python
57+
import openshell
58+
from openshell import SandboxClient
5059

51-
```shell
52-
mise run e2e:image
53-
scripts/e2e/start-gateway.sh "$(mise run -q core:version)" --default-image openshell/e2e-python:dev
54-
OPENSHELL_GATEWAY=e2e mise run e2e
55-
scripts/e2e/stop-gateway.sh
60+
print(f"SDK version: {openshell.__version__}")
61+
with SandboxClient.from_active_cluster() as client:
62+
print(f"Gateway version: {client.health().version}")
63+
```
64+
65+
Pass `cluster="my-gateway"` to select a registered gateway by name. For OIDC gateways, the client refreshes expiring tokens and saves the updated token bundle by default.
66+
67+
### List sandboxes
68+
69+
Sandbox operations require an explicit workspace. List methods return a lazy `Pager`, which fetches one page at a time:
70+
71+
```python
72+
from openshell import SandboxClient
73+
74+
with SandboxClient.from_active_cluster() as client:
75+
for page in client.list(workspace="default", page_size=100):
76+
for sandbox in page.items:
77+
print(sandbox.name, sandbox.id)
5678
```
5779

58-
`e2e:image` builds the sandbox image from `tests/e2e/Dockerfile.workload`, a
59-
copy of core's, with the Python version from `.python-version` and
60-
`cloudpickle`, so `Sandbox.exec_python` can run the client's callables.
80+
Use `client.list_all(workspace="default")` to collect every page into a list.
81+
82+
### Run commands in an existing sandbox
83+
84+
Use `sandbox` to attach by name. Set `delete_on_exit=False` to keep the sandbox after the context exits:
85+
86+
```python
87+
from openshell import Sandbox
88+
89+
with Sandbox(
90+
workspace="default",
91+
sandbox="my-sandbox",
92+
delete_on_exit=False,
93+
) as sandbox:
94+
result = sandbox.exec(
95+
["sh", "-c", "echo Starting; ls /tmp"],
96+
stream_output=True,
97+
timeout_seconds=30,
98+
)
99+
print(f"Exit code: {result.exit_code}")
100+
```
101+
102+
`exec()` returns an `ExecResult` with `stdout`, `stderr`, and `exit_code`. With `stream_output=True`, it also prints output as it arrives.
103+
104+
### Authenticate service automation
105+
106+
For an OIDC gateway that supports the OAuth client credentials flow, supply a renewable authentication provider:
107+
108+
```python
109+
import os
110+
111+
from openshell import ClientCredentialsAuth, SandboxClient
112+
113+
auth = ClientCredentialsAuth(
114+
issuer="https://idp.example.com/realms/openshell",
115+
client_id="openshell-service",
116+
client_secret=lambda: os.environ["OPENSHELL_OIDC_CLIENT_SECRET"],
117+
audience="openshell-gateway",
118+
)
119+
120+
with SandboxClient.from_active_cluster(client_credentials=auth) as client:
121+
print(client.health().version)
122+
```
123+
124+
Configure the issuer, client ID, and audience for your identity provider. Non-loopback gateway connections using client credentials require TLS. See [gateway authentication](https://docs.nvidia.com/openshell/latest/how-it-works/gateways/authentication) for setup.
125+
126+
## Documentation
127+
128+
- [Python SDK guide](https://docs.nvidia.com/openshell/latest/sdk/python): connections, provider credentials, and generated RPCs.
129+
- [Sandboxes](https://docs.nvidia.com/openshell/latest/how-it-works/sandboxes/overview): lifecycle, workload images, and templates.
130+
- [API errors](https://docs.nvidia.com/openshell/latest/sdk/api-errors): structured gateway errors and error handling.
131+
132+
The package includes generated gRPC bindings under `openshell._proto` for access to the underlying gateway API. `SandboxClient` is synchronous; generated stubs support synchronous and asynchronous gRPC channels.
133+
134+
## Supported core versions
135+
136+
Use SDK and gateway versions from the same OpenShell release when possible. SDK releases follow core releases: SDK `X.Y.Z` is built from core `vX.Y.Z`.
137+
138+
The generated bindings currently target core `v0.1.7`, pinned by `OPENSHELL_CORE_REF` in `mise.toml`.
139+
140+
## Contributing
141+
142+
See [CONTRIBUTING.md](https://github.com/ai-openshell/sdk-python/blob/main/CONTRIBUTING.md) for development setup, checks, end-to-end tests, and release conventions. The project uses [mise](https://mise.jdx.dev/) for tools and [uv](https://docs.astral.sh/uv/) for Python dependencies.
143+
144+
Report vulnerabilities through the [security policy](https://github.com/ai-openshell/sdk-python/blob/main/SECURITY.md).
61145

62-
`start-gateway.sh` is meant for throwaway hosts. It registers `e2e` as the
63-
active gateway, and `stop-gateway.sh` removes every sandbox container labelled
64-
with core's default namespace. Set `XDG_CONFIG_HOME` to keep your own gateway
65-
registrations apart.
146+
## Repository history
66147

67-
## History
148+
The SDK moved from NVIDIA/OpenShell to this repository. The PyPI package name, import paths, and API are unchanged, including `openshell._proto`. Earlier releases remain available on PyPI.
68149

69-
The history up to the move was imported from NVIDIA/OpenShell at `v0.1.7`.
70-
The scripts that extracted and verified it are not on `main`. They are kept at
71-
the `migration/v0.1.7` tag, in
72-
[hack/migration](https://github.com/ai-openshell/sdk-python/tree/migration/v0.1.7/hack/migration).
150+
History through core `v0.1.7` was imported from NVIDIA/OpenShell. The extraction and verification scripts are preserved under [hack/migration at the migration/v0.1.7 tag](https://github.com/ai-openshell/sdk-python/tree/migration/v0.1.7/hack/migration).
73151

74152
## License
75153

76-
Apache-2.0. See [LICENSE](LICENSE).
154+
[Apache-2.0](https://github.com/ai-openshell/sdk-python/blob/main/LICENSE).

‎pyproject.toml‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
88
[project]
99
name = "openshell"
1010
dynamic = ["version"]
11-
description = "OpenShell is the safe, private runtime for autonomous AI agents. "
11+
description = "Python SDK for OpenShell sandbox management and command execution."
1212
license = "Apache-2.0"
1313
readme = "README.md"
1414
authors = [{ name = "NVIDIA Inc." }]
@@ -21,7 +21,6 @@ dependencies = [
2121
"protobuf>=4.25",
2222
]
2323
classifiers = [
24-
"Development Status :: 3 - Alpha",
2524
"Intended Audience :: Developers",
2625
"Intended Audience :: Science/Research",
2726
"Intended Audience :: Information Technology",
@@ -36,11 +35,11 @@ classifiers = [
3635
"Operating System :: POSIX :: Linux",
3736
"Operating System :: MacOS :: MacOS X",
3837
]
39-
keywords = ["agent", "sandbox", "nvidia"]
38+
keywords = ["openshell", "sdk", "agent", "sandbox", "nvidia"]
4039

4140
[project.urls]
4241
source = "https://github.com/ai-openshell/sdk-python"
43-
documentation = "https://docs.nvidia.com/openshell/latest/"
42+
documentation = "https://docs.nvidia.com/openshell/latest/sdk/python"
4443

4544
[dependency-groups]
4645
dev = [

0 commit comments

Comments
 (0)