openai 0.26.0 → 0.27.1

data/lib/openai/helpers/streaming/chat_events.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Streaming
+      # Raw streaming chunk event with accumulated completion snapshot.
+      #
+      # This is the fundamental event that wraps each raw chunk from the API
+      # along with the accumulated state up to that point. All other events
+      # are derived from processing these chunks.
+      #
+      # @example
+      #   event.chunk     # => ChatCompletionChunk (raw API response)
+      #   event.snapshot  # => ParsedChatCompletion (accumulated state)
+      class ChatChunkEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :chunk
+        required :chunk, -> { OpenAI::Chat::ChatCompletionChunk }
+        required :snapshot, -> { OpenAI::Chat::ParsedChatCompletion }
+      end
+
+      # Incremental text content update event.
+      #
+      # Emitted as the assistant's text response is being generated. Each event
+      # contains the new text fragment (delta) and the complete accumulated
+      # text so far (snapshot).
+      #
+      # @example
+      #   event.delta    # => "Hello"        (new fragment)
+      #   event.snapshot # => "Hello world"  (accumulated text)
+      #   event.parsed   # => {name: "John"} (if using structured outputs)
+      class ChatContentDeltaEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"content.delta"
+        required :delta, String
+        required :snapshot, String
+        optional :parsed, Object # Partially parsed structured output
+      end
+
+      # Text content completion event.
+      #
+      # Emitted when the assistant has finished generating text content.
+      # Contains the complete text and, if applicable, the fully parsed
+      # structured output.
+      #
+      # @example
+      #   event.content # => "Hello world! How can I help?"
+      #   event.parsed  # => {name: "John", age: 30} (if using structured outputs)
+      class ChatContentDoneEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"content.done"
+        required :content, String
+        optional :parsed, Object # Fully parsed structured output
+      end
+
+      # Incremental refusal update event.
+      #
+      # Emitted when the assistant is refusing to fulfill a request.
+      # Contains the new refusal text fragment and accumulated refusal message.
+      #
+      # @example
+      #   event.delta    # => "I cannot"
+      #   event.snapshot # => "I cannot help with that request"
+      class ChatRefusalDeltaEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"refusal.delta"
+        required :delta, String
+        required :snapshot, String
+      end
+
+      # Refusal completion event.
+      #
+      # Emitted when the assistant has finished generating a refusal message.
+      # Contains the complete refusal text.
+      #
+      # @example
+      #   event.refusal # => "I cannot help with that request as it violates..."
+      class ChatRefusalDoneEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"refusal.done"
+        required :refusal, String
+      end
+
+      # Incremental function tool call arguments update.
+      #
+      # Emitted as function arguments are being streamed. Provides both the
+      # raw JSON fragments and incrementally parsed arguments for strict tools.
+      #
+      # @example
+      #   event.name            # => "get_weather"
+      #   event.index           # => 0 (tool call index in array)
+      #   event.arguments_delta # => '{"location": "San'  (new fragment)
+      #   event.arguments       # => '{"location": "San Francisco"'  (accumulated JSON)
+      #   event.parsed # => {location: "San Francisco"}  (if strict: true)
+      class ChatFunctionToolCallArgumentsDeltaEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"tool_calls.function.arguments.delta"
+        required :name, String
+        required :index, Integer
+        required :arguments_delta, String
+        required :arguments, String
+        required :parsed, Object
+      end
+
+      # Function tool call arguments completion event.
+      #
+      # Emitted when a function tool call's arguments are complete.
+      # For tools defined with `strict: true`, the arguments will be fully
+      # parsed and validated. For non-strict tools, only raw JSON is available.
+      #
+      # @example With strict tool
+      #   event.name             # => "get_weather"
+      #   event.arguments        # => '{"location": "San Francisco", "unit": "celsius"}'
+      #   event.parsed # => {location: "San Francisco", unit: "celsius"}
+      #
+      # @example Without strict tool
+      #   event.parsed # => nil (parse JSON from event.arguments manually)
+      class ChatFunctionToolCallArgumentsDoneEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"tool_calls.function.arguments.done"
+        required :name, String
+        required :index, Integer
+        required :arguments, String
+        required :parsed, Object # (only for strict: true tools)
+      end
+
+      # Incremental logprobs update for content tokens.
+      #
+      # Emitted when logprobs are requested and content tokens are being generated.
+      # Contains log probability information for the new tokens and accumulated
+      # logprobs for all content tokens so far.
+      #
+      # @example
+      #   event.content[0].token        # => "Hello"
+      #   event.content[0].logprob      # => -0.31725305
+      #   event.content[0].top_logprobs # => [{token: "Hello", logprob: -0.31725305}, ...]
+      #   event.snapshot                # => [all logprobs accumulated so far]
+      class ChatLogprobsContentDeltaEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"logprobs.content.delta"
+        required :content, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Chat::ChatCompletionTokenLogprob] }
+        required :snapshot, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Chat::ChatCompletionTokenLogprob] }
+      end
+
+      # Logprobs completion event for content tokens.
+      #
+      # Emitted when content generation is complete and logprobs were requested.
+      # Contains the complete array of log probabilities for all content tokens.
+      #
+      # @example
+      #   event.content.each do |logprob|
+      #     puts "Token: #{logprob.token}, Logprob: #{logprob.logprob}"
+      #   end
+      class ChatLogprobsContentDoneEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"logprobs.content.done"
+        required :content, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Chat::ChatCompletionTokenLogprob] }
+      end
+
+      # Incremental logprobs update for refusal tokens.
+      #
+      # Emitted when logprobs are requested and refusal tokens are being generated.
+      # Contains log probability information for refusal message tokens.
+      #
+      # @example
+      #   event.refusal[0].token   # => "I"
+      #   event.refusal[0].logprob # => -0.12345
+      #   event.snapshot           # => [all refusal logprobs accumulated so far]
+      class ChatLogprobsRefusalDeltaEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"logprobs.refusal.delta"
+        required :refusal, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Chat::ChatCompletionTokenLogprob] }
+        required :snapshot, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Chat::ChatCompletionTokenLogprob] }
+      end
+
+      # Logprobs completion event for refusal tokens.
+      #
+      # Emitted when refusal generation is complete and logprobs were requested.
+      # Contains the complete array of log probabilities for all refusal tokens.
+      #
+      # @example
+      #   event.refusal.each do |logprob|
+      #     puts "Refusal token: #{logprob.token}, Logprob: #{logprob.logprob}"
+      #   end
+      class ChatLogprobsRefusalDoneEvent < OpenAI::Internal::Type::BaseModel
+        required :type, const: :"logprobs.refusal.done"
+        required :refusal, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Chat::ChatCompletionTokenLogprob] }
+      end
+    end
+  end
+end

data/lib/openai/helpers/streaming/exceptions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Streaming
+      class StreamError < StandardError; end
+
+      class LengthFinishReasonError < StreamError
+        attr_reader :completion
+
+        def initialize(completion:)
+          @completion = completion
+          super("Stream finished due to length limit")
+        end
+      end
+
+      class ContentFilterFinishReasonError < StreamError
+        def initialize
+          super("Stream finished due to content filter")
+        end
+      end
+    end
+  end
+end
+
+module OpenAI
+  LengthFinishReasonError = Helpers::Streaming::LengthFinishReasonError
+  ContentFilterFinishReasonError = Helpers::Streaming::ContentFilterFinishReasonError
+end

data/lib/openai/helpers/streaming/response_stream.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "events"
-
 module OpenAI
   module Helpers
     module Streaming

data/lib/openai/internal/type/file_input.rb

@@ -82,17 +82,20 @@ module OpenAI
           #
           # @return [Pathname, StringIO, IO, String, Object]
           def dump(value, state:)
-            # rubocop:disable Lint/DuplicateBranch
             case value
+            in StringIO | String
+              # https://datatracker.ietf.org/doc/html/rfc7578#section-4.2
+              # while not required, a filename is recommended, and in practice many servers do expect this
+              OpenAI::FilePart.new(value, filename: "upload")
             in IO
               state[:can_retry] = false
+              value.to_path.nil? ? OpenAI::FilePart.new(value, filename: "upload") : value
             in OpenAI::FilePart if value.content.is_a?(IO)
               state[:can_retry] = false
+              value
             else
+              value
             end
-            # rubocop:enable Lint/DuplicateBranch
-
-            value
           end
 
           # @api private

data/lib/openai/internal/util.rb

@@ -566,7 +566,8 @@ module OpenAI
         #
         # @return [Array(String, Enumerable<String>)]
         private def encode_multipart_streaming(body)
-          boundary = SecureRandom.urlsafe_base64(60)
+          # RFC 1521 Section 7.2.1 says we should have 70 char maximum for boundary length
+          boundary = SecureRandom.urlsafe_base64(46)
 
           closing = []
           strio = writable_enum do |y|

data/lib/openai/models/chat/parsed_chat_completion.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Chat
+      class ParsedChoice < OpenAI::Models::Chat::ChatCompletion::Choice
+        optional :finish_reason, enum: -> { OpenAI::Chat::ChatCompletion::Choice::FinishReason }, nil?: true
+      end
+
+      class ParsedChatCompletion < ChatCompletion
+        required :choices, -> { OpenAI::Internal::Type::ArrayOf[ParsedChoice] }
+      end
+    end
+  end
+end

data/lib/openai/resources/chat/completions.rb

@@ -110,6 +110,54 @@ module OpenAI
             raise ArgumentError.new(message)
           end
 
+          model, tool_models = get_structured_output_models(parsed)
+
+          # rubocop:disable Metrics/BlockLength
+          unwrap = ->(raw) do
+            if model.is_a?(OpenAI::StructuredOutput::JsonSchemaConverter)
+              raw[:choices]&.each do |choice|
+                message = choice.fetch(:message)
+                begin
+                  content = message.fetch(:content)
+                  parsed = content.nil? ? nil : JSON.parse(content, symbolize_names: true)
+                rescue JSON::ParserError => e
+                  parsed = e
+                end
+                coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
+                message.store(:parsed, coerced)
+              end
+            end
+            raw[:choices]&.each do |choice|
+              choice.dig(:message, :tool_calls)&.each do |tool_call|
+                func = tool_call.fetch(:function)
+                next if (model = tool_models[func.fetch(:name)]).nil?
+
+                begin
+                  arguments = func.fetch(:arguments)
+                  parsed = arguments.nil? ? nil : JSON.parse(arguments, symbolize_names: true)
+                rescue JSON::ParserError => e
+                  parsed = e
+                end
+                coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
+                func.store(:parsed, coerced)
+              end
+            end
+
+            raw
+          end
+          # rubocop:enable Metrics/BlockLength
+
+          @client.request(
+            method: :post,
+            path: "chat/completions",
+            body: parsed,
+            unwrap: unwrap,
+            model: OpenAI::Chat::ChatCompletion,
+            options: options
+          )
+        end
+
+        def get_structured_output_models(parsed)
           model = nil
           tool_models = {}
           case parsed
@@ -162,53 +210,46 @@ module OpenAI
           else
           end
 
-          # rubocop:disable Metrics/BlockLength
-          unwrap = ->(raw) do
-            if model.is_a?(OpenAI::StructuredOutput::JsonSchemaConverter)
-              raw[:choices]&.each do |choice|
-                message = choice.fetch(:message)
-                begin
-                  content = message.fetch(:content)
-                  parsed = content.nil? ? nil : JSON.parse(content, symbolize_names: true)
-                rescue JSON::ParserError => e
-                  parsed = e
-                end
-                coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
-                message.store(:parsed, coerced)
-              end
-            end
-            raw[:choices]&.each do |choice|
-              choice.dig(:message, :tool_calls)&.each do |tool_call|
-                func = tool_call.fetch(:function)
-                next if (model = tool_models[func.fetch(:name)]).nil?
+          [model, tool_models]
+        end
 
-                begin
-                  arguments = func.fetch(:arguments)
-                  parsed = arguments.nil? ? nil : JSON.parse(arguments, symbolize_names: true)
-                rescue JSON::ParserError => e
-                  parsed = e
-                end
-                coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
-                func.store(:parsed, coerced)
-              end
-            end
+        def build_tools_with_models(tools, tool_models)
+          return [] if tools.nil?
 
-            raw
+          tools.map do |tool|
+            next tool unless tool[:type] == :function
+
+            function_name = tool.dig(:function, :name)
+            model = tool_models[function_name]
+
+            model ? tool.merge(model: model) : tool
           end
-          # rubocop:enable Metrics/BlockLength
+        end
 
-          @client.request(
+        def stream(params)
+          parsed, options = OpenAI::Chat::CompletionCreateParams.dump_request(params)
+
+          parsed.store(:stream, true)
+
+          response_format, tool_models = get_structured_output_models(parsed)
+
+          input_tools = build_tools_with_models(parsed[:tools], tool_models)
+
+          raw_stream = @client.request(
             method: :post,
             path: "chat/completions",
+            headers: {"accept" => "text/event-stream"},
             body: parsed,
-            unwrap: unwrap,
-            model: OpenAI::Chat::ChatCompletion,
+            stream: OpenAI::Internal::Stream,
+            model: OpenAI::Chat::ChatCompletionChunk,
             options: options
           )
-        end
 
-        def stream
-          raise NotImplementedError.new("higher level helpers are coming soon!")
+          OpenAI::Helpers::Streaming::ChatCompletionStream.new(
+            raw_stream: raw_stream,
+            response_format: response_format,
+            input_tools: input_tools
+          )
         end
 
         # See {OpenAI::Resources::Chat::Completions#create} for non-streaming counterpart.

data/lib/openai/resources/responses.rb

@@ -85,7 +85,7 @@ module OpenAI
       def create(params = {})
         parsed, options = OpenAI::Responses::ResponseCreateParams.dump_request(params)
         if parsed[:stream]
-          message = "Please use `#stream_raw` for the streaming use case."
+          message = "Please use `#stream` for the streaming use case."
           raise ArgumentError.new(message)
         end
 

data/lib/openai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenAI
-  VERSION = "0.26.0"
+  VERSION = "0.27.1"
 end

data/lib/openai.rb

@@ -195,6 +195,7 @@ require_relative "openai/models/chat/chat_completion_assistant_message_param"
 require_relative "openai/models/chat/chat_completion_audio"
 require_relative "openai/models/chat/chat_completion_audio_param"
 require_relative "openai/models/chat/chat_completion_chunk"
+require_relative "openai/models/chat/parsed_chat_completion"
 require_relative "openai/models/chat/chat_completion_content_part"
 require_relative "openai/models/chat/chat_completion_content_part_image"
 require_relative "openai/models/chat/chat_completion_content_part_input_audio"
@@ -697,6 +698,9 @@ require_relative "openai/resources/vector_stores"
 require_relative "openai/resources/vector_stores/file_batches"
 require_relative "openai/resources/vector_stores/files"
 require_relative "openai/resources/webhooks"
-require_relative "openai/helpers/streaming/events"
+require_relative "openai/helpers/streaming/response_events"
 require_relative "openai/helpers/streaming/response_stream"
+require_relative "openai/helpers/streaming/exceptions"
+require_relative "openai/helpers/streaming/chat_events"
+require_relative "openai/helpers/streaming/chat_completion_stream"
 require_relative "openai/streaming"

data/rbi/openai/file_part.rbi

@@ -27,7 +27,7 @@ module OpenAI
     sig do
       params(
         content: T.any(Pathname, StringIO, IO, String),
-        filename: T.nilable(String),
+        filename: T.nilable(T.any(Pathname, String)),
         content_type: T.nilable(String)
       ).returns(T.attached_class)
     end

data/rbi/openai/helpers/streaming/events.rbi

@@ -26,6 +26,126 @@ module OpenAI
         def response
         end
       end
+
+      class ChatChunkEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(T.untyped) }
+        def chunk
+        end
+
+        sig { returns(T.untyped) }
+        def snapshot
+        end
+      end
+
+      class ChatContentDeltaEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(String) }
+        def delta
+        end
+
+        sig { returns(String) }
+        def snapshot
+        end
+
+        sig { returns(T.untyped) }
+        def parsed
+        end
+      end
+
+      class ChatContentDoneEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(String) }
+        def content
+        end
+
+        sig { returns(T.untyped) }
+        def parsed
+        end
+      end
+
+      class ChatRefusalDeltaEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(String) }
+        def delta
+        end
+
+        sig { returns(String) }
+        def snapshot
+        end
+      end
+
+      class ChatRefusalDoneEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(String) }
+        def refusal
+        end
+      end
+
+      class ChatFunctionToolCallArgumentsDeltaEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(String) }
+        def name
+        end
+
+        sig { returns(Integer) }
+        def index
+        end
+
+        sig { returns(String) }
+        def arguments_delta
+        end
+
+        sig { returns(String) }
+        def arguments
+        end
+
+        sig { returns(T.untyped) }
+        def parsed_arguments
+        end
+      end
+
+      class ChatFunctionToolCallArgumentsDoneEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(String) }
+        def name
+        end
+
+        sig { returns(Integer) }
+        def index
+        end
+
+        sig { returns(String) }
+        def arguments
+        end
+
+        sig { returns(T.untyped) }
+        def parsed_arguments
+        end
+      end
+
+      class ChatLogprobsContentDeltaEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(T.untyped) }
+        def content
+        end
+      end
+
+      class ChatLogprobsContentDoneEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(T.untyped) }
+        def content
+        end
+      end
+
+      class ChatLogprobsRefusalDeltaEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(T.untyped) }
+        def refusal
+        end
+      end
+
+      class ChatLogprobsRefusalDoneEvent < OpenAI::Internal::Type::BaseModel
+        sig { returns(T.untyped) }
+        def refusal
+        end
+      end
+
+      class ChatCompletionStream
+        sig { returns(T.untyped) }
+        def each
+        end
+      end
     end
   end
 end

data/rbi/openai/streaming.rbi

@@ -1,5 +1,32 @@
 # typed: strong
 
 module OpenAI
-  Streaming = OpenAI::Helpers::Streaming
+  module Streaming
+    ResponseTextDeltaEvent = OpenAI::Helpers::Streaming::ResponseTextDeltaEvent
+    ResponseTextDoneEvent = OpenAI::Helpers::Streaming::ResponseTextDoneEvent
+    ResponseFunctionCallArgumentsDeltaEvent =
+      OpenAI::Helpers::Streaming::ResponseFunctionCallArgumentsDeltaEvent
+    ResponseCompletedEvent = OpenAI::Helpers::Streaming::ResponseCompletedEvent
+
+    ChatChunkEvent = OpenAI::Helpers::Streaming::ChatChunkEvent
+    ChatContentDeltaEvent = OpenAI::Helpers::Streaming::ChatContentDeltaEvent
+    ChatContentDoneEvent = OpenAI::Helpers::Streaming::ChatContentDoneEvent
+    ChatRefusalDeltaEvent = OpenAI::Helpers::Streaming::ChatRefusalDeltaEvent
+    ChatRefusalDoneEvent = OpenAI::Helpers::Streaming::ChatRefusalDoneEvent
+    ChatFunctionToolCallArgumentsDeltaEvent =
+      OpenAI::Helpers::Streaming::ChatFunctionToolCallArgumentsDeltaEvent
+    ChatFunctionToolCallArgumentsDoneEvent =
+      OpenAI::Helpers::Streaming::ChatFunctionToolCallArgumentsDoneEvent
+    ChatLogprobsContentDeltaEvent =
+      OpenAI::Helpers::Streaming::ChatLogprobsContentDeltaEvent
+    ChatLogprobsContentDoneEvent =
+      OpenAI::Helpers::Streaming::ChatLogprobsContentDoneEvent
+    ChatLogprobsRefusalDeltaEvent =
+      OpenAI::Helpers::Streaming::ChatLogprobsRefusalDeltaEvent
+    ChatLogprobsRefusalDoneEvent =
+      OpenAI::Helpers::Streaming::ChatLogprobsRefusalDoneEvent
+
+    ResponseStream = OpenAI::Helpers::Streaming::ResponseStream
+    ChatCompletionStream = OpenAI::Helpers::Streaming::ChatCompletionStream
+  end
 end

data/sig/openai/file_part.rbs

@@ -14,7 +14,7 @@ module OpenAI
 
     def initialize: (
       Pathname | StringIO | IO | String content,
-      ?filename: String?,
+      ?filename: (Pathname | String)?,
       ?content_type: String?
     ) -> void
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openai
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.1
 platform: ruby
 authors:
 - OpenAI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-23 00:00:00.000000000 Z
+date: 2025-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -39,7 +39,10 @@ files:
 - lib/openai/client.rb
 - lib/openai/errors.rb
 - lib/openai/file_part.rb
-- lib/openai/helpers/streaming/events.rb
+- lib/openai/helpers/streaming/chat_completion_stream.rb
+- lib/openai/helpers/streaming/chat_events.rb
+- lib/openai/helpers/streaming/exceptions.rb
+- lib/openai/helpers/streaming/response_events.rb
 - lib/openai/helpers/streaming/response_stream.rb
 - lib/openai/helpers/structured_output.rb
 - lib/openai/helpers/structured_output/array_of.rb
@@ -229,6 +232,7 @@ files:
 - lib/openai/models/chat/completion_retrieve_params.rb
 - lib/openai/models/chat/completion_update_params.rb
 - lib/openai/models/chat/completions/message_list_params.rb
+- lib/openai/models/chat/parsed_chat_completion.rb
 - lib/openai/models/chat_model.rb
 - lib/openai/models/comparison_filter.rb
 - lib/openai/models/completion.rb