ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/research_job.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A hosted, single-turn research task. RubyLLM.research_later returns a
+  # job immediately; #wait polls it and #message returns its report.
+  # The provider's agent identity is separate from an inference model.
+  #
+  #   job = RubyLLM.research_later(question, provider: provider, agent: agent_id)
+  #   job.wait
+  #   puts job.message.content
+  #
+  class ResearchJob
+    include Support::Inspectable
+
+    class DeadlineExpired < StandardError; end # :nodoc:
+    private_constant :DeadlineExpired
+
+    # A research failure that retains the job for inspection or recovery.
+    class Error < RubyLLM::Error
+      # The research job, including its remote ID and last known state.
+      attr_reader :job
+
+      # Creates an error retaining +job+ and the optional HTTP response.
+      def initialize(message, job:, response: nil)
+        @job = job
+        super(message, response:)
+      end
+    end
+
+    # Raised when polling exceeds its deadline. The independent job may
+    # still be running; Error#job retains its ID.
+    class TimeoutError < Error; end
+
+    # An interrupted blocking research call retaining its remote job.
+    class InterruptedError < Interrupt
+      # The job whose cancellation was attempted before interrupting.
+      attr_reader :job
+
+      # Creates an interruption retaining +job+ for recovery.
+      def initialize(message, job:)
+        @job = job
+        super(message)
+      end
+    end
+
+    # The provider-assigned job ID.
+    attr_reader :id
+
+    # The provider slug.
+    attr_reader :provider
+
+    # The hosted agent's identity, separate from a model ID.
+    attr_reader :agent
+
+    # The normalized state: +:pending+, +:completed+, +:incomplete+,
+    # +:failed+, or +:cancelled+.
+    attr_reader :status
+
+    # The provider's failure explanation, if any.
+    attr_reader :error
+
+    # The original provider response from submission or the latest poll.
+    attr_reader :raw
+
+    # The error from an unsuccessful automatic cancellation attempt, if any.
+    attr_reader :cancellation_error
+
+    # Submits one research task without waiting. +provider:+ and +agent:+
+    # are required; +with:+ attaches documents or images where supported.
+    # +server_tools:+ accepts an array of aliases or a Hash of aliases
+    # and their options, as on Chat#with_server_tools.
+    def self.research_later(prompt, provider:, agent:, with: nil, server_tools: nil,
+                            context: nil, provider_options: {}, metadata: nil)
+      config = context&.config || RubyLLM.config
+      instance = Provider.resolve!(provider).new(config)
+      payload = { provider: instance.slug, agent:, prompt:, metadata: }
+      RubyLLM.instrument('research_job.ruby_llm', payload, config:) do |event|
+        job = instance.research_later(prompt, agent:, with:, server_tools:, provider_options:)
+        event[:job_id] = job.id
+        event[:status] = job.status
+        job
+      end
+    end
+
+    # Runs a research task and returns its Message. On a timeout or
+    # interrupt, attempts to cancel the remote task before raising an
+    # error retaining the job. +timeout:+ and +interval:+ are seconds.
+    def self.research(prompt, timeout: 600, interval: 5, **options)
+      validate_polling_options(timeout, interval)
+      job = research_later(prompt, **options)
+      job.wait(timeout:, interval:).message
+    rescue Interrupt => e
+      raise unless job
+
+      job.send(:attempt_cancellation)
+      raise InterruptedError.new("Research interrupted (job #{job.id})", job:), cause: e
+    rescue StandardError => e
+      job ||= e.job if e.is_a?(Error)
+      raise unless job
+
+      job.send(:attempt_cancellation)
+      raise if e.is_a?(Error)
+
+      response = e.response if e.respond_to?(:response)
+      raise Error.new("Research failed: #{e.message} (job #{job.id})", job:, response:), cause: e
+    end
+
+    # Retrieves an existing task by ID without submitting another one.
+    # Use the same provider configuration that created the task.
+    def self.find(id, provider:, context: nil)
+      config = context&.config || RubyLLM.config
+      Provider.resolve!(provider).new(config).find_research_job(id)
+    end
+
+    def self.validate_polling_options(timeout, interval) # :nodoc:
+      return if [timeout, interval].all? { |value| value.is_a?(Numeric) && value.positive? && value.finite? }
+
+      raise ArgumentError, 'Research timeout and interval must be positive finite numbers'
+    end
+
+    def initialize(id:, provider:, agent:, protocol:, **state) # :nodoc:
+      @id = id
+      @provider = provider.to_sym
+      @agent = agent
+      @protocol = protocol
+      apply_state(state)
+    end
+
+    # Returns whether the task is waiting or running.
+    def pending? = status == :pending
+
+    # Returns whether the task reached any terminal state.
+    def done? = !pending?
+
+    # Returns whether the task finished with a complete report.
+    def completed? = status == :completed
+
+    # Returns whether the provider stopped before completing the report.
+    def incomplete? = status == :incomplete
+
+    # Returns whether the provider reported failure.
+    def failed? = status == :failed
+
+    # Returns whether the provider confirmed cancellation.
+    def cancelled? = status == :cancelled
+
+    # Fetches the latest state and returns self. Does nothing after the
+    # task finishes. +timeout:+ limits this request in seconds.
+    def refresh(timeout: nil)
+      self.class.validate_polling_options(timeout, 1) unless timeout.nil?
+      unless done?
+        state = request_with_timeout(timeout) { @protocol.refresh_research_job(self, timeout:) }
+        apply_state(state)
+      end
+      self
+    end
+
+    # Polls until a terminal state and returns self. A timeout leaves the
+    # independent task running and raises TimeoutError with this job.
+    # Incomplete reports remain available through #message.
+    def wait(timeout: 600, interval: 5)
+      self.class.validate_polling_options(timeout, interval)
+      deadline = monotonic_time + timeout
+      until done?
+        remaining = deadline - monotonic_time
+        raise TimeoutError.new("Research timed out (job #{id})", job: self) unless remaining.positive?
+
+        refresh(timeout: remaining)
+        sleep [interval, deadline - monotonic_time].min if pending? && monotonic_time < deadline
+      end
+      raise Error.new("Research #{status}: #{error} (job #{id})", job: self) if failed? || cancelled?
+
+      self
+    end
+
+    # Requests cancellation and returns self. Only the provider's response
+    # can confirm cancellation; this does not delete stored task data.
+    def cancel(timeout: 5)
+      self.class.validate_polling_options(timeout, 1)
+      unless done?
+        state = request_with_timeout(timeout) { @protocol.cancel_research_job(self, timeout:) }
+        apply_state(state)
+      end
+      self
+    end
+
+    # Returns the report, or +nil+ while pending. An incomplete report has
+    # Message#finish_reason +:max_tokens+. Raises Error for failed or
+    # cancelled tasks.
+    def message
+      raise Error.new("Research #{status}: #{error} (job #{id})", job: self) if failed? || cancelled?
+
+      @message
+    end
+
+    # Returns the provider-reported task usage. Unreported fields are nil.
+    attr_reader :tokens
+
+    # Returns the reported cost, or unknown cost when the provider supplies
+    # no price. Agent IDs are never used to look up model token prices.
+    def cost
+      Cost.from_h({ total: tokens.reported_cost }.compact, tokens:)
+    end
+
+    private
+
+    def request_with_timeout(timeout, &)
+      Timeout.timeout(timeout, DeadlineExpired, &)
+    rescue DeadlineExpired, Faraday::TimeoutError => e
+      raise TimeoutError.new("Research request timed out (job #{id})", job: self), cause: e
+    rescue Error
+      raise
+    rescue RubyLLM::Error, Faraday::Error => e
+      response = e.response if e.respond_to?(:response)
+      @raw = response.body if response.respond_to?(:body)
+      raise Error.new("Research request failed: #{e.message} (job #{id})", job: self, response:), cause: e
+    end
+
+    def apply_state(state)
+      @status = state.fetch(:status)
+      @raw = state[:raw]
+      @error = state[:error]
+      @message = state[:message]
+      @tokens = state[:tokens] || @message&.tokens || Tokens.new
+    end
+
+    def attempt_cancellation
+      cancel(timeout: 5)
+    rescue StandardError => e
+      @cancellation_error = e
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def inspect_attributes # :nodoc:
+      { id:, provider:, agent:, status: }
+    end
+  end
+end

data/lib/ruby_llm/search_results.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A SearchResults wraps documents a Tool returns so the model can cite
+  # each source. RubyLLM renders them in the selected provider's citation
+  # format; cited passages appear on Message#citations.
+  #
+  #   def execute(query:)
+  #     docs = MyVectorStore.search(query)
+  #
+  #     RubyLLM::SearchResults.new(
+  #       *docs.map { |doc| { title: doc.name, url: doc.link, text: doc.body } }
+  #     )
+  #   end
+  #
+  # Cited passages come back on the response as Message#citations.
+  class SearchResults
+    KEY = 'search_results' # :nodoc:
+
+    # The normalized results, as an array of hashes with +:title+, +:text+,
+    # and optional +:url+ keys.
+    attr_reader :results
+
+    # Returns a new SearchResults built from one or more result hashes, or
+    # from a single result given as keywords.
+    #
+    #   RubyLLM::SearchResults.new(title: 'Q4 Report', url: report_url, text: report_text)
+    #   RubyLLM::SearchResults.new({ title: 'A', text: '...' }, { title: 'B', text: '...' })
+    #
+    # Each result is reduced to its +:title+, +:url+, and +:text+ entries.
+    # Raises ArgumentError if no results are given or a result is missing
+    # +:title+ or +:text+.
+    def initialize(*results, **result)
+      results << result if result.any?
+      @results = results.map { |entry| normalize(entry) }
+      raise ArgumentError, 'SearchResults requires at least one result' if @results.empty?
+    end
+
+    def self.from_content(content) # :nodoc:
+      return unless content.is_a?(String) && content.lstrip.start_with?('{')
+
+      parsed = JSON.parse(content)
+      entries = parsed[KEY]
+      return unless entries.is_a?(Array) && entries.any? && entries.all?(Hash)
+
+      new(*entries)
+    rescue JSON::ParserError, ArgumentError
+      nil
+    end
+
+    def to_h # :nodoc:
+      { KEY => results }
+    end
+
+    def to_json(*args) # :nodoc:
+      JSON.generate(to_h, *args)
+    end
+
+    private
+
+    def normalize(entry)
+      entry = Support::Utils.deep_symbolize_keys(entry.to_h)
+      raise ArgumentError, 'Search results require :title and :text' unless entry[:title] && entry[:text]
+
+      entry.slice(:title, :url, :text)
+    end
+  end
+end

data/lib/ruby_llm/server_tool_call.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A ServerToolCall records one provider-executed tool step in an assistant
+  # response: a web search the model ran, a code execution, or the results
+  # block a provider returned for one. They appear on
+  # Message#server_tool_calls when a chat enables tools with
+  # Chat#with_server_tools.
+  #
+  #   response = chat.with_server_tools(:web_search).ask "What changed in Ruby 3.5?"
+  #   response.server_tool_calls.map(&:type) # => ["server_tool_use", "web_search_tool_result"]
+  #
+  # RubyLLM does not model each tool's result schema. #raw always holds the
+  # provider's block exactly as received, and is what RubyLLM replays to the
+  # provider in subsequent turns when the wire format requires it.
+  class ServerToolCall
+    include Support::Inspectable
+
+    # The provider's block or item type, such as <tt>"server_tool_use"</tt>,
+    # <tt>"web_search_tool_result"</tt>, or <tt>"web_search_call"</tt>.
+    attr_reader :type
+
+    # The tool name when the provider reports one, such as
+    # <tt>"web_search"</tt>, or +nil+.
+    attr_reader :name
+
+    # The provider's identifier for the call, or +nil+.
+    attr_reader :id
+
+    # The input the model gave the tool (a query, code to run), in the
+    # provider's shape, or +nil+.
+    attr_reader :input
+
+    # The tool's output in the provider's shape, or +nil+ for blocks that
+    # only record the invocation.
+    attr_reader :result
+
+    # The complete provider block as received, used verbatim when the
+    # conversation is sent back to the provider.
+    attr_reader :raw
+
+    def self.from_h(data) # :nodoc:
+      data = Support::Utils.deep_symbolize_keys(data)
+      new(type: data[:type], name: data[:name], id: data[:id], input: data[:input],
+          result: data[:result], raw: data[:raw])
+    end
+
+    def initialize(type:, raw:, name: nil, id: nil, input: nil, result: nil) # :nodoc:
+      @type = type
+      @name = name
+      @id = id
+      @input = input
+      @result = result
+      @raw = raw
+    end
+
+    # Returns the call's attributes as a Hash, omitting +nil+ values.
+    def to_h
+      {
+        type: type,
+        name: name,
+        id: id,
+        input: input,
+        result: result,
+        raw: raw
+      }.compact
+    end
+
+    def inspect_attributes # :nodoc:
+      { type: type, name: name, id: id, input: input }
+    end
+  end
+end

data/lib/ruby_llm/speech.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A Speech is audio generated from text. RubyLLM.speak returns one. It
+  # holds the raw audio bytes along with the model, voice, and format used.
+  #
+  #   speech = RubyLLM.speak "Hello, welcome to RubyLLM!"
+  #   speech.save "welcome.mp3"
+  #
+  class Speech
+    include Support::Inspectable
+    include Accounting::Usage::Result
+
+    # Maps audio format names to their MIME types.
+    MIME_TYPES = {
+      'aac' => 'audio/aac',
+      'flac' => 'audio/flac',
+      'mp3' => 'audio/mpeg',
+      'opus' => 'audio/opus',
+      'pcm' => 'audio/pcm',
+      'wav' => 'audio/wav'
+    }.freeze
+
+    # The raw audio bytes returned by the provider.
+    attr_reader :data
+
+    # The id of the model that generated the audio.
+    attr_reader :model
+
+    # The voice used for synthesis. When no +voice:+ was given, this is the
+    # provider default.
+    attr_reader :voice
+
+    # The audio format name, such as <tt>"mp3"</tt> or <tt>"pcm"</tt>.
+    attr_reader :format
+
+    # The MIME type of the audio, such as <tt>"audio/mpeg"</tt>.
+    attr_reader :mime_type
+
+    def initialize(data:, model:, voice: nil, format: 'mp3', mime_type: nil, # :nodoc:
+                   input_tokens: nil, output_tokens: nil)
+      @data = data
+      @model = model
+      @voice = voice
+      @format = (format || 'mp3').to_s
+      @mime_type = mime_type || MIME_TYPES.fetch(@format, "audio/#{@format}")
+      @input_tokens = input_tokens
+      @output_tokens = output_tokens
+    end
+
+    # Generates speech for +input+ and returns a Speech holding the audio.
+    # Uses <tt>config.default_speech_model</tt> unless +model:+ is given.
+    # Pass +provider:+ and <tt>assume_model_exists: true</tt> to use a model
+    # that is not in the registry. +provider_options:+ takes options in the
+    # provider's request vocabulary, such as +instructions:+ and +speed:+
+    # for OpenAI, and merges them into the request as-is.
+    #
+    #   speech = RubyLLM.speak "Hello, welcome to RubyLLM!"
+    #   speech.save "welcome.mp3"
+    #
+    #   RubyLLM.speak "Welcome back.", voice: "nova"
+    #   RubyLLM.speak "Save this as a WAV file.", format: "wav"
+    #   RubyLLM.speak "Say cheerfully: Have a wonderful day!",
+    #                 model: "gemini-3.1-flash-tts-preview", provider: :gemini
+    #
+    # Given a block, yields SpeechChunk objects as audio arrives and still
+    # returns the complete Speech. Chunks contain consecutive bytes of the
+    # recording and are not separate audio files.
+    #
+    #   File.open("welcome.mp3", "wb") do |file|
+    #     RubyLLM.speak("Welcome back.") { |chunk| file.write(chunk.data) }
+    #   end
+    #
+    # Raises RubyLLM::Error when the selected protocol cannot stream speech,
+    # or RubyLLM::ModelNotFoundError if +model:+ is not in the registry.
+    def self.speak(input,
+                   model: nil,
+                   provider: nil,
+                   assume_model_exists: false,
+                   voice: nil,
+                   format: nil,
+                   context: nil,
+                   provider_options: {},
+                   metadata: nil,
+                   &block)
+      config = context&.config || RubyLLM.config
+      model ||= config.default_speech_model
+      model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
+                                                       config: config)
+      empty_tokens = Tokens.new
+
+      payload = {
+        provider: provider_instance.slug,
+        provider_class: provider_instance.class.display_name,
+        model: model.id,
+        model_info: model,
+        input: input,
+        voice: voice,
+        format: format,
+        provider_options: provider_options,
+        metadata: metadata,
+        streaming: !block.nil?,
+        tokens: empty_tokens,
+        cost: Cost.new(tokens: empty_tokens, model:, category: :audio_tokens)
+      }
+
+      RubyLLM.instrument('speech.ruby_llm', payload, config: config) do |event|
+        result = provider_instance.speak(input, model:, voice:, format:, provider_options:, &block)
+        event[:result] = result
+        event[:response_model] = result.model
+        event[:voice] = result.voice
+        event[:format] = result.format
+        event[:audio_bytes] = result.to_blob.bytesize
+        event[:tokens] = result.tokens
+        event[:cost] = result.cost
+        result
+      end
+    end
+
+    # Returns the raw audio bytes. Alias for #data, mirroring Image#to_blob.
+    def to_blob
+      data
+    end
+
+    # Returns provider-reported usage across every attempt. Its fields are
+    # +nil+ when the provider did not report any.
+    def tokens
+      return ruby_llm_usage_tokens unless ruby_llm_usage_entries.empty?
+
+      Tokens.new(input: @input_tokens, output: @output_tokens)
+    end
+
+    # Returns the speech cost across every provider attempt.
+    def cost
+      return ruby_llm_usage_cost unless ruby_llm_usage_entries.empty?
+
+      Cost.new(tokens:, model: model_info, category: :audio_tokens)
+    end
+
+    def model_info # :nodoc:
+      @model_info ||= RubyLLM.models.find(model)
+    rescue ModelNotFoundError
+      nil
+    end
+
+    # Writes the audio to +path+ in binary mode and returns +path+.
+    #
+    #   speech.save "welcome.mp3"
+    #
+    def save(path)
+      File.binwrite(File.expand_path(path), to_blob)
+      path
+    end
+
+    def inspect_attributes # :nodoc:
+      { model: model, voice: voice, format: format, data: data && "#{data.bytesize} bytes" }
+    end
+  end
+end

data/lib/ruby_llm/speech_chunk.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A piece of generated audio, yielded by RubyLLM.speak as it arrives.
+  # Chunks are consecutive bytes of one recording, not separate audio files.
+  class SpeechChunk
+    include Support::Inspectable
+
+    # The raw audio bytes in this chunk.
+    attr_reader :data
+
+    # The audio format name, such as <tt>"mp3"</tt> or <tt>"pcm"</tt>.
+    attr_reader :format
+
+    # The MIME type of the audio, such as <tt>"audio/mpeg"</tt>.
+    attr_reader :mime_type
+
+    def initialize(data:, format:, mime_type: nil) # :nodoc:
+      @data = data.b
+      @format = format.to_s
+      @mime_type = mime_type || Speech::MIME_TYPES.fetch(@format, "audio/#{@format}")
+    end
+
+    # Returns the raw audio bytes. Alias for #data.
+    def to_blob
+      data
+    end
+
+    def inspect_attributes # :nodoc:
+      { format: format, data: "#{data.bytesize} bytes" }
+    end
+  end
+end

data/lib/ruby_llm/support/deprecator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Support # :nodoc:
+    class Deprecator # :nodoc:
+      def warn(message)
+        case RubyLLM.config.deprecation_behavior
+        when :silence
+          nil
+        when :raise
+          raise DeprecationError, message
+        else
+          RubyLLM.logger.warn(message)
+        end
+      end
+
+      def deprecate(name, replacement:, removal:)
+        warn("#{name} is deprecated and will be removed in RubyLLM #{removal}. Use #{replacement} instead.")
+      end
+    end
+  end
+end

data/lib/ruby_llm/support/inspectable.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Support # :nodoc:
+    # Concise console output, the way Active Record prints records. Including
+    # classes declare what matters in +inspect_attributes+; #inspect shows
+    # those on one line with long strings truncated, and pretty printing
+    # follows #inspect so IRB stays readable. Inspection is a summary, not
+    # the data: everything remains reachable through the readers
+    # (+message.raw+, +embedding.vectors+, +chat.messages+).
+    module Inspectable
+      TRUNCATE_AT = 64 # :nodoc:
+
+      # Returns a one-line summary of the object built from its
+      # +inspect_attributes+, omitting empty ones and truncating long values.
+      def inspect
+        attributes = inspect_attributes
+                     .reject { |_, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
+                     .map { |name, value| "#{name}: #{format_for_inspect(value)}" }
+        return "#<#{self.class.name}>" if attributes.empty?
+
+        "#<#{self.class.name} #{attributes.join(', ')}>"
+      end
+
+      def pretty_print(printer) # :nodoc:
+        printer.text(inspect)
+      end
+
+      # Returns the stock Ruby dump with every instance variable, for when
+      # the one-line summary is not enough.
+      #
+      #   message.full_inspect
+      #
+      def full_inspect
+        Object.instance_method(:inspect).bind_call(self)
+      end
+
+      private
+
+      def format_for_inspect(value)
+        if value.is_a?(String) && value.length > TRUNCATE_AT
+          "#{value[0, TRUNCATE_AT]}...".inspect
+        else
+          value.inspect
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/support/instrumentation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Support # :nodoc:
+    module Instrumentation # :nodoc:
+      WORKFLOW_CONTEXT_KEY = :ruby_llm_workflow_context
+
+      module_function
+
+      def instrument(name, payload = nil, config: nil, **attributes) # rubocop:disable Metrics/PerceivedComplexity
+        payload ||= {}
+        payload = payload.merge(attributes) unless attributes.empty?
+        workflow_context = current_workflow
+        payload = payload.merge(workflow_context) if workflow_context
+        instrumenter = (config || RubyLLM.config).instrumenter
+
+        if instrumenter.respond_to?(:instrument)
+          if block_given?
+            instrumenter.instrument(name, payload) { yield(payload) }
+          else
+            instrumenter.instrument(name, payload)
+          end
+        elsif block_given?
+          yield(payload)
+        end
+      end
+
+      def current_workflow
+        Thread.current[WORKFLOW_CONTEXT_KEY]
+      end
+
+      def with_workflow(context)
+        previous_context = current_workflow
+        Thread.current[WORKFLOW_CONTEXT_KEY] = context
+        yield
+      ensure
+        Thread.current[WORKFLOW_CONTEXT_KEY] = previous_context
+      end
+    end
+  end
+end