omniai 3.7.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7464f0580c8f8392155996aa7b4675491bec1fe62b48ff9b12e53264952a50e5
-  data.tar.gz: 3ef5570bd7eac6ed72a9826c90313565dc0fd00b6ec52745fe02a04ce2855264
+  metadata.gz: 444922e4ffb4b54da232b01faab2b171f39ec2547830a7c02a4dc607173acae9
+  data.tar.gz: 221d5e646b968f9cb422c64547966855518351038c9f1d7248961778785dd8fc
 SHA512:
-  metadata.gz: e5ab80ba78ab316ca74e46dffb0bdea26ed13b83f4ec4ff7c5e985580c5460d926366d71bf547ac905273968db44cf1949eb57c56b0560077f1b805f52a4c93d
-  data.tar.gz: bd453f4fd6355066833db225b771b1078fd8d916138213a1f0d4d18f37316cae7b60f47a215c46d7a76fb096eeece2e6d887a8dc9a4819c8c54dd65f3ece731f
+  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/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.7.0"
+  VERSION = "3.8.0"
 end

metadata

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