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

Direct Known Subclasses

Evals::Judge::EvaluationTool

Constant Summary collapse

DEFAULT_TIMEOUT =

: Integer

10
TOOL_SEPARATOR =

Some providers do not allow “/” in tool names, so we use “__” as separator.

"__"

Constants included from Helpers::ClassNameConverter

Helpers::ClassNameConverter::DEFAULT_SEPARATOR

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Helpers::ClassNameConverter

class_name_to_path

Class Method Details

.description(value = nil) ⇒ Object

Gets or sets the tool description.

: (?String?) -> String?



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

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

.identifier(value = nil) ⇒ Object

Gets or sets the tool identifier/name.

: (?String?) -> String



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

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

.name(value = nil) ⇒ Object

Alias for identifier - used by providers.

: (?String?) -> String



53
54
55
56
 
# File 'lib/riffer/tool.rb', line 53

def self.name(value = nil)
  return identifier(value) unless value.nil?
  identifier
end

.parameters_schema ⇒ Object

Returns the JSON Schema for the tool’s parameters.

: () -> Hash[Symbol, untyped]



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

def self.parameters_schema
  @params_builder&.to_json_schema || empty_schema
end

.params(&block) ⇒ Object

Defines parameters using the Params DSL.

: () ?{ () -> void } -> Riffer::Tools::Params?



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

def self.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.

: (?(Integer | Float)?) -> (Integer | Float)



61
62
63
64
 
# File 'lib/riffer/tool.rb', line 61

def self.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.

Raises NotImplementedError if not implemented by subclass.

: (context: Hash[Symbol, untyped]?, **untyped) -> Riffer::Tools::Response

Raises:

  • (NotImplementedError) 


92
93
94
 
# File 'lib/riffer/tool.rb', line 92

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).

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.

: (context: Hash[Symbol, untyped]?, **untyped) -> Riffer::Tools::Response



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/riffer/tool.rb', line 124

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.

: (String, ?type: Symbol) -> Riffer::Tools::Response



113
114
115
 
# File 'lib/riffer/tool.rb', line 113

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.

: (untyped) -> Riffer::Tools::Response



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

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

#text(result) ⇒ Object

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

: (untyped) -> Riffer::Tools::Response



99
100
101
 
# File 'lib/riffer/tool.rb', line 99

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