openai 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3c1a71d808c79d0cc0c3d6258103489ca127f3c437d79823b8975e73a5c5027
-  data.tar.gz: a5cd6cc4d1cb2d7f144b9d7f498d9ae51d540bb025883b0c04f9ac60c751487e
+  metadata.gz: bae9059a58e735637f77e8f67206ae5461c0a9b1644dae426b5ecdc783f9856b
+  data.tar.gz: 2b0724ad0cc6348a15db3d6d305cc451bb289ec7d8af9f8375d97fa884be4acc
 SHA512:
-  metadata.gz: f923479ccd9602e086b3dd87cb4b17f94cc42146f9e61b313473161f824cba737b4770c776bac4158e658896d8f77a2c1fcff571c99e97a544da89c8f6fbceb7
-  data.tar.gz: 5113901c49d3bb0476d7076ff41270e1baa68a02b54db309312589214d372607352936b310a6d8ce6b4ccdb02d72054043c79b1b3c38e560f19e065b091c2867
+  metadata.gz: b93a9f4249988394f4d90dd36c1f161eea365978ad6b83d3e9e9ecd8579d10f5f0ac26320a5f698dc2174755553ab0048e33602992c3d213c26e5f97d7b2adf9
+  data.tar.gz: dbe13a678f0617a93002ab5f14ca13b2f1305083ac2b5ecc3982d1afa925698dd41673b1bade182d6287e4558177b26e75b465af3d382111d0a640687c30dbb4

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.27.0 (2025-09-26)
+
+Full Changelog: [v0.26.0...v0.27.0](https://github.com/openai/openai-ruby/compare/v0.26.0...v0.27.0)
+
+### Features
+
+* chat completion streaming helpers ([#828](https://github.com/openai/openai-ruby/issues/828)) ([6e98424](https://github.com/openai/openai-ruby/commit/6e9842485e819876dd6b78107fa45f1a5da67e4f))
+
+
+### Bug Fixes
+
+* **internal:** use null byte as file separator in the fast formatting script ([151ffe1](https://github.com/openai/openai-ruby/commit/151ffe10c9dc8d5edaf46de2a1c6b6e6fda80034))
+* shorten multipart boundary sep to less than RFC specificed max length ([d7770d1](https://github.com/openai/openai-ruby/commit/d7770d10ee3b093d8e2464b79e0e12be3a9d2beb))
+
+
+### Performance Improvements
+
+* faster code formatting ([67da711](https://github.com/openai/openai-ruby/commit/67da71139e5b572c97539299c39bae04c1d569fd))
+
+
+### Chores
+
+* allow fast-format to use bsd sed as well ([66ac913](https://github.com/openai/openai-ruby/commit/66ac913d195d8b5a5c4474ded88a5f9dad13b7b6))
+
 ## 0.26.0 (2025-09-23)
 
 Full Changelog: [v0.25.1...v0.26.0](https://github.com/openai/openai-ruby/compare/v0.25.1...v0.26.0)

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openai", "~> 0.26.0"
+gem "openai", "~> 0.27.0"
 ```
 
 <!-- x-release-please-end -->

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

@@ -0,0 +1,683 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Streaming
+      class ChatCompletionStream
+        include OpenAI::Internal::Type::BaseStream
+
+        def initialize(raw_stream:, response_format: nil, input_tools: nil)
+          @raw_stream = raw_stream
+          @state = ChatCompletionStreamState.new(
+            response_format: response_format,
+            input_tools: input_tools
+          )
+          @iterator = iterator
+        end
+
+        def get_final_completion
+          until_done
+          @state.get_final_completion
+        end
+
+        def get_output_text
+          completion = get_final_completion
+          text_parts = []
+
+          completion.choices.each do |choice|
+            next unless choice.message.content
+            text_parts << choice.message.content
+          end
+
+          text_parts.join
+        end
+
+        def until_done
+          each {} # rubocop:disable Lint/EmptyBlock
+          self
+        end
+
+        def current_completion_snapshot
+          @state.current_completion_snapshot
+        end
+
+        def text
+          OpenAI::Internal::Util.chain_fused(@iterator) do |yielder|
+            @iterator.each do |event|
+              yielder << event.delta if event.is_a?(ChatContentDeltaEvent)
+            end
+          end
+        end
+
+        private
+
+        def iterator
+          @iterator ||= OpenAI::Internal::Util.chain_fused(@raw_stream) do |y|
+            @raw_stream.each do |raw_event|
+              next unless valid_chat_completion_chunk?(raw_event)
+              @state.handle_chunk(raw_event).each do |event|
+                y << event
+              end
+            end
+          end
+        end
+
+        def valid_chat_completion_chunk?(sse_event)
+          # Although the _raw_stream is always supposed to contain only objects adhering to ChatCompletionChunk schema,
+          # this is broken by the Azure OpenAI in case of Asynchronous Filter enabled.
+          # An easy filter is to check for the "object" property:
+          # - should be "chat.completion.chunk" for a ChatCompletionChunk;
+          # - is an empty string for Asynchronous Filter events.
+          sse_event.object == :"chat.completion.chunk"
+        end
+      end
+
+      class ChatCompletionStreamState
+        attr_reader :current_completion_snapshot
+
+        def initialize(response_format: nil, input_tools: nil)
+          @current_completion_snapshot = nil
+          @choice_event_states = []
+          @input_tools = Array(input_tools)
+          @response_format = response_format
+          @rich_response_format = response_format.is_a?(Class) ? response_format : nil
+        end
+
+        def get_final_completion
+          parse_chat_completion(
+            chat_completion: current_completion_snapshot,
+            response_format: @rich_response_format
+          )
+        end
+
+        # Transforms raw streaming chunks into higher-level events that represent content changes,
+        # tool calls, and completion states. It maintains a running snapshot of the complete
+        # response by accumulating data from each chunk.
+        #
+        # The method performs the following steps:
+        #   1. Unwraps the chunk if it's wrapped in a ChatChunkEvent
+        #   2. Filters out non-ChatCompletionChunk objects
+        #   3. Accumulates the chunk data into the current completion snapshot
+        #   4. Generates appropriate events based on the chunk's content
+        def handle_chunk(chunk)
+          chunk = chunk.chunk if chunk.is_a?(ChatChunkEvent)
+
+          return [] unless chunk.is_a?(OpenAI::Chat::ChatCompletionChunk)
+
+          @current_completion_snapshot = accumulate_chunk(chunk)
+          build_events(chunk: chunk, completion_snapshot: @current_completion_snapshot)
+        end
+
+        private
+
+        def get_choice_state(choice)
+          index = choice.index
+          @choice_event_states[index] ||= ChoiceEventState.new(input_tools: @input_tools)
+        end
+
+        def accumulate_chunk(chunk)
+          if @current_completion_snapshot.nil?
+            return convert_initial_chunk_into_snapshot(chunk)
+          end
+
+          completion_snapshot = @current_completion_snapshot
+
+          chunk.choices.each do |choice|
+            accumulate_choice!(choice, completion_snapshot)
+          end
+
+          completion_snapshot.usage = chunk.usage if chunk.usage
+          completion_snapshot.system_fingerprint = chunk.system_fingerprint if chunk.system_fingerprint
+
+          completion_snapshot
+        end
+
+        def accumulate_choice!(choice, completion_snapshot)
+          choice_snapshot = completion_snapshot.choices[choice.index]
+
+          if choice_snapshot.nil?
+            choice_snapshot = create_new_choice_snapshot(choice)
+            completion_snapshot.choices[choice.index] = choice_snapshot
+          else
+            update_existing_choice_snapshot(choice, choice_snapshot)
+          end
+
+          if choice.finish_reason
+            choice_snapshot.finish_reason = choice.finish_reason
+            handle_finish_reason(choice.finish_reason)
+          end
+
+          parse_tool_calls!(choice.delta.tool_calls, choice_snapshot.message.tool_calls)
+
+          accumulate_logprobs!(choice.logprobs, choice_snapshot)
+        end
+
+        def create_new_choice_snapshot(choice)
+          OpenAI::Internal::Type::Converter.coerce(
+            OpenAI::Models::Chat::ParsedChoice,
+            choice.to_h.except(:delta).merge(message: choice.delta.to_h)
+          )
+        end
+
+        def update_existing_choice_snapshot(choice, choice_snapshot)
+          delta_data = model_dump(choice.delta)
+          message_hash = model_dump(choice_snapshot.message)
+
+          accumulated_data = accumulate_delta(message_hash, delta_data)
+
+          choice_snapshot.message = OpenAI::Internal::Type::Converter.coerce(
+            OpenAI::Chat::ChatCompletionMessage,
+            accumulated_data
+          )
+        end
+
+        def build_events(chunk:, completion_snapshot:)
+          chunk_event = ChatChunkEvent.new(
+            type: :chunk,
+            chunk: chunk,
+            snapshot: completion_snapshot
+          )
+
+          choice_events = chunk.choices.flat_map do |choice|
+            build_choice_events(choice, completion_snapshot)
+          end
+
+          [chunk_event] + choice_events
+        end
+
+        def build_choice_events(choice, completion_snapshot)
+          choice_state = get_choice_state(choice)
+          choice_snapshot = completion_snapshot.choices[choice.index]
+
+          content_delta_events(choice, choice_snapshot) +
+            tool_call_delta_events(choice, choice_snapshot) +
+            logprobs_delta_events(choice, choice_snapshot) +
+            choice_state.get_done_events(
+              choice_chunk: choice,
+              choice_snapshot: choice_snapshot,
+              response_format: @response_format
+            )
+        end
+
+        def content_delta_events(choice, choice_snapshot)
+          events = []
+
+          if choice.delta.content && choice_snapshot.message.content
+            events << ChatContentDeltaEvent.new(
+              type: :"content.delta",
+              delta: choice.delta.content,
+              snapshot: choice_snapshot.message.content,
+              parsed: choice_snapshot.message.parsed
+            )
+          end
+
+          if choice.delta.refusal && choice_snapshot.message.refusal
+            events << ChatRefusalDeltaEvent.new(
+              type: :"refusal.delta",
+              delta: choice.delta.refusal,
+              snapshot: choice_snapshot.message.refusal
+            )
+          end
+
+          events
+        end
+
+        def tool_call_delta_events(choice, choice_snapshot)
+          events = []
+          return events unless choice.delta.tool_calls
+
+          tool_calls = choice_snapshot.message.tool_calls
+          return events unless tool_calls
+
+          choice.delta.tool_calls.each do |tool_call_delta|
+            tool_call = tool_calls[tool_call_delta.index]
+            next unless tool_call.type == :function && tool_call_delta.function
+
+            parsed_args = if tool_call.function.respond_to?(:parsed)
+              tool_call.function.parsed
+            end
+            events << ChatFunctionToolCallArgumentsDeltaEvent.new(
+              type: :"tool_calls.function.arguments.delta",
+              name: tool_call.function.name,
+              index: tool_call_delta.index,
+              arguments: tool_call.function.arguments,
+              parsed: parsed_args,
+              arguments_delta: tool_call_delta.function.arguments || ""
+            )
+          end
+
+          events
+        end
+
+        def logprobs_delta_events(choice, choice_snapshot)
+          events = []
+          return events unless choice.logprobs && choice_snapshot.logprobs
+
+          if choice.logprobs.content && choice_snapshot.logprobs.content
+            events << ChatLogprobsContentDeltaEvent.new(
+              type: :"logprobs.content.delta",
+              content: choice.logprobs.content,
+              snapshot: choice_snapshot.logprobs.content
+            )
+          end
+
+          if choice.logprobs.refusal && choice_snapshot.logprobs.refusal
+            events << ChatLogprobsRefusalDeltaEvent.new(
+              type: :"logprobs.refusal.delta",
+              refusal: choice.logprobs.refusal,
+              snapshot: choice_snapshot.logprobs.refusal
+            )
+          end
+
+          events
+        end
+
+        def handle_finish_reason(finish_reason)
+          return unless parseable_input?
+
+          case finish_reason
+          when :length
+            raise LengthFinishReasonError.new(completion: @chat_completion)
+          when :content_filter
+            raise ContentFilterFinishReasonError.new
+          end
+        end
+
+        def parse_tool_calls!(delta_tool_calls, snapshot_tool_calls)
+          return unless delta_tool_calls && snapshot_tool_calls
+
+          delta_tool_calls.each do |tool_call_chunk|
+            tool_call_snapshot = snapshot_tool_calls[tool_call_chunk.index]
+            next unless tool_call_snapshot&.type == :function
+
+            input_tool = find_input_tool(tool_call_snapshot.function.name)
+            next unless input_tool&.dig(:function, :strict)
+            next unless tool_call_snapshot.function.arguments
+
+            begin
+              tool_call_snapshot.function.parsed = JSON.parse(
+                tool_call_snapshot.function.arguments,
+                symbolize_names: true
+              )
+            rescue JSON::ParserError
+              nil
+            end
+          end
+        end
+
+        def accumulate_logprobs!(choice_logprobs, choice_snapshot)
+          return unless choice_logprobs
+
+          if choice_snapshot.logprobs.nil?
+            choice_snapshot.logprobs = OpenAI::Chat::ChatCompletionChunk::Choice::Logprobs.new(
+              content: choice_logprobs.content,
+              refusal: choice_logprobs.refusal
+            )
+          else
+            if choice_logprobs.content
+              choice_snapshot.logprobs.content ||= []
+              choice_snapshot.logprobs.content.concat(choice_logprobs.content)
+            end
+
+            if choice_logprobs.refusal
+              choice_snapshot.logprobs.refusal ||= []
+              choice_snapshot.logprobs.refusal.concat(choice_logprobs.refusal)
+            end
+          end
+        end
+
+        def parse_chat_completion(chat_completion:, response_format:)
+          choices = chat_completion.choices.map do |choice|
+            if parseable_input?
+              case choice.finish_reason
+              when :length
+                raise LengthFinishReasonError.new(completion: chat_completion)
+              when :content_filter
+                raise ContentFilterFinishReasonError.new
+              end
+            end
+
+            build_parsed_choice(choice, response_format)
+          end
+
+          OpenAI::Internal::Type::Converter.coerce(
+            OpenAI::Chat::ParsedChatCompletion,
+            chat_completion.to_h.merge(choices: choices)
+          )
+        end
+
+        def build_parsed_choice(choice, response_format)
+          message = choice.message
+
+          tool_calls = parse_choice_tool_calls(message.tool_calls)
+
+          choice_data = model_dump(choice)
+          choice_data[:message] = model_dump(message)
+          choice_data[:message][:tool_calls] = tool_calls && !tool_calls.empty? ? tool_calls : nil
+
+          if response_format && message.content && !message.refusal
+            choice_data[:message][:parsed] = parse_content(response_format, message)
+          end
+
+          choice_data
+        end
+
+        def parse_choice_tool_calls(tool_calls)
+          return unless tool_calls
+
+          tool_calls.map do |tool_call|
+            tool_call_hash = model_dump(tool_call)
+            next tool_call_hash unless tool_call_hash[:type] == :function && tool_call_hash[:function]
+
+            function = tool_call_hash[:function]
+            parsed_args = parse_function_tool_arguments(function)
+            function[:parsed] = parsed_args if parsed_args
+
+            tool_call_hash
+          end
+        end
+
+        def parseable_input?
+          @response_format || @input_tools.any?
+        end
+
+        def model_dump(obj)
+          if obj.is_a?(OpenAI::Internal::Type::BaseModel)
+            obj.deep_to_h
+          elsif obj.respond_to?(:to_h)
+            obj.to_h
+          else
+            obj
+          end
+        end
+
+        def find_input_tool(name)
+          @input_tools.find { |tool| tool.dig(:function, :name) == name }
+        end
+
+        def parse_function_tool_arguments(function)
+          return nil unless function[:arguments]
+
+          input_tool = find_input_tool(function[:name])
+          return nil unless input_tool&.dig(:function, :strict)
+
+          parsed = JSON.parse(function[:arguments], symbolize_names: true)
+          return nil unless parsed
+
+          model_class = input_tool[:model] || input_tool.dig(:function, :parameters)
+          if model_class.is_a?(Class)
+            OpenAI::Internal::Type::Converter.coerce(model_class, parsed)
+          else
+            parsed
+          end
+        rescue JSON::ParserError
+          nil
+        end
+
+        def parse_content(response_format, message)
+          return nil unless message.content && !message.refusal
+
+          parsed = JSON.parse(message.content, symbolize_names: true)
+          return nil unless parsed
+
+          if response_format.is_a?(Class)
+            OpenAI::Internal::Type::Converter.coerce(response_format, parsed)
+          else
+            parsed
+          end
+        rescue JSON::ParserError
+          nil
+        end
+
+        def convert_initial_chunk_into_snapshot(chunk)
+          data = chunk.to_h
+
+          choices = []
+          chunk.choices.each do |choice|
+            choice_hash = choice.to_h
+            delta_hash = choice.delta.to_h
+
+            message_data = delta_hash.dup
+            message_data[:role] ||= :assistant
+
+            choice_data = {
+              index: choice_hash[:index],
+              message: message_data,
+              finish_reason: choice_hash[:finish_reason],
+              logprobs: choice_hash[:logprobs]
+            }
+            choices << choice_data
+          end
+
+          OpenAI::Internal::Type::Converter.coerce(
+            OpenAI::Chat::ParsedChatCompletion,
+            {
+              id: data[:id],
+              object: :"chat.completion",
+              created: data[:created],
+              model: data[:model],
+              choices: choices,
+              usage: data[:usage],
+              system_fingerprint: nil,
+              service_tier: data[:service_tier]
+            }
+          )
+        end
+
+        def accumulate_delta(acc, delta)
+          return acc if delta.nil?
+
+          delta.each do |key, delta_value| # rubocop:disable Metrics/BlockLength
+            key = key.to_sym if key.is_a?(String)
+
+            unless acc.key?(key)
+              acc[key] = delta_value
+              next
+            end
+
+            acc_value = acc[key]
+            if acc_value.nil?
+              acc[key] = delta_value
+              next
+            end
+
+            # Special properties that should be replaced, not accumulated.
+            if [:index, :type, :parsed].include?(key)
+              acc[key] = delta_value
+              next
+            end
+
+            if acc_value.is_a?(String) && delta_value.is_a?(String)
+              acc[key] = acc_value + delta_value
+            elsif acc_value.is_a?(Numeric) && delta_value.is_a?(Numeric) # rubocop:disable Lint/DuplicateBranch
+              acc[key] = acc_value + delta_value
+            elsif acc_value.is_a?(Hash) && delta_value.is_a?(Hash)
+              acc[key] = accumulate_delta(acc_value, delta_value)
+            elsif acc_value.is_a?(Array) && delta_value.is_a?(Array)
+              if acc_value.all? { |x| x.is_a?(String) || x.is_a?(Numeric) }
+                acc_value.concat(delta_value)
+                next
+              end
+
+              delta_value.each do |delta_entry|
+                unless delta_entry.is_a?(Hash)
+                  raise TypeError,
+                        "Unexpected list delta entry is not a hash: #{delta_entry}"
+                end
+
+                index = delta_entry[:index] || delta_entry["index"]
+                if index.nil?
+                  raise RuntimeError,
+                        "Expected list delta entry to have an `index` key; #{delta_entry}"
+                end
+                unless index.is_a?(Integer)
+                  raise TypeError,
+                        "Unexpected, list delta entry `index` value is not an integer; #{index}"
+                end
+
+                if acc_value[index].nil?
+                  acc_value[index] = delta_entry
+                elsif acc_value[index].is_a?(Hash)
+                  acc_value[index] = accumulate_delta(acc_value[index], delta_entry)
+                end
+              end
+            else
+              acc[key] = acc_value
+            end
+          end
+
+          acc
+        end
+      end
+
+      class ChoiceEventState
+        def initialize(input_tools:)
+          @input_tools = Array(input_tools)
+          @content_done = false
+          @refusal_done = false
+          @logprobs_content_done = false
+          @logprobs_refusal_done = false
+          @done_tool_calls = Set.new
+          @current_tool_call_index = nil
+        end
+
+        def get_done_events(choice_chunk:, choice_snapshot:, response_format:)
+          events = []
+
+          if choice_snapshot.finish_reason
+            events.concat(content_done_events(choice_snapshot, response_format))
+
+            if @current_tool_call_index && !@done_tool_calls.include?(@current_tool_call_index)
+              event = tool_done_event(choice_snapshot, @current_tool_call_index)
+              events << event if event
+            end
+          end
+
+          Array(choice_chunk.delta.tool_calls).each do |tool_call|
+            if @current_tool_call_index != tool_call.index
+              events.concat(content_done_events(choice_snapshot, response_format))
+
+              if @current_tool_call_index
+                event = tool_done_event(choice_snapshot, @current_tool_call_index)
+                events << event if event
+              end
+            end
+
+            @current_tool_call_index = tool_call.index
+          end
+
+          events
+        end
+
+        private
+
+        def content_done_events(choice_snapshot, response_format)
+          events = []
+
+          if choice_snapshot.message.content && !@content_done
+            @content_done = true
+            parsed = parse_content(choice_snapshot.message, response_format)
+            choice_snapshot.message.parsed = parsed
+
+            events << ChatContentDoneEvent.new(
+              type: :"content.done",
+              content: choice_snapshot.message.content,
+              parsed: parsed
+            )
+          end
+
+          if choice_snapshot.message.refusal && !@refusal_done
+            @refusal_done = true
+            events << ChatRefusalDoneEvent.new(
+              type: :"refusal.done",
+              refusal: choice_snapshot.message.refusal
+            )
+          end
+
+          events + logprobs_done_events(choice_snapshot)
+        end
+
+        def logprobs_done_events(choice_snapshot)
+          events = []
+          logprobs = choice_snapshot.logprobs
+          return events unless logprobs
+
+          if logprobs.content&.any? && !@logprobs_content_done
+            @logprobs_content_done = true
+            events << ChatLogprobsContentDoneEvent.new(
+              type: :"logprobs.content.done",
+              content: logprobs.content
+            )
+          end
+
+          if logprobs.refusal&.any? && !@logprobs_refusal_done
+            @logprobs_refusal_done = true
+            events << ChatLogprobsRefusalDoneEvent.new(
+              type: :"logprobs.refusal.done",
+              refusal: logprobs.refusal
+            )
+          end
+
+          events
+        end
+
+        def tool_done_event(choice_snapshot, tool_index)
+          return nil if @done_tool_calls.include?(tool_index)
+
+          @done_tool_calls.add(tool_index)
+
+          tool_call = choice_snapshot.message.tool_calls&.[](tool_index)
+          return nil unless tool_call&.type == :function
+
+          parsed_args = parse_function_tool_arguments(tool_call.function)
+
+          if tool_call.function.respond_to?(:parsed=)
+            tool_call.function.parsed = parsed_args
+          end
+
+          ChatFunctionToolCallArgumentsDoneEvent.new(
+            type: :"tool_calls.function.arguments.done",
+            index: tool_index,
+            name: tool_call.function.name,
+            arguments: tool_call.function.arguments,
+            parsed: parsed_args
+          )
+        end
+
+        def parse_content(message, response_format)
+          return nil unless response_format && message.content
+
+          parsed = JSON.parse(message.content, symbolize_names: true)
+          if response_format.is_a?(Class)
+            OpenAI::Internal::Type::Converter.coerce(response_format, parsed)
+          else
+            parsed
+          end
+        rescue JSON::ParserError
+          nil
+        end
+
+        def parse_function_tool_arguments(function)
+          return nil unless function.arguments
+
+          tool = find_input_tool(function.name)
+          return nil unless tool&.dig(:function, :strict)
+
+          parsed = JSON.parse(function.arguments, symbolize_names: true)
+
+          if tool[:model]
+            OpenAI::Internal::Type::Converter.coerce(tool[:model], parsed)
+          else
+            parsed
+          end
+        rescue JSON::ParserError
+          nil
+        end
+
+        def find_input_tool(name)
+          @input_tools.find { |tool| tool.dig(:function, :name) == name }
+        end
+      end
+    end
+  end
+end

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/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.0"
 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/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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openai
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - OpenAI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-23 00:00:00.000000000 Z
+date: 2025-09-27 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