Refactor request handling across various providers to improve parameter normalization and cleanup processes

Author: sirwolfgang

lib/active_agent/providers/anthropic/request.rb

@@ -69,61 +69,42 @@ class Request < SimpleDelegator
         # @option params [Hash] :response_format custom field for JSON mode simulation
         # @raise [ArgumentError] when gem model validation fails
         def initialize(**params)
-          # Extract custom fields that gem doesn't support
+          # Step 1: Extract custom fields that gem doesn't support
           @response_format = params.delete(:response_format)
           @stream = params.delete(:stream)
 
-          # Map common format 'instructions' to Anthropic's 'system'
+          # Step 2: Map common format 'instructions' to Anthropic's 'system'
           if params.key?(:instructions)
             params[:system] = params.delete(:instructions)
           end
 
-          # Apply defaults
+          # Step 3: Apply defaults
           params = apply_defaults(params)
 
-          # Transform params for gem compatibility
+          # Step 4: Transform params for gem compatibility
           transformed = Transforms.normalize_params(params)
 
-          # Create gem model - this validates all parameters!
+          # Step 5: Create gem model - this validates all parameters!
           gem_model = ::Anthropic::Models::MessageCreateParams.new(**transformed)
 
-          # Delegate all method calls to gem model
+          # Step 6: Delegate all method calls to gem model
           super(gem_model)
         rescue ArgumentError => e
           # Re-raise with more context
           raise ArgumentError, "Invalid Anthropic request parameters: #{e.message}"
         end
 
-        # Serializes request for API call with content compression.
+        # Serializes request for API call.
         #
-        # Uses gem's JSON serialization, then removes response-only fields
-        # and compresses single text blocks to string shorthand for efficiency.
+        # Uses gem's JSON serialization and delegates cleanup to Transforms module.
         #
         # @return [Hash]
         def serialize
           # Use gem's JSON serialization (handles all nested objects)
           hash = Anthropic::Transforms.gem_to_hash(__getobj__)
 
-          # Clean up messages - remove response-only fields
-          if hash[:messages]
-            hash[:messages].each do |msg|
-              msg.delete(:id)
-              msg.delete(:model)
-              msg.delete(:stop_reason)
-              msg.delete(:stop_sequence)
-              msg.delete(:type)
-              msg.delete(:usage)
-            end
-          end
-
-          # Apply content compression for API efficiency
-          Transforms.compress_content(hash)
-
-          # Remove provider-internal fields that should not be in API request
-          hash.delete(:mcp_servers)   # Provider-level config, not API param
-          hash.delete(:stop_sequences) if hash[:stop_sequences] == []
-
-          hash
+          # Delegate cleanup to transforms module
+          Transforms.cleanup_serialized_request(hash, DEFAULTS, __getobj__)
         end
 
         # Accessor for system instructions.

lib/active_agent/providers/anthropic/transforms.rb

@@ -291,6 +291,45 @@ def compress_message_content!(msg)
             end
           end
 
+          # Cleans up serialized request for API submission.
+          #
+          # Removes response-only fields, applies content compression,
+          # removes provider-internal fields, and removes default values.
+          # Note: max_tokens is kept even if it matches default as Anthropic API requires it.
+          #
+          # @param hash [Hash] serialized request
+          # @param defaults [Hash] default values to remove
+          # @param gem_object [Object] original gem object (unused but for consistency)
+          # @return [Hash] cleaned request hash
+          def cleanup_serialized_request(hash, defaults, gem_object = nil)
+            # Remove response-only fields from messages
+            if hash[:messages]
+              hash[:messages].each do |msg|
+                msg.delete(:id)
+                msg.delete(:model)
+                msg.delete(:stop_reason)
+                msg.delete(:stop_sequence)
+                msg.delete(:type)
+                msg.delete(:usage)
+              end
+            end
+
+            # Apply content compression for API efficiency
+            compress_content(hash)
+
+            # Remove provider-internal fields that should not be in API request
+            hash.delete(:mcp_servers)   # Provider-level config, not API param
+            hash.delete(:stop_sequences) if hash[:stop_sequences] == []
+
+            # Remove default values (except max_tokens which is required by API)
+            defaults.each do |key, value|
+              next if key == :max_tokens  # Anthropic API requires max_tokens
+              hash.delete(key) if hash[key] == value
+            end
+
+            hash
+          end
+
           private
 
           # Converts single text block to string.

lib/active_agent/providers/ollama/chat/request.rb

@@ -65,26 +65,26 @@ class Request < SimpleDelegator
           # @option params [Boolean] :raw raw prompt mode
           # @raise [ArgumentError] when parameters are invalid
           def initialize(**params)
-            # Extract stream flag
+            # Step 1: Extract stream flag
             @stream = params[:stream]
 
-            # Apply defaults
+            # Step 2: Apply defaults
             params = apply_defaults(params)
 
-            # Normalize parameters and split into OpenAI vs Ollama-specific
+            # Step 3: Normalize parameters and split into OpenAI vs Ollama-specific
             openai_params, @ollama_params = Transforms.normalize_params(params)
 
-            # Validate Ollama-specific parameters
+            # Step 4: Validate Ollama-specific parameters
             validate_format(@ollama_params[:format]) if @ollama_params[:format]
             validate_options(@ollama_params[:options]) if @ollama_params[:options]
 
-            # Create gem model with OpenAI-compatible params
+            # Step 5: Create gem model with OpenAI-compatible params
             gem_model = ::OpenAI::Models::Chat::CompletionCreateParams.new(**openai_params)
 
-            # Delegate to the gem model
+            # Step 6: Delegate to the gem model
             super(gem_model)
           rescue ArgumentError => e
-            raise ArgumentError, "Invalid Ollama request parameters: #{e.message}"
+            raise ArgumentError, "Invalid Ollama Chat request parameters: #{e.message}"
           end
 
           # Serializes request for API submission

lib/active_agent/providers/ollama/embedding/request.rb

@@ -63,23 +63,23 @@ class Request < SimpleDelegator
           # @option params [Integer] :seed delegated to options
           # @raise [ArgumentError] when parameters are invalid
           def initialize(**params)
-            # Apply defaults
+            # Step 1: Apply defaults
             params = apply_defaults(params)
 
-            # Validate presence of required params before normalization
+            # Step 2: Validate presence of required params before normalization
             raise ArgumentError, "model is required" unless params[:model]
             raise ArgumentError, "input is required" unless params[:input]
 
-            # Normalize parameters and split into OpenAI vs Ollama-specific
+            # Step 3: Normalize parameters and split into OpenAI vs Ollama-specific
             openai_params, @ollama_params = Transforms.normalize_params(params)
 
-            # Create gem model with OpenAI-compatible params
+            # Step 4: Create gem model with OpenAI-compatible params
             gem_model = ::OpenAI::Models::EmbeddingCreateParams.new(**openai_params)
 
-            # Delegate to the gem model
+            # Step 5: Delegate to the gem model
             super(gem_model)
           rescue ArgumentError => e
-            raise ArgumentError, "Invalid Ollama embedding request parameters: #{e.message}"
+            raise ArgumentError, "Invalid Ollama Embedding request parameters: #{e.message}"
           end
 
           # Serializes request for API submission

lib/active_agent/providers/open_ai/chat/request.rb

@@ -69,19 +69,19 @@ class Request < SimpleDelegator
           # @option params [Array] :tools available tool definitions
           # @raise [ArgumentError] when parameters are invalid
           def initialize(**params)
-            # Extract stream flag
+            # Step 1: Extract stream flag
             @stream = params[:stream]
 
-            # Apply defaults
+            # Step 2: Apply defaults
             params = apply_defaults(params)
 
-            # Normalize all parameters (instructions, messages, response_format)
+            # Step 3: Normalize all parameters (instructions, messages, response_format)
             params = Chat::Transforms.normalize_params(params)
 
-            # Create gem model - this validates all parameters!
+            # Step 4: Create gem model - this validates all parameters!
             gem_model = ::OpenAI::Models::Chat::CompletionCreateParams.new(**params)
 
-            # Delegate all method calls to gem model
+            # Step 5: Delegate all method calls to gem model
             super(gem_model)
           rescue ArgumentError => e
             # Re-raise with more context

lib/active_agent/providers/open_ai/embedding/request.rb

@@ -12,6 +12,9 @@ module Embedding
         # Delegates to OpenAI::Models::EmbeddingCreateParams while providing
         # parameter normalization via the Transforms module
         class Request < SimpleDelegator
+          # Default parameter values applied during initialization
+          DEFAULTS = {}.freeze
+
           # Creates a new embedding request
           #
           # @param params [Hash] embedding parameters
@@ -21,18 +24,27 @@ class Request < SimpleDelegator
           # @option params [Integer, nil] :dimensions number of dimensions for output (text-embedding-3 only)
           # @option params [String, nil] :encoding_format "float" or "base64"
           # @option params [String, nil] :user unique user identifier
-          def initialize(params = {})
-            normalized_params = Transforms.normalize_params(params)
-            gem_model = ::OpenAI::Models::EmbeddingCreateParams.new(**normalized_params)
+          # @raise [ArgumentError] when parameters are invalid
+          def initialize(**params)
+            # Step 1: Normalize parameters
+            params = Transforms.normalize_params(params)
+
+            # Step 2: Create gem model - this validates all parameters!
+            gem_model = ::OpenAI::Models::EmbeddingCreateParams.new(**params)
+
+            # Step 3: Delegate all method calls to gem model
             super(gem_model)
+          rescue ArgumentError => e
+            # Re-raise with more context
+            raise ArgumentError, "Invalid OpenAI Embedding request parameters: #{e.message}"
           end
 
           # Serializes request for API submission
           #
           # @return [Hash] cleaned request hash without nil values
           def serialize
             serialized = Transforms.gem_to_hash(__getobj__)
-            Transforms.cleanup_serialized_request(serialized)
+            Transforms.cleanup_serialized_request(serialized, DEFAULTS, __getobj__)
           end
         end
       end

lib/active_agent/providers/open_ai/embedding/transforms.rb

@@ -66,10 +66,20 @@ def self.normalize_input(input)
 
           # Removes nil values from serialized request
           #
-          # @param serialized [Hash]
+          # @param serialized [Hash] serialized request
+          # @param defaults [Hash] default values to remove
+          # @param gem_object [Object] original gem object (unused but for consistency)
           # @return [Hash] cleaned request hash
-          def self.cleanup_serialized_request(serialized)
-            serialized.compact
+          def self.cleanup_serialized_request(serialized, defaults = {}, gem_object = nil)
+            # Remove nil values
+            cleaned = serialized.compact
+
+            # Remove default values
+            defaults.each do |key, value|
+              cleaned.delete(key) if cleaned[key] == value
+            end
+
+            cleaned
           end
         end
       end

lib/active_agent/providers/open_ai/responses/request.rb

@@ -48,35 +48,35 @@ class Request < SimpleDelegator
           # @option params [Integer] :max_output_tokens
           # @raise [ArgumentError] when parameters are invalid
           def initialize(**params)
-            # Extract custom fields
+            # Step 1: Extract custom fields
             @stream = params[:stream]
             @response_format = params.delete(:response_format)
 
-            # Map common format 'messages' to OpenAI Responses 'input'
+            # Step 2: Map common format 'messages' to OpenAI Responses 'input'
             if params.key?(:messages)
               params[:input] = params.delete(:messages)
             end
 
-            # Join instructions array into string (like Chat API)
+            # Step 3: Join instructions array into string (like Chat API)
             if params[:instructions].is_a?(Array)
               params[:instructions] = params[:instructions].join("\n")
             end
 
-            # Map response_format to text parameter for Responses API
+            # Step 4: Map response_format to text parameter for Responses API
             if @response_format
               params[:text] = Responses::Transforms.normalize_response_format(@response_format)
             end
 
-            # Apply defaults
+            # Step 5: Apply defaults
             params = apply_defaults(params)
 
-            # Normalize input content for gem compatibility
+            # Step 6: Normalize input content for gem compatibility
             params[:input] = Responses::Transforms.normalize_input(params[:input]) if params[:input]
 
-            # Create gem model - delegates to OpenAI gem
+            # Step 7: Create gem model - delegates to OpenAI gem
             gem_model = ::OpenAI::Models::Responses::ResponseCreateParams.new(**params)
 
-            # Delegate all method calls to gem model
+            # Step 8: Delegate all method calls to gem model
             super(gem_model)
           rescue ArgumentError => e
             # Re-raise with more context
@@ -85,22 +85,12 @@ def initialize(**params)
 
           # Serializes request for API call
           #
-          # Removes default values for minimal request body and simplifies
-          # single-element input arrays to strings where possible.
+          # Uses gem's JSON serialization and delegates cleanup to Transforms module.
           #
           # @return [Hash] cleaned request hash
           def serialize
             hash = Responses::Transforms.gem_to_hash(__getobj__)
-
-            # Remove default values that shouldn't be in the request body
-            DEFAULTS.each do |key, value|
-              hash.delete(key) if hash[key] == value
-            end
-
-            # Simplify input when possible for cleaner API requests
-            hash[:input] = Responses::Transforms.simplify_input(hash[:input]) if hash[:input]
-
-            hash
+            Responses::Transforms.cleanup_serialized_request(hash, DEFAULTS, __getobj__)
           end
 
           # @return [Array, String, Hash, nil]

lib/active_agent/providers/open_ai/responses/transforms.rb

@@ -200,6 +200,26 @@ def normalize_message(message, context: :content)
                 message
               end
             end
+
+            # Cleans up serialized request for API submission
+            #
+            # Removes default values and simplifies input where possible.
+            #
+            # @param hash [Hash] serialized request
+            # @param defaults [Hash] default values to remove
+            # @param gem_object [Object] original gem object
+            # @return [Hash] cleaned request hash
+            def cleanup_serialized_request(hash, defaults, gem_object)
+              # Remove default values that shouldn't be in the request body
+              defaults.each do |key, value|
+                hash.delete(key) if hash[key] == value
+              end
+
+              # Simplify input when possible for cleaner API requests
+              hash[:input] = simplify_input(hash[:input]) if hash[:input]
+
+              hash
+            end
           end
         end
       end

lib/active_agent/providers/open_router/request.rb

@@ -71,20 +71,20 @@ class Request < SimpleDelegator
         # @option params [Float] :repetition_penalty repetition penalty
         # @raise [ArgumentError] when parameters are invalid
         def initialize(**params)
-          # Extract stream flag
+          # Step 1: Extract stream flag
           @stream = params[:stream]
 
-          # Apply defaults
+          # Step 2: Apply defaults
           params = apply_defaults(params)
 
-          # Normalize parameters and split into OpenAI vs OpenRouter-specific
+          # Step 3: Normalize parameters and split into OpenAI vs OpenRouter-specific
           # This handles response_format special logic for structured output
           openai_params, @openrouter_params = Transforms.normalize_params(params)
 
-          # Create gem model with OpenAI-compatible params
+          # Step 4: Create gem model with OpenAI-compatible params
           gem_model = ::OpenAI::Models::Chat::CompletionCreateParams.new(**openai_params)
 
-          # Delegate to the gem model
+          # Step 5: Delegate to the gem model
           super(gem_model)
         rescue ArgumentError => e
           raise ArgumentError, "Invalid OpenRouter request parameters: #{e.message}"