enterprise_ai.core.transport

Source: sdks/python/src/enterprise_ai/_core/transport.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Model ClientConfig

Connection settings. Values not given fall back to EAI_* environment variables.

Fields:

Name	Type	Required	Description
base_url	str | None	no	Address of the API, trailing slash removed and validated. Env: EAI_BASE_URL, a local address by default.
api_key	str | None	no	API key sent in the X-API-Key header. Env: EAI_API_KEY.
token	str | None	no	Access token of the Hub. Write only, sealed; null keeps the stored token.
tenant	str | None	no	Tenant slug.
project	str | None	no	Identifier of the project the results are restricted to.
environment	str | None	no	Target environment sent in the X-Environment header. Env: EAI_ENVIRONMENT.
locale	str | None	no	Language of the messages, sent in Accept-Language, for example fr; resolved from the environment when not given.
timeout	float	no	Timeout of each HTTP request, in seconds. Default 30.0.
retries	int	no	Number of retries after the first attempt on a transient failure. Default 3.
backoff	float	no	Base delay in seconds of the exponential retry backoff (doubled on each attempt, plus jitter). Default 0.5.
max_backoff	float	no	Upper bound in seconds of the delay between two retries, Retry-After included. Default 20.0.
dev_user	str | None	no	User sent in X-Dev-User when no token nor API key is set and a tenant is; sdk-dev by default. Env: EAI_DEV_USER.
dev_roles	str | None	no	Roles sent in X-Dev-Roles when no token nor API key is set and a tenant is. Env: EAI_DEV_ROLES.
traceparent	str | None	no	W3C traceparent sent when no operation of enterprise_ai.telemetry sets one.
headers	dict[str, str]	no	Headers of the event, string values. The trace context is added.
ca_bundle	str | None	no	PEM bundle of extra trusted certificate authorities; verification stays on. Env: EAI_CA_BUNDLE.
dangerously_disable_tls_verification_for_localhost	bool	no	Disable TLS certificate verification; refused with ValueError unless the base URL host is local. Default False.

ClientConfig.default_headers

default_headers() -> dict[str, str]

Headers sent with every request (auth, tenancy, locale, user agent).

This element takes no parameter.

Returns: dict[str, str]. Header name to value: Accept, Accept-Language, User-Agent, then the auth, X-Dev-*, X-Project, X-Environment and custom headers.

ClientConfig.httpx_options

httpx_options() -> dict[str, Any]

TLS 1.2+ with verification on (or the explicit localhost opt out), redirects not followed.

This element takes no parameter.

Returns: dict[str, Any]. Keyword arguments for the httpx client: verify (an SSL context) and follow_redirects=False.

Model ApiResponse

Decoded body plus the response metadata (raw=True calls).

Fields:

Name	Type	Required	Description
data	Any	yes	Decoded body of the response: JSON value, text, or None for an empty answer.
status	int	yes	HTTP status code of the response, for example 200.
headers	httpx.Headers	yes	Headers of the event, string values. The trace context is added.

Attributes:

Name	Type	Required	Description
cost_estimated	str | None	yes	Estimated cost of the call, read from the x-eai-cost-estimated response header, or None.
cost_measured	str | None	yes	Measured cost of the call, read from the x-eai-cost-measured response header, or None.
decision_id	str | None	yes	Identifier of the policy decision, read from the x-eai-decision-id response header, or None.
request_id	str | None	yes	Request identifier, read from the x-request-id response header, or None.

Model Call

One prepared API call. template is the documented path template.

Fields:

Name	Type	Required	Description
method	str	yes	Name of the method, for example basic, token or none.
template	str	yes	Documented path template the call was built from, for example /v1/catalog/bricks/{id}.
path	str	yes	Path with its placeholders filled and URL encoded, relative to the base URL.
params	dict[str, Any] | None	no	Query parameters, with None values already removed, or None.
json	Any	no	Value sent as the JSON request body, or None.
files	Any	no	Files to import (1 to 200).
data	Any	no	Form fields of the request (with files, a multipart body), or None.
headers	dict[str, str]	no	Headers of the event, string values. The trace context is added.
idempotency_key	str | None	no	Value of the Idempotency-Key header; when set, the call is retried even if its method is not idempotent.
raw	bool	no	When True, the call returns an ApiResponse with the status and headers instead of the decoded body only. Default False.
content	bytes | None	no	Raw bytes sent as the request body, or None.

Class SyncTransport

Blocking transport over :class:httpx.Client.

_BaseTransport

Attributes:

Name	Type	Required	Description
http		yes	Underlying httpx.Client that sends the requests.

Constructor SyncTransport

SyncTransport(config: ClientConfig, http_client: httpx.Client | None = None, **httpx_kwargs: Any) -> None

Create the transport, building an httpx.Client from the configuration unless one is given.

Name	Type	Default	Required	Description
config	ClientConfig		yes	Connection settings (ClientConfig): base URL, credentials, timeout and retry policy.
http_client	httpx.Client | None	None	no	Existing httpx.Client to use as is; by default a new one is created with the configured base URL, timeout and TLS options.
**httpx_kwargs	Any		no	Extra options passed to httpx.Client; verify and follow_redirects=True are refused with ValueError.

SyncTransport.close

close() -> None

Close the underlying HTTP client and its connections.

This element takes no parameter.

Returns: None.

SyncTransport.paginate

paginate(method: str, template: str, args: tuple[Any, ...] = (), **kwargs: Any) -> Page

Send a listing call and return its first page as a Page.

Name	Type	Default	Required	Description
method	str		yes	HTTP method of the call, for example GET (upper cased).
template	str		yes	Documented path template, for example /v1/catalog/bricks/{id}.
args	tuple[Any, ...]	()	no	Values of the path placeholders, in order; they are URL encoded.
**kwargs	Any		no	Options of the call: params, json, files, data, content, headers, idempotent, idempotency_key, raw.

Returns: Page. A Page: First page of a {items, next_cursor} listing. Iterating follows every cursor.

SyncTransport.request

request(method: str, template: str, args: tuple[Any, ...] = (), **kwargs: Any) -> Any

Prepare and send one call, then return its decoded body.

Name	Type	Default	Required	Description
method	str		yes	HTTP method of the call, for example GET (upper cased).
template	str		yes	Documented path template, for example /v1/catalog/bricks/{id}.
args	tuple[Any, ...]	()	no	Values of the path placeholders, in order; they are URL encoded.
**kwargs	Any		no	Options of the call: params, json, files, data, content, headers, idempotent, idempotency_key, raw.

Returns: Any. Decoded body (JSON value, text or None for an empty answer), or an ApiResponse when raw=True.

SyncTransport.send

send(call: Call, stream: bool = False) -> httpx.Response

Send with retries; raises the typed error on a final failure.

Name	Type	Default	Required	Description
call	Call		yes	Prepared Call to send.
stream	bool	False	no	When True, the body is not read up front so it can be consumed as a stream. Default False.

Returns: httpx.Response. The successful httpx.Response (status below 400).

Raises: TransportError.

SyncTransport.sse

sse(method: str, template: str, args: tuple[Any, ...] = (), **kwargs: Any) -> Iterator[ServerSentEvent]

Open a Server Sent Events stream (Accept: text/event-stream) and return an iterator of its events.

Name	Type	Default	Required	Description
method	str		yes	HTTP method of the call, for example GET (upper cased).
template	str		yes	Documented path template, for example /v1/catalog/bricks/{id}.
args	tuple[Any, ...]	()	no	Values of the path placeholders, in order; they are URL encoded.
**kwargs	Any		no	Options of the call: params, json, files, data, content, headers, idempotent, idempotency_key, raw.

Returns: Iterator[ServerSentEvent]. A ServerSentEvent: One SSE event. data is the raw text; :meth:json decodes it.

Class AsyncTransport

Non blocking transport over :class:httpx.AsyncClient.

_BaseTransport

Attributes:

Name	Type	Required	Description
http		yes	Underlying httpx.AsyncClient that sends the requests.
sleep		yes	Function awaited between retries; asyncio.sleep by default, replaceable in tests.

Constructor AsyncTransport

AsyncTransport(config: ClientConfig, http_client: httpx.AsyncClient | None = None, **httpx_kwargs: Any) -> None

Create the transport, building an httpx.AsyncClient from the configuration unless one is given.

Name	Type	Default	Required	Description
config	ClientConfig		yes	Connection settings (ClientConfig): base URL, credentials, timeout and retry policy.
http_client	httpx.AsyncClient | None	None	no	Existing httpx.AsyncClient to use as is; by default a new one is created with the configured base URL, timeout and TLS options.
**httpx_kwargs	Any		no	Extra options passed to httpx.AsyncClient; verify and follow_redirects=True are refused with ValueError.

AsyncTransport.close

async close() -> None

Close the underlying HTTP client and its connections (a coroutine).

This element takes no parameter.

Returns: None.

AsyncTransport.paginate

async paginate(method: str, template: str, args: tuple[Any, ...] = (), **kwargs: Any) -> AsyncPage

Send a listing call and return its first page as an AsyncPage (a coroutine).

Name	Type	Default	Required	Description
method	str		yes	HTTP method of the call, for example GET (upper cased).
template	str		yes	Documented path template, for example /v1/catalog/bricks/{id}.
args	tuple[Any, ...]	()	no	Values of the path placeholders, in order; they are URL encoded.
**kwargs	Any		no	Options of the call: params, json, files, data, content, headers, idempotent, idempotency_key, raw.

Returns: AsyncPage. A AsyncPage: Async counterpart of :class:Page (async for item in page).

AsyncTransport.request

async request(method: str, template: str, args: tuple[Any, ...] = (), **kwargs: Any) -> Any

Prepare and send one call, then return its decoded body (a coroutine).

Name	Type	Default	Required	Description
method	str		yes	HTTP method of the call, for example GET (upper cased).
template	str		yes	Documented path template, for example /v1/catalog/bricks/{id}.
args	tuple[Any, ...]	()	no	Values of the path placeholders, in order; they are URL encoded.
**kwargs	Any		no	Options of the call: params, json, files, data, content, headers, idempotent, idempotency_key, raw.

Returns: Any. Decoded body (JSON value, text or None for an empty answer), or an ApiResponse when raw=True.

AsyncTransport.send

async send(call: Call, stream: bool = False) -> httpx.Response

Send a prepared call with retries on transient failures; raises the typed error on a final failure (a coroutine).

Name	Type	Default	Required	Description
call	Call		yes	Prepared Call to send.
stream	bool	False	no	When True, the body is not read up front so it can be consumed as a stream. Default False.

Returns: httpx.Response. The successful httpx.Response (status below 400).

Raises: TransportError.

AsyncTransport.sse

sse(method: str, template: str, args: tuple[Any, ...] = (), **kwargs: Any) -> AsyncIterator[ServerSentEvent]

Open a Server Sent Events stream (Accept: text/event-stream) and return an async iterator of its events.

Name	Type	Default	Required	Description
method	str		yes	HTTP method of the call, for example GET (upper cased).
template	str		yes	Documented path template, for example /v1/catalog/bricks/{id}.
args	tuple[Any, ...]	()	no	Values of the path placeholders, in order; they are URL encoded.
**kwargs	Any		no	Options of the call: params, json, files, data, content, headers, idempotent, idempotency_key, raw.

Returns: AsyncIterator[ServerSentEvent]. A ServerSentEvent: One SSE event. data is the raw text; :meth:json decodes it.

Class Page

First page of a {items, next_cursor} listing. Iterating follows every cursor.

Attributes:

Name	Type	Required	Description
items		yes	Elements of this page only (a list).
next_cursor		yes	Cursor of the following page, or None on the last page.
raw		yes	Decoded response body of this page, as received.

Constructor Page

Page(transport: SyncTransport, call: Call, payload: Any) -> None

Wrap the decoded payload of a listing call; the call is kept to fetch the following pages.

Name	Type	Default	Required	Description
transport	SyncTransport		yes	Transport shared by the sub-clients of one client.
call	Call		yes	Prepared Call that produced this page, reused with the cursor query parameter for the next page.
payload	Any		yes	Decoded response body: an {items, next_cursor} object, a plain list or a single value.

Page.next_page

next_page() -> Page | None

Fetch the following page, or None at the end.

This element takes no parameter.

Returns: Page \| None. A Page: First page of a {items, next_cursor} listing. Iterating follows every cursor.

Class AsyncPage

Async counterpart of :class:Page (async for item in page).

Attributes:

Name	Type	Required	Description
items		yes	Elements of this page only (a list).
next_cursor		yes	Cursor of the following page, or None on the last page.
raw		yes	Decoded response body of this page, as received.

Constructor AsyncPage

AsyncPage(transport: AsyncTransport, call: Call, payload: Any) -> None

Wrap the decoded payload of a listing call; the call is kept to fetch the following pages.

Name	Type	Default	Required	Description
transport	AsyncTransport		yes	Transport shared by the sub-clients of one client.
call	Call		yes	Prepared Call that produced this page, reused with the cursor query parameter for the next page.
payload	Any		yes	Decoded response body: an {items, next_cursor} object, a plain list or a single value.

AsyncPage.next_page

async next_page() -> AsyncPage | None

Fetch the following page, or return None at the end of the listing.

This element takes no parameter.

Returns: AsyncPage \| None. A AsyncPage: Async counterpart of :class:Page (async for item in page).

Class Resource

Base of every sub-client. Methods map 1:1 to documented API paths.

Constructor Resource

Resource(transport: SyncTransport | AsyncTransport, client: Any = None) -> None

Bind the sub-client to a sync or async transport and, optionally, to its parent client.

Name	Type	Default	Required	Description
transport	SyncTransport | AsyncTransport		yes	Transport shared by the sub-clients of one client.
client	Any	None	no	Parent client.

Functions

new_traceparent

new_traceparent() -> str

Generate a fresh sampled W3C traceparent.

This element takes no parameter.

Returns: str. A traceparent string 00-<32 hex trace id>-<16 hex span id>-01.

expand_path

expand_path(template: str, args: tuple[Any, ...]) -> str

Fill {placeholders} of template in order with URL encoded args.

Name	Type	Default	Required	Description
template	str		yes	Path template with {name} placeholders, for example /v1/catalog/bricks/{id}.
args	tuple[Any, ...]		yes	Values of the placeholders, in order; a missing or extra value raises ValueError.

Returns: str. The filled path, each value URL encoded with no safe character.

Raises: ValueError.

retry_delay

retry_delay(attempt: int, response: httpx.Response | None, backoff: float, max_backoff: float) -> float

Delay before retry attempt (0 based), honoring Retry-After (seconds or HTTP date).

Name	Type	Default	Required	Description
attempt	int		yes	Index of the retry, starting at 0; the backoff doubles on each one.
response	httpx.Response | None		yes	Failed response whose Retry-After header is honored, or None after a network error.
backoff	float		yes	Base delay in seconds of the exponential backoff.
max_backoff	float		yes	Upper bound of the returned delay, in seconds.

Returns: float. Delay in seconds: Retry-After capped at max_backoff, otherwise backoff * 2**attempt plus up to half of it as jitter, capped.

then

then(result: Any, fn: Callable[[Any], Any]) -> Any

Apply fn to a sync result, or chain it after an awaitable one (async client).

Name	Type	Default	Required	Description
result	Any		yes	Value returned by a sync call, or a coroutine or future returned by an async call.
fn	Callable[[Any], Any]		yes	Function applied to the resolved result.

Returns: Any. fn(result) directly, or a coroutine that awaits result and then applies fn.

body

body(**fields: Any) -> dict[str, Any]

Build a JSON body, dropping None values and merging an extra dict.

Name	Type	Default	Required	Description
**fields	Any		no	Fields of the body as keyword arguments; None values are dropped and the extra dict is merged last.

Returns: dict[str, Any]. The JSON body as a dict.