View Source Anthropic (anthropic_community v0.3.0)
Provides an unofficial Elixir wrapper for the Anthropic API, facilitating access to the Claude LLM model. This module handles configuration, request preparation, and communication with the API, offering an idiomatic Elixir interface to the Anthropic AI capabilities.
Key Features
- Configuration Management: Centralizes settings for the Anthropic API, such as model specifications, API keys, and request parameters, ensuring a consistent request configuration.
- Message Handling: Supports adding various types of messages to the request, including text and image content, enhancing interaction with the Anthropic AI.
- Error Handling: Implements comprehensive error handling for both request generation and response parsing, providing clear feedback on failures.
- Telemetry Integration: Integrates with Elixir's
:telemetry
library to emit events for key operations, enabling monitoring and observability.
Usage
Start by configuring the API settings, then use the provided functions to add messages or images to your request. Finally, send the request to the Anthropic API and handle the response:
config = Anthropic.new(api_key: "your_api_key")
request = Anthropic.add_user_message(config, "Hello, Anthropic!")
Anthropic.request_next_message(request)
Telemetry
This module emits several :telemetry
events to help monitor its operations, which can be observed for logging, metrics, or operational insights.
Events
[:anthropic, :request_next_message, :start]
- Emitted at the beginning of a request to the Anthropic API.[:anthropic, :request_next_message, :stop]
- Emitted after a request to the Anthropic API successfully completes.[:anthropic, :request_next_message, :exception]
- Emitted if an exception occurs during a request to the Anthropic API.
Metrics
Each telemetry event includes metadata with the following fields:
:model
- The model specified in the request.:max_tokens
- The maximum number of tokens allowed in the response.
In addition, the :stop
event includes metrics on:
:input_tokens
- The number of tokens in the request.:output_tokens
- The number of tokens in the API response.
Errors are captured with their specific types, aiding in debugging and monitoring of the integration's health.
Summary
Functions
Adds a assistant message to the request.
Adds an image message to the request.
Adds a message to the request with a specified role.
Adds a system message to the request.
Adds a user message to the request.
Initializes a new Anthropic.Config
struct with the given options, merging them with the default configuration.
Sends the current request to the Anthropic API and awaits the next message in the conversation.
Types
@type role() :: :user | :assistant
Functions
@spec add_assistant_message(Anthropic.Messages.Request.t(), binary()) :: Anthropic.Messages.Request.t()
Adds a assistant message to the request.
Parameters
request
: TheAnthropic.Messages.Request
struct to which the assistant message will be added.message
: The content of the assistant message.
Returns
- The updated
Anthropic.Messages.Request
struct with the assistant message added.
@spec add_image( Anthropic.Messages.Request.t(), {Anthropic.Messages.Content.Image.input_type(), binary()} ) :: Anthropic.Messages.Request.t()
Adds an image message to the request.
Processes the given image, converts it to a base64 encoded string, and adds it as a message to the request with a role of :user
.
Parameters
request
: TheAnthropic.Messages.Request
struct to which the image message will be added.image_data
: A tuple consisting of the input type and the image path or binary data. The input type should be one of:path
,:binary
, or:base64
, indicating how the image is provided.
Returns
- The updated
Anthropic.Messages.Request
struct with the image message added.
Examples
Anthropic.add_image(request, {:path, "/path/to/image.png"})
# Adds an image from a local file path
Anthropic.add_image(request, {:binary, <<binary data>>})
# Adds an image from binary data
Anthropic.add_image(request, {:base64, "base64 encoded image data"})
# Adds an image from a base64 encoded string
Errors
- Returns
{:error, reason}
if the image processing fails, wherereason
is a descriptive error message.
@spec add_message(Anthropic.Messages.Request.t(), role(), any()) :: any()
Adds a message to the request with a specified role.
Parameters
request
: TheAnthropic.Messages.Request
struct to which the message will be added.role
: The role of the message (e.g.,:user
or:assistant
).message
: The content of the message, can be a binary string, or a list of binary strings that will be treated as different messages.
Returns
- The updated
Anthropic.Messages.Request
struct with the new message added.
@spec add_system_message(Anthropic.Messages.Request.t(), binary()) :: Anthropic.Messages.Request.t()
Adds a system message to the request.
Parameters
request
: The currentAnthropic.Messages.Request
struct to which the system message will be added.message
: The system message to add, must be a binary string.
Returns
- The updated
Anthropic.Messages.Request
struct with the system message added.
Errors
- Raises
ArgumentError
if the message is not a binary string.
@spec add_user_message(Anthropic.Messages.Request.t(), binary()) :: Anthropic.Messages.Request.t()
Adds a user message to the request.
Parameters
request
: TheAnthropic.Messages.Request
struct to which the user message will be added.message
: The content of the user message, must be a binary string.
Returns
- The updated
Anthropic.Messages.Request
struct with the user message added.
@spec new(Anthropic.Config.config_options() | nil) :: Anthropic.Messages.Request.t()
Initializes a new Anthropic.Config
struct with the given options, merging them with the default configuration.
Parameters
opts
: (Optional) A keyword list of options to override the default configuration settings.
Returns
- A new
Anthropic.Messages.Request
struct populated with the merged configuration options.
Sends the current request to the Anthropic API and awaits the next message in the conversation.
This function encapsulates the process of sending the prepared request to the Anthropic API, parsing the response, and preparing the next step of the conversation based on the API's response.
Parameters
request
: TheAnthropic.Messages.Request
struct that contains the current state of the conversation.http_client_opts
: (Optional) A list of options for the HTTP client used to make the request. These options are passed directly to the HTTP client.
Returns
- On success, returns a tuple
{:ok, response_content, updated_request}
whereresponse_content
is the content of the response from the API, andupdated_request
is the updated request struct including the response message. - On failure, returns a tuple
{:error, response, request}
whereresponse
contains error information provided by the API or HTTP client.
This function is the main mechanism through which conversations are advanced, by sending user or assistant messages to the API and incorporating the API's responses into the ongoing conversation.