llm.rb 16.0.0 → 17.0.1

data/lib/llm/provider.rb

@@ -32,7 +32,7 @@ class LLM::Provider
   #  Requires the net-http-persistent gem.
   # @param [LLM::Transport, Class, nil] transport
   #  Optional override with any {LLM::Transport} instance or subclass.
-  def initialize(key:, host:, port: 443, timeout: 600, read_timeout: nil, connect_timeout: 5, ssl: true, base_path: "", persistent: false, transport: nil)
+  def initialize(key:, host:, port: 443, timeout: 240, read_timeout: nil, connect_timeout: 5, ssl: true, base_path: "", persistent: false, transport: nil)
     @key = key
     @host = host
     @port = port
@@ -482,6 +482,21 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # Returns an array of exceptions that a request
+  # could raise and that will be retried up to
+  # {LLM::Provider#retry_budget} times.
+  # @return [Array<Exception>]
+  def retry_errors
+    [
+      LLM::InsufficientQuotaError,
+      LLM::RateLimitError,
+      Net::ReadTimeout,
+      Net::WriteTimeout,
+      Net::OpenTimeout
+    ]
+  end
+
   private
 
   def path(suffix, base_path: true)

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

@@ -102,7 +102,7 @@ class LLM::Anthropic
         fn.arguments = LLM::Anthropic.parse_tool_input(tool["input"])
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
-        fn.guard = @stream.extra[:guard]
+        fn.intercept = @stream.extra[:intercept]
       end
       [fn, (registered ? nil : fn.unavailable)]
     end

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

@@ -181,7 +181,7 @@ class LLM::Bedrock
         f.arguments = payload["input"] || {}
         f.tracer = @stream.extra[:tracer]
         f.model = @stream.extra[:model]
-        f.guard = @stream.extra[:guard]
+        f.intercept = @stream.extra[:intercept]
       end
       [fn, registered ? nil : fn.unavailable]
     end

data/lib/llm/providers/deepseek/files.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class LLM::DeepSeek
+  ##
+  # The {LLM::DeepSeek::Files LLM::DeepSeek::Files} class provides a files
+  # object for interacting with [DeepSeek's Files API](https://api-docs.deepseek.com/guides/files_api).
+  # The files API lets a client upload images and reference them later by
+  # `file_id` - for example in chat requests to `deepseek-flash` - without
+  # re-uploading them. DeepSeek supports the JPEG, PNG, GIF, and WebP formats,
+  # and a single file may be at most 64 MiB.
+  #
+  # DeepSeek's Files API is OpenAI-compatible, with two differences from
+  # OpenAI's: it is served from the root of the API host (not under `/v1`),
+  # and the `purpose` of an upload must be `"user_data"`.
+  #
+  # @example example #1
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.deepseek(key: ENV["KEY"])
+  #   file = llm.files.create file: "/images/photo.jpg"
+  #   print "id: ", file.id, "\n"
+  class Files < LLM::OpenAI::Files
+    ##
+    # Create a file
+    # @example
+    #   llm = LLM.deepseek(key: ENV["KEY"])
+    #   res = llm.files.create file: "/images/photo.jpg"
+    # @see https://api-docs.deepseek.com/guides/files_api DeepSeek docs
+    # @param [File, LLM::File, String] file The file
+    # @param [String] purpose The purpose of the file (DeepSeek only supports "user_data")
+    # @param [Hash] params Other parameters (see DeepSeek docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create(file:, purpose: "user_data", **params)
+      super
+    end
+
+    private
+
+    ##
+    # DeepSeek serves its Files API from the root of the API host,
+    # while the rest of its OpenAI-compatible API lives under `/v1`
+    # @see https://api-docs.deepseek.com/guides/files_api DeepSeek docs
+    def path(suffix, **)
+      @provider.send(:path, suffix, base_path: false)
+    end
+  end
+end

data/lib/llm/providers/deepseek/request_adapter/completion.rb

@@ -35,7 +35,7 @@ module LLM::DeepSeek::RequestAdapter
       when String
         [{type: :text, text: content.to_s}]
       when LLM::Response
-        no_files_api!("response")
+        adapt_remote_file(content)
       when LLM::Message
         adapt_content(content.content)
       when LLM::Function::Return
@@ -57,7 +57,7 @@ module LLM::DeepSeek::RequestAdapter
       when :local_file
         adapt_local_file(object.value)
       when :remote_file
-        no_files_api!("remote file")
+        adapt_remote_file(object.value)
       else
         prompt_error!(object)
       end
@@ -80,17 +80,19 @@ module LLM::DeepSeek::RequestAdapter
     end
 
     ##
-    # Raises for a file that lives on the provider's side. DeepSeek
-    # has no Files API, so a file id that another provider minted
-    # cannot be resolved here.
-    # @param [String] subject
-    #  A description of the rejected content
-    # @raise [LLM::PromptError]
-    # @return [void]
-    def no_files_api!(subject)
-      raise LLM::PromptError, "The given #{subject} is not supported by the DeepSeek " \
-                              "chat completions API: DeepSeek has no Files API, so a " \
-                              "file id cannot be resolved"
+    # Adapts a file that lives on the provider's side as a `file` content
+    # block that references it by `file_id`, which DeepSeek's chat
+    # completions API accepts for images uploaded through its Files API
+    # @see https://api-docs.deepseek.com/guides/files_api DeepSeek docs
+    # @param [LLM::Object, LLM::Response] file The file
+    # @return [Array<Hash>]
+    # @raise [LLM::PromptError] when the given object is not a file
+    def adapt_remote_file(file)
+      if file.file?
+        [{type: :file, file_id: file.id}]
+      else
+        prompt_error!(file)
+      end
     end
 
     def adapt_message

data/lib/llm/providers/deepseek.rb

@@ -20,6 +20,7 @@ module LLM
   class DeepSeek < OpenAI
     require_relative "deepseek/request_adapter"
     require_relative "deepseek/response_adapter"
+    require_relative "deepseek/files"
     require_relative "deepseek/images"
     include DeepSeek::RequestAdapter
 
@@ -38,9 +39,11 @@ module LLM
     end
 
     ##
-    # @raise [NotImplementedError]
+    # Provides an interface to DeepSeek's files API
+    # @see https://api-docs.deepseek.com/guides/files_api DeepSeek docs
+    # @return [LLM::DeepSeek::Files]
     def files
-      raise NotImplementedError
+      LLM::DeepSeek::Files.new(self)
     end
 
     ##
@@ -80,5 +83,16 @@ module LLM
     def default_model
       "deepseek-flash"
     end
+
+    ##
+    # @note
+    #  This method extends the default errors
+    #  that are retried to include LLM::ServerError -
+    #  a common error that DeepSeek returns when
+    #  it is overloaded.
+    # @return [Array<Exception>]
+    def retry_errors
+      super.concat [LLM::ServerError]
+    end
   end
 end

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

@@ -150,7 +150,7 @@ class LLM::Google
         fn.arguments = call["args"]
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
-        fn.guard = @stream.extra[:guard]
+        fn.intercept = @stream.extra[:intercept]
       end
       [fn, (registered ? nil : fn.unavailable)]
     end

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

@@ -265,7 +265,7 @@ class LLM::OpenAI
         fn.arguments = arguments
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
-        fn.guard = @stream.extra[:guard]
+        fn.intercept = @stream.extra[:intercept]
       end
       [fn, (registered ? nil : fn.unavailable)]
     end

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

@@ -180,7 +180,7 @@ class LLM::OpenAI
         fn.arguments = arguments
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
-        fn.guard = @stream.extra[:guard]
+        fn.intercept = @stream.extra[:intercept]
       end
       [fn, (registered ? nil : fn.unavailable)]
     end

data/lib/llm/stream.rb

@@ -132,14 +132,15 @@ module LLM
     end
 
     ##
-    # Called when a streamed tool call has been fully constructed.
-    # A stream implementation may start tool execution here by pushing
-    # `@queue << tool.task(:thread).tap(&:spawn)` onto {#queue} — `spawn`
-    # returns nil, so `tap` keeps the task while starting it. The task
-    # carries the context's guard, so it is checked before the tool runs —
-    # a blocked call yields its guard return without executing.
+    # This method is called when the model
+    # requests a tool call. A little known
+    # feature: it is possible to spawn a tool
+    # call during a stream through:
+    #
+    #   @queue << tool.task(:thread).tap(&:spawn)
+    #
     # @param [LLM::Function] tool
-    #  The parsed tool call.
+    #  An instance of {LLM::Function LLM::Function}
     # @return [nil]
     def on_tool_call(tool)
       nil

data/lib/llm/tool.rb

@@ -205,7 +205,7 @@ class LLM::Tool
   # @return [Class<LLM::Tool>]
   # @raise [LLM::NoSuchToolError]
   def self.find_by_name!(name)
-    find_by_name(name) || raise(LLM::NoSuchToolError, "no such tool #{name.inspect}")
+    find_by_name(name) || raise(LLM::NoSuchToolError, "tool '#{name}' not found")
   end
 
   ##

data/lib/llm/tools/utils.rb

@@ -122,7 +122,7 @@ class LLM::Tool
 
     ##
     # requires test-cmd.rb
-    LLM.require "test-cmd.rb", "~> 2.7.1"
+    LLM.require "test-cmd.rb", "~> 2.7.3"
     Command = Test::Command
   end
 end

data/lib/llm/tracer/logger.rb

@@ -56,8 +56,12 @@ module LLM
     end
 
     ##
+    # @note An "ending" describes the method
+    #  that matches the end of a tool call, and it can be one of:
+    #  on_tool_finish, on_tool_error or on_tool_interrupt.
     # @param (see LLM::Tracer#on_tool_start)
-    # @return [void]
+    # @return [LLM::Object]
+    #  The span an ending is handed, with the call's id and name
     def on_tool_start(id:, name:, arguments:, model:, **)
       @logger.info(
         tracer: "llm.rb (logger)",
@@ -69,6 +73,7 @@ module LLM
         tool_arguments: arguments,
         model:
       )
+      LLM::Object.from(id:, name:)
     end
 
     ##
@@ -95,11 +100,47 @@ module LLM
         event: "tool.error",
         provider: provider_name,
         operation: "execute_tool",
+        error_class: ex.value[:type],
+        error_message: ex.value[:message]
+      )
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_interrupt)
+    # @return [void]
+    def on_tool_interrupt(ex:, span:, **)
+      @logger.info(
+        tracer: "llm.rb (logger)",
+        event: "tool.interrupt",
+        provider: provider_name,
+        operation: "execute_tool",
+        tool_id: span.id,
+        tool_name: span.name,
         error_class: ex.class.to_s,
         error_message: ex.message
       )
     end
 
+    ##
+    # @param (see LLM::Tracer#on_interrupt)
+    # @return [void]
+    def on_interrupt(scope:, request_id: nil, **)
+      @logger.info(
+        tracer: "llm.rb (logger)",
+        event: "#{scope}.interrupt",
+        provider: provider_name,
+        scope:,
+        request_id:
+      )
+    end
+
+    ##
+    # No-op.
+    # @return [nil]
+    def on_exit
+      nil
+    end
+
     private
 
     ##

data/lib/llm/tracer/multi.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+class LLM::Tracer
+  ##
+  # A tracer that fans out every tracing callback to a set of
+  # tracers, so a request can (for example) be logged to a file
+  # and exported to OpenTelemetry at the same time.
+  #
+  # {on_request_start} and {on_tool_start} return an array with
+  # one span per tracer, in the same order as {#tracers}. Pass the
+  # array back as `span:` to the matching finish, error, or
+  # interrupt callback, and each tracer is handed back the span
+  # it returned.
+  #
+  # A tracer that raises does not take the others down with it:
+  # the error is reported the same way
+  # {LLM::Tracer::Rescue LLM::Tracer::Rescue} reports a crashed
+  # tracer, and the remaining tracers still run.
+  #
+  # @example
+  #   LLM::Tracer::Multi.new(
+  #     LLM::Tracer.logger(llm, io: $stdout),
+  #     LLM::Tracer.telemetry(llm)
+  #   )
+  class Multi < self
+    ##
+    # Returns the tracer(s) under the supervision of Multi
+    # @return [Array<LLM::Tracer>]
+    attr_reader :tracers
+
+    ##
+    # @param [Array<LLM::Tracer>] tracers
+    #  The tracers to fan out to. A Multi has no provider
+    #  of its own.
+    def initialize(*tracers)
+      super(nil)
+      @tracers = tracers
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_start)
+    # @return [Array]
+    #  One span per tracer, in the same order as {#tracers}
+    def on_request_start(operation:, request_id:, model: nil, inputs: nil)
+      @tracers.map { _1.on_request_start(operation:, request_id:, model:, inputs:) }
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_finish)
+    # @return [void]
+    def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil, request_id:)
+      span.each.with_index do |s, i|
+        @tracers[i].on_request_finish(operation:, res:, model:, span: s, outputs:, metadata:, request_id:)
+      end
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_error)
+    # @return [void]
+    def on_request_error(ex:, span:, request_id:)
+      span.each.with_index do |s, i|
+        @tracers[i].on_request_error(ex:, span: s, request_id:)
+      end
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_start)
+    # @return [Array]
+    #  One span per tracer, in the same order as {#tracers}
+    def on_tool_start(id:, name:, arguments:, model:)
+      @tracers.map { _1.on_tool_start(id:, name:, arguments:, model:) }
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_interrupt)
+    # @return [void]
+    def on_tool_interrupt(ex:, span:, started_at:, finished_at:)
+      span.each.with_index do |s, i|
+        @tracers[i].on_tool_interrupt(ex:, span: s, started_at:, finished_at:)
+      end
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_finish)
+    # @return [void]
+    def on_tool_finish(result:, span:, started_at:, finished_at:)
+      span.each.with_index do |s, i|
+        @tracers[i].on_tool_finish(result:, span: s, started_at:, finished_at:)
+      end
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_error)
+    # @return [void]
+    def on_tool_error(ex:, span:, started_at:, finished_at:)
+      span.each.with_index do |s, i|
+        @tracers[i].on_tool_error(ex:, span: s, started_at:, finished_at:)
+      end
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_interrupt)
+    # @return [void]
+    def on_interrupt(scope:, span: nil, request_id: nil)
+      spans = span || Array.new(@tracers.size)
+      spans.each.with_index do |s, i|
+        @tracers[i].on_interrupt(scope:, span: s, request_id:)
+      end
+    end
+
+    ##
+    # @return [void]
+    def on_exit
+      @tracers.each(&:on_exit)
+    end
+
+    ##
+    # @param (see LLM::Tracer#start_trace)
+    # @return [Array<LLM::Tracer>]
+    def start_trace(...)
+      @tracers.each { _1.start_trace(...) }
+    end
+
+    ##
+    # @return [Array<LLM::Tracer>]
+    def stop_trace
+      @tracers.each(&:stop_trace)
+    end
+
+    ##
+    # @param (see LLM::Tracer#set_finish_metadata_proc)
+    # @return [Array<LLM::Tracer>]
+    def set_finish_metadata_proc(...)
+      @tracers.each { _1.set_finish_metadata_proc(...) }
+    end
+
+    ##
+    # @param (see LLM::Tracer#merge_extra)
+    # @return [Array<LLM::Tracer>]
+    def merge_extra(...)
+      @tracers.each { _1.merge_extra(...) }
+    end
+  end
+end

data/lib/llm/tracer/null.rb

@@ -32,6 +32,13 @@ module LLM
       nil
     end
 
+    ##
+    # @param (see LLM::Tracer#on_tool_interrupt)
+    # @return [nil]
+    def on_tool_interrupt(**)
+      nil
+    end
+
     ##
     # @param (see LLM::Tracer#on_tool_finish)
     # @return [nil]
@@ -46,6 +53,19 @@ module LLM
       nil
     end
 
+    ##
+    # @param (see LLM::Tracer#on_interrupt)
+    # @return [nil]
+    def on_interrupt(**)
+      nil
+    end
+
+    ##
+    # @return [nil]
+    def on_exit
+      nil
+    end
+
     ##
     # @param (see LLM::Tracer#set_finish_metadata_proc)
     # @return [self]

data/lib/llm/tracer/pretty_logger.rb

@@ -52,9 +52,11 @@ module LLM
 
     ##
     # @param (see LLM::Tracer#on_tool_start)
-    # @return [void]
+    # @return [LLM::Object]
+    #  The span an ending is handed, with the call's id and name
     def on_tool_start(id:, name:, arguments:, **)
       @io.puts "#{timestamp} #{name}(#{format_arguments(arguments)})"
+      LLM::Object.from(id:, name:)
     end
 
     ##
@@ -68,7 +70,28 @@ module LLM
     # @param (see LLM::Tracer#on_tool_error)
     # @return [void]
     def on_tool_error(ex:, **)
-      @io.puts "#{timestamp} tool error #{ex.class}: #{ex.message}"
+      @io.puts "#{timestamp} tool error #{ex.value[:type]}: #{ex.value[:message]}"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_interrupt)
+    # @return [void]
+    def on_tool_interrupt(ex:, span:, **)
+      @io.puts "#{timestamp} tool #{span.name} (#{format_id(span.id)}) received an interrupt"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_interrupt)
+    # @return [void]
+    def on_interrupt(scope:, **)
+      @io.puts "#{timestamp} #{provider_name} interrupt received (scope=#{scope})"
+    end
+
+    ##
+    # No-op.
+    # @return [nil]
+    def on_exit
+      nil
     end
 
     private
@@ -123,5 +146,13 @@ module LLM
         str.size > max ? "#{str[0...max]}..." : str
       end
     end
+
+    ##
+    # A call id, which is a long string that reads as gibberish:
+    # ten characters are enough to tell two of them apart.
+    def format_id(id)
+      id = id.to_s
+      id.size > 10 ? "#{id[0, 10]}..." : id
+    end
   end
 end

data/lib/llm/tracer/rescue.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+class LLM::Tracer
+  ##
+  # The {LLM::Tracer::Rescue} module prepends
+  # itself to every subclass of {LLM::Tracer}
+  # and ensures that a tracer callback never
+  # crashes an agent.
+  #
+  # When an error occurs, it is dumped to standard
+  # error and does not travel up the stack. But
+  # LLM::Interrupt, and any other exception not
+  # covered by the 'ERRORS' constant can crash
+  # the tracer. So it handles most cases but not
+  # all, and LLM::Interrupt travelling up the stack
+  # is intentional.
+  module Rescue
+    ##
+    # @param [StandardError] ex
+    # @return [void]
+    def self.crash(tracer, ex)
+      $stderr.puts "",
+                   "an llm.rb tracer has crashed.",
+                   "",
+                   "[  tracer    ] #{tracer.class}",
+                   "[  class     ] #{ex.class}",
+                   "[  message   ] #{ex.message}",
+                   "[  backtrace ] ",
+                   "#{(ex.backtrace || []).take(10).join("\n")}",
+                   ""
+    end
+
+    ##
+    # @api private
+    ERRORS = [StandardError, ScriptError]
+    private_constant :ERRORS
+
+    def on_exit
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+
+    def on_request_start(...)
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+
+    def on_request_finish(...)
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+
+    def on_request_error(...)
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+
+    def on_tool_start(...)
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+
+    def on_tool_interrupt(...)
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+
+    def on_tool_finish(...)
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+
+    def on_tool_error(...)
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+
+    def on_interrupt(...)
+      super
+    rescue LLM::Interrupt
+      raise
+    rescue *ERRORS => ex
+      LLM::Tracer::Rescue.crash(self, ex)
+    end
+  end
+end