Module: Riffer::Toolable

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

Overview

Riffer::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::Toolable

  description "Does something useful"

  params do
    required :input, String
  end
end

Constant Summary collapse

DEFAULT_TIMEOUT =

: Integer

10

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.all ⇒ Object

Returns all classes that have extended Toolable.

– : () -> Array



42
43
44
 
# File 'lib/riffer/toolable.rb', line 42

def self.all
  @extenders || []
end

.extended(base) ⇒ Object

Tracks all classes that extend Toolable.

– : (Module) -> void



32
33
34
35
36
 
# File 'lib/riffer/toolable.rb', line 32

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

Instance Method Details

#description(value = nil) ⇒ Object

Gets or sets the tool description.

– : (?String?) -> String?



50
51
52
53
 
# File 'lib/riffer/toolable.rb', line 50

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



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

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



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

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



68
69
70
71
 
# File 'lib/riffer/toolable.rb', line 68

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]



96
97
98
 
# File 'lib/riffer/toolable.rb', line 96

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

#params(&block) ⇒ Object

Defines parameters using the Params DSL.

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



86
87
88
89
90
 
# File 'lib/riffer/toolable.rb', line 86

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

#timeout(value = nil) ⇒ Object

Gets or sets the tool timeout in seconds.

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



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

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]



115
116
117
118
119
120
121
 
# File 'lib/riffer/toolable.rb', line 115

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:



129
130
131
132
133
 
# File 'lib/riffer/toolable.rb', line 129

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