HubServiceClient

Part of the Kipu Quantum Hub API SDK reference - see the landing page for installation and Python credential helpers.

HubServiceClient talks to deployed services through the service gateway. It takes a short-lived bearer token and, in Python, the async client additionally accepts async_token: Callable[[], Awaitable[str]] for async-driven refresh.

The default environment is a URL template - https://gateway.hub.kipu-quantum.com/<context>/<service>/<version> - that you must override by passing the concrete gateway URL for the service you are invoking (the placeholders are not substituted by the SDK).

All operations live under the service_api (Python) / serviceApi (TypeScript) namespace.

Authentication

The bearer token is sent as Authorization: Bearer <token>. Tokens are short-lived; the caller is responsible for rotating them before they expire. In Python, pass either a str or a Callable[[], str] to token; the async client also accepts async_token: Callable[[], Awaitable[str]] for refresh that involves async I/O. Python users can resolve tokens with the Python credential helpers and pass the value via token.

Quickstart

Start a service execution and stream its logs.

python

from qhub.api.service import HubServiceClient

service = HubServiceClient(
    base_url="https://gateway.hub.kipu-quantum.com/acme/vqe/v1",
    token="YOUR_GATEWAY_TOKEN",
)

execution = service.service_api.start_execution(
    request={"input": {"molecule": "H2"}},
)

for entry in service.service_api.get_logs(execution.id) or []:
    print(entry.timestamp, entry.severity, entry.message)

Constructor

Parameter	Required	Description
`token`	yes	Bearer token, or a callable returning one. Sent as `Authorization: Bearer <token>`.
`async_token` (Python async only)	no	Awaitable callable for async-driven token refresh; used instead of `token` on async requests when supplied.
`base_url` / `baseUrl`	yes (effectively)	Concrete gateway URL for the service; the default `environment` is a template that must be overridden.
`environment`	no	`HubServiceClientEnvironment.DEFAULT` (Python) / `HubServiceEnvironment.Default` (TypeScript) - template URL.
`headers`	no	Additional headers merged into every request.
`timeout` / `timeoutInSeconds`	no	Read timeout in seconds; defaults to 60 when no custom HTTP client is supplied.
`max_retries` / `maxRetries`	no	Number of retries for transient failures; defaults to 2.
`follow_redirects`	no (Python only)	Passed through to `httpx.Client`; defaults to `True`.
`httpx_client` / `fetch`	no	Inject a preconfigured HTTP client (Python) or `fetch` implementation (TypeScript).
`logging`	no	Logger instance or `{level, logger, silent}` config dict.

Python also ships AsyncHubServiceClient with the same shape plus an httpx.AsyncClient hook and the async_token callable.

Behaviour

The default environment is an un-substituted template, so base_url / baseUrl is effectively required - see Endpoints.
base_url / baseUrl always wins over environment.
async_token exists only on AsyncHubServiceClient; when supplied it is used instead of the synchronous token for async requests.
max_retries applies to transient failures (network errors and 5xx responses); per-request overrides in request_options (Python) or per-call options (TypeScript) take precedence.

Service Execution lifecycle

PENDING ──► RUNNING ──► SUCCEEDED
    │          │
    │          ├──► FAILED
    │          └──► CANCELLED
    └──► CANCELLED

UNKNOWN covers states the server has not yet resolved. Terminal states are SUCCEEDED, FAILED, and CANCELLED.

Operations

All methods live under the service_api (Python) / serviceApi (TypeScript) namespace.

Method	Description
`service_api.get_service_executions()`	List executions started through this gateway.
`service_api.start_execution(request=body)`	Start a new execution; body is a JSON `dict` (reserved keys below).
`service_api.get_status(id)`	Lightweight `ServiceExecution` snapshot.
`service_api.get_result(id)`	Result response (HAL-style: `_links` + `_embedded`).
`service_api.get_result_file(id, file)`	Download a single result file as a byte stream.
`service_api.get_logs(id)`	Chronological list of log entries (oldest first).
`service_api.cancel_execution(id)`	Request cancellation of a pending or running execution.

TypeScript exposes the same methods in camelCase (serviceApi.getServiceExecutions(), serviceApi.startExecution({ ... }), serviceApi.getStatus(id), serviceApi.getResult(id), serviceApi.getResultFile(id, file), serviceApi.getLogs(id), serviceApi.cancelExecution(id)).

get_service_executions

List every service execution started through this gateway.

This method takes no arguments beyond per-request options.

python

executions = service.service_api.get_service_executions()
for execution in executions:
    print(execution.id, execution.status)

Returns List[ServiceExecution] / ServiceExecution[] - see ServiceExecution.

start_execution

Start a service execution, processed asynchronously. The returned ServiceExecution starts non-terminal; poll get_status until it reaches a terminal state, then read the result with get_result.

Parameter	Required	Type	Default	Description
`request`	yes	`RequestBody` (`Dict[str, Any]` / `Record<string, any>`)	—	Free-form JSON body; two keys are reserved (see Reserved request keys).

In Python request is keyword-only; in TypeScript the body is passed as the first positional argument.

python

execution = service.service_api.start_execution(
    request={
        "input": {"molecule": "H2", "basis": "sto-3g"},
        "tags": ["demo"],
    },
)
print(execution.id, execution.status)

Returns ServiceExecution - see ServiceExecution.

get_status

Lightweight snapshot of a single execution's lifecycle state.

Parameter	Required	Type	Default	Description
`id`	yes	`str` / `string`	—	The id of a service execution.

python

execution = service.service_api.get_status(execution_id)
print(execution.status)

Returns ServiceExecution; inspect its status (a ServiceExecutionStatus) against the lifecycle.

get_result

Retrieve the result of a service execution as a HAL envelope. The response carries _embedded.status (a full ServiceExecution) and _links.status (a HalLink pointing back at the status resource); individual result files are downloaded with get_result_file.

Parameter	Required	Type	Default	Description
`id`	yes	`str` / `string`	—	The id of a service execution.

python

result = service.service_api.get_result(execution_id)
if result.embedded and result.embedded.status:
    print(result.embedded.status.status)

Returns ResultResponse - see ResultResponse.

get_result_file

Download a single named result file as a byte stream. Use this for large outputs rather than parsing the full result into memory.

Parameter	Required	Type	Default	Description
`id`	yes	`str` / `string`	—	The id of a service execution.
`file`	yes	`str` / `string`	—	The name of the result file.

python

with open("result.bin", "wb") as out:
    for chunk in service.service_api.get_result_file(execution_id, "result.bin"):
        out.write(chunk)

Returns Iterator[bytes] (Python; AsyncIterator[bytes] on the async client) / BinaryResponse (TypeScript).

get_logs

Chronological list of log entries for an execution, oldest first.

Parameter	Required	Type	Default	Description
`id`	yes	`str` / `string`	—	The id of a service execution.

python

for entry in service.service_api.get_logs(execution_id) or []:
    print(entry.timestamp, entry.severity, entry.message)

Returns Optional[List[LogEntry]] / LogEntry[] | null | undefined - see LogEntry. Each entry's severity is a LogEntrySeverity; the response may be absent when no logs have been emitted yet.

cancel_execution

Request cancellation of a pending or running execution.

Parameter	Required	Type	Default	Description
`id`	yes	`str` / `string`	—	The id of a service execution.

python

service.service_api.cancel_execution(execution_id)

No body returned.

Reserved request keys

start_execution takes a free-form JSON body, but two top-level keys are reserved by the gateway:

input - the service-specific payload; every deployed service expects this shape.
inputDataRefs - references to mounted data-pool files, used when the input is too large to inline or lives in a shared data pool.

Everything else in the body is forwarded verbatim to the service.

Advanced usage

Polling for completion

python

import time

TERMINAL = {"SUCCEEDED", "FAILED", "CANCELLED"}

def wait(execution_id: str, poll_interval: float = 2.0) -> str:
    while True:
        status = service.service_api.get_status(execution_id).status
        if status in TERMINAL:
            return status
        time.sleep(poll_interval)

final = wait(execution.id)
if final == "SUCCEEDED":
    result = service.service_api.get_result(execution.id)

Streaming a result file

Large result files are better consumed as a byte stream than loaded whole.

python

with open("result.json", "wb") as out:
    for chunk in service.service_api.get_result_file(execution.id, "result.json"):
        out.write(chunk)

Endpoints

Default base URL	Override
`https://gateway.hub.kipu-quantum.com/<context>/<service>/<version>`	Always override - the template placeholders are not substituted by the SDK; pass the full concrete URL via `base_url` / `baseUrl`.

Errors

Service gateway responses do not surface per-status typed exceptions. All Python errors extend ApiError (in qhub.api.service.core.api_error); all TypeScript errors extend HubServiceError.

Other failure modes:

Auth misconfiguration (TypeScript) - constructing HubServiceClient without token throws HubServiceError with message "Please provide 'token' when initializing the client".
Timeouts - hitting timeoutInSeconds raises HubServiceTimeoutError in TypeScript; in Python, timeouts surface as the underlying httpx.TimeoutException.
Missing base URL - because the default environment is an un-substituted template, calling any method without providing a concrete base_url / baseUrl will produce a 404 (or DNS) failure against the literal URL https://gateway.hub.kipu-quantum.com/<context>/<service>/<version>. In Python, omitting both base_url and environment raises Exception("Please pass in either base_url or environment to construct the client").

All HTTP error instances expose status_code, headers, and body (Python) / statusCode, rawResponse, and body (TypeScript).

Reference

ServiceExecution

Field	Python / wire name	Type	Description
id	`id`	`str`	Service execution identifier.
created_at	`created_at` / `createdAt`	`str`	When the execution was created.
started_at	`started_at` / `startedAt`	`str?`	When processing started.
ended_at	`ended_at` / `endedAt`	`str?`	When processing ended.
status	`status`	`ServiceExecutionStatus`	See lifecycle.
type	`type`	`ServiceExecutionType?`	`MANAGED` or `WORKFLOW`.
service_id	`service_id` / `serviceId`	`str?`	Catalog service this run belongs to.
service_definition_id	`service_definition_id` / `serviceDefinitionId`	`str?`	Service definition (version).
application_id	`application_id` / `applicationId`	`str?`	Application that invoked the service.
tags	`tags`	`List[str]?`	Free-form tags.

ResultResponse

HAL envelope returned by get_result. Unknown top-level keys are preserved in both languages.

Field	Python / wire name	Type	Description
embedded	`embedded` / `_embedded`	`ResultResponseEmbedded?`	`status` holds a full ServiceExecution.
links	`links` / `_links`	`ResultResponseLinks?`	`status` holds a `HalLink` to the status resource.

HalLink fields: href (str, required), and optional templated (bool?), type (str?), deprecation (str?), name (str?), profile (str?), title (str?), hreflang (str?).

LogEntry

Field	Python / wire name	Type	Description
message	`message`	`str`	Log message content.
severity	`severity`	`LogEntrySeverity?`	One of `DEBUG`, `NOTICE`, `INFO`, `WARNING`, `ERROR`.
timestamp	`timestamp`	`datetime` / `string`	When the entry was logged; a `datetime` in Python, a `string` in TypeScript.

RequestBody

The body accepted by start_execution. A free-form JSON object: Dict[str, Any] (Python) / Record<string, any> (TypeScript). See Reserved request keys for the two top-level keys the gateway interprets.

Enums

ServiceExecutionStatus - UNKNOWN | PENDING | RUNNING | SUCCEEDED | CANCELLED | FAILED
ServiceExecutionType - MANAGED | WORKFLOW
LogEntrySeverity - DEBUG | NOTICE | INFO | WARNING | ERROR

Field casing

Service-API DTOs use snake_case in Python and camelCase in TypeScript for most fields, but preserve the HAL wire names (_links, _embedded) on ResultResponse in both languages.

HubServiceClient ​

Authentication ​

Quickstart ​

Constructor ​

Behaviour ​

Service Execution lifecycle ​

Operations ​

get_service_executions ​

start_execution ​

get_status ​

get_result ​

get_result_file ​

get_logs ​

cancel_execution ​

Reserved request keys ​

Advanced usage ​

Polling for completion ​

Streaming a result file ​

Endpoints ​

Errors ​

Reference ​

ServiceExecution ​

ResultResponse ​

LogEntry ​

RequestBody ​

Enums ​

Field casing ​

HubServiceClient

Authentication

Quickstart

Constructor

Behaviour

Service Execution lifecycle

Operations

get_service_executions

start_execution

get_status

get_result

get_result_file

get_logs

cancel_execution

Reserved request keys

Advanced usage

Polling for completion

Streaming a result file

Endpoints

Errors

Reference

ServiceExecution

ResultResponse

LogEntry

RequestBody

Enums

Field casing