ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/transport/websocket_connection.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'openssl'
+require 'io/wait'
+
+module RubyLLM
+  module Transport # :nodoc:
+    class WebsocketConnection # :nodoc: all
+      MAX_FRAME_BYTES = 16 * 1024 * 1024
+
+      attr_reader :url
+
+      def self.open(url, headers:, config:)
+        connection = new(url, headers:, config:)
+        connection.connect
+        yield connection
+      ensure
+        connection&.close
+      end
+
+      def initialize(url, headers:, config:)
+        @url = url
+        @uri = URI.parse(url)
+        raise ArgumentError, 'WebSocket URL must use ws or wss' unless %w[ws wss].include?(@uri.scheme)
+        if @uri.userinfo || @uri.fragment
+          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
+
+        @headers = headers
+        @timeout = config.request_timeout
+        @messages = []
+        @write_lock = Mutex.new
+      end
+
+      def connect
+        load_driver
+        deadline = monotonic_time + @timeout
+        open_socket(deadline)
+        configure_driver
+        @driver.start
+        read_frame(deadline) until @opened || @closed || @error
+        raise @error if @error
+        raise Error, 'WebSocket closed before opening' unless @opened
+
+        self
+      rescue StandardError
+        close
+        raise
+      end
+
+      def send_text(text)
+        ensure_open
+        @driver.text(text)
+      end
+
+      def send_binary(data)
+        ensure_open
+        @driver.binary(data.b)
+      end
+
+      def read(timeout: @timeout)
+        deadline = monotonic_time + timeout
+        read_frame(deadline) while @messages.empty? && !@closed && !@error
+        raise @error if @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
+
+        @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:)
+        writer_error = nil
+        writer = Thread.new do
+          write.call(self)
+        rescue StandardError => e
+          writer_error = e
+          close
+        end
+        writer.report_on_exception = false
+
+        while (message = read)
+          yield message
+        end
+        finish_writer(writer)
+        raise writer_error if writer_error
+      rescue StandardError => e
+        raise writer_error || e
+      ensure
+        close
+        writer.kill.join if writer&.alive?
+      end
+
+      def close
+        @driver.close if @driver && @opened && !@closed
+      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError, Error
+        nil
+      ensure
+        @closed = true
+        close_socket
+      end
+
+      def write(data)
+        @write_lock.synchronize do
+          deadline = monotonic_time + @timeout
+          offset = 0
+          while offset < data.bytesize
+            written = socket_operation(deadline) { @socket.write_nonblock(data.byteslice(offset..)) }
+            offset += written
+          end
+        end
+        data.bytesize
+      end
+
+      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
+
+      def configure_driver
+        @driver = WebSocket::Driver.client(self, max_length: MAX_FRAME_BYTES)
+        @headers.each { |name, value| @driver.set_header(name, value) if value }
+        @driver.on(:open) { @opened = true }
+        @driver.on(:message) { |event| @messages << event.data }
+        @driver.on(:error) { |event| @error = Error.new(event.message) }
+        @driver.on(:close) do |event|
+          @closed = true
+          @error ||= Error.new("WebSocket closed with code #{event.code}: #{event.reason}") unless event.code == 1000
+        end
+      end
+
+      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'
+      end
+
+      def close_socket
+        @socket.close if @socket && !@socket.closed?
+      end
+
+      def load_driver
+        require 'websocket/driver'
+      rescue LoadError
+        raise LoadError, 'WebSocket streaming requires websocket-driver. Add gem "websocket-driver" to your Gemfile.'
+      end
+
+      def secure_socket(deadline)
+        context = OpenSSL::SSL::SSLContext.new
+        context.set_params
+        socket = OpenSSL::SSL::SSLSocket.new(@socket, context)
+        socket.hostname = @uri.host
+        socket.sync_close = true
+        @socket = socket
+        socket_operation(deadline) { @socket.connect_nonblock }
+        @socket.post_connection_check(@uri.host)
+      end
+
+      def ensure_open
+        raise Error, 'WebSocket connection is closed' unless @opened && !@closed
+        raise @error if @error
+      end
+
+      def read_frame(deadline)
+        data = socket_operation(deadline) { @socket.read_nonblock(16_384) }
+        @driver.parse(data)
+      rescue EOFError, Errno::ECONNRESET
+        @closed = true
+        @error ||= Error.new('WebSocket connection ended without a close frame')
+      end
+
+      def socket_operation(deadline)
+        yield
+      rescue IO::WaitReadable
+        wait_for_socket(:wait_readable, deadline)
+        retry
+      rescue IO::WaitWritable
+        wait_for_socket(:wait_writable, deadline)
+        retry
+      end
+
+      def wait_for_socket(method, deadline)
+        remaining = deadline - monotonic_time
+        raise Error, 'WebSocket operation timed out' unless remaining.positive?
+        raise Error, 'WebSocket operation timed out' unless @socket.to_io.public_send(method, remaining)
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/ruby_llm/uploaded_file.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # An UploadedFile is the metadata record for a file stored with a provider
+  # through its Files API. Upload a file once with ::upload, then reuse its
+  # provider id or URI, for example as a chat attachment or in a batch.
+  #
+  #   file = RubyLLM.upload("batch.jsonl", purpose: "batch")
+  #   file.id         # => "file_..."
+  #   file.filename   # => "batch.jsonl"
+  #   file.byte_size  # => 1234
+  #
+  # File ids are provider-owned. Persist #provider alongside #id and pass it
+  # back when finding or downloading the file later.
+  class UploadedFile
+    include Support::Inspectable
+
+    def inspect_attributes # :nodoc:
+      { id: id, provider: provider, filename: filename, byte_size: byte_size }
+    end
+
+    # The provider-assigned file identifier, such as <tt>"file_..."</tt>.
+    attr_reader :id
+
+    # The slug of the provider that stores the file.
+    attr_reader :provider
+
+    # The filename reported by the provider.
+    attr_reader :filename
+
+    # The file size in bytes.
+    attr_reader :byte_size
+
+    # The Time the provider stored the file.
+    attr_reader :created_at
+
+    # The Time the provider will delete the file, or +nil+ if it does not
+    # expire.
+    attr_reader :expires_at
+
+    # The provider-reported processing status of the file.
+    attr_reader :status
+
+    # The MIME type of the stored file.
+    attr_reader :mime_type
+
+    # The purpose the file was uploaded for, such as <tt>"batch"</tt>, when
+    # the provider tracks one.
+    attr_reader :purpose
+
+    # The provider URI for the file, such as a Gemini Files API URI or a
+    # <tt>gs://</tt> or <tt>s3://</tt> location for storage-backed providers.
+    attr_reader :uri
+
+    # Whether the provider allows downloading the file's content.
+    attr_reader :downloadable
+
+    # The raw provider response data for the file, as a Hash.
+    attr_reader :metadata
+
+    def initialize(id:, **attributes) # :nodoc:
+      @id = id
+      @provider = attributes[:provider]
+      @filename = attributes[:filename]
+      @byte_size = attributes[:byte_size]
+      @created_at = attributes[:created_at]
+      @expires_at = attributes[:expires_at]
+      @status = attributes[:status]
+      @mime_type = attributes[:mime_type]
+      @purpose = attributes[:purpose]
+      @uri = attributes[:uri]
+      @downloadable = attributes[:downloadable]
+      @metadata = attributes[:metadata] || {}
+    end
+
+    EXPIRY_MARGIN = 60 # :nodoc:
+
+    # Returns +true+ once the provider's retention window for this file has
+    # passed or is about to; a file expiring within the next minute cannot
+    # safely serve a request. Files without a reported expiry never expire.
+    def expired?
+      !expires_at.nil? && expires_at <= Time.now + EXPIRY_MARGIN
+    end
+
+    # Uploads +file+ to the provider's Files API and returns an UploadedFile.
+    # +file+ may be a path, an IO object, or an Attachment. When +provider:+
+    # is omitted, the provider of the configured default model is used.
+    # Also available as RubyLLM.upload.
+    #
+    #   RubyLLM::UploadedFile.upload("document.pdf", provider: :anthropic)
+    #   RubyLLM::UploadedFile.upload(io, provider: :openai, purpose: "batch",
+    #                                filename: "batch.jsonl")
+    #
+    # OpenAI 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.
+    # 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.
+    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
+      options[:provider_options] = provider_options unless provider_options.empty?
+      provider_for(provider, context).upload_file(file, **options)
+    end
+
+    # Fetches metadata for an existing provider file by +id+ and returns an
+    # UploadedFile. When +provider:+ is omitted, the provider of the
+    # configured default model is used.
+    #
+    #   file = RubyLLM::UploadedFile.find("file_123")
+    #
+    def self.find(id, provider: nil, context: nil)
+      provider_for(provider, context).find_file(id)
+    end
+
+    # Downloads the provider file +id+ and returns a DownloadedFile.
+    # Also available as RubyLLM.download.
+    #
+    #   RubyLLM.download(file.id, provider: :openai).save("report.pdf")
+    #
+    # Not every provider allows downloads; see #downloadable. Cohere
+    # downloads original uploaded bytes when preserved; generated datasets
+    # return JSONL and require the optional +avro+ gem.
+    def self.download(id, provider: nil, context: nil)
+      DownloadedFile.new(provider_for(provider, context).download_file(id))
+    end
+
+    def self.provider_for(provider, context)
+      config = context&.config || RubyLLM.config
+
+      if provider
+        Provider.resolve!(provider).new(config)
+      else
+        Models.resolve(config.default_model, config:).last
+      end
+    end
+    private_class_method :provider_for
+  end
+end

data/lib/ruby_llm/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  VERSION = '1.16.0'
+  # The version of the ruby_llm gem, as a string.
+  VERSION = '2.0.0.rc2'
 end

data/lib/ruby_llm/video.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A Video is a generated clip. Save it with #save or read the raw bytes
+  # with #to_blob. Both handle hosted URLs and inline data.
+  #
+  #   video = RubyLLM.animate("a paper boat sailing down a rainy gutter")
+  #   video.save("boat.mp4")
+  #
+  class Video
+    include Support::Inspectable
+
+    # The URL of the hosted video, for providers that return one, or +nil+.
+    attr_reader :url
+
+    # The raw video bytes, returned inline or downloaded with the
+    # provider's credentials, or +nil+ when the video is hosted at #url.
+    attr_reader :data
+
+    # The MIME type of the video, such as <tt>"video/mp4"</tt>.
+    attr_reader :mime_type
+
+    # The id of the model that generated the video.
+    attr_reader :model
+
+    # The clip length in seconds, when the provider reports one.
+    attr_reader :duration
+
+    # The provider's raw job response, for provider-specific fields such
+    # as reported cost.
+    attr_reader :raw
+
+    # Generates a video from +prompt+, blocks until the provider finishes
+    # rendering it, and returns a Video. Most code calls this through
+    # RubyLLM.animate. Video generation is asynchronous on every provider,
+    # so this submits a job with VideoJob.animate_later and polls until it
+    # is done, honoring <tt>config.video_generation_timeout</tt> and
+    # <tt>config.video_generation_poll_interval</tt>.
+    #
+    # +model:+ selects the video model and defaults to the configured
+    # +default_video_model+. +provider:+ forces a specific provider, and
+    # +assume_model_exists:+ skips the registry lookup. +with:+ passes a
+    # reference image or a video to edit on models that support it. Models
+    # driven by image and audio input can omit the prompt and pass both
+    # attachments through +with:+.
+    # +extend:+ continues a source video instead. It accepts a Video,
+    # file path, URL, or Attachment and cannot be combined with +with:+.
+    # +provider_options:+ takes options in the provider's request
+    # vocabulary, such as durations and resolutions, and merges them into
+    # the request as-is. +context:+ supplies a Context whose configuration
+    # replaces the global one. +metadata:+ is included in the
+    # instrumentation payload.
+    #
+    #   video = RubyLLM.animate("a hummingbird in slow motion", model: "veo-3.1-fast-generate-preview")
+    #
+    #   RubyLLM.animate(
+    #     "Make the waterfall crash down",
+    #     model: "grok-imagine-video-1.5",
+    #     with: "waterfall.png",
+    #     provider_options: { duration: 5 }
+    #   )
+    #
+    def self.animate(prompt = nil,
+                     model: nil,
+                     provider: nil,
+                     assume_model_exists: false,
+                     context: nil,
+                     with: nil,
+                     extend: nil,
+                     provider_options: {},
+                     metadata: nil)
+      config = context&.config || RubyLLM.config
+      payload = { model:, prompt:, provider_options:, metadata: }
+
+      RubyLLM.instrument('video.ruby_llm', payload, config: config) do |event|
+        job = VideoJob.animate_later(prompt, model:, provider:, assume_model_exists:,
+                                             context:, with:, extend:, provider_options:, metadata:)
+        event[:model] = job.model
+        event[:job_id] = job.id
+        job.wait
+        result = job.video
+        event[:result] = result
+        event[:response_model] = result.model
+        result
+      end
+    end
+
+    # Set by the protocol that generated the video, so a Context's
+    # connection settings reach #to_blob.
+    attr_writer :config # :nodoc:
+
+    def config # :nodoc:
+      @config || RubyLLM.config
+    end
+
+    def initialize(url: nil, data: nil, mime_type: nil, model: nil, duration: nil, raw: nil) # :nodoc:
+      @url = url
+      @data = data
+      @mime_type = mime_type
+      @model = model
+      @duration = duration
+      @raw = raw
+    end
+
+    # Returns the raw binary video bytes, downloading from #url when the
+    # provider returned a hosted video.
+    #
+    #   video_bytes = video.to_blob
+    #
+    def to_blob
+      data || Transport::Connection.basic(config).get(url).body
+    end
+
+    # Writes the binary video to +path+, expanding it first. Returns
+    # +path+ as given.
+    #
+    #   video.save("clip.mp4")
+    #
+    def save(path)
+      File.binwrite(File.expand_path(path), to_blob)
+      path
+    end
+
+    private
+
+    def inspect_attributes # :nodoc:
+      {
+        model: model,
+        mime_type: mime_type,
+        url: url,
+        data: data && "#{data.bytesize} bytes",
+        duration: duration
+      }
+    end
+  end
+end

data/lib/ruby_llm/video_job.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A VideoJob is an in-flight video generation. RubyLLM.animate_later
+  # returns one immediately; poll it with #refresh and read the finished
+  # clip with #video. RubyLLM.animate runs the same job through #wait.
+  #
+  #   job = RubyLLM.animate_later("a paper boat sailing down a gutter")
+  #   job.wait
+  #   job.video.save("boat.mp4")
+  #
+  class VideoJob
+    include Support::Inspectable
+
+    # The provider's id for the job.
+    attr_reader :id
+
+    # The job state: +:pending+, +:completed+, or +:failed+.
+    attr_reader :status
+
+    # The id of the model rendering the video.
+    attr_reader :model
+
+    # The provider's failure message when #failed?, or +nil+.
+    attr_reader :error
+
+    # The provider's raw response from the last submit or poll.
+    attr_reader :raw
+
+    # 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.
+    #
+    #   job = RubyLLM.animate_later("a hummingbird in slow motion")
+    #   job.id      # => "0eb6910f-a353-4699-9d1e-6a4f7a5b39e2"
+    #   job.done?   # => false
+    #
+    def self.animate_later(prompt = nil,
+                           model: nil,
+                           provider: nil,
+                           assume_model_exists: false,
+                           context: nil,
+                           with: nil,
+                           extend: nil,
+                           provider_options: {},
+                           metadata: 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.class.display_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 = provider_instance.animate_later(prompt, model:, with:, extend:, provider_options:)
+        event[:job_id] = job.id
+        job
+      end
+    end
+
+    def initialize(id:, protocol:, model: nil, status: :pending, raw: nil, error: nil) # :nodoc:
+      @id = id
+      @protocol = protocol
+      @model = model
+      @status = status
+      @raw = raw
+      @error = error
+    end
+
+    # Returns +true+ while the provider is still rendering the video.
+    def pending?
+      status == :pending
+    end
+
+    # Returns +true+ once the job finished, successfully or not.
+    def done?
+      !pending?
+    end
+
+    # Returns +true+ when the job finished with a video.
+    def completed?
+      status == :completed
+    end
+
+    # Returns +true+ when the job finished without a video. #error carries
+    # the provider's failure message.
+    def failed?
+      status == :failed
+    end
+
+    # Re-fetches the job from the provider, updating #status, #error, and
+    # #raw. Does nothing once the job is #done?. Returns self.
+    def refresh
+      return self if done?
+
+      state = @protocol.refresh_video_job(self)
+      @status = state.fetch(:status)
+      @raw = state[:raw]
+      @error = state[:error]
+      self
+    end
+
+    # Polls the job until it finishes, then returns self. Raises Error
+    # when the job fails or +timeout+ elapses first. +timeout+ and
+    # +interval+ are seconds and default to the configured
+    # +video_generation_timeout+ and +video_generation_poll_interval+.
+    def wait(timeout: nil, interval: nil)
+      timeout ||= @protocol.config.video_generation_timeout
+      interval ||= @protocol.config.video_generation_poll_interval
+      deadline = monotonic_time + timeout
+
+      until done?
+        raise Error, "Video generation timed out after #{timeout} seconds" if monotonic_time > deadline
+
+        sleep interval
+        refresh
+      end
+      raise Error, "Video generation failed: #{error}" if failed?
+
+      self
+    end
+
+    # Returns the finished Video, downloading it from the provider when
+    # its API requires that. Returns +nil+ while #pending? and raises
+    # Error when #failed?.
+    def video
+      raise Error, "Video generation failed: #{error}" if failed?
+      return unless completed?
+
+      @video ||= @protocol.download_video(self).tap { |video| video.config = @protocol.config }
+    end
+
+    private
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def inspect_attributes # :nodoc:
+      { id: id, status: status, model: model }
+    end
+  end
+end