Class: Ask::ToolDef

Inherits:
Object
  • Object
show all
Defined in:
lib/ask/tool_def.rb

Overview

Immutable value object representing a tool (function) definition that can be passed to LLM providers. Describes a callable tool’s name, description, and parameter schema.

ToolDef.new(
  name: "get_weather",
  description: "Get current weather for a location",
  parameters: {
    type: "object",
    properties: { location: { type: "string" } },
    required: ["location"]
  }
)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name:, description: "", parameters: nil, provider_params: {}) ⇒ ToolDef

Returns a new instance of ToolDef.



66
67
68
69
70
71
72
 
# File 'lib/ask/tool_def.rb', line 66

def initialize(name:, description: "", parameters: nil, provider_params: {})
  @name = validate_name!(name)
  @description = description.to_s
  @parameters = parameters
  @provider_params = provider_params.dup.freeze
  freeze
end

Instance Attribute Details

#description ⇒ String (readonly)

Returns description of what the tool does.

Returns:

  • (String) —

    description of what the tool does



58
59
60
 
# File 'lib/ask/tool_def.rb', line 58

def description
  @description
end

#name ⇒ String (readonly)

Returns tool name (must match /\A[a-zA-Z0-9_-]*\z/).

Returns:

  • (String) —

    tool name (must match /\A[a-zA-Z0-9_-]*\z/)



55
56
57
 
# File 'lib/ask/tool_def.rb', line 55

def name
  @name
end

#parameters ⇒ Hash? (readonly)

Returns JSON Schema parameter definition.

Returns:

  • (Hash, nil) —

    JSON Schema parameter definition



61
62
63
 
# File 'lib/ask/tool_def.rb', line 61

def parameters
  @parameters
end

#provider_params ⇒ Hash (readonly)

Returns provider-specific parameters (e.g. concurrency limits).

Returns:

  • (Hash) —

    provider-specific parameters (e.g. concurrency limits)



64
65
66
 
# File 'lib/ask/tool_def.rb', line 64

def provider_params
  @provider_params
end

Class Method Details

.from_tool(tool) ⇒ Ask::ToolDef

Build a ToolDef from an object that responds to #name, #description, #params_schema, and #provider_params.

Parameters:

Returns:



24
25
26
27
28
29
30
31
32
 
# File 'lib/ask/tool_def.rb', line 24

def from_tool(tool)
  schema = tool.params_schema
  new(
    name: tool.name,
    description: tool.description,
    parameters: schema,
    provider_params: tool.provider_params
  )
end

.safe_create(name:, description: "", parameters: nil, provider_params: {}) {|message| ... } ⇒ Ask::ToolDef?

Safely create a ToolDef, returning nil instead of raising on invalid input. Calls the optional log block with the error message if creation fails.

Yields:

  • (message) —

    called with the error message if creation fails

Yield Parameters:

  • message (String) —

    the error description

Returns:

  • (Ask::ToolDef, nil) —

    the created ToolDef or nil on failure



40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/ask/tool_def.rb', line 40

def safe_create(name:, description: "", parameters: nil, provider_params: {}, &log_block)
  new(name: name, description: description, parameters: parameters, provider_params: provider_params)
rescue InvalidToolDefinition => e
  msg = e.message
  if log_block
    log_block.call(msg)
  else
    $stderr.puts "[ask-core] ToolDef.safe_create skipped: #{msg}"
  end
  nil
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Two ToolDefs are equal if they have the same name.

Returns:

  • (Boolean) 


85
86
87
88
89
 
# File 'lib/ask/tool_def.rb', line 85

def ==(other)
  return false unless other.is_a?(ToolDef)

  name == other.name
end

#hash ⇒ Object 



92
93
94
 
# File 'lib/ask/tool_def.rb', line 92

def hash
  name.hash
end

#inspect ⇒ String

Returns:

  • (String) 


107
108
109
 
# File 'lib/ask/tool_def.rb', line 107

def inspect
  "#<Ask::ToolDef name=#{@name.inspect}>"
end

#to_h ⇒ Hash

Returns serialized representation.

Returns:

  • (Hash) —

    serialized representation



97
98
99
100
101
102
103
104
 
# File 'lib/ask/tool_def.rb', line 97

def to_h
  {
    name: @name,
    description: @description,
    parameters: @parameters,
    provider_params: @provider_params
  }
end

#to_provider_format {|self| ... } ⇒ Hash

Convert to a provider-specific format.

Yields:

  • (self) —

    yields the tool def for custom formatting

Returns:

  • (Hash) —

    provider-ready parameters



77
78
79
80
81
 
# File 'lib/ask/tool_def.rb', line 77

def to_provider_format(&block)
  return @parameters || default_parameters unless block

  block.call(self)
end