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#
- From
pyfect.ai.ai_error:AiError
Values#
| Attribute | Type | Description |
|---|---|---|
MessageStreamEvent | TypeAliasType | |
Message | type[Message] | |
DEFAULT_API_URL | Literal['https://api.anthropic.com'] = 'https://api.anthropic.com' | |
DEFAULT_API_VERSION | Literal['2023-06-01'] = '2023-06-01' |
Types#
| Type | Definition | Description |
|---|---|---|
Payload | type Payload = Mapping[str, Any] | A Messages request body (Anthropic's |
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.
| Parameter | Type | Description |
|---|---|---|
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 |
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).
| Parameter | Type | Description |
|---|---|---|
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 |
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.
| Parameter | Type | Description |
|---|---|---|
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 |
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)