activeagent 1.0.0.rc1 → 1.0.1

data/lib/active_agent/providers/open_ai/embedding/_types.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
-require_relative "requests/_types"
 require_relative "request"
 
 module ActiveAgent
   module Providers
     module OpenAI
       module Embedding
-        # Type for Request model
+        # ActiveModel type for casting and serializing embedding requests
         class RequestType < ActiveModel::Type::Value
+          # Casts value to Request object
+          #
+          # @param value [Request, Hash, nil]
+          # @return [Request, nil]
+          # @raise [ArgumentError] when value cannot be cast
           def cast(value)
             case value
             when Request
@@ -22,6 +26,11 @@ module ActiveAgent
             end
           end
 
+          # Serializes Request to hash for API submission
+          #
+          # @param value [Request, Hash, nil]
+          # @return [Hash, nil]
+          # @raise [ArgumentError] when value cannot be serialized
           def serialize(value)
             case value
             when Request
@@ -35,6 +44,8 @@ module ActiveAgent
             end
           end
 
+          # @param value [Object]
+          # @return [Request, nil]
           def deserialize(value)
             cast(value)
           end

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

@@ -1,82 +1,50 @@
 # frozen_string_literal: true
 
-require "active_agent/providers/common/model"
-require_relative "_types"
+require "json"
+require_relative "transforms"
 
 module ActiveAgent
   module Providers
     module OpenAI
       module Embedding
-        class Request < Common::BaseModel
-          # Input text to embed (required)
-          # Can be a string or array of strings or array of token arrays
-          # - Must not exceed max input tokens for the model (8192 for all embedding models)
-          # - Cannot be an empty string
-          # - Arrays must be 2048 dimensions or less
-          # - Maximum of 300,000 tokens summed across all inputs in a single request
-          attribute :input, Requests::InputType.new
-
-          # Model ID (required)
-          attribute :model, :string
-
-          # Number of dimensions for output embeddings (optional)
-          # Only supported in text-embedding-3 and later models
-          attribute :dimensions, :integer
-
-          # Format for returned embeddings (optional)
-          # Can be "float" or "base64"
-          attribute :encoding_format, :string, default: "float"
-
-          # Unique identifier for end-user (optional, deprecated)
-          # Can help OpenAI monitor and detect abuse
-          attribute :user, :string
-
-          # Validations
-          validates :input, :model,   presence: true
-          validates :encoding_format, inclusion: { in: %w[float base64] }, allow_nil: true
-          validates :dimensions,      numericality: { greater_than: 0 },   allow_nil: true
-
-          # Custom validations
-          validate :validate_input_format
-          validate :validate_input_not_empty
-
-          private
-
-          def validate_input_format
-            return if input.nil?
-
-            unless input.is_a?(Array)
-              errors.add(:input, "must be stored as an array internally")
-              return
-            end
-
-            # Validate array contents
-            input.each_with_index do |item, index|
-              case item
-              when String
-                if item.empty?
-                  errors.add(:input, "cannot contain empty strings at index #{index}")
-                end
-              when Array
-                # Token array validation
-                if item.length > 2048
-                  errors.add(:input, "token arrays must be 2048 dimensions or less at index #{index}")
-                end
-                if item.empty?
-                  errors.add(:input, "cannot contain empty token arrays at index #{index}")
-                end
-              else
-                errors.add(:input, "array elements must be strings or token arrays at index #{index}")
-              end
-            end
+        # Wraps OpenAI gem's EmbeddingCreateParams with normalization
+        #
+        # 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
+          # @option params [String, Array<String>, Array<Integer>, Array<Array<Integer>>] :input
+          #   text or token array(s) to embed
+          # @option params [String] :model embedding model identifier
+          # @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
+          # @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
 
-          def validate_input_not_empty
-            return if input.nil?
-
-            if input.is_a?(Array) && input.empty?
-              errors.add(:input, "cannot be an empty array")
-            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, DEFAULTS, __getobj__)
           end
         end
       end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      # Handles transformation and normalization of embedding request parameters
+      # for the OpenAI Embeddings API
+      module Embedding
+        # Provides transformation methods for normalizing embedding parameters
+        # to OpenAI gem's native format
+        module Transforms
+          # Converts OpenAI gem objects to hash representation
+          #
+          # @param obj [Object] gem object or primitive value
+          # @return [Hash, Object] hash if object supports JSON serialization, otherwise original object
+          def self.gem_to_hash(obj)
+            if obj.respond_to?(:to_json)
+              JSON.parse(obj.to_json)
+            else
+              obj
+            end
+          end
+
+          # Normalizes all embedding request parameters
+          #
+          # @param params [Hash] raw request parameters
+          # @return [Hash] normalized parameters
+          def self.normalize_params(params)
+            normalized = params.dup
+
+            if normalized[:input]
+              normalized[:input] = normalize_input(normalized[:input])
+            end
+
+            normalized
+          end
+
+          # Normalizes input parameter to supported format
+          #
+          # Handles multiple input formats:
+          # - `"text"` - single string for one embedding
+          # - `["text1", "text2"]` - array of strings for multiple embeddings
+          # - `[1, 2, 3]` - token array for single embedding
+          # - `[[1, 2], [3, 4]]` - array of token arrays for multiple embeddings
+          #
+          # @param input [String, Array<String>, Array<Integer>, Array<Array<Integer>>]
+          # @return [String, Array] normalized input in gem-compatible format
+          def self.normalize_input(input)
+            case input
+            when String
+              input
+            when Array
+              if input.empty?
+                input
+              elsif input.first.is_a?(Integer)
+                input
+              elsif input.first.is_a?(Array)
+                input
+              else
+                input
+              end
+            else
+              input
+            end
+          end
+
+          # Removes nil values from serialized request
+          #
+          # @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, 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
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/responses/_types.rb

@@ -24,13 +24,7 @@ module ActiveAgent
           def serialize(value)
             case value
             when Request
-              hash = value.serialize
-
-              if hash[:input] in [ { role: "user", content: String } ]
-                hash[:input] = hash[:input][0][:content]
-              end
-
-              hash
+              value.serialize
             when Hash
               value
             when nil

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

@@ -1,160 +1,141 @@
 # frozen_string_literal: true
 
-require "active_agent/providers/common/model"
-require_relative "requests/_types"
+require_relative "transforms"
 
 module ActiveAgent
   module Providers
     module OpenAI
       module Responses
-        class Request < Common::BaseModel
-          # Background execution
-          attribute :background, :boolean, default: false
-
-          # Conversation
-          attribute :conversation, Requests::ConversationType.new
-
-          # Include additional output data
-          attribute :include, default: -> { [] } # Array of strings
-
-          # Input items (text, image, or file inputs)
-          attribute :input, Requests::Inputs::MessagesType.new
-
-          # Instructions (system/developer message)
-          attribute :instructions, :string
-
-          # Token limits
-          attribute :max_output_tokens, :integer
-          attribute :max_tool_calls, :integer
-
-          # Metadata
-          attribute :metadata # Hash of key-value pairs
-
-          # Model ID
-          attribute :model, :string
-
-          # Parallel tool calls
-          attribute :parallel_tool_calls, :boolean, default: true
-
-          # Previous response ID for multi-turn conversations
-          attribute :previous_response_id, :string
-
-          # Prompt template reference
-          attribute :prompt, Requests::PromptReferenceType.new
-
-          # Cache key for optimization
-          attribute :prompt_cache_key, :string
-
-          # Reasoning configuration (for o-series and gpt-5 models)
-          attribute :reasoning, Requests::ReasoningType.new
-
-          # Safety identifier for usage policy detection
-          attribute :safety_identifier, :string
-
-          # Service tier
-          attribute :service_tier, :string, default: "auto"
-
-          # Storage
-          attribute :store, :boolean, default: true
-
-          # Streaming
-          attribute :stream, :boolean, default: false
-          attribute :stream_options, Requests::StreamOptionsType.new
-
-          # Temperature sampling
-          attribute :temperature, :float, default: 1
-
-          # Text response configuration
-          attribute :text, Requests::TextType.new
-
-          # Tool choice
-          attribute :tool_choice, Requests::ToolChoiceType.new
-
-          # Tools array
-          attribute :tools, Requests::Tools::ToolsType.new
-
-          # Top logprobs
-          attribute :top_logprobs, :integer
-
-          # Top P sampling
-          attribute :top_p, :float, default: 1
-
-          # Truncation strategy
-          attribute :truncation, :string, default: "disabled"
+        # Wraps OpenAI gem's ResponseCreateParams with field mapping and normalization
+        #
+        # Delegates to OpenAI::Models::Responses::ResponseCreateParams while providing
+        # compatibility layer for common format fields and content normalization:
+        # - `messages` → `input`
+        # - `response_format` → `text` (via ResponseTextConfig)
+        # - Instructions array joined to string
+        class Request < SimpleDelegator
+          # Default parameter values applied during initialization
+          DEFAULTS = {
+            service_tier: "auto",
+            store: true,
+            temperature: 1.0,
+            top_p: 1.0,
+            truncation: "disabled",
+            parallel_tool_calls: true,
+            background: false,
+            include: []
+          }.freeze
+
+          # @return [Boolean, nil]
+          attr_reader :stream
+
+          # @return [Hash, nil]
+          attr_reader :response_format
+
+          # Creates a new response creation request
+          #
+          # Maps common format fields to Responses API format:
+          # - `messages` → `input`
+          # - `response_format` → `text` parameter
+          # - Instructions array → joined string
+          #
+          # @param params [Hash] request parameters
+          # @option params [String] :model required model identifier
+          # @option params [Array, String, Hash] :input messages or content
+          # @option params [Array, String, Hash] :messages alternative to :input (mapped automatically)
+          # @option params [Hash, String, Symbol] :response_format
+          # @option params [Array<String>, String] :instructions
+          # @option params [Integer] :max_output_tokens
+          # @raise [ArgumentError] when parameters are invalid
+          def initialize(**params)
+            # Step 1: Extract custom fields
+            @stream = params[:stream]
+            @response_format = params.delete(:response_format)
+
+            # Step 2: Map common format 'messages' to OpenAI Responses 'input'
+            if params.key?(:messages)
+              params[:input] = params.delete(:messages)
+            end
 
-          # User identifier (deprecated, use safety_identifier or prompt_cache_key)
-          attribute :user, :string
+            # Step 3: Join instructions array into string (like Chat API)
+            if params[:instructions].is_a?(Array)
+              params[:instructions] = params[:instructions].join("\n")
+            end
 
-          # Validations
-          validates :max_output_tokens, numericality: { greater_than: 0 },                                        allow_nil: true
-          validates :max_tool_calls,    numericality: { greater_than: 0 },                                        allow_nil: true
-          validates :temperature,       numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 2 },  allow_nil: true
-          validates :top_p,             numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 },  allow_nil: true
-          validates :top_logprobs,      numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 20 }, allow_nil: true
-          validates :service_tier,      inclusion: { in: %w[auto default flex priority] },                        allow_nil: true
-          validates :truncation,        inclusion: { in: %w[auto disabled] },                                     allow_nil: true
+            # Step 4: Map response_format to text parameter for Responses API
+            if @response_format
+              params[:text] = Responses::Transforms.normalize_response_format(@response_format)
+            end
 
-          validate :validate_conversation_exclusivity
-          validate :validate_metadata_format
-          validate :validate_include_values
+            # Step 5: Apply defaults
+            params = apply_defaults(params)
+
+            # Step 6: Normalize input content for gem compatibility
+            params[:input] = Responses::Transforms.normalize_input(params[:input]) if params[:input]
+
+            # Step 7: Normalize tools and tool_choice from common format
+            params[:tools] = Responses::Transforms.normalize_tools(params[:tools]) if params[:tools]
+            params[:tool_choice] = Responses::Transforms.normalize_tool_choice(params[:tool_choice]) if params[:tool_choice]
+
+            # Step 8: Normalize MCP servers from common format (mcps parameter)
+            # OpenAI treats MCP servers as a special type of tool in the tools array
+            mcp_param = params[:mcps] || params[:mcp_servers]
+            if mcp_param&.any?
+              normalized_mcp_tools = Responses::Transforms.normalize_mcp_servers(mcp_param)
+              params.delete(:mcps)
+              params.delete(:mcp_servers)
+              # Merge MCP servers into tools array
+              params[:tools] = (params[:tools] || []) + normalized_mcp_tools
+            end
 
-          # Common Format Mapping
-          alias_attribute :messages,        :input
-          alias_attribute :message,         :input
-          alias_attribute :response_format, :text
+            # Step 9: Create gem model - delegates to OpenAI gem
+            gem_model = ::OpenAI::Models::Responses::ResponseCreateParams.new(**params)
 
-          # Common Format Compatability
-          def instructions=(value)
-            super(value.is_a?(Array) ? value.join("\n") : value)
+            # Step 10: Delegate all method calls to gem model
+            super(gem_model)
+          rescue ArgumentError => e
+            # Re-raise with more context
+            raise ArgumentError, "Invalid OpenAI Responses request parameters: #{e.message}"
           end
 
-          private
+          # Serializes request for API call
+          #
+          # 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__)
+            Responses::Transforms.cleanup_serialized_request(hash, DEFAULTS, __getobj__)
+          end
 
-          def validate_conversation_exclusivity
-            if conversation.present? && previous_response_id.present?
-              errors.add(:base, "Cannot use both conversation and previous_response_id")
-            end
+          # @return [Array, String, Hash, nil]
+          def messages
+            __getobj__.instance_variable_get(:@data)[:input]
           end
 
-          def validate_metadata_format
-            return if metadata.nil?
+          # Sets input messages with normalization
+          #
+          # @param value [Array, String, Hash]
+          # @return [void]
+          def messages=(value)
+            normalized_value = Responses::Transforms.normalize_input(value)
+            __getobj__.instance_variable_get(:@data)[:input] = normalized_value
+          end
 
-            unless metadata.is_a?(Hash)
-              errors.add(:metadata, "must be a hash")
-              return
-            end
+          alias_method :message, :messages
+          alias_method :message=, :messages=
 
-            metadata.each do |key, value|
-              if key.to_s.length > 64
-                errors.add(:metadata, "keys must be 64 characters or less")
-              end
-              if value.to_s.length > 512
-                errors.add(:metadata, "values must be 512 characters or less")
-              end
-            end
+          private
 
-            if metadata.size > 16
-              errors.add(:metadata, "must have 16 key-value pairs or less")
+          # @api private
+          # @param params [Hash]
+          # @return [Hash]
+          def apply_defaults(params)
+            DEFAULTS.each do |key, value|
+              params[key] = value unless params.key?(key)
             end
-          end
 
-          def validate_include_values
-            return if include.nil? || include.empty?
-
-            valid_include_values = [
-              "web_search_call.action.sources",
-              "code_interpreter_call.outputs",
-              "computer_call_output.output.image_url",
-              "file_search_call.results",
-              "message.input_image.image_url",
-              "message.output_text.logprobs",
-              "reasoning.encrypted_content"
-            ]
-
-            invalid_values = include - valid_include_values
-            if invalid_values.any?
-              errors.add(:include, "contains invalid values: #{invalid_values.join(', ')}")
-            end
+            params
           end
         end
       end