GitHub

API reference for client.

The client of an OpenAI-compatible Chat Completions and Embeddings API (Effect's OpenAiClient in @effect/ai-openai-compat).

layer(api_key=..., api_url=...) provides OpenAiClient over the HttpClient service; requests carry the key as a bearer token and the optional openai-organization / openai-project headers (redacted in errors and spans)::

client = yield from OpenAiClient()
completion, response = yield from client.create_response(
    {"model": "llama-3.3-70b", "messages": [{"role": "user", "content": "Hi"}]}
)

Every failure is an AiError. create_response_stream streams the completion's chunks until [DONE]; an event that is not a chunk arrives as an UnknownEvent.

Re-exports

Values

AttributeTypeDescription
ChatCompletiontype[ChatCompletion]
EmbeddingResponsetype[EmbeddingResponse]
StreamEventTypeAliasType
UnknownEventtype[UnknownEvent]
DEFAULT_API_URLLiteral['https://api.openai.com/v1'] = 'https://api.openai.com/v1'
ERRORSErrorMapper

Types

TypeDefinitionDescription
Payloadtype Payload = Mapping[str, Any]

A Chat Completions or Embeddings request body.

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. Requests go to api_url (https://api.openai.com/v1); transform_client changes the underlying client (and so does an OpenAiConfig, per call). A response body, or a streamed tool call's arguments, 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. Requests go to ``api_url``
    (``https://api.openai.com/v1``); ``transform_client`` changes the
    underlying client (and so does an ``OpenAiConfig``, per call). A
    response body, or a streamed tool call's arguments, larger than
    ``max_response_bytes`` (256 MiB) fails the call."""
    limit = P.response_limit(max_response_bytes)

    def prepare(request: http_request.HttpClientRequest) -> http_request.HttpClientRequest:
        request = request.prepend_url(or_default(api_url, DEFAULT_API_URL))
        if api_key is not None:
            request = request.bearer_token(redacted_value(api_key))
        if organization_id is not None:
            request = request.set_header("openai-organization", redacted_value(organization_id))
        if project_id is not None:
            request = request.set_header("openai-project", redacted_value(project_id))
        return request.accept_json()

    def build(base: HttpClientService[HttpClientError]) -> Service:
        mapped = base.map_request(prepare)
        http_client = mapped if transform_client is None else transform_client(mapped)
        limited = P.limit_responses(http_client, limit)

        def send(path: str, payload: Payload) -> Effect[HttpClientResponse, HttpClientError]:
            request = http_request.post(path).body_json_unsafe(payload)
            return P.resolve_client(OpenAiConfig, limited).flat_map(
                lambda client: client.filter_status_ok().execute(request)
            )

        def create_response(
            payload: Payload,
        ) -> Effect[tuple[W.ChatCompletion, HttpClientResponse], AiError]:
            sent: Effect[Any, Any] = send("/chat/completions", payload).flat_map(
                lambda response: response.json.flat_map(W.decode_completion).map(
                    lambda body: (body, response)
                )
            )
            return sent.catch_all(ERRORS.catch("createResponse")).pipe(_redacted)

        def create_response_stream(
            payload: Payload,
        ) -> Effect[tuple[HttpClientResponse, Stream[W.StreamEvent, AiError]], AiError]:
            body = {**payload, "stream": True, "stream_options": {"include_usage": True}}
            sent: Effect[Any, Any] = send("/chat/completions", body).map(
                lambda response: (response, _events(response))
            )
            return sent.catch_all(ERRORS.catch("createResponseStream")).pipe(_redacted)

        def create_embedding(payload: Payload) -> Effect[W.EmbeddingResponse, AiError]:
            sent: Effect[Any, Any] = send("/embeddings", payload).flat_map(
                lambda response: response.json.flat_map(W.decode_embedding)
            )
            return sent.catch_all(ERRORS.catch("createEmbedding")).pipe(_redacted)

        return Service(
            http_client, create_response, create_response_stream, create_embedding, limit
        )

    return HttpClient().map(build)

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