omniai 3.7.1 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e22534811cc346b74927ec47382420e86faee449ff730cbb0665d30a714cd872
-  data.tar.gz: 1c3e58ad36506a2564563c46a700e8be04731b7266d8008bbd63bcc22d9cfa64
+  metadata.gz: 444922e4ffb4b54da232b01faab2b171f39ec2547830a7c02a4dc607173acae9
+  data.tar.gz: 221d5e646b968f9cb422c64547966855518351038c9f1d7248961778785dd8fc
 SHA512:
-  metadata.gz: ea3efdf811897d5fff8f55b0e4051b71f151d077230518b139fde0ef38656c6b784f9aafcfccb43c692fe85a102b47d0ca41c8696af767294b1a2270dfeee5fa
-  data.tar.gz: f3e87e1dd51ca72ec1d8706d3833a06c10b65947fdaf1e9a375518ca2b3d78f03a43af1c2869de1e84fb1c5cd77226ecbd5aa45fa7092f84691f0ea5f5afd183
+  metadata.gz: 30da07946fab93796f28c4d831ef00f0b609051e664a1cdc01373af8e6079d857239bf26be88d5cbeb6e9d25c7c2bcc08588979e3393da661bc73057e4c34bcb
+  data.tar.gz: '09907c95ccd31c1f672f2fcc324a11a23b63799916db570a4a4fcaee4677249f430e15071a3f5e5ca34e72d867dedfc039a52527aa2dc9d6ffe7734b4f7d7dc7'

data/README.md

@@ -578,6 +578,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/version.rb

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

metadata

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