activeagent 0.6.3 → 1.0.0

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActiveAgent
+  module Providers
+    module Ollama
+      # Handles transformation and normalization of embedding request parameters
+      # for the Ollama Embeddings API
+      module Embedding
+        # Provides transformation methods for normalizing embedding parameters
+        # to Ollama API format with OpenAI gem compatibility
+        module Transforms
+          class << self
+            # Converts gem objects to hash representation
+            #
+            # @param obj [Object] gem object or primitive value
+            # @return [Hash, Object] hash if object supports JSON serialization
+            def gem_to_hash(obj)
+              if obj.respond_to?(:to_json)
+                JSON.parse(obj.to_json, symbolize_names: true)
+              else
+                obj
+              end
+            end
+
+            # Normalizes all embedding request parameters
+            #
+            # Ollama-specific parameters (options, keep_alive, truncate) are extracted
+            # and returned separately from OpenAI-compatible parameters.
+            #
+            # @param params [Hash] raw request parameters
+            # @return [Array<Hash, Hash>] tuple of [openai_params, ollama_params]
+            def normalize_params(params)
+              params = params.dup
+
+              # Extract Ollama-specific parameters
+              ollama_params = {}
+              ollama_params[:options] = params.delete(:options) if params.key?(:options)
+              ollama_params[:keep_alive] = params.delete(:keep_alive) if params.key?(:keep_alive)
+              ollama_params[:truncate] = params.delete(:truncate) if params.key?(:truncate)
+
+              # Extract options attributes that can be at top level
+              extract_option_attributes(params, ollama_params)
+
+              # Normalize input - Ollama only accepts strings, not token arrays
+              if params[:input]
+                params[:input] = normalize_input(params[:input])
+              end
+
+              [ params, ollama_params ]
+            end
+
+            # Normalizes input parameter to Ollama format
+            #
+            # Ollama only accepts strings or arrays of strings (no token arrays).
+            # Converts single string to array internally for consistency.
+            #
+            # @param input [String, Array<String>]
+            # @return [Array<String>] normalized input as array of strings
+            # @raise [ArgumentError] if input contains non-string values
+            def normalize_input(input)
+              case input
+              when String
+                [ input.presence ].compact
+              when Array
+                # Validate all elements are strings
+                input.each_with_index do |item, index|
+                  unless item.is_a?(String)
+                    raise ArgumentError, "Ollama embedding input must contain only strings, got #{item.class} at index #{index}"
+                  end
+                  if item.empty?
+                    raise ArgumentError, "Ollama embedding input cannot contain empty strings at index #{index}"
+                  end
+                end
+                input.compact
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot normalize #{input.class} to Ollama input (expected String or Array)"
+              end
+            end
+
+            # Serializes input for API submission
+            #
+            # Returns single string if array has only one element, otherwise array.
+            #
+            # @param input [Array<String>, nil]
+            # @return [String, Array<String>, nil]
+            def serialize_input(input)
+              return nil if input.nil?
+
+              # Return single string if array has only one element
+              if input.is_a?(Array) && input.length == 1
+                input.first
+              else
+                input
+              end
+            end
+
+            # Cleans up serialized request for API submission
+            #
+            # Merges OpenAI-compatible params with Ollama-specific params.
+            #
+            # @param openai_hash [Hash] serialized OpenAI-compatible request
+            # @param ollama_params [Hash] Ollama-specific parameters
+            # @param defaults [Hash] default values to remove
+            # @return [Hash] cleaned and merged request hash
+            def cleanup_serialized_request(openai_hash, ollama_params, defaults)
+              # Remove nil values
+              cleaned = openai_hash.compact
+
+              # Serialize input (convert single-element array to string)
+              if cleaned[:input]
+                cleaned[:input] = serialize_input(cleaned[:input])
+              end
+
+              # Merge Ollama-specific params, skip defaults
+              ollama_params.each do |key, value|
+                next if value.nil?
+                next if value.respond_to?(:empty?) && value.empty?
+                next if defaults.key?(key) && defaults[key] == value
+
+                # Serialize options object if present
+                cleaned[key] = if value.respond_to?(:serialize)
+                  value.serialize
+                else
+                  value
+                end
+              end
+
+              cleaned
+            end
+
+            private
+
+            # Extracts option attributes that can be specified at the top level
+            #
+            # @param params [Hash] request parameters
+            # @param ollama_params [Hash] ollama-specific parameters to populate
+            def extract_option_attributes(params, ollama_params)
+              option_keys = [
+                :mirostat, :mirostat_eta, :mirostat_tau, :num_ctx,
+                :repeat_last_n, :repeat_penalty, :temperature, :seed,
+                :num_predict, :top_k, :top_p, :min_p, :stop
+              ]
+
+              option_keys.each do |key|
+                if params.key?(key)
+                  ollama_params[:options] ||= {}
+                  ollama_params[:options][key] = params.delete(key)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/ollama/options.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/options"
+
+module ActiveAgent
+  module Providers
+    module Ollama
+      class Options < ActiveAgent::Providers::OpenAI::Options
+        attribute :base_url, :string, fallback: "http://127.0.0.1:11434/v1"
+        attribute :api_key,  :string, fallback: "ollama"
+
+        private
+
+        def resolve_api_key(kwargs)
+          kwargs[:api_key] ||
+            kwargs[:access_token] ||
+            ENV["OLLAMA_API_KEY"] ||
+            ENV["OLLAMA_ACCESS_TOKEN"]
+        end
+
+        # Not Used as Part of Ollama
+        def resolve_organization_id(settings) = nil
+        def resolve_project_id(settings)      = nil
+      end
+    end
+  end
+end

data/lib/active_agent/providers/ollama_provider.rb

@@ -0,0 +1,94 @@
+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)
+        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,59 @@
+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_call.active_agent", tool_name: name) do
+            tools_function.call(name, **kwargs)
+          end
+        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,56 @@
+# frozen_string_literal: true
+
+require_relative "request"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        # ActiveModel type for casting and serializing chat 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/chat/request.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "json"
+require_relative "transforms"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Chat
+        # Wraps OpenAI gem's CompletionCreateParams with normalization
+        #
+        # Delegates to OpenAI::Models::Chat::CompletionCreateParams while providing
+        # parameter normalization and shorthand format support via the Transforms module.
+        #
+        # All OpenAI Chat API fields are available via delegation:
+        # model, messages, temperature, max_tokens, max_completion_tokens, top_p,
+        # frequency_penalty, presence_penalty, tools, tool_choice, response_format,
+        # stream_options, audio, prediction, metadata, modalities, service_tier, store,
+        # parallel_tool_calls, reasoning_effort, verbosity, stop, seed, logit_bias,
+        # logprobs, top_logprobs, prompt_cache_key, safety_identifier, user,
+        # web_search_options, function_call, functions
+        #
+        # @example Basic usage
+        #   request = Request.new(
+        #     model: "gpt-4o",
+        #     messages: [{role: "user", content: "Hello"}]
+        #   )
+        #
+        # @example String message normalization
+        #   Request.new(model: "gpt-4o", messages: "Hello")
+        #   # Normalized to: [{role: "user", content: "Hello"}]
+        #
+        # @example Instructions support
+        #   Request.new(
+        #     model: "gpt-4o",
+        #     messages: [{role: "user", content: "Hi"}],
+        #     instructions: ["You are helpful", "Be concise"]
+        #   )
+        #   # instructions converted to developer messages and prepended
+        class Request < SimpleDelegator
+          # Default parameter values applied during initialization
+          DEFAULTS = {
+            frequency_penalty: 0,
+            logprobs: false,
+            modalities: [ "text" ],
+            n: 1,
+            parallel_tool_calls: true,
+            presence_penalty: 0,
+            service_tier: "auto",
+            store: false,
+            stream: false,
+            temperature: 1,
+            top_p: 1
+          }.freeze
+
+          # @return [Boolean, nil]
+          attr_reader :stream
+
+          # Creates a new chat completion request
+          #
+          # @param params [Hash] request parameters
+          # @option params [String] :model required model identifier
+          # @option params [Array, String, Hash] :messages required conversation messages
+          # @option params [Array<String>, String] :instructions system/developer prompts
+          # @option params [Hash, String, Symbol] :response_format
+          # @option params [Float] :temperature (1) sampling temperature 0-2
+          # @option params [Integer] :max_tokens maximum tokens to generate
+          # @option params [Array] :tools available tool definitions
+          # @raise [ArgumentError] when parameters are invalid
+          def initialize(**params)
+            # Step 1: Extract stream flag
+            @stream = params[:stream]
+
+            # Step 2: Apply defaults
+            params = apply_defaults(params)
+
+            # Step 3: Normalize all parameters (instructions, messages, response_format)
+            params = Chat::Transforms.normalize_params(params)
+
+            # Step 4: Create gem model - this validates all parameters!
+            gem_model = ::OpenAI::Models::Chat::CompletionCreateParams.new(**params)
+
+            # Step 5: Delegate all method calls to gem model
+            super(gem_model)
+          rescue ArgumentError => e
+            # Re-raise with more context
+            raise ArgumentError, "Invalid OpenAI Chat request parameters: #{e.message}"
+          end
+
+          # Serializes request for API call
+          #
+          # Uses gem's JSON serialization, removes default values for minimal
+          # request body, and simplifies messages where possible.
+          #
+          # @return [Hash] cleaned request hash
+          def serialize
+            # Use gem's JSON serialization (handles all nested objects)
+            hash = Chat::Transforms.gem_to_hash(__getobj__)
+
+            # Cleanup and simplify for API request
+            Chat::Transforms.cleanup_serialized_request(hash, DEFAULTS, __getobj__)
+          end
+
+          # @return [Array<Hash>, nil]
+          def messages
+            __getobj__.instance_variable_get(:@data)[:messages]
+          end
+
+          # Sets messages with normalization
+          #
+          # @param value [Array, String, Hash]
+          # @return [void]
+          def messages=(value)
+            normalized_value = Chat::Transforms.normalize_messages(value)
+            __getobj__.instance_variable_get(:@data)[:messages] = normalized_value
+          end
+
+          # Alias for messages (common format compatibility)
+          #
+          # @return [Array<Hash>, nil]
+          def message
+            messages
+          end
+
+          # @param value [Array, String, Hash]
+          # @return [void]
+          def message=(value)
+            self.messages = value
+          end
+
+          # Sets instructions as developer messages
+          #
+          # Prepends developer messages to the messages array for common format compatibility.
+          #
+          # @param values [Array<String>, String]
+          # @return [void]
+          def instructions=(*values)
+            instructions_messages = Chat::Transforms.normalize_instructions(values.flatten)
+            current_messages = messages || []
+            self.messages = instructions_messages + current_messages
+          end
+
+          private
+
+          # @api private
+          # @param params [Hash]
+          # @return [Hash]
+          def apply_defaults(params)
+            # Only apply defaults for keys that aren't present
+            DEFAULTS.each do |key, value|
+              params[key] = value unless params.key?(key)
+            end
+
+            params
+          end
+        end
+      end
+    end
+  end
+end