activeagent 1.0.0.rc1 → 1.0.0

data/lib/active_agent/providers/anthropic_provider.rb

@@ -5,6 +5,7 @@ require_relative "_base_provider"
 require_gem!(:anthropic, __FILE__)
 
 require_relative "anthropic/_types"
+require_relative "anthropic/transforms"
 
 module ActiveAgent
   module Providers
@@ -24,10 +25,10 @@ module ActiveAgent
 
       protected
 
-      # Prepares the request and handles tool choice cleanup.
+      # Removes forced tool choice after first use to prevent endless looping.
       #
-      # Removes forced tool choice from subsequent requests to prevent endless looping
-      # when the tool has already been used in the conversation.
+      # Clears tool_choice when the specified tool has already been called in the
+      # conversation, preventing the model from being forced to call it repeatedly.
       #
       # @see BaseProvider#prepare_prompt_request
       # @return [Request]
@@ -41,20 +42,24 @@ module ActiveAgent
       # @api private
       def prepare_prompt_request_tools
         return unless request.tool_choice
+        return unless request.tool_choice.respond_to?(:type)
 
         functions_used = message_stack.pluck(:content).flatten.select { _1[:type] == "tool_use" }.pluck(:name)
 
-        if (request.tool_choice.type == "any" && functions_used.any?) ||
-          (request.tool_choice.type == "tool" && functions_used.include?(request.tool_choice.name))
+        # tool_choice is always a gem model object (ToolChoiceAny, ToolChoiceTool, ToolChoiceAuto)
+        tool_choice_type = request.tool_choice.type
+        tool_choice_name = request.tool_choice.respond_to?(:name) ? request.tool_choice.name : nil
+
+        if (tool_choice_type == :any && functions_used.any?) ||
+          (tool_choice_type == :tool && tool_choice_name && functions_used.include?(tool_choice_name))
 
-          instrument("tool_choice_removed.provider.active_agent")
           request.tool_choice = nil
         end
       end
 
       # @api private
       def prepare_prompt_request_response_format
-        return unless request.response_format&.type == "json_object"
+        return unless request.response_format&.dig(:type) == "json_object"
 
         self.message_stack.push({
           role:    "assistant",
@@ -62,50 +67,61 @@ module ActiveAgent
         })
       end
 
+      # @see BaseProvider#api_prompt_executer
+      # @return [Anthropic::Messages]
       def api_prompt_executer
         client.messages
       end
 
-      # Processes streaming response chunks from Anthropic's API.
+      # @see BaseProvider#api_response_normalize
+      # @param api_response [Anthropic::Models::Message]
+      # @return [Hash] normalized response hash
+      def api_response_normalize(api_response)
+        return api_response unless api_response
+
+        Anthropic::Transforms.gem_to_hash(api_response)
+      end
+
+      # Processes streaming chunks and builds message incrementally in message_stack.
       #
       # Handles chunk types: message_start, content_block_start, content_block_delta,
       # content_block_stop, message_delta, message_stop. Manages text deltas,
       # tool use inputs, and Claude's thinking/signature blocks.
       #
-      # @param api_response_chunk [Object]
+      # @see BaseProvider#process_stream_chunk
+      # @param api_response_chunk [Anthropic::StreamEvent]
       # @return [void]
       def process_stream_chunk(api_response_chunk)
-        api_response_chunk = api_response_chunk.as_json.deep_symbolize_keys
-        chunk_type = api_response_chunk[:type].to_sym
+        chunk_type = api_response_chunk[:type]&.to_sym
 
-        instrument("stream_chunk_processing.provider.active_agent", chunk_type:)
+        instrument("stream_chunk.active_agent", chunk_type:)
 
         broadcast_stream_open
 
         case chunk_type
         # Message Created
         when :message_start
-          api_message = api_response_chunk.fetch(:message)
+          api_message = Anthropic::Transforms.gem_to_hash(api_response_chunk.message)
           self.message_stack.push(api_message)
           broadcast_stream_update(message_stack.last)
 
         # -> Content Block Create
         when :content_block_start
-          api_content = api_response_chunk.fetch(:content_block)
+          api_content = Anthropic::Transforms.gem_to_hash(api_response_chunk.content_block)
           self.message_stack.last[:content].push(api_content)
           broadcast_stream_update(message_stack.last, api_content[:text])
 
         # -> -> Content Block Append
         when :content_block_delta
-          index     = api_response_chunk.fetch(:index)
+          index     = api_response_chunk.index
           content   = self.message_stack.last[:content][index]
-          api_delta = api_response_chunk.fetch(:delta)
+          api_delta = api_response_chunk.delta
 
-          case (delta_type = api_delta[:type].to_sym)
+          case api_delta.type.to_sym
           # -> -> -> Content Text Append
           when :text_delta
-            content[:text] += api_delta[:text]
-            broadcast_stream_update(message_stack.last, api_delta[:text])
+            content[:text] += api_delta.text
+            broadcast_stream_update(message_stack.last, api_delta.text)
 
           # -> -> -> Content Function Call Append
           when :input_json_delta
@@ -113,21 +129,29 @@ module ActiveAgent
           when :thinking_delta, :signature_delta
             # TODO: Add with thinking rendering support
           else
-            fail "Unexpected Delta Type #{delta_type}"
+            raise "Unexpected delta type: #{api_delta.type}"
           end
         # -> Content Block Completed [Full Block]
         when :content_block_stop
-          index       = api_response_chunk.fetch(:index)
-          api_content = api_response_chunk.fetch(:content_block)
+          index       = api_response_chunk.index
+          api_content = Anthropic::Transforms.gem_to_hash(api_response_chunk.content_block)
           self.message_stack.last[:content][index] = api_content
 
         # Message Delta
         when :message_delta
-          self.message_stack.last.merge!(api_response_chunk.fetch(:delta))
+          delta = Anthropic::Transforms.gem_to_hash(api_response_chunk.delta)
+          self.message_stack.last.merge!(delta)
 
         # Message Completed [Full Message]
         when :message_stop
-          self.message_stack[-1] = api_response_chunk.fetch(:message)
+          api_message = Anthropic::Transforms.gem_to_hash(api_response_chunk.message)
+
+          # Handle _json_buf (gem >= 1.14.0)
+          api_message[:content]&.each do |content_block|
+            content_block.delete(:_json_buf) if content_block[:type] == "tool_use"
+          end
+
+          self.message_stack[-1] = api_message
 
           # Once we are finished, close out and run tooling callbacks (Recursive)
           process_prompt_finished if message_stack.last[:stop_reason]
@@ -137,12 +161,12 @@ module ActiveAgent
           # TODO: https://docs.claude.com/en/docs/build-with-claude/streaming#error-events
         else
           # No-Op: Looks like internal tracking from gem wrapper
-          return if api_response_chunk.key?(:snapshot)
-          fail "Unexpected Chunk Type: #{api_response_chunk[:type]}"
+          return if api_response_chunk.respond_to?(:snapshot)
+          raise "Unexpected chunk type: #{api_response_chunk.type}"
         end
       end
 
-      # Executes tool calls and creates user message with results.
+      # Executes tool calls and appends user message with results to message_stack.
       #
       # @param api_function_calls [Array<Hash>] with :name, :input, and :id keys
       # @return [void]
@@ -151,58 +175,77 @@ module ActiveAgent
           process_tool_call_function(api_function_call)
         end
 
-        message = Anthropic::Requests::Messages::User.new(content:)
+        api_message = ::Anthropic::Models::MessageParam.new(role: "user", content:)
+        message     = Anthropic::Transforms.gem_to_hash(api_message)
 
-        message_stack.push(message.serialize)
+        message_stack.push(message)
       end
 
-      # Executes a single tool call and returns the result.
+      # Executes a single tool call via callback.
       #
       # @param api_function_call [Hash] with :name, :input, and :id keys
-      # @return [Anthropic::Requests::Content::ToolResult]
+      # @return [Anthropic::Models::ToolResultBlockParam]
       def process_tool_call_function(api_function_call)
-        instrument("tool_execution.provider.active_agent", tool_name: api_function_call[:name])
-
-        results = tools_function.call(
-          api_function_call[:name], **api_function_call[:input]
-        )
+        instrument("tool_call.active_agent", tool_name: api_function_call[:name]) do
+          results = tools_function.call(
+            api_function_call[:name], **api_function_call[:input]
+          )
+
+          ::Anthropic::Models::ToolResultBlockParam.new(
+            type:        "tool_result",
+            tool_use_id: api_function_call[:id],
+            content:     results.to_json,
+            is_error:    false
+          )
+        end
+      end
 
-        Anthropic::Requests::Content::ToolResult.new(
-          tool_use_id: api_function_call[:id],
-          content:     results.to_json,
-        )
+      # 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
 
-      # Extracts messages from completed API response.
       #
-      # Handles JSON response format by merging the leading `{` prefix back into
-      # the message content after removing the assistant lead-in message.
+      # Handles JSON response format simulation by prepending `{` to the response
+      # content after removing the assistant lead-in message.
       #
-      # @param api_response [Object]
+      # @see BaseProvider#process_prompt_finished_extract_messages
+      # @param api_response [Hash] converted response hash
       # @return [Array<Hash>, nil]
       def process_prompt_finished_extract_messages(api_response)
         return unless api_response
 
-        message = api_response.as_json.deep_symbolize_keys
-
-        if request.response_format&.type == "json_object"
-          request.messages.pop # Remove the `Here is the JSON requested:\n{` lead in message
-          message[:content][0][:text] = "{#{message[:content][0][:text]}" # Merge in `{` prefix
+        # 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]}"
         end
 
-        [ message ]
+        [ api_response ]
       end
 
-      # Extracts function calls from message stack.
+      # Extracts tool_use blocks from message_stack and parses JSON inputs.
       #
-      # Processes tool_use content blocks and converts JSON buffers into proper
-      # input parameters for function execution.
+      # Handles JSON buffer parsing for gem versions and string inputs for gem >= 1.14.0.
       #
+      # @see BaseProvider#process_prompt_finished_extract_function_calls
       # @return [Array<Hash>] with :name, :input, and :id keys
       def process_prompt_finished_extract_function_calls
         message_stack.pluck(:content).flatten.select { _1 in { type: "tool_use" } }.map do |api_function_call|
           json_buf = api_function_call.delete(:json_buf)
           api_function_call[:input] = JSON.parse(json_buf, symbolize_names: true) if json_buf
+
+          # Handle case where :input is still a JSON string (gem >= 1.14.0)
+          if api_function_call[:input].is_a?(String)
+            api_function_call[:input] = JSON.parse(api_function_call[:input], symbolize_names: true)
+          end
+
           api_function_call
         end
       end

data/lib/active_agent/providers/common/messages/_types.rb

@@ -51,6 +51,12 @@ module ActiveAgent
                 when "assistant"
                   # Filter to only known attributes for Assistant
                   filtered_hash = hash.slice(:role, :content, :name)
+
+                  # Compress content array to string if needed (Anthropic format)
+                  if filtered_hash[:content].is_a?(Array)
+                    filtered_hash[:content] = compress_content_array(filtered_hash[:content])
+                  end
+
                   Common::Messages::Assistant.new(**filtered_hash)
                 when "tool"
                   # Filter to only known attributes for Tool
@@ -63,6 +69,13 @@ module ActiveAgent
                 # Check if the value responds to to_common (provider-specific message)
                 if value.respond_to?(:to_common)
                   cast_message(value.to_common)
+                # Check if it's a gem model object that can be converted to hash
+                # Use JSON round-trip to ensure proper nested serialization
+                elsif value.respond_to?(:to_json)
+                  hash = JSON.parse(value.to_json, symbolize_names: true)
+                  cast_message(hash)
+                elsif value.respond_to?(:to_h)
+                  cast_message(value.to_h)
                 else
                   raise ArgumentError, "Cannot cast #{value.class} to Message"
                 end
@@ -78,9 +91,32 @@ module ActiveAgent
               when Hash
                 value
               else
-                raise ArgumentError, "Cannot serialize #{value.class}"
+                  raise ArgumentError, "Cannot serialize #{value.class}"
               end
             end
+
+            # Compresses Anthropic-style content array into a string.
+            #
+            # Anthropic messages can have content as an array of blocks like:
+            # [{type: "text", text: "..."}, {type: "tool_use", ...}]
+            # This extracts and joins text blocks into a single string.
+            #
+            # @param content_array [Array<Hash>]
+            # @return [String]
+            def compress_content_array(content_array)
+              content_array.map do |block|
+                case block[:type]&.to_s
+                when "text"
+                  block[:text]
+                when "tool_use"
+                  # Tool use blocks don't have readable text content
+                  nil
+                else
+                  # Unknown block type, try to extract text if present
+                  block[:text]
+                end
+              end.compact.join("\n")
+            end
           end
 
           # Type for Messages array

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

@@ -1,27 +1,24 @@
 # frozen_string_literal: true
 
 require "active_agent/providers/common/model"
+require "active_agent/providers/common/usage"
 
 module ActiveAgent
   module Providers
     module Common
       module Responses
-        # Base response model for provider responses.
-        #
-        # This class represents the standard response structure from AI providers
-        # across different services (OpenAI, Anthropic, etc.). It provides a unified
-        # interface for accessing response data, usage statistics, and request context.
+        # Provides unified interface for AI provider responses across OpenAI, Anthropic, etc.
         #
         # @abstract Subclass and override {#usage} if provider uses non-standard format
         #
-        # @note This is a base class. Use specialized subclasses for specific response types:
-        #   - {Prompt} for conversational/completion responses with messages
-        #   - {Embed} for embedding responses with vector data
+        # @note Use specialized subclasses for specific response types:
+        #   - {Prompt} for conversational/completion responses
+        #   - {Embed} for embedding 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
@@ -33,117 +30,168 @@ module ActiveAgent
         # @see BaseModel
         class Base < BaseModel
           # @!attribute [r] context
-          #   The original context that was sent to the provider.
+          #   Original request context sent to the provider.
           #
-          #   Contains structured information about the request including instructions,
-          #   messages, tools, and other configuration passed to the LLM.
+          #   Includes instructions, messages, tools, and configuration.
           #
-          #   @return [Hash] the request context
+          #   @return [Hash]
           attribute :context, writable: false
 
           # @!attribute [r] raw_request
-          #   The most recent request in provider-specific format.
+          #   Most recent request in provider-specific format.
           #
-          #   Contains the actual API request payload sent to the provider,
-          #   useful for debugging and logging.
+          #   Useful for debugging and logging.
           #
-          #   @return [Hash] the provider-formatted request
+          #   @return [Hash]
           attribute :raw_request, writable: false
 
           # @!attribute [r] raw_response
-          #   The most recent response in provider-specific format.
+          #   Most recent response in provider-specific format.
           #
-          #   Contains the raw API response from the provider, including all
-          #   metadata, usage stats, and provider-specific fields.
+          #   Includes metadata, usage stats, and provider-specific fields.
+          #   Hash keys are deep symbolized for consistent access.
           #
-          #   @return [Hash] the provider-formatted response
+          #   @return [Hash]
           attribute :raw_response, writable: false
 
-          # Initializes a new response object with deep-duplicated attributes.
+          # @!attribute [r] usages
+          #   Usage objects from each API call in multi-turn conversations.
+          #
+          #   Each call (e.g., for tool calling) tracks usage separately. These are
+          #   summed to provide cumulative statistics via {#usage}.
           #
-          # Deep duplication ensures that the response object maintains its own
-          # independent copy of the data, preventing external modifications from
-          # affecting the response's internal state.
+          #   @return [Array<Usage>]
+          attribute :usages, default: -> { [] }, writable: false
+
+          # Initializes response with deep-duplicated attributes.
           #
-          # @param kwargs [Hash] response attributes
-          # @option kwargs [Hash] :context the original request context
-          # @option kwargs [Hash] :raw_request the provider-formatted request
-          # @option kwargs [Hash] :raw_response the provider-formatted response
+          # Deep duplication prevents external modifications from affecting internal state.
+          # The raw_response is deep symbolized for consistent key access across providers.
           #
-          # @return [Base] the initialized response object
+          # @param kwargs [Hash]
+          # @option kwargs [Hash] :context
+          # @option kwargs [Hash] :raw_request
+          # @option kwargs [Hash] :raw_response
           def initialize(kwargs = {})
-            super(kwargs.deep_dup) # Ensure that userland can't fuck with our memory space
+            kwargs = kwargs.deep_dup # Ensure that userland can't fuck with our memory space
+
+            # Deep symbolize raw_response for consistent access across all extraction methods
+            if kwargs[:raw_response].is_a?(Hash)
+              kwargs[:raw_response] = kwargs[:raw_response].deep_symbolize_keys
+            end
+
+            super(kwargs)
           end
 
-          # Extracts instructions from the context.
-          #
-          # @return [String, Array<Hash>, nil] the instructions that were sent to the provider
+          # @return [String, Array<Hash>, nil]
           def instructions
             context[:instructions]
           end
 
-          # Indicates whether the generation request was successful.
-          #
           # @todo Better handling of failure flows
-          #
-          # @return [Boolean] true if successful, false otherwise
+          # @return [Boolean]
           def success?
             true
           end
 
-          # Extracts usage statistics from the raw response.
+          # Normalized usage statistics across all providers.
+          #
+          # For multi-turn conversations with tool calling, returns cumulative
+          # usage across all API calls (sum of {#usages}).
           #
-          # 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.
+          # @return [Usage, nil]
           #
-          # @return [Hash, nil] usage statistics hash with keys like "prompt_tokens",
-          #   "completion_tokens", and "total_tokens", or nil if not available
+          # @example Single-turn usage
+          #   response.usage.input_tokens      #=> 100
+          #   response.usage.output_tokens     #=> 25
+          #   response.usage.total_tokens      #=> 125
           #
-          # @example Usage data structure
-          #   {
-          #     "prompt_tokens" => 10,
-          #     "completion_tokens" => 20,
-          #     "total_tokens" => 30
-          #   }
+          # @example Multi-turn usage (cumulative)
+          #   # After 3 API calls due to tool usage:
+          #   response.usage.input_tokens      #=> 350 (sum of all calls)
+          #   response.usage.output_tokens     #=> 120 (sum of all calls)
+          #
+          # @see Usage
           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"]
+            @usage ||= begin
+              if usages.any?
+                usages.reduce(:+)
+              elsif raw_response
+                Usage.from_provider_usage(
+                  raw_response.is_a?(Hash) ? raw_response[:usage] : raw_response.usage
+                )
+              end
             end
           end
 
-          # Extracts the number of tokens used in the prompt/input.
+          # Response ID from provider, useful for tracking and debugging.
           #
-          # @return [Integer, nil] number of prompt tokens used, or nil if unavailable
+          # @return [String, nil]
           #
           # @example
-          #   response.prompt_tokens #=> 10
-          def prompt_tokens
-            usage&.dig("prompt_tokens")
+          #   response.id  #=> "chatcmpl-CbDx1nXoNSBrNIMhiuy5fk7jXQjmT" (OpenAI)
+          #   response.id  #=> "msg_01RotDmSnYpKQjrTpaHUaEBz" (Anthropic)
+          #   response.id  #=> "gen-1761505659-yxgaVsqVABMQqw6oA7QF" (OpenRouter)
+          def id
+            @id ||= begin
+              return nil unless raw_response
+
+              if raw_response.is_a?(Hash)
+                raw_response[:id]
+              elsif raw_response.respond_to?(:id)
+                raw_response.id
+              end
+            end
           end
 
-          # Extracts the number of tokens used in the completion/output.
+          # Model name from provider response.
+          #
+          # Useful for confirming which model was actually used, as providers may
+          # use different versions than requested.
           #
-          # @return [Integer, nil] number of completion tokens used, or nil if unavailable
+          # @return [String, nil]
           #
           # @example
-          #   response.completion_tokens #=> 20
-          def completion_tokens
-            usage&.dig("completion_tokens")
+          #   response.model  #=> "gpt-4o-mini-2024-07-18"
+          #   response.model  #=> "claude-3-5-haiku-20241022"
+          def model
+            @model ||= begin
+              return nil unless raw_response
+
+              if raw_response.is_a?(Hash)
+                raw_response[:model]
+              elsif raw_response.respond_to?(:model)
+                raw_response.model
+              end
+            end
           end
 
-          # Extracts the total number of tokens used (prompt + completion).
+          # Finish reason from provider response.
+          #
+          # Indicates why generation stopped (e.g., "stop", "length", "tool_calls").
+          # Normalizes access across providers that use different field names.
           #
-          # @return [Integer, nil] total number of tokens used, or nil if unavailable
+          # @return [String, nil]
           #
           # @example
-          #   response.total_tokens #=> 30
-          def total_tokens
-            usage&.dig("total_tokens")
+          #   response.finish_reason  #=> "stop"
+          #   response.finish_reason  #=> "length"
+          #   response.finish_reason  #=> "tool_calls"
+          #   response.stop_reason    #=> "stop" (alias)
+          def finish_reason
+            @finish_reason ||= begin
+              return nil unless raw_response
+
+              if raw_response.is_a?(Hash)
+                # OpenAI format: choices[0].finish_reason or choices[0].message.finish_reason
+                raw_response.dig(:choices, 0, :finish_reason) ||
+                  raw_response.dig(:choices, 0, :message, :finish_reason) ||
+                  # Anthropic format: stop_reason
+                  raw_response[:stop_reason]
+              end
+            end
           end
+          alias_method :stop_reason, :finish_reason
         end
       end
     end