activeagent 1.0.0.rc1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a2f8f345b5f6a3f9d2717f24542a0dd0a75ae22a7b3601ebe77b9ff8ba3bbc1
-  data.tar.gz: efe4dc5f9c4d10e4f1454bf274080d42cd88c5af5488195fa98cafd5cbadb812
+  metadata.gz: 330c02d2e1ac16e72413f22401dbc6899f652b794d34090b0f499a37b901fbaf
+  data.tar.gz: a492f5c88db1f217fe47f9de1477f195c6b150b5dc5ce5791c66fe0f63b0b028
 SHA512:
-  metadata.gz: ab6e83518446995be3984dc347524314d831de5650c263e0338f2cff4382cd111196145f2155b206fe651d930054ac3cf166b05cee9aa89fe907fbc4c7d7ed5f
-  data.tar.gz: bbff91deb2aba1feccb49edbf71664c3569595357fc7d3c1aea9555d95f07c2edb102f24927fe2132eb35ddc5bc2a8b8d0f52eb1b0f40ca9ca308b59263b68a6
+  metadata.gz: d8dac6789ba1f3685c24d711aace46ad5b681e9c795a975e61f07ee3c7d9a9bc44c2fd0568fabcabd739df5efd13b222c5fa6e954384bacb8bbcfdaaab0d7182
+  data.tar.gz: 8a0f61b2b5a9375c8f1b090bca29af077384079ba008622a1a510d8190acdff034c7f6b8065c1c752a2cee00dabd35d00f017db28954aacc17386fb06be63d50

data/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - Unreleased
+## [1.0.0] - 2025-11-21
 
 Major refactor with breaking changes. Complete provider rewrite. New modular architecture.
 
@@ -148,6 +148,35 @@ 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
+```
+
+**Enhanced Instrumentation for APM Integration**
+- Unified event structure: `prompt.active_agent` and `embed.active_agent` (top-level) plus `prompt.provider.active_agent` and `embed.provider.active_agent` (per-API-call)
+- Event payloads include comprehensive data for monitoring tools (New Relic, DataDog, etc.):
+  - Request parameters: `model`, `temperature`, `max_tokens`, `top_p`, `stream`, `message_count`, `has_tools`
+  - Usage data: `input_tokens`, `output_tokens`, `total_tokens`, `cached_tokens`, `reasoning_tokens`, `audio_tokens`, `cache_creation_tokens` (critical for cost tracking)
+  - Response metadata: `finish_reason`, `response_model`, `response_id`, `embedding_count`
+- Top-level events report cumulative usage across all API calls in multi-turn conversations
+- Provider-level events report per-call usage for granular tracking
+
+**Multi-Turn Usage Tracking**
+- `response.usage` now returns cumulative token counts across all API calls during tool calling
+- New `response.usages` array contains individual usage objects from each API call
+- `Usage` objects support addition: `usage1 + usage2` for combining statistics
+
 **Provider Enhancements**
 - OpenAI Responses API: `api: :responses` or `api: :chat`
 - Anthropic JSON object mode with automatic extraction
@@ -195,6 +224,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
 

data/lib/active_agent/providers/_base_provider.rb

@@ -2,21 +2,21 @@ require "active_support/delegation"
 
 require_relative "common/response"
 require_relative "concerns/exception_handler"
+require_relative "concerns/instrumentation"
 require_relative "concerns/previewable"
 
-# Maps provider types to their gem dependencies.
 # @private
 GEM_LOADERS = {
   anthropic: [ "anthropic", "~> 1.12", "anthropic" ],
   openai:    [ "openai",    "~> 0.34", "openai" ]
 }
 
-# Loads and requires a provider's gem dependency.
+# Requires a provider's gem dependency.
 #
 # @param type [Symbol] provider type (:anthropic, :openai)
-# @param file_name [String] provider file path for error context
+# @param file_name [String] for error context
 # @return [void]
-# @raise [LoadError] when the required gem is not available
+# @raise [LoadError] when required gem is not installed
 def require_gem!(type, file_name)
   gem_name, requirement, package_name = GEM_LOADERS.fetch(type)
   provider_name = file_name.split("/").last.delete_suffix(".rb").camelize
@@ -31,9 +31,8 @@ end
 
 module ActiveAgent
   module Providers
-    # Base class for LLM provider integrations.
+    # Orchestrates LLM provider API requests, streaming, and multi-turn tool calling.
     #
-    # Orchestrates API requests, streaming responses, and multi-turn tool calling.
     # Each provider (OpenAI, Anthropic, etc.) subclasses this to implement
     # provider-specific API interactions.
     #
@@ -44,6 +43,7 @@ module ActiveAgent
       extend ActiveSupport::Delegation
 
       include ExceptionHandler
+      include Instrumentation
       include Previewable
 
       class ProvidersError < StandardError; end
@@ -51,34 +51,35 @@ module ActiveAgent
       attr_internal :options, :context, :trace_id,   # Setup
                     :request, :message_stack,        # Runtime
                     :stream_broadcaster, :streaming, # Callback (Streams)
-                    :tools_function                  # Callback (Tools)
+                    :tools_function,                 # Callback (Tools)
+                    :usage_stack                     # Usage Tracking
 
-      # @return [String] provider name extracted from class name (e.g., "Anthropic", "OpenAI")
+      # @return [String] e.g., "Anthropic", "OpenAI"
       def self.service_name
         name.split("::").last.delete_suffix("Provider")
       end
 
-      # @return [String] module-qualified provider name (e.g., "Anthropic", "OpenAI::Chat")
+      # @return [String] e.g., "Anthropic", "OpenAI::Chat"
       def self.tag_name
         name.delete_prefix("ActiveAgent::Providers::").delete_suffix("Provider")
       end
 
-      # @return [Module] provider's namespace module (e.g., ActiveAgent::Providers::OpenAI)
+      # @return [Module] e.g., ActiveAgent::Providers::OpenAI
       def self.namespace
         "#{name.deconstantize}::#{service_name}".safe_constantize
       end
 
-      # @return [Class] provider's options class
+      # @return [Class]
       def self.options_klass
         namespace::Options
       end
 
-      # @return [ActiveModel::Type::Value] provider-specific request type for prompt casting/serialization
+      # @return [ActiveModel::Type::Value] for prompt casting/serialization
       def self.prompt_request_type
         namespace::RequestType.new
       end
 
-      # @return [ActiveModel::Type::Value] provider-specific request type for embedding casting/serialization
+      # @return [ActiveModel::Type::Value] for embedding casting/serialization
       # @raise [NotImplementedError] when provider doesn't support embeddings
       def self.embed_request_type
         fail(NotImplementedError)
@@ -86,12 +87,10 @@ module ActiveAgent
 
       delegate :service_name, :tag_name, :namespace, :options_klass, :prompt_request_type, :embed_request_type, to: :class
 
-      # Initializes a provider instance.
-      #
       # @param kwargs [Hash] configuration and callbacks
       # @option kwargs [Symbol] :service validates against provider's service name
-      # @option kwargs [Proc] :stream_broadcaster callback for streaming events (:open, :update, :close)
-      # @option kwargs [Proc] :tools_function callback to execute tool/function calls
+      # @option kwargs [Proc] :stream_broadcaster for streaming events (:open, :update, :close)
+      # @option kwargs [Proc] :tools_function to execute tool/function calls
       # @raise [RuntimeError] when service name doesn't match provider
       def initialize(kwargs = {})
         assert_service!(kwargs.delete(:service))
@@ -107,21 +106,10 @@ module ActiveAgent
         self.options            = options_klass.new(kwargs.extract!(*options_klass.keys))
         self.context            = kwargs
         self.message_stack      = []
+        self.usage_stack        = []
       end
 
-      # Executes a prompt request with error handling and instrumentation.
-      #
-      # @return [ActiveAgent::Providers::Common::PromptResponse]
-      def prompt
-        instrument("prompt_start.provider.active_agent") do
-          self.request = prompt_request_type.cast(context.except(:trace_id))
-          resolve_prompt
-        end
-      end
-
-      # Generates a preview of the prompt without executing the API call.
-      #
-      # Casts context into a request object and renders it as markdown for inspection.
+      # Generates prompt preview without executing the API call.
       #
       # @return [String] markdown-formatted preview
       def preview
@@ -129,15 +117,31 @@ module ActiveAgent
         preview_prompt
       end
 
-      # Executes an embedding request with error handling and instrumentation.
+      # Executes prompt request with error handling and instrumentation.
       #
-      # Converts text into vector representations for semantic search and similarity operations.
+      # @return [ActiveAgent::Providers::Common::PromptResponse]
+      def prompt
+        self.request = prompt_request_type.cast(context.except(:trace_id))
+
+        instrument("prompt.active_agent") do |payload|
+          response = resolve_prompt
+          instrumentation_prompt_payload(payload, request, response)
+
+          response
+        end
+      end
+
+      # Executes embedding request with error handling and instrumentation.
       #
       # @return [ActiveAgent::Providers::Common::EmbedResponse]
       def embed
-        instrument("embed_start.provider.active_agent") do
-          self.request = embed_request_type.cast(context.except(:trace_id))
-          resolve_embed
+        self.request = embed_request_type.cast(context.except(:trace_id))
+
+        instrument("embed.active_agent") do |payload|
+          response = resolve_embed
+          instrumentation_embed_payload(payload, request, response)
+
+          response
         end
       end
 
@@ -149,8 +153,6 @@ module ActiveAgent
         fail "Unexpected Service Name: #{name} != #{service_name}" if name && name != service_name
       end
 
-      # Instruments an event for logging and metrics.
-      #
       # @param name [String]
       # @param payload [Hash]
       # @yield block to instrument
@@ -160,34 +162,42 @@ module ActiveAgent
         ActiveSupport::Notifications.instrument(name, full_payload, &block)
       end
 
-      # Orchestrates the complete prompt request lifecycle.
+      # Orchestrates complete prompt request lifecycle.
       #
-      # Prepares request, executes API call, processes response, and handles
-      # recursive tool/function calling until completion.
+      # Handles recursive tool/function calling until completion.
       #
       # @return [ActiveAgent::Providers::Common::PromptResponse]
       def resolve_prompt
-        request = prepare_prompt_request
-
-        instrument("request_prepared.provider.active_agent", message_count: request.messages.size)
-
-        # @todo Validate Request
-        api_parameters = api_request_build(request, prompt_request_type)
-        api_response   = instrument("api_call.provider.active_agent", streaming: api_parameters[:stream].present?) do
-          with_exception_handling { api_prompt_execute(api_parameters) }
+        api_parameters = api_request_build(prepare_prompt_request, prompt_request_type)
+        api_response = instrument("prompt.provider.active_agent") do |payload|
+          raw_response = with_exception_handling { api_prompt_execute(api_parameters) }
+
+          # Instrumentation Context Building
+          # Normalize response for instrumentation (providers may return gem objects)
+          normalized_response = api_response_normalize(raw_response)
+          common_response = Common::PromptResponse.new(raw_response: normalized_response)
+          instrumentation_prompt_payload(payload, self.request, common_response)
+          usage_stack.push(common_response.usage) if common_response&.usage
+
+          raw_response
         end
 
-        process_prompt_finished(api_response.as_json&.deep_symbolize_keys)
+        process_prompt_finished(api_response)
       end
 
-      # Orchestrates the complete embedding request lifecycle.
+      # Orchestrates complete embedding request lifecycle.
       #
       # @return [ActiveAgent::Providers::Common::EmbedResponse]
       def resolve_embed
-        # @todo Validate Request
-        api_parameters = api_request_build(request, embed_request_type)
-        api_response   = instrument("embed_call.provider.active_agent") do
-          with_exception_handling { api_embed_execute(api_parameters) }
+        api_parameters = api_request_build(self.request, embed_request_type)
+        api_response = instrument("embed.provider.active_agent") do |payload|
+          raw_response = with_exception_handling { api_embed_execute(api_parameters) }
+
+          # Instrumentation Context Building
+          common_response = Common::EmbedResponse.new(raw_response:)
+          instrumentation_embed_payload(payload, self.request, common_response)
+
+          raw_response
         end
 
         process_embed_finished(api_response)
@@ -195,7 +205,7 @@ module ActiveAgent
 
       # Prepares request for next iteration in multi-turn conversation.
       #
-      # Appends accumulated messages from message stack and resets buffer for next cycle.
+      # Appends accumulated messages and resets buffer for next cycle.
       #
       # @return [Request]
       def prepare_prompt_request
@@ -205,11 +215,9 @@ module ActiveAgent
         self.request
       end
 
-      # Builds API request parameters from request object.
-      #
       # @param request [Request]
-      # @param request_type [ActiveModel::Type::Value] type for serialization
-      # @return [Hash]
+      # @param request_type [ActiveModel::Type::Value] for serialization
+      # @return [Hash] API request parameters
       def api_request_build(request, request_type)
         parameters          = request_type.serialize(request)
         parameters[:stream] = process_stream if request.try(:stream)
@@ -221,7 +229,7 @@ module ActiveAgent
         parameters
       end
 
-      # @return [Proc] invoked for each response chunk
+      # @return [Proc] for each response chunk
       def process_stream
         proc do |api_response_chunk|
           process_stream_chunk(api_response_chunk)
@@ -231,12 +239,10 @@ module ActiveAgent
       # Executes prompt request against provider's API.
       #
       # @abstract
-      # @param request_parameters [Hash]
+      # @param parameters [Hash]
       # @return [Object] provider-specific API response
       # @raise [NotImplementedError]
       def api_prompt_execute(parameters)
-        instrument("api_request.provider.active_agent", model: parameters[:model], streaming: !!parameters[:stream])
-
         unless parameters[:stream]
           api_prompt_executer.create(**parameters)
         else
@@ -257,6 +263,18 @@ module ActiveAgent
         fail NotImplementedError, "Subclass expected to implement"
       end
 
+      # Normalizes API response for instrumentation.
+      #
+      # Providers that return gem objects (like Anthropic::Models::Message) should
+      # override this to convert to a hash so usage data can be extracted.
+      # By default, returns the response as-is (for providers returning hashes).
+      #
+      # @param api_response [Object] provider-specific API response
+      # @return [Hash, Object] normalized response (preferably hash)
+      def api_response_normalize(api_response)
+        api_response
+      end
+
       # Executes embedding request against provider's API.
       #
       # @abstract
@@ -278,21 +296,21 @@ module ActiveAgent
 
       # Broadcasts stream open event.
       #
-      # Fires once per request cycle even during multi-turn tool calling.
+      # Fires once per request cycle, even during multi-turn tool calling.
       #
       # @return [void]
       def broadcast_stream_open
         return if streaming
         self.streaming = true
 
-        instrument("stream_open.provider.active_agent")
+        instrument("stream_open.active_agent")
         stream_broadcaster.call(nil, nil, :open)
       end
 
       # Broadcasts stream update with message content delta.
       #
       # @param message [Hash, Object]
-      # @param delta [String, nil] incremental content chunk
+      # @param delta [String, nil]
       # @return [void]
       def broadcast_stream_update(message, delta = nil)
         stream_broadcaster.call(message, delta, :update)
@@ -300,35 +318,31 @@ module ActiveAgent
 
       # Broadcasts stream close event.
       #
-      # Fires once per request cycle even during multi-turn tool calling.
+      # Fires once per request cycle, even during multi-turn tool calling.
       #
       # @return [void]
       def broadcast_stream_close
         return unless streaming
         self.streaming = false
 
-        instrument("stream_close.provider.active_agent")
+        instrument("stream_close.active_agent")
         stream_broadcaster.call(message_stack.last, nil, :close)
       end
 
       # Processes completed API response and handles tool calling recursion.
       #
-      # Extracts messages and function calls from the response. If tools were invoked,
-      # executes them and recursively continues the prompt until completion.
+      # Extracts messages and function calls. If tools were invoked,
+      # executes them and recursively continues until completion.
       #
       # @param api_response [Object, nil] provider-specific response
       # @return [Common::PromptResponse, nil]
       def process_prompt_finished(api_response = nil)
         if (api_messages = process_prompt_finished_extract_messages(api_response))
-          instrument("messages_extracted.provider.active_agent", message_count: api_messages.size)
           message_stack.push(*api_messages)
         end
 
         if (tool_calls = process_prompt_finished_extract_function_calls)&.any?
-          instrument("tool_calls_processing.provider.active_agent", tool_count: tool_calls.size)
           process_function_calls(tool_calls)
-
-          instrument("multi_turn_continue.provider.active_agent")
           resolve_prompt
         else
 
@@ -337,27 +351,25 @@ module ActiveAgent
           # as they continue to work.
           broadcast_stream_close
 
-          instrument("prompt_complete.provider.active_agent", message_count: message_stack.size)
-
           # To convert the messages into common format we first need to merge the current
           # stack and then cast them to the provider type, so we can cast them out to common.
           messages = prompt_request_type.cast(
             messages: [ *request.messages, *message_stack ]
           ).messages
 
+          # Create response object with usage_stack array for multi-turn cumulative tracking.
           # This will returned as it closes up the recursive stack
           Common::PromptResponse.new(
             context:,
+            format: request.response_format,
+            messages:,
             raw_request:  prompt_request_type.serialize(request),
             raw_response: api_response,
-            messages:,
-            format: request.response_format
+            usages: usage_stack
           )
         end
       end
 
-      # Extracts messages from API response.
-      #
       # @abstract
       # @param api_response [Object]
       # @return [Array<Message>, nil]
@@ -366,8 +378,6 @@ module ActiveAgent
         fail NotImplementedError, "Subclass expected to implement"
       end
 
-      # Extracts tool/function calls from API response.
-      #
       # @abstract
       # @return [Array<Hash>, nil]
       # @raise [NotImplementedError]

data/lib/active_agent/providers/anthropic/_types.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "requests/_types"
-
 require_relative "options"
 require_relative "request"
 
@@ -11,6 +9,8 @@ module ActiveAgent
       # ActiveModel type for casting and serializing Anthropic Request objects.
       #
       # Handles conversion between Hash, Request, and serialized formats for API calls.
+      # The Request class now delegates to the official Anthropic gem model, eliminating
+      # the need for maintaining nested type definitions.
       class RequestType < ActiveModel::Type::Value
         # Casts input to Request object.
         #