feat: ensure partial jsons in structured ouput are handled gracefully (#740)

Author: ms-jpq

lib/openai.rb

@@ -56,6 +56,7 @@
 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"

lib/openai/helpers/structured_output/parsed_json.rb

@@ -0,0 +1,40 @@
+# 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.fetch(:exactness)[:yes] += 1
+            (state[:error] = value) if value.is_a?(StandardError)
+
+            value
+          end
+        end
+      end
+    end
+  end
+end

lib/openai/models/chat/chat_completion_message.rb

@@ -14,7 +14,7 @@ class ChatCompletionMessage < OpenAI::Internal::Type::BaseModel
         #   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.

lib/openai/models/chat/chat_completion_message_tool_call.rb

@@ -44,7 +44,7 @@ class Function < OpenAI::Internal::Type::BaseModel
           #   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.

lib/openai/models/responses/response_function_tool_call.rb

@@ -14,7 +14,7 @@ class ResponseFunctionToolCall < OpenAI::Internal::Type::BaseModel
         #   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.

lib/openai/models/responses/response_output_text.rb

@@ -23,7 +23,7 @@ class ResponseOutputText < OpenAI::Internal::Type::BaseModel
         #   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`.

lib/openai/resources/chat/completions.rb

@@ -104,7 +104,6 @@ def create(params)
             raise ArgumentError.new(message)
           end
 
-          # rubocop:disable Layout/LineLength
           model = nil
           tool_models = {}
           case parsed
@@ -157,11 +156,16 @@ def create(params)
           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,15 +175,19 @@ def create(params)
                 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
             end
 
             raw
           end
-          # rubocop:enable Layout/LineLength
+          # rubocop:enable Metrics/BlockLength
 
           @client.request(
             method: :post,

lib/openai/resources/responses.rb

@@ -442,15 +442,23 @@ def parse_structured_outputs!(raw, model, tool_models)
             end
             &.each do |content|
               next unless content[:type] == "output_text"
-              parsed = JSON.parse(content.fetch(:text), symbolize_names: true)
+              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?
-          parsed = JSON.parse(output.fetch(:arguments), symbolize_names: true)
+          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

test/openai/helpers/structured_output_test.rb

@@ -52,7 +52,8 @@ def test_coerce
       exactness, expect = rhs
       state = OpenAI::Internal::Type::Converter.new_coerce_state
       assert_pattern do
-        OpenAI::Internal::Type::Converter.coerce(target, input, state: state) => ^expect
+        coerced = OpenAI::Internal::Type::Converter.coerce(target, input, state: state)
+        coerced => ^expect
         state.fetch(:exactness).filter { _2.nonzero? }.to_h => ^exactness
       end
     end
@@ -218,4 +219,26 @@ def test_definition_reusing
       end
     end
   end
+
+  class M7 < OpenAI::Helpers::StructuredOutput::BaseModel
+    required :a, OpenAI::Helpers::StructuredOutput::ParsedJson
+  end
+
+  def test_parsed_json
+    assert_pattern do
+      M7.new(a: {dog: "woof"}) => {a: {dog: "woof"}}
+    end
+
+    err = JSON::ParserError.new("unexpected token at 'invalid json'")
+
+    m1 = M7.new(a: err)
+    assert_raises(OpenAI::Errors::ConversionError) do
+      m1.a
+    end
+
+    m2 = OpenAI::Internal::Type::Converter.coerce(M7, {a: err})
+    assert_raises(OpenAI::Errors::ConversionError) do
+      m2.a
+    end
+  end
 end