llm.rb 9.0.0 → 11.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,29 +221,13 @@ 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, :talk)
     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)
+    # @see LLM::Context#ask
+    def ask(prompt, params = {})
+      run_loop(prompt, params, :ask)
     end
 
     ##
@@ -347,6 +354,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]
@@ -357,13 +371,13 @@ module LLM
     ##
     # @return [String]
     def to_json(...)
-      to_h.to_json(...)
+      LLM.json.dump(to_h, ...)
     end
 
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "#<#{LLM::Utils.object_id(self)} " \
       "@llm=#{@llm.class}, @mode=#{mode.inspect}, @messages=#{messages.inspect}>"
     end
 
@@ -383,19 +397,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 +444,47 @@ 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, target)
+      run = proc do
+        talk = @ctx.method(target)
         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 = talk.call(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 = talk.call(call_functions, params)
             end
-            break unless @ctx.functions?
-            res = @ctx.public_send(method, @ctx.functions.map { rate_limit(_1) }, params)
+            res = talk.call(@ctx.functions.map(&:rate_limit), params) if @ctx.functions?
           else
-            res = @ctx.public_send(method, call_functions, params)
+            res = talk.call(call_functions, params)
           end
         end
         res
       end
-      @tracer ? @llm.with_tracer(@tracer, &loop) : loop.call
+      return run.call unless @tracer
+      @llm.with_tracer(@tracer, &run)
     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"
-      })
-    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/buffer.rb

@@ -97,8 +97,7 @@ module LLM
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
-      "message_count=#{@messages.size}>"
+      "#<#{LLM::Utils.object_id(self)} message_count=#{@messages.size}>"
     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?
@@ -206,41 +201,37 @@ module LLM
       @messages.concat [res.choices[-1]]
       res
     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
+    # Ask a question and return the content string directly.
+    # Accepts `with:` for file attachments and a block for streaming.
+    # This interface is compatible with RubyLLM's `ask` method.
+    # @param [String] prompt
+    # @param [Hash] options
+    # @option options [String, Array<String>, nil] :with
+    #  File path(s) to attach
+    # @option options [#<<, LLM::Stream, nil] :stream
+    #  A stream target
+    # @yield [String] content chunks when streaming
+    # @return [LLM::Response]
+    def ask(prompt, options = {}, &block)
+      options = {with: nil, stream: nil}.merge!(options || {})
+      with, stream = options.values_at(:with, :stream)
+      prompt = with ? [prompt, [*with].map { local_file(_1) }] : prompt
+      target = if block
+        blk = block.dup
+        blk.singleton_class.alias_method(:<<, :call)
+        blk
+      else
+        stream
+      end
+      target ? talk(prompt, stream: target) : talk(prompt)
     end
 
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "#<#{LLM::Utils.object_id(self)} " \
       "@llm=#{@llm.class}, @mode=#{@mode.inspect}, @params=#{@params.inspect}, " \
       "@messages=#{@messages.inspect}>"
     end
@@ -448,7 +439,7 @@ module LLM
     ##
     # @return [String]
     def to_json(...)
-      to_h.to_json(...)
+      LLM.json.dump(to_h, ...)
     end
 
     ##
@@ -493,6 +484,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 +496,34 @@ 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
+      [@queue, stream&.queue].compact.first
+    rescue NoMethodError
+      nil
     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 +533,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 +567,4 @@ module LLM
       })
     end
   end
-
-  # Backward-compatible alias
-  Bot = Context
-
-  # Scheduled for removal in v6.0
-  deprecate_constant :Bot
 end

data/lib/llm/file.rb

@@ -43,6 +43,13 @@ class LLM::File
     mime_type == "application/pdf"
   end
 
+  ##
+  # @return [Boolean]
+  #  Returns true if the file exists on disk
+  def exist?
+    File.exist?(path)
+  end
+
   ##
   # @return [Integer]
   #  Returns the size of the file in bytes

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"
@@ -181,7 +182,7 @@ class LLM::Function
   def define(klass = nil, &b)
     @runner = klass || b
   end
-  alias_method :register, :define
+  alias_method :def, :define
 
   ##
   # Call the function
@@ -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/mcp/transport/http.rb

@@ -7,7 +7,7 @@ module LLM::MCP::Transport
   # JSON-RPC messages with HTTP POST requests and buffers response
   # messages for non-blocking reads.
   class HTTP
-    require_relative "http/event_handler"
+    include LLM::Transport::Utils
 
     ##
     # @param [String] url
@@ -22,7 +22,7 @@ module LLM::MCP::Transport
     def initialize(url:, headers: {}, timeout: nil, transport: nil)
       @uri = URI.parse(url)
       @headers = headers
-      @transport = resolve_transport(transport, timeout:)
+      @transport = resolve_transport(uri, transport, timeout)
       @queue = []
       @monitor = Monitor.new
       @running = false
@@ -101,24 +101,11 @@ module LLM::MCP::Transport
       res
     end
 
-    def resolve_transport(transport, timeout:)
-      return default_transport(timeout:) if transport.nil?
-      if Class === transport && transport <= LLM::Transport
-        return transport.new(host: uri.host, port: uri.port, timeout:, ssl: uri.scheme == "https")
-      end
-      transport
-    end
-
-    def default_transport(timeout:)
-      LLM::Transport::HTTP.new(host: uri.host, port: uri.port, timeout:, ssl: uri.scheme == "https")
-    end
-
     def read(res)
       if res["content-type"].to_s.include?("text/event-stream")
-        parser = LLM::EventStream::Parser.new
-        parser.register EventHandler.new { enqueue(_1) }
-        res.read_body { parser << _1 }
-        parser.free
+        decoder = LLM::Transport::StreamDecoder.new { enqueue(_1) }
+        res.read_body { decoder << _1 }
+        decoder.free
       else
         body = +""
         res.read_body { body << _1 }