Class: LLM::Function

Inherits:
Object
  • Object
show all
Extended by:
Registry
Includes:
Tracing
Defined in:
lib/llm/function.rb,
lib/llm/function/fork.rb,
lib/llm/function/task.rb,
lib/llm/function/array.rb,
lib/llm/function/ractor.rb,
lib/llm/function/tracing.rb,
lib/llm/function/fork/job.rb,
lib/llm/function/registry.rb,
lib/llm/function/fork/task.rb,
lib/llm/function/call_group.rb,
lib/llm/function/fork_group.rb,
lib/llm/function/ractor/job.rb,
lib/llm/function/task_group.rb,
lib/llm/function/fiber_group.rb,
lib/llm/function/ractor/task.rb,
lib/llm/function/ractor_group.rb,
lib/llm/function/thread_group.rb,
lib/llm/function/ractor/mailbox.rb

Overview

The LLM::Function class represents a local function that can be called by an LLM.

Examples:

example #1

LLM.function(:system) do |fn|
  fn.name "system"
  fn.description "Runs system commands"
  fn.params do |schema|
    schema.object(command: schema.string.required)
  end
  fn.define do |command:|
    {success: Kernel.system(command)}
  end
end

example #2

class System < LLM::Tool
  name "system"
  description "Runs system commands"
  params do |schema|
    schema.object(command: schema.string.required)
  end

  def call(command:)
    {success: Kernel.system(command)}
  end
end

Defined Under Namespace

Modules: Array, Fork, Ractor, Registry, Tracing Classes: CallGroup, FiberGroup, Return, Task, TaskGroup, ThreadGroup

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Registry

clear_registry!, extended, find_by_name, lock, registry, registry_key, tool_name, unregister

Constructor Details

#initialize(name) {|self| ... } ⇒ Function

Returns a new instance of Function.

Parameters:

  • name (String) —

    The function name

Yield Parameters:



127
128
129
130
131
132
133
 
# File 'lib/llm/function.rb', line 127

def initialize(name, &b)
  @name = name
  @schema = LLM::Schema.new
  @called = false
  @cancelled = false
  yield(self) if block_given?
end

Instance Attribute Details

#arguments ⇒ Array?

Returns function arguments

Returns:



112
113
114
 
# File 'lib/llm/function.rb', line 112

def arguments
  @arguments
end

#id ⇒ String?

Returns the function ID

Returns:

  • (String, nil) 


107
108
109
 
# File 'lib/llm/function.rb', line 107

def id
  @id
end

#model ⇒ String?

Returns a model name, or nil

Returns:

  • (String, nil) 


122
123
124
 
# File 'lib/llm/function.rb', line 122

def model
  @model
end

#tracer ⇒ LLM::Tracer?

Returns a tracer, or nil

Returns:



117
118
119
 
# File 'lib/llm/function.rb', line 117

def tracer
  @tracer
end

Instance Method Details

#adapt(provider) ⇒ Hash

Returns:

  • (Hash) 


300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/llm/function.rb', line 300

def adapt(provider)
  case provider.class.to_s
  when "LLM::Google"
    {name: @name, description: @description, parameters: @params}.compact
  when "LLM::Anthropic"
    {
      name: @name,
      description: @description,
      input_schema: @params || {type: "object", properties: {}}
    }.compact
  else
    format_openai(provider)
  end
end

#call ⇒ LLM::Function::Return

Call the function

Returns:



189
190
191
192
193
 
# File 'lib/llm/function.rb', line 189

def call
  call_function
ensure
  @called = true
end

#called? ⇒ Boolean

Returns true when a function has been called

Returns:

  • (Boolean) 


280
281
282
 
# File 'lib/llm/function.rb', line 280

def called?
  @called
end

#cancel(reason: "function call cancelled") ⇒ LLM::Function::Return

Returns a value that communicates that the function call was cancelled

Examples:

llm = LLM.openai(key: ENV["KEY"])
ctx = LLM::Context.new(llm, tools: [fn1, fn2])
ctx.talk "I want to run the functions"
ctx.talk ctx.functions.map(&:cancel)

Returns:



259
260
261
262
263
 
# File 'lib/llm/function.rb', line 259

def cancel(reason: "function call cancelled")
  Return.new(id, name, {cancelled: true, reason:})
ensure
  @cancelled = true
end

#cancelled? ⇒ Boolean

Returns true when a function has been cancelled

Returns:

  • (Boolean) 


287
288
289
 
# File 'lib/llm/function.rb', line 287

def cancelled?
  @cancelled
end

#define(klass = nil, &b) ⇒ void Also known as: register

This method returns an undefined value.

Set the function implementation

Parameters:

  • b (Proc, Class) —

    The function implementation



181
182
183
 
# File 'lib/llm/function.rb', line 181

def define(klass = nil, &b)
  @runner = klass || b
end

#description(desc = nil) ⇒ void

This method returns an undefined value.

Set (or get) the function description

Parameters:

  • desc (String) (defaults to: nil) —

    The function description



151
152
153
154
155
156
157
 
# File 'lib/llm/function.rb', line 151

def description(desc = nil)
  if desc
    @description = desc
  else
    @description
  end
end

#interrupt! ⇒ nil Also known as: cancel!

Notifies the function runner that the call was interrupted. This is cooperative and only applies to runners that implement ‘on_interrupt`.

Returns:

  • (nil) 


270
271
272
273
274
 
# File 'lib/llm/function.rb', line 270

def interrupt!
  hook = %i[on_cancel on_interrupt].find { @runner.respond_to?(_1) }
  @runner.public_send(hook) if hook
  nil
end

#name(name = nil) ⇒ void

This method returns an undefined value.

Set (or get) the function name

Parameters:

  • name (String) (defaults to: nil) —

    The function name



139
140
141
142
143
144
145
 
# File 'lib/llm/function.rb', line 139

def name(name = nil)
  if name
    @name = name.to_s
  else
    @name
  end
end

#params {|schema| ... } ⇒ LLM::Schema::Leaf?

Set (or get) the function parameters

Yield Parameters:

Returns:



163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/llm/function.rb', line 163

def params
  if block_given?
    params = yield(@schema)
    params = LLM::Schema.parse(params) if Hash === params
    if @params
      @params.merge!(params)
    else
      @params = params
    end
  else
    @params
  end
end

#pending? ⇒ Boolean

Returns true when a function has neither been called nor cancelled

Returns:

  • (Boolean) 


294
295
296
 
# File 'lib/llm/function.rb', line 294

def pending?
  !@called && !@cancelled
end

#runner ⇒ Object

Returns the bound function runner instance.

Returns:



318
319
320
321
322
 
# File 'lib/llm/function.rb', line 318

def runner
  runner = Class === @runner ? @runner.new : @runner
  runner.tracer = @tracer if runner.respond_to?(:tracer=)
  runner
end

#spawn(strategy) ⇒ LLM::Function::Task

Calls the function concurrently.

This is the low-level method that powers concurrent tool execution. Prefer the collection methods on Context#functions for most use cases: LLM::Function::Array#call, LLM::Function::Array#wait, or LLM::Function::Array#spawn.

Examples:

# Normal usage (via collection)
ctx.talk(ctx.functions.wait)

# Direct usage (uncommon)
task = tool.spawn(:thread)
result = task.value

Parameters:

  • strategy (Symbol) —

    Controls concurrency strategy:

    • ‘:thread`: Use threads

    • ‘:task`: Use async tasks (requires async gem)

    • ‘:fork`: Use a forked child process (requires xchan.rb support)

    • ‘:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)

    • ‘:fork`: Use a forked child process (requires xchan.rb support)

    • ‘:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)

Returns:



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/llm/function.rb', line 222

def spawn(strategy)
  task = case strategy
  when :task
    LLM.require "async" unless defined?(::Async)
    Async { call! }
  when :thread
    Thread.new { call! }
  when :fiber
    raise ArgumentError, "Fiber concurrency requires Fiber.scheduler" unless Fiber.scheduler
    Fiber.schedule { call! }
  when :fork
    LLM.require "xchan" unless defined?(::Chan::UNIXSocket)
    span = @tracer&.on_tool_start(id:, name:, arguments:, model:)
    Fork::Task.new(self, tracer: @tracer, span:).spawn
  when :ractor
    raise LLM::RactorError, "Ractor concurrency only supports class-based tools" unless Class === @runner
    if @runner.respond_to?(:skill?) && @runner.skill?
      raise LLM::RactorError, "Ractor concurrency does not support skill-backed tools"
    end
    span = @tracer&.on_tool_start(id:, name:, arguments:, model:)
    Ractor::Task.new(@runner, id, name, arguments, tracer: @tracer, span:).spawn
  else
    raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, :fork, or :ractor"
  end
  Task.new(task, self)
ensure
  @called = true
end