Class: TurnKit::Tool

Inherits:
Object
  • Object
show all
Defined in:
lib/turnkit/tool.rb

Direct Known Subclasses

SubAgentTool

Constant Summary collapse

TYPES = 
%i[string integer number boolean array object enum].freeze
NAME_PATTERN = 
/\A[a-zA-Z_][a-zA-Z0-9_]*\z/

Class Method Summary collapse

Class Method Details

.call(arguments = {}, context:) ⇒ Object 



103
104
105
106
107
108
109
110
111
 
# File 'lib/turnkit/tool.rb', line 103

def call(arguments = {}, context:)
  keyword_arguments = symbolize(validate_arguments(arguments))
  instance = new
  if accepts_turnkit_context?(instance)
    instance.call(**keyword_arguments, turnkit_context: context)
  else
    instance.call(**keyword_arguments, context: context)
  end
end

.completion_message(_result) ⇒ Object 



51
52
53
 
# File 'lib/turnkit/tool.rb', line 51

def completion_message(_result)
  nil
end

.description(value = nil) ⇒ Object 



14
15
16
17
 
# File 'lib/turnkit/tool.rb', line 14

def description(value = nil)
  @description = value.to_s if value
  @description.to_s
end

.ends_turn? ⇒ Boolean

Returns:

  • (Boolean) 


47
48
49
 
# File 'lib/turnkit/tool.rb', line 47

def ends_turn?
  false
end

.input_schema ⇒ Object 



68
69
70
71
72
73
74
75
76
 
# File 'lib/turnkit/tool.rb', line 68

def input_schema
  properties = parameters.to_h { |param| [ param.fetch(:name), schema_for(param) ] }
  required = parameters.select { |param| param.fetch(:required) }.map { |param| param.fetch(:name) }
  {
    "type" => "object",
    "properties" => properties,
    "required" => required
  }
end

.parameter(name, type = :string, required: false, description: "", default: nil, enum: nil, items: nil, properties: nil) ⇒ Object

Raises:

  • (ArgumentError) 


24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/turnkit/tool.rb', line 24

def parameter(name, type = :string, required: false, description: "", default: nil, enum: nil, items: nil, properties: nil)
  name = name.to_s
  raise ArgumentError, "unknown parameter type: #{type}" unless TYPES.include?(type)
  raise ArgumentError, "invalid parameter name: #{name}" unless NAME_PATTERN.match?(name)
  raise ArgumentError, "duplicate parameter: #{name}" if parameters.any? { |param| param.fetch(:name) == name }
  raise ArgumentError, "enum values are required for enum parameter: #{name}" if type == :enum && Array(enum).empty?

  parameters << {
    name: name,
    type: type,
    required: required ? true : false,
    description: description.to_s,
    default: default,
    enum: enum,
    items: items,
    properties: properties
  }.compact
end

.parameters ⇒ Object 



43
44
45
 
# File 'lib/turnkit/tool.rb', line 43

def parameters
  @parameters ||= superclass.respond_to?(:parameters) ? superclass.parameters.dup : []
end

.tool_name(value = nil) ⇒ Object 



9
10
11
12
 
# File 'lib/turnkit/tool.rb', line 9

def tool_name(value = nil)
  @tool_name = value.to_s if value
  @tool_name ||= name.to_s.split("::").last.gsub(/([a-z\d])([A-Z])/, "\\1_\\2").downcase
end

.usage_hint(value = nil) ⇒ Object 



19
20
21
22
 
# File 'lib/turnkit/tool.rb', line 19

def usage_hint(value = nil)
  @usage_hint = value.to_s if value
  @usage_hint.to_s
end

.validate_arguments(arguments) ⇒ Object

Raises:



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/turnkit/tool.rb', line 78

def validate_arguments(arguments)
  attrs = arguments.respond_to?(:to_h) ? arguments.to_h.transform_keys(&:to_s) : {}
  allowed = parameters.map { |param| param.fetch(:name) }
  unknown = attrs.keys - allowed
  raise ToolValidationError, "unknown argument#{unknown.length == 1 ? "" : "s"}: #{unknown.join(", ")}" if unknown.any?

  normalized = {}
  parameters.each do |param|
    name = param.fetch(:name)
    if attrs.key?(name)
      value = attrs[name]
    elsif param.key?(:default)
      value = param[:default]
    elsif param.fetch(:required)
      raise ToolValidationError, "missing required argument: #{name}"
    else
      next
    end

    validate_value!(value, param)
    normalized[name] = value
  end
  normalized
end

.validate_definition! ⇒ Object

Raises:

  • (ArgumentError) 


55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/turnkit/tool.rb', line 55

def validate_definition!
  raise ArgumentError, "tool name is required" if tool_name.empty?
  raise ArgumentError, "invalid tool name: #{tool_name}" unless NAME_PATTERN.match?(tool_name)

  parameters.each do |param|
    type = param.fetch(:type)
    raise ArgumentError, "unknown parameter type: #{type}" unless TYPES.include?(type)
    raise ArgumentError, "enum values are required for enum parameter: #{param.fetch(:name)}" if type == :enum && Array(param[:enum]).empty?
    validate_value!(param[:default], param) if param.key?(:default)
  end
  true
end