activeagent 1.0.0.rc1 → 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_provider.rb

@@ -56,7 +56,6 @@ module ActiveAgent
       # @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

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

@@ -49,8 +49,9 @@ module ActiveAgent
           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)
+          instrument("tool_call.active_agent", tool_name: name) do
+            tools_function.call(name, **kwargs)
+          end
         end
       end
     end

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

@@ -6,8 +6,13 @@ module ActiveAgent
   module Providers
     module OpenAI
       module Chat
-        # Type for Request model
+        # 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
@@ -21,6 +26,11 @@ module ActiveAgent
             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
@@ -34,6 +44,8 @@ module ActiveAgent
             end
           end
 
+          # @param value [Object]
+          # @return [Request, nil]
           def deserialize(value)
             cast(value)
           end

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

@@ -1,212 +1,158 @@
 # frozen_string_literal: true
 
-require "active_agent/providers/common/model"
-require_relative "requests/_types"
+require "delegate"
+require "json"
+require_relative "transforms"
 
 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
+        # 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
 
-          # Common Format Compatability
-          def instructions=(*values)
-            self.messages ||= []
+          # 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__)
 
-            values.flatten.reverse.each do |value|
-              self.messages.unshift({ role: "developer", content: value })
-            end
+            # Cleanup and simplify for API request
+            Chat::Transforms.cleanup_serialized_request(hash, DEFAULTS, __getobj__)
           end
 
-          # Common Format Compatability
-          alias_attribute :message, :messages
+          # @return [Array<Hash>, nil]
+          def messages
+            __getobj__.instance_variable_get(:@data)[:messages]
+          end
 
-          # Common Format Compatability
+          # Sets messages with normalization
+          #
+          # @param value [Array, String, Hash]
+          # @return [void]
           def messages=(value)
-            case value
-            when Array
-              super((messages || []) | value)
-            else
-              super((messages || []) | [ value ])
-            end
+            normalized_value = Chat::Transforms.normalize_messages(value)
+            __getobj__.instance_variable_get(:@data)[:messages] = normalized_value
           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
+          # Alias for messages (common format compatibility)
+          #
+          # @return [Array<Hash>, nil]
+          def message
+            messages
           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
+          # @param value [Array, String, Hash]
+          # @return [void]
+          def message=(value)
+            self.messages = value
+          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
+          # 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
 
-          def validate_stop_sequences
-            return if stop.nil?
-            return if stop.is_a?(String)
+          private
 
-            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")
+          # @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