Alchemind behaviour (Alchemind v0.1.0-rc1)
View SourceAlchemind provides a unified interface for interacting with various LLM providers.
This module defines the base behaviours and types for working with different LLM implementations in a unified way, similar to LiteLLM or LlamaIndex.
Summary
Callbacks
Completes a conversation with the LLM provider.
Completes a conversation with the LLM provider, with optional streaming.
Defines the client behaviour for LLM providers.
Converts text to speech.
Transcribes audio to text.
Functions
Completes a conversation using the specified client, with optional streaming.
Creates a new client for the specified provider.
Converts text to speech using the specified client.
Transcribes audio to text using the specified client.
Types
@type completion_choice() :: %{ :index => non_neg_integer(), :message => message(), optional(:finish_reason) => String.t() }
@type completion_response() :: %{ id: String.t(), object: String.t(), created: pos_integer(), model: String.t(), choices: [completion_choice()] }
@type completion_result() :: {:ok, completion_response()} | {:error, completion_error() | any()}
@type role() :: :system | :user | :assistant
@type stream_callback() :: (stream_delta() -> any())
Callbacks
@callback complete( client :: term(), messages :: [message()], opts :: keyword() ) :: completion_result()
Completes a conversation with the LLM provider.
Each provider module must implement this callback to handle completion requests.
@callback complete( client :: term(), messages :: [message()], callback :: stream_callback(), opts :: keyword() ) :: completion_result()
Completes a conversation with the LLM provider, with optional streaming.
Each provider module must implement this callback to handle streaming completion requests. If a callback is provided, streaming is enabled.
Defines the client behaviour for LLM providers.
Each provider must implement a client that conforms to this behaviour.
@callback speech( client :: term(), input :: String.t(), opts :: keyword() ) :: {:ok, binary()} | {:error, term()}
Converts text to speech.
Optional callback that providers can implement to support text-to-speech conversion.
@callback transcribe( client :: term(), audio_binary :: binary(), opts :: keyword() ) :: {:ok, String.t()} | {:error, term()}
Transcribes audio to text.
Optional callback that providers can implement to support audio transcription.
Functions
@spec complete(term(), [message()], stream_callback() | keyword(), keyword()) :: completion_result()
Completes a conversation using the specified client, with optional streaming.
Parameters
client
: Client created with new/2messages
: List of messages in the conversationcallback_or_opts
: Either a callback function for streaming or options for the requestopts
: Additional options for the completion request (when callback is provided)
Options
:model
- The model to use (required unless specified in the client):temperature
- Controls randomness (0.0 to 2.0):max_tokens
- Maximum number of tokens to generate
Examples
Without streaming:
iex> {:ok, client} = Alchemind.new(Alchemind.OpenAI, api_key: "sk-...")
iex> messages = [
...> %{role: :system, content: "You are a helpful assistant."},
...> %{role: :user, content: "Hello, world!"}
...> ]
iex> Alchemind.complete(client, messages, model: "gpt-4o", temperature: 0.7)
With streaming:
iex> {:ok, client} = Alchemind.new(Alchemind.OpenAI, api_key: "sk-...")
iex> messages = [
...> %{role: :system, content: "You are a helpful assistant."},
...> %{role: :user, content: "Hello, world!"}
...> ]
iex> callback = fn delta -> IO.write(delta.content) end
iex> Alchemind.complete(client, messages, callback, model: "gpt-4o", temperature: 0.7)
Returns
{:ok, response}
- Successful completion with response data{:error, reason}
- Error with reason
Creates a new client for the specified provider.
Parameters
provider
: Module implementing Alchemind provider behaviouropts
: Provider-specific options (like api_key, base_url, etc.)
Examples
iex> Alchemind.new(Alchemind.OpenAI, api_key: "sk-...")
{:ok, %Alchemind.OpenAI.Client{...}}
Returns
{:ok, client}
- Client for the specified provider{:error, reason}
- Error with reason
Converts text to speech using the specified client.
Parameters
client
: Client created with new/2input
: Text to convert to speechopts
: Options for the speech request
Options
Options are provider-specific. For OpenAI:
:model
- OpenAI text-to-speech model to use (default: "gpt-4o-mini-tts"):voice
- Voice to use (default: "alloy"):response_format
- Format of the audio (default: "mp3"):speed
- Speed of the generated audio (optional)
Examples
iex> {:ok, client} = Alchemind.new(Alchemind.OpenAI, api_key: "sk-...")
iex> Alchemind.speech(client, "Hello, world!", voice: "echo")
{:ok, <<binary audio data>>}
Returns
{:ok, audio_binary}
- Successful speech generation with audio binary{:error, reason}
- Error with reason
Transcribes audio to text using the specified client.
Parameters
client
: Client created with new/2audio_binary
: Binary audio dataopts
: Options for the transcription request
Options
Options are provider-specific. For OpenAI:
:model
- Transcription model to use (default: "whisper-1"):language
- Language of the audio (default: nil, auto-detect):prompt
- Optional text to guide the model's transcription:response_format
- Format of the transcript (default: "json"):temperature
- Controls randomness (0.0 to 1.0, default: 0)
Examples
iex> {:ok, client} = Alchemind.new(Alchemind.OpenAI, api_key: "sk-...")
iex> audio_binary = File.read!("audio.mp3")
iex> Alchemind.transcribe(client, audio_binary, language: "en")
{:ok, "This is a transcription of the audio."}
Returns
{:ok, text}
- Successful transcription with text{:error, reason}
- Error with reason