Candil.Tools (Candil v3.0.0)

Copy Markdown View Source

Tool calling for LLM responses.

Most modern LLMs (OpenAI, Anthropic, llama.cpp with --jinja / function-calling grammar) support tool calling: the model returns structured JSON instead of (or alongside) free-form text.

This module:

  1. Serialises a list of Candil.Tool.t/0 schemas into the prompt (or the API's tools parameter) — schemas_to_prompt/1.
  2. Parses the model's response into a list of %ToolCall{} structs — parse_tool_calls/1.

OpenAI-compatible wire format

%{
  "type" => "function",
  "function" => %{
    "name" => "get_weather",
    "description" => "Get the current weather",
    "parameters" => %{
      "type" => "object",
      "properties" => %{
        "city" => %{"type" => "string"}
      },
      "required" => ["city"]
    }
  }
}

Local (llama.cpp) prompt format

A <|tool_call|> style marker followed by JSON. The parser is forgiving: leading/trailing whitespace and stray markdown fences are tolerated.

Summary

Types

tool_call()
wire_schema()

Functions

parse_tool_calls(response)

Parse a model's response into a list of tool_call/0 maps.

schemas_to_prompt(tools)

Serialise a list of Candil.Tool.t/0 into OpenAI-compatible wire schemas suitable for body["tools"].

Types

tool_call()

@type tool_call() :: %{name: String.t(), args: map()}

wire_schema()

@type wire_schema() :: map()

Functions

parse_tool_calls(response)

@spec parse_tool_calls(String.t() | map()) :: {:ok, [tool_call()]} | {:error, term()}

Parse a model's response into a list of tool_call/0 maps.

Accepts either:

  • A string with <|tool_call|> (or <tool_call>) markers followed by JSON, separated by whitespace and possibly surrounded by markdown fences.
  • An OpenAI-style response map with a tool_calls array.

Returns {:ok, [tool_call()]} on success or {:error, %Candil.Error{}} if a JSON block fails to parse.

schemas_to_prompt(tools)

@spec schemas_to_prompt([Candil.Tool.t()]) :: [wire_schema()]

Serialise a list of Candil.Tool.t/0 into OpenAI-compatible wire schemas suitable for body["tools"].

Each entry is %{"type" => "function", "function" => %{...}}.