GitHub

API reference for client.

The Anthropic Messages API client (Effect's AnthropicClient).

layer(api_key=...) provides AnthropicClient over the HttpClient service; its requests carry the x-api-key (redacted in errors and spans) and anthropic-version headers::

client = yield from AnthropicClient()
message, response = yield from client.create_message(
    {"model": "claude-sonnet-5-5", "max_tokens": 1024, "messages": [...]}
)

Every failure is an AiError: a status maps to its reason (a 429 to a RateLimitError with its Retry-After), a malformed body to an InvalidResponseError. create_message_stream streams the events of a message until message_stop.

Re-exports

Values

AttributeTypeDescription
MessageStreamEventTypeAliasType
Messagetype[Message]
DEFAULT_API_URLLiteral['https://api.anthropic.com'] = 'https://api.anthropic.com'
DEFAULT_API_VERSIONLiteral['2023-06-01'] = '2023-06-01'

Types

TypeDefinitionDescription
Payloadtype Payload = Mapping[str, Any]

A Messages request body (Anthropic's BetaCreateMessageParams).

Classes

Functions

make

make(*, api_key=None, api_url=None, api_version=None, transform_client=None, max_response_bytes=None) -> Effect[Service, Never, HttpClient]

An Anthropic client over the HttpClient service. Requests go to api_url (https://api.anthropic.com) with api_key as x-api-key (none when omitted, for proxies) and api_version as anthropic-version (2023-06-01); transform_client changes the underlying client (and so does an AnthropicConfig, per call). A response body, or a streamed tool call's parameters, larger than max_response_bytes (256 MiB) fails the call.

ParameterTypeDescription
api_keyRedacted[str] | None = None
api_urlstr | None = None
api_versionstr | 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,
    api_version: str | None = None,
    transform_client: ClientTransform | None = None,
    max_response_bytes: byte_size.Input | None = None,
) -> Effect[Service, Never, HttpClient]:
    """An Anthropic client over the ``HttpClient`` service. Requests go to
    ``api_url`` (``https://api.anthropic.com``) with ``api_key`` as
    ``x-api-key`` (none when omitted, for proxies) and ``api_version`` as
    ``anthropic-version`` (``2023-06-01``); ``transform_client`` changes
    the underlying client (and so does an ``AnthropicConfig``, per call).
    A response body, or a streamed tool call's parameters, larger than
    ``max_response_bytes`` (256 MiB) fails the call."""
    version = or_default(api_version, DEFAULT_API_VERSION)
    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.set_header("x-api-key", redacted_value(api_key))
        return request.set_header("anthropic-version", version).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)
        generated = limited.pipe(transform_response(_gateway_check))
        client_ok = limited.filter_status_ok()

        def resolved() -> Effect[HttpClientService[HttpClientError]]:
            return P.resolve_client(AnthropicConfig, generated)

        def on_response(response: HttpClientResponse) -> Effect[Any, Any]:
            status = response.status
            if 200 <= status < 300:
                return response.json.flat_map(W.decode_message).map(lambda body: (body, response))
            if 400 <= status < 500:
                return response.json.flat_map(
                    lambda body: W.decode_error_response(body).flat_map(
                        lambda _: map_client_error(body, response, "createMessage")  # pyright: ignore[reportArgumentType]
                    )
                )
            return _unexpected_status(response)

        def create_message(
            payload: Payload, params: MessageParams | None = None
        ) -> Effect[tuple[W.Message, HttpClientResponse], AiError]:
            request = http_request.post(
                "/v1/messages?beta=true", headers=_headers(params, None)
            ).body_json_unsafe(payload)
            sent: Effect[Any, Any] = resolved().flat_map(
                lambda client: client.execute(request).flat_map(on_response)
            )
            return sent.catch_all(ERRORS.catch("createMessage")).pipe(_redacted)

        def create_message_stream(
            payload: Payload, params: MessageParams | None = None
        ) -> Effect[tuple[HttpClientResponse, Stream[W.MessageStreamEvent, AiError]], AiError]:
            body = http_body.json_unsafe({**payload, "stream": True})
            request = http_request.post(
                "/v1/messages", headers=_headers(params, version), body=body
            )
            sent: Effect[Any, Any] = client_ok.execute(request).map(
                lambda response: (response, _message_events(response))
            )
            return sent.catch_all(ERRORS.catch("createMessageStream")).pipe(_redacted)

        return Service(http_client, create_message, create_message_stream, limit)

    return HttpClient().map(build)

layer

layer(*, api_key=None, api_url=None, api_version=None, transform_client=None, max_response_bytes=None) -> L.Layer[AnthropicClient, Never, HttpClient]

AnthropicClient from these options (see make).

ParameterTypeDescription
api_keyRedacted[str] | None = None
api_urlstr | None = None
api_versionstr | None = None
transform_clientClientTransform | None = None
max_response_bytesbyte_size.Input | None = None

Returns L.Layer[AnthropicClient, Never, HttpClient]

def layer(
    *,
    api_key: Redacted[str] | None = None,
    api_url: str | None = None,
    api_version: str | None = None,
    transform_client: ClientTransform | None = None,
    max_response_bytes: byte_size.Input | None = None,
) -> L.Layer[AnthropicClient, Never, HttpClient]:
    """``AnthropicClient`` from these options (see ``make``)."""
    return L.effect(
        AnthropicClient,
        make(
            api_key=api_key,
            api_url=api_url,
            api_version=api_version,
            transform_client=transform_client,
            max_response_bytes=max_response_bytes,
        ),
    )

layer_config

layer_config(*, api_key=None, api_url=None, api_version=None, transform_client=None, max_response_bytes=None) -> L.Layer[AnthropicClient, ConfigError, HttpClient]

AnthropicClient with its options read from Config.

ParameterTypeDescription
api_keyConfig[Redacted[str]] | Config[Redacted[str] | None] | None = None
api_urlConfig[str] | None = None
api_versionConfig[str] | None = None
transform_clientClientTransform | None = None
max_response_bytesbyte_size.Input | None = None

Returns L.Layer[AnthropicClient, ConfigError, HttpClient]

def layer_config(
    *,
    api_key: Config[Redacted[str]] | Config[Redacted[str] | None] | None = None,
    api_url: Config[str] | None = None,
    api_version: Config[str] | None = None,
    transform_client: ClientTransform | None = None,
    max_response_bytes: byte_size.Input | None = None,
) -> L.Layer[AnthropicClient, ConfigError, HttpClient]:
    """``AnthropicClient`` 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(api_version)
    ).flat_map(
        lambda values: make(
            api_key=values[0],
            api_url=values[1],
            api_version=values[2],
            transform_client=transform_client,
            max_response_bytes=max_response_bytes,
        )
    )
    return L.effect(AnthropicClient, built)