omniai 3.7.1 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e22534811cc346b74927ec47382420e86faee449ff730cbb0665d30a714cd872
-  data.tar.gz: 1c3e58ad36506a2564563c46a700e8be04731b7266d8008bbd63bcc22d9cfa64
+  metadata.gz: 79d29d3011d03634e81f70e37b83af802c8881afb6920769a2b49e165f244735
+  data.tar.gz: 15b2e1cc6af34b9692f2d0628c8a94754f7d2dafc6b545bd739c2d4d88fe8141
 SHA512:
-  metadata.gz: ea3efdf811897d5fff8f55b0e4051b71f151d077230518b139fde0ef38656c6b784f9aafcfccb43c692fe85a102b47d0ca41c8696af767294b1a2270dfeee5fa
-  data.tar.gz: f3e87e1dd51ca72ec1d8706d3833a06c10b65947fdaf1e9a375518ca2b3d78f03a43af1c2869de1e84fb1c5cd77226ecbd5aa45fa7092f84691f0ea5f5afd183
+  metadata.gz: d3d3636fc343966d21f40c7b09b566bcc3a3375e5d52e3b700f9d9db6e69194cb6d657cc25f721216ece7f8fa3d775216ca1baaaeb527b865d16be9398aaee47
+  data.tar.gz: bb45ac481dd2b27edf8e62ba66667ed1d17e77b4c44ab7505b17af0b78db4e8c7550d25fd67b8e5556b97e8455a8c65db443fcfb52abc3a2c3c4130904fafb65

data/README.md

@@ -545,6 +545,28 @@ end
 client.chat('What is the weather in "London" in Celsius and "Paris" in Fahrenheit?', tools: [WeatherTool.new])
 ```
 
+#### Per-Round Usage
+
+A tool-call chain makes one request per round, but only the final `Response` is returned. Pass `on_response:` to receive each round's `Response` as it completes, before that round's tool calls run. It fires for single-round chats too and is independent of `stream:`.
+
+Usage then survives an abort. When a stream block or a tool raises mid-chain, `process!` unwinds without returning a `Response`, but the rounds already handed over are still accounted for:
+
+```ruby
+rounds = []
+
+stream = proc do |chunk|
+  raise TooManyRounds if rounds.length >= 20
+
+  print(chunk.text)
+end
+
+begin
+  client.chat(prompt, tools:, stream:, on_response: proc { |round| rounds << round })
+rescue TooManyRounds
+  rounds.filter_map(&:usage).sum { |usage| usage.input_tokens.to_i + usage.output_tokens.to_i }
+end
+```
+
 #### Extended Thinking / Reasoning
 
 Some models support extended thinking or reasoning capabilities. OmniAI provides a unified `thinking:` option that works across all supported providers:
@@ -578,6 +600,30 @@ client.chat("Solve this step by step: What is 123 * 456?", thinking: true, strea
 | Google | `thinking: true` | Requires Gemini 2.0+ with thinking enabled |
 | OpenAI | `thinking: true` or `thinking: { effort: "high" }` | Requires o1/o3 models |
 
+#### Thinking Token Accounting
+
+Reasoning tokens are billable. `OmniAI::Chat::Usage#thinking_tokens` reports how many of a response's output tokens were internal reasoning:
+
+```ruby
+response = client.chat("What is 25 * 25?", thinking: true)
+
+response.usage.output_tokens   # => 1424 — billable output, reasoning included
+response.usage.thinking_tokens # => 840  — the reasoning subset of the above
+```
+
+`thinking_tokens` is always a **subset** of `output_tokens`, never an addition to it. Adding the two together double counts.
+
+It is `nil` when the provider reported no breakdown, which is deliberately distinct from `0` (the provider reported that no reasoning occurred). Each provider gem reads its own vocabulary:
+
+| Provider | Populated | Read from |
+|----------|-----------|-----------|
+| omniai-google >= 3.12 | yes | `thoughtsTokenCount` |
+| omniai-anthropic >= 3.6 | yes | `usage.output_tokens_details.thinking_tokens` |
+| omniai-openai >= 3.2 | yes | `usage.output_tokens_details.reasoning_tokens` (Responses API) |
+| omniai-mistral | no | no breakdown reported |
+
+Note also that `total_tokens` may exceed `input_tokens + output_tokens` — providers count buckets OmniAI does not model, such as cached input and tool-use prompts — and may be `nil` where a provider reports no total. The reported total is authoritative and is never recomputed from the parts.
+
 ### 🎤 Speech to Text
 
 Clients that support transcribe (e.g. OpenAI w/ "Whisper") convert recordings to text via the following calls:

data/lib/omniai/chat/response.rb

@@ -153,20 +153,30 @@ module OmniAI
       # Returns aggregated usage across all responses in the chain.
       # Walks the parent chain and sums all token counts.
       #
+      # `total_tokens` prefers each response's provider-reported total and only falls back to `input + output` for
+      # responses where the provider reported none. Summing the reported totals matters wherever a provider counts
+      # tokens that are neither input nor output — Google's `totalTokenCount` includes thinking tokens, so
+      # recomputing unconditionally would discard them.
+      #
+      # Known limitation: Anthropic reports no total at all, so its contribution is always the derived
+      # `input + output`, which excludes `cache_creation_input_tokens` and `cache_read_input_tokens`. An aggregate
+      # spanning Anthropic responses therefore understates cache-heavy conversations.
+      #
       # @return [Usage, nil]
       def total_usage
-        chain = response_chain
-        usages = chain.map(&:usage).compact
+        usages = response_chain.map(&:usage).compact
         return nil if usages.empty?
 
-        input_tokens = usages.sum { |u| u.input_tokens || 0 }
-        output_tokens = usages.sum { |u| u.output_tokens || 0 }
+        input_tokens = usages.sum { |usage| usage.input_tokens || 0 }
+        output_tokens = usages.sum { |usage| usage.output_tokens || 0 }
+        total_tokens = usages.sum do |usage|
+          usage.total_tokens || ((usage.input_tokens || 0) + (usage.output_tokens || 0))
+        end
+
+        thinking = usages.filter_map(&:thinking_tokens)
+        thinking_tokens = thinking.sum unless thinking.empty?
 
-        Usage.new(
-          input_tokens:,
-          output_tokens:,
-          total_tokens: input_tokens + output_tokens
-        )
+        Usage.new(input_tokens:, output_tokens:, total_tokens:, thinking_tokens:)
       end
     end
   end

data/lib/omniai/chat/usage.rb

@@ -3,28 +3,52 @@
 module OmniAI
   class Chat
     # The usage of a chat in terms of tokens (input / output / total).
+    #
+    # Two invariants hold across every provider:
+    #
+    # - `thinking_tokens` is a *subset* of `output_tokens`, never an addition to it. Providers either fold reasoning
+    #   into their output count already (reporting the breakdown separately) or report it separately and have it
+    #   added in by their own serializer. Adding `thinking_tokens` to `output_tokens` double counts.
+    # - `total_tokens` may exceed `input_tokens + output_tokens`. Providers count buckets this class does not model
+    #   — cached input, tool-use prompts — so the reported total is authoritative and is never recomputed from the
+    #   parts. It may also be `nil`: some providers report no total at all.
+    #
+    # Provider-specific vocabulary is read by that provider's own `:usage` deserializer, not here. This class reads
+    # only its own keys and the flat OpenAI-compatible aliases the base client speaks.
     class Usage
-      # @return [Integer]
+      # @return [Integer, nil]
       attr_accessor :input_tokens
 
-      # @return [Integer]
+      # @return [Integer, nil]
       attr_accessor :output_tokens
 
-      # @return [Integer]
+      # @return [Integer, nil]
       attr_accessor :total_tokens
 
-      # @param input_tokens [Integer]
-      # @param output_tokens [Integer]
-      # @param total_tokens [Integer]
-      def initialize(input_tokens:, output_tokens:, total_tokens:)
+      # The subset of `output_tokens` a provider attributes to internal reasoning ("thinking"). `nil` when the
+      # provider does not report a breakdown — which is distinct from `0`, meaning the provider reported that no
+      # reasoning occurred.
+      #
+      # @return [Integer, nil]
+      attr_accessor :thinking_tokens
+
+      # @param input_tokens [Integer, nil]
+      # @param output_tokens [Integer, nil]
+      # @param total_tokens [Integer, nil]
+      # @param thinking_tokens [Integer, nil] optional
+      def initialize(input_tokens:, output_tokens:, total_tokens:, thinking_tokens: nil)
         @input_tokens = input_tokens
         @output_tokens = output_tokens
         @total_tokens = total_tokens
+        @thinking_tokens = thinking_tokens
       end
 
       # @return [String]
       def inspect
-        "#<#{self.class.name} input_tokens=#{input_tokens} output_tokens=#{output_tokens} total_tokens=#{total_tokens}>"
+        text = "#<#{self.class.name} input_tokens=#{input_tokens} output_tokens=#{output_tokens} " \
+          "total_tokens=#{total_tokens}"
+        text += " thinking_tokens=#{thinking_tokens}" unless thinking_tokens.nil?
+        "#{text}>"
       end
 
       # @param data [Hash]
@@ -38,8 +62,9 @@ module OmniAI
         input_tokens = data["input_tokens"] || data["prompt_tokens"]
         output_tokens = data["output_tokens"] || data["completion_tokens"]
         total_tokens = data["total_tokens"]
+        thinking_tokens = data["thinking_tokens"]
 
-        new(input_tokens:, output_tokens:, total_tokens:)
+        new(input_tokens:, output_tokens:, total_tokens:, thinking_tokens:)
       end
 
       # @param context [OmniAI::Context] optional
@@ -53,7 +78,7 @@ module OmniAI
           input_tokens:,
           output_tokens:,
           total_tokens:,
-        }
+        }.tap { |data| data[:thinking_tokens] = thinking_tokens unless thinking_tokens.nil? }
       end
     end
   end

data/lib/omniai/chat.rb

@@ -66,6 +66,8 @@ module OmniAI
     # @param stream [Proc, IO, nil] optional
     # @param tools [Array<OmniAI::Tool>, nil] optional
     # @param format [:json, :text, OmniAI::Schema::Object, nil] optional
+    # @param on_response [Proc, nil] optional - called with each completed round's `Response` before its tool
+    #   calls run
     # @param options [Hash] optional (used for vendor specific options)
     #
     # @yield [prompt] optional
@@ -80,6 +82,7 @@ module OmniAI
       stream: nil,
       tools: nil,
       format: nil,
+      on_response: nil,
       **options,
       &block
     )
@@ -94,6 +97,7 @@ module OmniAI
       @stream = stream
       @tools = tools
       @format = format
+      @on_response = on_response
       @options = options || {}
     end
 
@@ -112,6 +116,8 @@ module OmniAI
         raise SSLError, e.message, cause: e
       end
 
+      @on_response&.call(completion)
+
       if tools? && completion.tool_call_list?
         next_completion = spawn!(
           @prompt.dup.tap do |prompt|
@@ -165,6 +171,7 @@ module OmniAI
         stream: @stream,
         tools: @tools,
         format: @format,
+        on_response: @on_response,
         **@options
       )
     end

data/lib/omniai/client.rb

@@ -191,13 +191,16 @@ module OmniAI
     # @param temperature [Float, nil] optional
     # @param stream [Proc, nil] optional
     # @param tools [Array<OmniAI::Tool>] optional
+    # @param on_response [Proc, nil] optional - called with each completed round's `Response` before its tool
+    #   calls run
     # @param options [Hash, nil] optional
     #
     # @yield [prompt] optional
     # @yieldparam prompt [OmniAI::Chat::Prompt]
     #
     # @return [OmniAI::Chat::Response]
-    def chat(prompt = nil, model:, temperature: nil, format: nil, stream: nil, tools: nil, options: {}, &)
+    def chat(prompt = nil, model:, temperature: nil, format: nil, stream: nil, tools: nil, on_response: nil,
+      options: {}, &)
       raise NotImplementedError, "#{self.class.name}#chat undefined"
     end
 

data/lib/omniai/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 3.7.1
+  version: 3.9.0
 platform: ruby
 authors:
 - Kevin Sylvestre