@spec answer([ALLM.Tool.t()], ALLM.ToolCall.t()) :: String.t()

Build the content string answering a tool_help call, for callers that run tool calls themselves (for example under mode: :manual). Equal to render/2 on the call's arguments, with nil arguments treated as %{}.

Pass the full tool list, including meta_tool/0.

Examples

iex> tool = ALLM.Tool.new(name: "lookup", description: "Look up a record.", schema: %{}, compact: true)
iex> call = ALLM.ToolCall.new(id: "call_1", name: "tool_help", arguments: %{"names" => ["lookup"]})
iex> ALLM.ToolHelp.answer([tool, ALLM.ToolHelp.meta_tool()], call)
"## lookup\nLook up a record.\nParameters (JSON Schema): {}"

@spec check_args(ALLM.Tool.t(), map()) :: :ok | {:error, String.t()}

Check that a compact tool's call supplies every required top-level argument.

Returns :ok for any tool that is not compact, so full tools behave exactly as they would without this check. For a compact tool, returns {:error, usage} when a name in the schema's "required" list is absent from args. usage names the missing arguments in "required" order and ends with the tool's full help (see render/2), so the model can correct its call in one round trip even if it never called tool_help. The chat loop routes this error through your on_tool_error policy like any handler error.

An argument counts as present under its string key or an existing atom of the same name. Only presence is checked: no types, no nesting, no unknown-key rejection. Never raises: non-map args count as no arguments, and a schema without a "required" list has no required arguments.

Examples

iex> tool = ALLM.Tool.new(name: "lookup", description: "Look up a record.", schema: %{"type" => "object", "properties" => %{"id" => %{"type" => "string"}}, "required" => ["id"]}, compact: true)
iex> ALLM.ToolHelp.check_args(tool, %{"id" => "42"})
:ok
iex> {:error, usage} = ALLM.ToolHelp.check_args(tool, %{})
iex> String.split(usage, "\n") |> Enum.take(3)
["missing required argument(s): id", "", "## lookup"]

@spec compact?(ALLM.Tool.t()) :: boolean()

Whether tool is compact. Only compact: true counts: any other value (including a badly-typed one from a hand-built struct or decoded JSON) means the tool is sent in full.

Examples

iex> ALLM.ToolHelp.compact?(ALLM.Tool.new(name: "t", description: "d", schema: %{}, compact: true))
true
iex> ALLM.ToolHelp.compact?(%ALLM.Tool{name: "t", description: "d", schema: %{}, compact: :yes})
false

@spec meta_tool() :: ALLM.Tool.t()

The built-in tool_help meta-tool.

Plain data with no handler, so it serializes like any other tool. It takes {"names": ["tool_name", ...]} and is answered by render/2.

Examples

iex> meta = ALLM.ToolHelp.meta_tool()
iex> {meta.name, meta.handler, meta.metadata}
{"tool_help", nil, %{"allm_builtin" => "tool_help"}}
iex> meta.schema["required"]
["names"]

@spec meta_tool?(ALLM.Tool.t()) :: boolean()

Whether tool is the built-in meta-tool, judged by its metadata marker, not its name. Never raises.

Examples

iex> ALLM.ToolHelp.meta_tool?(ALLM.ToolHelp.meta_tool())
true
iex> ALLM.ToolHelp.meta_tool?(ALLM.Tool.new(name: "tool_help", description: "mine", schema: %{}))
false

@spec project([ALLM.Tool.t()], ALLM.Request.tool_choice() | {:tool, String.t()}) :: [
  ALLM.Tool.t()
]

Project a resolved tool list into the list sent to the model.

Every compact tool is replaced by its stub, in place, and meta_tool/0 is appended when at least one compact tool is present. Non-compact tools are returned unchanged, so a list with no compact tool comes back == to the input. The result is deterministic: equal inputs give equal outputs.

When tool_choice forces a single tool by name, that tool is sent in full even if it is compact. The forced name is read from:

• a binary tool name, or {:tool, name};
• %{"type" => "tool", "name" => name} (string or atom keys);
• %{"type" => "function", "function" => %{"name" => name}} and the flat %{"type" => "function", "name" => name} (string or atom keys);
• %{"mode" => "ANY", "allowedFunctionNames" => [name]} with exactly one name (string or atom keys).

:auto, :none, :required, nil and any other shape leave every compact tool stubbed.

Examples

iex> full = ALLM.Tool.new(name: "search", description: "Search the web.", schema: %{})
iex> compact = ALLM.Tool.new(name: "lookup", description: "Look up a record. Slow.", schema: %{}, compact: true)
iex> ALLM.ToolHelp.project([full, compact], :auto) |> Enum.map(& &1.description)
["Search the web.", "Look up a record. [compact]", ALLM.ToolHelp.meta_tool().description]
iex> ALLM.ToolHelp.project([full, compact], {:tool, "lookup"}) |> Enum.map(& &1.description) |> Enum.at(1)
"Look up a record. Slow."
iex> ALLM.ToolHelp.project([full], :auto) == [full]
true

@spec render([ALLM.Tool.t()], map()) :: String.t()

Render the full help for the tools named in a tool_help call's arguments.

args is %{"names" => [name, ...]}, %{"names" => name}, or the atom-keyed equivalent. Each requested name gets one section, in request order and deduplicated, and sections are separated by a blank line. A known tool, compact or not, renders as its name, full description and compact JSON schema. An unknown name renders a note listing the compact tools ((none) when there are none). Any other args shape returns a short usage string ending in the same list. Never raises: a schema that cannot be encoded as JSON is shown with inspect/1.

Examples

iex> tool = ALLM.Tool.new(name: "lookup", description: "Look up a record.", schema: %{"type" => "object"}, compact: true)
iex> ALLM.ToolHelp.render([tool], %{"names" => ["lookup"]})
"## lookup\nLook up a record.\nParameters (JSON Schema): {\"type\":\"object\"}"
iex> ALLM.ToolHelp.render([tool], %{"names" => ["nope"]})
"## nope\nUnknown tool. Compact tools: lookup"
iex> ALLM.ToolHelp.render([tool], %{})
"tool_help expects {\"names\": [\"tool_name\", ...]}. Compact tools: lookup"