omniai 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae7a0b04197a95f107c66d4d7108435f44f82d0e3e4b3a956cb755d3ac352c6a
-  data.tar.gz: 9d8a85ede589c08431d49ada35d2a13ed57338f7eafbc7231134e1866e083bc3
+  metadata.gz: 7464f0580c8f8392155996aa7b4675491bec1fe62b48ff9b12e53264952a50e5
+  data.tar.gz: 3ef5570bd7eac6ed72a9826c90313565dc0fd00b6ec52745fe02a04ce2855264
 SHA512:
-  metadata.gz: 05372f0de7a16a3da31702eebfa49b2cd1bbc890ee1777820b575e81c72d59d532941ed96d52ac572b58fd34ab9f897fcda2d85bd91d21be00b115de39a1dac2
-  data.tar.gz: f2b518b58405e2a4995b282280693f4d985cd1b9ce129abc04a55e679e62b5b9a495aa9ed980449874af43f7d8cd5108c717bed5b5f4337a3d65f3ef1ecd9c31
+  metadata.gz: e5ab80ba78ab316ca74e46dffb0bdea26ed13b83f4ec4ff7c5e985580c5460d926366d71bf547ac905273968db44cf1949eb57c56b0560077f1b805f52a4c93d
+  data.tar.gz: bd453f4fd6355066833db225b771b1078fd8d916138213a1f0d4d18f37316cae7b60f47a215c46d7a76fb096eeece2e6d887a8dc9a4819c8c54dd65f3ece731f

data/README.md

@@ -398,6 +398,19 @@ require 'omniai/openai'
 client = OmniAI::OpenAI::Client.new
 ```
 
+OpenAI-compatible gateways can be configured by passing a custom host. This keeps
+normal OpenAI usage unchanged while allowing private gateways, local model
+servers, or governed endpoints such as Tuning Engines:
+
+```ruby
+require 'omniai/openai'
+
+client = OmniAI::OpenAI::Client.new(
+  api_key: ENV.fetch('OPENAI_API_KEY'),
+  host: ENV.fetch('OPENAI_HOST', 'https://api.openai.com')
+)
+```
+
 #### Usage with LocalAI
 
 LocalAI support is offered through [OmniAI::OpenAI](https://github.com/ksylvest/omniai-openai):

data/lib/omniai/chat/choice.rb

@@ -16,11 +16,18 @@ module OmniAI
       #   @return [Message]
       attr_accessor :message
 
+      # @!attribute [rw] finish_reason
+      #   @return [FinishReason, nil] the normalized reason generation stopped (carrying both `#reason` and the
+      #     verbatim provider `#value`), or `nil` when absent.
+      attr_accessor :finish_reason
+
       # @param message [Message]
       # @param index [Integer]
-      def initialize(message:, index: DEFAULT_INDEX)
+      # @param finish_reason [FinishReason, nil]
+      def initialize(message:, index: DEFAULT_INDEX, finish_reason: nil)
         @message = message
         @index = index
+        @finish_reason = finish_reason
       end
 
       # @return [String]
@@ -39,7 +46,7 @@ module OmniAI
         index = data["index"] || DEFAULT_INDEX
         message = Message.deserialize(data["message"] || data["delta"], context:)
 
-        new(message:, index:)
+        new(message:, index:, finish_reason: FinishReason.deserialize(data["finish_reason"]))
       end
 
       # @param context [OmniAI::Context] optional

data/lib/omniai/chat/finish_reason.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module OmniAI
+  class Chat
+    # A normalized, provider-agnostic reason a generation stopped, paired with the verbatim provider value.
+    #
+    # `#reason` is one of the canonical symbols ({REASONS}) for branching/alerting; `#value` is the raw provider
+    # token (e.g. "RECITATION", "end_turn", "stop"), preserved verbatim — including when the reason normalizes to
+    # `:other`. Each provider maps its own vocabulary onto a reason in its deserializer; the verbatim value is never
+    # discarded, so consumers keep provider granularity without digging the provider-specific response `data`.
+    class FinishReason
+      # A natural stopping point was reached.
+      STOP = :stop
+
+      # The token budget (requested max tokens or the model's context window) was reached.
+      LENGTH = :length
+
+      # The model is requesting a tool / function call.
+      TOOL_CALL = :tool_call
+
+      # The provider deliberately suppressed or blocked output (safety, policy, recitation, unsupported language).
+      FILTER = :filter
+
+      # A value was present but does not map to a known category (forward-compatible fallback).
+      OTHER = :other
+
+      # The canonical normalized reasons.
+      REASONS = %i[stop length tool_call filter other].freeze
+
+      # The Chat Completions `finish_reason` vocabulary (originated by OpenAI; also emitted by Mistral and
+      # OpenAI-compatible gateways). Applied by the base `Choice.deserialize` path, which models that schema.
+      CHAT_COMPLETIONS = {
+        "stop" => STOP,
+        "length" => LENGTH,
+        "tool_calls" => TOOL_CALL,
+        "function_call" => TOOL_CALL,
+        "content_filter" => FILTER,
+      }.freeze
+
+      # @!attribute [r] reason
+      #   @return [Symbol] one of {REASONS}
+      attr_reader :reason
+
+      # @!attribute [r] value
+      #   @return [String] the verbatim provider token
+      attr_reader :value
+
+      # Normalizes a raw provider value through a mapping table into a FinishReason.
+      #
+      # - `nil` in → `nil` out (absence is not the same as unrecognized).
+      # - otherwise → a FinishReason whose `reason` is the table's mapping (or `:other` when unmapped) and whose
+      #   `value` is the raw token, preserved verbatim — always, including on `:other`.
+      #
+      # @param value [String, nil] the raw provider value
+      # @param table [Hash{String => Symbol}] the provider's mapping table (defaults to the Chat Completions vocabulary)
+      #
+      # @return [FinishReason, nil]
+      def self.deserialize(value, table: CHAT_COMPLETIONS)
+        return if value.nil?
+
+        new(reason: table.fetch(value, OTHER), value:)
+      end
+
+      # @param reason [Symbol] one of {REASONS}
+      # @param value [String] the verbatim provider token
+      def initialize(reason:, value:)
+        @reason = reason
+        @value = value
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} reason=#{reason.inspect} value=#{value.inspect}>"
+      end
+
+      # @return [Boolean]
+      def stop?
+        reason == STOP
+      end
+
+      # @return [Boolean]
+      def length?
+        reason == LENGTH
+      end
+
+      # @return [Boolean]
+      def tool_call?
+        reason == TOOL_CALL
+      end
+
+      # @return [Boolean]
+      def filter?
+        reason == FILTER
+      end
+
+      # @return [Boolean]
+      def other?
+        reason == OTHER
+      end
+    end
+  end
+end

data/lib/omniai/chat/message.rb

@@ -145,7 +145,7 @@ module OmniAI
         return if @content.nil?
         return @content if @content.is_a?(String)
 
-        parts = arrayify(@content).filter { |content| content.is_a?(Text) }
+        parts = arrayify(@content).grep(Text)
         parts.map(&:text).join("\n") unless parts.empty?
       end
 
@@ -158,7 +158,7 @@ module OmniAI
       def thinking
         return if @content.nil?
 
-        parts = arrayify(@content).filter { |content| content.is_a?(Thinking) }
+        parts = arrayify(@content).grep(Thinking)
         parts.map(&:thinking).join("\n") unless parts.empty?
       end
 

data/lib/omniai/chat/response.rb

@@ -23,12 +23,29 @@ module OmniAI
       # @param data [Hash]
       # @param choices [Array<Choice>]
       # @param usage [Usage, nil]
-      def initialize(data:, choices: [], usage: nil)
+      # @param finish_reason [FinishReason, nil] an optional response-level finish reason (used by providers that
+      #   expose it at the response level, e.g. OpenAI's Responses API); when omitted, `#finish_reason` falls back to
+      #   the first choice's finish reason.
+      def initialize(data:, choices: [], usage: nil, finish_reason: nil)
         @data = data
         @choices = choices
         @usage = usage
+        @finish_reason = finish_reason
       end
 
+      # The normalized {FinishReason} for the final turn (carrying both `#reason` and the verbatim provider `#value`),
+      # or `nil` when absent. Some providers (e.g. OpenAI's Responses API) expose this at the response level; most
+      # expose it per-choice. Prefers an explicit response-level value, then falls back to the first choice. Reflects
+      # this response only (the final turn) — it is not aggregated across the parent chain, unlike {#total_usage}.
+      #
+      # @return [FinishReason, nil]
+      def finish_reason
+        @finish_reason || @choices.first&.finish_reason
+      end
+
+      # @!attribute [w] finish_reason
+      attr_writer :finish_reason
+
       # @return [String]
       def inspect
         "#<#{self.class.name} choices=#{@choices.inspect} usage=#{@usage.inspect}>"

data/lib/omniai/client.rb

@@ -10,7 +10,7 @@ module OmniAI
   #       super
   #     end
   #
-  #     # @return [HTTP::Client]
+  #     # @return [HTTP::Client, HTTP::Session]
   #     def connection
   #       @connection ||= super.auth("Bearer: #{@api_key}")
   #     end
@@ -175,7 +175,7 @@ module OmniAI
       "#{api_key[..2]}***" if api_key
     end
 
-    # @return [HTTP::Client]
+    # @return [HTTP::Client, HTTP::Session] an `HTTP::Client` on http 5, an `HTTP::Session` on http 6
     def connection
       http = HTTP.persistent(@host)
       http = http.use(instrumentation: { instrumenter: Instrumentation.new(logger: @logger) }) if @logger

data/lib/omniai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniAI
-  VERSION = "3.6.0"
+  VERSION = "3.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.0
 platform: ruby
 authors:
 - Kevin Sylvestre
@@ -41,16 +41,22 @@ dependencies:
   name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -99,6 +105,7 @@ files:
 - lib/omniai/chat/content.rb
 - lib/omniai/chat/delta.rb
 - lib/omniai/chat/file.rb
+- lib/omniai/chat/finish_reason.rb
 - lib/omniai/chat/function.rb
 - lib/omniai/chat/media.rb
 - lib/omniai/chat/message.rb