llm.rb 9.0.0 → 10.0.0

data/lib/llm/agent.rb

@@ -48,9 +48,9 @@ module LLM
     #  The model identifier
     # @return [String, nil]
     #  Returns the current model when no argument is provided
-    def self.model(model = nil)
-      return @model if model.nil?
-      @model = model
+    def self.model(model = nil, &block)
+      return @model if model.nil? && !block
+      @model = block || model
     end
 
     ##
@@ -59,9 +59,9 @@ module LLM
     #  One or more tools
     # @return [Array<LLM::Function>]
     #  Returns the current tools when no argument is provided
-    def self.tools(*tools)
-      return @tools || [] if tools.empty?
-      @tools = tools.flatten
+    def self.tools(*tools, &block)
+      return @tools || [] if tools.empty? && !block
+      @tools = block || tools.flatten
     end
 
     ##
@@ -70,9 +70,9 @@ module LLM
     #  One or more skill directories
     # @return [Array<String>, nil]
     #  Returns the current skills when no argument is provided
-    def self.skills(*skills)
-      return @skills if skills.empty?
-      @skills = skills.flatten
+    def self.skills(*skills, &block)
+      return @skills if skills.empty? && !block
+      @skills = block || skills.flatten
     end
 
     ##
@@ -81,9 +81,9 @@ module LLM
     #  The schema
     # @return [#to_json, nil]
     #  Returns the current schema when no argument is provided
-    def self.schema(schema = nil)
-      return @schema if schema.nil?
-      @schema = schema
+    def self.schema(schema = nil, &block)
+      return @schema if schema.nil? && !block
+      @schema = block || schema
     end
 
     ##
@@ -157,6 +157,19 @@ module LLM
       @stream = block || stream
     end
 
+    ##
+    # Set or get the tool names that require confirmation before they can run.
+    #
+    # @param [String, Symbol, Array<String, Symbol>, Proc] tool_names
+    #  One or more tool names.
+    # @param [Proc] block
+    #  An optional, lazy-evaluated Proc
+    # @return [Array<String>, Proc, nil]
+    def self.confirm(*tool_names, &block)
+      return @confirm if tool_names.empty? && !block
+      @confirm = block || tool_names.flatten.map(&:to_s)
+    end
+
     ##
     # @param [LLM::Provider] provider
     #  A provider
@@ -168,17 +181,27 @@ module LLM
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
     # @option params [Array<String>, nil] :skills Defaults to nil
     # @option params [#to_json, nil] :schema Defaults to nil
+    # @option params [Object, Proc, nil] :stream Optional stream override for this agent instance
     # @option params [LLM::Tracer, Proc, nil] :tracer Optional tracer override for this agent instance
     # @option params [Symbol, Array<Symbol>, nil] :concurrency Defaults to the agent class concurrency
     def initialize(llm, params = {})
-      defaults = {model: self.class.model, tools: self.class.tools, skills: self.class.skills, schema: self.class.schema}.compact
-      @concurrency = params.delete(:concurrency) || self.class.concurrency
       @llm = llm
-      tracer = params.key?(:tracer) ? params.delete(:tracer) : self.class.tracer
-      stream = params.key?(:stream) ? params.delete(:stream) : self.class.stream
-      @tracer = resolve_option(tracer) unless tracer.nil?
-      params[:stream] = resolve_option(stream) unless stream.nil?
-      @ctx = LLM::Context.new(llm, defaults.merge({guard: true}).merge(params))
+      fields = %i[model skills schema tracer stream tools concurrency instructions confirm]
+      fields_ivar = %i[tracer concurrency instructions confirm]
+      fields.each do |field|
+        resolvable = params.key?(field) ? params.delete(field) : self.class.public_send(field)
+        resolve_symbol = !%i[concurrency confirm].include?(field)
+        resolved = resolvable != nil ? resolve_option(self, resolvable, resolve_symbol:) : resolvable
+        resolved = [*resolved].map(&:to_s) if field == :confirm && resolved
+        if field == :model
+          params[field] = resolved unless resolved.nil? || params.key?(field)
+        elsif resolved && !fields_ivar.include?(field)
+          params[field] ||= resolved
+        elsif fields_ivar.include?(field)
+          instance_variable_set(:"@#{field}", resolved)
+        end
+      end
+      @ctx = LLM::Context.new(llm, {guard: true}.merge(params))
     end
 
     ##
@@ -198,31 +221,10 @@ module LLM
     #   response = agent.talk("Hello, what is your name?")
     #   puts response.choices[0].content
     def talk(prompt, params = {})
-      run_loop(:talk, prompt, params)
+      run_loop(prompt, params)
     end
     alias_method :chat, :talk
 
-    ##
-    # Maintain a conversation via the responses API.
-    # This method immediately sends a request to the LLM and returns the response.
-    #
-    # @note Not all LLM providers support this API
-    # @param prompt (see LLM::Provider#complete)
-    # @param [Hash] params The params passed to the provider, including optional :stream, :tools, :schema etc.
-    # @option params [Integer] :tool_attempts
-    #  The maxinum number of tool call iterations before the agent sends
-    #  in-band advisory tool errors back through the model (default 25).
-    #  Set to `nil` to disable advisory tool-limit returns.
-    # @return [LLM::Response] Returns the LLM's response for this turn.
-    # @example
-    #   llm = LLM.openai(key: ENV["KEY"])
-    #   agent = LLM::Agent.new(llm)
-    #   res = agent.respond("What is the capital of France?")
-    #   puts res.output_text
-    def respond(prompt, params = {})
-      run_loop(:respond, prompt, params)
-    end
-
     ##
     # @return [LLM::Buffer<LLM::Message>]
     def messages
@@ -347,6 +349,13 @@ module LLM
       @ctx.context_window
     end
 
+    ##
+    # @see LLM::Context#params
+    # @return [Hash]
+    def params
+      @ctx.params
+    end
+
     ##
     # @see LLM::Context#to_h
     # @return [Hash]
@@ -383,19 +392,33 @@ module LLM
     end
     alias_method :restore, :deserialize
 
+    ##
+    # This method is called when confirmation is required before a tool can run.
+    #
+    # @param [LLM::Function] fn
+    #  The pending function call. It can be cancelled through the
+    #  {LLM::Function#cancel} method.
+    # @param [Symbol, Array<Symbol>] strategy
+    #  The execution strategy that would be used for the tool call.
+    # @return [LLM::Function::Return]
+    #  Return either `fn.spawn(strategy).wait` to approve execution or
+    #  `fn.cancel(...)` to cancel the call.
+    def on_tool_confirmation(fn, strategy)
+      fn.cancel
+    end
+
     private
 
     ##
     # @return [LLM::Prompt]
     def apply_instructions(new_prompt)
-      instr = self.class.instructions
-      return new_prompt unless instr
+      return new_prompt unless @instructions
       if LLM::Prompt === new_prompt
-        new_prompt.system(instr) if inject_instructions?(new_prompt)
+        new_prompt.system(@instructions) if inject_instructions?(new_prompt)
         new_prompt
       else
         prompt do
-          _1.system(instr) if inject_instructions?
+          _1.system(@instructions) if inject_instructions?
           _1.user(new_prompt)
         end
       end
@@ -416,50 +439,46 @@ module LLM
     ##
     # @return [Array<LLM::Function::Return>]
     def call_functions
-      case concurrency || :call
-      when :call then wait(:call)
-      when :thread, :task, :fiber, :fork, :ractor, Array then wait(concurrency)
-      else raise ArgumentError, "Unknown concurrency: #{concurrency.inspect}. " \
-                                "Expected :call, :thread, :task, :fiber, :fork, :ractor, " \
-                                "or an array of the mentioned options"
+      strategy = concurrency || :call
+      return wait(strategy) unless @confirm&.any?
+      confirmables = @ctx.functions.select { @confirm.include?(_1.name.to_s) }
+      results = confirmables.map do |tool|
+        send(:on_tool_confirmation, tool, strategy)
       end
+      @ctx.functions? ? [*results, *wait(strategy)] : results
     end
 
-    def run_loop(method, prompt, params)
-      loop = proc do
+    ##
+    # Runs the tool loop
+    # @api private
+    def run_loop(prompt, params)
+      run = proc do
         max = params.key?(:tool_attempts) ? params.delete(:tool_attempts) : 25
         max = Integer(max) if max
         stream = params[:stream] || @ctx.params[:stream]
         stream.extra[:concurrency] = concurrency if LLM::Stream === stream
-        res = @ctx.public_send(method, apply_instructions(prompt), params)
-        loop do
-          break unless @ctx.functions?
+        res = @ctx.talk(apply_instructions(prompt), params)
+        while @ctx.functions?
           if max
             max.times do
               break unless @ctx.functions?
-              res = @ctx.public_send(method, call_functions, params)
+              res = @ctx.talk(call_functions, params)
             end
-            break unless @ctx.functions?
-            res = @ctx.public_send(method, @ctx.functions.map { rate_limit(_1) }, params)
+            res = @ctx.talk(@ctx.functions.map(&:rate_limit), params) if @ctx.functions?
           else
-            res = @ctx.public_send(method, call_functions, params)
+            res = @ctx.talk(call_functions, params)
           end
         end
         res
       end
-      @tracer ? @llm.with_tracer(@tracer, &loop) : loop.call
-    end
-
-    def rate_limit(function)
-      LLM::Function::Return.new(function.id, function.name, {
-        error: true,
-        type: LLM::ToolLoopError.name,
-        message: "tool loop rate limit reached"
-      })
+      return run.call unless @tracer
+      @llm.with_tracer(@tracer, &run)
     end
 
-    def resolve_option(option)
-      Proc === option ? instance_exec(&option) : option
+    ##
+    # @api private
+    def resolve_option(...)
+      LLM::Utils.resolve_option(...)
     end
   end
 end

data/lib/llm/context.rb

@@ -68,13 +68,6 @@ module LLM
     # @return [Symbol]
     attr_reader :mode
 
-    ##
-    # Returns the default params for this context
-    # @return [Hash]
-    def params
-      @params.dup
-    end
-
     ##
     # @param [LLM::Provider] llm
     #  A provider
@@ -98,6 +91,13 @@ module LLM
       @messages = LLM::Buffer.new(llm)
     end
 
+    ##
+    # Returns the default params for this context
+    # @return [Hash]
+    def params
+      @params.dup
+    end
+
     ##
     # Returns a context compactor
     # This feature is inspired by the compaction approach developed by
@@ -191,14 +191,9 @@ module LLM
     #   res = ctx.talk("Hello, what is your name?")
     #   puts res.messages[0].content
     def talk(prompt, params = {})
-      return respond(prompt, params) if mode == :responses
       @owner = @llm.request_owner
       compactor.compact!(prompt) if compactor.compact?(prompt)
-      params = params.merge(messages: @messages.to_a)
-      params = @params.merge(params)
-      prompt, params = transform(prompt, params)
-      bind!(params[:stream], params[:model], params[:tools])
-      res = @llm.complete(prompt, params)
+      prompt, params, res = mode == :responses ? respond(prompt, params) : complete(prompt, params)
       self.compacted = false
       role = params[:role] || @llm.user_role
       role = @llm.tool_role if params[:role].nil? && [*prompt].grep(LLM::Function::Return).any?
@@ -208,35 +203,6 @@ module LLM
     end
     alias_method :chat, :talk
 
-    ##
-    # Interact with the context via the responses API.
-    # This method immediately sends a request to the LLM and returns the response.
-    #
-    # @note Not all LLM providers support this API
-    # @param prompt (see LLM::Provider#complete)
-    # @param params The params, including optional :role (defaults to :user), :stream, :tools, :schema etc.
-    # @return [LLM::Response] Returns the LLM's response for this turn.
-    # @example
-    #   llm = LLM.openai(key: ENV["KEY"])
-    #   ctx = LLM::Context.new(llm)
-    #   res = ctx.respond("What is the capital of France?")
-    #   puts res.output_text
-    def respond(prompt, params = {})
-      @owner = @llm.request_owner
-      compactor.compact!(prompt) if compactor.compact?(prompt)
-      params = @params.merge(params)
-      prompt, params = transform(prompt, params)
-      bind!(params[:stream], params[:model], params[:tools])
-      res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
-      params = params.merge(previous_response_id: res_id, input: @messages.to_a).compact
-      res = @llm.responses.create(prompt, params)
-      self.compacted = false
-      role = params[:role] || @llm.user_role
-      @messages.concat LLM::Prompt === prompt ? prompt.to_a : [LLM::Message.new(role, prompt)]
-      @messages.concat [res.choices[-1]]
-      res
-    end
-
     ##
     # @return [String]
     def inspect
@@ -493,6 +459,9 @@ module LLM
 
     private
 
+    ##
+    # Binds runtime metadata onto an active stream.
+    # @api private
     def bind!(stream, model, tools)
       return unless LLM::Stream === stream
       @stream = stream
@@ -502,21 +471,33 @@ module LLM
       stream.extra[:tools] = tools
     end
 
+    ##
+    # Returns the bound stream queue, if available.
+    # @api private
     def queue
       return @queue if @queue
       stream.queue if LLM::Stream === stream
     end
 
+    ##
+    # Loads skill directories and adapts them into tools.
+    # @api private
     def load_skills(skills)
       [*skills].map { LLM::Skill.load(_1).to_tool(self) }
     end
 
+    ##
+    # Builds in-band guarded returns when the guard blocks tool work.
+    # @api private
     def guarded_returns
       warning = guard&.call(self)
       return unless warning
       functions.map { guarded_return_for(_1, warning) }
     end
 
+    ##
+    # Rewrites a prompt and params through the configured transformer.
+    # @api private
     def transform(prompt, params)
       return [prompt, params] unless transformer
       stream = params[:stream]
@@ -526,6 +507,32 @@ module LLM
       stream.on_transform_finish(self, transformer) if LLM::Stream === stream
     end
 
+    ##
+    # Executes a turn through the Responses API.
+    # @api private
+    def respond(prompt, params)
+      params = @params.merge(params)
+      prompt, params = transform(prompt, params)
+      bind!(params[:stream], params[:model], params[:tools])
+      res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
+      params = params.merge(previous_response_id: res_id, input: @messages.to_a).compact
+      [prompt, params, @llm.responses.create(prompt, params)]
+    end
+
+    ##
+    # Executes a turn through the chat completions API.
+    # @api private
+    def complete(prompt, params)
+      params = params.merge(messages: @messages.to_a)
+      params = @params.merge(params)
+      prompt, params = transform(prompt, params)
+      bind!(params[:stream], params[:model], params[:tools])
+      [prompt, params, @llm.complete(prompt, params)]
+    end
+
+    ##
+    # Builds one guarded tool return for a blocked function call.
+    # @api private
     def guarded_return_for(function, warning)
       LLM::Function::Return.new(function.id, function.name, {
         error: true,
@@ -534,10 +541,4 @@ module LLM
       })
     end
   end
-
-  # Backward-compatible alias
-  Bot = Context
-
-  # Scheduled for removal in v6.0
-  deprecate_constant :Bot
 end

data/lib/llm/function/call_task.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::CallTask} class wraps a single direct function call
+  # behind the same task-like interface used by spawned concurrency modes.
+  class CallTask
+    ##
+    # @return [LLM::Function]
+    attr_reader :function
+
+    ##
+    # @param [LLM::Function] function
+    # @return [LLM::Function::CallTask]
+    def initialize(function)
+      @function = function
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      false
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      function.interrupt!
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [LLM::Function::Return]
+    def wait
+      function.call
+    end
+    alias_method :value, :wait
+
+    ##
+    # @return [Class]
+    def group_class
+      LLM::Function::TaskGroup
+    end
+  end
+end

data/lib/llm/function.rb

@@ -33,6 +33,7 @@ class LLM::Function
   require_relative "function/tracing"
   require_relative "function/array"
   require_relative "function/call_group"
+  require_relative "function/call_task"
   require_relative "function/task"
   require_relative "function/thread_group"
   require_relative "function/fiber_group"
@@ -210,6 +211,7 @@ class LLM::Function
   #
   # @param [Symbol] strategy
   #   Controls concurrency strategy:
+  #   - `:call`: Call the function sequentially without spawning
   #   - `:thread`: Use threads
   #   - `:task`: Use async tasks (requires async gem)
   #   - `:fork`: Use a forked child process (requires xchan.rb support)
@@ -221,6 +223,8 @@ class LLM::Function
   #   Returns a task whose `#value` is an {LLM::Function::Return}.
   def spawn(strategy)
     task = case strategy
+    when :call
+      CallTask.new(self)
     when :task
       LLM.require "async" unless defined?(::Async)
       Async { call! }
@@ -241,7 +245,7 @@ class LLM::Function
       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"
+      raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :call, :thread, :task, :fiber, :fork, or :ractor"
     end
     Task.new(task, self)
   ensure
@@ -295,6 +299,28 @@ class LLM::Function
     !@called && !@cancelled
   end
 
+  ##
+  # Returns an in-band error for an unresolved function call.
+  # @return [LLM::Function::Return]
+  def unavailable
+    Return.new(id, name, {
+      error: true,
+      type: LLM::NoSuchToolError.name,
+      message: "tool not found"
+    })
+  end
+
+  ##
+  # Returns an in-band error for a tool loop rate limit.
+  # @return [LLM::Function::Return]
+  def rate_limit
+    LLM::Function::Return.new(id, name, {
+      error: true,
+      type: LLM::ToolLoopError.name,
+      message: "tool loop rate limit reached"
+    })
+  end
+
   ##
   # @return [Hash]
   def adapt(provider)

data/lib/llm/provider.rb

@@ -339,6 +339,13 @@ class LLM::Provider
     LLM::Stream === stream || stream.respond_to?(:<<)
   end
 
+  ##
+  # @return [Boolean]
+  #  Returns true when an API key is configured
+  def key?
+    @key != nil && @key.to_s.strip.size > 0
+  end
+
   private
 
   def path(suffix)

data/lib/llm/providers/anthropic/stream_parser.rb

@@ -105,14 +105,14 @@ class LLM::Anthropic
     end
 
     def resolve_tool(tool)
-      registered = @stream.find_tool(tool["name"])
+      registered = @stream.__find__(tool["name"])
       fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
         fn.id = tool["id"]
         fn.arguments = LLM::Anthropic.parse_tool_input(tool["input"])
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
       end
-      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+      [fn, (registered ? nil : fn.unavailable)]
     end
   end
 end

data/lib/llm/providers/bedrock/stream_parser.rb

@@ -184,14 +184,14 @@ class LLM::Bedrock
 
     def resolve_tool(tool)
       payload = tool["toolUse"] || {}
-      registered = @stream.find_tool(payload["name"])
+      registered = @stream.__find__(payload["name"])
       fn = (registered || LLM::Function.new(payload["name"])).dup.tap do |f|
         f.id = payload["toolUseId"]
         f.arguments = payload["input"] || {}
         f.tracer = @stream.extra[:tracer]
         f.model = @stream.extra[:model]
       end
-      [fn, registered ? nil : @stream.tool_not_found(fn)]
+      [fn, registered ? nil : fn.unavailable]
     end
 
     def content

data/lib/llm/providers/google/stream_parser.rb

@@ -153,14 +153,14 @@ class LLM::Google
 
     def resolve_tool(part, cindex, pindex)
       call = part["functionCall"]
-      registered = @stream.find_tool(call["name"])
+      registered = @stream.__find__(call["name"])
       fn = (registered || LLM::Function.new(call["name"])).dup.tap do |fn|
         fn.id = LLM::Google.tool_id(part:, cindex:, pindex:)
         fn.arguments = call["args"]
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
       end
-      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+      [fn, (registered ? nil : fn.unavailable)]
     end
   end
 end

data/lib/llm/providers/openai/responses/stream_parser.rb

@@ -269,14 +269,14 @@ class LLM::OpenAI
     # @group Resolvers
 
     def resolve_tool(tool, arguments)
-      registered = @stream.find_tool(tool["name"])
+      registered = @stream.__find__(tool["name"])
       fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
         fn.id = tool["call_id"]
         fn.arguments = arguments
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
       end
-      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+      [fn, (registered ? nil : fn.unavailable)]
     end
 
     def parse_arguments(arguments)

data/lib/llm/providers/openai/stream_parser.rb

@@ -185,14 +185,14 @@ class LLM::OpenAI
     end
 
     def resolve_tool(tool, function, arguments)
-      registered = @stream.find_tool(function["name"])
+      registered = @stream.__find__(function["name"])
       fn = (registered || LLM::Function.new(function["name"])).dup.tap do |fn|
         fn.id = tool["id"]
         fn.arguments = arguments
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
       end
-      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+      [fn, (registered ? nil : fn.unavailable)]
     end
 
     def parse_arguments(arguments)

data/lib/llm/schema.rb

@@ -56,6 +56,8 @@ class LLM::Schema
     def resolve(schema, type)
       if LLM::Schema::Leaf === type
         type
+      elsif ::Array === type
+        resolve_array(schema, type)
       elsif Class === type && type.respond_to?(:object)
         type.object
       else
@@ -63,6 +65,15 @@ class LLM::Schema
         schema.public_send(target)
       end
     end
+
+    def resolve_array(schema, values)
+      item = if values.size == 1
+        resolve(schema, values[0])
+      else
+        schema.any_of(*values.map { resolve(schema, _1) })
+      end
+      schema.array(item)
+    end
   end
 
   ##

data/lib/llm/sequel/agent.rb

@@ -58,6 +58,11 @@ module LLM::Sequel
         agent.concurrency(concurrency)
       end
 
+      def confirm(*tool_names, &block)
+        return agent.confirm if tool_names.empty? && !block
+        agent.confirm(*tool_names, &block)
+      end
+
       def tracer(tracer = nil, &block)
         return agent.tracer if tracer.nil? && !block
         agent.tracer(tracer, &block)