omniai 3.6.0 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae7a0b04197a95f107c66d4d7108435f44f82d0e3e4b3a956cb755d3ac352c6a
-  data.tar.gz: 9d8a85ede589c08431d49ada35d2a13ed57338f7eafbc7231134e1866e083bc3
+  metadata.gz: e22534811cc346b74927ec47382420e86faee449ff730cbb0665d30a714cd872
+  data.tar.gz: 1c3e58ad36506a2564563c46a700e8be04731b7266d8008bbd63bcc22d9cfa64
 SHA512:
-  metadata.gz: 05372f0de7a16a3da31702eebfa49b2cd1bbc890ee1777820b575e81c72d59d532941ed96d52ac572b58fd34ab9f897fcda2d85bd91d21be00b115de39a1dac2
-  data.tar.gz: f2b518b58405e2a4995b282280693f4d985cd1b9ce129abc04a55e679e62b5b9a495aa9ed980449874af43f7d8cd5108c717bed5b5f4337a3d65f3ef1ecd9c31
+  metadata.gz: ea3efdf811897d5fff8f55b0e4051b71f151d077230518b139fde0ef38656c6b784f9aafcfccb43c692fe85a102b47d0ca41c8696af767294b1a2270dfeee5fa
+  data.tar.gz: f3e87e1dd51ca72ec1d8706d3833a06c10b65947fdaf1e9a375518ca2b3d78f03a43af1c2869de1e84fb1c5cd77226ecbd5aa45fa7092f84691f0ea5f5afd183

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/instrumentation.rb

@@ -8,27 +8,78 @@ module OmniAI
       @logger = logger
     end
 
+    # ActiveSupport::Notifications-compatible instrument.
+    #
+    # On http 6 the instrumentation feature drives every request through
+    # `around_request`, which (per http's own feature docs) "emits two events on
+    # every request: `start_request.http` before the request is made [and]
+    # `request.http` after the response is received". Both are delivered here as
+    # `instrument(name) { ... }` calls: the start event carries an empty block,
+    # and the request event's block wraps the exchange and returns the response.
+    # The block of the request event MUST be yielded and its value returned,
+    # otherwise the response is lost as `nil` (http uses the return value as the
+    # response). We log the request on the start event and the response on the
+    # request event. The event namespace is caller-configurable (the names are
+    # `start_request.#{namespace}` / `request.#{namespace}`), so #start_event?
+    # prefix-matches rather than comparing the full name.
+    #
+    # On http 5 this is only ever called without a block (for the start and
+    # error events); request/response logging there happens via #start / #finish.
+    #
     # @param name [String]
     # @param payload [Hash]
+    # @option payload [HTTP::Request] :request
+    # @option payload [HTTP::Response] :response
     # @option payload [Exception] :error
     def instrument(name, payload = {})
       error = payload[:error]
-      return unless error
+      @logger.error("#{name}: #{error.message}") if error
 
-      @logger.error("#{name}: #{error.message}")
+      return unless block_given?
+
+      if start_event?(name)
+        log_request(payload[:request])
+        yield payload
+      else
+        response = yield payload
+        log_response(payload[:response] || response)
+        response
+      end
     end
 
     # @param payload [Hash]
     # @option payload [HTTP::Request] :request
     def start(_, payload)
-      request = payload[:request]
-      @logger.info("#{request.verb.upcase} #{request.uri}")
+      log_request(payload[:request])
     end
 
     # @param payload [Hash]
     # @option payload [HTTP::Response] :response
     def finish(_, payload)
-      response = payload[:response]
+      log_response(payload[:response])
+    end
+
+  private
+
+    # @param name [String] the http instrumentation event name, e.g.
+    #   "start_request.http" (pre-flight) or "request.http" (the exchange).
+    #
+    # @return [Boolean] true for the pre-flight "start_..." event
+    def start_event?(name)
+      name.to_s.start_with?("start_")
+    end
+
+    # @param request [HTTP::Request, nil]
+    def log_request(request)
+      return unless request
+
+      @logger.info("#{request.verb.upcase} #{request.uri}")
+    end
+
+    # @param response [HTTP::Response, nil]
+    def log_response(response)
+      return unless response
+
       @logger.info("#{response.status.code} #{response.status.reason}")
     end
   end

data/lib/omniai/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.1
 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