Class: Riffer::Tool

Inherits:
Object
  • Object
show all
Extended by:
Helpers::ClassNameConverter
Defined in:
lib/riffer/tool.rb

Overview

Riffer::Tool is the base class for all tools in the Riffer framework.

Provides a DSL for defining tool description and parameters. Subclasses must implement the call method.

See Riffer::Agent.

class WeatherLookupTool < Riffer::Tool
  description "Provides current weather information for a specified city."

  params do
    required :city, String, description: "The city to look up"
    optional :units, String, default: "celsius"
  end

  def call(context:, city:, units: nil)
    # Implementation
  end
end

Constant Summary collapse

DEFAULT_TIMEOUT = 
10

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.description(value = nil) ⇒ Object

Gets or sets the tool description.

value

String or nil - the description to set, or nil to get

Returns String or nil - the tool description.



36
37
38
39
 
# File 'lib/riffer/tool.rb', line 36

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

.identifier(value = nil) ⇒ Object Also known as: name

Gets or sets the tool identifier/name.

value

String or nil - the identifier to set, or nil to get

Returns String - the tool identifier (defaults to snake_case class name).



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

def identifier(value = nil)
  return @identifier || class_name_to_path(Module.instance_method(:name).bind_call(self)) if value.nil?
  @identifier = value.to_s
end

.parameters_schema ⇒ Object

Returns the JSON Schema for the tool’s parameters.

Returns Hash - the JSON Schema.



78
79
80
 
# File 'lib/riffer/tool.rb', line 78

def parameters_schema
  @params_builder&.to_json_schema || empty_schema
end

.params(&block) ⇒ Object

Defines parameters using the Params DSL.

Yields to the parameter definition block.

Returns Riffer::Tools::Params or nil - the params builder.



69
70
71
72
73
 
# File 'lib/riffer/tool.rb', line 69

def params(&block)
  return @params_builder if block.nil?
  @params_builder = Riffer::Tools::Params.new
  @params_builder.instance_eval(&block)
end

.timeout(value = nil) ⇒ Object

Gets or sets the tool timeout in seconds.

value

Numeric or nil - the timeout to set in seconds, or nil to get

Returns Numeric - the tool timeout (defaults to 10).



59
60
61
62
 
# File 'lib/riffer/tool.rb', line 59

def timeout(value = nil)
  return @timeout || DEFAULT_TIMEOUT if value.nil?
  @timeout = value.to_f
end

Instance Method Details

#call(context:, **kwargs) ⇒ Object

Executes the tool with the given arguments.

context

Object or nil - optional context passed from the agent

kwargs

Hash - the tool arguments

Returns Object - the tool result.

Raises NotImplementedError if not implemented by subclass.

Raises:

  • (NotImplementedError) 


97
98
99
 
# File 'lib/riffer/tool.rb', line 97

def call(context:, **kwargs)
  raise NotImplementedError, "#{self.class} must implement #call"
end

#call_with_validation(context:, **kwargs) ⇒ Object

Executes the tool with validation and timeout (used by Agent).

context

Object or nil - context passed from the agent

kwargs

Hash - the tool arguments

Returns Riffer::Tools::Response - the tool response.

Raises Riffer::ValidationError if validation fails. Raises Riffer::TimeoutError if execution exceeds the configured timeout. Raises Riffer::Error if the tool does not return a Response object.



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/riffer/tool.rb', line 139

def call_with_validation(context:, **kwargs)
  params_builder = self.class.params
  validated_args = params_builder ? params_builder.validate(kwargs) : kwargs

  result = Timeout.timeout(self.class.timeout) do
    call(context: context, **validated_args)
  end

  unless result.is_a?(Riffer::Tools::Response)
    raise Riffer::Error, "#{self.class} must return a Riffer::Tools::Response from #call"
  end

  result
rescue Timeout::Error
  raise Riffer::TimeoutError, "Tool execution timed out after #{self.class.timeout} seconds"
end

#error(message, type: :execution_error) ⇒ Object

Creates an error response. Shorthand for Riffer::Tools::Response.error.

message

String - the error message

type

Symbol - the error type (default: :execution_error)

Returns Riffer::Tools::Response.



125
126
127
 
# File 'lib/riffer/tool.rb', line 125

def error(message, type: :execution_error)
  Riffer::Tools::Response.error(message, type: type)
end

#json(result) ⇒ Object

Creates a JSON response. Shorthand for Riffer::Tools::Response.json.

result

Object - the tool result (converted via JSON.generate)

Returns Riffer::Tools::Response.



115
116
117
 
# File 'lib/riffer/tool.rb', line 115

def json(result)
  Riffer::Tools::Response.json(result)
end

#text(result) ⇒ Object

Creates a text response. Shorthand for Riffer::Tools::Response.text.

result

Object - the tool result (converted via to_s)

Returns Riffer::Tools::Response.



106
107
108
 
# File 'lib/riffer/tool.rb', line 106

def text(result)
  Riffer::Tools::Response.text(result)
end