llm.rb 13.1.0 → 14.0.0

data/lib/llm/agent.rb

@@ -18,11 +18,13 @@ module LLM
   # * Instructions are injected once unless a system message is already present.
   # * An agent automatically executes tool loops (unlike {LLM::Context LLM::Context}).
   # * The automatic tool loop enables the wrapped context's `guard` by default.
-  #   The built-in {LLM::LoopGuard LLM::LoopGuard} detects repeated tool-call
-  #   patterns and blocks stuck execution before more tool work is queued.
-  # * The default tool attempt budget is `25`. After that, the agent sends
-  #   advisory tool errors back through the model and keeps the loop in-band.
-  #   Set `tool_attempts: nil` to disable that advisory behavior.
+  #   The built-in {LLM::Guard::Loop LLM::Guard::Loop} detects repeated
+  #   tool-call patterns and blocks stuck execution before more tool work is
+  #   queued.
+  # * The tool loop can be bounded with `tool_budget`. Once the budget is
+  #   spent, the agent sends an in-band advisory message back through the
+  #   model and keeps the loop in-band. By default no budget is set
+  #   (`nil`), so the feature is disabled.
   # * Tool loop execution can be configured with `concurrency :sequential`,
   #   `:thread`, `:async`, `:fiber`, `:fork`, or `:ractor`.
   #
@@ -311,6 +313,28 @@ module LLM
       end
     end
 
+    ##
+    # Set or get the maximum number of tool calls
+    # that are allowed in a single turn. Once the
+    # budget is spent, we will return an in-band
+    # message that informs the model it has spent
+    # its tool call budget - and usually a model
+    # will change course afterwards.
+    # @note
+    #  By default this feature is disabled
+    #  (set to `nil`).
+    # @param [Integer] budget
+    #  The maximum number of tool calls to allow in
+    #  a single turn.
+    # @return [Integer, nil]
+    def self.tool_budget(budget = UNDEFINED, &block)
+      if budget.equal?(UNDEFINED)
+        @tool_budget
+      else
+        @tool_budget = budget || block
+      end
+    end
+
     ##
     # @param [LLM::Provider] llm
     #  A provider
@@ -326,9 +350,10 @@ module LLM
     # @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 = {})
+      params = {}.merge!(params)
       @llm = llm
-      fields = %i[name description path model skills schema tracer stream tools concurrency instructions confirm]
-      fields_ivar = %i[name description path tracer concurrency instructions confirm]
+      fields = %i[name description path tool_budget model skills schema tracer stream tools concurrency instructions confirm]
+      fields_ivar = %i[name description path tool_budget tracer concurrency instructions confirm]
       fields.each do |field|
         resolvable = params.key?(field) ? params.delete(field) : self.class.public_send(field)
         resolve_symbol = !%i[concurrency].include?(field)
@@ -342,7 +367,7 @@ module LLM
           instance_variable_set(:"@#{field}", resolved)
         end
       end
-      @ctx = LLM::Context.new(llm, {guard: true}.merge(params))
+      @ctx = LLM::Context.new(llm, {guard: LLM::Guard::Loop}.merge(params))
       @path and File.readable?(@path) ? @ctx.restore(path:) : nil
     end
 
@@ -374,10 +399,11 @@ module LLM
     #
     # @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.
+    # @option params [Integer] :tool_budget
+    #  The maximum number of tool calls that can be made in a single turn
+    #  before the agent sends an in-band advisory message that tells the model
+    #  it has spent its tool call budget - and usually the model will change
+    #  course after that. By default this feature is disabled (set to `nil`).
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
@@ -531,6 +557,13 @@ module LLM
       @ctx.context_window
     end
 
+    ##
+    # @see LLM::Context#compacted?
+    # @return [Boolean]
+    def compacted?
+      @ctx.compacted?
+    end
+
     ##
     # Start a minimalist repl that can interact
     # with the agent and its current state. This
@@ -681,7 +714,7 @@ module LLM
     def run_loop(prompt, params, target)
       run = proc do
         talk = @ctx.method(target)
-        max = params.key?(:tool_attempts) ? params.delete(:tool_attempts) : 25
+        max = params.key?(:tool_budget) ? params.delete(:tool_budget) : @tool_budget
         max = Integer(max) if max
         stream = params[:stream] || @ctx.params[:stream]
         params[:stream] = LLM::Stream.try(stream, extra: {concurrency:})
@@ -692,7 +725,7 @@ module LLM
               break unless @ctx.pending_functions?
               res = talk.call(call_functions, params)
             end
-            res = talk.call(@ctx.pending_functions.map(&:rate_limit), params) if @ctx.pending_functions?
+            res = talk.call(@ctx.pending_functions.map(&:budget_spent), params) if @ctx.pending_functions?
           else
             res = talk.call(call_functions, params)
           end

data/lib/llm/context.rb

@@ -83,13 +83,22 @@ module LLM
     #   {LLM::Compactor::Null}.
     # @option params [Hash] :compactor_options
     #   Options passed to the compactor's `call` method. Defaults to `{}`.
+    # @option params [Class<LLM::Transformer>, nil] :transformer
+    #   A transformer class to use for message transformation. Defaults to
+    #   {LLM::Transformer::Null}.
+    # @option params [Hash] :transformer_options
+    #   Options passed to the transformer's `call` method. Defaults to `{}`.
+    # @option params [Class<LLM::Guard>, nil] :guard
+    #   A guard class to supervise agentic tool execution. Defaults to
+    #   {LLM::Guard::Null}.
+    # @option params [Hash] :guard_options
+    #   Options passed to the guard's `call` method. Defaults to `{}`.
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
     # @option params [Array<String>, nil] :skills Defaults to nil
     def initialize(llm, params = {})
+      params = {}.merge!(params)
       @llm = llm
       @mode = params.delete(:mode) || (llm.name == :openai ? :responses : :completions)
-      @guard = params.delete(:guard)
-      @transformer = params.delete(:transformer)
       tools = [*params.delete(:tools), *load_skills(params.delete(:skills))]
       @params = {model: llm.default_model, schema: nil}.compact.merge!(params)
       @params[:tools] = tools unless tools.empty?
@@ -101,6 +110,14 @@ module LLM
         klass: params.delete(:compactor) || LLM::Compactor::Null,
         options: params.delete(:compactor_options) || {}
       }
+      @transformer = {
+        klass: params.delete(:transformer) || LLM::Transformer::Null,
+        options: params.delete(:transformer_options) || {}
+      }
+      @guard = {
+        klass: params.delete(:guard) || LLM::Guard::Null,
+        options: params.delete(:guard_options) || {}
+      }
     end
 
     ##
@@ -126,58 +143,35 @@ module LLM
     alias_method :compacted?, :compacted
 
     ##
-    # Returns a guard, if configured.
+    # Returns the configured guard class.
     #
     # Guards are context-level supervisors for agentic execution. A guard can
     # inspect the runtime state and decide whether pending tool work should be
     # blocked before the context keeps looping.
     #
-    # The built-in implementation is {LLM::LoopGuard LLM::LoopGuard}, which
+    # The guard is stamped onto the functions the context binds, so it runs
+    # whenever a task is spawned — including tool calls queued from a stream
+    # via {LLM::Stream#on_tool_call}. A blocked call yields its in-band
+    # `guard_error` return without executing.
+    #
+    # The built-in implementation is {LLM::Guard::Loop LLM::Guard::Loop}, which
     # detects repeated tool-call patterns and turns them into in-band
-    # {LLM::GuardError LLM::GuardError} tool returns.
+    # `guard_error` tool returns.
     #
-    # @return [#call, nil]
+    # @return [Class<LLM::Guard>]
     def guard
-      return if @guard.nil? || @guard == false
-      @guard = LLM::LoopGuard.new if @guard == true
-      @guard = LLM::LoopGuard.new(@guard) if Hash === @guard
-      @guard
-    end
-
-    ##
-    # Sets a guard or guard config.
-    #
-    # Guards must implement `call(ctx)` and return either `nil` or a warning
-    # string. Returning a warning tells the context to block pending tool work
-    # with guarded tool errors instead of continuing the loop.
-    #
-    # @param [#call, Hash, Boolean, nil] guard
-    # @return [#call, Hash, Boolean, nil]
-    def guard=(guard)
-      @guard = guard
+      @guard[:klass]
     end
 
     ##
-    # Returns a transformer, if configured.
+    # Returns the configured transformer class.
     #
-    # Transformers can rewrite outgoing prompts and params before a request is
-    # sent to the provider.
+    # Transformers rewrite the most recent message before it is sent to the
+    # provider.
     #
-    # @return [#call, nil]
+    # @return [Class<LLM::Transformer>]
     def transformer
-      @transformer
-    end
-
-    ##
-    # Sets a transformer.
-    #
-    # Transformers must implement `call(ctx, prompt, params)` and return a
-    # two-element array of `[prompt, params]`.
-    #
-    # @param [#call, nil] transformer
-    # @return [#call, nil]
-    def transformer=(transformer)
-      @transformer = transformer
+      @transformer[:klass]
     end
 
     # Interact with the context via the chat completions API.
@@ -197,10 +191,12 @@ module LLM
       repair!(@messages, prompt)
       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?
-      @messages.concat LLM::Prompt === prompt ? prompt.to_a : [LLM::Message.new(role, prompt)]
-      @messages.concat [res.choices[-1]].compact
+      if prompt.all?(&:tool_return?)
+        @messages.concat prompt.map { LLM::Message.new(@llm.tool_role, _1.content, _1.extra) }
+      else
+        @messages.concat(prompt)
+      end
+      @messages.concat([res.choices[-1]].compact)
       res
     ensure
       @owner = nil
@@ -245,6 +241,7 @@ module LLM
     # @return [Array<LLM::Function>]
     def pending_functions
       return_ids = returns.map(&:id)
+      guard = @guard[:klass].new(self)
       @messages
         .select(&:assistant?)
         .flat_map do |msg|
@@ -252,9 +249,11 @@ module LLM
           fns.each do |fn|
             fn.tracer = tracer
             fn.model  = msg.model
+            fn.guard  = guard
           end
         end.extend(LLM::Function::Array)
     end
+
     ##
     # Returns whether there is pending tool work in this context.
     # This prefers queued streamed tool work when present, and otherwise
@@ -268,15 +267,10 @@ module LLM
     ##
     # Spawns a function through the context.
     #
-    # When a guard is configured, this method can return an in-band guarded
-    # tool error instead of spawning work.
-    #
     # @param [LLM::Function] function
     # @param [Symbol] strategy
-    # @return [LLM::Function::Return, LLM::Function::Task]
+    # @return [LLM::Function::Task]
     def spawn(function, strategy)
-      warning = guard&.call(self)
-      return guarded_return_for(function, warning) if warning
       function.task(strategy)
     end
 
@@ -310,9 +304,11 @@ module LLM
     # @return [Array<LLM::Function::Return>]
     def wait(strategy, except: [])
       if stream.queue.empty?
-        tools  = except.empty? ? pending_functions : pending_functions - except
-        guards = guarded_returns(tools:)
-        return guards if guards
+        ##
+        # Every pending function is spawned as a task that checks its own
+        # guard (stamped on the function) before running. Blocked tasks
+        # yield their guard's return, so all pending calls still close.
+        tools = except.empty? ? pending_functions : pending_functions - except
         @queue = tools.task(strategy)
         returns = @queue.wait
         emit_tool_returns(tools, returns)
@@ -513,65 +509,52 @@ module LLM
       [*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(tools:)
-      warning = guard&.call(self)
-      return unless warning
-      tools.map { guarded_return_for(_1, warning) }
-    end
-
     ##
     # Rewrites a prompt and params through the configured transformer.
     # @api private
-    def transform(prompt, params)
-      transformer = self.transformer
-      return [prompt, params] unless transformer
+    def transform(prompt, params, key: :messages)
+      transformer = @transformer[:klass].new(self)
       stream = params[:stream]
-      stream.on_transform(self, transformer)
-      transformer.call(self, prompt, params)
+      stream.on_transform(transformer)
+      role = params[:role] || @llm.user_role
+      messages = @llm.build_messages(prompt, params, role, key:)
+      messages[-1] = transformer.call(message: messages[-1], **@transformer[:options])
+      messages
     ensure
-      stream.on_transform_finish(self, transformer) if transformer
+      stream.on_transform_finish(transformer)
     end
 
     ##
     # Executes a turn through the Responses API.
     # @api private
     def respond(prompt, params)
+      history = @messages.to_a
       params = @params.merge(params)
-      extra = params.slice(:model, :tools).merge!(ctx: self, tracer:)
+      extra = params.slice(:model, :tools).merge!(ctx: self, tracer:, guard: @guard[:klass].new(self))
       params[:stream] = LLM::Stream.try(params[:stream], extra:)
-      prompt, params = transform(prompt, params)
-      @stream = params[:stream]
       res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
-      input = res_id ? [] : @messages.to_a
+      input = res_id ? [] : history
+      params[:input] = input
+      messages = transform(prompt, params, key: :input)
+      @stream = params[:stream]
+      new_messages = messages[input.size..]
       params = params.merge(previous_response_id: res_id, input:).compact
-      [prompt, params, @llm.responses.create(prompt, params)]
+      [new_messages, params, @llm.responses.create(messages, params)]
     end
 
     ##
     # Executes a turn through the chat completions API.
     # @api private
     def complete(prompt, params)
-      params = params.merge(messages: @messages.to_a)
+      history = @messages.to_a
+      params = params.merge(messages: history)
       params = @params.merge(params)
-      extra = params.slice(:model, :tools).merge!(ctx: self, tracer:)
+      extra = params.slice(:model, :tools).merge!(ctx: self, tracer:, guard: @guard[:klass].new(self))
       params[:stream] = LLM::Stream.try(params[:stream], extra:)
-      prompt, params = transform(prompt, params)
+      messages = transform(prompt, params)
       @stream = params[:stream]
-      [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,
-        type: LLM::GuardError.name,
-        message: warning
-      })
+      new_messages = messages[history.size..]
+      [new_messages, params, @llm.complete(messages, params)]
     end
 
     ##

data/lib/llm/cost.rb

@@ -7,27 +7,27 @@
 # and reasoning costs separately and can return the total.
 #
 # @attr [Float] input_costs
-#   Returns the input cost
+#   Returns the input cost, aliased as `input`
 # @attr [Float] output_costs
-#   Returns the output cost
+#   Returns the output cost, aliased as `output`
 # @attr [Float, nil] input_audio_costs
 #   Returns the input audio cost, or nil when no input audio tokens
-#   were used
+#   were used, aliased as `input_audio`
 # @attr [Float, nil] output_audio_costs
 #   Returns the output audio cost, or nil when no output audio tokens
-#   were used
+#   were used, aliased as `output_audio`
 # @attr [Float, nil] input_image_costs
 #   Returns the input image cost, or nil when no input image tokens
-#   were used
+#   were used, aliased as `input_image`
 # @attr [Float, nil] cache_read_costs
 #   Returns the cache read cost, or nil when no cache tokens
-#   were used
+#   were used, aliased as `cache_read`
 # @attr [Float, nil] cache_write_costs
 #   Returns the cache write cost, or nil when no cache creation
-#   tokens were used
+#   tokens were used, aliased as `cache_write`
 # @attr [Float, nil] reasoning_costs
 #   Returns the reasoning cost, or nil when no reasoning tokens
-#   were used
+#   were used, aliased as `reasoning`
 class LLM::Cost < Struct.new(
   :input_costs, :output_costs,
   :input_audio_costs, :output_audio_costs,
@@ -82,15 +82,10 @@ class LLM::Cost < Struct.new(
   #  Returns a hash with the non-nil cost components and the total
   def to_h
     {
-      input: input_costs,
-      output: output_costs,
-      input_audio: input_audio_costs,
-      output_audio: output_audio_costs,
-      input_image: input_image_costs,
-      cache_read: cache_read_costs,
-      cache_write: cache_write_costs,
-      reasoning: reasoning_costs,
-      total: total
+      input:, output:,
+      cache_read:, cache_write:,
+      input_audio:, output_audio:, input_image:,
+      reasoning:, total:
     }.compact
   end
 
@@ -100,4 +95,15 @@ class LLM::Cost < Struct.new(
   def to_s
     format("%.12f", total).sub(/\.?0+$/, "")
   end
+
+  ##
+  # Aliases
+  alias_method :input, :input_costs
+  alias_method :output, :output_costs
+  alias_method :input_audio, :input_audio_costs
+  alias_method :output_audio, :output_audio_costs
+  alias_method :cache_read, :cache_read_costs
+  alias_method :cache_write, :cache_write_costs
+  alias_method :input_image, :input_image_costs
+  alias_method :reasoning, :reasoning_costs
 end

data/lib/llm/error.rb

@@ -55,14 +55,6 @@ module LLM
   # When the context window is exceeded
   ContextWindowError = Class.new(InvalidRequestError)
 
-  ##
-  # When stuck in a tool call loop
-  ToolLoopError = Class.new(Error)
-
-  ##
-  # When a guard blocks pending tool execution
-  GuardError = Class.new(Error)
-
   ##
   # When a request is interrupted
   Interrupt = Class.new(Error)

data/lib/llm/function/async/task.rb

@@ -32,6 +32,7 @@ module LLM::Function::Async
     # pushed to a queue that {#wait} consumes.
     # @return [nil]
     def spawn
+      return if @guarded
       @queue = Queue.new
       @alive = true
       @reactor.submit do
@@ -66,6 +67,7 @@ module LLM::Function::Async
     # Wait for the result queue to contain a value.
     # @return [LLM::Function::Return]
     def wait
+      return @guarded if @guarded
       spawn unless @queue
       result = @queue.pop
       @alive = false

data/lib/llm/function/fiber/task.rb

@@ -22,6 +22,7 @@ module LLM::Function::Fiber
     ##
     # @return [nil]
     def spawn
+      return if @guarded
       if Fiber.scheduler.nil?
         raise ArgumentError, "Fiber concurrency requires Fiber.scheduler"
       else
@@ -48,6 +49,7 @@ module LLM::Function::Fiber
     ##
     # @return [LLM::Function::Return]
     def wait
+      return @guarded if @guarded
       spawn unless @fiber
       @result ||= @fiber.value
     end

data/lib/llm/function/fork/task.rb

@@ -20,6 +20,7 @@ class LLM::Function
     ##
     # @return [LLM::Function::Fork::Task]
     def spawn
+      return if @guarded
       @span = @tracer&.on_tool_start(
         id: @function.id, name: @function.name,
         arguments: @function.arguments, model: @function.model
@@ -59,6 +60,7 @@ class LLM::Function
     ##
     # @return [LLM::Function::Return]
     def wait
+      return @guarded if @guarded
       spawn unless @spawned
       kind, data = @ch.result.recv
       raise LLM::Interrupt if kind == :interrupt

data/lib/llm/function/ractor/task.rb

@@ -33,6 +33,7 @@ class LLM::Function
     ##
     # @return [LLM::Function::Ractor::Task]
     def spawn
+      return if @guarded
       @span = @tracer&.on_tool_start(
         id: @id, name: @name,
         arguments: @arguments, model: @model
@@ -58,6 +59,7 @@ class LLM::Function
     ##
     # @return [LLM::Function::Return]
     def wait
+      return @guarded if @guarded
       spawn unless @mailbox
       id, name, value = mailbox.wait
       result = Return.new(id, name, value)

data/lib/llm/function/sequential/group.rb

@@ -39,7 +39,10 @@ module LLM::Function::Sequential
     # @return [Array<LLM::Function::Return>]
     def wait
       @owner = Thread.current
-      @functions.map(&:call)
+      ##
+      # Sequential groups call functions directly (no tasks), so each
+      # function's guard is checked here instead.
+      @functions.map { |function| function.guard&.call(function:) || function.call }
     ensure
       @owner = nil
     end

data/lib/llm/function/sequential/task.rb

@@ -36,7 +36,7 @@ module LLM::Function::Sequential
     ##
     # @return [LLM::Function::Return]
     def wait
-      @result ||= function.call
+      @result ||= @guarded || function.call
     end
     alias_method :value, :wait
 

data/lib/llm/function/task.rb

@@ -16,8 +16,12 @@ class LLM::Function
     # @param [Hash] options
     #  An optional set of options that are specific
     #  to a given concurrency strategy.
+    # @option options [LLM::Function::Return, nil] :guarded
+    #  A blocked return produced by the function's guard. When set, the
+    #  task yields it without running the tool.
     def initialize(fn, options = {})
       @function = fn
+      @guarded = options[:guarded]
     end
 
     ##

data/lib/llm/function/thread/task.rb

@@ -23,6 +23,7 @@ module LLM::Function::Thread
     ##
     # @return [nil]
     def spawn
+      return if @guarded
       @thread = ::Thread.new { function.call }
       @thread.report_on_exception = false
       nil
@@ -46,6 +47,7 @@ module LLM::Function::Thread
     ##
     # @return [LLM::Function::Return]
     def wait
+      return @guarded if @guarded
       spawn unless @thread
       @thread.value
     end

data/lib/llm/function.rb

@@ -155,6 +155,13 @@ class LLM::Function
   # @return [String, nil]
   attr_accessor :model
 
+  ##
+  # Returns the guard class that protects this function, or nil.
+  # The context stamps the guard onto the functions it binds, so any task
+  # built from this function checks it before the tool runs.
+  # @return [Class<LLM::Guard>, nil]
+  attr_accessor :guard
+
   ##
   # @param [String] name The function name
   # @yieldparam [LLM::Function] self The function object
@@ -250,6 +257,11 @@ class LLM::Function
   # @return [LLM::Function::Task]
   #   Returns a task whose `#value` is an {LLM::Function::Return}.
   def task(strategy, options = {})
+    ##
+    # Check the function's guard on the calling thread before handing
+    # the tool to the strategy. The task carries the blocked result and
+    # returns it without running if the guard intervenes.
+    options = options.merge(guarded: @guard&.call(function: self))
     case strategy
     when :sequential
       Sequential::Task.new(self, options)
@@ -340,16 +352,32 @@ class LLM::Function
   end
 
   ##
-  # Returns an in-band error for a tool loop rate limit.
+  # Returns an in-band error that indicates the tool
+  # call budget has been spent.
   # @return [LLM::Function::Return]
-  def rate_limit
+  def budget_spent
     LLM::Function::Return.new(id, name, {
       error: true,
-      type: LLM::ToolLoopError.name,
-      message: "tool loop rate limit reached"
+      type: "LLM::BudgetSpentError",
+      message: "the tool call budget for this turn has been spent. " \
+               "try to solve the problem with less tool calls."
     })
   end
 
+  ##
+  # Builds an {LLM::Function::Return LLM::Function::Return} for this
+  # function, using its own id and name. The given keywords become the
+  # return's value.
+  # @note
+  #   `return` is a Ruby keyword, so this is defined via
+  #   {Kernel#define_method Kernel#define_method}.
+  # @param [Hash] value
+  #  The return content, eg `{error: true, type: ..., message: ...}`.
+  # @return [LLM::Function::Return]
+  define_method(:return) do |value|
+    Return.new(id, name, value)
+  end
+
   ##
   # @return [Hash]
   def adapt(provider)