Metadata-Version: 2.4
Name: ona-sdk
Version: 0.1.0
Summary: Public Python SDK for Ona.
Author-email: Ona <support@ona.com>
License-Expression: Apache-2.0
Project-URL: Documentation, https://ona.com/docs/ona/integrations/sdk
Project-URL: Repository, https://github.com/gitpod-io/gitpod-next
Project-URL: Source Commit, https://github.com/gitpod-io/gitpod-next/commit/ecbd180689d7c2f550c15d96914a52d41b9411a1
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: protobuf<6,>=5.29.3
Dynamic: license-file

# Ona Python SDK

The public Python SDK exposes stable workflows from `ona_sdk`. Generated protobuf modules remain available under `gitpod.*` for lower-level message types, but the SDK intentionally does not expose every raw backend RPC.

Install the package with `pip install ona-sdk`.

```python
from ona_sdk import create_client_from_env

ona = create_client_from_env()
env = ona.environments().create("https://github.com/gitpod-io/template-golang-cli")

result = env.run_command(
    command="pwd && git status --short",
    working_directory=env.workspace_dir(),
)

print(result.stdout)
```

`create_client_from_env()` reads `ONA_API_KEY`. It uses `https://app.ona.com/api` by default and accepts `ONA_BASE_URL` for a custom management-plane domain, local development, or replay verification. Use `create_client(api_key=..., base_url=...)` to pass values explicitly.

Pass `new_debug_logger()` to the client to get human-readable SDK debug logs. The formatter uses ANSI colors by default and honors `NO_COLOR`; pass `no_color=True` when writing plain logs.

The SDK is structured as:

- `create_client*` creates an SDK client for production Connect API calls.
- `client.environments()` returns environment workflows.
- `environments.create/get/list/start/stop/delete` manages environments.
- `Environment.run_command/read_file/write_file/git_changes` performs environment ops.
- `Environment.start_codex` starts Codex in that environment.
- `AgentSession.send_message/message_stream/watch_result` interacts with the agent execution.

Runnable examples live in `examples/`.

The SDK uses Connect over the Python standard library HTTP stack. The package includes generated protobuf messages and type stubs, but it does not ship generated gRPC clients.
