Cyclium.Intent.ToolSignature (Cyclium v0.5.2)

Copy Markdown View Source

A tool the strategy allows the model to call, declared in strategy config by the consuming app under allowed_tool_signatures.

The runtime matches each planned tool call against these on two keys:

  • the tool name must match a signature, and
  • the step's action must be one the signature lists in actions.

A signature that lists no actions allows none. The prompt and the native tool schema are built from the same list, so an action the model cannot see is not callable either. A tool whose every call/3 clause is safe to expose may opt out with "actions" => "*" (or :any); do that deliberately.

side_effect classifies the whole tool. An action entry may carry its own "side_effect" to override it, so a tool that mixes reads and one write can gate only the write behind preview.

%{
  "name" => "widgets",
  "side_effect" => "read",
  "constraints" => %{"max_rows" => 500},
  "actions" => [
    %{"name" => "lookup", "args" => %{"id" => "widget id"}, "description" => "..."},
    %{"name" => "adjust", "side_effect" => "write", "args" => %{...}, "description" => "..."}
  ]
}

Summary

Types

side_effect()
t()

Functions

allows_action?(arg1, action)

Whether action is callable under this signature.

from_config(sig)

Build a signature from one allowed_tool_signatures entry. Accepts string or atom keys (the Actor DSL normalises to strings, DB-loaded JSON is strings, and in-process callers may pass atoms).

parse_side_effect(atom)

Normalise a declared side-effect value; anything unrecognised is :read.

side_effect_for(sig, action)

The side-effect class that applies to action: the action's own override when declared, otherwise the tool's class.

Types

side_effect()

@type side_effect() :: :read | :write | :external_effect

t()

@type t() :: %Cyclium.Intent.ToolSignature{
  action_side_effects: %{required(binary()) => side_effect()},
  actions: [binary()] | :any,
  args_schema: binary() | nil,
  constraints: map(),
  name: binary(),
  side_effect: side_effect(),
  version: pos_integer()
}

Functions

allows_action?(arg1, action)

@spec allows_action?(t(), binary() | atom() | nil) :: boolean()

Whether action is callable under this signature.

from_config(sig)

@spec from_config(map()) :: t()

Build a signature from one allowed_tool_signatures entry. Accepts string or atom keys (the Actor DSL normalises to strings, DB-loaded JSON is strings, and in-process callers may pass atoms).

parse_side_effect(atom)

@spec parse_side_effect(term()) :: side_effect()

Normalise a declared side-effect value; anything unrecognised is :read.

side_effect_for(sig, action)

@spec side_effect_for(t(), binary() | atom() | nil) :: side_effect()

The side-effect class that applies to action: the action's own override when declared, otherwise the tool's class.