openai 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0a273910412c6b05028da1b9e7fceab0b048d4d34df4b1bee6a781dcbad33dd
-  data.tar.gz: 51a3719def2827a793c2b9974cc4104e00000cea78893ff36d327254bb8e586e
+  metadata.gz: 252a9ce9833b0a9f66be94b76081f34716e348ebca732e63c3e16c105ed42ea1
+  data.tar.gz: d4d8b36822ee74af77508ec8e48b472d72d619333e468055695158e242c49760
 SHA512:
-  metadata.gz: d65777601ceac3d125750949f80a0ca4d50f62593e971d067f7c164ab1dbbddf51266cee8ab752ef058f2313f09b7ad48a6312c8df7a465e0807e956ed55cedf
-  data.tar.gz: 9156aee0d88ad6be1e794acede9961d774c40ade621282aff54899879e718f6f514f61007d25f614e507796eefefbf694508042e1e126fc0412aac76b003ff44
+  metadata.gz: f27c40e40df727c8da570a4f6b1e20f72a87baa710efd3957bb0fbbcc23eb1dd78d03b1bcc3c3cf5684d4db4b062c392c1c3d970093c8e0fac89ef85db053db3
+  data.tar.gz: 21fe44d1605c6196d7321dcb7efa7d951a2523ba71859eab1bf242ff3314afe0cce25201c21b141f9f3902b684cb577ba51c520d12602d1279eccb770769e3a4

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 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)
+
+### Features
+
+* **api:** make model and inputs not required to create response ([2087fb5](https://github.com/openai/openai-ruby/commit/2087fb53d775f6481dd34737f6d554c5c35f65e7))
+* **api:** update api shapes for usage and code interpreter ([733ebfb](https://github.com/openai/openai-ruby/commit/733ebfbafe14d9733149b174c99d41d471a42865))
+
+
+### Bug Fixes
+
+* **internal:** fix: should publish to ruby gems when a release is created ([aebd8eb](https://github.com/openai/openai-ruby/commit/aebd8eb2855d6a8f4fe685bdb5a458346d509e50))
+* issue where we cannot mutate arrays on base model derivatives ([266d072](https://github.com/openai/openai-ruby/commit/266d072946c75f93abeff45eec9787ce4e7fea56))
+
+
+### Chores
+
+* allow more free formatted json response input ([#726](https://github.com/openai/openai-ruby/issues/726)) ([69fb0af](https://github.com/openai/openai-ruby/commit/69fb0afabf86ecc3d1ca469d9700c42447569f3b))
+
 ## 0.9.0 (2025-06-17)
 
 Full Changelog: [v0.8.0...v0.9.0](https://github.com/openai/openai-ruby/compare/v0.8.0...v0.9.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.9.0"
+gem "openai", "~> 0.11.0"
 ```
 
 <!-- x-release-please-end -->
@@ -112,6 +112,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,7 +8,32 @@ 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
+
+      # @api private
+      #
+      # @param on [Class<StandardError>]
+      # @param method [Symbol]
+      # @param target [Object]
+      # @param value [Object]
+      # @param cause [StandardError, nil]
+      def initialize(on:, method:, target:, value:, cause: nil)
+        cls = on.name.split("::").last
+
+        message = [
+          "Failed to parse #{cls}.#{method} from #{value.class} to #{target.inspect}.",
+          "To get the unparsed API response, use #{cls}[#{method.inspect}].",
+          cause && "Cause: #{cause.message}"
+        ].filter(&:itself).join(" ")
+
+        @cause = cause
+        super(message)
+      end
     end
 
     class APIError < OpenAI::Errors::Error

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

@@ -62,10 +62,14 @@ module OpenAI
         #
         # @param state [Hash{Symbol=>Object}] .
         #
-        #   @option state [Boolean, :strong] :strictness
+        #   @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 [Array<Object>, Object]
@@ -74,6 +78,7 @@ module OpenAI
 
           unless value.is_a?(Array)
             exactness[:no] += 1
+            state[:error] = TypeError.new("#{value.class} can't be coerced into #{Array}")
             return value
           end
 

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

@@ -60,7 +60,7 @@ module OpenAI
                 [OpenAI::Internal::Type::Converter.type_info(type_info), type_info]
               end
 
-            setter = "#{name_sym}="
+            setter = :"#{name_sym}="
             api_name = info.fetch(:api_name, name_sym)
             nilable = info.fetch(:nil?, false)
             const = required && !nilable ? info.fetch(:const, OpenAI::Internal::OMIT) : OpenAI::Internal::OMIT
@@ -77,30 +77,61 @@ module OpenAI
                 type_fn: type_fn
               }
 
-            define_method(setter) { @data.store(name_sym, _1) }
+            define_method(setter) do |value|
+              target = type_fn.call
+              state = OpenAI::Internal::Type::Converter.new_coerce_state(translate_names: false)
+              coerced = OpenAI::Internal::Type::Converter.coerce(target, value, state: state)
+              error = @coerced.store(name_sym, state.fetch(:error) || true)
+              stored =
+                case [target, error]
+                in [OpenAI::Internal::Type::Converter | Symbol, nil]
+                  coerced
+                else
+                  value
+                end
+              @data.store(name_sym, stored)
+            end
 
+            # rubocop:disable Style/CaseEquality
+            # rubocop:disable Metrics/BlockLength
             define_method(name_sym) do
               target = type_fn.call
-              value = @data.fetch(name_sym) { const == OpenAI::Internal::OMIT ? nil : const }
-              state = {strictness: :strong, exactness: {yes: 0, no: 0, maybe: 0}, branched: 0}
-              if (nilable || !required) && value.nil?
-                nil
-              else
-                OpenAI::Internal::Type::Converter.coerce(
-                  target,
-                  value,
-                  state: state
+
+              case @coerced[name_sym]
+              in true | false if OpenAI::Internal::Type::Converter === target
+                @data.fetch(name_sym)
+              in ::StandardError => e
+                raise OpenAI::Errors::ConversionError.new(
+                  on: self.class,
+                  method: __method__,
+                  target: target,
+                  value: @data.fetch(name_sym),
+                  cause: e
                 )
+              else
+                Kernel.then do
+                  value = @data.fetch(name_sym) { const == OpenAI::Internal::OMIT ? nil : const }
+                  state = OpenAI::Internal::Type::Converter.new_coerce_state(translate_names: false)
+                  if (nilable || !required) && value.nil?
+                    nil
+                  else
+                    OpenAI::Internal::Type::Converter.coerce(
+                      target, value, state: state
+                    )
+                  end
+                rescue StandardError => e
+                  raise OpenAI::Errors::ConversionError.new(
+                    on: self.class,
+                    method: __method__,
+                    target: target,
+                    value: value,
+                    cause: e
+                  )
+                end
               end
-            rescue StandardError => e
-              cls = self.class.name.split("::").last
-              message = [
-                "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}.",
-                "To get the unparsed API response, use #{cls}[#{__method__.inspect}].",
-                "Cause: #{e.message}"
-              ].join(" ")
-              raise OpenAI::Errors::ConversionError.new(message)
             end
+            # rubocop:enable Metrics/BlockLength
+            # rubocop:enable Style/CaseEquality
           end
 
           # @api private
@@ -200,10 +231,14 @@ module OpenAI
           #
           # @param state [Hash{Symbol=>Object}] .
           #
-          #   @option state [Boolean, :strong] :strictness
+          #   @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 [self, Object]
@@ -217,6 +252,7 @@ module OpenAI
 
             unless (val = OpenAI::Internal::Util.coerce_hash(value)).is_a?(Hash)
               exactness[:no] += 1
+              state[:error] = TypeError.new("#{value.class} can't be coerced into #{Hash}")
               return value
             end
             exactness[:yes] += 1
@@ -224,13 +260,15 @@ module OpenAI
             keys = val.keys.to_set
             instance = new
             data = instance.to_h
+            viability = instance.instance_variable_get(:@coerced)
 
             # rubocop:disable Metrics/BlockLength
             fields.each do |name, field|
               mode, required, target = field.fetch_values(:mode, :required, :type)
               api_name, nilable, const = field.fetch_values(:api_name, :nilable, :const)
+              src_name = state.fetch(:translate_names) ? api_name : name
 
-              unless val.key?(api_name)
+              unless val.key?(src_name)
                 if required && mode != :dump && const == OpenAI::Internal::OMIT
                   exactness[nilable ? :maybe : :no] += 1
                 else
@@ -239,9 +277,10 @@ module OpenAI
                 next
               end
 
-              item = val.fetch(api_name)
-              keys.delete(api_name)
+              item = val.fetch(src_name)
+              keys.delete(src_name)
 
+              state[:error] = nil
               converted =
                 if item.nil? && (nilable || !required)
                   exactness[nilable ? :yes : :maybe] += 1
@@ -255,6 +294,8 @@ module OpenAI
                     item
                   end
                 end
+
+              viability.store(name, state.fetch(:error) || true)
               data.store(name, converted)
             end
             # rubocop:enable Metrics/BlockLength
@@ -430,7 +471,18 @@ module OpenAI
         # Create a new instance of a model.
         #
         # @param data [Hash{Symbol=>Object}, self]
-        def initialize(data = {}) = (@data = OpenAI::Internal::Util.coerce_hash!(data).to_h)
+        def initialize(data = {})
+          @data = {}
+          @coerced = {}
+          OpenAI::Internal::Util.coerce_hash!(data).each do
+            if self.class.known_fields.key?(_1)
+              public_send(:"#{_1}=", _2)
+            else
+              @data.store(_1, _2)
+              @coerced.store(_1, false)
+            end
+          end
+        end
 
         class << self
           # @api private

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

@@ -31,14 +31,20 @@ module OpenAI
         class << self
           # @api private
           #
+          # Coerce value to Boolean if possible, otherwise return the original value.
+          #
           # @param value [Boolean, Object]
           #
           # @param state [Hash{Symbol=>Object}] .
           #
-          #   @option state [Boolean, :strong] :strictness
+          #   @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 [Boolean, Object]

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

@@ -15,10 +15,14 @@ module OpenAI
         #
         # @param state [Hash{Symbol=>Object}] .
         #
-        #   @option state [Boolean, :strong] :strictness
+        #   @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]
@@ -94,6 +98,21 @@ module OpenAI
             end
           end
 
+          # @api private
+          #
+          # @param translate_names [Boolean]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def new_coerce_state(translate_names: true)
+            {
+              translate_names: translate_names,
+              strictness: true,
+              exactness: {yes: 0, no: 0, maybe: 0},
+              error: nil,
+              branched: 0
+            }
+          end
+
           # @api private
           #
           # Based on `target`, transform `value` into `target`, to the extent possible:
@@ -110,14 +129,11 @@ module OpenAI
           #
           # @param value [Object]
           #
-          # @param state [Hash{Symbol=>Object}] The `strictness` is one of `true`, `false`, or `:strong`. This informs the
-          # coercion strategy when we have to decide between multiple possible conversion
-          # targets:
+          # @param state [Hash{Symbol=>Object}] The `strictness` is one of `true`, `false`. This informs the coercion strategy
+          # when we have to decide between multiple possible conversion targets:
           #
           # - `true`: the conversion must be exact, with minimum coercion.
           # - `false`: the conversion can be approximate, with some coercion.
-          # - `:strong`: the conversion must be exact, with no coercion, and raise an error
-          #   if not possible.
           #
           # The `exactness` is `Hash` with keys being one of `yes`, `no`, or `maybe`. For
           # any given conversion attempt, the exactness will be updated based on how closely
@@ -130,21 +146,20 @@ module OpenAI
           #
           # See implementation below for more details.
           #
-          #   @option state [Boolean, :strong] :strictness
+          #   @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(
-            target,
-            value,
-            state: {strictness: true, exactness: {yes: 0, no: 0, maybe: 0}, branched: 0}
-          )
-            # rubocop:disable Lint/SuppressedException
+          def coerce(target, value, state: OpenAI::Internal::Type::Converter.new_coerce_state)
             # rubocop:disable Metrics/BlockNesting
-            strictness, exactness = state.fetch_values(:strictness, :exactness)
+            exactness = state.fetch(:exactness)
 
             case target
             in OpenAI::Internal::Type::Converter
@@ -160,29 +175,26 @@ module OpenAI
                 exactness[value.nil? ? :yes : :maybe] += 1
                 return nil
               in -> { _1 <= Integer }
-                if value.is_a?(Integer)
+                case value
+                in Integer
                   exactness[:yes] += 1
                   return value
-                elsif strictness == :strong && Integer(value, exception: false) != value
-                  message = "no implicit conversion of #{value.class} into #{target.inspect}"
-                  raise value.is_a?(Numeric) ? ArgumentError.new(message) : TypeError.new(message)
                 else
                   Kernel.then do
                     return Integer(value).tap { exactness[:maybe] += 1 }
-                  rescue ArgumentError, TypeError
+                  rescue ArgumentError, TypeError => e
+                    state[:error] = e
                   end
                 end
               in -> { _1 <= Float }
                 if value.is_a?(Numeric)
                   exactness[:yes] += 1
                   return Float(value)
-                elsif strictness == :strong
-                  message = "no implicit conversion of #{value.class} into #{target.inspect}"
-                  raise TypeError.new(message)
                 else
                   Kernel.then do
                     return Float(value).tap { exactness[:maybe] += 1 }
-                  rescue ArgumentError, TypeError
+                  rescue ArgumentError, TypeError => e
+                    state[:error] = e
                   end
                 end
               in -> { _1 <= String }
@@ -194,16 +206,13 @@ module OpenAI
                   exactness[:yes] += 1
                   return value.string
                 else
-                  if strictness == :strong
-                    message = "no implicit conversion of #{value.class} into #{target.inspect}"
-                    raise TypeError.new(message)
-                  end
+                  state[:error] = TypeError.new("#{value.class} can't be coerced into #{String}")
                 end
               in -> { _1 <= Date || _1 <= Time }
                 Kernel.then do
                   return target.parse(value).tap { exactness[:yes] += 1 }
                 rescue ArgumentError, TypeError => e
-                  raise e if strictness == :strong
+                  state[:error] = e
                 end
               in -> { _1 <= StringIO } if value.is_a?(String)
                 exactness[:yes] += 1
@@ -221,10 +230,8 @@ module OpenAI
                   return value
                 end
               else
-                if strictness == :strong
-                  message = "cannot convert non-matching #{value.class} into #{target.inspect}"
-                  raise ArgumentError.new(message)
-                end
+                message = "cannot convert non-matching #{value.class} into #{target.inspect}"
+                state[:error] = ArgumentError.new(message)
               end
             else
             end
@@ -232,7 +239,6 @@ module OpenAI
             exactness[:no] += 1
             value
             # rubocop:enable Metrics/BlockNesting
-            # rubocop:enable Lint/SuppressedException
           end
 
           # @api private
@@ -277,8 +283,10 @@ module OpenAI
         define_sorbet_constant!(:CoerceState) do
           T.type_alias do
             {
-              strictness: T.any(T::Boolean, Symbol),
+              translate_names: T::Boolean,
+              strictness: T::Boolean,
               exactness: {yes: Integer, no: Integer, maybe: Integer},
+              error: T::Class[StandardError],
               branched: Integer
             }
           end

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

@@ -81,10 +81,14 @@ module OpenAI
         #
         # @param state [Hash{Symbol=>Object}] .
         #
-        #   @option state [Boolean, :strong] :strictness
+        #   @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 [Symbol, Object]
@@ -95,8 +99,12 @@ module OpenAI
           if values.include?(val)
             exactness[:yes] += 1
             val
+          elsif values.first&.class == val.class
+            exactness[:maybe] += 1
+            value
           else
-            exactness[values.first&.class == val.class ? :maybe : :no] += 1
+            exactness[:no] += 1
+            state[:error] = TypeError.new("#{value.class} can't be coerced into #{self}")
             value
           end
         end

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

@@ -45,10 +45,14 @@ module OpenAI
           #
           # @param state [Hash{Symbol=>Object}] .
           #
-          #   @option state [Boolean, :strong] :strictness
+          #   @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 [StringIO, Object]
@@ -62,6 +66,7 @@ module OpenAI
               exactness[:yes] += 1
               value
             else
+              state[:error] = TypeError.new("#{value.class} can't be coerced into #{StringIO}")
               exactness[:no] += 1
               value
             end