openai 0.85.0 → 0.87.0

data/lib/openai/client.rb

@@ -399,14 +399,16 @@ module OpenAI
       rescue OpenAI::Errors::APIError => error
         status = error.status
         connection_failure = error.is_a?(OpenAI::Errors::APIConnectionError)
-        retryable_status = connection_failure ||
+        retryable_connection_failure = connection_failure &&
+          false.equal?(error.request_may_have_been_sent?)
+        retryable_status = retryable_connection_failure ||
           [408, 409, 429].include?(status) ||
           (status.is_a?(Integer) && (500..599).cover?(status))
         consumed_retries = attempts + previous_issuer_retries + retry_count
         unless x509_transport?(@requester) &&
             retryable_status &&
             consumed_retries < request.fetch(:x509_request_context).fetch(:auth_max_retries) &&
-            (connection_failure || self.class.should_retry?(status, headers: error.headers || {}))
+            (retryable_connection_failure || self.class.should_retry?(status, headers: error.headers || {}))
           raise
         end
 

data/lib/openai/errors.rb

@@ -141,6 +141,15 @@ module OpenAI
       #
       #   @return [nil]
 
+      # Whether request bytes might have reached the peer before the transport
+      # failed. HTTP clients should only set this to `false` when they can
+      # prove that no request bytes were sent.
+      #
+      # @api private
+      #
+      # @return [Boolean]
+      def request_may_have_been_sent? = @request_may_have_been_sent
+
       # @api private
       #
       # @param url [URI::Generic]
@@ -150,6 +159,7 @@ module OpenAI
       # @param request [nil]
       # @param response [nil]
       # @param message [String, nil]
+      # @param request_may_have_been_sent [Boolean]
       def initialize(
         url:,
         status: nil,
@@ -157,9 +167,11 @@ module OpenAI
         body: nil,
         request: nil,
         response: nil,
-        message: "Connection error."
+        message: "Connection error.",
+        request_may_have_been_sent: true
       )
-        super
+        @request_may_have_been_sent = request_may_have_been_sent
+        super(url:, status:, headers:, body:, request:, response:, message:)
       end
     end
 
@@ -173,6 +185,7 @@ module OpenAI
       # @param request [nil]
       # @param response [nil]
       # @param message [String, nil]
+      # @param request_may_have_been_sent [Boolean]
       def initialize(
         url:,
         status: nil,
@@ -180,7 +193,8 @@ module OpenAI
         body: nil,
         request: nil,
         response: nil,
-        message: "Request timed out."
+        message: "Request timed out.",
+        request_may_have_been_sent: true
       )
         super
       end
@@ -264,9 +278,9 @@ module OpenAI
           safe_status_message(url: url, status: status, body: body)
         end
 
-        @code = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :code))
-        @param = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :param))
-        @type = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :type))
+        @code = OpenAI::Internal::Type::Converter.coerce(String, error_metadata(body, :code))
+        @param = OpenAI::Internal::Type::Converter.coerce(String, error_metadata(body, :param))
+        @type = OpenAI::Internal::Type::Converter.coerce(String, error_metadata(body, :type))
         super(
           url: url,
           status: status,
@@ -278,6 +292,10 @@ module OpenAI
         )
       end
 
+      private def error_metadata(body, key)
+        OpenAI::Internal::Util.dig(body, key) { OpenAI::Internal::Util.dig(body, [:error, key]) }
+      end
+
       private def safe_status_message(url:, status:, body:)
         sensitive_description = %r{
           https?:// |
@@ -536,10 +554,11 @@ module OpenAI
       attr_reader :error_code
 
       def initialize(status:, body:, headers:)
-        @error_code = OpenAI::Internal::Type::Converter.coerce(OpenAI::Models::OAuthErrorCode, body&.dig(:error))
+        error = OpenAI::Internal::Util.dig(body, :error)
+        @error_code = OpenAI::Internal::Type::Converter.coerce(OpenAI::Models::OAuthErrorCode, error)
 
-        message = if body&.dig(:error_description)
-          body[:error_description]
+        message = if (error_description = OpenAI::Internal::Util.dig(body, :error_description))
+          error_description
         elsif @error_code
           @error_code
         else

data/lib/openai/file_part.rb

@@ -30,6 +30,14 @@ module OpenAI
     }nx
     private_constant :MEDIA_TYPE
 
+    # Directory separators recognized on any host, so an upload name is stripped
+    # the same way everywhere.
+    #
+    # @api private
+    # @type [Regexp]
+    SEPARATORS = %r{[/\\]}
+    private_constant :SEPARATORS
+
     # Validate an effective media type before it is written to multipart headers.
     #
     # @api private
@@ -85,7 +93,7 @@ module OpenAI
       in Pathname
         content.read(binmode: true)
       in StringIO
-        content.string
+        content.string.byteslice(content.pos..) || ""
       in IO
         content.read
       in String
@@ -112,7 +120,7 @@ module OpenAI
       @content_type = content_type
       @filename = case [filename, (@content = content)]
       in [String | Pathname, _]
-        ::File.basename(filename)
+        strip_directories(filename)
       in [nil, Pathname]
         content.basename.to_path
       in [nil, IO]
@@ -121,5 +129,30 @@ module OpenAI
         filename
       end
     end
+
+    # Strip directory components from a caller-supplied upload name.
+    #
+    # `::File.basename` applies the host platform's path rules, so on Windows it
+    # also truncates at a drive separator: the remote name `"report: final.md"`
+    # becomes `"report"`. This name is sent to the API rather than resolved
+    # locally, so drop separators directly and keep every other character, no
+    # matter which platform the SDK runs on.
+    #
+    # @api private
+    #
+    # @param filename [Pathname, String]
+    #
+    # @return [String]
+    private def strip_directories(filename)
+      name = filename.to_s
+      binary_name = name.b
+      raise ArgumentError, "path name contains null byte" if binary_name.include?("\0")
+
+      searchable_name = name.scrub { |bytes| "?" * bytes.bytesize }
+      basename = searchable_name.split(SEPARATORS).last
+      return name.byteslice(0, name.empty? ? 0 : 1) if basename.nil?
+
+      name.byteslice(searchable_name.byterindex(basename), basename.bytesize)
+    end
   end
 end

data/lib/openai/helpers/local_audio/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module LocalAudio
+    class Error < OpenAI::Errors::Error
+    end
+
+    class DependencyError < Error
+    end
+
+    class UnsupportedPlatformError < Error
+    end
+
+    class DeviceError < Error
+    end
+
+    class PlaybackError < Error
+    end
+
+    class TimeoutError < Error
+    end
+
+    class FormatError < Error
+    end
+
+  end
+end

data/lib/openai/helpers/local_audio/process.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module OpenAI
+  module LocalAudio
+    # An owned media child. No credentials, shell, inherited descriptors or diagnostics.
+    # @api private
+    class MediaProcess
+      ENVIRONMENT_KEYS = %w[
+        PATH
+        HOME
+        TMPDIR
+        LANG
+        LC_ALL
+        SystemRoot
+        WINDIR
+        USERPROFILE
+        APPDATA
+        LOCALAPPDATA
+        XDG_RUNTIME_DIR
+        PULSE_SERVER
+        SDL_AUDIODRIVER
+      ]
+        .freeze
+      private_constant :ENVIRONMENT_KEYS
+
+      def self.environment = ENV.to_h.slice(*ENVIRONMENT_KEYS)
+      def self.clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def self.duration(value, name:)
+        unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+          raise ArgumentError, "#{name} must be a positive finite number of seconds"
+        end
+
+        result = value.to_f
+        raise ArgumentError, "#{name} is not representable" unless result.finite?
+        result
+      end
+
+      def initialize(argv, input:, output:, timeout:, capture_errors: false)
+        @deadline = self.class.clock + self.class.duration(timeout, name: :timeout) unless timeout.nil?
+        @error_reader, error_writer = IO.pipe(binmode: true) if capture_errors
+        @pid = Process.spawn(
+          self.class.environment,
+          *argv,
+          in: input,
+          out: output,
+          err: error_writer || File::NULL,
+          close_others: true,
+          unsetenv_others: true
+        )
+      rescue Errno::ENOENT
+        @error_reader&.close
+        raise DependencyError.new("Install the required FFmpeg/FFplay executable on PATH."), cause: nil
+      rescue SystemCallError
+        @error_reader&.close
+        raise DeviceError.new("Cannot start the local audio executable."), cause: nil
+      ensure
+        error_writer&.close
+      end
+
+      def check_deadline
+        raise TimeoutError, "Local audio operation timed out." if @deadline && self.class.clock >= @deadline
+        errors?
+      end
+
+      # Drain at most one chunk per polling step, retaining no diagnostic content.
+      def errors?
+        if @error_reader && !@error_reader.closed?
+          chunk = @error_reader.read_nonblock(65_536, exception: false)
+          @errors = true if chunk.is_a?(String) && !chunk.empty?
+        end
+
+        !!@errors
+      end
+
+      def read(io, stop_on_exit: false)
+        loop do
+          check_deadline
+          return io.read(65_536) if io.is_a?(StringIO)
+          result = io.read_nonblock(65_536, exception: false)
+          return result unless result == :wait_readable
+          if stop_on_exit
+            reap
+            raise PlaybackError, "Audio player exited before the input ended." if @status
+          end
+
+          io.wait_readable(0.05)
+        end
+      end
+
+      def write(io, bytes)
+        offset = 0
+        while offset < bytes.bytesize
+          check_deadline
+          result = io.write_nonblock(bytes.byteslice(offset, 65_536), exception: false)
+          if result == :wait_writable
+            io.wait_writable(0.05)
+          else
+            offset += result
+          end
+        end
+
+      rescue Errno::EPIPE
+        raise PlaybackError.new("Audio player closed before receiving the input."), cause: nil
+      end
+
+      def wait
+        until @status
+          check_deadline
+          reap
+          sleep(0.01) unless @status
+        end
+
+        @status
+      end
+
+      def close
+        return unless @pid
+        reap
+        unless @status
+          signal("TERM")
+          deadline = self.class.clock + 0.25
+          until @status || self.class.clock >= deadline
+            reap
+            sleep(0.01) unless @status
+          end
+
+          unless @status
+            signal("KILL")
+            _, @status = Process.waitpid2(@pid)
+          end
+        end
+
+      ensure
+        @pid = nil
+        @error_reader&.close unless @error_reader&.closed?
+      end
+
+      private def reap
+        return if @status
+        result = Process.waitpid2(@pid, Process::WNOHANG)
+        @status = result.last if result
+      end
+
+      private def signal(name)
+        Process.kill(name, @pid)
+      rescue Errno::EINVAL
+        # Windows rejects TERM for another process; KILL still terminates it.
+        raise unless name == "TERM"
+        signal("KILL")
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/openai/helpers/local_audio.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "../../openai"
+require_relative "local_audio/errors"
+require_relative "local_audio/process"
+
+module OpenAI
+  # Optional local microphone and speaker helpers. Loading this file opens no devices.
+  module LocalAudio
+    class << self
+      # Record a finite mono 24 kHz WAV, ready for a multipart audio upload.
+      # @return [OpenAI::FilePart]
+      def record(duration:, device: nil, timeout: nil)
+        seconds = MediaProcess.duration(duration, name: :duration)
+        MediaProcess.duration(timeout, name: :timeout) unless timeout.nil?
+        format, source = capture_device(device)
+        reader, writer = IO.pipe(binmode: true)
+        child = nil
+        begin
+          child = MediaProcess.new(
+            [
+              "ffmpeg",
+              "-nostdin",
+              "-hide_banner",
+              "-loglevel",
+              "quiet",
+              "-f",
+              format,
+              "-i",
+              source,
+              "-t",
+              seconds.to_s,
+              "-ar",
+              "24000",
+              "-ac",
+              "1",
+              "-acodec",
+              "pcm_s16le",
+              "-f",
+              "s16le",
+              "pipe:1"
+            ],
+            input: File::NULL,
+            output: writer,
+            timeout: timeout
+          )
+          writer.close
+          pcm = +"".b
+          while (chunk = child.read(reader))
+            pcm << chunk
+          end
+
+          raise DeviceError, "Microphone capture failed." unless child.wait.success?
+          raise DeviceError, "Microphone returned no complete audio samples." if pcm.empty? || pcm.bytesize.odd?
+          audio = StringIO.new(wav_header(pcm.bytesize) << pcm)
+          OpenAI::FilePart.new(audio, filename: "audio.wav", content_type: "audio/wav")
+        ensure
+          reader.close unless reader.closed?
+          writer.close unless writer.closed?
+          child&.close
+        end
+      end
+
+      # Play encoded audio, or explicitly selected mono 24 kHz raw PCM16.
+      # The source is consumed from its current position and remains caller-owned.
+      # @return [nil]
+      def play(source, format: :auto, timeout: nil)
+        raise ArgumentError, "format must be :auto or :pcm" unless [:auto, :pcm].include?(format)
+        MediaProcess.duration(timeout, name: :timeout) unless timeout.nil?
+        io = playback_source(source)
+        reader, writer = IO.pipe(binmode: true)
+        child = nil
+        begin
+          # FFplay can exit zero on decoder/device failure. Its owner drains
+          # error output while feeding input, retaining only a boolean.
+          args = ["ffplay", "-autoexit", "-nodisp", "-nostats", "-loglevel", "error", "-protocol_whitelist", "pipe"]
+          args.concat(
+            format == :pcm ? ["-f", "s16le", "-ar", "24000", "-ch_layout", "mono"] : [
+              "-format_whitelist",
+              "wav,mp3,ogg,aac,flac"
+            ]
+          )
+          child = MediaProcess.new(
+            args + ["-i", "pipe:0"],
+            input: reader,
+            output: File::NULL,
+            capture_errors: true,
+            timeout: timeout
+          )
+          reader.close
+          bytes = 0
+          while (chunk = child.read(io, stop_on_exit: true))
+            break if chunk.empty?
+            bytes += chunk.bytesize
+            child.write(writer, chunk)
+          end
+
+          raise PlaybackError, "Audio input is empty." if bytes.zero?
+          raise FormatError, "PCM input ends with an incomplete sample." if format == :pcm && bytes.odd?
+          writer.close
+          status = child.wait
+          raise PlaybackError, "Audio playback failed." unless status.success? && !child.errors?
+          nil
+        ensure
+          reader.close unless reader.closed?
+          writer.close unless writer.closed?
+          child&.close
+        end
+      end
+
+      # @api private
+      def playback_source(source)
+        content = source.is_a?(OpenAI::FilePart) ? source.content : source
+        return content if content.is_a?(IO) || content.is_a?(StringIO)
+        return StringIO.new(content) if source.is_a?(OpenAI::FilePart) && content.is_a?(String)
+        raise ArgumentError, "source must be IO, StringIO, or a FilePart containing IO or bytes"
+      end
+
+      # @api private
+      def capture_device(device, platform: RUBY_PLATFORM)
+        unless device.nil? || device.is_a?(String) || (device.is_a?(Integer) && device >= 0)
+          raise ArgumentError, "device must be a device name or nonnegative index"
+        end
+
+        raise ArgumentError, "invalid device identifier" if device.to_s.include?("\0") || device == ""
+        case platform
+        when /darwin/
+          ["avfoundation", "none:#{device || "default"}"]
+        when /linux/
+          ["alsa", device.is_a?(Integer) ? "hw:#{device}" : (device || "default")]
+        when /mswin|mingw|cygwin/
+          raise ArgumentError, "Windows capture requires an explicit audio device name" unless device.is_a?(String)
+          ["dshow", "audio=#{device}"]
+        else
+          raise UnsupportedPlatformError, "Local capture is not supported on this platform."
+        end
+      end
+
+      # @api private
+      def wav_header(bytes)
+        format = "fmt " + [16, 1, 1, 24_000, 48_000, 2, 16].pack("VvvVVvv")
+        if bytes <= 0xFFFFFFFF - 36
+          "RIFF" + [bytes + 36].pack("V") + "WAVE" + format + "data" + [bytes].pack("V")
+        else
+          "RF64" +
+            [0xFFFFFFFF].pack("V") +
+            "WAVEds64" +
+            [28].pack("V") +
+            [bytes + 72, bytes, bytes / 2, 0].pack("Q<Q<Q<V") +
+            format +
+            "data" +
+            [0xFFFFFFFF].pack("V")
+        end
+      end
+    end
+  end
+end