ReqLLM.ToolCall (ReqLLM v1.5.1)

View Source

Represents a single tool call from an assistant message.

This struct matches the OpenAI Chat Completions API wire format:

{
  "id": "call_abc123",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{"location":"Paris"}"
  }
}

Fields

  • id - Unique call identifier (auto-generated if nil)
  • type - Always "function" (reserved for future extensibility)
  • function - Map with name (string) and arguments (JSON string)

Examples

iex> ToolCall.new("call_abc", "get_weather", ~s({"location":"Paris"}))
%ReqLLM.ToolCall{
  id: "call_abc",
  type: "function",
  function: %{name: "get_weather", arguments: ~s({"location":"Paris"})}
}

iex> ToolCall.new(nil, "get_time", "{}")
%ReqLLM.ToolCall{
  id: "call_..." # auto-generated
  type: "function",
  function: %{name: "get_time", arguments: "{}"}
}

Summary

Types

t()

Functions

args_json(tool_call)

Extract the arguments JSON string from a ToolCall.

args_map(tool_call)

Extract and decode the arguments as a map from a ToolCall. Returns nil if decoding fails.

find_args(tool_calls, name)

Find the first tool call matching the given name and return its decoded arguments. Returns nil if no match found or if arguments cannot be decoded.

from_map(tc)

Normalize a map or ToolCall to the standard %{id, name, arguments} format.

matches_name?(tool_call, expected_name)

Check if a ToolCall matches the given function name.

name(tool_call)

Extract the function name from a ToolCall.

new(id, name, arguments_json)

Create a new ToolCall with OpenAI-compatible structure.

schema()

Returns the Zoi schema for this module

to_map(tc)

Convert a ToolCall to a flat map with decoded arguments.

Types

t()

@type t() :: %ReqLLM.ToolCall{function: map(), id: binary(), type: binary()}

Functions

args_json(tool_call)

@spec args_json(t()) :: String.t()

Extract the arguments JSON string from a ToolCall.

args_map(tool_call)

@spec args_map(t()) :: map() | nil

Extract and decode the arguments as a map from a ToolCall. Returns nil if decoding fails.

find_args(tool_calls, name)

@spec find_args([t()], String.t()) :: map() | nil

Find the first tool call matching the given name and return its decoded arguments. Returns nil if no match found or if arguments cannot be decoded.

from_map(tc)

@spec from_map(t() | map()) :: %{id: String.t(), name: String.t(), arguments: map()}

Normalize a map or ToolCall to the standard %{id, name, arguments} format.

Accepts ToolCall structs or plain maps with atom/string keys. Arguments are decoded from JSON if provided as a string.

Examples

iex> ToolCall.from_map(%{"id" => "call_123", "name" => "get_weather", "arguments" => ~s({"location":"Paris"})})
%{id: "call_123", name: "get_weather", arguments: %{"location" => "Paris"}}

iex> tc = ToolCall.new("call_456", "get_time", "{}")
iex> ToolCall.from_map(tc)
%{id: "call_456", name: "get_time", arguments: %{}}

matches_name?(tool_call, expected_name)

@spec matches_name?(t(), String.t()) :: boolean()

Check if a ToolCall matches the given function name.

name(tool_call)

@spec name(t()) :: String.t()

Extract the function name from a ToolCall.

new(id, name, arguments_json)

@spec new(String.t() | nil, String.t(), String.t()) :: t()

Create a new ToolCall with OpenAI-compatible structure.

Parameters

  • id - Unique identifier (generates "call_<uuid>" if nil)
  • name - Function name
  • arguments_json - Arguments as JSON-encoded string

Examples

ToolCall.new("call_123", "get_weather", ~s({"location":"SF"}))
ToolCall.new(nil, "get_time", "{}")

schema()

Returns the Zoi schema for this module

to_map(tc)

@spec to_map(t()) :: %{id: String.t(), name: String.t(), arguments: map()}

Convert a ToolCall to a flat map with decoded arguments.

Returns a map with :id, :name, and :arguments keys. Arguments are decoded from JSON; returns empty map if decoding fails.

Examples

iex> tc = ToolCall.new("call_123", "get_weather", ~s({"location":"Paris"}))
iex> ToolCall.to_map(tc)
%{id: "call_123", name: "get_weather", arguments: %{"location" => "Paris"}}

iex> tc = ToolCall.new("call_456", "get_time", "{}")
iex> ToolCall.to_map(tc)
%{id: "call_456", name: "get_time", arguments: %{}}