class Riffer::Tool

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

Constants

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

Public Class Methods

description (value = nil)

Source

# File lib/riffer/tool.rb, line 37
def self.description(value = nil)
  return @description if value.nil?
  @description = value.to_s
end

Gets or sets the tool description.

: (?String?) -> String?

identifier (value = nil)

Source

# 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

Gets or sets the tool identifier/name.

: (?String?) -> String

name (value = nil)

Source

# File lib/riffer/tool.rb, line 53
def self.name(value = nil)
  return identifier(value) unless value.nil?
  identifier
end

Alias for identifier - used by providers.

: (?String?) -> String

parameters_schema (strict: false)

Source

# File lib/riffer/tool.rb, line 78
def self.parameters_schema(strict: false)
  @params_builder&.to_json_schema(strict: strict) || empty_schema
end

Returns the JSON Schema for the tool’s parameters.

: (?strict: bool) -> Hash[Symbol, untyped]

params (&block)

Source

# File lib/riffer/tool.rb, line 69
def self.params(&block)
  return @params_builder if block.nil?
  @params_builder = Riffer::Params.new
  @params_builder.instance_eval(&block)
end

Defines parameters using the Params DSL.

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

timeout (value = nil)

Source

# File lib/riffer/tool.rb, line 61
def self.timeout(value = nil)
  return @timeout || DEFAULT_TIMEOUT if value.nil?
  @timeout = value.to_f
end

Gets or sets the tool timeout in seconds.

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

Public Instance Methods

call (context:, **kwargs)

Source

# File lib/riffer/tool.rb, line 92
def call(context:, **kwargs)
  raise NotImplementedError, "#{self.class} must implement #call"
end

Executes the tool with the given arguments.

Raises NotImplementedError if not implemented by subclass.

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

call_with_validation (context:, **kwargs)

Source

# 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

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

error (message, type: :execution_error)

Source

# File lib/riffer/tool.rb, line 113
def error(message, type: :execution_error)
  Riffer::Tools::Response.error(message, type: type)
end

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

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

json (result)

Source

# File lib/riffer/tool.rb, line 106
def json(result)
  Riffer::Tools::Response.json(result)
end

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

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

text (result)

Source

# File lib/riffer/tool.rb, line 99
def text(result)
  Riffer::Tools::Response.text(result)
end

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

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