omniai-google 3.19.0 → 3.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4c5367190abf998fe07c957ea0bcb092660540d96e6a81bbe82b1f67e751895
-  data.tar.gz: 1d37b3a65b76667d647f35091b432cfa4c94458d222a1d43120d509145045d94
+  metadata.gz: bdc1ade66e25bb33aca449a360b70e9e0df885996022ce6ed6bc8350137cf69c
+  data.tar.gz: f54782298b7bd730164e437564ac3184b23eeebb5df7779c429d9cc978d68983
 SHA512:
-  metadata.gz: 4227aa6e92bc19605188ba27e0d5b3b33672f4d66b1cbfdc14a0d17c47ad205f86e893d131f9986c830df21135d778a97e962f1575c67adf5d72c5cac2d6b3ae
-  data.tar.gz: eb585c514a31d9fa8577968ff5e558a9b9da3762d7c316e4528dfecd7e60890f408adf5172d94a2b7981e3382d00c75177b3a2c6f092a371f1685037ec6dea06
+  metadata.gz: 0d7b57da0258da82684ac694c35d056b77b60ac2edbf6b3146c674f84b2906d42457915672276a5c19a8ea24ec6aa7108359e224ce33660e2c5eb6bbb110b692
+  data.tar.gz: b577e9ce548f3cae58d0fbffea9a933c648855f48a5455c277f04d77fd842b839de095e767da1f235f648994fe265fc7814d9b7acfb1412d91d91c4b5667349d

data/README.md

@@ -58,6 +58,30 @@ OmniAI::Google.configure do |config|
 end
 ```
 
+#### Vertex Locations per Model
+
+No single Vertex location serves every model. To route each model to its own location, set `locations`; the host is
+derived from the location the way Google's SDKs do it (`global`, the `us` / `eu` multi-regions, or a single region):
+
+```ruby
+OmniAI::Google.configure do |config|
+  config.credentials = File.open("./credentials.json")
+  config.project_id = '...'
+  config.locations = {
+    'gemini-3.8-flash' => 'us',              # https://aiplatform.us.rep.googleapis.com
+    'gemini-2.5-flash' => 'us-central1',     # https://us-central1-aiplatform.googleapis.com
+    'gemini-embedding-001' => 'us-central1',
+    'chirp_3' => 'us',
+  }
+end
+```
+
+- Applies to chat (including streaming), embed, transcribe and live. A mapped location is used as given.
+- A model missing from the map raises `OmniAI::Google::UnknownLocationError` (with `#model`) before any request.
+  List every model you call, including any default you rely on (`Chat::DEFAULT_MODEL`, `Embed::DEFAULT_MODEL`,
+  `Transcribe::DEFAULT_MODEL`).
+- A client built with an explicit `host:` or `location_id:` ignores the map.
+
 **Note for Transcription**: When using transcription features, ensure your service account has the necessary permissions for Google Cloud Speech-to-Text API and Google Cloud Storage (for automatic file uploads). See the [GCS Setup](#gcs-setup-for-transcription) section below for detailed configuration.
 
 Credentials may be configured using:
@@ -344,6 +368,36 @@ client.transcribe("audio.mp3", model: OmniAI::Google::Transcribe::Model::CHIRP)
 
 [Google Speech-to-Text API Reference](https://cloud.google.com/speech-to-text/docs)
 
+#### Gemini Transcribe
+
+`gemini-3.5-transcribe` is a Gemini model served by Vertex `generateContent`, not Speech-to-Text, so it needs Vertex
+credentials. Pass it as the model; the Chirp models above are unaffected.
+
+```ruby
+transcription = client.transcribe("interview.wav", model: OmniAI::Google::Transcribe::Model::GEMINI_3_5_TRANSCRIBE)
+transcription.text
+
+# Speaker labels per utterance (experimental, up to 8 speakers)
+transcription = client.transcribe("interview.wav", model: "gemini-3.5-transcribe", diarization: true, format: "verbose_json")
+transcription.segments # => [{ "id" => 0, "text" => "...", "speaker" => "spk:0" }, ...]
+
+# Language hints and custom vocabulary (up to 1,000 terms); the language is auto-detected when omitted
+client.transcribe("interview.wav", model: "gemini-3.5-transcribe", language: "es-US", vocabulary: %w[ibuprofeno])
+
+# Word times (experimental, off by default; see the caveat below)
+client.transcribe("interview.wav", model: "gemini-3.5-transcribe", word_timestamps: true, format: "verbose_json")
+```
+
+- **Location:** served from `global` and the `us` / `eu` multi-regions, never a single region. A zonal `location_id`
+  maps to its multi-region (`us` by default, `eu` for `eu*` / `europe*`); `global` is kept.
+- **Input:** wav, mp3, flac, ogg, webm, m4a or aiff (detected from the bytes), or a `gs://` URI. Files over 10 MB are
+  uploaded to the `<project_id>-speech-audio` bucket and deleted afterwards.
+- **Length:** Google caps a file at 15 minutes when diarization or timestamps are on, so split longer recordings.
+- **Word timestamps can drop speech.** In live tests on a two-speaker, 8-second clip (2026-10-15), `word_timestamps: true`
+  returned only the first word of the answer, and with `diarization: true` as well it dropped the whole first utterance.
+  Google labels both features experimental and warns that word timestamps degrade accuracy. `diarization:` alone
+  returned the complete transcript but no times.
+
 #### GCS Setup for Transcription
 
 For transcription to work properly with automatic file uploads, you need to set up Google Cloud Storage and configure the appropriate permissions.
@@ -426,6 +480,59 @@ client.transcribe("audio.mp3", bucket_name: "my-custom-audio-bucket")
 - Audio files are automatically deleted after successful transcription
 - If transcription fails, temporary files may remain and should be cleaned up manually
 
+### Live
+
+A Gemini Live session (Vertex `BidiGenerateContent` over a WebSocket): stream microphone audio in, get speech,
+transcripts and tool calls back. Vertex credentials only.
+
+```ruby
+client = OmniAI::Google::Client.new(
+  project_id: "...", credentials: "...",
+  location_id: "us", host: "https://aiplatform.us.rep.googleapis.com" # gemini-3.8-live: us, eu or us-central1 (not global)
+)
+
+session = client.live(
+  model: OmniAI::Google::Live::Model::GEMINI_3_8_LIVE,
+  system: "You are an intake assistant...",
+  tools: [RecordAnswer.new],       # OmniAI::Tool; run automatically, results sent back
+  tool_behavior: :blocking,        # default; or :non_blocking, or { "flag" => :non_blocking }
+  voice: "Kore",                   # optional
+  vad: { silence_ms: 800 },        # optional
+  compression: { trigger_tokens: 10_000, target_tokens: 5_000 } # optional (or true): see Limits
+) do |event|
+  case event
+  when OmniAI::Google::Live::Event::Audio then speaker.write(event.data) # PCM16, 24 kHz, mono
+  when OmniAI::Google::Live::Event::Transcript then caption(event.role, event.text) # :user / :model
+  when OmniAI::Google::Live::Event::Interrupted then speaker.flush
+  when OmniAI::Google::Live::Event::GoAway then reconnect_within(event.time_left)
+  when OmniAI::Google::Live::Event::Usage then track(event.usage, event.data) # data has per-modality counts
+  when OmniAI::Google::Live::Event::Closed then reconnect_or_finish(event.code, event.error)
+  end
+end
+
+session.send_audio(pcm16_16khz) # from any thread
+session.send_text("We are at question 12; answers so far: ...") # e.g. to re-seed after reconnecting
+session.close
+```
+
+- **Threads:** each session has one socket and one reader thread. Events are yielded, and tools run, on that thread;
+  `send_*` may be called from any thread. A send that blocks longer than `write_timeout:` (default 5 s) closes the
+  session and raises `Live::TimeoutError`, as does a connect (TCP + TLS) slower than 10 s. An idle connection is pinged
+  every 15 s; with no answer in 10 s it is dropped, so a silently dead path still ends the session. The session always
+  ends with exactly one `Event::Closed`, including when the socket drops or your handler raises (`event.error`).
+- **Tools:** a raising tool answers the model with its error class only, and the session carries on.
+- **Limits (Google):** a connection lasts about 10 minutes, and an audio-only session 15 minutes without
+  `compression:`. Measured live at `us` (2026-10-15): `GoAway` arrived at 9 min (`time_left` 30 s, not the 60 s
+  Google documents) and the server closed with 1000 at 9.5 min. Reconnect when `GoAway` arrives, not on a timer: the documented numbers are off.
+- **Cost:** every turn re-bills the whole context. `compression:` bounds it: in a live test with a 10,000-token trigger
+  and 5,000-token target, `promptTokenCount` dropped from about 8,500 to 3,400 whenever the next turn would pass the
+  trigger (a sawtooth instead of linear growth; 51% fewer prompt tokens over 12 turns). The oldest turns are dropped,
+  so keep anything the model must remember in your own state and re-send it when needed. The gem does not reconnect: open a new session and re-seed it
+  (`resumption:` takes Google's resumption handles if you prefer that).
+- **Privacy:** the gem never logs or raises audio, transcripts or tool arguments. `Live::Error#message` carries codes and
+  ids only; Google's close reason is on `#reason`, and `Event::Closed#inspect` leaves it out. A server frame that fails
+  to parse closes the session with a `Live::Error` naming only the exception class.
+
 ### Embed
 
 Text can be converted into a vector embedding for similarity comparison usage via:

data/lib/omniai/google/chat.rb

@@ -76,6 +76,11 @@ module OmniAI
         context.deserializers[:thinking] = ThinkingSerializer.method(:deserialize)
       end
 
+      # `client` is swapped for `client.for_model(model)`, so `locations` routes the request.
+      def initialize(prompt = nil, client:, model:, **, &)
+        super(prompt, client: client.for_model(model), model:, **, &)
+      end
+
     protected
 
       # @return [Context]

data/lib/omniai/google/client.rb

@@ -20,6 +20,10 @@ module OmniAI
     #
     #   client = OmniAI::Google::Client.new
     class Client < OmniAI::Client
+      # Marks `host` / `location_id` as not passed, so an explicit value can take precedence over `locations`.
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
       # @!attribute [rw] version
       #   @return [String, nil]
       attr_accessor :version
@@ -32,28 +36,56 @@ module OmniAI
       # @param version [String] default is `OmniAI::Google.config.version`
       # @param logger [Logger] default is `OmniAI::Google.config.logger`
       # @param timeout [Integer] default is `OmniAI::Google.config.timeout`
+      # @param locations [Hash{String => String}, nil] default is `OmniAI::Google.config.locations`; ignored when
+      #   `host` or `location_id` is passed
       def initialize(
         api_key: OmniAI::Google.config.api_key,
         project_id: OmniAI::Google.config.project_id,
-        location_id: OmniAI::Google.config.location_id,
+        location_id: UNSET,
         credentials: OmniAI::Google.config.credentials,
         logger: OmniAI::Google.config.logger,
-        host: OmniAI::Google.config.host,
+        host: UNSET,
         version: nil,
-        timeout: OmniAI::Google.config.timeout
+        timeout: OmniAI::Google.config.timeout,
+        locations: OmniAI::Google.config.locations
       )
         if api_key.nil? && credentials.nil?
           raise(ArgumentError, "either an `api_key` or `credentials` must be provided")
         end
 
+        pinned = !(UNSET.equal?(host) && UNSET.equal?(location_id))
+        @locations = locations unless pinned
+        host = OmniAI::Google.config.host if UNSET.equal?(host)
+        location_id = OmniAI::Google.config.location_id if UNSET.equal?(location_id)
+
         super(api_key:, host:, logger:, timeout:)
 
         @project_id = project_id
         @location_id = location_id
         @credentials = Credentials.parse(credentials)
+        @version_override = version
         @version = version || default_version
       end
 
+      # A copy of this client pointed at the model's location in `locations`, or this client when no map applies.
+      #
+      # @param model [String]
+      #
+      # @raise [UnknownLocationError] when the map has no entry for the model
+      #
+      # @return [Client]
+      def for_model(model)
+        return self if @locations.nil?
+
+        location_id = @locations.fetch(model) { raise UnknownLocationError, model }
+        dup.tap { |client| client.locate!(location_id) }
+      end
+
+      # @return [Boolean] true for a client returned by `#for_model`
+      def located?
+        @located || false
+      end
+
       # @raise [OmniAI::Error]
       #
       # @param messages [String] optional
@@ -96,8 +128,20 @@ module OmniAI
       # @param model [String] optional
       # @param language [String, Array<String>] optional - language codes for transcription
       # @param format [Symbol] optional - :json or :verbose_json
-      def transcribe(input, model: Transcribe::DEFAULT_MODEL, language: nil, format: nil)
-        Transcribe.process!(input, model:, language:, format:, client: self)
+      # @param options [Hash] Gemini transcribe models only: `diarization:`, `word_timestamps:`, `vocabulary:`
+      def transcribe(input, model: Transcribe::DEFAULT_MODEL, language: nil, format: nil, **)
+        Transcribe.process!(input, model:, language:, format:, client: self, **)
+      end
+
+      # Opens a Gemini Live session (Vertex only). See `OmniAI::Google::Live#initialize` for the options.
+      #
+      # @raise [OmniAI::Google::Live::Error]
+      #
+      # @yieldparam event [OmniAI::Google::Live::Event::*]
+      #
+      # @return [OmniAI::Google::Live]
+      def live(model: Live::DEFAULT_MODEL, **, &)
+        Live.open(client: self, model:, **, &)
       end
 
       # @return [String]
@@ -143,6 +187,16 @@ module OmniAI
         false
       end
 
+    protected
+
+      # @param location_id [String]
+      def locate!(location_id)
+        @location_id = location_id
+        @host = Vertex.host(location_id)
+        @version = @version_override || Config::Version::STABLE
+        @located = true
+      end
+
     private
 
       # Vertex AI serves `v1`; the Gemini API serves `v1beta`. `OmniAI::Google.config.version` derives from the

data/lib/omniai/google/config.rb

@@ -19,6 +19,12 @@ module OmniAI
       #   @return [String, nil]
       attr_accessor :location_id
 
+      # @!attribute [rw] locations
+      #   Vertex location per model, e.g. `{ "gemini-3.8-flash" => "us" }`. When set, each request derives its host
+      #   from the model's location, and a model missing from the map raises `UnknownLocationError`.
+      #   @return [Hash{String => String}, nil]
+      attr_accessor :locations
+
       # @param api_key [String, nil] optional - defaults to `ENV['GOOGLE_API_KEY']`
       # @param project_id [String, nil] optional - defaults to `ENV['GOOGLE_PROJECT_ID']`
       # @param location_id [String, nil] optional - defaults to `ENV['GOOGLE_LOCATION_ID']`

data/lib/omniai/google/embed.rb

@@ -72,6 +72,11 @@ module OmniAI
         context.deserializers[:usage] = USAGE_METADATA_DESERIALIZER
       end
 
+      # `client` is swapped for `client.for_model(model)`, so `locations` routes the request.
+      def initialize(input, client:, model:, **)
+        super(input, client: client.for_model(model), model:, **)
+      end
+
     protected
 
       # Determines which endpoint to use based on client and model configuration.
@@ -155,7 +160,7 @@ module OmniAI
 
       # @return [String]
       def path
-        "/#{@client.path}/models/#{@model}:#{PROCEDURES[endpoint]}"
+        "#{@client.path}/models/#{@model}:#{PROCEDURES[endpoint]}"
       end
     end
   end

data/lib/omniai/google/live/connection.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "socket"
+require "websocket/driver"
+
+module OmniAI
+  module Google
+    class Live
+      # A WebSocket client over TCP or TLS, driven by websocket-driver with one reader thread per connection.
+      #
+      # Callbacks run on the reader thread. Writes may come from any thread: they are serialized by a mutex and bounded
+      # by `write_timeout`, so a stalled peer can't block the caller indefinitely. An idle connection is pinged, so a
+      # silently dropped path is noticed. `on_close` is called exactly once, whether the peer closes, the socket hits
+      # EOF or errors, a write or pong times out, or a callback raises.
+      class Connection
+        CONNECT_TIMEOUT = 10 # seconds, TCP and TLS together
+        CLOSE_TIMEOUT = 2 # seconds
+        PING_INTERVAL = 15 # seconds without a frame before pinging
+        PONG_TIMEOUT = 10 # seconds
+        READ_CHUNK = 16_384 # bytes
+
+        class ConnectTimeout < StandardError; end
+        class WriteTimeout < StandardError; end
+        class PongTimeout < StandardError; end
+
+        # @return [String]
+        attr_reader :url
+
+        # @param url [String] a ws:// or wss:// URL
+        # @param headers [Hash] sent with the upgrade request
+        # @param write_timeout [Numeric] seconds
+        # @param on_open [Proc] called with no arguments
+        # @param on_message [Proc] called with the payload String
+        # @param on_close [Proc] called with (code, reason, error)
+        def initialize(url:, headers:, write_timeout:, on_open:, on_message:, on_close:)
+          @url = url
+          @headers = headers
+          @write_timeout = write_timeout
+          @on_open = on_open
+          @on_message = on_message
+          @on_close = on_close
+          @mutex = Mutex.new
+          @pending = []
+          @finished = false
+        end
+
+        # @raise [ConnectTimeout]
+        def connect
+          @io = open_socket
+          @wake_reader, @wake_writer = IO.pipe # for abort!: on Linux, closing a socket doesn't interrupt a select on it
+          @driver = WebSocket::Driver.client(self, binary_data_format: :string)
+          @headers.each { |name, value| @driver.set_header(name, value) }
+          @driver.on(:open) { @pending << [:open] }
+          @driver.on(:message) { |event| @pending << [:message, event.data] }
+          @driver.on(:close) { |event| @pending << [:close, event.code, event.reason] }
+          @mutex.synchronize { @driver.start }
+          @reader = Thread.new { read_loop }
+          @reader.name = "omniai-google-live"
+          @reader.report_on_exception = false
+        rescue StandardError
+          [@io, @wake_reader, @wake_writer].compact.each { |io| close_quietly(io) } unless @reader
+          raise
+        end
+
+        # @return [Boolean]
+        def open?
+          !@finished && !@aborted
+        end
+
+        # @param payload [String]
+        #
+        # @raise [WriteTimeout]
+        def send_text(payload)
+          @mutex.synchronize { @driver.text(payload) }
+        rescue WriteTimeout => e
+          abort!(e)
+          raise
+        end
+
+        # Sends a close frame and waits briefly for the peer's reply before dropping the socket. Called from a callback
+        # (the reader thread itself), it only sends the frame: the reader finishes when the reply arrives.
+        def close
+          return if @finished || @reader.nil?
+
+          begin
+            @mutex.synchronize { @driver.close }
+          rescue WriteTimeout, IOError, SystemCallError
+            nil
+          end
+          return if Thread.current == @reader
+
+          abort! unless @reader.join(CLOSE_TIMEOUT)
+          @reader.join(CLOSE_TIMEOUT)
+        end
+
+        # Called by websocket-driver (under the mutex) for every outgoing frame.
+        #
+        # @param data [String]
+        def write(data)
+          deadline = monotonic + @write_timeout
+          data = data.b
+          until data.empty?
+            result = @io.write_nonblock(data, exception: false)
+            case result
+            when :wait_writable then wait!(nil, [@io.to_io], deadline) { write_timeout }
+            when :wait_readable then wait!([@io.to_io], nil, deadline) { write_timeout }
+            else data = data.byteslice(result..)
+            end
+          end
+        end
+
+      private
+
+        # @return [WriteTimeout]
+        def write_timeout
+          WriteTimeout.new("write timed out after #{@write_timeout}s")
+        end
+
+        # @return [Socket, OpenSSL::SSL::SSLSocket]
+        def open_socket
+          uri = URI.parse(@url)
+          deadline = monotonic + CONNECT_TIMEOUT
+          tcp = begin
+            Socket.tcp(uri.host, uri.port, connect_timeout: CONNECT_TIMEOUT)
+          rescue Errno::ETIMEDOUT, IO::TimeoutError
+            raise ConnectTimeout, "connect timed out after #{CONNECT_TIMEOUT}s"
+          end
+          return tcp unless uri.scheme == "wss"
+
+          handshake(tcp, uri.host, deadline)
+        end
+
+        # @return [OpenSSL::SSL::SSLSocket]
+        def handshake(tcp, host, deadline)
+          context = OpenSSL::SSL::SSLContext.new
+          context.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER)
+          ssl = OpenSSL::SSL::SSLSocket.new(tcp, context)
+          ssl.hostname = host
+          ssl.sync_close = true
+          timeout = -> { ConnectTimeout.new("connect timed out after #{CONNECT_TIMEOUT}s") }
+          loop do
+            case ssl.connect_nonblock(exception: false)
+            when :wait_readable then wait!([tcp], nil, deadline, &timeout)
+            when :wait_writable then wait!(nil, [tcp], deadline, &timeout)
+            else return ssl
+            end
+          end
+        rescue StandardError
+          tcp.close
+          raise
+        end
+
+        def read_loop
+          loop do
+            data = read_chunk
+            @ping_at = nil
+            events = @mutex.synchronize do
+              @driver.parse(data)
+              @pending.slice!(0..)
+            end
+            events.each { |event| dispatch(*event) }
+            break if @finished
+          end
+        rescue EOFError
+          finish(nil, nil, @abort_error)
+        rescue IOError, SystemCallError, OpenSSL::SSL::SSLError => e
+          finish(nil, nil, @abort_error || e)
+        rescue StandardError => e # a callback raised, or a ping went unanswered
+          finish(nil, nil, e)
+        ensure
+          finish(nil, nil, @abort_error)
+        end
+
+        # Waits for data, pinging when idle for PING_INTERVAL. Any frame (a pong included) counts as an answer.
+        #
+        # @raise [PongTimeout, EOFError]
+        #
+        # @return [String]
+        def read_chunk
+          loop do
+            result = @io.read_nonblock(READ_CHUNK, exception: false)
+            case result
+            when :wait_readable then idle([@io.to_io], nil)
+            when :wait_writable then idle(nil, [@io.to_io])
+            when nil then raise EOFError
+            else return result
+            end
+          end
+        end
+
+        def idle(readers, writers)
+          timeout = @ping_at ? @ping_at + PONG_TIMEOUT - monotonic : PING_INTERVAL
+          ready = IO.select([*readers, @wake_reader], writers, nil, timeout) if timeout.positive?
+          raise IOError, "aborted" if @aborted
+          return if ready
+
+          raise PongTimeout, "no pong within #{PONG_TIMEOUT}s" if @ping_at
+
+          @ping_at = monotonic
+          @mutex.synchronize { @driver.ping }
+        end
+
+        def dispatch(type, *args)
+          case type
+          when :open then @on_open.call
+          when :message then @on_message.call(args.first)
+          when :close then finish(args[0], args[1], nil)
+          end
+        end
+
+        # Drops the socket; the reader thread then finishes with `error`.
+        def abort!(error = nil)
+          @abort_error ||= error
+          @aborted = true
+          close_quietly(@io)
+          @wake_writer.write_nonblock(".", exception: false)
+        rescue IOError
+          nil # already finished
+        end
+
+        def finish(code, reason, error)
+          return if @finished
+
+          @finished = true
+          [@io, @wake_reader, @wake_writer].each { |io| close_quietly(io) }
+          begin
+            @on_close.call(code, reason, error)
+          rescue StandardError
+            nil
+          end
+        end
+
+        def close_quietly(io)
+          io.close
+        rescue IOError, SystemCallError
+          nil
+        end
+
+        # @yieldreturn [StandardError] raised once the deadline passes
+        def wait!(readers, writers, deadline)
+          remaining = deadline - monotonic
+          return if remaining.positive? && IO.select(readers, writers, nil, remaining)
+
+          raise yield
+        end
+
+        def monotonic
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/omniai/google/live/event.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Google
+    class Live
+      # Events yielded by a Live session, on its reader thread.
+      module Event
+        # Model speech: raw PCM16 (24 kHz, mono, little-endian) bytes.
+        Audio = Data.define(:data, :mime_type) do
+          def inspect = "#<#{self.class.name} bytes=#{data.bytesize} mime_type=#{mime_type}>"
+        end
+
+        # Model text (only when the session asks for text responses).
+        Text = Data.define(:text)
+
+        # A transcript fragment of the user's (`:user`) or the model's (`:model`) speech.
+        Transcript = Data.define(:role, :text, :finished)
+
+        # @!attribute calls [Array<FunctionCall>]
+        ToolCall = Data.define(:calls)
+        FunctionCall = Data.define(:id, :name, :arguments)
+        ToolCallCancellation = Data.define(:ids)
+
+        # The user spoke over the model; drop any audio still queued for playback.
+        Interrupted = Data.define
+        GenerationComplete = Data.define
+        TurnComplete = Data.define
+
+        # Speech start/end detected by the server; `offset` is seconds into the session's input audio.
+        VoiceActivity = Data.define(:type, :offset)
+
+        # The server will end the connection in `time_left` seconds.
+        GoAway = Data.define(:time_left)
+        ResumptionUpdate = Data.define(:handle, :resumable)
+
+        # @!attribute usage [OmniAI::Chat::Usage] (`output_tokens` includes thinking)
+        # @!attribute data [Hash] the raw usageMetadata, with per-modality token details
+        Usage = Data.define(:usage, :data)
+
+        # The session ended. `code` is nil when the connection dropped without a close frame; `error` is set when it
+        # ended because of an exception (socket error, write timeout, or a raising handler). Google's close `reason`
+        # can echo request content, so `inspect` leaves it out.
+        Closed = Data.define(:code, :reason, :error) do
+          def inspect = "#<#{self.class.name} code=#{code.inspect} error=#{error&.class.inspect}>"
+        end
+      end
+    end
+  end
+end