openai 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 252a9ce9833b0a9f66be94b76081f34716e348ebca732e63c3e16c105ed42ea1
-  data.tar.gz: d4d8b36822ee74af77508ec8e48b472d72d619333e468055695158e242c49760
+  metadata.gz: 38a07c18c8f0197c2edc1400139623aefc1c85e8a0fbf167a86afc53f1399a75
+  data.tar.gz: 13b400c12a9d2bef1ebcf2722413e3e6b1915992df539542f4a73f084b839cfa
 SHA512:
-  metadata.gz: f27c40e40df727c8da570a4f6b1e20f72a87baa710efd3957bb0fbbcc23eb1dd78d03b1bcc3c3cf5684d4db4b062c392c1c3d970093c8e0fac89ef85db053db3
-  data.tar.gz: 21fe44d1605c6196d7321dcb7efa7d951a2523ba71859eab1bf242ff3314afe0cce25201c21b141f9f3902b684cb577ba51c520d12602d1279eccb770769e3a4
+  metadata.gz: d5a62aacb54b1e50526da647c3ea91adbe8dbf69bd8c4f0df08a0a6c9fa4b49ebb79bd4b51bf5efc55d06d514af286b7658c153a6498298761dedc2f73c42c20
+  data.tar.gz: 9c7a2bbe1053d11780882a11a9617ea4cd2ee4a6648f278003be7da107c0e5dc281beeb6dbce3db168f4c9338d161742ab48bc03711a8c4f05e540f11e6f40d0

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.12.0 (2025-07-03)
+
+Full Changelog: [v0.11.0...v0.12.0](https://github.com/openai/openai-ruby/compare/v0.11.0...v0.12.0)
+
+### Features
+
+* ensure partial jsons in structured ouput are handled gracefully ([#740](https://github.com/openai/openai-ruby/issues/740)) ([5deec70](https://github.com/openai/openai-ruby/commit/5deec708bad1ceb1a03e9aa65f737e3f89ce6455))
+* responses streaming helpers ([#721](https://github.com/openai/openai-ruby/issues/721)) ([c2f4270](https://github.com/openai/openai-ruby/commit/c2f42708e41492f1c22886735079973510fb2789))
+
+
+### Chores
+
+* **ci:** only run for pushes and fork pull requests ([97538e2](https://github.com/openai/openai-ruby/commit/97538e266f6f9a0e09669453539ee52ca56f4f59))
+* **internal:** allow streams to also be unwrapped on a per-row basis ([49bdadf](https://github.com/openai/openai-ruby/commit/49bdadfc0d3400664de0c8e7cfd59879faec45b8))
+* **internal:** minor refactoring of json helpers ([#744](https://github.com/openai/openai-ruby/issues/744)) ([f13edee](https://github.com/openai/openai-ruby/commit/f13edee16325be04335443cb886a7c2024155fd9))
+
 ## 0.11.0 (2025-06-26)
 
 Full Changelog: [v0.10.0...v0.11.0](https://github.com/openai/openai-ruby/compare/v0.10.0...v0.11.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.11.0"
+gem "openai", "~> 0.12.0"
 ```
 
 <!-- x-release-please-end -->
@@ -42,16 +42,14 @@ puts(chat_completion)
 
 We provide support for streaming responses using Server-Sent Events (SSE).
 
-**coming soon:** `openai.chat.completions.stream` will soon come with Python SDK-style higher-level streaming responses support.
-
 ```ruby
-stream = openai.chat.completions.stream_raw(
-  messages: [{role: "user", content: "Say this is a test"}],
+stream = openai.responses.stream(
+  input: "Write a haiku about OpenAI.",
   model: :"gpt-4.1"
 )
 
-stream.each do |completion|
-  puts(completion)
+stream.each do |event|
+  puts(event.type)
 end
 ```
 

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Streaming
+      class ResponseTextDeltaEvent < OpenAI::Models::Responses::ResponseTextDeltaEvent
+        required :snapshot, String
+      end
+
+      class ResponseTextDoneEvent < OpenAI::Models::Responses::ResponseTextDoneEvent
+        optional :parsed, Object
+      end
+
+      class ResponseFunctionCallArgumentsDeltaEvent < OpenAI::Models::Responses::ResponseFunctionCallArgumentsDeltaEvent
+        required :snapshot, String
+      end
+
+      class ResponseCompletedEvent < OpenAI::Models::Responses::ResponseCompletedEvent
+        required :response, OpenAI::Models::Responses::Response
+      end
+    end
+  end
+end

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require_relative "events"
+
+module OpenAI
+  module Helpers
+    module Streaming
+      class ResponseStream
+        include OpenAI::Internal::Type::BaseStream
+
+        def initialize(raw_stream:, text_format: nil, starting_after: nil)
+          @text_format = text_format
+          @starting_after = starting_after
+          @raw_stream = raw_stream
+          @iterator = iterator
+          @state = ResponseStreamState.new(
+            text_format: text_format
+          )
+        end
+
+        def until_done
+          each {} # rubocop:disable Lint/EmptyBlock
+          self
+        end
+
+        def text
+          OpenAI::Internal::Util.chain_fused(@iterator) do |yielder|
+            @iterator.each do |event|
+              case event
+              when OpenAI::Streaming::ResponseTextDeltaEvent
+                yielder << event.delta
+              end
+            end
+          end
+        end
+
+        def get_final_response
+          until_done
+          response = @state.completed_response
+          raise RuntimeError.new("Didn't receive a 'response.completed' event") unless response
+          response
+        end
+
+        def get_output_text
+          response = get_final_response
+          text_parts = []
+
+          response.output.each do |output|
+            next unless output.type == :message
+
+            output.content.each do |content|
+              next unless content.type == :output_text
+              text_parts << content.text
+            end
+          end
+
+          text_parts.join
+        end
+
+        private
+
+        def iterator
+          @iterator ||= OpenAI::Internal::Util.chain_fused(@raw_stream) do |y|
+            @raw_stream.each do |raw_event|
+              events_to_yield = @state.handle_event(raw_event)
+              events_to_yield.each do |event|
+                if @starting_after.nil? || event.sequence_number > @starting_after
+                  y << event
+                end
+              end
+            end
+          end
+        end
+      end
+
+      class ResponseStreamState
+        attr_reader :completed_response
+
+        def initialize(text_format:)
+          @current_snapshot = nil
+          @completed_response = nil
+          @text_format = text_format
+        end
+
+        def handle_event(event)
+          @current_snapshot = accumulate_event(
+            event: event,
+            current_snapshot: @current_snapshot
+          )
+
+          events_to_yield = []
+
+          case event
+          when OpenAI::Models::Responses::ResponseTextDeltaEvent
+            output = @current_snapshot.output[event.output_index]
+            assert_type(output, :message)
+
+            content = output.content[event.content_index]
+            assert_type(content, :output_text)
+
+            events_to_yield << OpenAI::Streaming::ResponseTextDeltaEvent.new(
+              content_index: event.content_index,
+              delta: event.delta,
+              item_id: event.item_id,
+              output_index: event.output_index,
+              sequence_number: event.sequence_number,
+              type: event.type,
+              snapshot: content.text
+            )
+
+          when OpenAI::Models::Responses::ResponseTextDoneEvent
+            output = @current_snapshot.output[event.output_index]
+            assert_type(output, :message)
+
+            content = output.content[event.content_index]
+            assert_type(content, :output_text)
+
+            parsed = parse_structured_text(content.text)
+
+            events_to_yield << OpenAI::Streaming::ResponseTextDoneEvent.new(
+              content_index: event.content_index,
+              item_id: event.item_id,
+              output_index: event.output_index,
+              sequence_number: event.sequence_number,
+              text: event.text,
+              type: event.type,
+              parsed: parsed
+            )
+
+          when OpenAI::Models::Responses::ResponseFunctionCallArgumentsDeltaEvent
+            output = @current_snapshot.output[event.output_index]
+            assert_type(output, :function_call)
+
+            events_to_yield << OpenAI::Streaming::ResponseFunctionCallArgumentsDeltaEvent.new(
+              delta: event.delta,
+              item_id: event.item_id,
+              output_index: event.output_index,
+              sequence_number: event.sequence_number,
+              type: event.type,
+              snapshot: output.arguments
+            )
+
+          when OpenAI::Models::Responses::ResponseCompletedEvent
+            events_to_yield << OpenAI::Streaming::ResponseCompletedEvent.new(
+              sequence_number: event.sequence_number,
+              type: event.type,
+              response: event.response
+            )
+
+          else
+            # Pass through other events unchanged.
+            events_to_yield << event
+          end
+
+          events_to_yield
+        end
+
+        def accumulate_event(event:, current_snapshot:)
+          if current_snapshot.nil?
+            unless event.is_a?(OpenAI::Models::Responses::ResponseCreatedEvent)
+              raise "Expected first event to be response.created"
+            end
+
+            # Use the converter to create a new, isolated copy of the response object.
+            # This ensures proper type validation and prevents shared object references.
+            return OpenAI::Internal::Type::Converter.coerce(
+              OpenAI::Models::Responses::Response,
+              event.response
+            )
+          end
+
+          case event
+          when OpenAI::Models::Responses::ResponseOutputItemAddedEvent
+            current_snapshot.output.push(event.item)
+
+          when OpenAI::Models::Responses::ResponseContentPartAddedEvent
+            output = current_snapshot.output[event.output_index]
+            if output && output.type == :message
+              output.content.push(event.part)
+              current_snapshot.output[event.output_index] = output
+            end
+
+          when OpenAI::Models::Responses::ResponseTextDeltaEvent
+            output = current_snapshot.output[event.output_index]
+            if output && output.type == :message
+              content = output.content[event.content_index]
+              if content && content.type == :output_text
+                content.text += event.delta
+                output.content[event.content_index] = content
+                current_snapshot.output[event.output_index] = output
+              end
+            end
+
+          when OpenAI::Models::Responses::ResponseFunctionCallArgumentsDeltaEvent
+            output = current_snapshot.output[event.output_index]
+            if output && output.type == :function_call
+              output.arguments = (output.arguments || "") + event.delta
+              current_snapshot.output[event.output_index] = output
+            end
+
+          when OpenAI::Models::Responses::ResponseCompletedEvent
+            @completed_response = event.response
+          end
+
+          current_snapshot
+        end
+
+        private
+
+        def assert_type(object, expected_type)
+          return if object && object.type == expected_type
+          actual_type = object ? object.type : "nil"
+          raise "Invalid state: expected #{expected_type} but got #{actual_type}"
+        end
+
+        def parse_structured_text(text)
+          return nil unless @text_format && text
+
+          begin
+            parsed = JSON.parse(text, symbolize_names: true)
+            OpenAI::Internal::Type::Converter.coerce(@text_format, parsed)
+          rescue JSON::ParserError => e
+            raise RuntimeError.new(
+              "Failed to parse structured text as JSON for #{@text_format}: #{e.message}. " \
+              "Raw text: #{text.inspect}"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/structured_output/parsed_json.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module StructuredOutput
+      # @abstract
+      #
+      # Like OpenAI::Internal::Type::Unknown, but for parsed JSON values, which can be incomplete or malformed.
+      class ParsedJson < OpenAI::Internal::Type::Unknown
+        class << self
+          # @api private
+          #
+          # No coercion needed for Unknown type.
+          #
+          # @param value [Object]
+          #
+          # @param state [Hash{Symbol=>Object}] .
+          #
+          #   @option state [Boolean] :translate_names
+          #
+          #   @option state [Boolean] :strictness
+          #
+          #   @option state [Hash{Symbol=>Object}] :exactness
+          #
+          #   @option state [Class<StandardError>] :error
+          #
+          #   @option state [Integer] :branched
+          #
+          # @return [Object]
+          def coerce(value, state:)
+            (state[:error] = value) if value.is_a?(StandardError)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openai/internal/stream.rb

@@ -47,7 +47,8 @@ module OpenAI
                   message: message
                 )
               in decoded
-                y << OpenAI::Internal::Type::Converter.coerce(@model, decoded)
+                unwrapped = OpenAI::Internal::Util.dig(decoded, @unwrap)
+                y << OpenAI::Internal::Type::Converter.coerce(@model, unwrapped)
               end
             else
             end

data/lib/openai/internal/transport/base_client.rb

@@ -471,6 +471,7 @@ module OpenAI
           self.class.validate!(req)
           model = req.fetch(:model) { OpenAI::Internal::Type::Unknown }
           opts = req[:options].to_h
+          unwrap = req[:unwrap]
           OpenAI::RequestOptions.validate!(opts)
           request = build_request(req.except(:options), opts)
           url = request.fetch(:url)
@@ -487,11 +488,18 @@ module OpenAI
           decoded = OpenAI::Internal::Util.decode_content(response, stream: stream)
           case req
           in {stream: Class => st}
-            st.new(model: model, url: url, status: status, response: response, stream: decoded)
+            st.new(
+              model: model,
+              url: url,
+              status: status,
+              response: response,
+              unwrap: unwrap,
+              stream: decoded
+            )
           in {page: Class => page}
             page.new(client: self, req: req, headers: response, page_data: decoded)
           else
-            unwrapped = OpenAI::Internal::Util.dig(decoded, req[:unwrap])
+            unwrapped = OpenAI::Internal::Util.dig(decoded, unwrap)
             OpenAI::Internal::Type::Converter.coerce(model, unwrapped)
           end
         end

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

@@ -64,12 +64,14 @@ module OpenAI
         # @param url [URI::Generic]
         # @param status [Integer]
         # @param response [Net::HTTPResponse]
+        # @param unwrap [Symbol, Integer, Array<Symbol, Integer>, Proc]
         # @param stream [Enumerable<Object>]
-        def initialize(model:, url:, status:, response:, stream:)
+        def initialize(model:, url:, status:, response:, unwrap:, stream:)
           @model = model
           @url = url
           @status = status
           @response = response
+          @unwrap = unwrap
           @stream = stream
           @iterator = iterator
 

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

@@ -14,7 +14,7 @@ module OpenAI
         #   The parsed contents of the message, if JSON schema is specified.
         #
         #   @return [Object, nil]
-        optional :parsed, OpenAI::Internal::Type::Unknown
+        optional :parsed, OpenAI::StructuredOutput::ParsedJson
 
         # @!attribute refusal
         #   The refusal message generated by the model.

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

@@ -44,7 +44,7 @@ module OpenAI
           #   The parsed contents of the arguments.
           #
           #   @return [Object, nil]
-          required :parsed, OpenAI::Internal::Type::Unknown
+          required :parsed, OpenAI::StructuredOutput::ParsedJson
 
           # @!attribute name
           #   The name of the function to call.

data/lib/openai/models/responses/response_function_tool_call.rb

@@ -14,7 +14,7 @@ module OpenAI
         #   The parsed contents of the arguments.
         #
         #   @return [Object, nil]
-        required :parsed, OpenAI::Internal::Type::Unknown
+        required :parsed, OpenAI::StructuredOutput::ParsedJson
 
         # @!attribute call_id
         #   The unique ID of the function tool call generated by the model.

data/lib/openai/models/responses/response_output_text.rb

@@ -23,7 +23,7 @@ module OpenAI
         #   The parsed contents of the output, if JSON schema is specified.
         #
         #   @return [Object, nil]
-        optional :parsed, OpenAI::Internal::Type::Unknown
+        optional :parsed, OpenAI::StructuredOutput::ParsedJson
 
         # @!attribute type
         #   The type of the output text. Always `output_text`.

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

@@ -104,7 +104,6 @@ module OpenAI
             raise ArgumentError.new(message)
           end
 
-          # rubocop:disable Layout/LineLength
           model = nil
           tool_models = {}
           case parsed
@@ -157,11 +156,16 @@ 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)
-                parsed = JSON.parse(message.fetch(:content), symbolize_names: true)
+                begin
+                  parsed = JSON.parse(message.fetch(:content), symbolize_names: true)
+                rescue JSON::ParserError => e
+                  parsed = e
+                end
                 coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
                 message.store(:parsed, coerced)
               end
@@ -171,7 +175,11 @@ module OpenAI
                 func = tool_call.fetch(:function)
                 next if (model = tool_models[func.fetch(:name)]).nil?
 
-                parsed = JSON.parse(func.fetch(:arguments), symbolize_names: true)
+                begin
+                  parsed = JSON.parse(func.fetch(:arguments), symbolize_names: true)
+                rescue JSON::ParserError => e
+                  parsed = e
+                end
                 coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
                 func.store(:parsed, coerced)
               end
@@ -179,7 +187,7 @@ module OpenAI
 
             raw
           end
-          # rubocop:enable Layout/LineLength
+          # rubocop:enable Metrics/BlockLength
 
           @client.request(
             method: :post,

data/lib/openai/resources/responses.rb

@@ -81,81 +81,12 @@ module OpenAI
           raise ArgumentError.new(message)
         end
 
-        model = nil
-        tool_models = {}
-        case parsed
-        in {text: OpenAI::StructuredOutput::JsonSchemaConverter => model}
-          parsed.update(
-            text: {
-              format: {
-                type: :json_schema,
-                strict: true,
-                name: model.name.split("::").last,
-                schema: model.to_json_schema
-              }
-            }
-          )
-        in {text: {format: OpenAI::StructuredOutput::JsonSchemaConverter => model}}
-          parsed.fetch(:text).update(
-            format: {
-              type: :json_schema,
-              strict: true,
-              name: model.name.split("::").last,
-              schema: model.to_json_schema
-            }
-          )
-        in {text: {format: {type: :json_schema, schema: OpenAI::StructuredOutput::JsonSchemaConverter => model}}}
-          parsed.dig(:text, :format).store(:schema, model.to_json_schema)
-        in {tools: Array => tools}
-          mapped = tools.map do |tool|
-            case tool
-            in OpenAI::StructuredOutput::JsonSchemaConverter
-              name = tool.name.split("::").last
-              tool_models.store(name, tool)
-              {
-                type: :function,
-                strict: true,
-                name: name,
-                parameters: tool.to_json_schema
-              }
-            in {type: :function, parameters: OpenAI::StructuredOutput::JsonSchemaConverter => params}
-              func = tool.fetch(:function)
-              name = func[:name] ||= params.name.split("::").last
-              tool_models.store(name, params)
-              func.update(parameters: params.to_json_schema)
-              tool
-            else
-              tool
-            end
-          end
-          tools.replace(mapped)
-        else
-        end
+        model, tool_models = get_structured_output_models(parsed)
 
         unwrap = ->(raw) do
-          if model.is_a?(OpenAI::StructuredOutput::JsonSchemaConverter)
-            raw[:output]
-              &.flat_map do |output|
-                next [] unless output[:type] == "message"
-                output[:content].to_a
-              end
-              &.each do |content|
-                next unless content[:type] == "output_text"
-                parsed = JSON.parse(content.fetch(:text), symbolize_names: true)
-                coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
-                content.store(:parsed, coerced)
-              end
-          end
-          raw[:output]&.each do |output|
-            next unless output[:type] == "function_call"
-            next if (model = tool_models[output.fetch(:name)]).nil?
-            parsed = JSON.parse(output.fetch(:arguments), symbolize_names: true)
-            coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
-            output.store(:parsed, coerced)
-          end
-
-          raw
+          parse_structured_outputs!(raw, model, tool_models)
         end
+
         @client.request(
           method: :post,
           path: "responses",
@@ -166,8 +97,112 @@ module OpenAI
         )
       end
 
-      def stream
-        raise NotImplementedError.new("higher level helpers are coming soon!")
+      # See {OpenAI::Resources::Responses#create} for non-streaming counterpart.
+      #
+      # Some parameter documentations has been truncated, see
+      # {OpenAI::Models::Responses::ResponseCreateParams} for more details.
+      #
+      # Creates a model response. Provide
+      # [text](https://platform.openai.com/docs/guides/text) or
+      # [image](https://platform.openai.com/docs/guides/images) inputs to generate
+      # [text](https://platform.openai.com/docs/guides/text) or
+      # [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have
+      # the model call your own
+      # [custom code](https://platform.openai.com/docs/guides/function-calling) or use
+      # built-in [tools](https://platform.openai.com/docs/guides/tools) like
+      # [web search](https://platform.openai.com/docs/guides/tools-web-search) or
+      # [file search](https://platform.openai.com/docs/guides/tools-file-search) to use
+      # your own data as input for the model's response.
+      #
+      # @overload stream_raw(input:, model:, background: nil, include: nil, instructions: nil, max_output_tokens: nil, metadata: nil, parallel_tool_calls: nil, previous_response_id: nil, prompt: nil, reasoning: nil, service_tier: nil, store: nil, temperature: nil, text: nil, tool_choice: nil, tools: nil, top_p: nil, truncation: nil, user: nil, request_options: {})
+      #
+      # @param input [String, Array<OpenAI::Models::Responses::EasyInputMessage, OpenAI::Models::Responses::ResponseInputItem::Message, OpenAI::Models::Responses::ResponseOutputMessage, OpenAI::Models::Responses::ResponseFileSearchToolCall, OpenAI::Models::Responses::ResponseComputerToolCall, OpenAI::Models::Responses::ResponseInputItem::ComputerCallOutput, OpenAI::Models::Responses::ResponseFunctionWebSearch, OpenAI::Models::Responses::ResponseFunctionToolCall, OpenAI::Models::Responses::ResponseInputItem::FunctionCallOutput, OpenAI::Models::Responses::ResponseReasoningItem, OpenAI::Models::Responses::ResponseInputItem::ImageGenerationCall, OpenAI::Models::Responses::ResponseCodeInterpreterToolCall, OpenAI::Models::Responses::ResponseInputItem::LocalShellCall, OpenAI::Models::Responses::ResponseInputItem::LocalShellCallOutput, OpenAI::Models::Responses::ResponseInputItem::McpListTools, OpenAI::Models::Responses::ResponseInputItem::McpApprovalRequest, OpenAI::Models::Responses::ResponseInputItem::McpApprovalResponse, OpenAI::Models::Responses::ResponseInputItem::McpCall, OpenAI::Models::Responses::ResponseInputItem::ItemReference>] Text, image, or file inputs to the model, used to generate a response.
+      #
+      # @param model [String, Symbol, OpenAI::Models::ChatModel, OpenAI::Models::ResponsesModel::ResponsesOnlyModel] Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI
+      #
+      # @param background [Boolean, nil] Whether to run the model response in the background.
+      #
+      # @param include [Array<Symbol, OpenAI::Models::Responses::ResponseIncludable>, nil] Specify additional output data to include in the model response. Currently
+      #
+      # @param instructions [String, nil] A system (or developer) message inserted into the model's context.
+      #
+      # @param max_output_tokens [Integer, nil] An upper bound for the number of tokens that can be generated for a response, in
+      #
+      # @param metadata [Hash{Symbol=>String}, nil] Set of 16 key-value pairs that can be attached to an object. This can be
+      #
+      # @param parallel_tool_calls [Boolean, nil] Whether to allow the model to run tool calls in parallel.
+      #
+      # @param previous_response_id [String, nil] The unique ID of the previous response to the model. Use this to resume streams from a given response.
+      #
+      # @param prompt [OpenAI::Models::Responses::ResponsePrompt, nil] Reference to a prompt template and its variables.
+      #
+      # @param reasoning [OpenAI::Models::Reasoning, nil] **o-series models only**
+      #
+      # @param service_tier [Symbol, OpenAI::Models::Responses::ResponseCreateParams::ServiceTier, nil] Specifies the latency tier to use for processing the request. This parameter is
+      #
+      # @param store [Boolean, nil] Whether to store the generated model response for later retrieval via
+      #
+      # @param temperature [Float, nil] What sampling temperature to use, between 0 and 2. Higher values like 0.8 will m
+      #
+      # @param text [OpenAI::Models::Responses::ResponseTextConfig] Configuration options for a text response from the model. Can be plain
+      #
+      # @param tool_choice [Symbol, OpenAI::Models::Responses::ToolChoiceOptions, OpenAI::Models::Responses::ToolChoiceTypes, OpenAI::Models::Responses::ToolChoiceFunction] How the model should select which tool (or tools) to use when generating
+      #
+      # @param tools [Array<OpenAI::Models::Responses::FunctionTool, OpenAI::Models::Responses::FileSearchTool, OpenAI::Models::Responses::ComputerTool, OpenAI::Models::Responses::Tool::Mcp, OpenAI::Models::Responses::Tool::CodeInterpreter, OpenAI::Models::Responses::Tool::ImageGeneration, OpenAI::Models::Responses::Tool::LocalShell, OpenAI::Models::Responses::WebSearchTool>] An array of tools the model may call while generating a response. You
+      #
+      # @param top_p [Float, nil] An alternative to sampling with temperature, called nucleus sampling,
+      #
+      # @param truncation [Symbol, OpenAI::Models::Responses::ResponseCreateParams::Truncation, nil] The truncation strategy to use for the model response.
+      #
+      # @param user [String] A stable identifier for your end-users.
+      #
+      # @param request_options [OpenAI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [OpenAI::Helpers::Streaming::ResponseStream]
+      #
+      # @see OpenAI::Models::Responses::ResponseCreateParams
+      def stream(params)
+        parsed, options = OpenAI::Responses::ResponseCreateParams.dump_request(params)
+        starting_after, previous_response_id = parsed.values_at(:starting_after, :previous_response_id)
+
+        if starting_after && !previous_response_id
+          raise ArgumentError, "starting_after can only be used with previous_response_id"
+        end
+        model, tool_models = get_structured_output_models(parsed)
+
+        if previous_response_id
+          retrieve_params = {}
+          retrieve_params[:include] = params[:include] if params[:include]
+          retrieve_params[:request_options] = params[:request_options] if params[:request_options]
+
+          raw_stream = retrieve_streaming(previous_response_id, retrieve_params)
+        else
+          unwrap = ->(raw) do
+            if raw[:type] == "response.completed" && raw[:response]
+              parse_structured_outputs!(raw[:response], model, tool_models)
+            end
+            raw
+          end
+
+          parsed[:stream] = true
+
+          raw_stream = @client.request(
+            method: :post,
+            path: "responses",
+            headers: {"accept" => "text/event-stream"},
+            body: parsed,
+            stream: OpenAI::Internal::Stream,
+            model: OpenAI::Models::Responses::ResponseStreamEvent,
+            unwrap: unwrap,
+            options: options
+          )
+        end
+
+        OpenAI::Streaming::ResponseStream.new(
+          raw_stream: raw_stream,
+          text_format: model,
+          starting_after: starting_after
+        )
       end
 
       # See {OpenAI::Resources::Responses#create} for non-streaming counterpart.
@@ -207,7 +242,7 @@ module OpenAI
       #
       # @param parallel_tool_calls [Boolean, nil] Whether to allow the model to run tool calls in parallel.
       #
-      # @param previous_response_id [String, nil] The unique ID of the previous response to the model. Use this to
+      # @param previous_response_id [String, nil] The unique ID of the previous response to the response to the model. Use this to resume streams from a given response.
       #
       # @param prompt [OpenAI::Models::Responses::ResponsePrompt, nil] Reference to a prompt template and its variables.
       #
@@ -245,6 +280,7 @@ module OpenAI
           raise ArgumentError.new(message)
         end
         parsed.store(:stream, true)
+
         @client.request(
           method: :post,
           path: "responses",
@@ -378,6 +414,143 @@ module OpenAI
         @client = client
         @input_items = OpenAI::Resources::Responses::InputItems.new(client: client)
       end
+
+      private
+
+      # Post-processes raw API responses to parse and coerce structured outputs into typed Ruby objects.
+      #
+      # This method enhances the raw API response by parsing JSON content in structured outputs
+      # (both text outputs and function/tool calls) and converting them to their corresponding
+      # Ruby types using the JsonSchemaConverter models identified during request preparation.
+      #
+      # @param raw [Hash] The raw API response hash that will be mutated with parsed data
+      # @param model [JsonSchemaConverter|nil] The converter for structured text output, if specified
+      # @param tool_models [Hash<String, JsonSchemaConverter>] Hash mapping tool names to their converters
+      # @return [Hash] The mutated raw response with added :parsed fields containing typed Ruby objects
+      #
+      # The method performs two main transformations:
+      # 1. For structured text outputs: Finds output_text content, parses the JSON, and coerces it
+      #    to the model type, adding the result as content[:parsed]
+      # 2. For function/tool calls: Looks up the tool's converter by name, parses the arguments JSON,
+      #    and coerces it to the appropriate type, adding the result as output[:parsed]
+      def parse_structured_outputs!(raw, model, tool_models)
+        if model.is_a?(OpenAI::StructuredOutput::JsonSchemaConverter)
+          raw[:output]
+            &.flat_map do |output|
+              next [] unless output[:type] == "message"
+              output[:content].to_a
+            end
+            &.each do |content|
+              next unless content[:type] == "output_text"
+              begin
+                parsed = JSON.parse(content.fetch(:text), symbolize_names: true)
+              rescue JSON::ParserError => e
+                parsed = e
+              end
+              coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
+              content.store(:parsed, coerced)
+            end
+        end
+        raw[:output]&.each do |output|
+          next unless output[:type] == "function_call"
+          next if (model = tool_models[output.fetch(:name)]).nil?
+          begin
+            parsed = JSON.parse(output.fetch(:arguments), symbolize_names: true)
+          rescue JSON::ParserError => e
+            parsed = e
+          end
+          coerced = OpenAI::Internal::Type::Converter.coerce(model, parsed)
+          output.store(:parsed, coerced)
+        end
+
+        raw
+      end
+
+      # Extracts structured output models from request parameters and converts them to JSON Schema format.
+      #
+      # This method processes the parsed request parameters to identify any JsonSchemaConverter instances
+      # that define expected output schemas. It transforms these Ruby schema definitions into the JSON
+      # Schema format required by the OpenAI API, enabling type-safe structured outputs.
+      #
+      # @param parsed [Hash] The parsed request parameters that may contain structured output definitions
+      # @return [Array<(JsonSchemaConverter|nil, Hash)>] A tuple containing:
+      #   - model: The JsonSchemaConverter for structured text output (or nil if not specified)
+      #   - tool_models: Hash mapping tool names to their JsonSchemaConverter models
+      #
+      # The method handles multiple ways structured outputs can be specified:
+      # - Direct text format: { text: JsonSchemaConverter }
+      # - Nested text format: { text: { format: JsonSchemaConverter } }
+      # - Deep nested format: { text: { format: { type: :json_schema, schema: JsonSchemaConverter } } }
+      # - Tool parameters: { tools: [JsonSchemaConverter, ...] } or tools with parameters as converters
+      def get_structured_output_models(parsed)
+        model = nil
+        tool_models = {}
+
+        case parsed
+        in {text: OpenAI::StructuredOutput::JsonSchemaConverter => model}
+          parsed.update(
+            text: {
+              format: {
+                type: :json_schema,
+                strict: true,
+                name: model.name.split("::").last,
+                schema: model.to_json_schema
+              }
+            }
+          )
+        in {text: {format: OpenAI::StructuredOutput::JsonSchemaConverter => model}}
+          parsed.fetch(:text).update(
+            format: {
+              type: :json_schema,
+              strict: true,
+              name: model.name.split("::").last,
+              schema: model.to_json_schema
+            }
+          )
+        in {text: {format: {type: :json_schema,
+                            schema: OpenAI::StructuredOutput::JsonSchemaConverter => model}}}
+          parsed.dig(:text, :format).store(:schema, model.to_json_schema)
+        in {tools: Array => tools}
+          # rubocop:disable Metrics/BlockLength
+          mapped = tools.map do |tool|
+            case tool
+            in OpenAI::StructuredOutput::JsonSchemaConverter
+              name = tool.name.split("::").last
+              tool_models.store(name, tool)
+              {
+                type: :function,
+                strict: true,
+                name: name,
+                parameters: tool.to_json_schema
+              }
+            in {type: :function, parameters: OpenAI::StructuredOutput::JsonSchemaConverter => params}
+              func = tool.fetch(:function)
+              name = func[:name] ||= params.name.split("::").last
+              tool_models.store(name, params)
+              func.update(parameters: params.to_json_schema)
+              tool
+            in {type: _, function: {parameters: OpenAI::StructuredOutput::JsonSchemaConverter => params, **}}
+              name = tool[:function][:name] || params.name.split("::").last
+              tool_models.store(name, params)
+              tool[:function][:parameters] = params.to_json_schema
+              tool
+            in {type: _, function: Hash => func} if func[:parameters].is_a?(Class) && func[:parameters] < OpenAI::Internal::Type::BaseModel
+              params = func[:parameters]
+              name = func[:name] || params.name.split("::").last
+              tool_models.store(name, params)
+              func[:parameters] = params.to_json_schema
+              tool
+            else
+              tool
+            end
+          end
+          # rubocop:enable Metrics/BlockLength
+          tools.replace(mapped)
+        else
+        end
+
+        [model, tool_models]
+      end
     end
   end
 end

data/lib/openai/streaming.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenAI
+  Streaming = Helpers::Streaming
+end

data/lib/openai/version.rb

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

data/lib/openai.rb

@@ -56,6 +56,7 @@ require_relative "openai/helpers/structured_output/enum_of"
 require_relative "openai/helpers/structured_output/union_of"
 require_relative "openai/helpers/structured_output/array_of"
 require_relative "openai/helpers/structured_output/base_model"
+require_relative "openai/helpers/structured_output/parsed_json"
 require_relative "openai/helpers/structured_output"
 require_relative "openai/structured_output"
 require_relative "openai/models/reasoning_effort"
@@ -539,3 +540,6 @@ 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_stream"
+require_relative "openai/streaming"

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

@@ -0,0 +1,31 @@
+# typed: strong
+
+module OpenAI
+  module Helpers
+    module Streaming
+      class ResponseTextDeltaEvent < OpenAI::Models::Responses::ResponseTextDeltaEvent
+        sig { returns(String) }
+        def snapshot
+        end
+      end
+
+      class ResponseTextDoneEvent < OpenAI::Models::Responses::ResponseTextDoneEvent
+        sig { returns(T.untyped) }
+        def parsed
+        end
+      end
+
+      class ResponseFunctionCallArgumentsDeltaEvent < OpenAI::Models::Responses::ResponseFunctionCallArgumentsDeltaEvent
+        sig { returns(String) }
+        def snapshot
+        end
+      end
+
+      class ResponseCompletedEvent < OpenAI::Models::Responses::ResponseCompletedEvent
+        sig { returns(OpenAI::Models::Responses::Response) }
+        def response
+        end
+      end
+    end
+  end
+end

data/rbi/openai/helpers/streaming/response_stream.rbi

@@ -0,0 +1,104 @@
+# typed: strong
+
+module OpenAI
+  module Helpers
+    module Streaming
+      class ResponseStream
+        include OpenAI::Internal::Type::BaseStream
+
+        # Define the type union for streaming events that can be yielded
+        ResponseStreamEvent =
+          T.type_alias do
+            T.any(
+              OpenAI::Streaming::ResponseTextDeltaEvent,
+              OpenAI::Streaming::ResponseTextDoneEvent,
+              OpenAI::Streaming::ResponseCompletedEvent,
+              OpenAI::Streaming::ResponseFunctionCallArgumentsDeltaEvent,
+              # Pass through other raw events
+              OpenAI::Models::Responses::ResponseStreamEvent::Variants
+            )
+          end
+
+        Message = type_member { { fixed: ResponseStreamEvent } }
+        Elem = type_member { { fixed: ResponseStreamEvent } }
+
+        sig do
+          params(
+            raw_stream: T.untyped,
+            text_format: T.untyped,
+            starting_after: T.nilable(Integer)
+          ).void
+        end
+        def initialize(raw_stream:, text_format:, starting_after:)
+        end
+
+        sig { void }
+        def close
+        end
+
+        sig { returns(T.self_type) }
+        def until_done
+        end
+
+        sig { returns(OpenAI::Models::Responses::Response) }
+        def get_final_response
+        end
+
+        sig { returns(String) }
+        def get_output_text
+        end
+
+        sig { returns(T::Enumerator::Lazy[String]) }
+        def text
+        end
+
+        # Override the each method to properly type the yielded events
+        sig do
+          params(
+            block: T.nilable(T.proc.params(event: ResponseStreamEvent).void)
+          ).returns(T.any(T.self_type, T::Enumerator[ResponseStreamEvent]))
+        end
+        def each(&block)
+        end
+
+        private
+
+        sig { returns(T.untyped) }
+        def iterator
+        end
+      end
+
+      class ResponseStreamState
+        sig { returns(T.nilable(OpenAI::Models::Responses::Response)) }
+        attr_reader :completed_response
+
+        sig { params(text_format: T.untyped).void }
+        def initialize(text_format:)
+        end
+
+        sig { params(event: T.untyped).returns(T::Array[T.untyped]) }
+        def handle_event(event)
+        end
+
+        sig do
+          params(
+            event: T.untyped,
+            current_snapshot: T.nilable(OpenAI::Models::Responses::Response)
+          ).returns(OpenAI::Models::Responses::Response)
+        end
+        def accumulate_event(event:, current_snapshot:)
+        end
+
+        private
+
+        sig { params(text: T.nilable(String)).returns(T.untyped) }
+        def parse_structured_text(text)
+        end
+
+        sig { params(object: T.untyped, expected_type: Symbol).void }
+        def assert_type(object, expected_type)
+        end
+      end
+    end
+  end
+end

data/rbi/openai/internal/type/base_stream.rbi

@@ -52,10 +52,17 @@ module OpenAI
             url: URI::Generic,
             status: Integer,
             response: Net::HTTPResponse,
+            unwrap:
+              T.any(
+                Symbol,
+                Integer,
+                T::Array[T.any(Symbol, Integer)],
+                T.proc.params(arg0: T.anything).returns(T.anything)
+              ),
             stream: T::Enumerable[Message]
           ).void
         end
-        def initialize(model:, url:, status:, response:, stream:)
+        def initialize(model:, url:, status:, response:, unwrap:, stream:)
         end
 
         # @api private

data/rbi/openai/resources/responses.rbi

@@ -275,7 +275,13 @@ module OpenAI
             ),
           store: T.nilable(T::Boolean),
           temperature: T.nilable(Float),
-          text: OpenAI::Responses::ResponseTextConfig::OrHash,
+          text:
+            T.nilable(
+              T.any(
+                OpenAI::Responses::ResponseTextConfig::OrHash,
+                OpenAI::StructuredOutput::JsonSchemaConverter
+              )
+            ),
           tool_choice:
             T.any(
               OpenAI::Responses::ToolChoiceOptions::OrSymbol,
@@ -462,6 +468,125 @@ module OpenAI
       )
       end
 
+      # See {OpenAI::Resources::Responses#create} for non-streaming counterpart.
+      #
+      # Creates a model response with a higher-level streaming interface that provides
+      # helper methods for processing events and aggregating stream outputs.
+      sig do
+        params(
+          input:
+            T.nilable(OpenAI::Responses::ResponseCreateParams::Input::Variants),
+          model:
+            T.nilable(
+              T.any(
+                String,
+                OpenAI::ChatModel::OrSymbol,
+                OpenAI::ResponsesModel::ResponsesOnlyModel::OrSymbol
+              )
+            ),
+          background: T.nilable(T::Boolean),
+          include:
+            T.nilable(
+              T::Array[OpenAI::Responses::ResponseIncludable::OrSymbol]
+            ),
+          instructions: T.nilable(String),
+          max_output_tokens: T.nilable(Integer),
+          metadata: T.nilable(T::Hash[Symbol, String]),
+          parallel_tool_calls: T.nilable(T::Boolean),
+          previous_response_id: T.nilable(String),
+          prompt: T.nilable(OpenAI::Responses::ResponsePrompt::OrHash),
+          reasoning: T.nilable(OpenAI::Reasoning::OrHash),
+          service_tier:
+            T.nilable(
+              OpenAI::Responses::ResponseCreateParams::ServiceTier::OrSymbol
+            ),
+          store: T.nilable(T::Boolean),
+          temperature: T.nilable(Float),
+          text:
+            T.any(
+              OpenAI::Responses::ResponseTextConfig::OrHash,
+              OpenAI::StructuredOutput::JsonSchemaConverter
+            ),
+          tool_choice:
+            T.any(
+              OpenAI::Responses::ToolChoiceOptions::OrSymbol,
+              OpenAI::Responses::ToolChoiceTypes::OrHash,
+              OpenAI::Responses::ToolChoiceFunction::OrHash
+            ),
+          tools:
+            T.nilable(
+              T::Array[
+                T.any(
+                  OpenAI::Responses::FunctionTool::OrHash,
+                  OpenAI::Responses::FileSearchTool::OrHash,
+                  OpenAI::Responses::ComputerTool::OrHash,
+                  OpenAI::Responses::Tool::Mcp::OrHash,
+                  OpenAI::Responses::Tool::CodeInterpreter::OrHash,
+                  OpenAI::Responses::Tool::ImageGeneration::OrHash,
+                  OpenAI::Responses::Tool::LocalShell::OrHash,
+                  OpenAI::Responses::WebSearchTool::OrHash,
+                  OpenAI::StructuredOutput::JsonSchemaConverter
+                )
+              ]
+            ),
+          top_p: T.nilable(Float),
+          truncation:
+            T.nilable(
+              OpenAI::Responses::ResponseCreateParams::Truncation::OrSymbol
+            ),
+          user: T.nilable(String),
+          starting_after: T.nilable(Integer),
+          request_options: T.nilable(OpenAI::RequestOptions::OrHash)
+        ).returns(OpenAI::Streaming::ResponseStream)
+      end
+      def stream(
+        # Text, image, or file inputs to the model, used to generate a response.
+        input: nil,
+        # Model ID used to generate the response, like `gpt-4o` or `o3`.
+        model: nil,
+        # Whether to run the model response in the background.
+        background: nil,
+        # Specify additional output data to include in the model response.
+        include: nil,
+        # A system (or developer) message inserted into the model's context.
+        instructions: nil,
+        # An upper bound for the number of tokens that can be generated for a response.
+        max_output_tokens: nil,
+        # Set of 16 key-value pairs that can be attached to an object.
+        metadata: nil,
+        # Whether to allow the model to run tool calls in parallel.
+        parallel_tool_calls: nil,
+        # The unique ID of the previous response to the model. Use this to create
+        # multi-turn conversations.
+        previous_response_id: nil,
+        # Reference to a prompt template and its variables.
+        prompt: nil,
+        # Configuration options for reasoning models.
+        reasoning: nil,
+        # Specifies the latency tier to use for processing the request.
+        service_tier: nil,
+        # Whether to store the generated model response for later retrieval via API.
+        store: nil,
+        # What sampling temperature to use, between 0 and 2.
+        temperature: nil,
+        # Configuration options for a text response from the model.
+        text: nil,
+        # How the model should select which tool (or tools) to use when generating a response.
+        tool_choice: nil,
+        # An array of tools the model may call while generating a response.
+        tools: nil,
+        # An alternative to sampling with temperature, called nucleus sampling.
+        top_p: nil,
+        # The truncation strategy to use for the model response.
+        truncation: nil,
+        # A stable identifier for your end-users.
+        user: nil,
+        # The sequence number of the event after which to start streaming (for resuming streams).
+        starting_after: nil,
+        request_options: {}
+      )
+      end
+
       # See {OpenAI::Resources::Responses#retrieve_streaming} for streaming counterpart.
       #
       # Retrieves a model response with the given ID.

data/rbi/openai/streaming.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module OpenAI
+  Streaming = OpenAI::Helpers::Streaming
+end

data/sig/openai/internal/type/base_stream.rbs

@@ -23,6 +23,10 @@ module OpenAI
           url: URI::Generic,
           status: Integer,
           response: top,
+          unwrap: Symbol
+          | Integer
+          | ::Array[Symbol | Integer]
+          | ^(top arg0) -> top,
           stream: Enumerable[Message]
         ) -> void
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openai
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - OpenAI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-26 00:00:00.000000000 Z
+date: 2025-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -39,12 +39,15 @@ files:
 - lib/openai/client.rb
 - lib/openai/errors.rb
 - lib/openai/file_part.rb
+- lib/openai/helpers/streaming/events.rb
+- lib/openai/helpers/streaming/response_stream.rb
 - lib/openai/helpers/structured_output.rb
 - lib/openai/helpers/structured_output/array_of.rb
 - lib/openai/helpers/structured_output/base_model.rb
 - lib/openai/helpers/structured_output/boolean.rb
 - lib/openai/helpers/structured_output/enum_of.rb
 - lib/openai/helpers/structured_output/json_schema_converter.rb
+- lib/openai/helpers/structured_output/parsed_json.rb
 - lib/openai/helpers/structured_output/union_of.rb
 - lib/openai/internal.rb
 - lib/openai/internal/cursor_page.rb
@@ -547,12 +550,15 @@ files:
 - lib/openai/resources/vector_stores/file_batches.rb
 - lib/openai/resources/vector_stores/files.rb
 - lib/openai/resources/webhooks.rb
+- lib/openai/streaming.rb
 - lib/openai/structured_output.rb
 - lib/openai/version.rb
 - manifest.yaml
 - rbi/openai/client.rbi
 - rbi/openai/errors.rbi
 - rbi/openai/file_part.rbi
+- rbi/openai/helpers/streaming/events.rbi
+- rbi/openai/helpers/streaming/response_stream.rbi
 - rbi/openai/helpers/structured_output.rbi
 - rbi/openai/helpers/structured_output/array_of.rbi
 - rbi/openai/helpers/structured_output/base_model.rbi
@@ -1061,6 +1067,7 @@ files:
 - rbi/openai/resources/vector_stores/file_batches.rbi
 - rbi/openai/resources/vector_stores/files.rbi
 - rbi/openai/resources/webhooks.rbi
+- rbi/openai/streaming.rbi
 - rbi/openai/structured_output.rbi
 - rbi/openai/version.rbi
 - sig/openai/client.rbs