Altar.ADM.Tool (Altar v0.2.0)

View Source

Tool structure for ALTAR Data Model (ADM).

A Tool is the top-level container for AI capabilities, providing a standardized way to declare and organize function-based tools. It wraps one or more FunctionDeclaration structures.

Structure

A Tool contains:

  • function_declarations - Array of one or more FunctionDeclaration structs

Examples

# Simple tool with single function
{:ok, tool} = Tool.new(%{
  function_declarations: [
    %Altar.ADM.FunctionDeclaration{
      name: "get_weather",
      description: "Get current weather",
      parameters: %{}
    }
  ]
})

# Complex tool with multiple related functions
{:ok, tool} = Tool.new(%{
  function_declarations: [
    weather_forecast_declaration,
    weather_alerts_declaration,
    weather_history_declaration
  ]
})

JSON Serialization

Tools can be serialized to/from JSON for interchange:

{:ok, json} = Jason.encode(Tool.to_map(tool))
{:ok, tool} = Tool.from_map(Jason.decode!(json))

Summary

Types

t()

A validated Tool structure.

Functions

find_function(tool, name)

Find a function declaration by name.

from_map(arg1)

Parse tool from JSON-deserialized map.

function_names(tool)

Get a list of all function names defined in this tool.

new(attrs)

Construct a new validated Tool.

to_map(tool)

Convert tool to JSON-serializable map.

Types

t()

@type t() :: %Altar.ADM.Tool{
  function_declarations: [Altar.ADM.FunctionDeclaration.t(), ...]
}

A validated Tool structure.

Functions

find_function(tool, name)

@spec find_function(t(), String.t()) ::
  {:ok, Altar.ADM.FunctionDeclaration.t()} | {:error, :not_found}

Find a function declaration by name.

Returns {:ok, declaration} if found, {:error, :not_found} otherwise.

Examples

{:ok, decl} = Tool.find_function(tool, "add")
{:error, :not_found} = Tool.find_function(tool, "nonexistent")

from_map(arg1)

@spec from_map(map()) :: {:ok, t()} | {:error, String.t()}

Parse tool from JSON-deserialized map.

Examples

json = ~s({"function_declarations": [{"name": "add", "description": "Add", "parameters": {}}]})
map = Jason.decode!(json)
{:ok, tool} = Tool.from_map(map)

function_names(tool)

@spec function_names(t()) :: [String.t()]

Get a list of all function names defined in this tool.

Examples

iex> {:ok, tool} = Altar.ADM.Tool.new(%{
...>   function_declarations: [
...>     %{name: "add", description: "Add", parameters: %{}},
...>     %{name: "multiply", description: "Multiply", parameters: %{}}
...>   ]
...> })
iex> Altar.ADM.Tool.function_names(tool)
["add", "multiply"]

new(attrs)

@spec new(map() | keyword()) :: {:ok, t()} | {:error, String.t()}

Construct a new validated Tool.

Required Fields

  • :function_declarations - Non-empty list of FunctionDeclaration structs

Validation Rules

  1. Must have at least one function declaration
  2. All elements must be valid FunctionDeclaration structs
  3. Function names must be unique within the tool
  4. Tool must be JSON-serializable

Returns {:ok, tool} or {:error, reason}.

Examples

# From existing FunctionDeclarations
{:ok, decl1} = FunctionDeclaration.new(%{name: "add", description: "Add numbers", parameters: %{}})
{:ok, decl2} = FunctionDeclaration.new(%{name: "multiply", description: "Multiply", parameters: %{}})
{:ok, tool} = Tool.new(%{function_declarations: [decl1, decl2]})

# From raw maps (will be converted to FunctionDeclarations)
{:ok, tool} = Tool.new(%{
  function_declarations: [
    %{name: "add", description: "Add numbers", parameters: %{}},
    %{name: "multiply", description: "Multiply", parameters: %{}}
  ]
})

to_map(tool)

@spec to_map(t()) :: map()

Convert tool to JSON-serializable map.

Examples

map = Tool.to_map(tool)
json = Jason.encode!(map)