omniai-google 3.14.0 → 3.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5954a8c865af0699193eec624f9ddbb6e7bb52f0df650d16a61ad3237b15aedd
-  data.tar.gz: 3e455a236f2c073735e44054c55489c93418252259fd556df734d38ea7895043
+  metadata.gz: 9fd43c08069868c8d20d91ac6e1028baf97643eda9018a0db146c73ce0828c15
+  data.tar.gz: 04ca6d4c4789b91c194abb44f8d2d178f1e65605644fe3c72a72824e8707a9e2
 SHA512:
-  metadata.gz: c99cb0f8e5d8e802ff247874ab5c4e4530fd5b91cadc617d506187125ed9603cc5468c09586f36f2ca2ddcde0549c7aba48d1b50285450a7d830b5c2fad3112b
-  data.tar.gz: d32ccfaf6210fade5a0a7dfaf4c868a9474880d440f4465b959966bc1085509df3d67e50795555402b7ad069da47dedf1c91b2f1c8666799f47a16eb6ac43b7b
+  metadata.gz: 3b2076e4c7f504e899015fbd0c8fb4f3290d347d2191051cdad1a6e079f45b6086bf8b6725693d073c45e02adf85bc43be7aace65a37fce282a163ed338596c6
+  data.tar.gz: ebf586d81abd71f7959f12f85159a27b3a5a53cd4966adcc2e05bec009341378fc306140ca0f94e129a3a4df1875ba2b5433e1b2b738e2c78c6a2eaf24ab0e87

data/README.md

@@ -118,6 +118,30 @@ end
 client.chat('Be poetic.', stream:)
 ```
 
+#### Max Output Tokens
+
+`max_tokens:` caps the response, mapping to Gemini's `generationConfig.maxOutputTokens`:
+
+```ruby
+client.chat("Summarize this page.", model: "gemini-3.7-flash", max_tokens: 8_000)
+```
+
+It can also be set globally, and a per-call value wins:
+
+```ruby
+OmniAI::Google.configure do |config|
+  config.chat_options[:max_tokens] = 8_000
+end
+```
+
+The value is passed through unchanged — no floor is imposed, so the number you ask for is the number that reaches the wire. When the cap is hit, `response.finish_reason.reason` is `:length`.
+
+**Size it as thinking headroom plus expected answer.** Unlike Anthropic's answer-only ceiling, Gemini spends this budget on thinking *before* emitting an answer. A cap sized to the expected answer alone gets consumed by thinking on any request the model reasons about:
+
+```
+max_tokens: 200  ->  finish_reason :length, 196 output tokens, 115 of them thinking, 81 characters of answer
+```
+
 #### Extended Thinking
 
 Gemini models support extended thinking, which shows the model's reasoning process.

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

@@ -18,11 +18,69 @@ module OmniAI
             end
           end
 
+          validate!
           @data
         end
 
       protected
 
+        # Google reports a post-200 failure as an `error` object in the stream, which
+        # `process_data!` otherwise copies into @data and returns as an empty success.
+        def validate!
+          error = @data["error"]
+          if error
+            raise StreamError.new("the stream carried an error: #{error_summary(error)}",
+              provider_message: error["message"])
+          end
+
+          # No candidates at all (a usageMetadata-only stream) is incomplete too.
+          candidates = @data["candidates"] || []
+          incomplete = candidates.select { |candidate| incomplete?(candidate) }
+          return unless candidates.empty? || incomplete.any?
+
+          raise IncompleteStreamError,
+            "the stream ended without a finish reason: #{candidates_summary(incomplete)}"
+        end
+
+        # Only thought-only-and-empty counts. A missing finishReason alone would also condemn
+        # an unterminated stream that did deliver an answer, and discarding a usable answer to
+        # retry is the more expensive mistake.
+        def incomplete?(candidate)
+          return false if candidate["finishReason"]
+
+          parts = candidate.dig("content", "parts") || []
+          parts.none? { |part| part["functionCall"] || answer_part?(part) }
+        end
+
+        # "" is truthy in Ruby, so an empty text part must not count as an answer.
+        def answer_part?(part)
+          !thought_part?(part) && !part["text"].to_s.strip.empty?
+        end
+
+        # Code and status only. Google's `message` can echo request content back, and consumers
+        # log these, so it is omitted for the same reason candidates_summary omits part text.
+        #
+        # @param error [Hash]
+        # @return [String]
+        def error_summary(error)
+          "code=#{error['code'].inspect} status=#{error['status'].inspect}"
+        end
+
+        # Structure only: consumers log these messages and part text may be sensitive.
+        #
+        # @param candidates [Array<Hash>]
+        # @return [String]
+        def candidates_summary(candidates)
+          return "candidates=0" if candidates.empty?
+
+          candidates.map.with_index do |candidate, index|
+            parts = candidate.dig("content", "parts") || []
+            "candidate=#{index} parts=#{parts.size} " \
+              "thought_parts=#{parts.count { |part| part['thought'] }} " \
+              "finish_reason=#{candidate['finishReason'].inspect}"
+          end.join("; ")
+        end
+
         # @yield [delta]
         # @yieldparam delta [OmniAI::Chat::Delta]
         #

data/lib/omniai/google/chat.rb

@@ -93,9 +93,15 @@ module OmniAI
           }.compact, json: payload)
       end
 
+      # `chat_options` is forwarded verbatim, so a key this class builds itself must be excluded or it is sent
+      # twice — and `max_tokens` is OmniAI's normalized name, not one Gemini knows. Left in, it reaches the
+      # wire as an unknown top-level field and the request fails with
+      # `Invalid JSON payload received. Unknown name "max_tokens"`. `#generation_config` consumes it and
+      # emits `maxOutputTokens` instead.
+      #
       # @return [Hash]
       def payload
-        OmniAI::Google.config.chat_options.merge({
+        OmniAI::Google.config.chat_options.except(:max_tokens).merge({
           system_instruction: @prompt.messages.find(&:system?)&.serialize(context:),
           contents: @prompt.messages.reject(&:system?).map { |message| message.serialize(context:) },
           tools:,
@@ -138,11 +144,26 @@ module OmniAI
 
         data[:temperature] = @temperature if @temperature
         data[:thinkingConfig] = thinking_config if @options[:thinking]
+        data[:maxOutputTokens] = max_tokens if max_tokens
 
         data = data.compact
         data unless data.empty?
       end
 
+      # A per-call `max_tokens:`, falling back to `config.chat_options[:max_tokens]` so a cap can also be set
+      # globally — the same precedence omniai-anthropic applies. The value is passed through unchanged: no
+      # floor is imposed, so the number a caller asks for is the number that reaches the wire.
+      #
+      # Note that Gemini spends this budget on thinking BEFORE emitting an answer, unlike Anthropic's
+      # answer-only ceiling. A cap sized to the expected answer alone will be consumed by thinking on any
+      # request the model reasons about, returning `finishReason: MAX_TOKENS` with little or no text. Size it
+      # as thinking headroom plus expected answer.
+      #
+      # @return [Integer, nil]
+      def max_tokens
+        @options[:max_tokens] || OmniAI::Google.config.chat_options[:max_tokens]
+      end
+
       # @return [String]
       def path
         "#{@client.path}/models/#{@model}:#{operation}"

data/lib/omniai/google/client.rb

@@ -121,9 +121,26 @@ module OmniAI
         !@credentials.nil?
       end
 
+      # Vertex AI is served from three host shapes under `googleapis.com`: the global `aiplatform`, a
+      # region-prefixed `<region>-aiplatform`, and the multi-region `aiplatform.<geo>.rep`. Only the first two
+      # contain the literal "aiplatform.googleapis.com", so a substring test misses the multi-region endpoint.
+      #
+      # Deliberately wider than those three shapes: any labels are accepted between `aiplatform` and
+      # `googleapis.com`, so a future multi-region shape needs no change here. Everything it accepts is still
+      # under `googleapis.com`.
+      #
+      # Matched against the parsed hostname rather than the raw host, so a proxy whose path or query merely
+      # mentions a Vertex host is not treated as Vertex. A host given with no scheme has no hostname to parse, so
+      # the raw value is matched instead; the pattern is anchored, which keeps that safe — note that a schemeless
+      # host carrying a path therefore does not match.
+      VERTEX_HOSTNAME = /\A(?:[a-z0-9-]+-)?aiplatform(?:\.[a-z0-9-]+)*\.googleapis\.com\z/
+
       # @return [Boolean]
       def vertex?
-        @host.include?("aiplatform.googleapis.com")
+        hostname = URI.parse(@host).hostname || @host
+        VERTEX_HOSTNAME.match?(hostname.downcase)
+      rescue URI::InvalidURIError
+        false
       end
 
     private

data/lib/omniai/google/incomplete_stream_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Google
+    # Raised when a stream ends with no `finishReason` and produced nothing but thinking.
+    # Rescue StreamError to catch this and stream errors together. `#provider_message` is
+    # always nil here -- there is no provider error to carry.
+    class IncompleteStreamError < StreamError; end
+  end
+end

data/lib/omniai/google/stream_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Google
+    # Raised when a streamed generation does not complete.
+    #
+    # Deliberately has no `#response`: the request returned 200 and the failure arrived inside
+    # the stream. Consumers branch on that to decide whether to retry.
+    class StreamError < OmniAI::Error
+      # Google's own explanation of the failure, verbatim.
+      #
+      # Named for what it holds rather than borrowing `value` from FinishReason, which is a
+      # provider enum rather than prose. Kept off `#message` because consumers log that and
+      # this text can echo request content -- a deliberate departure from HTTPError, which puts
+      # the whole response body into its message.
+      #
+      # @return [String, nil]
+      attr_reader :provider_message
+
+      # @param message [String, nil]
+      # @param provider_message [String, nil]
+      def initialize(message = nil, provider_message: nil)
+        @provider_message = provider_message
+        super(message)
+      end
+    end
+  end
+end

data/lib/omniai/google/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAI
   module Google
-    VERSION = "3.14.0"
+    VERSION = "3.17.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniai-google
 version: !ruby/object:Gem::Version
-  version: 3.14.0
+  version: 3.17.0
 platform: ruby
 authors:
 - Kevin Sylvestre
@@ -122,6 +122,8 @@ files:
 - lib/omniai/google/config.rb
 - lib/omniai/google/credentials.rb
 - lib/omniai/google/embed.rb
+- lib/omniai/google/incomplete_stream_error.rb
+- lib/omniai/google/stream_error.rb
 - lib/omniai/google/transcribe.rb
 - lib/omniai/google/transcribe_helpers.rb
 - lib/omniai/google/upload.rb