activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/providers/ollama_provider.rb

@@ -0,0 +1,95 @@
+require_relative "_base_provider"
+
+require_gem!(:openai, __FILE__)
+
+require_relative "open_ai_provider"
+require_relative "ollama/_types"
+
+module ActiveAgent
+  module Providers
+    # Connects to local Ollama instances via OpenAI-compatible API.
+    #
+    # Provides chat completion and embedding functionality through locally-hosted
+    # Ollama models. Handles connection errors specific to local deployments.
+    #
+    # @see OpenAI::ChatProvider
+    class OllamaProvider < OpenAI::ChatProvider
+      # @return [String]
+      def self.service_name
+        "Ollama"
+      end
+
+      # @return [Class]
+      def self.options_klass
+        namespace::Options
+      end
+
+      # @return [ActiveModel::Type::Value]
+      def self.prompt_request_type
+        namespace::Chat::RequestType.new
+      end
+
+      # @return [ActiveModel::Type::Value]
+      def self.embed_request_type
+        namespace::Embedding::RequestType.new
+      end
+
+      protected
+
+      # Executes chat completion request with Ollama-specific error handling.
+      #
+      # @see OpenAI::ChatProvider#api_prompt_execute
+      # @param parameters [Hash]
+      # @return [Object, nil] response object or nil for streaming
+      # @raise [OpenAI::Errors::APIConnectionError] when Ollama server unreachable
+      def api_prompt_execute(parameters)
+        super
+
+      rescue ::OpenAI::Errors::APIConnectionError => exception
+        log_connection_error(exception)
+        raise exception
+      end
+
+      # Executes embedding request with Ollama-specific error handling.
+      #
+      # @param parameters [Hash]
+      # @return [Hash] symbolized API response
+      # @raise [OpenAI::Errors::APIConnectionError] when Ollama server unreachable
+      def api_embed_execute(parameters)
+        instrument("embeddings_request.provider.active_agent")
+        client.embeddings.create(**parameters).as_json.deep_symbolize_keys
+
+      rescue ::OpenAI::Errors::APIConnectionError => exception
+        log_connection_error(exception)
+        raise exception
+      end
+
+      # Handles role duplication bug in Ollama's OpenAI-compatible streaming.
+      #
+      # Ollama duplicates role information in streaming deltas, requiring
+      # manual cleanup to prevent message corruption. This fixes the
+      # "role appears in every chunk" issue when using streaming responses.
+      #
+      # @see OpenAI::ChatProvider#message_merge_delta
+      # @param message [Hash]
+      # @param delta [Hash]
+      # @return [Hash]
+      def message_merge_delta(message, delta)
+        message[:role] = delta.delete(:role) if delta[:role] # Copy a Bad Design (OpenAI's Chat API) Badly, Win Bad Prizes
+
+        hash_merge_delta(message, delta)
+      end
+
+      # Logs connection failures with Ollama server details for debugging.
+      #
+      # @param error [Exception]
+      # @return [void]
+      def log_connection_error(error)
+        instrument("connection_error.provider.active_agent",
+                  uri_base: options.uri_base,
+                  exception: error.class,
+                  message: error.message)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+require_relative "../_base_provider"
+
+require_gem!(:openai, __FILE__)
+
+require_relative "options"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      # Base provider class for OpenAI API implementations.
+      #
+      # Provides common functionality for OpenAI-based providers including
+      # client configuration, service identification, and tool call processing.
+      #
+      # @see ActiveAgent::Providers::BaseProvider
+      class Base < ActiveAgent::Providers::BaseProvider
+        # Returns the service name for OpenAI providers.
+        #
+        # @return [String] Always returns "OpenAI"
+        def self.service_name
+          "OpenAI"
+        end
+
+        # Returns a configured OpenAI client instance.
+        #
+        # @return [OpenAI::Client] The configured OpenAI client
+        def client
+          ::OpenAI::Client.new(**options.serialize)
+        end
+
+        protected
+
+        # Processes a tool call function from the API response.
+        #
+        # This method extracts the function name and arguments from an API function call,
+        # parses the arguments as JSON, and invokes the function callback with the parsed parameters.
+        #
+        # @param api_function_call [Hash] The function call data from the API response
+        # @option api_function_call [String] :name The name of the function to call
+        # @option api_function_call [String] :arguments JSON string containing the function arguments
+        #
+        # @return [Object] The result of the function callback invocation
+        #
+        # @example Processing a tool call
+        #   api_call = { name: "get_weather", arguments: '{"location":"NYC"}' }
+        #   process_tool_call_function(api_call)
+        #   # => calls tools_function.call("get_weather", location: "NYC")
+        def process_tool_call_function(api_function_call)
+          name   = api_function_call[:name]
+          kwargs = JSON.parse(api_function_call[:arguments], symbolize_names: true) if api_function_call[:arguments]
+
+          instrument("tool_execution.provider.active_agent", tool_name: name)
+          tools_function.call(name, **kwargs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "chat/_types"
+require_relative "embedding/_types"
+require_relative "responses/_types"

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "request"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        # 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/chat/request.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+require_relative "requests/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        class Request < Common::BaseModel
+          # Messages array (required)
+          attribute :messages, Requests::Messages::MessagesType.new
+
+          # Model ID (required)
+          attribute :model, :string
+
+          # Audio output parameters
+          attribute :audio, Requests::AudioType.new
+
+          # Frequency penalty
+          attribute :frequency_penalty, :float, default: 0
+
+          # Deprecated: function_call (use tool_choice instead)
+          attribute :function_call # String or object
+
+          # Deprecated: functions (use tools instead)
+          attribute :functions # Array of function objects
+
+          # Logit bias
+          attribute :logit_bias # Hash of token_id => bias_value
+
+          # Log probabilities
+          attribute :logprobs, :boolean, default: false
+
+          # Max completion tokens
+          attribute :max_completion_tokens, :integer
+
+          # Deprecated: max_tokens (use max_completion_tokens)
+          attribute :max_tokens, :integer
+
+          # Metadata
+          attribute :metadata # Hash of key-value pairs
+
+          # Modalities
+          attribute :modalities, default: -> { [ "text" ] } # Array of strings
+
+          # Number of completions
+          attribute :n, :integer, default: 1
+
+          # Parallel tool calls
+          attribute :parallel_tool_calls, :boolean, default: true
+
+          # Prediction configuration
+          attribute :prediction, Requests::PredictionType.new
+
+          # Presence penalty
+          attribute :presence_penalty, :float, default: 0
+
+          # Prompt cache key
+          attribute :prompt_cache_key, :string
+
+          # Reasoning effort (for reasoning models)
+          attribute :reasoning_effort, :string
+
+          # Response format
+          attribute :response_format, Requests::ResponseFormatType.new
+
+          # Safety identifier
+          attribute :safety_identifier, :string
+
+          # Deprecated: seed
+          attribute :seed, :integer
+
+          # Service tier
+          attribute :service_tier, :string, default: "auto"
+
+          # Stop sequences
+          attribute :stop # String, array, or null
+
+          # Storage
+          attribute :store, :boolean, default: false
+
+          # Streaming
+          attribute :stream, :boolean, default: false
+          attribute :stream_options, Requests::StreamOptionsType.new
+
+          # Temperature sampling
+          attribute :temperature, :float, default: 1
+
+          # Tool choice
+          attribute :tool_choice, Requests::ToolChoiceType.new
+
+          # Tools array
+          attribute :tools # Array of tool objects
+
+          # Top logprobs
+          attribute :top_logprobs, :integer
+
+          # Top P sampling
+          attribute :top_p, :float, default: 1
+
+          # Deprecated: user (use safety_identifier or prompt_cache_key)
+          attribute :user, :string
+
+          # Verbosity (for reasoning models)
+          attribute :verbosity, :string
+
+          # Web search options
+          attribute :web_search_options, Requests::WebSearchOptionsType.new
+
+          # Validations
+          validates :model, :messages, presence: true
+
+          validates :frequency_penalty,     numericality: { greater_than_or_equal_to: -2.0, less_than_or_equal_to: 2.0 }, allow_nil: true
+          validates :presence_penalty,      numericality: { greater_than_or_equal_to: -2.0, less_than_or_equal_to: 2.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 :n,                     numericality: { greater_than: 0 },                                            allow_nil: true
+          validates :max_completion_tokens, numericality: { greater_than: 0 },                                            allow_nil: true
+          validates :max_tokens,            numericality: { greater_than: 0 },                                            allow_nil: true
+
+          validates :service_tier,     inclusion: { in: %w[auto default flex priority] }, allow_nil: true
+          validates :reasoning_effort, inclusion: { in: %w[minimal low medium high] },    allow_nil: true
+          validates :verbosity,        inclusion: { in: %w[low medium high] },            allow_nil: true
+          validates :modalities,       inclusion: { in: %w[text audio] },                 allow_nil: true
+
+          # Custom validations
+          validate :validate_metadata_format
+          validate :validate_logit_bias_format
+          validate :validate_stop_sequences
+
+          def serialize
+            super.tap do |hash|
+              # Can be an empty hash, to enable the feature
+              hash[:web_search_options] ||= {} if web_search_options
+            end
+          end
+
+          # Common Format Compatability
+          def instructions=(*values)
+            self.messages ||= []
+
+            values.flatten.reverse.each do |value|
+              self.messages.unshift({ role: "developer", content: value })
+            end
+          end
+
+          # Common Format Compatability
+          alias_attribute :message, :messages
+
+          # Common Format Compatability
+          def messages=(value)
+            case value
+            when Array
+              super((messages || []) | value)
+            else
+              super((messages || []) | [ value ])
+            end
+          end
+
+          private
+
+          def validate_metadata_format
+            return if metadata.nil?
+
+            unless metadata.is_a?(Hash)
+              errors.add(:metadata, "must be a hash")
+              return
+            end
+
+            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
+
+            if metadata.size > 16
+              errors.add(:metadata, "must have 16 key-value pairs or less")
+            end
+          end
+
+          def validate_logit_bias_format
+            return if logit_bias.nil?
+
+            unless logit_bias.is_a?(Hash)
+              errors.add(:logit_bias, "must be a hash")
+              return
+            end
+
+            logit_bias.each do |token_id, bias|
+              unless bias.is_a?(Numeric) && bias >= -100 && bias <= 100
+                errors.add(:logit_bias, "bias values must be between -100 and 100")
+              end
+            end
+          end
+
+          def validate_stop_sequences
+            return if stop.nil?
+            return if stop.is_a?(String)
+
+            if stop.is_a?(Array)
+              errors.add(:stop, "can have at most 4 sequences") if stop.length > 4
+            else
+              errors.add(:stop, "must be a string, array, or null")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require_relative "messages/_types"
+require_relative "tools/_types"
+
+require_relative "audio"
+require_relative "prediction"
+require_relative "response_format"
+require_relative "stream_options"
+require_relative "tool_choice"
+require_relative "web_search_options"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        module Requests
+          # Type for Audio
+          class AudioType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when Audio
+                value
+              when Hash
+                Audio.new(**value.symbolize_keys)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to Audio"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when Audio
+                value.serialize
+              when Hash
+                value
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+          end
+
+          # Type for Prediction
+          class PredictionType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when Prediction
+                value
+              when Hash
+                Prediction.new(**value.symbolize_keys)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to Prediction"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when Prediction
+                value.serialize
+              when Hash
+                value
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+          end
+
+          # Type for ResponseFormat
+          class ResponseFormatType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when ResponseFormat
+                value
+              when Hash
+                ResponseFormat.new(**value.symbolize_keys)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to ResponseFormat"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when ResponseFormat
+                value.serialize
+              when Hash
+                value
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+          end
+
+          # Type for StreamOptions
+          class StreamOptionsType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when StreamOptions
+                value
+              when Hash
+                StreamOptions.new(**value.symbolize_keys)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to StreamOptions"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when StreamOptions
+                value.serialize
+              when Hash
+                value
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+          end
+
+          # Type for ToolChoice
+          class ToolChoiceType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when ToolChoice
+                value
+              when Hash
+                ToolChoice.new(**value.symbolize_keys)
+              when String
+                ToolChoice.new(mode: value)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to ToolChoice"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when ToolChoice
+                hash = value.serialize
+                # If it's just a mode string, return the string
+                if hash[:mode].present? && hash[:type].blank? && hash[:function].blank? && hash[:custom].blank? && hash[:allowed_tools].blank?
+                  hash[:mode]
+                else
+                  hash
+                end
+              when Hash
+                value
+              when String
+                value
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+          end
+
+          # Type for WebSearchOptions
+          class WebSearchOptionsType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when WebSearchOptions
+                value
+              when Hash
+                WebSearchOptions.new(**value.symbolize_keys)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to WebSearchOptions"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when WebSearchOptions
+                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
+end

data/lib/active_agent/providers/open_ai/chat/requests/audio.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 Audio < Common::BaseModel
+            # Voice to use for audio output
+            attribute :voice, :string
+
+            # Audio format
+            attribute :format, :string
+
+            validates :voice, inclusion: { in: %w[alloy ash ballad coral echo fable nova onyx sage shimmer] }, allow_nil: true
+            validates :format, inclusion: { in: %w[wav mp3 flac opus pcm16] }, allow_nil: true
+          end
+        end
+      end
+    end
+  end
+end