ReqLLM.Tool (ReqLLM v1.0.0-rc.5)

View Source

Tool definition for AI model function calling.

Tools enable AI models to call external functions, perform actions, and retrieve information. Each tool has a name, description, parameters schema, and a callback function to execute.

Basic Usage

# Create a simple tool
{:ok, tool} = ReqLLM.Tool.new(
  name: "get_weather",
  description: "Get current weather for a location",
  parameter_schema: [
    location: [type: :string, required: true, doc: "City name"]
  ],
  callback: {WeatherService, :get_current_weather}
)

# Execute the tool
{:ok, result} = ReqLLM.Tool.execute(tool, %{location: "San Francisco"})

# Get provider-specific schema
anthropic_schema = ReqLLM.Tool.to_schema(tool, :anthropic)

Parameters Schema

Parameters are defined using NimbleOptions-compatible keyword lists:

parameter_schema: [
  location: [type: :string, required: true, doc: "City name"],
  units: [type: :string, default: "celsius", doc: "Temperature units"]
]

Callback Formats

Multiple callback formats are supported:

# Module and function (args passed as single argument)
callback: {MyModule, :my_function}

# Module, function, and additional args (prepended to input)
callback: {MyModule, :my_function, [:extra, :args]}

# Anonymous function
callback: fn args -> {:ok, "result"} end

Provider Schema Formats

Tools can be converted to provider-specific formats:

# Anthropic tool format
anthropic_schema = ReqLLM.Tool.to_schema(tool, :anthropic)

Functions

  • new/1 - Creates a new Tool from the given options
  • new!/1 - Creates a new Tool from the given options, raising on error
  • execute/2 - Executes a tool with the given input parameters
  • to_schema/2 - Converts a Tool to provider-specific schema format
  • to_json_schema/1 - Converts a Tool to JSON Schema format for LLM integration
  • valid_name?/1 - Validates a tool name for compliance with function calling standards

Summary

Types

callback()
callback_fun()
callback_mfa()
t()

A tool definition for AI model function calling

tool_opts()

Functions

execute(tool, input)

Executes a tool with the given input parameters.

new(opts)

Creates a new Tool from the given options.

new!(opts)

Creates a new Tool from the given options, raising on error.

to_json_schema(tool)

Converts a Tool to JSON Schema format for LLM integration.

to_schema(tool, provider \\ :openai)

Converts a Tool to provider-specific schema format.

valid_name?(name)

Validates a tool name for compliance with function calling standards.

Types

callback()

@type callback() :: callback_mfa() | callback_fun()

callback_fun()

@type callback_fun() :: (map() -> {:ok, term()} | {:error, term()})

callback_mfa()

@type callback_mfa() :: {module(), atom()} | {module(), atom(), list()}

t()

@type t() :: %ReqLLM.Tool{
  callback: callback(),
  compiled: term() | nil,
  description: String.t(),
  name: String.t(),
  parameter_schema: keyword(),
  strict: boolean()
}

A tool definition for AI model function calling

tool_opts()

@type tool_opts() :: [
  name: String.t(),
  description: String.t(),
  parameter_schema: keyword(),
  callback: callback()
]

Functions

execute(tool, input)

@spec execute(t(), map()) :: {:ok, term()} | {:error, term()}

Executes a tool with the given input parameters.

Validates input parameters against the tool's schema and calls the callback function. The callback is expected to return {:ok, result} or {:error, reason}.

Parameters

  • tool - Tool struct
  • input - Input parameters as map

Examples

{:ok, result} = ReqLLM.Tool.execute(tool, %{location: "San Francisco"})
#=> {:ok, %{temperature: 72, conditions: "sunny"}}

{:error, reason} = ReqLLM.Tool.execute(tool, %{invalid: "params"})
#=> {:error, %ReqLLM.Error.Validation.Error{...}}

new(opts)

@spec new(tool_opts()) :: {:ok, t()} | {:error, term()}

Creates a new Tool from the given options.

Parameters

  • opts - Tool options as keyword list

Options

  • :name - Tool name (required, must be valid identifier)
  • :description - Tool description for AI model (required)
  • :parameter_schema - Parameter schema as NimbleOptions keyword list (optional)
  • :callback - Callback function or MFA tuple (required)

Examples

{:ok, tool} = ReqLLM.Tool.new(
  name: "get_weather",
  description: "Get current weather",
  parameter_schema: [
    location: [type: :string, required: true]
  ],
  callback: {WeatherService, :get_weather}
)

new!(opts)

@spec new!(tool_opts()) :: t() | no_return()

Creates a new Tool from the given options, raising on error.

See new/1 for details.

Examples

tool = ReqLLM.Tool.new!(
  name: "get_weather",
  description: "Get current weather",
  callback: {WeatherService, :get_weather}
)

to_json_schema(tool)

@spec to_json_schema(t()) :: map()

Converts a Tool to JSON Schema format for LLM integration.

Backward compatibility function that defaults to OpenAI format. Use to_schema/2 for explicit provider selection.

Examples

json_schema = ReqLLM.Tool.to_json_schema(tool)
# Equivalent to: ReqLLM.Tool.to_schema(tool, :openai)

to_schema(tool, provider \\ :openai)

@spec to_schema(t(), atom()) :: map()

Converts a Tool to provider-specific schema format.

Returns a map containing the provider's expected tool format with tool name, description, and parameter definitions.

Parameters

  • tool - Tool struct
  • provider - Provider atom (:anthropic)

Examples

# Anthropic tool format
anthropic_schema = ReqLLM.Tool.to_schema(tool, :anthropic)
#=> %{
#     "name" => "get_weather",
#     "description" => "Get current weather",
#     "input_schema" => %{...}
#   }

valid_name?(name)

@spec valid_name?(String.t()) :: boolean()

Validates a tool name for compliance with function calling standards.

Tool names must be valid identifiers (alphanumeric + underscores, start with letter/underscore).

Examples

ReqLLM.Tool.valid_name?("get_weather")
#=> true

ReqLLM.Tool.valid_name?("123invalid")
#=> false