ElixirLLM.Tool behaviour (ElixirLLM v0.3.0)

Copy Markdown View Source

Behaviour and DSL for defining tools that can be called by LLMs.

Tools allow AI models to execute code and interact with external systems.

defmodule MyApp.Tools.Weather do
  use ElixirLLM.Tool,
    name: "get_weather",
    description: "Gets current weather for a location"

  param :latitude, :string, required: true, description: "Latitude coordinate"
  param :longitude, :string, required: true, description: "Longitude coordinate"
  param :units, :string, required: false, description: "celsius or fahrenheit"

  @impl true
  def execute(%{latitude: lat, longitude: lon} = args) do
    units = Map.get(args, :units, "celsius")
    # Fetch weather data...
    {:ok, %{temperature: 22, conditions: "sunny", units: units}}
  end
end

Inline Tool Definition

For simple cases, create tools inline:

weather_tool = ElixirLLM.Tool.define(
  name: "get_weather",
  description: "Gets current weather",
  parameters: %{
    location: [type: :string, required: true]
  },
  execute: fn %{location: loc} ->
    {:ok, "Sunny, 22°C in #{loc}"}
  end
)

Summary

Callbacks

Executes the tool with the given arguments. Arguments are passed as a map with atom keys. Return {:ok, result} or {:error, reason}.

Functions

Creates an inline tool definition.

Executes a tool (module or inline) with the given arguments.

Returns the tool description.

Returns the tool name.

Returns the tool parameters.

Defines a parameter for the tool.

Types

param_type()

@type param_type() :: :string | :integer | :number | :boolean | :array | :object

Callbacks

execute(args)

@callback execute(args :: map()) :: {:ok, term()} | {:error, term()}

Executes the tool with the given arguments. Arguments are passed as a map with atom keys. Return {:ok, result} or {:error, reason}.

Functions

define(opts)

@spec define(keyword()) :: map()

Creates an inline tool definition.

Example

tool = ElixirLLM.Tool.define(
  name: "calculator",
  description: "Performs basic math",
  parameters: %{
    expression: [type: :string, description: "Math expression", required: true]
  },
  execute: fn %{expression: expr} ->
    {:ok, 42}
  end
)

execute(tool, args)

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

Executes a tool (module or inline) with the given arguments.

get_description(tool)

@spec get_description(module() | map()) :: String.t()

Returns the tool description.

get_name(tool)

@spec get_name(module() | map()) :: String.t()

Returns the tool name.

get_parameters(tool)

@spec get_parameters(module() | map()) :: map()

Returns the tool parameters.

param(name, type, opts \\ [])

(macro)

Defines a parameter for the tool.

Options

  • :required - Whether the parameter is required (default: true)
  • :description - Description of the parameter
  • :enum - List of allowed values
  • :default - Default value

Examples

param :query, :string, required: true, description: "Search query"
param :limit, :integer, required: false, default: 10
param :format, :string, enum: ["json", "xml", "csv"]