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.

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

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

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.

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.

Python reference

ServiceApi

client.service_api.get_service_executions() -> typing.List[ServiceExecution]

Description

Retrieves a list of all service executions. The response includes links to each service execution, allowing for further queries on their status and results.

Usage

from qhub.api.service import HubServiceClient
from qhub.api.service.environment import HubServiceClientEnvironment

client = HubServiceClient(
    token="<token>",
    environment=HubServiceClientEnvironment.DEFAULT,
)

client.service_api.get_service_executions()

Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.service_api.start_execution(...) -> ServiceExecution

Description

Starts a service execution, which in turn is processed asynchronously. The location header of the response contains the URL which can be used to query the status and the result of the service execution.

Usage

from qhub.api.service import HubServiceClient
from qhub.api.service.environment import HubServiceClientEnvironment

client = HubServiceClient(
    token="<token>",
    environment=HubServiceClientEnvironment.DEFAULT,
)

client.service_api.start_execution(
    request={
        "key": "value"
    },
)

Parameters

request: RequestBody

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.service_api.get_status(...) -> ServiceExecution

Description

Retrieves the status of a service execution. The status can be one of the following: UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED.

Usage

from qhub.api.service import HubServiceClient
from qhub.api.service.environment import HubServiceClientEnvironment

client = HubServiceClient(
    token="<token>",
    environment=HubServiceClientEnvironment.DEFAULT,
)

client.service_api.get_status(
    id="id",
)

Parameters

id: str — The id of a service execution

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.service_api.get_result(...) -> ResultResponse

Description

Retrieves the result of a service execution. The result is returned as a JSON object containing the status and any additional data. The result may include links to download specific result files.

Usage

from qhub.api.service import HubServiceClient
from qhub.api.service.environment import HubServiceClientEnvironment

client = HubServiceClient(
    token="<token>",
    environment=HubServiceClientEnvironment.DEFAULT,
)

client.service_api.get_result(
    id="id",
)

Parameters

id: str — The id of a service execution

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.service_api.get_result_file(...) -> typing.Iterator[bytes]

Description

Retrieves a specific result file of a service execution. The file name is provided in the path parameter. The result file is returned as a binary stream.

Usage

client.service_api.get_result_file(...)

Parameters

id: str — The id of a service execution

file: str — The name of the result file

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.service_api.get_logs(...) -> typing.Optional[typing.List[LogEntry]]

Description

Returns a list of log entries for a service execution in chronological order, where the first entry is the oldest.

Usage

from qhub.api.service import HubServiceClient
from qhub.api.service.environment import HubServiceClientEnvironment

client = HubServiceClient(
    token="<token>",
    environment=HubServiceClientEnvironment.DEFAULT,
)

client.service_api.get_logs(
    id="id",
)

Parameters

id: str — The id of a service execution

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.service_api.cancel_execution(...)

Description

Cancel a pending or running service execution.

Usage

from qhub.api.service import HubServiceClient
from qhub.api.service.environment import HubServiceClientEnvironment

client = HubServiceClient(
    token="<token>",
    environment=HubServiceClientEnvironment.DEFAULT,
)

client.service_api.cancel_execution(
    id="id",
)

Parameters

id: str — The id of a service execution

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

TypeScript reference

ServiceApi

client.serviceApi.getServiceExecutions() -> HubService.ServiceExecution[]

Description

Retrieves a list of all service executions. The response includes links to each service execution, allowing for further queries on their status and results.

Usage

await client.serviceApi.getServiceExecutions();

Parameters

requestOptions: ServiceApiClient.RequestOptions

client.serviceApi.startExecution({ ...params }) -> HubService.ServiceExecution

Description

Starts a service execution, which in turn is processed asynchronously. The location header of the response contains the URL which can be used to query the status and the result of the service execution.

Usage

await client.serviceApi.startExecution({
    "key": "value"
});

Parameters

request: HubService.RequestBody

requestOptions: ServiceApiClient.RequestOptions

client.serviceApi.getStatus(id) -> HubService.ServiceExecution

Description

Retrieves the status of a service execution. The status can be one of the following: UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED.

Usage

await client.serviceApi.getStatus("id");

Parameters

id: string — The id of a service execution

requestOptions: ServiceApiClient.RequestOptions

client.serviceApi.getResult(id) -> HubService.ResultResponse

Description

Retrieves the result of a service execution. The result is returned as a JSON object containing the status and any additional data. The result may include links to download specific result files.

Usage

await client.serviceApi.getResult("id");

Parameters

id: string — The id of a service execution

requestOptions: ServiceApiClient.RequestOptions

client.serviceApi.getLogs(id) -> (HubService.LogEntry[] | null) | undefined

Description

Returns a list of log entries for a service execution in chronological order, where the first entry is the oldest.

Usage

await client.serviceApi.getLogs("id");

Parameters

id: string — The id of a service execution

requestOptions: ServiceApiClient.RequestOptions

client.serviceApi.cancelExecution(id) -> void

Description

Cancel a pending or running service execution.

Usage

await client.serviceApi.cancelExecution("id");

Parameters

id: string — The id of a service execution

requestOptions: ServiceApiClient.RequestOptions