activeagent 0.6.3 → 1.0.0

data/lib/active_agent/providers/common/model.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module Common
+      # BaseModel provides a foundation for structured data models with compressed serialization support.
+      #
+      # This class extends ActiveModel functionality to provide:
+      # - Attribute definition with default values
+      # - Compressed hash serialization (excludes default values)
+      # - Required attribute tracking
+      # - Deep compaction of nested structures
+      #
+      # == Example
+      #
+      #   class Message < BaseModel
+      #     attribute :role, :string, as: "user"
+      #     attribute :type, :string, fallback: "plain/text"
+      #     attribute :content, :string
+      #   end
+      #
+      #   message = Message.new(content: "Hello")
+      #   message.to_h      #=> { role: "user", type: "plain/text", content: "Hello" }
+      #   message.serialize #=> { role: "user", type: "plain/text", content: "Hello" }
+      class BaseModel
+        include ActiveModel::Model
+        include ActiveModel::Attributes
+
+        # Returns the set of required attribute names that must be included in compressed output.
+        #
+        # Required attributes are those defined with the +as+ option, which establishes
+        # a default value that should always be serialized.
+        #
+        # @return [Set<String>] set of required attribute names
+        def self.required_attributes
+          @required_attributes ||= Set.new
+        end
+
+        # Ensures subclasses get their own required_attributes set.
+        #
+        # @param subclass [Class] the inheriting class
+        # @return [void]
+        def self.inherited(subclass)
+          super
+          subclass.instance_variable_set(:@required_attributes, required_attributes.dup)
+        end
+
+        # Defines an attribute on the model with special handling for default values.
+        #
+        # @param name [Symbol, String] the name of the attribute
+        # @param type [Class, nil] the type of the attribute (optional)
+        # @param options [Hash] additional options for the attribute
+        # @option options [Object] :as A default value that makes the attribute read-only.
+        #   When set, attempts to assign a different value will raise an ArgumentError.
+        #   This attribute will be included in the compressed hash representation.
+        # @option options [Object] :fallback A default value for the attribute.
+        #   This attribute will be included in the compressed hash representation.
+        #
+        # @raise [ArgumentError] if attempting to set a value different from the :as default
+        #
+        # @example Define a read-only attribute with a default value
+        #   attribute :role, :string, as: "user"
+        #
+        # @example Define an attribute with a fallback value
+        #   attribute :temperature, :float, fallback: 0.7
+        #
+        # @example Define a regular attribute
+        #   attribute :messages, :array
+        def self.attribute(name, type = nil, **options)
+          if options.key?(:as)
+            default_value = options.delete(:as)
+            super(name, type, default: default_value, **options)
+
+            # Track this attribute as required (must be included in compressed hash)
+            required_attributes << name.to_s
+
+            define_method("#{name}=") do |value|
+              normalized_value   = value.is_a?(String)         ? value.to_sym         : value
+              normalized_default = default_value.is_a?(String) ? default_value.to_sym : default_value
+
+              next if normalized_value == normalized_default
+
+              raise ArgumentError, "Cannot set '#{name}' attribute (read-only with default value)"
+            end
+          elsif options.key?(:fallback)
+            default_value = options.delete(:fallback)
+            super(name, type, default: default_value, **options)
+
+            # Track this attribute as required (must be included in compressed hash)
+            required_attributes << name.to_s
+          else
+            super(name, type, **options)
+          end
+        end
+
+        # Delegates attribute accessors to another object.
+        #
+        # Creates getter and setter methods that forward to the specified target object.
+        # If the target is nil when setting, an empty hash is initialized.
+        #
+        # @param attributes [Array<Symbol>] attribute names to delegate
+        # @param to [Symbol] the target method/attribute name
+        #
+        # @example
+        #   delegate_attributes :temperature, :max_tokens, to: :options
+        def self.delegate_attributes(*attributes, to:)
+          attributes.each do |attribute|
+            define_method(attribute) do
+              public_send(to)&.public_send(attribute)
+            end
+
+            define_method("#{attribute}=") do |value|
+              public_send("#{to}=", {}) if public_send(to).nil?
+
+              public_send(to).public_send("#{attribute}=", value)
+            end
+          end
+        end
+
+        # Drops specified attributes by defining no-op setters.
+        #
+        # This is useful when converting between providers that support different attributes
+        # or when dropping attributes during message response to request construction.
+        # The attributes can still be read if defined elsewhere, but setting them has no effect.
+        #
+        # @param attributes [Array<Symbol>] attribute names to drop
+        # @return [void]
+        #
+        # @example
+        #   drop_attributes :metadata, :extra_info
+        def self.drop_attributes(*attributes)
+          attributes.each do |attribute|
+            define_method("#{attribute}=") do |value|
+              # No-Op: Drop the value
+            end
+          end
+        end
+
+        # Returns all attribute keys including aliases.
+        #
+        # Combines both the main attribute type keys and any attribute aliases,
+        # ensuring all possible attribute names are represented as symbols.
+        #
+        # @return [Array<Symbol>] array of all attribute keys
+        def self.keys
+          (attribute_types.keys.map(&:to_sym) | attribute_aliases.keys.map(&:to_sym))
+        end
+
+        # Initializes a new instance with the given attributes.
+        #
+        # Attributes can be provided as a hash. Hash keys are sorted to prioritize nested
+        # objects during initialization for backwards compatibility. A special internal key
+        # `__default_values` can be passed to get an instance with only default values
+        # without any overrides.
+        #
+        # @param kwargs [Hash] attributes to initialize the instance with
+        # @return [BaseModel] the initialized instance
+        #
+        # @example
+        #   Message.new(role: "user", content: "Hello")
+        def initialize(kwargs = {})
+          # To allow us to get a list of attribute defaults without initialized overrides
+          return super(nil) if kwargs.key?(:'__default_values')
+
+          # Backwards Compatibility: This sorts object construction to the top to protect the assignment
+          #   of backward compatibility assignments.
+          kwargs = kwargs.sort_by { |k, v| v.is_a?(Hash) ? 0 : 1 }.to_h if kwargs.is_a?(Hash)
+
+          super(kwargs)
+        end
+
+        # Merges the given attributes into the current instance.
+        #
+        # Only attributes with corresponding setter methods are updated.
+        # Keys are symbolized before merging.
+        #
+        # @param kwargs [Hash] attribute keyword arguments to merge
+        # @return [BaseModel] self for method chaining
+        def merge!(kwargs = {})
+          kwargs.deep_symbolize_keys.each do |key, value|
+            public_send("#{key}=", value) if respond_to?("#{key}=")
+          end
+
+          self
+        end
+
+        # Recursively removes nil values and empty collections from a hash.
+        #
+        # Nested hashes and arrays are processed recursively. Empty hashes and
+        # arrays after compaction are also removed.
+        #
+        # @param kwargs [Hash] hash to compact
+        # @return [Hash] compacted hash with nil values and empty collections removed
+        #
+        # @example
+        #   deep_compact({ a: 1, b: nil, c: { d: nil, e: 2 } })
+        #   #=> { a: 1, c: { e: 2 } }
+        def deep_compact(kwargs = {})
+          kwargs.each_with_object({}) do |(key, value), result|
+            compacted_value = case value
+            when Hash
+              deep_compacted = deep_compact(value)
+              deep_compacted unless deep_compacted.empty?
+            when Array
+              compacted_array = value.map { |v| v.is_a?(Hash) ? deep_compact(v) : v }.compact
+              compacted_array unless compacted_array.empty?
+            else
+              value
+            end
+
+            result[key] = compacted_value unless compacted_value.nil?
+          end
+        end
+
+        # Converts the model to a hash representation.
+        #
+        # Recursively converts nested BaseModel instances and arrays to hashes.
+        # Nil values and empty collections are removed via deep_compact.
+        #
+        # @return [Hash] hash representation of all attributes
+        #
+        # @example
+        #   message.to_hash
+        #   #=> { role: "user", content: "Hello", metadata: { id: 1 } }
+        def to_hash
+          deep_compact(attribute_names.each_with_object({}) do |name, hash|
+            value = public_send(name)
+
+            hash[name.to_sym] = case value
+            when BaseModel then value.to_hash
+            when Array     then value.map { _1.is_a?(BaseModel) ? _1.to_hash : _1 }
+            else
+              value
+            end
+          end)
+        end
+
+        # Alias for {#to_hash}.
+        #
+        # @return [Hash] hash representation of all attributes
+        # @see #to_hash
+        def to_h = to_hash
+
+        # Creates a deep duplicate of the model.
+        #
+        # Duplicates the model instance and recursively duplicates any array or hash attributes
+        # to ensure complete independence from the original object.
+        #
+        # @return [BaseModel] deep duplicate of the model
+        def deep_dup
+          dup.tap do |duplicated|
+            attribute_names.each do |name|
+              value = public_send(name)
+              next if value.nil?
+
+              duplicated.public_send("#{name}=", case value
+              when Array
+                value.map { |v| v.respond_to?(:deep_dup) ? v.deep_dup : v.dup rescue v }
+              when Hash
+                value.deep_dup
+              when BaseModel
+                value.deep_dup
+              else
+                value.dup rescue value
+              end)
+            end
+          end
+        end
+
+        # Serializes the model using attribute type serializers.
+        #
+        # Iterates through each attribute and uses its ActiveModel::Type serializer
+        # to convert the value to its serialized form. Only non-default values are included,
+        # except for required attributes (those defined with `:as` or `:fallback` options).
+        # This provides a compressed serialization that respects custom type logic.
+        #
+        # @return [Hash] serialized representation with non-default and required attributes
+        #
+        # @example
+        #   message = Message.new(role: "user", content: "Hello")
+        #   message.serialize  #=> { role: "user", content: "Hello" }
+        def serialize
+          default_values = self.class.new(__default_values: true).attributes
+          required_attrs = self.class.required_attributes
+
+          deep_compact(attribute_names.each_with_object({}) do |name, hash|
+            value = public_send(name)
+
+            # Always include required attributes (those defined with 'as' option)
+            # or attributes that differ from their default value
+            next if value == default_values[name] && !required_attrs.include?(name)
+
+            # Use the attribute's type serializer
+            attr_type = self.class.attribute_types[name]
+            hash[name.to_sym] = attr_type.serialize(value)
+          end)
+        end
+
+        # Returns a string representation for inspection.
+        #
+        # Provides a readable view of the model showing the class name and non-default attributes
+        # in a format similar to standard Ruby object inspection.
+        #
+        # @return [String] formatted string representation
+        # @see #serialize
+        #
+        # @example
+        #   message = Message.new(role: "user", content: "Hello")
+        #   message.inspect
+        #   #=> "#<Message role: \"user\", content: \"Hello\">"
+        def inspect
+          attrs = JSON.pretty_generate(serialize, {
+            space: " ",
+            indent: "  ",
+            object_nl: "\n",
+            array_nl: "\n"
+          }).lines.drop(1).join.chomp.sub(/\}\z/, "").strip
+
+          return "#<#{self.class.name}>" if attrs.empty?
+
+          "#<#{self.class.name} {\n  #{attrs}\n}>"
+        end
+
+        # @see #inspect
+        alias_method :to_s, :inspect
+
+        # Compares two models based on their serialized representations.
+        #
+        # Uses the serialized hash to compare models, allowing for sorting and equality
+        # comparisons based on attribute values rather than object identity.
+        #
+        # @param other [BaseModel] the model to compare against
+        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+        #
+        # @example
+        #   model1 = Message.new(content: "A")
+        #   model2 = Message.new(content: "B")
+        #   model1 <=> model2  #=> -1
+        def <=>(other)
+          serialize <=> other&.serialize
+        end
+
+        # Compares equality based on serialized representation.
+        #
+        # Two models are equal if their serialized hashes are equal, regardless
+        # of object identity. This allows value-based equality comparisons.
+        #
+        # @param other [BaseModel] the model to compare against
+        # @return [Boolean]
+        #
+        # @example
+        #   model1 = Message.new(content: "Hello")
+        #   model2 = Message.new(content: "Hello")
+        #   model1 == model2  #=> true
+        def ==(other)
+          serialize == other&.serialize
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "responses/prompt"
+require_relative "responses/embed"
+
+module ActiveAgent
+  module Providers
+    module Common
+      PromptResponse = Responses::Prompt
+      EmbedResponse  = Responses::Embed
+    end
+  end
+end

data/lib/active_agent/providers/common/responses/_types.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../messages/_types"
+
+require_relative "format"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Responses
+        module Types
+          # Type for Messages array - delegates to the shared common messages type
+          class MessagesType < Common::Messages::Types::MessagesType
+          end
+
+          class FormatType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when BaseModel
+                Responses::Format.new(**value.serialize)
+              when Hash
+                Responses::Format.new(**value.deep_symbolize_keys)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to Format"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when Format
+                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/common/responses/base.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+require "active_agent/providers/common/usage"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Responses
+        # Provides unified interface for AI provider responses across OpenAI, Anthropic, etc.
+        #
+        # @abstract Subclass and override {#usage} if provider uses non-standard format
+        #
+        # @note Use specialized subclasses for specific response types:
+        #   - {Prompt} for conversational/completion responses
+        #   - {Embed} for embedding responses
+        #
+        # @example Accessing response data
+        #   response = agent.prompt.generate_now
+        #   response.success?         #=> true
+        #   response.usage            #=> Usage object with normalized fields
+        #   response.total_tokens     #=> 30
+        #
+        # @example Inspecting raw provider data
+        #   response.raw_request      #=> { "model" => "gpt-4", "messages" => [...] }
+        #   response.raw_response     #=> { "id" => "chatcmpl-...", "choices" => [...] }
+        #
+        # @see Prompt
+        # @see Embed
+        # @see BaseModel
+        class Base < BaseModel
+          # @!attribute [r] context
+          #   Original request context sent to the provider.
+          #
+          #   Includes instructions, messages, tools, and configuration.
+          #
+          #   @return [Hash]
+          attribute :context, writable: false
+
+          # @!attribute [r] raw_request
+          #   Most recent request in provider-specific format.
+          #
+          #   Useful for debugging and logging.
+          #
+          #   @return [Hash]
+          attribute :raw_request, writable: false
+
+          # @!attribute [r] raw_response
+          #   Most recent response in provider-specific format.
+          #
+          #   Includes metadata, usage stats, and provider-specific fields.
+          #   Hash keys are deep symbolized for consistent access.
+          #
+          #   @return [Hash]
+          attribute :raw_response, writable: false
+
+          # @!attribute [r] usages
+          #   Usage objects from each API call in multi-turn conversations.
+          #
+          #   Each call (e.g., for tool calling) tracks usage separately. These are
+          #   summed to provide cumulative statistics via {#usage}.
+          #
+          #   @return [Array<Usage>]
+          attribute :usages, default: -> { [] }, writable: false
+
+          # Initializes response with deep-duplicated attributes.
+          #
+          # Deep duplication prevents external modifications from affecting internal state.
+          # The raw_response is deep symbolized for consistent key access across providers.
+          #
+          # @param kwargs [Hash]
+          # @option kwargs [Hash] :context
+          # @option kwargs [Hash] :raw_request
+          # @option kwargs [Hash] :raw_response
+          def initialize(kwargs = {})
+            kwargs = kwargs.deep_dup # Ensure that userland can't fuck with our memory space
+
+            # Deep symbolize raw_response for consistent access across all extraction methods
+            if kwargs[:raw_response].is_a?(Hash)
+              kwargs[:raw_response] = kwargs[:raw_response].deep_symbolize_keys
+            end
+
+            super(kwargs)
+          end
+
+          # @return [String, Array<Hash>, nil]
+          def instructions
+            context[:instructions]
+          end
+
+          # @todo Better handling of failure flows
+          # @return [Boolean]
+          def success?
+            true
+          end
+
+          # Normalized usage statistics across all providers.
+          #
+          # For multi-turn conversations with tool calling, returns cumulative
+          # usage across all API calls (sum of {#usages}).
+          #
+          # @return [Usage, nil]
+          #
+          # @example Single-turn usage
+          #   response.usage.input_tokens      #=> 100
+          #   response.usage.output_tokens     #=> 25
+          #   response.usage.total_tokens      #=> 125
+          #
+          # @example Multi-turn usage (cumulative)
+          #   # After 3 API calls due to tool usage:
+          #   response.usage.input_tokens      #=> 350 (sum of all calls)
+          #   response.usage.output_tokens     #=> 120 (sum of all calls)
+          #
+          # @see Usage
+          def usage
+            @usage ||= begin
+              if usages.any?
+                usages.reduce(:+)
+              elsif raw_response
+                Usage.from_provider_usage(
+                  raw_response.is_a?(Hash) ? raw_response[:usage] : raw_response.usage
+                )
+              end
+            end
+          end
+
+          # Response ID from provider, useful for tracking and debugging.
+          #
+          # @return [String, nil]
+          #
+          # @example
+          #   response.id  #=> "chatcmpl-CbDx1nXoNSBrNIMhiuy5fk7jXQjmT" (OpenAI)
+          #   response.id  #=> "msg_01RotDmSnYpKQjrTpaHUaEBz" (Anthropic)
+          #   response.id  #=> "gen-1761505659-yxgaVsqVABMQqw6oA7QF" (OpenRouter)
+          def id
+            @id ||= begin
+              return nil unless raw_response
+
+              if raw_response.is_a?(Hash)
+                raw_response[:id]
+              elsif raw_response.respond_to?(:id)
+                raw_response.id
+              end
+            end
+          end
+
+          # Model name from provider response.
+          #
+          # Useful for confirming which model was actually used, as providers may
+          # use different versions than requested.
+          #
+          # @return [String, nil]
+          #
+          # @example
+          #   response.model  #=> "gpt-4o-mini-2024-07-18"
+          #   response.model  #=> "claude-3-5-haiku-20241022"
+          def model
+            @model ||= begin
+              return nil unless raw_response
+
+              if raw_response.is_a?(Hash)
+                raw_response[:model]
+              elsif raw_response.respond_to?(:model)
+                raw_response.model
+              end
+            end
+          end
+
+          # Finish reason from provider response.
+          #
+          # Indicates why generation stopped (e.g., "stop", "length", "tool_calls").
+          # Normalizes access across providers that use different field names.
+          #
+          # @return [String, nil]
+          #
+          # @example
+          #   response.finish_reason  #=> "stop"
+          #   response.finish_reason  #=> "length"
+          #   response.finish_reason  #=> "tool_calls"
+          #   response.stop_reason    #=> "stop" (alias)
+          def finish_reason
+            @finish_reason ||= begin
+              return nil unless raw_response
+
+              if raw_response.is_a?(Hash)
+                # OpenAI format: choices[0].finish_reason or choices[0].message.finish_reason
+                raw_response.dig(:choices, 0, :finish_reason) ||
+                  raw_response.dig(:choices, 0, :message, :finish_reason) ||
+                  # Anthropic format: stop_reason
+                  raw_response[:stop_reason]
+              end
+            end
+          end
+          alias_method :stop_reason, :finish_reason
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/responses/embed.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Responses
+        # Response model for embedding responses
+        #
+        # This class represents responses from embedding endpoints.
+        # It includes the embedding data, the original context, raw API data,
+        # and usage statistics.
+        #
+        # == Example
+        #
+        #   response = EmbedResponse.new(
+        #     context: context_hash,
+        #     data: [embedding_array],
+        #     raw_response: { "usage" => { "prompt_tokens" => 10 } }
+        #   )
+        #
+        #   response.data           #=> [[0.1, 0.2, ...]]
+        #   response.prompt_tokens  #=> 10
+        #   response.usage          #=> { "prompt_tokens" => 10, ... }
+        class Embed < Base
+          # The embedding data
+          attribute :data, writable: false
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/responses/format.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Responses
+        class Format < Common::BaseModel
+          # Type of response format (text, json_object, json_schema)
+          attribute :type, :string, default: "text"
+          attribute :name, :string
+          attribute :schema
+
+          validates :type, inclusion: { in: %w[text json_object json_object] }, allow_nil: true
+
+          # OpenAI's Responses => Common Format
+          def format=(value)
+            self.type = value[:type]
+          end
+
+          # OpenAI's Chat => Common Format
+          def json_schema=(value)
+            self.name   = value[:name]   if value[:name]
+            self.schema = value[:schema] if value[:schema]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/responses/message.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../messages/base"