activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/providers/common/messages/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        class Base < Common::BaseModel
+          attribute :role, :string
+
+          validates :role, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/system.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        # System message - provides instructions and context to the AI
+        class System < Base
+          attribute :role, :string, as: "system"
+          attribute :content, :string # Text content
+          attribute :name, :string # Optional name for the system message
+
+          validates :content, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/tool.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        # Tool message - messages containing tool call results
+        class Tool < Base
+          attribute :role, :string, as: "tool"
+          attribute :content, :string # Tool result content
+          attribute :tool_call_id, :string # ID of the tool call this is responding to
+          attribute :name, :string # Optional name of the tool
+
+          validates :content, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/user.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        # Represents a message sent by the user in a conversation
+        class User < Base
+          attribute :role, :string, as: "user"
+          attribute :content, :string
+          attribute :name, :string
+
+          validates :content, presence: true
+        end
+      end
+    end
+  end
+end

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,151 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Responses
+        # Base response model for provider responses.
+        #
+        # This class represents the standard response structure from AI providers
+        # across different services (OpenAI, Anthropic, etc.). It provides a unified
+        # interface for accessing response data, usage statistics, and request context.
+        #
+        # @abstract Subclass and override {#usage} if provider uses non-standard format
+        #
+        # @note This is a base class. Use specialized subclasses for specific response types:
+        #   - {Prompt} for conversational/completion responses with messages
+        #   - {Embed} for embedding responses with vector data
+        #
+        # @example Accessing response data
+        #   response = agent.prompt.generate_now
+        #   response.success?         #=> true
+        #   response.usage            #=> { "prompt_tokens" => 10, "completion_tokens" => 20 }
+        #   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
+          #   The original context that was sent to the provider.
+          #
+          #   Contains structured information about the request including instructions,
+          #   messages, tools, and other configuration passed to the LLM.
+          #
+          #   @return [Hash] the request context
+          attribute :context, writable: false
+
+          # @!attribute [r] raw_request
+          #   The most recent request in provider-specific format.
+          #
+          #   Contains the actual API request payload sent to the provider,
+          #   useful for debugging and logging.
+          #
+          #   @return [Hash] the provider-formatted request
+          attribute :raw_request, writable: false
+
+          # @!attribute [r] raw_response
+          #   The most recent response in provider-specific format.
+          #
+          #   Contains the raw API response from the provider, including all
+          #   metadata, usage stats, and provider-specific fields.
+          #
+          #   @return [Hash] the provider-formatted response
+          attribute :raw_response, writable: false
+
+          # Initializes a new response object with deep-duplicated attributes.
+          #
+          # Deep duplication ensures that the response object maintains its own
+          # independent copy of the data, preventing external modifications from
+          # affecting the response's internal state.
+          #
+          # @param kwargs [Hash] response attributes
+          # @option kwargs [Hash] :context the original request context
+          # @option kwargs [Hash] :raw_request the provider-formatted request
+          # @option kwargs [Hash] :raw_response the provider-formatted response
+          #
+          # @return [Base] the initialized response object
+          def initialize(kwargs = {})
+            super(kwargs.deep_dup) # Ensure that userland can't fuck with our memory space
+          end
+
+          # Extracts instructions from the context.
+          #
+          # @return [String, Array<Hash>, nil] the instructions that were sent to the provider
+          def instructions
+            context[:instructions]
+          end
+
+          # Indicates whether the generation request was successful.
+          #
+          # @todo Better handling of failure flows
+          #
+          # @return [Boolean] true if successful, false otherwise
+          def success?
+            true
+          end
+
+          # Extracts usage statistics from the raw response.
+          #
+          # Most providers (OpenAI, Anthropic, etc.) return usage data in a
+          # standardized format within the response. This method extracts that
+          # information for token counting and billing purposes.
+          #
+          # @return [Hash, nil] usage statistics hash with keys like "prompt_tokens",
+          #   "completion_tokens", and "total_tokens", or nil if not available
+          #
+          # @example Usage data structure
+          #   {
+          #     "prompt_tokens" => 10,
+          #     "completion_tokens" => 20,
+          #     "total_tokens" => 30
+          #   }
+          def usage
+            return nil unless raw_response
+
+            # Most providers store usage in the same format
+            if raw_response.is_a?(Hash) && raw_response["usage"]
+              raw_response["usage"]
+            end
+          end
+
+          # Extracts the number of tokens used in the prompt/input.
+          #
+          # @return [Integer, nil] number of prompt tokens used, or nil if unavailable
+          #
+          # @example
+          #   response.prompt_tokens #=> 10
+          def prompt_tokens
+            usage&.dig("prompt_tokens")
+          end
+
+          # Extracts the number of tokens used in the completion/output.
+          #
+          # @return [Integer, nil] number of completion tokens used, or nil if unavailable
+          #
+          # @example
+          #   response.completion_tokens #=> 20
+          def completion_tokens
+            usage&.dig("completion_tokens")
+          end
+
+          # Extracts the total number of tokens used (prompt + completion).
+          #
+          # @return [Integer, nil] total number of tokens used, or nil if unavailable
+          #
+          # @example
+          #   response.total_tokens #=> 30
+          def total_tokens
+            usage&.dig("total_tokens")
+          end
+        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