activeagent 0.6.3 → 1.0.0

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

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/keys"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        # Provides transformation methods for normalizing chat parameters
+        # to OpenAI gem's native format
+        #
+        # Handles message normalization, shorthand formats, instructions mapping,
+        # and response format conversion for the Chat Completions 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
+
+            # Normalizes all request parameters for OpenAI Chat API
+            #
+            # Handles instructions mapping to developer messages, message normalization,
+            # and response_format conversion. This is the main entry point for parameter
+            # transformation.
+            #
+            # @param params [Hash]
+            # @return [Hash] normalized parameters
+            def normalize_params(params)
+              params = params.dup
+
+              # Map common format 'instructions' to developer messages
+              if params.key?(:instructions)
+                instructions_messages = normalize_instructions(params.delete(:instructions))
+                params[:messages] = instructions_messages + Array(params[:messages] || [])
+              end
+
+              # Normalize messages for gem compatibility
+              params[:messages] = normalize_messages(params[:messages]) if params[:messages]
+
+              # Normalize response_format if present
+              params[:response_format] = normalize_response_format(params[:response_format]) if params[:response_format]
+
+              params
+            end
+
+            # Normalizes messages to OpenAI Chat API format using gem message classes
+            #
+            # Handles various input formats:
+            # - `"text"` → UserMessageParam
+            # - `[{role: "user", content: "..."}]` → array of message params
+            # - Merges consecutive same-role messages into single message
+            #
+            # @param messages [Array, String, Hash, nil]
+            # @return [Array<OpenAI::Models::Chat::ChatCompletionMessageParam>, nil]
+            def normalize_messages(messages)
+              case messages
+              when String
+                [ create_message_param("user", messages) ]
+              when Hash
+                [ normalize_message(messages) ]
+              when Array
+                grouped = []
+
+                messages.each do |msg|
+                  normalized = normalize_message(msg)
+
+                  if grouped.empty? || grouped.last.role != normalized.role
+                    grouped << normalized
+                  else
+                    # Merge consecutive same-role messages
+                    merged_content = merge_content(grouped.last.content, normalized.content)
+                    grouped[-1] = create_message_param(grouped.last.role, merged_content)
+                  end
+                end
+
+                grouped
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot normalize #{messages.class} to messages array"
+              end
+            end
+
+            # Normalizes a single message to proper gem message param class
+            #
+            # Handles shorthand formats:
+            # - `"text"` → user message
+            # - `{text: "..."}` → user message
+            # - `{role: "system", text: "..."}` → system message
+            # - `{image: "url"}` → user message with image content part
+            # - `{text: "...", image: "url"}` → user message with text and image parts
+            #
+            # @param message [String, Hash, OpenAI::Models::Chat::ChatCompletionMessageParam]
+            # @return [OpenAI::Models::Chat::ChatCompletionMessageParam]
+            def normalize_message(message)
+              case message
+              when String
+                create_message_param("user", message)
+              when ::OpenAI::Models::Chat::ChatCompletionMessageParam
+                # Already a gem message param - pass through
+                message
+              when Hash
+                msg_hash = message.deep_symbolize_keys
+                role = msg_hash[:role]&.to_s || "user"
+
+                # Handle shorthand formats
+                content = if msg_hash.key?(:content)
+                  # Standard format with explicit content
+                  msg_hash[:content]
+                elsif msg_hash.key?(:text) && msg_hash.key?(:image)
+                  # Shorthand with both text and image: { text: "...", image: "url" }
+                  [
+                    { type: "text", text: msg_hash[:text] },
+                    { type: "image_url", image_url: { url: msg_hash[:image] } }
+                  ]
+                elsif msg_hash.key?(:image)
+                  # Shorthand with only image: { image: "url" }
+                  # Text comes from adjacent prompt arguments
+                  [ { type: "image_url", image_url: { url: msg_hash[:image] } } ]
+                elsif msg_hash.key?(:text)
+                  # Shorthand: { text: "..." } or { role: "...", text: "..." }
+                  msg_hash[:text]
+                else
+                  # No content specified
+                  nil
+                end
+
+                # Create appropriate message param based on role and content
+                extra_params = msg_hash.except(:role, :content, :text, :image)
+                create_message_param(role, content, extra_params)
+              else
+                raise ArgumentError, "Cannot normalize #{message.class} to message"
+              end
+            end
+
+            # Creates the appropriate gem message param class for the given role
+            #
+            # @param role [String] message role (developer, system, user, assistant, tool, function)
+            # @param content [String, Array, Hash, nil]
+            # @param extra_params [Hash] additional parameters (tool_call_id, name, etc.)
+            # @return [OpenAI::Models::Chat::ChatCompletionMessageParam]
+            # @raise [ArgumentError] when role is unknown
+            def create_message_param(role, content, extra_params = {})
+              params = { role: role }
+              params[:content] = normalize_content(content) if content
+              params.merge!(extra_params)
+
+              case role.to_s
+              when "developer"
+                ::OpenAI::Models::Chat::ChatCompletionDeveloperMessageParam.new(**params)
+              when "system"
+                ::OpenAI::Models::Chat::ChatCompletionSystemMessageParam.new(**params)
+              when "user"
+                ::OpenAI::Models::Chat::ChatCompletionUserMessageParam.new(**params)
+              when "assistant"
+                ::OpenAI::Models::Chat::ChatCompletionAssistantMessageParam.new(**params)
+              when "tool"
+                ::OpenAI::Models::Chat::ChatCompletionToolMessageParam.new(**params)
+              when "function"
+                ::OpenAI::Models::Chat::ChatCompletionFunctionMessageParam.new(**params)
+              else
+                raise ArgumentError, "Unknown message role: #{role}"
+              end
+            end
+
+            # Normalizes message content to Chat API format
+            #
+            # @param content [String, Array, Hash, nil]
+            # @return [String, Array, nil]
+            # @raise [ArgumentError] when content type is invalid
+            def normalize_content(content)
+              case content
+              when String
+                content
+              when Array
+                content.map { |part| normalize_content_part(part) }
+              when Hash
+                # Single content part as hash - wrap in array
+                [ normalize_content_part(content) ]
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot normalize #{content.class} to content"
+              end
+            end
+
+            # Normalizes a single content part
+            #
+            # Converts strings to proper content part format with type and text keys.
+            #
+            # @param part [Hash, String]
+            # @return [Hash] content part with symbolized keys
+            # @raise [ArgumentError] when part type is invalid
+            def normalize_content_part(part)
+              case part
+              when Hash
+                part.deep_symbolize_keys
+              when String
+                { type: "text", text: part }
+              else
+                raise ArgumentError, "Cannot normalize #{part.class} to content part"
+              end
+            end
+
+            # Merges two content values for consecutive same-role messages
+            #
+            # Preserves multiple text parts and mixed content as array structure
+            # rather than concatenating strings.
+            #
+            # @param content1 [String, Array, nil]
+            # @param content2 [String, Array, nil]
+            # @return [Array] merged content parts
+            def merge_content(content1, content2)
+              # Convert to arrays for consistent handling
+              arr1 = content_to_array(content1)
+              arr2 = content_to_array(content2)
+
+              merged = arr1 + arr2
+
+              # Keep as array of content parts - don't simplify to string
+              # This preserves multiple text parts and mixed content
+              merged
+            end
+
+            # Converts content to array format for merging
+            #
+            # @param content [String, Array, nil]
+            # @return [Array<Hash>] content parts with type and text keys
+            def content_to_array(content)
+              case content
+              when String
+                [ { type: "text", text: content } ]
+              when Array
+                content.map { |part| part.is_a?(String) ? { type: "text", text: part } : part }
+              when nil
+                []
+              else
+                [ content ]
+              end
+            end
+
+            # Simplifies messages for cleaner API requests
+            #
+            # Converts gem message objects to hashes and simplifies content:
+            # - Single text content arrays → strings
+            # - Empty content arrays → removed
+            #
+            # @param messages [Array]
+            # @return [Array<Hash>]
+            def simplify_messages(messages)
+              return messages unless messages.is_a?(Array)
+
+              messages.map do |msg|
+                # Convert to hash if it's a gem object
+                simplified = msg.is_a?(Hash) ? msg.dup : gem_to_hash(msg)
+
+                # Simplify content if it's a single text part
+                if simplified[:content].is_a?(Array) && simplified[:content].size == 1
+                  part = simplified[:content][0]
+                  if part.is_a?(Hash) && part[:type] == "text" && part.keys.sort == [ :text, :type ]
+                    simplified[:content] = part[:text]
+                  end
+                end
+
+                # Remove empty content arrays
+                simplified.delete(:content) if simplified[:content] == []
+
+                simplified
+              end
+            end
+
+            # Normalizes response_format to OpenAI Chat API format
+            #
+            # @param format [Hash, Symbol, String]
+            # @return [Hash] normalized response format
+            def normalize_response_format(format)
+              case format
+              when Hash
+                format_hash = format.deep_symbolize_keys
+
+                if format_hash[:type] == "json_schema" || format_hash[:type] == :json_schema
+                  # json_schema format
+                  {
+                    type: "json_schema",
+                    json_schema: {
+                      name: format_hash[:name] || format_hash[:json_schema]&.dig(:name),
+                      schema: format_hash[:schema] || format_hash[:json_schema]&.dig(:schema),
+                      strict: format_hash[:strict] || format_hash[:json_schema]&.dig(:strict)
+                    }.compact
+                  }
+                elsif format_hash[:type]
+                  # Other type formats (json_object, text, etc.)
+                  { type: format_hash[:type].to_s }
+                else
+                  # Pass through (already properly structured or complex)
+                  format_hash
+                end
+              when Symbol, String
+                # Simple string type
+                { type: format.to_s }
+              else
+                format
+              end
+            end
+
+            # Normalizes instructions to developer message format
+            #
+            # Converts instructions into developer messages with proper content structure.
+            # Multiple instructions become content parts in a single developer message
+            # rather than separate messages.
+            #
+            # @param instructions [Array<String>, String]
+            # @return [Array<Hash>] developer messages
+            def normalize_instructions(instructions)
+              instructions_array = Array(instructions)
+
+              # Convert multiple instructions into content parts for a single developer message
+              if instructions_array.size > 1
+                content_parts = instructions_array.map do |instruction|
+                  { type: "text", text: instruction }
+                end
+                [ { role: "developer", content: content_parts } ]
+              else
+                instructions_array.map do |instruction|
+                  { role: "developer", content: instruction }
+                end
+              end
+            end
+
+            # Cleans up serialized hash for API request
+            #
+            # Removes default values, simplifies messages, and handles special cases
+            # like web_search_options (which requires empty hash to enable).
+            #
+            # @param hash [Hash] serialized request hash
+            # @param defaults [Hash] default values to remove
+            # @param gem_object [Object] original gem object for checking values
+            # @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 messages for cleaner API requests
+              hash[:messages] = simplify_messages(hash[:messages]) if hash[:messages]
+
+              # Add web_search_options if present (defaults to empty hash to enable feature)
+              if gem_object.instance_variable_get(:@data)[:web_search_options]
+                hash[:web_search_options] ||= {}
+              end
+
+              hash
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat_provider.rb

@@ -0,0 +1,219 @@
+require_relative "_base"
+require_relative "chat/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      # Provider implementation for OpenAI's Chat Completions API
+      #
+      # Handles chat-based interactions including streaming responses,
+      # function/tool calling, and message management.
+      #
+      # @see Base
+      # @see https://platform.openai.com/docs/api-reference/chat
+      class ChatProvider < Base
+        # @return [Class] the options class for this provider
+        def self.options_klass
+          Options
+        end
+
+        # @return [Chat::RequestType] request type instance for chat completions
+        def self.prompt_request_type
+          Chat::RequestType.new
+        end
+
+        protected
+
+        # @return [OpenAI::Client::Completions] the API client for chat completions
+        # @see Base#api_prompt_executer
+        def api_prompt_executer
+          client.chat.completions
+        end
+
+        # @see BaseProvider#api_response_normalize
+        # @param api_response [OpenAI::Models::ChatCompletion]
+        # @return [Hash] normalized response hash
+        def api_response_normalize(api_response)
+          return api_response unless api_response
+
+          Chat::Transforms.gem_to_hash(api_response)
+        end
+
+        # Processes streaming response chunks from OpenAI's chat API
+        #
+        # Handles message deltas, content updates, and completion detection.
+        # Manages the message stack and broadcasts streaming updates.
+        #
+        # Event types handled:
+        # - `:chunk` - message content and tool call deltas
+        # - `:"content.delta"` - incremental content updates
+        # - `:"content.done"` - complete content delivery
+        # - `:"tool_calls.function.arguments.delta"` - tool argument deltas
+        # - `:"tool_calls.function.arguments.done"` - complete tool arguments
+        #
+        # @param api_response_event [OpenAI::Helpers::Streaming::ChatChunkEvent]
+        # @return [void]
+        # @see Base#process_stream_chunk
+        def process_stream_chunk(api_response_event)
+          instrument("stream_chunk.active_agent")
+
+          # Called Multiple Times: [Chunk<T>, T]<Content, ToolsCall>
+          case api_response_event.type
+          when :chunk
+            api_message = api_response_event.chunk.choices.first
+
+            # If we have a delta, we need to update a message in the stack
+            message = find_or_create_message(api_message.index)
+            message = message_merge_delta(message, api_message.delta.as_json.deep_symbolize_keys)
+
+            # Stream back content changes as they come in
+            if api_message.delta.content
+              broadcast_stream_update(message_stack.last, api_message.delta.content)
+            end
+          when :"content.delta"
+            # Returns the deltas, without context
+            # => {type: :"content.delta", delta: "", snapshot: "", parsed: nil}
+            # => {type: :"content.delta", delta: "Hi", snapshot: "Hi", parsed: nil}
+          when :"content.done"
+            # Returns the full content when complete
+            # => {type: :"content.done", content: "Hi there! How can I help you today?", parsed: nil}
+
+            # Once we are finished, close out and run tooling callbacks (Recursive)
+            process_prompt_finished
+          when :"tool_calls.function.arguments.delta"
+            # => {type: :"tool_calls.function.arguments.delta", name: "get_current_weather", index: 0, arguments: "", parsed: nil, arguments_delta: ""}
+          when :"tool_calls.function.arguments.done"
+            # => => {type: :"tool_calls.function.arguments.done", index: 0, name: "get_current_weather", arguments: "{\"location\":\"Boston, MA\"}", parsed: nil}
+          else
+            fail "Unexpected Response Event Type: #{api_response_event.type}"
+          end
+        end
+
+        # Processes function/tool calls from the API response
+        #
+        # Executes each tool call and creates tool response messages
+        # for the next iteration of the conversation.
+        #
+        # @param api_function_calls [Array<Hash>] function calls with :type, :id, and :function keys
+        # @return [void]
+        # @see Base#process_function_calls
+        def process_function_calls(api_function_calls)
+          api_function_calls.each do |api_function_call|
+            content = instrument("tool_call.active_agent", tool_name: api_function_call.dig(:function, :name)) do
+              case api_function_call[:type]
+              when "function"
+                process_tool_call_function(api_function_call[:function])
+              else
+                fail "Unexpected Tool Call Type: #{api_function_call[:type]}"
+              end
+            end
+
+            # Create tool message using gem's message param class
+            message = ::OpenAI::Models::Chat::ChatCompletionToolMessageParam.new(
+              role: "tool",
+              tool_call_id: api_function_call[:id],
+              content: content.to_json
+            )
+
+            # Serialize and push to message stack
+            message_hash = Chat::Transforms.gem_to_hash(message)
+            message_stack.push(message_hash)
+          end
+        end
+
+        # Extracts messages from the completed API response.
+        # Converts OpenAI gem response object to hash for storage.
+        #
+        # @param api_response [OpenAI::Models::Chat::ChatCompletion]
+        # @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 ? Chat::Transforms.gem_to_hash(api_response) : nil
+          super(api_response_hash)
+        end
+
+        # Extracts messages from completed API response.
+        #
+        # @param api_response [Hash] converted response hash
+        # @return [Array<Hash>, nil] single-element array with message or nil if no message
+        # @see Base#process_prompt_finished_extract_messages
+        def process_prompt_finished_extract_messages(api_response)
+          return unless api_response
+
+          api_message = api_response[:choices][0][:message]
+
+          [ api_message ]
+        end
+
+        # Extracts function calls from the last message in the stack.
+        #
+        # @return [Array<Hash>, nil] tool call objects or nil if no tool calls
+        # @see Base#process_prompt_finished_extract_function_calls
+        def process_prompt_finished_extract_function_calls
+          message_stack.last[:tool_calls]
+        end
+
+        # Merges streaming delta into a message
+        #
+        # Separated from hash_merge_delta to allow Ollama to override role handling.
+        #
+        # @param message [Hash]
+        # @param delta [Hash]
+        # @return [Hash] merged message
+        def message_merge_delta(message, delta)
+          hash_merge_delta(message, delta)
+        end
+
+        private
+
+        # Finds an existing message by index or creates a new one
+        #
+        # @param id [Integer]
+        # @return [Hash] found or newly created message
+        def find_or_create_message(id)
+          message = message_stack.find { _1[:index] == id }
+          return message if message
+
+          message_stack << { index: id }
+          message_stack.last
+        end
+
+        # Recursively merges delta changes into a hash structure
+        #
+        # Handles complex delta merging for OpenAI's streaming API, including
+        # arrays with indexed items and string concatenation.
+        #
+        # @param hash [Hash] target hash to merge into
+        # @param delta [Hash] delta changes to apply
+        # @return [Hash] merged hash
+        def hash_merge_delta(hash, delta)
+          delta.each do |key, value|
+            case hash[key]
+            when Hash
+              hash[key] = hash_merge_delta(hash[key], value)
+            when Array
+              value.each do |delta_item|
+                if delta_item.is_a?(Hash) && delta_item[:index]
+                  hash_item = hash[key].find { _1[:index] == delta_item[:index] }
+                  if hash_item
+                    hash_merge_delta(hash_item, delta_item)
+                  else
+                    hash[key] << delta_item
+                  end
+                else
+                  hash[key] << delta_item
+                end
+              end
+            when String
+              hash[key] += value
+            else
+              hash[key] = value
+            end
+          end
+
+          hash
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "request"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Embedding
+        # 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
+              value
+            when Hash
+              Request.new(**value.deep_symbolize_keys)
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot cast #{value.class} to Request"
+            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
+              value.serialize
+            when Hash
+              value
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot serialize #{value.class}"
+            end
+          end
+
+          # @param value [Object]
+          # @return [Request, nil]
+          def deserialize(value)
+            cast(value)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "transforms"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Embedding
+        # 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
+
+          # 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
+    end
+  end
+end