activeagent 0.6.3 → 1.0.0

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/options.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      class Options < Common::BaseModel
+        attribute :api_key,         :string
+        attribute :organization,    :string # Organization ID
+        attribute :project,         :string # Project ID ,
+        attribute :webhook_secret,  :string
+        attribute :base_url,        :string
+
+        attribute :max_retries,         :integer, default: ::OpenAI::Client::DEFAULT_MAX_RETRIES
+        attribute :timeout,             :float,   default: ::OpenAI::Client::DEFAULT_TIMEOUT_IN_SECONDS
+        attribute :initial_retry_delay, :float,   default: ::OpenAI::Client::DEFAULT_INITIAL_RETRY_DELAY
+        attribute :max_retry_delay,     :float,   default: ::OpenAI::Client::DEFAULT_MAX_RETRY_DELAY
+
+        validates :api_key, presence: true
+
+        # Backwards Compatibility
+        alias_attribute :host,            :base_url
+        alias_attribute :uri_base,        :base_url
+        alias_attribute :organization_id, :organization
+        alias_attribute :project_id,      :project
+        alias_attribute :access_token,    :api_key
+        alias_attribute :request_timeout, :timeout
+
+        # Initialize from a hash (kwargs) with fallback to environment variables and OpenAI gem configuration
+        def initialize(kwargs = {})
+          kwargs = kwargs.deep_symbolize_keys if kwargs.respond_to?(:deep_symbolize_keys)
+
+          super(**deep_compact(kwargs.except(:default_url_options).merge(
+            api_key:         resolve_api_key(kwargs),
+            organization_id: resolve_organization_id(kwargs),
+            project_id:      resolve_project_id(kwargs),
+          )))
+        end
+
+        def extra_headers
+          {}
+        end
+
+        private
+
+        def resolve_api_key(kwargs)
+          kwargs[:api_key] ||
+            kwargs[:access_token] ||
+            ENV["OPENAI_API_KEY"] ||
+            ENV["OPEN_AI_API_KEY"] ||
+            ENV["OPENAI_ACCESS_TOKEN"] ||
+            ENV["OPEN_AI_ACCESS_TOKEN"]
+        end
+
+        def resolve_organization_id(kwargs)
+          kwargs[:organization] ||
+            kwargs[:organization_id] ||
+            ENV["OPENAI_ORG_ID"] ||
+            ENV["OPEN_AI_ORG_ID"] ||
+            ENV["OPENAI_ORGANIZATION_ID"] ||
+            ENV["OPEN_AI_ORGANIZATION_ID"]
+        end
+
+        def resolve_project_id(kwargs)
+          kwargs[:project] ||
+            kwargs[:project_id]
+            ENV["OPENAI_PROJECT_ID"] ||
+            ENV["OPEN_AI_PROJECT_ID"]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "request"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Responses
+        # Type for Request model
+        class RequestType < ActiveModel::Type::Value
+          def cast(value)
+            case value
+            when Request
+              value
+            when Hash
+              Request.new(**value.deep_symbolize_keys)
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot cast #{value.class} to Request"
+            end
+          end
+
+          def serialize(value)
+            case value
+            when Request
+              value.serialize
+            when Hash
+              value
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot serialize #{value.class}"
+            end
+          end
+
+          def deserialize(value)
+            cast(value)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "transforms"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Responses
+        # 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
+
+            # Step 3: Join instructions array into string (like Chat API)
+            if params[:instructions].is_a?(Array)
+              params[:instructions] = params[:instructions].join("\n")
+            end
+
+            # Step 4: Map response_format to text parameter for Responses API
+            if @response_format
+              params[:text] = Responses::Transforms.normalize_response_format(@response_format)
+            end
+
+            # 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: Create gem model - delegates to OpenAI gem
+            gem_model = ::OpenAI::Models::Responses::ResponseCreateParams.new(**params)
+
+            # Step 8: 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
+
+          # 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
+
+          # @return [Array, String, Hash, nil]
+          def messages
+            __getobj__.instance_variable_get(:@data)[:input]
+          end
+
+          # 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
+
+          alias_method :message, :messages
+          alias_method :message=, :messages=
+
+          private
+
+          # @api private
+          # @param params [Hash]
+          # @return [Hash]
+          def apply_defaults(params)
+            DEFAULTS.each do |key, value|
+              params[key] = value unless params.key?(key)
+            end
+
+            params
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/keys"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Responses
+        # Provides transformation methods for normalizing response parameters
+        # to OpenAI gem's native format
+        #
+        # Handles input normalization, message conversion, and response format
+        # transformation for the Responses API.
+        module Transforms
+          class << self
+            # Converts gem model object to hash via JSON round-trip
+            #
+            # @param gem_object [Object]
+            # @return [Hash] with symbolized keys
+            def gem_to_hash(gem_object)
+              JSON.parse(gem_object.to_json, symbolize_names: true)
+            end
+
+            # Simplifies input for cleaner API requests
+            #
+            # Unwraps single-element arrays:
+            # - `["text"]` → `"text"`
+            # - `[{type: "input_text", text: "..."}]` → `"..."`
+            # - `[{role: "user", content: "..."}]` → `"..."`
+            #
+            # @param input [Array, String, Hash]
+            # @return [String, Array, Hash]
+            def simplify_input(input)
+              return input unless input.is_a?(Array)
+
+              # Single string element - unwrap it
+              if input.size == 1 && input[0].is_a?(String)
+                return input[0]
+              end
+
+              # Single content object {type: "input_text", text: "..."} - unwrap to string
+              if input.size == 1 &&
+                 input[0].is_a?(Hash) &&
+                 input[0][:type] == "input_text" &&
+                 input[0][:text].is_a?(String) &&
+                 input[0].keys.sort == [ :text, :type ]
+                return input[0][:text]
+              end
+
+              # Single message with string content - simplify to string
+              if input.size == 1 &&
+                 input[0].is_a?(Hash) &&
+                 input[0][:role] == "user" &&
+                 input[0][:content].is_a?(String)
+                return input[0][:content]
+              end
+
+              input
+            end
+
+            # Normalizes response_format to OpenAI Responses API text parameter
+            #
+            # Maps common response_format structures to Responses API format.
+            # Returns ResponseTextConfig object to preserve proper nesting.
+            #
+            # @param format [Hash, Symbol, String]
+            # @return [OpenAI::Models::Responses::ResponseTextConfig]
+            def normalize_response_format(format)
+              text_hash = case format
+              when Hash
+                if format[:type] == "json_schema" || format[:type] == :json_schema
+                  # json_schema format: map to Responses API structure
+                  {
+                    format: {
+                      type: "json_schema",
+                      name: format[:name] || format[:json_schema]&.dig(:name),
+                      schema: format[:schema] || format[:json_schema]&.dig(:schema),
+                      strict: format[:strict] || format[:json_schema]&.dig(:strict)
+                    }.compact
+                  }
+                elsif format[:type] == "json_object" || format[:type] == :json_object
+                  # json_object format
+                  { format: { type: "json_object" } }
+                elsif format[:type]
+                  # Other simple type formats (text, etc.) - wrap in format key
+                  { format: { type: format[:type].to_s } }
+                else
+                  # Pass through other hash formats (already has format key or complex structure)
+                  format
+                end
+              when Symbol, String
+                # Simple format types
+                { format: { type: format.to_s } }
+              else
+                format
+              end
+
+              # Convert hash to ResponseTextConfig object to preserve nesting
+              ::OpenAI::Models::Responses::ResponseTextConfig.new(**text_hash)
+            end
+
+            # Normalizes input/messages to gem-compatible format
+            #
+            # Handles various input formats:
+            # - `"text"` → string (passthrough)
+            # - `{role: "user", content: "..."}` → wrapped in array
+            # - `[{text: "..."}, {image: "url"}]` → wrapped as user message with content array
+            # - `["msg1", "msg2"]` → array of user messages
+            #
+            # @param input [String, Hash, Array, Object]
+            # @return [String, Array<Hash>]
+            def normalize_input(input)
+              # String inputs pass through unchanged
+              return input if input.is_a?(String)
+
+              # Single hash should be wrapped in an array
+              if input.is_a?(Hash)
+                return [ normalize_message(input) ]
+              end
+
+              # Handle arrays
+              return input unless input.respond_to?(:map)
+
+              # Check if this is an array of content items (strings or text/image/document hashes)
+              # Content items don't have a :role key (messages do)
+              # BUT NOT a single string (which should have been caught above)
+              all_content_items = input.size > 1 && input.all? do |item|
+                if item.is_a?(String)
+                  true
+                elsif item.is_a?(Hash)
+                  # If it has a role, it's a message, not a content item
+                  !item.key?(:role) && (item.key?(:text) || item.key?(:image) || item.key?(:document))
+                else
+                  false
+                end
+              end
+
+              if all_content_items
+                # These are multiple content items, wrap in a user message
+                content = input.map { |item| normalize_message(item) }
+                return [ { role: "user", content: content } ]
+              end
+
+              # Otherwise treat as array of messages
+              input.map { |item| normalize_message(item, context: :input) }
+            end
+
+            # Normalizes a single message to hash format
+            #
+            # Handles shorthand formats:
+            # - `{text: "..."}` → user message
+            # - `{image: "url"}` → input_image content part
+            # - `{document: "url"}` → input_file content part
+            #
+            # @param message [Hash, String, Object]
+            # @param context [Symbol] :input for messages, :content for content parts
+            # @return [Hash, String]
+            def normalize_message(message, context: :content)
+              # If it's our custom model object, serialize it
+              if message.respond_to?(:serialize)
+                message.serialize
+              elsif message.is_a?(Hash)
+                # If it has a role, it's a message - convert :text to :content
+                if message.key?(:role)
+                  normalized = message.dup
+                  if normalized.key?(:text) && !normalized.key?(:content)
+                    normalized[:content] = normalized.delete(:text)
+                  end
+                  return normalized
+                end
+
+                # Expand shorthand formats to full structures for content items
+                if message.key?(:image)
+                  { type: "input_image", image_url: message[:image] }
+                elsif message.key?(:document)
+                  document_value = message[:document]
+                  if document_value.start_with?("data:")
+                    { type: "input_file", filename: "document.pdf", file_data: document_value }
+                  else
+                    { type: "input_file", file_url: document_value }
+                  end
+                elsif message.key?(:text) && message.size == 1
+                  # Single :text key without :role - treat as user message
+                  { role: "user", content: message[:text] }
+                elsif message.key?(:text)
+                  # Bare text content item with other keys
+                  { type: "input_text", text: message[:text] }
+                else
+                  message
+                end
+              elsif message.is_a?(String)
+                # Context matters: in input array, strings become messages; in content array, they become input_text
+                if context == :input
+                  { role: "user", content: message }
+                else
+                  { type: "input_text", text: message }
+                end
+              else
+                # Pass through anything else
+                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
+    end
+  end
+end