activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/providers/open_ai/chat/requests/messages/function.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          module Messages
+            # Function message - result from a function call (deprecated)
+            class Function < Base
+              attribute :role, :string, as: "function"
+              attribute :content, :string # Result of the function call
+              attribute :name, :string # Name of the function that was called
+
+              validates :content, presence: true
+              validates :name, presence: true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/messages/system.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "content/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          module Messages
+            # System message - instructions that the model should follow (older models)
+            class System < Base
+              attribute :role, :string, as: "system"
+              attribute :content, Content::ContentsType.new # String or array of content parts
+              attribute :name, :string # Optional name for the participant
+
+              validates :content, presence: true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/messages/tool.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "content/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          module Messages
+            # Tool message - result from a tool call
+            class Tool < Base
+              attribute :role, :string, as: "tool"
+              attribute :content, Content::ContentsType.new # String or array of content parts
+              attribute :tool_call_id, :string # ID of the tool call this is a response to
+
+              validates :content, presence: true
+              validates :tool_call_id, presence: true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/messages/user.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "content/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          module Messages
+            # User message - messages sent by an end user
+            class User < Base
+              attribute :role, :string, as: "user"
+              attribute :content, Content::ContentsType.new # String or array of content parts
+              attribute :name, :string # Optional name for the participant
+
+              validates :content, presence: true
+
+              %i[text image document].each do |content_type|
+                define_method(:"#{content_type}=") do |value|
+                  self.content ||= []
+                  self.content += [ { content_type => value } ]
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/prediction.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          class Prediction < Common::BaseModel
+            # Type of predicted content (always "content")
+            attribute :type, :string, default: "content"
+
+            # Content that should be matched (string or array of content parts)
+            attribute :content
+
+            validates :type, inclusion: { in: %w[content] }, allow_nil: true
+
+            # Validate content is present and in correct format
+            validate :validate_content_format
+
+            private
+
+            def validate_content_format
+              if content.blank?
+                errors.add(:content, "must be present")
+                return
+              end
+
+              # Content can be a string or an array of content parts
+              if content.is_a?(Array)
+                content.each do |part|
+                  unless part.is_a?(Hash) && part[:type].present?
+                    errors.add(:content, "array elements must be hashes with a 'type' field")
+                  end
+                end
+              elsif !content.is_a?(String)
+                errors.add(:content, "must be a string or array of content parts")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/response_format.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          class ResponseFormat < Common::BaseModel
+            # Type of response format (text, json_schema, json_object)
+            attribute :type, :string
+
+            # JSON schema configuration (only for json_schema type)
+            attribute :json_schema # Hash with name, description, schema, strict
+
+            validates :type, inclusion: { in: %w[text json_schema json_object] }, allow_nil: true
+
+            # Validate that json_schema is present when type is json_schema
+            validate :validate_json_schema_presence
+
+            private
+
+            def validate_json_schema_presence
+              if type == "json_schema" && json_schema.blank?
+                errors.add(:json_schema, "must be present when type is 'json_schema'")
+              end
+
+              if json_schema.present? && json_schema.is_a?(Hash)
+                validate_json_schema_structure
+              end
+            end
+
+            def validate_json_schema_structure
+              unless json_schema[:name].present?
+                errors.add(:json_schema, "must include 'name' field")
+              end
+
+              if json_schema[:name].present? && json_schema[:name].length > 64
+                errors.add(:json_schema, "name must be 64 characters or less")
+              end
+
+              # Name must match pattern: a-z, A-Z, 0-9, underscores and dashes
+              if json_schema[:name].present? && json_schema[:name] !~ /^[a-zA-Z0-9_-]+$/
+                errors.add(:json_schema, "name must contain only a-z, A-Z, 0-9, underscores and dashes")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/stream_options.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          class StreamOptions < Common::BaseModel
+            # Include usage information in the stream
+            attribute :include_usage, :boolean
+
+            # Include obfuscation in the stream
+            attribute :include_obfuscation, :boolean
+
+            validates :include_usage, inclusion: { in: [ true, false ] }, allow_nil: true
+            validates :include_obfuscation, inclusion: { in: [ true, false ] }, allow_nil: true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/tool_choice.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          # Tool choice configuration
+          class ToolChoice < Common::BaseModel
+            # Can be string ("none", "auto", "required") or object
+            attribute :mode, :string
+            attribute :type, :string
+            attribute :function # Hash with name
+            attribute :custom # Hash with name
+            attribute :allowed_tools # Hash with mode and tools array
+
+            validates :mode, inclusion: { in: %w[none auto required] }, allow_nil: true
+            validates :type, inclusion: { in: %w[function custom allowed_tools] }, allow_nil: true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/tools/_types.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "custom_tool"
+require_relative "function_tool"

data/lib/active_agent/providers/open_ai/chat/requests/tools/base.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          module Tools
+            # Base class for tools
+            class Base < Common::BaseModel
+              attribute :type, :string
+
+              validates :type, inclusion: { in: %w[function custom] }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/tools/custom_tool.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          module Tools
+            # Custom tool
+            class CustomTool < Base
+              attribute :type, :string, as: "custom"
+              attribute :custom # Hash with name, description, format
+
+              validate :validate_custom_structure
+
+              private
+
+              def validate_custom_structure
+                if custom.blank?
+                  errors.add(:custom, "must be present")
+                  return
+                end
+
+                unless custom.is_a?(Hash)
+                  errors.add(:custom, "must be a hash")
+                  return
+                end
+
+                unless custom[:name].present?
+                  errors.add(:custom, "must include 'name' field")
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/tools/function_tool.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          module Tools
+            # Function tool
+            class FunctionTool < Base
+              attribute :type, :string, as: "function"
+              attribute :function # Hash with name, description, parameters, strict
+
+              validate :validate_function_structure
+
+              private
+
+              def validate_function_structure
+                if function.blank?
+                  errors.add(:function, "must be present")
+                  return
+                end
+
+                unless function.is_a?(Hash)
+                  errors.add(:function, "must be a hash")
+                  return
+                end
+
+                unless function[:name].present?
+                  errors.add(:function, "must include 'name' field")
+                end
+
+                if function[:name].present?
+                  if function[:name].length > 64
+                    errors.add(:function, "name must be 64 characters or less")
+                  end
+
+                  unless function[:name] =~ /^[a-zA-Z0-9_-]+$/
+                    errors.add(:function, "name must contain only a-z, A-Z, 0-9, underscores and dashes")
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/requests/web_search_options.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          class WebSearchOptions < Common::BaseModel
+            # Search context size (low, medium, high)
+            attribute :search_context_size, :string
+
+            # User location for search
+            attribute :user_location # Hash with type and approximate
+
+            validates :search_context_size, inclusion: { in: %w[low medium high] }, allow_nil: true
+
+            # Validate user_location format
+            validate :validate_user_location_format
+
+            private
+
+            def validate_user_location_format
+              return if user_location.nil?
+
+              unless user_location.is_a?(Hash)
+                errors.add(:user_location, "must be a hash")
+                return
+              end
+
+              unless user_location[:type] == "approximate"
+                errors.add(:user_location, "type must be 'approximate'")
+              end
+
+              unless user_location[:approximate].is_a?(Hash)
+                errors.add(:user_location, "must include 'approximate' hash")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,198 @@
+require_relative "_base"
+require_relative "chat/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      # Provider implementation for OpenAI's Chat Completion API.
+      #
+      # Handles chat-based interactions including streaming responses,
+      # function/tool calling, and message management. Uses OpenAI's
+      # chat completions endpoint for generating responses.
+      #
+      # @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
+
+        # 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.
+        #
+        # Handles multiple event types:
+        # - `: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_processing.provider.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
+
+            # If this is the last api_chunk to be processed
+            return unless api_message.finish_reason
+
+            instrument("stream_finished.provider.active_agent", finish_reason: api_message.finish_reason)
+          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 call objects 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 = case api_function_call[:type]
+            when "function"
+              instrument("tool_execution.provider.active_agent", tool_name: api_function_call.dig(:function, :name))
+              process_tool_call_function(api_function_call[:function])
+            else
+              fail "Unexpected Tool Call Type: #{api_function_call[:type]}"
+            end
+
+            message = Chat::Requests::Messages::Tool.new(
+              tool_call_id: api_function_call[:id],
+              content: content.to_json
+            )
+
+            message_stack.push(message.serialize)
+          end
+        end
+
+        # Extracts messages from the completed API response.
+        #
+        # @param api_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)
+          api_message = api_response&.dig(:choices, 0, :message)
+
+          [ api_message ] if 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] the merged message
+        def message_merge_delta(message, delta)
+          hash_merge_delta(message, delta)
+        end
+
+        private
+
+        # Finds an existing message by ID 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 the complex delta merging needed 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] the 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,45 @@
+# frozen_string_literal: true
+
+require_relative "requests/_types"
+require_relative "request"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Embedding
+        # 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