omniai-openai 3.0.2 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 312d839fba28d30d0475015f49a50482c2d852d2bbdd32e9e34b23c45f6b50fd
-  data.tar.gz: 674840ca8ddcc80e245fab65548831df37336367c244be8ed37732fcfcc50ec9
+  metadata.gz: 231ff4c15352d0e13f870683f437e7e05b41b78e58c6d5b343f3bd827a7874aa
+  data.tar.gz: 06e2e6d651eb56384ede3176920abbd51f771ba17ea066ab6f1842fc3e6a06ca
 SHA512:
-  metadata.gz: 9dadc45e46012fafb754d59fc695ac3e2b92ec7154c48a5fe00d04c7eaea7212092b9346193707c53e6a934f5960017ab8b49c28af962b0035e80ebc8df5fd82
-  data.tar.gz: 3e3646c25af3ba4d23b7f6a6d2aaa1e302f2c874c71c71a846c23600598a55e19c3583c7c90ed5639beb0227037049f9d174bf0fe5eef7c7aa5d2a543a7b51b6
+  metadata.gz: c17675c981946547d0c19c0f885d347d13b44a11a4344fa6e08cd35e930f4ca97987e66c69eb600091bb7dc71139ceaf510cbf1cbf017dec848a3105fa3c084e
+  data.tar.gz: e68ce52cfbdc2230d7690a75d5e81f35682502e18284aaaa72622abe5ee93fb4cdd59aa042791e6c7e39ddfce2011ab2b5c1f07c5dfbe713d79efb2353dab1d2

data/README.md

@@ -76,6 +76,18 @@ client  = OmniAI::OpenAI::Client.new(
             api_prefix: '/api')
 ```
 
+#### Usage with OpenAI-compatible gateways
+
+Private gateways and governed AI control planes can also be configured with a
+custom `host` while keeping application code on OmniAI's OpenAI provider:
+
+```ruby
+client = OmniAI::OpenAI::Client.new(
+  host: ENV.fetch('OPENAI_HOST', 'https://api.openai.com'),
+  api_key: ENV.fetch('OPENAI_API_KEY')
+)
+```
+
 ### Chat
 
 A chat completion is generated by passing in a simple text prompt:
@@ -97,13 +109,16 @@ completion.content # 'The capital of Canada is Ottawa.'
 
 #### Model
 
-`model` takes an optional string (default is `gpt-4o`):
+`model` takes an optional string (default is `gpt-5.2`):
 
 ```ruby
-completion = client.chat('How fast is a cheetah?', model: OmniAI::OpenAI::Chat::Model::GPT_3_5_TURBO)
+completion = client.chat('How fast is a cheetah?', model: OmniAI::OpenAI::Chat::Model::GPT_5_5)
 completion.content # 'A cheetah can reach speeds over 100 km/h.'
 ```
 
+Note that `temperature` is not supported by every model (e.g. `gpt-5`, `gpt-5.5` and the `o`-series). It is
+omitted from the request for those models rather than sent and rejected — see `TEMPERATURE_UNSUPPORTED_MODELS`.
+
 [OpenAI API Reference `model`](https://platform.openai.com/docs/api-reference/chat/create#chat-create-model)
 
 #### Temperature
@@ -146,6 +161,61 @@ JSON.parse(completion.content) # { "name": "Ringo" }
 
 > When using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message.
 
+#### Reasoning
+
+OpenAI o1 and o3 models support reasoning, which provides a summary of the model's thought process.
+
+```ruby
+# Enable reasoning with unified thinking API
+response = client.chat("What is 25 * 25?", model: "o3-mini", thinking: true)
+
+# Or use OpenAI-specific reasoning options
+response = client.chat("What is 25 * 25?", model: "o3-mini", reasoning: { effort: "high", summary: "auto" })
+```
+
+**Reasoning Effort Levels:**
+- `low` - Minimal reasoning
+- `medium` - Balanced reasoning
+- `high` - Maximum reasoning effort
+
+#### Accessing Reasoning Content
+
+```ruby
+response.choices.first.message.contents.each do |content|
+  case content
+  when OmniAI::Chat::Thinking
+    puts "Reasoning: #{content.thinking}"
+  when OmniAI::Chat::Text
+    puts "Response: #{content.text}"
+  end
+end
+```
+
+#### Streaming with Reasoning
+
+```ruby
+client.chat("What are the prime factors of 1234567?", model: "o3-mini", thinking: true, stream: $stdout)
+```
+
+[OpenAI API Reference `reasoning`](https://platform.openai.com/docs/guides/reasoning)
+
+#### Other Responses API Options
+
+Any option that is not modelled explicitly is forwarded to the Responses API verbatim, so parameters the gem
+does not wrap are still reachable:
+
+```ruby
+completion = client.chat('Summarize this.', model: 'gpt-5.5', max_output_tokens: 512, store: false)
+
+# continue a stored conversation
+completion = client.chat('And the next one?', previous_response_id: 'resp_123')
+```
+
+This covers `max_output_tokens`, `previous_response_id`, `store`, `parallel_tool_calls`, `metadata`,
+`truncation`, `top_p`, `service_tier`, and `prompt_cache_key`, among others.
+
+[OpenAI API Reference `responses`](https://platform.openai.com/docs/api-reference/responses/create)
+
 ### Transcribe
 
 A transcription is generated by passing in a path to a file:
@@ -231,7 +301,7 @@ client.speak('She sells seashells by the seashore.', voice: OmniAI::OpenAI::Spea
 
 #### Model
 
-`model` is optional and must be either `tts-1` or `tts-1-hd` (default):
+`model` is optional and is one of `tts-1`, `tts-1-hd`, or `gpt-4o-mini-tts` (default):
 
 ```ruby
 client.speak('I saw a kitten eating chicken in the kitchen.', format: OmniAI::OpenAI::Speak::Model::TTS_1)

data/lib/omniai/openai/chat/content_serializer.rb

@@ -8,10 +8,11 @@ module OmniAI
         # @param data [Hash]
         # @param context [Context]
         #
-        # @return [OmniAI::Chat::Text, OmniAI::Chat::ToolCall]
+        # @return [OmniAI::Chat::Text, OmniAI::Chat::Thinking, OmniAI::Chat::ToolCall]
         def self.deserialize(data, context:)
           case data["type"]
           when /(input|output)_text/ then OmniAI::Chat::Text.deserialize(data, context:)
+          when "reasoning" then OmniAI::Chat::Thinking.deserialize(data, context:)
           end
         end
       end

data/lib/omniai/openai/chat/message_serializer.rb

@@ -30,11 +30,14 @@ module OmniAI
         # @param message [OmniAI::Chat::Message]
         # @param context [OmniAI::Context]
         #
-        # @return [Hash]
+        # @return [Hash, nil]
         def self.serialize_for_content(message, context:)
           role = message.role
           direction = message.direction
-          parts = arrayify(message.content)
+          # Filter out thinking content - OpenAI doesn't accept it in input messages
+          parts = arrayify(message.content).reject { |part| part.is_a?(OmniAI::Chat::Thinking) }
+
+          return if parts.empty?
 
           content = parts.map do |part|
             case part
@@ -54,9 +57,19 @@ module OmniAI
           case data["type"]
           when "message" then deserialize_for_content(data, context:)
           when "function_call" then deserialize_for_tool_call(data, context:)
+          when "reasoning" then deserialize_for_reasoning(data, context:)
           end
         end
 
+        # @param data [Hash]
+        # @param context [OmniAI::Context]
+        #
+        # @return [OmniAI::Chat::Message]
+        def self.deserialize_for_reasoning(data, context:)
+          thinking = OmniAI::Chat::Thinking.deserialize(data, context:)
+          OmniAI::Chat::Message.new(role: OmniAI::Chat::Role::ASSISTANT, content: [thinking])
+        end
+
         # @param data [Hash]
         # @param context [OmniAI::Context]
         #

data/lib/omniai/openai/chat/response_serializer.rb

@@ -25,7 +25,7 @@ module OmniAI
         # @return [OmniAI::Chat::Response]
         def self.deserialize(data, context:)
           usage = OmniAI::Chat::Usage.deserialize(data["usage"], context:) if data["usage"]
-          choices = data["output"].map { |choice_data| OmniAI::Chat::Choice.deserialize(choice_data, context:) }
+          choices = data["output"].filter_map { |choice_data| OmniAI::Chat::Choice.deserialize(choice_data, context:) }
 
           OmniAI::Chat::Response.new(data:, choices:, usage:)
         end

data/lib/omniai/openai/chat/stream.rb

@@ -15,8 +15,10 @@ module OmniAI
           @chunks.each do |chunk|
             parser.feed(chunk.b) do |type, data, _id|
               case type
-              when /response\.(.*)_text\.delta/
+              when "response.output_text.delta"
                 block.call(OmniAI::Chat::Delta.new(text: JSON.parse(data)["delta"]))
+              when "response.reasoning_summary_text.delta"
+                block.call(OmniAI::Chat::Delta.new(thinking: JSON.parse(data)["delta"]))
               when "response.completed"
                 response = JSON.parse(data)["response"]
               end

data/lib/omniai/openai/chat/thinking_serializer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module OpenAI
+    class Chat
+      # Overrides thinking serialize / deserialize.
+      module ThinkingSerializer
+        # @param data [Hash]
+        # @param context [Context]
+        #
+        # @return [OmniAI::Chat::Thinking]
+        def self.deserialize(data, context: nil) # rubocop:disable Lint/UnusedMethodArgument
+          summary = data["summary"]
+
+          thinking = case summary
+                     when Array
+                       summary.filter_map { |item| item["text"] if item["type"] == "summary_text" }.join("\n")
+                     when String
+                       summary
+                     else
+                       data["thinking"]
+                     end
+
+          OmniAI::Chat::Thinking.new(thinking)
+        end
+
+        # @param thinking [OmniAI::Chat::Thinking]
+        # @param context [Context]
+        #
+        # @return [Hash]
+        def self.serialize(thinking, context: nil) # rubocop:disable Lint/UnusedMethodArgument
+          { type: "reasoning", summary: thinking.thinking }
+        end
+      end
+    end
+  end
+end

data/lib/omniai/openai/chat/usage_serializer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module OpenAI
+    class Chat
+      # Overrides usage deserialize to read OpenAI's reasoning breakdown.
+      module UsageSerializer
+        # OpenAI already counts reasoning inside `output_tokens` and reports the breakdown alongside it, so the
+        # breakdown is read into `thinking_tokens` and the output count is left exactly as reported. Adding the two
+        # together would double count.
+        #
+        # This gem targets the Responses API (`/responses`), whose usage object reports the breakdown at
+        # `output_tokens_details.reasoning_tokens`. The Chat Completions vocabulary from the previous API
+        # generation (`completion_tokens_details`) is deliberately not read — this gem never receives it.
+        #
+        # @param data [Hash]
+        # @return [OmniAI::Chat::Usage]
+        def self.deserialize(data, *)
+          # Deserialize without a context so the generic flat parse runs rather than recursing into this method.
+          usage = OmniAI::Chat::Usage.deserialize(data)
+
+          # Only overwrite when the vendor container is actually present. A payload produced by `Usage#serialize`
+          # carries base's own `thinking_tokens` key and no `output_tokens_details`, so assigning unconditionally
+          # would clobber a correctly-parsed value with nil and break the round-trip. `unless nil?` rather than
+          # `||=`, so a reported zero from the wire still wins over base's nil.
+          reasoning_tokens = data.dig("output_tokens_details", "reasoning_tokens")
+          usage.thinking_tokens = reasoning_tokens unless reasoning_tokens.nil?
+
+          usage
+        end
+      end
+    end
+  end
+end

data/lib/omniai/openai/chat.rb

@@ -32,11 +32,23 @@ module OmniAI
       end
 
       module Model
+        GPT_5_6_LUNA = "gpt-5.6-luna"
+        GPT_5_6_SOL = "gpt-5.6-sol"
+        GPT_5_6_TERRA = "gpt-5.6-terra"
+        GPT_5_5 = "gpt-5.5"
+        GPT_5_5_PRO = "gpt-5.5-pro"
+        GPT_5_4 = "gpt-5.4"
+        GPT_5_4_MINI = "gpt-5.4-mini"
+        GPT_5_4_NANO = "gpt-5.4-nano"
+        GPT_5_4_PRO = "gpt-5.4-pro"
+        GPT_5_3_CODEX = "gpt-5.3-codex"
         GPT_5_2 = "gpt-5.2"
+        GPT_5_2_PRO = "gpt-5.2-pro"
         GPT_5_1 = "gpt-5.1"
         GPT_5 = "gpt-5"
         GPT_5_MINI = "gpt-5-mini"
         GPT_5_NANO = "gpt-5-nano"
+        GPT_5_PRO = "gpt-5-pro"
         GPT_4_1 = "gpt-4.1"
         GPT_4_1_NANO = "gpt-4.1-nano"
         GPT_4_1_MINI = "gpt-4.1-mini"
@@ -54,6 +66,38 @@ module OmniAI
 
       DEFAULT_MODEL = Model::GPT_5_2
 
+      # Models that reject `temperature` on the Responses API.
+      #
+      # OpenAI's support here is not patterned by version, so this cannot be a prefix rule: `gpt-5` and its
+      # mini/nano/pro variants reject `temperature`, `gpt-5.1` through `gpt-5.4` accept it, and `gpt-5.5`
+      # onwards rejects it again. Every entry below was verified live against the API on 2026-08-16 by issuing
+      # a request with `temperature` and checking for `Unsupported parameter`.
+      #
+      # Models absent from this list pass `temperature` through unchanged. That is deliberate: an unlisted
+      # model that rejects it surfaces a loud API error the caller can act on, whereas over-applying the guard
+      # would silently discard a caller's temperature.
+      TEMPERATURE_UNSUPPORTED_MODELS = [
+        Model::GPT_5_6_LUNA,
+        Model::GPT_5_6_SOL,
+        Model::GPT_5_6_TERRA,
+        Model::GPT_5_5,
+        Model::GPT_5_5_PRO,
+        Model::GPT_5_4_PRO,
+        Model::GPT_5_2_PRO,
+        Model::GPT_5,
+        Model::GPT_5_MINI,
+        Model::GPT_5_NANO,
+        Model::GPT_5_PRO,
+        Model::O1_MINI,
+        Model::O1,
+        Model::O3,
+        Model::O3_MINI,
+        Model::O4_MINI,
+      ].freeze
+
+      # Keys in `@options` consumed by dedicated builders below rather than sent verbatim.
+      RESERVED_OPTIONS = %i[text reasoning thinking].freeze
+
       # @return [Context]
       CONTEXT = Context.build do |context|
         context.serializers[:choice] = ChoiceSerializer.method(:serialize)
@@ -65,6 +109,7 @@ module OmniAI
         context.serializers[:response] = ResponseSerializer.method(:serialize)
         context.deserializers[:response] = ResponseSerializer.method(:deserialize)
         context.deserializers[:content] = ContentSerializer.method(:deserialize)
+        context.deserializers[:usage] = UsageSerializer.method(:deserialize)
         context.serializers[:file] = FileSerializer.method(:serialize)
         context.serializers[:url] = URLSerializer.method(:serialize)
         context.serializers[:tool] = ToolSerializer.method(:serialize)
@@ -74,6 +119,8 @@ module OmniAI
         context.deserializers[:tool_call_result] = ToolCallResultSerializer.method(:deserialize)
         context.serializers[:tool_call_message] = ToolCallMessageSerializer.method(:serialize)
         context.deserializers[:tool_call_message] = ToolCallMessageSerializer.method(:deserialize)
+        context.serializers[:thinking] = ThinkingSerializer.method(:serialize)
+        context.deserializers[:thinking] = ThinkingSerializer.method(:deserialize)
       end
 
     protected
@@ -88,7 +135,7 @@ module OmniAI
         @prompt
           .messages
           .reject(&:system?)
-          .map { |message| message.serialize(context:) }
+          .filter_map { |message| message.serialize(context:) }
       end
 
       # @return [String, nil]
@@ -104,36 +151,38 @@ module OmniAI
         parts.join("\n\n")
       end
 
+      # @return [String]
+      def model
+        @model || DEFAULT_MODEL
+      end
+
       # @return [Float, nil]
       def temperature
         return if @temperature.nil?
-
-        return if [
-          Model::GPT_5,
-          Model::GPT_5_MINI,
-          Model::GPT_5_NANO,
-          Model::GPT_5_1,
-          Model::GPT_5_2,
-          Model::O1_MINI,
-          Model::O1,
-          Model::O3_MINI,
-        ].include?(@model)
+        return if TEMPERATURE_UNSUPPORTED_MODELS.include?(model)
 
         @temperature
       end
 
+      # Unrecognized options are passed through verbatim so callers can reach Responses API parameters the gem
+      # does not model explicitly (e.g. `max_output_tokens`, `previous_response_id`, `store`,
+      # `parallel_tool_calls`, `metadata`, `truncation`, `top_p`). Keys built by dedicated methods are excluded
+      # so they are not sent twice, and the explicit keys below win over any same-named passthrough.
+      #
       # @return [Hash]
       def payload
-        OmniAI::OpenAI.config.chat_options.merge({
-          instructions:,
-          input:,
-          model: @model || DEFAULT_MODEL,
-          stream: stream? || nil,
-          temperature:,
-          tools:,
-          text:,
-          reasoning:,
-        }).compact
+        OmniAI::OpenAI.config.chat_options
+          .merge(@options.except(*RESERVED_OPTIONS))
+          .merge({
+            instructions:,
+            input:,
+            model:,
+            stream: stream? || nil,
+            temperature:,
+            tools:,
+            text:,
+            reasoning:,
+          }).compact
       end
 
       # @return [Array<Hash>]
@@ -155,9 +204,24 @@ module OmniAI
       end
 
       # @return [Hash]
+      # Accepts unified `thinking:` option and translates to OpenAI's `reasoning:` format.
+      # Example: `thinking: { effort: "high" }` becomes `reasoning: { effort: "high", summary: "auto" }`
       def reasoning
-        options = @options.fetch(:reasoning, {})
-        options unless options.empty?
+        # Support both native `reasoning:` and unified `thinking:` options
+        options = @options[:reasoning] || translate_thinking_to_reasoning
+        options unless options.nil? || options.empty?
+      end
+
+      # Translates unified thinking option to OpenAI reasoning format
+      # @return [Hash, nil]
+      def translate_thinking_to_reasoning
+        thinking = @options[:thinking]
+        return unless thinking
+
+        case thinking
+        when true then { effort: ReasoningEffort::HIGH, summary: "auto" }
+        when Hash then { summary: "auto" }.merge(thinking)
+        end
       end
 
       # @raise [ArgumentError]

data/lib/omniai/openai/speak.rb

@@ -13,14 +13,17 @@ module OmniAI
       module Voice
         ALLOY = "alloy" # https://platform.openai.com/docs/guides/text-to-speech/alloy
         ASH = "ash" # https://platform.openai.com/docs/guides/text-to-speech/ash
-        BALLARD = "ballard" # https://platform.openai.com/docs/guides/text-to-speech/ballard
+        BALLAD = "ballad" # https://platform.openai.com/docs/guides/text-to-speech/ballad
+        CEDAR = "cedar" # https://platform.openai.com/docs/guides/text-to-speech/cedar
         CORAL = "coral" # https://platform.openai.com/docs/guides/text-to-speech/coral
         ECHO = "echo" # https://platform.openai.com/docs/guides/text-to-speech/echo
         FABLE = "fable" # https://platform.openai.com/docs/guides/text-to-speech/fable
+        MARIN = "marin" # https://platform.openai.com/docs/guides/text-to-speech/marin
         NOVA = "nova" # https://platform.openai.com/docs/guides/text-to-speech/nova
         ONYX = "onyx" # https://platform.openai.com/docs/guides/text-to-speech/onyx
         SAGE = "sage" # https://platform.openai.com/docs/guides/text-to-speech/sage
         SHIMMER = "shimmer" # https://platform.openai.com/docs/guides/text-to-speech/shimmer
+        VERSE = "verse" # https://platform.openai.com/docs/guides/text-to-speech/verse
       end
 
       DEFAULT_MODEL = Model::GPT_4O_MINI_TTS

data/lib/omniai/openai/transcribe.rb

@@ -7,7 +7,10 @@ module OmniAI
       module Model
         WHISPER_1 = "whisper-1"
         GPT_4O_TRANSCRIBE = "gpt-4o-transcribe"
-        GPT_4O_MINI_TRANSCRIBE = "gpt-4-0-mini-transcribe"
+        GPT_4O_TRANSCRIBE_DIARIZE = "gpt-4o-transcribe-diarize"
+        GPT_4O_MINI_TRANSCRIBE = "gpt-4o-mini-transcribe"
+        GPT_TRANSCRIBE = "gpt-transcribe"
+        GPT_LIVE_TRANSCRIBE = "gpt-live-transcribe"
         WHISPER = WHISPER_1
       end
 

data/lib/omniai/openai/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAI
   module OpenAI
-    VERSION = "3.0.2"
+    VERSION = "3.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniai-openai
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.2.0
 platform: ruby
 authors:
 - Kevin Sylvestre
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.8'
 - !ruby/object:Gem::Dependency
   name: openssl
   requirement: !ruby/object:Gem::Requirement
@@ -83,11 +83,13 @@ files:
 - lib/omniai/openai/chat/response_serializer.rb
 - lib/omniai/openai/chat/stream.rb
 - lib/omniai/openai/chat/text_serializer.rb
+- lib/omniai/openai/chat/thinking_serializer.rb
 - lib/omniai/openai/chat/tool_call_message_serializer.rb
 - lib/omniai/openai/chat/tool_call_result_serializer.rb
 - lib/omniai/openai/chat/tool_call_serializer.rb
 - lib/omniai/openai/chat/tool_serializer.rb
 - lib/omniai/openai/chat/url_serializer.rb
+- lib/omniai/openai/chat/usage_serializer.rb
 - lib/omniai/openai/client.rb
 - lib/omniai/openai/config.rb
 - lib/omniai/openai/embed.rb