openai 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8ca71d5671f3a20cde2fda0eec819c5305ebd9e60aabcc55abf471f1de63b53
-  data.tar.gz: 1de944c9a0ee804f9d15567fec8038368458132183468c81ae42609c036e05ac
+  metadata.gz: 38a07c18c8f0197c2edc1400139623aefc1c85e8a0fbf167a86afc53f1399a75
+  data.tar.gz: 13b400c12a9d2bef1ebcf2722413e3e6b1915992df539542f4a73f084b839cfa
 SHA512:
-  metadata.gz: 822226e8ebc9b077c242ae0366ec3f5e4b0b413054cbc3e4d9e971347c79ccb9b64006a6af5cc5a88b25472103be1a5c9a2b3c9a5e25396951f454f9f15f2dc4
-  data.tar.gz: 6ed344972114e5c0f098d3e5619dc1548ac61557e7b3b23384d558e2f9ccbe1ee1dd00ee0ffa0f77b17027554c1c46d33bc6eb552695615bf0fd289cf0fb4dc1
+  metadata.gz: d5a62aacb54b1e50526da647c3ea91adbe8dbf69bd8c4f0df08a0a6c9fa4b49ebb79bd4b51bf5efc55d06d514af286b7658c153a6498298761dedc2f73c42c20
+  data.tar.gz: 9c7a2bbe1053d11780882a11a9617ea4cd2ee4a6648f278003be7da107c0e5dc281beeb6dbce3db168f4c9338d161742ab48bc03711a8c4f05e540f11e6f40d0

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # 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)
+
+### Features
+
+* **api:** webhook and deep research support ([6228400](https://github.com/openai/openai-ruby/commit/6228400e19aadefc5f87e24b3c104fc0b44d3cee))
+
+
+### Bug Fixes
+
+* **ci:** release-doctor — report correct token name ([c12c991](https://github.com/openai/openai-ruby/commit/c12c9911beaeb8b1c72d7c5cc5f14dcb9cd5452e))
+
+
+### Chores
+
+* **api:** remove unsupported property ([1073c3a](https://github.com/openai/openai-ruby/commit/1073c3a6059f2d1e1ef92937326699e0240503e5))
+* **client:** throw specific errors ([0cf937e](https://github.com/openai/openai-ruby/commit/0cf937ea8abebc05e52a419e19e275a45b5da646))
+* **docs:** update README to include links to docs on Webhooks ([2d8f23e](https://github.com/openai/openai-ruby/commit/2d8f23ecb245c88f3f082f93eb906af857d64c7d))
+
 ## 0.10.0 (2025-06-23)
 
 Full Changelog: [v0.9.0...v0.10.0](https://github.com/openai/openai-ruby/compare/v0.9.0...v0.10.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.10.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
 ```
 
@@ -112,6 +110,84 @@ puts(edited.data.first)
 
 Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).
 
+## Webhook Verification
+
+Verifying webhook signatures is _optional but encouraged_.
+
+For more information about webhooks, see [the API docs](https://platform.openai.com/docs/guides/webhooks).
+
+### Parsing webhook payloads
+
+For most use cases, you will likely want to verify the webhook and parse the payload at the same time. To achieve this, we provide the method `client.webhooks.unwrap`, which parses a webhook request and verifies that it was sent by OpenAI. This method will raise an error if the signature is invalid.
+
+Note that the `body` parameter must be the raw JSON string sent from the server (do not parse it first). The `unwrap` method will parse this JSON for you into an event object after verifying the webhook was sent from OpenAI.
+
+```ruby
+require 'sinatra'
+require 'openai'
+
+# Set up the client with webhook secret from environment variable
+client = OpenAI::Client.new(webhook_secret: ENV['OPENAI_WEBHOOK_SECRET'])
+
+post '/webhook' do
+  request_body = request.body.read
+  
+  begin
+    event = client.webhooks.unwrap(request_body, request.env)
+    
+    case event.type
+    when 'response.completed'
+      puts "Response completed: #{event.data}"
+    when 'response.failed'
+      puts "Response failed: #{event.data}"
+    else
+      puts "Unhandled event type: #{event.type}"
+    end
+    
+    status 200
+    'ok'
+  rescue StandardError => e
+    puts "Invalid signature: #{e}"
+    status 400
+    'Invalid signature'
+  end
+end
+```
+
+### Verifying webhook payloads directly
+
+In some cases, you may want to verify the webhook separately from parsing the payload. If you prefer to handle these steps separately, we provide the method `client.webhooks.verify_signature` to _only verify_ the signature of a webhook request. Like `unwrap`, this method will raise an error if the signature is invalid.
+
+Note that the `body` parameter must be the raw JSON string sent from the server (do not parse it first). You will then need to parse the body after verifying the signature.
+
+```ruby
+require 'sinatra'
+require 'json'
+require 'openai'
+
+# Set up the client with webhook secret from environment variable
+client = OpenAI::Client.new(webhook_secret: ENV['OPENAI_WEBHOOK_SECRET'])
+
+post '/webhook' do
+  request_body = request.body.read
+  
+  begin
+    client.webhooks.verify_signature(request_body, request.env)
+    
+    # Parse the body after verification
+    event = JSON.parse(request_body)
+    puts "Verified event: #{event}"
+    
+    status 200
+    'ok'
+  rescue StandardError => e
+    puts "Invalid signature: #{e}"
+    status 400
+    'Invalid signature'
+  end
+end
+```
+
 ### [Structured outputs](https://platform.openai.com/docs/guides/structured-outputs) and function calling
 
 This SDK ships with helpers in `OpenAI::BaseModel`, `OpenAI::ArrayOf`, `OpenAI::EnumOf`, and `OpenAI::UnionOf` to help you define the supported JSON schemas used in making structured outputs and function calling requests.

data/lib/openai/client.rb

@@ -24,6 +24,9 @@ module OpenAI
     # @return [String, nil]
     attr_reader :project
 
+    # @return [String, nil]
+    attr_reader :webhook_secret
+
     # @return [OpenAI::Resources::Completions]
     attr_reader :completions
 
@@ -57,6 +60,9 @@ module OpenAI
     # @return [OpenAI::Resources::VectorStores]
     attr_reader :vector_stores
 
+    # @return [OpenAI::Resources::Webhooks]
+    attr_reader :webhooks
+
     # @return [OpenAI::Resources::Beta]
     attr_reader :beta
 
@@ -92,6 +98,8 @@ module OpenAI
     #
     # @param project [String, nil] Defaults to `ENV["OPENAI_PROJECT_ID"]`
     #
+    # @param webhook_secret [String, nil] Defaults to `ENV["OPENAI_WEBHOOK_SECRET"]`
+    #
     # @param base_url [String, nil] Override the default base URL for the API, e.g.,
     # `"https://api.example.com/v2/"`. Defaults to `ENV["OPENAI_BASE_URL"]`
     #
@@ -106,6 +114,7 @@ module OpenAI
       api_key: ENV["OPENAI_API_KEY"],
       organization: ENV["OPENAI_ORG_ID"],
       project: ENV["OPENAI_PROJECT_ID"],
+      webhook_secret: ENV["OPENAI_WEBHOOK_SECRET"],
       base_url: ENV["OPENAI_BASE_URL"],
       max_retries: self.class::DEFAULT_MAX_RETRIES,
       timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
@@ -124,6 +133,7 @@ module OpenAI
       }
 
       @api_key = api_key.to_s
+      @webhook_secret = webhook_secret&.to_s
 
       super(
         base_url: base_url,
@@ -145,6 +155,7 @@ module OpenAI
       @fine_tuning = OpenAI::Resources::FineTuning.new(client: self)
       @graders = OpenAI::Resources::Graders.new(client: self)
       @vector_stores = OpenAI::Resources::VectorStores.new(client: self)
+      @webhooks = OpenAI::Resources::Webhooks.new(client: self)
       @beta = OpenAI::Resources::Beta.new(client: self)
       @batches = OpenAI::Resources::Batches.new(client: self)
       @uploads = OpenAI::Resources::Uploads.new(client: self)

data/lib/openai/errors.rb

@@ -8,6 +8,9 @@ module OpenAI
       #   @return [StandardError, nil]
     end
 
+    class InvalidWebhookSignatureError < OpenAI::Errors::Error
+    end
+
     class ConversionError < OpenAI::Errors::Error
       # @return [StandardError, nil]
       def cause = @cause.nil? ? super : @cause

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/all_models.rb

@@ -18,6 +18,10 @@ module OpenAI
         O1_PRO_2025_03_19 = :"o1-pro-2025-03-19"
         O3_PRO = :"o3-pro"
         O3_PRO_2025_06_10 = :"o3-pro-2025-06-10"
+        O3_DEEP_RESEARCH = :"o3-deep-research"
+        O3_DEEP_RESEARCH_2025_06_26 = :"o3-deep-research-2025-06-26"
+        O4_MINI_DEEP_RESEARCH = :"o4-mini-deep-research"
+        O4_MINI_DEEP_RESEARCH_2025_06_26 = :"o4-mini-deep-research-2025-06-26"
         COMPUTER_USE_PREVIEW = :"computer-use-preview"
         COMPUTER_USE_PREVIEW_2025_03_11 = :"computer-use-preview-2025-03-11"