feat: initial structured outputs support (#565)

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>
Co-authored-by: Charles Finkel <[email protected]>

Author: 3 people

examples/structured_outputs_chat_completions.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# typed: strong
+
+require_relative "../lib/openai"
+
+class Location < OpenAI::BaseModel
+  required :address, String
+  required :city, String, doc: "City name"
+  required :postal_code, String, nil?: true
+end
+
+# Participant model with an optional last_name and an enum for status
+class Participant < OpenAI::BaseModel
+  required :first_name, String
+  required :last_name, String, nil?: true
+  required :status, OpenAI::EnumOf[:confirmed, :unconfirmed, :tentative]
+end
+
+# CalendarEvent model with a list of participants.
+class CalendarEvent < OpenAI::BaseModel
+  required :name, String
+  required :date, String
+  required :participants, OpenAI::ArrayOf[Participant]
+  required :is_virtual, OpenAI::Boolean
+  required :location,
+           OpenAI::UnionOf[String, Location],
+           nil?: true,
+           doc: "Event location"
+end
+
+# # gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+chat_completion = client.chat.completions.create(
+  model: "gpt-4o-2024-08-06",
+  messages: [
+    {role: :system, content: "Extract the event information."},
+    {
+      role: :user,
+      content: <<~CONTENT
+        Alice Shah and Lena are going to a science fair on Friday at 123 Main St. in San Diego.
+        They have also invited Jasper Vellani and Talia Groves - Jasper has not responded and Talia said she is thinking about it.
+      CONTENT
+    }
+  ],
+  response_format: CalendarEvent
+)
+
+chat_completion
+  .choices
+  .filter { !_1.message.refusal }
+  .each do |choice|
+    pp(choice.message.parsed)
+  end

examples/structured_outputs_chat_completions_function_calling.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# typed: strong
+
+require_relative "../lib/openai"
+
+class GetWeather < OpenAI::BaseModel
+  required :location, String, doc: "City and country e.g. Bogotá, Colombia"
+end
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+chat_completion = client.chat.completions.create(
+  model: "gpt-4o-2024-08-06",
+  messages: [
+    {
+      role: :user,
+      content: "What's the weather like in Paris today?"
+    }
+  ],
+  tools: [GetWeather]
+)
+
+chat_completion
+  .choices
+  .filter { !_1.message.refusal }
+  .flat_map { _1.message.tool_calls.to_a }
+  .each do |tool_call|
+    pp(tool_call.function.parsed)
+  end

lib/openai.rb

@@ -50,6 +50,14 @@
 require_relative "openai/internal/stream"
 require_relative "openai/internal/cursor_page"
 require_relative "openai/internal/page"
+require_relative "openai/helpers/structured_output/json_schema_converter"
+require_relative "openai/helpers/structured_output/boolean"
+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"
+require_relative "openai/structured_output"
 require_relative "openai/models/reasoning_effort"
 require_relative "openai/models/chat/chat_completion_message"
 require_relative "openai/models/fine_tuning/fine_tuning_job_wandb_integration_object"

lib/openai/helpers/structured_output.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    # Helpers for the structured output API.
+    #
+    # see https://platform.openai.com/docs/guides/structured-outputs
+    # see https://json-schema.org
+    #
+    # Based on the DSL in {OpenAI::Internal::Type}, but currently only support the limited subset of JSON schema types used in structured output APIs.
+    #
+    # Supported types: {NilClass} {String} {Symbol} {Integer} {Float} {OpenAI::Boolean}, {OpenAI::EnumOf}, {OpenAI::UnionOf}, {OpenAI::ArrayOf}, {OpenAI::BaseModel}
+    module StructuredOutput
+    end
+  end
+end

lib/openai/helpers/structured_output/array_of.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module StructuredOutput
+      # @generic Elem
+      #
+      # @example
+      #   example = OpenAI::ArrayOf[Integer]
+      #
+      # @example
+      #   example = OpenAI::ArrayOf[Integer, nil?: true, doc: "hi there!"]
+      class ArrayOf < OpenAI::Internal::Type::ArrayOf
+        include OpenAI::Helpers::StructuredOutput::JsonSchemaConverter
+
+        # @api private
+        #
+        # @param state [Hash{Symbol=>Object}]
+        #
+        #   @option state [Hash{Object=>String}] :defs
+        #
+        #   @option state [Array<String>] :path
+        #
+        # @return [Hash{Symbol=>Object}]
+        def to_json_schema_inner(state:)
+          OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.cache_def!(state, type: self) do
+            state.fetch(:path) << "[]"
+            items = OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.to_json_schema_inner(
+              item_type,
+              state: state
+            )
+            items = OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.to_nilable(items) if nilable?
+
+            schema = {type: "array", items: items}
+            description.nil? ? schema : schema.update(description: description)
+          end
+        end
+
+        # @return [String, nil]
+        attr_reader :description
+
+        def initialize(type_info, spec = {})
+          super
+          @description = [type_info, spec].grep(Hash).filter_map { _1[:doc] }.first
+        end
+      end
+    end
+  end
+end

lib/openai/helpers/structured_output/base_model.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module StructuredOutput
+      # Represents a response from OpenAI's API where the model's output has been structured according to a schema predefined by the user.
+      #
+      # This class is specifically used when making requests with the `response_format` parameter set to use structured output (e.g., JSON).
+      #
+      # See {examples/structured_outputs_chat_completions.rb} for a complete example of use
+      class BaseModel < OpenAI::Internal::Type::BaseModel
+        extend OpenAI::Helpers::StructuredOutput::JsonSchemaConverter
+
+        class << self
+          # @return [Hash{Symbol=>Object}]
+          def to_json_schema = OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.to_json_schema(self)
+
+          # @api private
+          #
+          # @param state [Hash{Symbol=>Object}]
+          #
+          #   @option state [Hash{Object=>String}] :defs
+          #
+          #   @option state [Array<String>] :path
+          #
+          # @return [Hash{Symbol=>Object}]
+          def to_json_schema_inner(state:)
+            OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.cache_def!(state, type: self) do
+              path = state.fetch(:path)
+              properties = fields.to_h do |name, field|
+                type, nilable = field.fetch_values(:type, :nilable)
+                new_state = {**state, path: [*path, ".#{name}"]}
+
+                schema =
+                  case type
+                  in {"$ref": String}
+                    type
+                  in OpenAI::Helpers::StructuredOutput::JsonSchemaConverter
+                    type.to_json_schema_inner(state: new_state).update(field.slice(:description))
+                  else
+                    OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.to_json_schema_inner(
+                      type,
+                      state: new_state
+                    )
+                  end
+                schema = OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.to_nilable(schema) if nilable
+                [name, schema]
+              end
+
+              {
+                type: "object",
+                properties: properties,
+                required: properties.keys.map(&:to_s),
+                additionalProperties: false
+              }
+            end
+          end
+        end
+
+        class << self
+          def required(name_sym, type_info, spec = {})
+            super
+
+            doc = [type_info, spec].grep(Hash).filter_map { _1[:doc] }.first
+            known_fields.fetch(name_sym).update(description: doc) unless doc.nil?
+          end
+
+          def optional(...)
+            # rubocop:disable Layout/LineLength
+            message = "`optional` is not supported for structured output APIs, use `#required` with `nil?: true` instead"
+            # rubocop:enable Layout/LineLength
+            raise RuntimeError.new(message)
+          end
+        end
+      end
+    end
+  end
+end

lib/openai/helpers/structured_output/boolean.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module StructuredOutput
+      # @abstract
+      #
+      # Ruby does not have a "boolean" Class, this is something for models to refer to.
+      class Boolean < OpenAI::Internal::Type::Boolean
+        extend OpenAI::Helpers::StructuredOutput::JsonSchemaConverter
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        # @api private
+        #
+        # @param state [Hash{Symbol=>Object}]
+        #
+        #   @option state [Hash{Object=>String}] :defs
+        #
+        #   @option state [Array<String>] :path
+        #
+        # @return [Hash{Symbol=>Object}]
+        def self.to_json_schema_inner(state:) = {type: "boolean"}
+
+        # rubocop:enable Lint/UnusedMethodArgument
+      end
+    end
+  end
+end

lib/openai/helpers/structured_output/enum_of.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module StructuredOutput
+      # @generic Value
+      #
+      # @example
+      #   example = OpenAI::EnumOf[:foo, :bar, :zoo]
+      #
+      # @example
+      #   example = OpenAI::EnumOf[1, 2, 3]
+      class EnumOf
+        include OpenAI::Internal::Type::Enum
+        include OpenAI::Helpers::StructuredOutput::JsonSchemaConverter
+
+        # @api private
+        #
+        # @param state [Hash{Symbol=>Object}]
+        #
+        #   @option state [Hash{Object=>String}] :defs
+        #
+        #   @option state [Array<String>] :path
+        #
+        # @return [Hash{Symbol=>Object}]
+        def to_json_schema_inner(state:)
+          OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.cache_def!(state, type: self) do
+            types = values.map do
+              case _1
+              in NilClass
+                "null"
+              in true | false
+                "boolean"
+              in Integer
+                "integer"
+              in Float
+                "number"
+              in Symbol
+                "string"
+              end
+            end
+              .uniq
+
+            {
+              type: types.length == 1 ? types.first : types,
+              enum: values.map { _1.is_a?(Symbol) ? _1.to_s : _1 }
+            }
+          end
+        end
+
+        private_class_method :new
+
+        def self.[](...) = new(...)
+
+        # @return [Array<generic<Value>>]
+        attr_reader :values
+
+        # @param values [Array<generic<Value>>]
+        def initialize(*values) = (@values = values.map { _1.is_a?(String) ? _1.to_sym : _1 })
+      end
+    end
+  end
+end