The OpenAI client (Effect's OpenAiClient): the Responses API,
embeddings and decisions over the HttpClient service, and the
Responses API's WebSocket mode.
layer(api_key=...) provides OpenAiClient; requests go to
api_url (https://api.openai.com/v1) with the key as a bearer token
and the optional openai-organization / openai-project headers,
which errors and spans show redacted::
client = yield from OpenAiClient()
body, response = yield from client.create_response({"model": "gpt-5", "input": "Hi"})Every failure is an AiError. create_response_stream streams the
response's events until response.completed, response.incomplete or
response.failed; an event of a type this library does not read
arrives as it came.
with_web_socket_mode (or layer_web_socket_mode) sends response
streams over one WebSocket connection to /responses instead, one
request at a time; it needs a WebSocketConstructor that sends headers
(pyfect.socket.ws). A connection left mid-response, or that answers an
error event, is replaced for the next request.
Re-exports#
- From
pyfect.ai.ai_error:AiError
Values#
| Attribute | Type | Description |
|---|---|---|
CreateResponse | type[CreateResponse] | |
CreateEmbeddingRequest | type[CreateEmbeddingRequest] | |
CreateDecisionsRequest | type[CreateDecisionsRequest] | |
Response | type[Response] | |
ResponseStreamEvent | TypeAliasType | |
with_web_socket_mode | _ProvideLocal[OpenAiSocket | ResponseIdTracker, Never, OpenAiClient | WebSocketConstructor] | Run an effect with its response streams over WebSocket mode; the
connection closes when it ends (Effect's |
DEFAULT_API_URL | Literal['https://api.openai.com/v1'] = 'https://api.openai.com/v1' |
Types#
| Type | Definition | Description |
|---|---|---|
ResponseStream | type ResponseStream = tuple[HttpClientResponse, Stream[W.ResponseStreamEvent, AiError]] |
Classes#
Functions#
make#
make(*, api_key=None, api_url=None, organization_id=None, project_id=None, transform_client=None, max_response_bytes=None) -> Effect[Service, Never, HttpClient]A client over the HttpClient service. transform_client
changes the underlying client, before a provided OpenAiConfig's
transform. A response body larger than max_response_bytes
(256 MiB) fails the call.
| Parameter | Type | Description |
|---|---|---|
api_key | Redacted[str] | None = None | |
api_url | str | None = None | |
organization_id | Redacted[str] | None = None | |
project_id | Redacted[str] | None = None | |
transform_client | ClientTransform | None = None | |
max_response_bytes | byte_size.Input | None = None |
Returns Effect[Service, Never, HttpClient]
def make(
*,
api_key: Redacted[str] | None = None,
api_url: str | None = None,
organization_id: Redacted[str] | None = None,
project_id: Redacted[str] | None = None,
transform_client: ClientTransform | None = None,
max_response_bytes: byte_size.Input | None = None,
) -> Effect[Service, Never, HttpClient]:
"""A client over the ``HttpClient`` service. ``transform_client``
changes the underlying client, before a provided ``OpenAiConfig``'s
transform. A response body larger than ``max_response_bytes``
(256 MiB) fails the call."""
limit = P.response_limit(max_response_bytes)
prepare = prepare_requests(api_key, api_url, organization_id, project_id)
def build(base: HttpClientService[HttpClientError]) -> Service:
mapped = base.map_request(prepare).filter_status_ok()
http_client = mapped if transform_client is None else transform_client(mapped)
limited = P.limit_responses(http_client, limit)
def send(path: str, payload: object) -> Effect[HttpClientResponse, HttpClientError]:
request = http_request.post(path).body_json_unsafe(payload)
return P.resolve_client(OpenAiConfig, limited).flat_map(
lambda client: client.execute(request)
)
def create_response(
payload: W.CreateResponse,
) -> Effect[tuple[W.Response, HttpClientResponse], AiError]:
sent: Effect[Any, Any] = send("/responses", payload).flat_map(
lambda response: response.json.flat_map(W.decode_response).map(
lambda body: (body, response)
)
)
return sent.catch_all(ERRORS.catch("createResponse")).pipe(_redacted)
def over_http(payload: W.CreateResponse) -> Effect[ResponseStream, AiError]:
body = {**payload, "stream": True}
sent: Effect[Any, Any] = send("/responses", body).map(
lambda response: (response, _events(response))
)
return sent.catch_all(ERRORS.catch("createResponseStream")).pipe(_redacted)
def create_response_stream(payload: W.CreateResponse) -> Effect[ResponseStream, AiError]:
return fx.service_option(OpenAiSocket).flat_map(
lambda socket: (
over_http(payload)
if socket is None
else socket.value.create_response_stream(payload)
)
)
def post_json[T](
path: str, decode: Callable[[object], Effect[T, Any]], method: str
) -> Callable[[Any], Effect[T, AiError]]:
def call(payload: Any) -> Effect[T, AiError]:
sent: Effect[Any, Any] = send(path, payload).flat_map(
lambda response: response.json.flat_map(decode)
)
return sent.catch_all(ERRORS.catch(method)).pipe(_redacted)
return call
return Service(
http_client,
create_response,
create_response_stream,
post_json("/embeddings", W.decode_embedding, "createEmbedding"),
post_json("/decisions", W.decode_decisions, "createDecisions"),
limit,
)
return HttpClient().map(build).pipe(_redacted)layer#
layer(*, api_key=None, api_url=None, organization_id=None, project_id=None, transform_client=None, max_response_bytes=None) -> L.Layer[OpenAiClient, Never, HttpClient]OpenAiClient from these options (see make).
| Parameter | Type | Description |
|---|---|---|
api_key | Redacted[str] | None = None | |
api_url | str | None = None | |
organization_id | Redacted[str] | None = None | |
project_id | Redacted[str] | None = None | |
transform_client | ClientTransform | None = None | |
max_response_bytes | byte_size.Input | None = None |
Returns L.Layer[OpenAiClient, Never, HttpClient]
def layer(
*,
api_key: Redacted[str] | None = None,
api_url: str | None = None,
organization_id: Redacted[str] | None = None,
project_id: Redacted[str] | None = None,
transform_client: ClientTransform | None = None,
max_response_bytes: byte_size.Input | None = None,
) -> L.Layer[OpenAiClient, Never, HttpClient]:
"""``OpenAiClient`` from these options (see ``make``)."""
return L.effect(
OpenAiClient,
make(
api_key=api_key,
api_url=api_url,
organization_id=organization_id,
project_id=project_id,
transform_client=transform_client,
max_response_bytes=max_response_bytes,
),
)layer_config#
layer_config(*, api_key=None, api_url=None, organization_id=None, project_id=None, transform_client=None, max_response_bytes=None) -> L.Layer[OpenAiClient, ConfigError, HttpClient]OpenAiClient with the given options read from Config.
| Parameter | Type | Description |
|---|---|---|
api_key | Config[Redacted[str]] | Config[Redacted[str] | None] | None = None | |
api_url | Config[str] | None = None | |
organization_id | Config[Redacted[str]] | Config[Redacted[str] | None] | None = None | |
project_id | Config[Redacted[str]] | Config[Redacted[str] | None] | None = None | |
transform_client | ClientTransform | None = None | |
max_response_bytes | byte_size.Input | None = None |
Returns L.Layer[OpenAiClient, ConfigError, HttpClient]
def layer_config(
*,
api_key: Config[Redacted[str]] | Config[Redacted[str] | None] | None = None,
api_url: Config[str] | None = None,
organization_id: Config[Redacted[str]] | Config[Redacted[str] | None] | None = None,
project_id: Config[Redacted[str]] | Config[Redacted[str] | None] | None = None,
transform_client: ClientTransform | None = None,
max_response_bytes: byte_size.Input | None = None,
) -> L.Layer[OpenAiClient, ConfigError, HttpClient]:
"""``OpenAiClient`` with the given options read from ``Config``."""
built: Effect[Service, ConfigError, HttpClient] = fx.all(
P.optional_config(api_key),
P.optional_config(api_url),
P.optional_config(organization_id),
P.optional_config(project_id),
).flat_map(
lambda values: make(
api_key=values[0],
api_url=values[1],
organization_id=values[2],
project_id=values[3],
transform_client=transform_client,
max_response_bytes=max_response_bytes,
)
)
return L.effect(OpenAiClient, built)layer_web_socket_mode#
layer_web_socket_mode() -> L.Layer[_SocketServices, Never, OpenAiClient | WebSocketConstructor]WebSocket mode for every response stream made with this layer: one
connection at a time, reopened when it closes, with the response id
tracker it clears. Needs a WebSocketConstructor that sends headers.
Returns L.Layer[_SocketServices, Never, OpenAiClient | WebSocketConstructor]
def layer_web_socket_mode() -> L.Layer[_SocketServices, Never, OpenAiClient | WebSocketConstructor]:
"""WebSocket mode for every response stream made with this layer: one
connection at a time, reopened when it closes, with the response id
tracker it clears. Needs a ``WebSocketConstructor`` that sends headers."""
return L.effect_context(_make_socket())