Metadata-Version: 2.4
Name: gitpod-sdk
Version: 1.2.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/0ced4c3bd0a417f5ac8e4a4827047915543e4fd8
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: connectrpc==0.11.1
Requires-Dist: protobuf<6,>=5.29.3
Dynamic: license-file

# Ona Python SDK

The public Python SDK exposes stable workflows from `ona_sdk`. For lower-level access, generated protobuf modules are available under `gitpod.*` and generated Connect service clients are available from `client.services`.

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

Run a Codex task in a repository with one call:

```python
from gitpod.v1 import agent_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
run = ona.run_codex(
    repository_url="https://github.com/gitpod-io/template-golang-cli",
    task="Inspect the repository and improve its README.",
    model=agent_pb2.CODEX_OPEN_AI_MODEL_GPT_5_6_SOL,
    reasoning_effort=agent_pb2.CODEX_REASONING_EFFORT_HIGH,
)

for chunk in run.message_stream():
    print(chunk, end="")
result = run.watch_result()
run.delete_environment(force=True)
```

Omit `repository_url` for an empty scratch workspace. The message stream is live-only, and the caller must explicitly stop or delete the created environment.

```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` and falls back to `GITPOD_API_KEY`. If both are set, `ONA_API_KEY` takes precedence. 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.

Use `client.services` when an operation is not covered by a high-level workflow:

```python
from gitpod.v1.environment_pb2 import ListEnvironmentsRequest
from ona_sdk import create_client_from_env

client = create_client_from_env()
response = client.services.environment.list_environments(
    ListEnvironmentsRequest(),
)
```

The generated clients include every RPC in the public protobuf API and inherit the SDK's authentication, base URL, user agent, and default timeout. Direct calls raise `connectrpc.errors.ConnectError`; high-level workflows continue to raise the SDK error types documented below.

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.services` provides typed, direct access to public API services.
- `client.environments()` returns environment workflows.
- `client.run_codex()` creates a workspace and starts an initial Codex task in one call.
- `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/`.

High-level workflows and direct API access use the official Connect Python runtime and generated clients. Supervisor environment-ops calls use a small private Connect transport because generated supervisor service clients are not available. The package does not ship generated gRPC clients.
