Mojentic.LLM.Gateway behaviour (Mojentic v1.2.0)

Behaviour for LLM gateway implementations.

A gateway handles communication with a specific LLM provider, converting between the universal message format and the provider-specific API.

Examples

Implementing a custom gateway:

defmodule MyGateway do
  @behaviour Mojentic.LLM.Gateway

  @impl true
  def complete(model, messages, tools, config) do
    # Implementation here
    {:ok, %GatewayResponse{content: "response"}}
  end

  @impl true
  def complete_object(model, messages, schema, config) do
    # Implementation here
    {:ok, %GatewayResponse{object: %{}}}
  end

  @impl true
  def get_available_models do
    {:ok, ["model1", "model2"]}
  end

  @impl true
  def calculate_embeddings(text, model) do
    {:ok, [0.1, 0.2, 0.3]}
  end
end

Summary

Types

error()

gateway()

Callbacks

calculate_embeddings(text, model)

Calculates embeddings for the given text.

complete(model, messages, tools, config)

Completes an LLM request with text response.

complete_object(model, messages, schema, config)

Completes an LLM request with structured object response.

complete_stream(model, messages, tools, config)

Streams LLM responses chunk by chunk.

get_available_models()

Gets list of available models from the provider.

Types

error()

@type error() :: {:error, atom() | String.t() | {atom(), term()}}

gateway()

@type gateway() :: module()

Callbacks

calculate_embeddings(text, model)

@callback calculate_embeddings(
  text :: String.t(),
  model :: String.t() | nil
) :: {:ok, [float()]} | error()

Calculates embeddings for the given text.

Parameters

text: Text to generate embeddings for
model: Optional model identifier for embeddings

Returns

{:ok, embeddings} vector of floats
{:error, reason} on failure

complete(model, messages, tools, config)

@callback complete(
  model :: String.t(),
  messages :: [Mojentic.LLM.Message.t()],
  tools :: [module()] | nil,
  config :: Mojentic.LLM.CompletionConfig.t()
) :: {:ok, Mojentic.LLM.GatewayResponse.t()} | error()

Completes an LLM request with text response.

Parameters

model: Model identifier (e.g., "gpt-4", "qwen3:32b")
messages: List of conversation messages
tools: Optional list of available tool modules
config: Completion configuration

Returns

{:ok, response} on success
{:error, reason} on failure

complete_object(model, messages, schema, config)

@callback complete_object(
  model :: String.t(),
  messages :: [Mojentic.LLM.Message.t()],
  schema :: map(),
  config :: Mojentic.LLM.CompletionConfig.t()
) :: {:ok, Mojentic.LLM.GatewayResponse.t()} | error()

Completes an LLM request with structured object response.

The response will be parsed into a map based on the provided schema.

Parameters

model: Model identifier
messages: List of conversation messages
schema: JSON schema defining the expected structure
config: Completion configuration

Returns

{:ok, response} with parsed object on success
{:error, reason} on failure

complete_stream(model, messages, tools, config)

@callback complete_stream(
  model :: String.t(),
  messages :: [Mojentic.LLM.Message.t()],
  tools :: [module()] | nil,
  config :: Mojentic.LLM.CompletionConfig.t()
) :: Enumerable.t()

Streams LLM responses chunk by chunk.

Returns a stream that yields response chunks as they arrive. Tool calls will be accumulated and yielded when complete.

Parameters

model: Model identifier
messages: List of conversation messages
tools: Optional list of available tool modules
config: Completion configuration

Returns

A stream of {:content, chunk} or {:tool_calls, calls} tuples

get_available_models()

@callback get_available_models() :: {:ok, [String.t()]} | error()

Gets list of available models from the provider.

Returns

{:ok, models} list of model names
{:error, reason} on failure