Module: Riffer::Tools::Toolable

Included in:
Riffer::Tool
Defined in:
lib/riffer/tools/toolable.rb

Overview

Riffer::Tools::Toolable provides the shared class-level DSL for anything that can present as a tool to an LLM — tools today, and subagents/workflows in the future.

Extend this module to make a class discoverable as a tool by LLM providers. Provides identifier, description, params, timeout, and JSON schema generation.

Instance-level execution concerns (call, call_with_validation, etc.) are NOT part of Toolable — those belong on Riffer::Tool.

class MyTool
  extend Riffer::Tools::Toolable

  description "Does something useful"

  params do
    required :input, String
  end
end

Constant Summary collapse

DEFAULT_TIMEOUT = 
10

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.all ⇒ Object

Returns all classes that have extended Toolable.

– : () -> Array



49
50
51
 
# File 'lib/riffer/tools/toolable.rb', line 49

def self.all
  @extenders || []
end

.extended(base) ⇒ Object

Tracks all classes that extend Toolable.

– : (Module) -> void



39
40
41
42
43
 
# File 'lib/riffer/tools/toolable.rb', line 39

def self.extended(base)
  base.extend Riffer::Helpers::ClassNameConverter
  extenders = (@extenders ||= []) #: Array[Module]
  extenders << base
end

Instance Method Details

#description(value = nil) ⇒ Object

Gets or sets the tool description.

– : (?String?) -> String?



57
58
59
60
 
# File 'lib/riffer/tools/toolable.rb', line 57

def 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



66
67
68
69
 
# File 'lib/riffer/tools/toolable.rb', line 66

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

#kind(value = nil) ⇒ Object

Returns the kind of toolable entity.

Defaults to :tool. Extensible to :agent, :workflow, etc.

– : (?Symbol?) -> Symbol



114
115
116
117
 
# File 'lib/riffer/tools/toolable.rb', line 114

def kind(value = nil)
  return @kind || :tool if value.nil?
  @kind = value.to_sym
end

#name(value = nil) ⇒ Object

Alias for identifier — used by providers.

– : (?String?) -> String



75
76
77
78
 
# File 'lib/riffer/tools/toolable.rb', line 75

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

#parameters_schema(strict: false) ⇒ Object

Returns the JSON Schema for the tool’s parameters.

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



104
105
106
 
# File 'lib/riffer/tools/toolable.rb', line 104

def parameters_schema(strict: false)
  @params_builder&.to_json_schema(strict: strict) || empty_schema
end

#params(&block) ⇒ Object

Defines parameters using the Params DSL.

– : () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?



93
94
95
96
97
98
 
# File 'lib/riffer/tools/toolable.rb', line 93

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

#timeout(value = nil) ⇒ Object

Gets or sets the tool timeout in seconds.

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



84
85
86
87
 
# File 'lib/riffer/tools/toolable.rb', line 84

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

#to_tool_schema(strict: false) ⇒ Object

Returns a provider-agnostic tool schema hash.

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



123
124
125
126
127
128
129
 
# File 'lib/riffer/tools/toolable.rb', line 123

def to_tool_schema(strict: false)
  {
    name: name,
    description: description,
    parameters_schema: parameters_schema(strict: strict)
  }
end

#validate_as_tool! ⇒ Object

Validates that the minimum required metadata is present for LLM tool use.

Raises Riffer::ArgumentError if validation fails.

– : () -> true

Raises:



137
138
139
140
141
 
# File 'lib/riffer/tools/toolable.rb', line 137

def validate_as_tool!
  raise Riffer::ArgumentError, "#{self} must define a description" if description.nil? || description.to_s.strip.empty?
  raise Riffer::ArgumentError, "#{self} must have an identifier" if identifier.nil? || identifier.to_s.strip.empty?
  true
end