ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/transport/release_request.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module RubyLLM
+  module Transport
+    # Sits outside everything on a connection without retries, so an error
+    # leaves it without the credentials of the request it answers.
+    class ReleaseRequest < Faraday::Middleware # :nodoc:
+      # The response outlives the call as Message#raw, Error#response, and
+      # other results, which applications log and report. The request holds
+      # the API key in its headers, the whole serialized conversation in its
+      # body, and the provider and signer in its context, and a streaming
+      # callback closes over the payload it was built from.
+      def self.release(response)
+        response.delete(:request) if response.is_a?(Hash)
+        env = response.respond_to?(:env) ? response.env : response
+        return response unless env.is_a?(Faraday::Env)
+
+        env.request_body = nil
+        env.request_headers = Faraday::Utils::Headers.new
+        env.request.on_data = nil
+        env.request.context = nil
+        response
+      end
+
+      def call(env)
+        @app.call(env)
+      rescue Error, Faraday::Error => e
+        self.class.release(e.response)
+        raise
+      end
+    end
+  end
+end

data/lib/ruby_llm/transport/websocket_connection.rb

@@ -3,6 +3,7 @@
 require 'socket'
 require 'openssl'
 require 'io/wait'
+require 'timeout'
 
 module RubyLLM
   module Transport # :nodoc:
@@ -27,9 +28,11 @@ module RubyLLM
           raise ArgumentError, 'WebSocket URL must not contain credentials or a fragment'
         end
         raise ArgumentError, 'WebSocket connections do not support HTTP proxies' if config.http_proxy
+        raise ArgumentError, 'WebSocket connections do not support TLS options' if config.ssl
 
         @headers = headers
         @timeout = config.request_timeout
+        @connect_timeout = config.connect_timeout || @timeout
         @messages = []
         @write_lock = Mutex.new
       end
@@ -41,7 +44,7 @@ module RubyLLM
         configure_driver
         @driver.start
         read_frame(deadline) until @opened || @closed || @error
-        raise @error if @error
+        raise @error if @error && !@opened
         raise Error, 'WebSocket closed before opening' unless @opened
 
         self
@@ -63,26 +66,13 @@ module RubyLLM
       def read(timeout: @timeout)
         deadline = monotonic_time + timeout
         read_frame(deadline) while @messages.empty? && !@closed && !@error
-        raise @error if @error
+        raise_unread_error
 
         @messages.shift
       rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
-        raise unless @closed
-      end
-
-      def read_available
-        ensure_open
-        until @messages.any? || @closed || @error
-          break unless read_available_frame
-        end
-        ensure_open
+        raise unless @closed || @messages.any?
 
         @messages.shift
-      rescue EOFError, Errno::ECONNRESET
-        @closed = true
-        raise Error, 'WebSocket connection ended without a close frame'
-      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
-        raise unless @closed
       end
 
       def each_message(write:)
@@ -130,16 +120,6 @@ module RubyLLM
 
       private
 
-      def read_available_frame
-        data = @socket.read_nonblock(16_384, exception: false)
-        return if %i[wait_readable wait_writable].include?(data)
-
-        raise EOFError unless data
-
-        @driver.parse(data)
-        data
-      end
-
       def finish_writer(writer)
         raise Error, 'WebSocket closed before outgoing messages finished' unless writer.join(1)
       end
@@ -158,8 +138,20 @@ module RubyLLM
 
       def open_socket(deadline)
         port = @uri.port || (@uri.scheme == 'wss' ? 443 : 80)
-        @socket = Socket.tcp(@uri.host, port, connect_timeout: @timeout)
-        secure_socket(deadline) if @uri.scheme == 'wss'
+        opened_by = [monotonic_time + @connect_timeout, deadline].min
+        @socket = connect_socket(port, opened_by)
+        secure_socket(opened_by) if @uri.scheme == 'wss'
+      end
+
+      # Socket.tcp times the lookup and each address on their own, so only
+      # the outer timeout holds the whole connect to one deadline.
+      def connect_socket(port, opened_by)
+        remaining = opened_by - monotonic_time
+        raise Error, 'WebSocket operation timed out' unless remaining.positive?
+
+        Timeout.timeout(remaining, Error, 'WebSocket operation timed out') do
+          Socket.tcp(@uri.hostname, port, connect_timeout: remaining, resolv_timeout: remaining)
+        end
       end
 
       def close_socket
@@ -176,11 +168,15 @@ module RubyLLM
         context = OpenSSL::SSL::SSLContext.new
         context.set_params
         socket = OpenSSL::SSL::SSLSocket.new(@socket, context)
-        socket.hostname = @uri.host
+        socket.hostname = @uri.hostname
         socket.sync_close = true
         @socket = socket
         socket_operation(deadline) { @socket.connect_nonblock }
-        @socket.post_connection_check(@uri.host)
+        @socket.post_connection_check(@uri.hostname)
+      end
+
+      def raise_unread_error
+        raise @error if @error && @messages.empty?
       end
 
       def ensure_open

data/lib/ruby_llm/uploaded_file.rb

@@ -41,7 +41,9 @@ module RubyLLM
     # The provider-reported processing status of the file.
     attr_reader :status
 
-    # The MIME type of the stored file.
+    # The MIME type of the stored file. OpenAI, Azure, DeepSeek, Meta, and
+    # xAI do not report one: ::upload returns the content type it sent, and
+    # ::find returns +nil+.
     attr_reader :mime_type
 
     # The purpose the file was uploaded for, such as <tt>"batch"</tt>, when
@@ -91,16 +93,23 @@ module RubyLLM
     #   RubyLLM::UploadedFile.upload(io, provider: :openai, purpose: "batch",
     #                                filename: "batch.jsonl")
     #
-    # OpenAI and Azure require +purpose:+. Cohere uses +purpose:+ for its
+    # OpenAI, Meta, and Azure require +purpose:+. Cohere uses +purpose:+ for its
     # dataset type, such as <tt>"embed-input"</tt>.
     # Pass +expires_in:+ as a number of
     # seconds to have the provider delete the file automatically; OpenAI,
-    # xAI, and Mistral support it, and Mistral rounds up to whole hours.
+    # Meta, Anthropic, xAI, and Mistral support it, and Mistral rounds up to
+    # whole hours.
     # Storage-backed providers (Vertex AI and Bedrock) store the file at
     # +uri:+ when given, otherwise at a generated object name under the
-    # configured bucket. +content_type:+ overrides the MIME type RubyLLM
-    # detects. +provider_options:+ carries the rest in the provider's own
-    # vocabulary: +visibility:+ on Mistral, +display_name:+ on Gemini.
+    # configured bucket. Providers that cannot carry +purpose:+,
+    # +expires_in:+, or +uri:+ raise ArgumentError. +content_type:+
+    # overrides the MIME type RubyLLM detects. +provider_options:+
+    # carries the rest in the provider's own vocabulary: multipart form
+    # fields on most providers, such as +visibility:+ on Mistral, File
+    # resource fields on Gemini, such as +display_name:+, PutObject keywords
+    # on Bedrock, and +create_file+ keywords on Vertex AI. RubyLLM sends them
+    # as given, so the provider rejects what it does not recognize. They
+    # cannot replace the file itself.
     def self.upload(file, provider: nil, context: nil, filename: nil, purpose: nil, expires_in: nil,
                     uri: nil, content_type: nil, provider_options: {})
       options = { filename:, purpose:, expires_in:, uri:, content_type: }.compact

data/lib/ruby_llm/version.rb

@@ -2,5 +2,5 @@
 
 module RubyLLM
   # The version of the ruby_llm gem, as a string.
-  VERSION = '2.1.0'
+  VERSION = '2.2.0'
 end

data/lib/ruby_llm/video.rb

@@ -9,6 +9,8 @@ module RubyLLM
   #
   class Video
     include Support::Inspectable
+    include Files::Saving
+    include Accounting::Usage::Result
 
     # The URL of the hosted video, for providers that return one, or +nil+.
     attr_reader :url
@@ -50,9 +52,9 @@ module RubyLLM
     # the request as-is. +context:+ supplies a Context whose configuration
     # replaces the global one. +metadata:+ is included in the
     # instrumentation payload. +owner:+ attributes the usage to a record,
-    # such as a user, and wins over RubyLLM.with_usage_owner.
+    # such as a user, and wins over RubyLLM.with_owner.
     #
-    #   video = RubyLLM.animate("a hummingbird in slow motion", model: "veo-3.1-fast-generate-preview")
+    #   video = RubyLLM.animate("a hummingbird in slow motion", model: "gemini-omni-1.2-flash")
     #
     #   RubyLLM.animate(
     #     "Make the waterfall crash down",
@@ -72,6 +74,7 @@ module RubyLLM
                      metadata: nil,
                      owner: nil)
       config = context&.config || RubyLLM.config
+      model ||= config.default_video_model
       payload = { model:, prompt:, provider_options:, metadata: }
 
       RubyLLM.instrument('video.ruby_llm', payload, config: config) do |event|
@@ -104,23 +107,44 @@ module RubyLLM
       @raw = raw
     end
 
-    # Returns the raw binary video bytes, downloading from #url when the
-    # provider returned a hosted video.
+    # Returns the usage the provider reported for the job that rendered
+    # the video.
+    def tokens
+      return ruby_llm_usage_tokens unless ruby_llm_usage_entries.empty?
+
+      Tokens.new
+    end
+
+    # Returns the Cost of the job that rendered the video: the amount the
+    # provider reported, or its reported tokens at registry prices. Its total
+    # is +nil+ when the provider reports neither a price nor priced tokens.
     #
-    #   video_bytes = video.to_blob
+    #   video = RubyLLM.animate("a paper boat")
+    #   video.cost.total # => 0.05
     #
-    def to_blob
-      data || Transport::Connection.basic(config).get(url).body
+    def cost
+      return ruby_llm_usage_cost unless ruby_llm_usage_entries.empty?
+
+      Cost.new(tokens:)
     end
 
+    ##
+    # :method: save
+    # :call-seq:
+    #   save(path)
+    #
     # Writes the binary video to +path+, expanding it first. Returns
     # +path+ as given.
     #
     #   video.save("clip.mp4")
+
+    # Returns the raw binary video bytes, downloading from #url when the
+    # provider returned a hosted video.
     #
-    def save(path)
-      File.binwrite(File.expand_path(path), to_blob)
-      path
+    #   video_bytes = video.to_blob
+    #
+    def to_blob
+      data || Transport::Connection.download(url, config)
     end
 
     private

data/lib/ruby_llm/video_job.rb

@@ -11,6 +11,7 @@ module RubyLLM
   #
   class VideoJob
     include Support::Inspectable
+    include Support::DeprecatedJobPredicates
 
     # The provider's id for the job.
     attr_reader :id
@@ -28,23 +29,23 @@ module RubyLLM
     attr_reader :raw
 
     # The clip length in seconds the request asked for, or +nil+ when it
-    # left the length to the provider's default.
+    # left the length to the provider's default or the job came from ::find.
     attr_reader :duration
 
     # The resolution the request asked for, as the provider spells it,
     # such as <tt>"720p"</tt> or <tt>"1280x720"</tt>, or +nil+ when it left
-    # the resolution to the provider's default.
+    # the resolution to the provider's default or the job came from ::find.
     attr_reader :resolution
 
     # Submits a video generation job and returns a VideoJob without
     # waiting for the result. Most code calls this through
     # RubyLLM.animate_later. Takes the same arguments as Video.animate.
     # The job records its usage, attributed to +owner:+ or the owner of
-    # RubyLLM.with_usage_owner, once it finishes.
+    # RubyLLM.with_owner, once it finishes.
     #
     #   job = RubyLLM.animate_later("a hummingbird in slow motion")
-    #   job.id      # => "0eb6910f-a353-4699-9d1e-6a4f7a5b39e2"
-    #   job.done?   # => false
+    #   job.id        # => "0eb6910f-a353-4699-9d1e-6a4f7a5b39e2"
+    #   job.complete? # => false
     #
     def self.animate_later(prompt = nil,
                            model: nil,
@@ -56,31 +57,32 @@ module RubyLLM
                            provider_options: {},
                            metadata: nil,
                            owner: nil)
-      config = context&.config || RubyLLM.config
-      model ||= config.default_video_model
-      model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
-                                                       config: config)
-      payload = {
-        provider: provider_instance.slug,
-        provider_class: provider_instance.name,
-        model: model.id,
-        model_info: model,
-        prompt: prompt,
-        provider_options: provider_options,
-        metadata: metadata
-      }
-
-      RubyLLM.instrument('video_job.ruby_llm', payload, config: config) do |event|
-        job = Accounting::Usage.owned_by(owner) do
-          provider_instance.animate_later(prompt, model:, with:, extend:, provider_options:)
-        end
-        event[:job_id] = job.id
-        job
+      Accounting::Operation.new(
+        'video_job', model, default: :default_video_model, usage: false, provider:, assume_model_exists:, context:,
+                            owner:, report: ->(event, job) { event[:job_id] = job.id }
+      ).run(prompt:, provider_options:, metadata:) do |provider_instance, model|
+        provider_instance.animate_later(prompt, model:, with:, extend:, provider_options:)
       end
     end
 
+    # Returns a VideoJob reflecting the provider's current state for +id+.
+    # Use it to pick a job back up from any process. Pass the #model that
+    # rendered it: it selects the provider and protocol, and names the
+    # usage entry. A job already finished reports its usage here, once per
+    # VideoJob object, attributed to the owner of RubyLLM.with_owner.
+    #
+    #   job = RubyLLM::VideoJob.find(clip.video_job_id, model: clip.video_model, provider: :xai)
+    #   job.video&.save("clip.mp4")
+    #
+    # Pass +context:+ to use a Context in place of the global configuration.
+    def self.find(id, model:, provider: nil, assume_model_exists: false, context: nil)
+      config = context&.config || RubyLLM.config
+      model, provider_instance = Models.resolve(model, provider:, assume_model_exists:, config:)
+      provider_instance.find_video_job(id, model:)
+    end
+
     def initialize(id:, protocol:, model: nil, status: :pending, raw: nil, error: nil, # :nodoc:
-                   reported_cost: nil, duration: nil, resolution: nil)
+                   reported_cost: nil, tokens: nil, duration: nil, resolution: nil)
       @id = id
       @protocol = protocol
       @model = model
@@ -88,9 +90,11 @@ module RubyLLM
       @raw = raw
       @error = error
       @reported_cost = reported_cost
+      @tokens = tokens
       @duration = duration
       @resolution = resolution
       @usage_owner = Accounting::Usage.owner
+      @usage_workflow = Accounting::Usage.workflow
       record_usage
     end
 
@@ -100,12 +104,12 @@ module RubyLLM
     end
 
     # Returns +true+ once the job finished, successfully or not.
-    def done?
+    def complete?
       !pending?
     end
 
     # Returns +true+ when the job finished with a video.
-    def completed?
+    def succeeded?
       status == :completed
     end
 
@@ -116,28 +120,29 @@ module RubyLLM
     end
 
     # Re-fetches the job from the provider, updating #status, #error, and
-    # #raw. Does nothing once the job is #done?. Returns self.
+    # #raw. Does nothing once the job is #complete?. Returns self.
     def refresh
-      return self if done?
+      return self if complete?
 
       state = @protocol.refresh_video_job(self)
       @status = state.fetch(:status)
       @raw = state[:raw]
       @error = state[:error]
       @reported_cost = state[:reported_cost]
+      @tokens = state[:tokens]
       record_usage
       self
     end
 
-    # Returns the Cost the provider reported for the job. Its total is
-    # +nil+ while the job is pending or when the provider reports no
-    # price.
+    # Returns the Cost of the job: the amount the provider reported, or its
+    # reported tokens at registry prices. Its total is +nil+ while the job is
+    # pending, or when the provider reports neither a price nor priced tokens.
     #
     #   job.wait
     #   job.cost.total # => 0.05
     #
     def cost
-      Cost.new(tokens: Tokens.new(reported_cost: @reported_cost))
+      Cost.new(tokens: usage_tokens, model: (@protocol.model if @tokens))
     end
 
     # Polls the job until it finishes, then returns self. Raises Error
@@ -149,7 +154,7 @@ module RubyLLM
       interval ||= @protocol.config.video_generation_poll_interval
       deadline = monotonic_time + timeout
 
-      until done?
+      until complete?
         remaining = deadline - monotonic_time
         raise Error, "Video generation timed out after #{timeout} seconds" unless remaining.positive?
 
@@ -166,20 +171,28 @@ module RubyLLM
     # Error when #failed?.
     def video
       raise Error, "Video generation failed: #{error}" if failed?
-      return unless completed?
+      return unless succeeded?
 
-      @video ||= @protocol.download_video(self).tap { |video| video.config = @protocol.config }
+      @video ||= @protocol.download_video(self).tap do |video|
+        video.config = @protocol.config
+        video.ruby_llm_usage_entries = @usage_entry
+      end
     end
 
     private
 
     def record_usage
-      return if pending? || @usage_recorded
+      return if pending? || @usage_entry
+
+      @usage_entry = Accounting::Usage::Entry.new(
+        operation: :video, provider: @protocol.provider.slug, model:, status: succeeded? ? :succeeded : :failed,
+        tokens: usage_tokens, cost:, owner: @usage_owner, workflow: @usage_workflow
+      )
+      Accounting::Usage.report(@usage_entry, config: @protocol.config)
+    end
 
-      @usage_recorded = true
-      entry = Accounting::Usage::Entry.new(operation: :video, provider: @protocol.provider.slug, model:,
-                                           status: completed? ? :succeeded : :failed, cost:, owner: @usage_owner)
-      Accounting::Usage.report(entry, config: @protocol.config)
+    def usage_tokens
+      @tokens || Tokens.new(reported_cost: @reported_cost)
     end
 
     def monotonic_time

data/lib/ruby_llm/web_source.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A WebSource is a page a hosted web search returned. They appear on
+  # Message#web_sources, normalized across providers. A Citation is different:
+  # it links a span of the answer to what supports it, so a search usually
+  # has more sources than citations.
+  #
+  #   response = chat.with_provider_tools(:web_search).ask "What changed in Ruby 4.0?"
+  #   response.web_sources.map(&:url) # => ["https://www.ruby-lang.org/en/news/", ...]
+  #
+  # An address here comes from the outside world. See Message#web_sources
+  # before treating one as safe to open.
+  #
+  class WebSource
+    include Support::Inspectable
+
+    # The address the provider reports for the page.
+    attr_reader :url
+
+    # The title the provider reports for the page, or +nil+.
+    attr_reader :title
+
+    def initialize(url:, title: nil) # :nodoc:
+      @url = url
+      @title = title
+    end
+
+    # Returns the source as a Hash with symbol keys, omitting a +nil+ title.
+    def to_h
+      { url: url, title: title }.compact
+    end
+
+    def inspect_attributes # :nodoc:
+      { url: url, title: title }
+    end
+  end
+end

data/lib/ruby_llm/workflow.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # Adds workflow and step context to RubyLLM instrumentation while leaving
-  # orchestration in ordinary Ruby code.
+  # Adds workflow and step context to RubyLLM instrumentation and usage
+  # records while leaving orchestration in ordinary Ruby code.
   #
   # Create workflows through RubyLLM.workflow rather than constructing this
   # class directly: