Create Normalize Usage

Author: sirwolfgang

CHANGELOG.md

@@ -148,6 +148,21 @@ response = MyAgent.embed(inputs: ["Text 1", "Text 2"]).embed_now
 vectors = response.data.map { |d| d[:embedding] }
 ```
 
+**Normalized Usage Statistics**
+```ruby
+response = MyAgent.prompt("Hello").generate_now
+
+# Works across all providers
+response.usage.input_tokens
+response.usage.output_tokens
+response.usage.total_tokens
+
+# Provider-specific fields when available
+response.usage.cached_tokens      # OpenAI, Anthropic
+response.usage.reasoning_tokens   # OpenAI o1 models
+response.usage.service_tier       # Anthropic
+```
+
 **Provider Enhancements**
 - OpenAI Responses API: `api: :responses` or `api: :chat`
 - Anthropic JSON object mode with automatic extraction
@@ -195,6 +210,7 @@ vectors = response.data.map { |d| d[:embedding] }
 - Template rendering without blocks
 - Schema generator key symbolization
 - Rails 8.0 and 8.1 compatibility
+- Usage extraction across OpenAI/Anthropic response formats
 
 ### Removed
 

docs/.vitepress/config.mts

@@ -100,6 +100,7 @@ export default defineConfig({
           { text: 'Embeddings', link: '/actions/embeddings' },
           { text: 'Tools', link: '/actions/tools' },
           { text: 'Structured Output', link: '/actions/structured_output' },
+          { text: 'Usage', link: '/actions/usage' },
         ]
       },
       {

docs/actions.md

@@ -43,6 +43,15 @@ Generate vectors for semantic search:
 
 <<< @/../test/docs/actions_examples_test.rb#embeddings_vectorize{ruby:line-numbers}
 
+### [Usage Statistics](/actions/usage)
+
+Track token consumption and costs:
+
+```ruby
+response = agent.summarize.generate_now
+response.usage.total_tokens  #=> 125
+```
+
 ## Common Patterns
 
 ### Multi-Capability Actions

docs/actions/usage.md

@@ -0,0 +1,65 @@
+---
+title: Usage Statistics
+description: Track token usage and performance metrics across all AI providers with normalized usage objects.
+---
+# {{ $frontmatter.title }}
+
+Track token consumption and performance metrics from AI provider responses. All providers return normalized usage statistics for consistent cost tracking and monitoring.
+
+## Accessing Usage
+
+Get usage statistics from any response:
+
+<<< @/../test/docs/actions/usage_examples_test.rb#accessing_usage{ruby:line-numbers}
+
+## Common Fields
+
+These fields work across all providers:
+
+<<< @/../test/docs/actions/usage_examples_test.rb#common_fields{ruby:line-numbers}
+
+## Provider-Specific Fields
+
+Access advanced metrics when available:
+
+::: code-group
+<<< @/../test/docs/actions/usage_examples_test.rb#provider_specific_openai{ruby:line-numbers} [OpenAI]
+<<< @/../test/docs/actions/usage_examples_test.rb#provider_specific_anthropic{ruby:line-numbers} [Anthropic]
+<<< @/../test/docs/actions/usage_examples_test.rb#provider_specific_ollama{ruby:line-numbers} [Ollama]
+:::
+
+## Provider Details
+
+Raw provider data preserved in `provider_details`:
+
+::: code-group
+<<< @/../test/docs/actions/usage_examples_test.rb#provider_details_openai{ruby:line-numbers} [OpenAI]
+<<< @/../test/docs/actions/usage_examples_test.rb#provider_details_ollama{ruby:line-numbers} [Ollama]
+:::
+
+## Cost Tracking
+
+Calculate costs using token counts:
+
+<<< @/../test/docs/actions/usage_examples_test.rb#cost_tracking{ruby:line-numbers}
+
+## Embeddings Usage
+
+Embedding responses have zero output tokens:
+
+<<< @/../test/docs/actions/usage_examples_test.rb#embeddings_usage{ruby:line-numbers}
+
+## Field Mapping
+
+How provider fields map to normalized names:
+
+| Provider | input_tokens | output_tokens | total_tokens |
+|----------|--------------|---------------|--------------|
+| OpenAI Chat | prompt_tokens | completion_tokens | total_tokens |
+| OpenAI Embed | prompt_tokens | 0 | total_tokens |
+| OpenAI Responses | input_tokens | output_tokens | total_tokens |
+| Anthropic | input_tokens | output_tokens | calculated |
+| Ollama | prompt_eval_count | eval_count | calculated |
+| OpenRouter | prompt_tokens | completion_tokens | total_tokens |
+
+**Note:** `total_tokens` is automatically calculated as `input_tokens + output_tokens` when not provided by the provider.

docs/agents/generation.md

@@ -93,10 +93,11 @@ response.raw_request       # The most recent request in provider format
 response.raw_response      # The most recent response in provider format
 response.context           # The original context that was sent
 
-# Usage statistics (when available from provider)
-response.prompt_tokens     # Input tokens used
-response.completion_tokens # Output tokens used
-response.total_tokens      # Total tokens used
+# Usage statistics (see /actions/usage for details)
+response.usage             # Normalized usage object across all providers
+response.usage.input_tokens
+response.usage.output_tokens
+response.usage.total_tokens
 ```
 
 For embeddings:
@@ -110,14 +111,16 @@ response.raw_request  # The most recent request in provider format
 response.raw_response # The most recent response in provider format
 response.context      # The original context that was sent
 
-# Usage statistics (when available from provider)
-response.prompt_tokens
+# Usage statistics
+response.usage             # Normalized usage object
+response.usage.input_tokens
 ```
 
 ## Next Steps
 
 - [Agents](/agents) - Understanding the full agent lifecycle
 - [Actions](/actions) - Define what your agents can do
+- [Usage Statistics](/actions/usage) - Track token consumption and costs
 - [Messages](/actions/messages) - Work with multimodal content
 - [Tools](/actions/tools) - Enable function calling capabilities
 - [Streaming](/agents/streaming) - Stream responses in real-time

docs/framework.md

@@ -60,7 +60,7 @@ When you define an agent, you create a specialized participant that interacts wi
 
 - **Agent** (Controller) - Manages lifecycle, defines actions, configures providers
 - **Generation** (Request Proxy) - Coordinates execution, holds configuration, provides synchronous/async methods. Created by invocation, it's lazy—execution doesn't start until you call `.prompt_now`, `.embed_now`, or `.prompt_later`.
-- **Response** (Result) - Contains messages, metadata, token usage, and parsed output. Returned after Generation executes.
+- **Response** (Result) - Contains messages, metadata, and normalized usage statistics (see **[Usage Statistics](/actions/usage)**). Returned after Generation executes.
 
 **Request-Response Lifecycle:**
 

docs/providers.md

@@ -92,7 +92,7 @@ All providers return standardized response objects:
 
 **Common attributes:**
 - `message` / `messages` - Response content and conversation history
-- `prompt_tokens` / `completion_tokens` - Token usage for cost tracking
+- `usage` - Normalized token usage statistics (see **[Usage Statistics](/actions/usage)**)
 - `raw_request` / `raw_response` - Provider-specific data for debugging
 - `context` - Original request sent to provider
 

lib/active_agent/providers/anthropic_provider.rb

@@ -192,25 +192,33 @@ def process_tool_call_function(api_function_call)
       end
 
       # Converts API response message to hash for message_stack.
+      # Converts Anthropic gem response object to hash for storage.
+      #
+      # @param api_response [Anthropic::Models::Message]
+      # @return [Common::PromptResponse, nil]
+      def process_prompt_finished(api_response = nil)
+        # Convert gem object to hash so that raw_response[:usage] works
+        api_response_hash = api_response ? Anthropic::Transforms.gem_to_hash(api_response) : nil
+        super(api_response_hash)
+      end
+
       #
       # Handles JSON response format simulation by prepending `{` to the response
       # content after removing the assistant lead-in message.
       #
       # @see BaseProvider#process_prompt_finished_extract_messages
-      # @param api_response [Anthropic::Models::Message]
+      # @param api_response [Hash] converted response hash
       # @return [Array<Hash>, nil]
       def process_prompt_finished_extract_messages(api_response)
         return unless api_response
 
         # Handle JSON response format simulation
         if request.response_format&.dig(:type) == "json_object"
           request.pop_message!
-          api_response.content[0].text = "{#{api_response.content[0].text}"
+          api_response[:content][0][:text] = "{#{api_response[:content][0][:text]}"
         end
 
-        message = Anthropic::Transforms.gem_to_hash(api_response)
-
-        [ message ]
+        [ api_response ]
       end
 
       # Extracts tool_use blocks from message_stack and parses JSON inputs.

lib/active_agent/providers/common/responses/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_agent/providers/common/model"
+require "active_agent/providers/common/usage"
 
 module ActiveAgent
   module Providers
@@ -21,7 +22,7 @@ module Responses
         # @example Accessing response data
         #   response = agent.prompt.generate_now
         #   response.success?         #=> true
-        #   response.usage            #=> { "prompt_tokens" => 10, "completion_tokens" => 20 }
+        #   response.usage            #=> Usage object with normalized fields
         #   response.total_tokens     #=> 30
         #
         # @example Inspecting raw provider data
@@ -91,58 +92,33 @@ def success?
             true
           end
 
-          # Extracts usage statistics from the raw response.
+          # Returns normalized usage statistics across all providers.
           #
-          # Most providers (OpenAI, Anthropic, etc.) return usage data in a
-          # standardized format within the response. This method extracts that
-          # information for token counting and billing purposes.
+          # This method provides a consistent interface for accessing token usage
+          # regardless of the underlying provider. It automatically detects the
+          # provider format and returns a {Usage} object with normalized fields.
           #
-          # @return [Hash, nil] usage statistics hash with keys like "prompt_tokens",
-          #   "completion_tokens", and "total_tokens", or nil if not available
+          # @return [Usage, nil] normalized usage object, or nil if not available
           #
-          # @example Usage data structure
-          #   {
-          #     "prompt_tokens" => 10,
-          #     "completion_tokens" => 20,
-          #     "total_tokens" => 30
-          #   }
-          def usage
-            return nil unless raw_response
-
-            # Most providers store usage in the same format
-            if raw_response.is_a?(Hash) && raw_response["usage"]
-              raw_response["usage"]
-            end
-          end
-
-          # Extracts the number of tokens used in the prompt/input.
-          #
-          # @return [Integer, nil] number of prompt tokens used, or nil if unavailable
+          # @example Accessing normalized usage
+          #   response.usage.input_tokens      #=> 100
+          #   response.usage.output_tokens     #=> 25
+          #   response.usage.total_tokens      #=> 125
+          #   response.usage.cached_tokens     #=> 20 (if available)
           #
-          # @example
-          #   response.prompt_tokens #=> 10
-          def prompt_tokens
-            usage&.dig("prompt_tokens")
-          end
+          # @see Usage
+          def usage
+            @usage ||= begin
+              return nil unless raw_response
 
-          # Extracts the number of tokens used in the completion/output.
-          #
-          # @return [Integer, nil] number of completion tokens used, or nil if unavailable
-          #
-          # @example
-          #   response.completion_tokens #=> 20
-          def completion_tokens
-            usage&.dig("completion_tokens")
-          end
+              # Extract raw usage hash from provider response
+              # Support both string and symbol keys for compatibility
+              raw_usage = if raw_response.is_a?(Hash)
+                raw_response["usage"] || raw_response[:usage]
+              end
 
-          # Extracts the total number of tokens used (prompt + completion).
-          #
-          # @return [Integer, nil] total number of tokens used, or nil if unavailable
-          #
-          # @example
-          #   response.total_tokens #=> 30
-          def total_tokens
-            usage&.dig("total_tokens")
+              Usage.from_provider_usage(raw_usage)
+            end
           end
         end
       end