GitHub

API reference for client.

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

Values

AttributeTypeDescription
CreateResponsetype[CreateResponse]
CreateEmbeddingRequesttype[CreateEmbeddingRequest]
CreateDecisionsRequesttype[CreateDecisionsRequest]
Responsetype[Response]
ResponseStreamEventTypeAliasType
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 withWebSocketMode). Use with .pipe: effect.pipe(client.with_web_socket_mode).

DEFAULT_API_URLLiteral['https://api.openai.com/v1'] = 'https://api.openai.com/v1'

Types

TypeDefinitionDescription
ResponseStreamtype 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.

ParameterTypeDescription
api_keyRedacted[str] | None = None
api_urlstr | None = None
organization_idRedacted[str] | None = None
project_idRedacted[str] | None = None
transform_clientClientTransform | None = None
max_response_bytesbyte_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).

ParameterTypeDescription
api_keyRedacted[str] | None = None
api_urlstr | None = None
organization_idRedacted[str] | None = None
project_idRedacted[str] | None = None
transform_clientClientTransform | None = None
max_response_bytesbyte_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.

ParameterTypeDescription
api_keyConfig[Redacted[str]] | Config[Redacted[str] | None] | None = None
api_urlConfig[str] | None = None
organization_idConfig[Redacted[str]] | Config[Redacted[str] | None] | None = None
project_idConfig[Redacted[str]] | Config[Redacted[str] | None] | None = None
transform_clientClientTransform | None = None
max_response_bytesbyte_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())