llm.rb 13.0.0 → 14.0.0

data/lib/llm/agent.rb

@@ -11,20 +11,22 @@ module LLM
   # {LLM::Context LLM::Context}: message history, usage, persistence,
   # streaming parameters, and provider-backed requests still flow through
   # an underlying context. The defining behavior of an agent is that it
-  # automatically resolves pending tool calls for you during `talk` and
-  # `respond`, instead of leaving tool loops to the caller.
+  # automatically resolves pending tool calls for you during `talk`,
+  # instead of leaving tool loops to the caller.
   #
   # **Notes:**
   # * 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`, or `:ractor`.
+  #   `:thread`, `:async`, `:fiber`, `:fork`, or `:ractor`.
   #
   # @example Subclass with defaults
   #   class SystemAdmin < LLM::Agent
@@ -52,6 +54,16 @@ module LLM
     UNDEFINED = Object.new
     private_constant :UNDEFINED
 
+    ##
+    # @api private
+    CASE_PATTERN = /(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/
+    private_constant :CASE_PATTERN
+
+    ##
+    # @api private
+    File = ::File
+    private_constant :File
+
     ##
     # Returns a provider
     # @return [LLM::Provider]
@@ -96,18 +108,44 @@ module LLM
 
     ##
     # Set or get an agent's name
+    # @note
+    #  This method serves as a self-documenting string
+    #  and it is used by {LLM::Repl LLM::Repl}. It is
+    #  optional but recommended.
     # @param [String] name
     #  The agent name
     # @return [String]
     #  Return's the agents name
     def self.name(name = UNDEFINED, &block)
       if name.equal?(UNDEFINED)
-        @name || self.to_s.gsub(/(.)([A-Z])/, '\\1-\\2').downcase
+        if @name.nil?
+          name  = to_s.split("::").last
+          @name = name.gsub(CASE_PATTERN, "-").downcase
+        else
+          @name
+        end
       else
         @name = block || name
       end
     end
 
+    ##
+    # Set or get an agent's description
+    # @note
+    #  This method serves as a self-documenting string.
+    #  It is optional but recommended.
+    # @param [String] desc
+    #  The agent's description
+    # @return [String, nil]
+    #  Returns the agent's description
+    def self.description(desc = UNDEFINED, &block)
+      if desc.equal?(UNDEFINED)
+        @desc
+      else
+        @desc = block || desc
+      end
+    end
+
     ##
     # Set or get the default model
     # @param [String, nil] model
@@ -261,6 +299,42 @@ module LLM
       end
     end
 
+    ##
+    # Set the file path where an agent's memory
+    # can be restored from, and written to.
+    # @param [String] path
+    #  The path to a file
+    # @return [String, nil]
+    def self.path(path = UNDEFINED, &block)
+      if path.equal?(UNDEFINED)
+        @path
+      else
+        @path = path || block
+      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
@@ -276,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 model skills schema tracer stream tools concurrency instructions confirm]
-      fields_ivar = %i[name 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)
@@ -292,7 +367,8 @@ 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
 
     ##
@@ -302,16 +378,32 @@ module LLM
       @name
     end
 
+    ##
+    # Returns a file path where an agent's memory is
+    # restored from, and written to after each turn.
+    # @return [String, nil]
+    def path
+      @path
+    end
+
+    ##
+    # Returns the agent's description
+    # @return [String, nil]
+    def description
+      @description
+    end
+
     ##
     # Maintain a conversation via the chat completions API.
     # This method immediately sends a request to the LLM and returns the response.
     #
     # @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"])
@@ -319,13 +411,17 @@ module LLM
     #   response = agent.talk("Hello, what is your name?")
     #   puts response.choices[0].content
     def talk(prompt, params = {})
-      run_loop(prompt, params, :talk)
+      res = run_loop(prompt, params, :talk)
+      path ? @ctx.save(path:) : nil
+      res
     end
 
     ##
     # @see LLM::Context#ask
     def ask(prompt, params = {})
-      run_loop(prompt, params, :ask)
+      res = run_loop(prompt, params, :ask)
+      path ? @ctx.save(path:) : nil
+      res
     end
 
     ##
@@ -461,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
@@ -611,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:})
@@ -622,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/array.rb

@@ -3,7 +3,7 @@
 class LLM::Function
   ##
   # The {LLM::Function::Array} module extends the array
-  # returned by {LLM::Context#functions} with methods
+  # returned by {LLM::Context#pending_functions} with methods
   # that can call all pending functions sequentially or
   # concurrently. The return values can be reported back
   # to the LLM on the next turn.
@@ -57,9 +57,9 @@ class LLM::Function
     #
     # @param [Symbol] strategy
     #   Controls concurrency strategy:
-    #   - `:call`: Call each function sequentially through a call group
+    #   - `:sequential`: Call functions sequentially without spawning
     #   - `:thread`: Use threads
-    #   - `:task`: Use async tasks (requires async gem)
+    #   - `:async`: Use async tasks (requires async gem)
     #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
     #   - `:fork`: Use forked child processes
     #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)

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