openai 0.10.0 → 0.12.0

data/lib/openai/resources/responses.rb

@@ -23,7 +23,7 @@ module OpenAI
       # [file search](https://platform.openai.com/docs/guides/tools-file-search) to use
       # your own data as input for the model's response.
       #
-      # @overload create(background: nil, include: nil, input: nil, instructions: nil, max_output_tokens: nil, metadata: nil, model: 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: {})
+      # @overload create(background: nil, include: nil, input: nil, instructions: nil, max_output_tokens: nil, max_tool_calls: nil, metadata: nil, model: 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_logprobs: nil, top_p: nil, truncation: nil, user: nil, request_options: {})
       #
       # @param background [Boolean, nil] Whether to run the model response in the background.
       #
@@ -35,6 +35,8 @@ module OpenAI
       #
       # @param max_output_tokens [Integer, nil] An upper bound for the number of tokens that can be generated for a response, in
       #
+      # @param max_tool_calls [Integer, nil] The maximum number of total calls to built-in tools that can be processed in a r
+      #
       # @param metadata [Hash{Symbol=>String}, nil] Set of 16 key-value pairs that can be attached to an object. This can be
       #
       # @param model [String, Symbol, OpenAI::Models::ChatModel, OpenAI::Models::ResponsesModel::ResponsesOnlyModel] Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI
@@ -47,7 +49,7 @@ module OpenAI
       #
       # @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 service_tier [Symbol, OpenAI::Models::Responses::ResponseCreateParams::ServiceTier, nil] Specifies the processing type used for serving the request.
       #
       # @param store [Boolean, nil] Whether to store the generated model response for later retrieval via
       #
@@ -55,10 +57,12 @@ module OpenAI
       #
       # @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 tool_choice [Symbol, OpenAI::Models::Responses::ToolChoiceOptions, OpenAI::Models::Responses::ToolChoiceTypes, OpenAI::Models::Responses::ToolChoiceFunction, OpenAI::Models::Responses::ToolChoiceMcp] 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_logprobs [Integer, nil] An integer between 0 and 20 specifying the number of most likely tokens to
+      #
       # @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.
@@ -77,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",
@@ -162,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.
@@ -183,7 +222,7 @@ module OpenAI
       # [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(background: nil, include: nil, input: nil, instructions: nil, max_output_tokens: nil, metadata: nil, model: 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: {})
+      # @overload stream_raw(background: nil, include: nil, input: nil, instructions: nil, max_output_tokens: nil, max_tool_calls: nil, metadata: nil, model: 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_logprobs: nil, top_p: nil, truncation: nil, user: nil, request_options: {})
       #
       # @param background [Boolean, nil] Whether to run the model response in the background.
       #
@@ -195,19 +234,21 @@ module OpenAI
       #
       # @param max_output_tokens [Integer, nil] An upper bound for the number of tokens that can be generated for a response, in
       #
+      # @param max_tool_calls [Integer, nil] The maximum number of total calls to built-in tools that can be processed in a r
+      #
       # @param metadata [Hash{Symbol=>String}, nil] Set of 16 key-value pairs that can be attached to an object. This can be
       #
       # @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 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.
       #
       # @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 service_tier [Symbol, OpenAI::Models::Responses::ResponseCreateParams::ServiceTier, nil] Specifies the processing type used for serving the request.
       #
       # @param store [Boolean, nil] Whether to store the generated model response for later retrieval via
       #
@@ -215,10 +256,12 @@ module OpenAI
       #
       # @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 tool_choice [Symbol, OpenAI::Models::Responses::ToolChoiceOptions, OpenAI::Models::Responses::ToolChoiceTypes, OpenAI::Models::Responses::ToolChoiceFunction, OpenAI::Models::Responses::ToolChoiceMcp] 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_logprobs [Integer, nil] An integer between 0 and 20 specifying the number of most likely tokens to
+      #
       # @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.
@@ -237,6 +280,7 @@ module OpenAI
           raise ArgumentError.new(message)
         end
         parsed.store(:stream, true)
+
         @client.request(
           method: :post,
           path: "responses",
@@ -370,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/resources/webhooks.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module OpenAI
+  module Resources
+    class Webhooks
+      # Validates that the given payload was sent by OpenAI and parses the payload.
+      #
+      # @param payload [String] The raw webhook payload as a string
+      # @param headers [Hash] The webhook headers
+      # @param webhook_secret [String, nil] The webhook secret (optional, will use client webhook secret or ENV["OPENAI_WEBHOOK_SECRET"] if not provided)
+      #
+      # @return [OpenAI::Models::Webhooks::BatchCancelledWebhookEvent, OpenAI::Models::Webhooks::BatchCompletedWebhookEvent, OpenAI::Models::Webhooks::BatchExpiredWebhookEvent, OpenAI::Models::Webhooks::BatchFailedWebhookEvent, OpenAI::Models::Webhooks::EvalRunCanceledWebhookEvent, OpenAI::Models::Webhooks::EvalRunFailedWebhookEvent, OpenAI::Models::Webhooks::EvalRunSucceededWebhookEvent, OpenAI::Models::Webhooks::FineTuningJobCancelledWebhookEvent, OpenAI::Models::Webhooks::FineTuningJobFailedWebhookEvent, OpenAI::Models::Webhooks::FineTuningJobSucceededWebhookEvent, OpenAI::Models::Webhooks::ResponseCancelledWebhookEvent, OpenAI::Models::Webhooks::ResponseCompletedWebhookEvent, OpenAI::Models::Webhooks::ResponseCreatedWebhookEvent, OpenAI::Models::Webhooks::ResponseFailedWebhookEvent, OpenAI::Models::Webhooks::ResponseIncompleteWebhookEvent]
+      #
+      # @raise [ArgumentError] if signature verification fails
+      def unwrap(
+        payload,
+        headers = {},
+        webhook_secret = @client.webhook_secret || ENV["OPENAI_WEBHOOK_SECRET"]
+      )
+        verify_signature(payload, headers, webhook_secret)
+
+        parsed = JSON.parse(payload, symbolize_names: true)
+        OpenAI::Internal::Type::Converter.coerce(OpenAI::Models::Webhooks::UnwrapWebhookEvent, parsed)
+      end
+
+      # Validates whether or not the webhook payload was sent by OpenAI.
+      #
+      # @param payload [String] The webhook payload as a string
+      # @param headers [Hash] The webhook headers
+      # @param webhook_secret [String, nil] The webhook secret (optional, will use client webhook secret or ENV["OPENAI_WEBHOOK_SECRET"] if not provided)
+      # @param tolerance [Integer] Maximum age of the webhook in seconds (default: 300 = 5 minutes)
+      #
+      # @raise [ArgumentError] if the signature is invalid
+      def verify_signature(
+        payload,
+        headers,
+        webhook_secret = @client.webhook_secret || ENV["OPENAI_WEBHOOK_SECRET"],
+        tolerance = 300
+      )
+        if webhook_secret.nil?
+          raise ArgumentError,
+                "The webhook secret must either be set using the env var, OPENAI_WEBHOOK_SECRET, " \
+                "or passed to this function"
+        end
+
+        # Extract required headers
+        signature_header = headers["webhook-signature"] || headers[:webhook_signature]
+        timestamp_header = headers["webhook-timestamp"] || headers[:webhook_timestamp]
+        webhook_id = headers["webhook-id"] || headers[:webhook_id]
+
+        if signature_header.nil?
+          raise ArgumentError, "Missing required webhook-signature header"
+        end
+
+        if timestamp_header.nil?
+          raise ArgumentError, "Missing required webhook-timestamp header"
+        end
+
+        if webhook_id.nil?
+          raise ArgumentError, "Missing required webhook-id header"
+        end
+
+        # Validate timestamp to prevent replay attacks
+        begin
+          timestamp_seconds = timestamp_header.to_i
+        rescue ArgumentError
+          raise ArgumentError, "Invalid webhook timestamp format"
+        end
+
+        now = Time.now.to_i
+
+        if now - timestamp_seconds > tolerance
+          raise OpenAI::Errors::InvalidWebhookSignatureError, "Webhook timestamp is too old"
+        end
+
+        if timestamp_seconds > now + tolerance
+          raise OpenAI::Errors::InvalidWebhookSignatureError, "Webhook timestamp is too new"
+        end
+
+        # Extract signatures from v1,<base64> format
+        # The signature header can have multiple values, separated by spaces.
+        # Each value is in the format v1,<base64>. We should accept if any match.
+        signatures = signature_header.split.map do |part|
+          if part.start_with?("v1,")
+            part[3..]
+          else
+            part
+          end
+        end
+
+        # Decode the secret if it starts with whsec_
+        decoded_secret = if webhook_secret.start_with?("whsec_")
+          Base64.decode64(webhook_secret[6..])
+        else
+          webhook_secret
+        end
+
+        # Create the signed payload: {webhook_id}.{timestamp}.{payload}
+        signed_payload = "#{webhook_id}.#{timestamp_header}.#{payload}"
+
+        # Compute HMAC-SHA256 signature
+        expected_signature = Base64.encode64(
+          OpenSSL::HMAC.digest("sha256", decoded_secret, signed_payload)
+        ).strip
+
+        # Accept if any signature matches using timing-safe comparison
+        return if signatures.any? { |signature| OpenSSL.secure_compare(expected_signature, signature) }
+
+        raise OpenAI::Errors::InvalidWebhookSignatureError,
+              "The given webhook signature does not match the expected signature"
+      end
+
+      # @api private
+      #
+      # @param client [OpenAI::Client]
+      def initialize(client:)
+        @client = client
+      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.10.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"
@@ -441,6 +442,7 @@ require_relative "openai/models/responses/response_web_search_call_in_progress_e
 require_relative "openai/models/responses/response_web_search_call_searching_event"
 require_relative "openai/models/responses/tool"
 require_relative "openai/models/responses/tool_choice_function"
+require_relative "openai/models/responses/tool_choice_mcp"
 require_relative "openai/models/responses/tool_choice_options"
 require_relative "openai/models/responses/tool_choice_types"
 require_relative "openai/models/responses/web_search_tool"
@@ -477,6 +479,22 @@ require_relative "openai/models/vector_stores/vector_store_file_deleted"
 require_relative "openai/models/vector_store_search_params"
 require_relative "openai/models/vector_store_search_response"
 require_relative "openai/models/vector_store_update_params"
+require_relative "openai/models/webhooks/batch_cancelled_webhook_event"
+require_relative "openai/models/webhooks/batch_completed_webhook_event"
+require_relative "openai/models/webhooks/batch_expired_webhook_event"
+require_relative "openai/models/webhooks/batch_failed_webhook_event"
+require_relative "openai/models/webhooks/eval_run_canceled_webhook_event"
+require_relative "openai/models/webhooks/eval_run_failed_webhook_event"
+require_relative "openai/models/webhooks/eval_run_succeeded_webhook_event"
+require_relative "openai/models/webhooks/fine_tuning_job_cancelled_webhook_event"
+require_relative "openai/models/webhooks/fine_tuning_job_failed_webhook_event"
+require_relative "openai/models/webhooks/fine_tuning_job_succeeded_webhook_event"
+require_relative "openai/models/webhooks/response_cancelled_webhook_event"
+require_relative "openai/models/webhooks/response_completed_webhook_event"
+require_relative "openai/models/webhooks/response_failed_webhook_event"
+require_relative "openai/models/webhooks/response_incomplete_webhook_event"
+require_relative "openai/models/webhooks/unwrap_webhook_event"
+require_relative "openai/models/webhooks/webhook_unwrap_params"
 require_relative "openai/models"
 require_relative "openai/resources/audio"
 require_relative "openai/resources/audio/speech"
@@ -521,3 +539,7 @@ require_relative "openai/resources/uploads/parts"
 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/client.rbi

@@ -52,6 +52,9 @@ module OpenAI
     sig { returns(OpenAI::Resources::VectorStores) }
     attr_reader :vector_stores
 
+    sig { returns(OpenAI::Resources::Webhooks) }
+    attr_reader :webhooks
+
     sig { returns(OpenAI::Resources::Beta) }
     attr_reader :beta
 

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