activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/providers/open_router/requests/messages/content/file.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/open_ai/chat/requests/messages/content/base"
+require_relative "files/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          module Content
+            # File content part for OpenRouter.
+            #
+            # Uses OpenRouter's Files::DetailsType which preserves the data URI prefix
+            # instead of stripping it like OpenAI does.
+            class File < OpenAI::Chat::Requests::Messages::Content::Base
+              attribute :type, :string, as: "file"
+              attribute :file, Files::DetailsType.new
+
+              validates :file, presence: true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/messages/content/files/_types.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "details"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          module Content
+            module Files
+              # Type for the nested file object in OpenRouter.
+              #
+              # Uses OpenRouter's Details class which preserves the data URI prefix.
+              class DetailsType < ActiveModel::Type::Value
+                def cast(value)
+                  case value
+                  when Details
+                    value
+                  when Hash
+                    Details.new(**value.deep_symbolize_keys)
+                  when String
+                    # Accept both data URIs and plain base64, but preserve the format
+                    if value.start_with?("data:")
+                      Details.new(file_data: value)
+                    elsif value.match?(%r{\Ahttps?://})
+                      raise ArgumentError, "HTTP/S URLs are not supported. Use a base64 data URI instead"
+                    else
+                      Details.new(file_data: value)
+                    end
+                  when nil
+                    nil
+                  else
+                    raise ArgumentError, "Cannot cast #{value.class} to File::Details"
+                  end
+                end
+
+                def serialize(value)
+                  case value
+                  when Details
+                    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
+  end
+end

data/lib/active_agent/providers/open_router/requests/messages/content/files/details.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/open_ai/chat/requests/messages/content/files/details"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          module Content
+            module Files
+              # Represents the nested file object within File content part for OpenRouter.
+              #
+              # Unlike OpenAI which strips the data URI prefix, OpenRouter keeps it intact
+              # (e.g., data:application/pdf;base64,) in the file_data field.
+              class Details < OpenAI::Chat::Requests::Messages::Content::Files::Details
+                # Override the setter to NOT strip the data URI prefix
+                attribute :file_data, :string
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/messages/user.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/open_ai/chat/requests/messages/user"
+require_relative "content/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          # User message for OpenRouter API.
+          #
+          # Extends OpenAI's user message with OpenRouter-specific content handling.
+          # Overrides the content attribute to use OpenRouter's ContentsType which
+          # preserves the data URI prefix in file content instead of stripping it.
+          class User < OpenAI::Chat::Requests::Messages::User
+            attribute :content, Content::ContentsType.new # Override with OpenRouter's content handling
+
+            %i[text image document].each do |content_type|
+              define_method(:"#{content_type}=") do |value|
+                self.content ||= []
+                self.content += [ { content_type => value } ]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/plugin.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        # Represents a plugin configuration for OpenRouter requests.
+        # Currently supports the file-parser plugin for PDF processing.
+        #
+        # @example
+        #   plugin = Plugin.new(
+        #     id: 'file-parser',
+        #     pdf: { engine: 'pdf-text' }
+        #   )
+        class Plugin < Common::BaseModel
+          attribute :id, :string
+          attribute :pdf, Plugins::PdfConfigType.new
+
+          validates :id, presence: true
+          validates :id, inclusion: { in: %w[file-parser] }, allow_nil: false
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/plugins/_types.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "pdf_config"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Plugins
+          # Type for PdfConfig
+          class PdfConfigType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when PdfConfig
+                value
+              when Hash
+                PdfConfig.new(**value.deep_symbolize_keys)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to PdfConfig"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when PdfConfig
+                value.serialize
+              when Hash
+                value
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/plugins/pdf_config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Plugins
+          # Configuration for PDF processing in the file-parser plugin.
+          #
+          # OpenRouter provides several PDF processing engines:
+          # - "mistral-ocr": Best for scanned documents or PDFs with images ($2 per 1,000 pages)
+          # - "pdf-text": Best for well-structured PDFs with clear text content (Free)
+          # - "native": Only available for models that support file input natively (charged as input tokens)
+          #
+          # If you don't explicitly specify an engine, OpenRouter will default first to the model's
+          # native file processing capabilities, and if that's not available, will use the "mistral-ocr" engine.
+          #
+          # @example
+          #   pdf_config = PdfConfig.new(engine: 'pdf-text')
+          class PdfConfig < Common::BaseModel
+            attribute :engine, :string
+
+            validates :engine, inclusion: { in: %w[mistral-ocr pdf-text native] }, allow_nil: true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/prediction.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        class Prediction < Common::BaseModel
+          attribute :type, :string
+          attribute :content, :string
+
+          validates :type, inclusion: { in: %w[content] }, allow_nil: true
+          validates :content, presence: true, if: -> { type.present? }
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/provider_preferences/_types.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "max_price"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        # Type for MaxPrice
+        class MaxPriceType < ActiveModel::Type::Value
+          def cast(value)
+            case value
+            when MaxPrice
+              value
+            when Hash
+              MaxPrice.new(**value.deep_symbolize_keys)
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot cast #{value.class} to MaxPrice"
+            end
+          end
+
+          def serialize(value)
+            case value
+            when MaxPrice
+              value.serialize
+            when Hash
+              value
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot serialize #{value.class}"
+            end
+          end
+
+          def deserialize(value)
+            cast(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/provider_preferences/max_price.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        # Maximum price configuration for provider routing
+        # Specifies USD price per million tokens for different operations
+        # See: https://openrouter.ai/docs/provider-routing
+        class MaxPrice < Common::BaseModel
+          attribute :prompt,     :float # Price per million prompt tokens (input)
+          attribute :completion, :float # Price per million completion tokens (output)
+          attribute :image,      :float # Price per image
+          attribute :audio,      :float # Price per audio unit
+          attribute :request,    :float # Price per request
+
+          validates :prompt,     numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+          validates :completion, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+          validates :image,      numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+          validates :audio,      numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+          validates :request,    numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+
+          # Backwards Compatibility
+          alias_attribute :prompt_tokens, :prompt
+          alias_attribute :completion_tokens, :completion
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/provider_preferences.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "provider_preferences/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        # Provider preferences for routing requests to specific providers
+        # See: https://openrouter.ai/docs/provider-routing
+        class ProviderPreferences < Common::BaseModel
+          # Whether to allow backup providers to serve requests
+          # - true: (default) when primary provider is unavailable, use next best provider
+          # - false: use only primary/custom provider, return upstream error if unavailable
+          attribute :allow_fallbacks, :boolean
+
+          # Whether to filter providers to only those that support provided parameters
+          # If false, providers receive only parameters they support and ignore the rest
+          attribute :require_parameters, :boolean
+
+          # Data collection setting
+          # - allow: (default) allow providers which store user data and may train on it
+          # - deny: use only providers which do not collect user data
+          attribute :data_collection, :string
+
+          # Zero Data Retention - stricter privacy mode
+          attribute :zdr, :boolean
+
+          # Ordered list of provider slugs to try in order
+          attribute :order, default: -> { [] }
+
+          # List of provider slugs to allow (merged with account-wide settings)
+          attribute :only, default: -> { [] }
+
+          # List of provider slugs to ignore (merged with account-wide settings)
+          attribute :ignore, default: -> { [] }
+
+          # List of quantization levels to filter providers by
+          # Options: int4, int8, fp4, fp6, fp8, fp16, bf16, fp32, unknown
+          attribute :quantizations, default: -> { [] }
+
+          # Sorting strategy to use if "order" is not specified
+          # Options: price, throughput, latency
+          # When set, no load balancing is performed
+          attribute :sort, :string
+
+          # Maximum price constraints (USD per million tokens)
+          attribute :max_price, MaxPriceType.new
+
+          # Validations matching the schema
+          validates :data_collection, inclusion: { in: %w[deny allow] }, allow_nil: true
+          validates :sort, inclusion: { in: %w[price throughput latency] }, allow_nil: true
+          validates :quantizations, inclusion: {
+            in: [ %w[int4 int8 fp4 fp6 fp8 fp16 bf16 fp32 unknown].freeze ],
+            message: "must contain valid quantization levels"
+          }, allow_nil: true, if: -> { quantizations.is_a?(Array) && quantizations.any? }
+
+          # Backwards Compatibility
+          alias_attribute :enable_fallbacks, :allow_fallbacks
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/response_format.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        class ResponseFormat < Common::BaseModel
+          # Type of response format (json_object, json_schema)
+          attribute :type, :string
+
+          # JSON schema configuration (only for json_schema type)
+          attribute :json_schema # Hash with name, description, schema, strict
+
+          validates :type, inclusion: { in: %w[json_object json_schema] }, allow_nil: true
+
+          # Validate that json_schema is present when type is json_schema
+          validate :validate_json_schema_presence
+
+          private
+
+          def validate_json_schema_presence
+            if type == "json_schema" && json_schema.blank?
+              errors.add(:json_schema, "must be present when type is 'json_schema'")
+            end
+
+            if json_schema.present? && json_schema.is_a?(Hash)
+              validate_json_schema_structure
+            end
+          end
+
+          def validate_json_schema_structure
+            unless json_schema[:name].present?
+              errors.add(:json_schema, "must include 'name' field")
+            end
+
+            if json_schema[:name].present? && json_schema[:name].length > 64
+              errors.add(:json_schema, "name must be 64 characters or less")
+            end
+
+            # Name must match pattern: a-z, A-Z, 0-9, underscores and dashes
+            if json_schema[:name].present? && json_schema[:name] !~ /^[a-zA-Z0-9_-]+$/
+              errors.add(:json_schema, "name must contain only a-z, A-Z, 0-9, underscores and dashes")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router_provider.rb

@@ -0,0 +1,53 @@
+require_relative "_base_provider"
+
+require_gem!(:openai, __FILE__)
+
+require_relative "open_ai_provider"
+require_relative "open_router/_types"
+
+module ActiveAgent
+  module Providers
+    # Provides access to OpenRouter's multi-model API.
+    #
+    # Extends OpenAI provider to work with OpenRouter's OpenAI-compatible API,
+    # enabling access to multiple AI models through a single interface with
+    # model fallbacks, cost tracking, and provider metadata.
+    #
+    # @see OpenAI::ChatProvider
+    # @see https://openrouter.ai/docs
+    class OpenRouterProvider < OpenAI::ChatProvider
+      # @return [String]
+      def self.service_name
+        "OpenRouter"
+      end
+
+      # @return [Class]
+      def self.options_klass
+        namespace::Options
+      end
+
+      # @return [ActiveModel::Type::Value]
+      def self.prompt_request_type
+        namespace::RequestType.new
+      end
+
+      protected
+
+      # Merges streaming delta into the message with role cleanup.
+      #
+      # Overrides parent to handle OpenRouter's role copying behavior which duplicates
+      # the role field in every streaming chunk, requiring manual cleanup to prevent
+      # message corruption.
+      #
+      # @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
+    end
+  end
+end

data/lib/active_agent/providers/openai_provider.rb

@@ -0,0 +1,2 @@
+# OpenAI, "Your tacky and I hate you" - Billy, https://youtu.be/dsheboxJNgQ?si=tzDlJ7sdSxM4RjSD
+require_relative "open_ai_provider"

data/lib/active_agent/providers/openrouter_provider.rb

@@ -0,0 +1,2 @@
+# OpenRouter, just copying OpenAI
+require_relative "open_router_provider"

data/lib/active_agent/railtie.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
+require "rails"
 require "active_job/railtie"
 require "active_agent"
-# require "active_agent/engine"
-require "rails"
-require "abstract_controller/railties/routes_helpers"
 require "active_agent/railtie/schema_generator_extension"
+require "abstract_controller/railties/routes_helpers"
 
 module ActiveAgent
   class Railtie < Rails::Railtie # :nodoc:
@@ -22,7 +21,7 @@ module ActiveAgent
     end
 
     initializer "active_agent.set_configs" do |app|
-      paths = app.config.paths
+      paths   = app.config.paths
       options = app.config.active_agent
 
       options.assets_dir ||= paths["public"].first
@@ -33,10 +32,13 @@ module ActiveAgent
       options.preview_paths |= [ "#{Rails.root}/test/agents/previews" ]
 
       # make sure readers methods get compiled
-      options.asset_host ||= app.config.asset_host
+      options.asset_host        ||= app.config.asset_host
       options.relative_url_root ||= app.config.relative_url_root
 
-      ActiveAgent.load_configuration(Rails.root.join("config", "active_agent.yml"))
+      # region configuration_load
+      # Loaded automatically via Railtie
+      ActiveAgent.configuration_load(Rails.root.join("config", "active_agent.yml"))
+      # endregion configuration_load
 
       ActiveSupport.on_load(:active_agent) do
         include AbstractController::UrlFor