activeagent 1.0.2 → 1.1.0

data/lib/active_agent/model_capabilities.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  # Per-model capability quirks, applied before a request reaches the
+  # provider. Vendors ship models that reject otherwise-standard sampling
+  # parameters (thinking-first models steered by prompting/effort instead)
+  # with an API 400 — this registry strips those parameters up front so an
+  # agent configured with a shared temperature keeps working across model
+  # switches.
+  #
+  # The built-in rules cover the known families; apps can extend the
+  # registry for new or self-hosted models:
+  #
+  # @example Register a custom rule
+  #   ActiveAgent::ModelCapabilities.register(/\Amy-reasoning-model/, unsupported: [:temperature, :top_p])
+  #
+  # @example Disable sanitization entirely
+  #   ActiveAgent::ModelCapabilities.enabled = false
+  module ModelCapabilities
+    SAMPLING_PARAMS = [ :temperature, :top_p ].freeze
+
+    # Model families that reject sampling parameters with a 400:
+    # - Anthropic thinking-first models (Opus 4.7+, Opus 5, Sonnet 5,
+    #   Fable 5 / Mythos 5)
+    # - OpenAI reasoning models (o-series, GPT-5 family)
+    BUILTIN_RULES = [
+      { pattern: /\Aclaude-(opus-5|opus-4-[78]|sonnet-5|fable-5|mythos-5)/, unsupported: SAMPLING_PARAMS },
+      { pattern: /\A(o1|o3|o4)(-|$)/, unsupported: SAMPLING_PARAMS },
+      { pattern: /\Agpt-5/, unsupported: SAMPLING_PARAMS }
+    ].freeze
+
+    class << self
+      # Master switch; on by default. Set false to send parameters through
+      # untouched (the vendor then enforces its own rules).
+      attr_writer :enabled
+
+      def enabled
+        return @enabled unless @enabled.nil?
+
+        true
+      end
+
+      # Registers an app-defined capability rule ahead of the built-ins.
+      #
+      # @param pattern [Regexp] matched against the model name
+      # @param unsupported [Array<Symbol>] parameter keys the model rejects
+      def register(pattern, unsupported:)
+        custom_rules << { pattern: pattern, unsupported: unsupported.map(&:to_sym) }
+      end
+
+      def custom_rules
+        @custom_rules ||= []
+      end
+
+      def reset!
+        @custom_rules = []
+        @enabled = nil
+      end
+
+      # @return [Array<Symbol>] parameter keys the model rejects
+      def unsupported_params(model)
+        return [] if model.nil?
+
+        (custom_rules + BUILTIN_RULES).each do |rule|
+          return rule[:unsupported] if model.to_s.match?(rule[:pattern])
+        end
+        []
+      end
+
+      def sampling_supported?(model)
+        (unsupported_params(model) & SAMPLING_PARAMS).empty?
+      end
+
+      # Strips parameters the model rejects, in place. Returns the removed
+      # keys (empty when nothing applied).
+      #
+      # @param parameters [Hash] prepared prompt parameters (must carry :model)
+      # @return [Array<Symbol>] removed parameter keys
+      def sanitize!(parameters)
+        return [] unless enabled
+        return [] unless parameters.is_a?(Hash)
+
+        removed = unsupported_params(parameters[:model]).select { |key| parameters.key?(key) }
+        removed.each { |key| parameters.delete(key) }
+        removed
+      end
+    end
+  end
+end

data/lib/active_agent/providers/_base_provider.rb

@@ -55,7 +55,13 @@ module ActiveAgent
                     :request, :message_stack,        # Runtime
                     :stream_broadcaster, :streaming, # Callback (Streams)
                     :tools_function,                 # Callback (Tools)
-                    :usage_stack                     # Usage Tracking
+                    :usage_stack,                    # Usage Tracking
+                    :max_tool_turns, :tool_turns     # Tool-loop safety
+
+      # Upper bound on tool-calling round-trips within one generation. A
+      # model that keeps emitting tool calls otherwise recurses until the
+      # provider stops it — override per agent/prompt with max_tool_turns:.
+      DEFAULT_MAX_TOOL_TURNS = 25
 
       # @return [String] e.g., "Anthropic", "OpenAI"
       def self.service_name
@@ -106,6 +112,8 @@ module ActiveAgent
         self.stream_broadcaster = kwargs.delete(:stream_broadcaster)
         self.streaming          = false
         self.tools_function     = kwargs.delete(:tools_function)
+        self.max_tool_turns     = kwargs.delete(:max_tool_turns) || DEFAULT_MAX_TOOL_TURNS
+        self.tool_turns         = 0
         self.options            = options_klass.new(kwargs.extract!(*options_klass.keys))
         self.context            = kwargs
         self.message_stack      = []
@@ -344,7 +352,7 @@ module ActiveAgent
           message_stack.push(*api_messages)
         end
 
-        if (tool_calls = process_prompt_finished_extract_function_calls)&.any?
+        if (tool_calls = process_prompt_finished_extract_function_calls)&.any? && tool_turn_allowed?
           process_function_calls(tool_calls)
           resolve_prompt
         else
@@ -373,6 +381,19 @@ module ActiveAgent
         end
       end
 
+      # Counts a tool round-trip against the per-generation cap. When the
+      # cap is hit the loop finishes cleanly with the messages gathered so
+      # far (a partial result) instead of recursing indefinitely.
+      #
+      # @return [Boolean] whether another tool round-trip may run
+      def tool_turn_allowed?
+        self.tool_turns += 1
+        return true if max_tool_turns.nil? || tool_turns <= max_tool_turns
+
+        instrument("tool_turns_exceeded.active_agent", limit: max_tool_turns)
+        false
+      end
+
       # @abstract
       # @param api_response [Object]
       # @return [Array<Message>, nil]

data/lib/active_agent/providers/anthropic/request.rb

@@ -71,7 +71,9 @@ module ActiveAgent
         # @raise [ArgumentError] when gem model validation fails
         def initialize(**params)
           # Step 1: Extract custom fields that gem doesn't support
-          @response_format = params.delete(:response_format)
+          # Read response_format without deleting - normalize_params will delete and convert it
+          # to output_config for json_schema, or drop it for other types.
+          @response_format = params[:response_format]
           @stream = params.delete(:stream)
           anthropic_beta = params.delete(:anthropic_beta)
 

data/lib/active_agent/providers/anthropic/transforms.rb

@@ -31,6 +31,12 @@ module ActiveAgent
             params[:tools] = normalize_tools(params[:tools]) if params[:tools]
             params[:tool_choice] = normalize_tool_choice(params[:tool_choice]) if params[:tool_choice]
 
+            # Normalize json_schema response_format → output_config (Anthropic's native structured output field)
+            if params[:response_format]
+              output_config = normalize_response_format(params.delete(:response_format))
+              params[:output_config] = output_config if output_config
+            end
+
             # Handle mcps parameter (common format) -> transforms to mcp_servers (provider format)
             if params[:mcps]
               params[:mcp_servers] = normalize_mcp_servers(params.delete(:mcps))
@@ -159,6 +165,87 @@ module ActiveAgent
             end
           end
 
+          # Normalizes response_format to Anthropic output_config structure.
+          #
+          # Supported (ActiveAgent common format):
+          #   { type: "json_schema", json_schema: { name: "...", schema: {...}, strict: true } }
+          # → { format: { type: "json_schema", schema: {...} } }
+          #
+          # Notes:
+          # - Anthropic requires `additionalProperties: false` on all object schemas.
+          #   This is auto-injected into any object schemas that don't have it set.
+          # - Anthropic does not use OpenAI's `name` or `strict` fields in output_config.format.
+          # - json_object is not handled here; it remains prompt-emulated.
+          # - text is not handled here; Anthropic returns plain text by default.
+          #
+          # @param format [Hash, Symbol, String] ActiveAgent common response_format
+          # @return [Hash] Anthropic output_config hash, or nil if not applicable
+          def normalize_response_format(format)
+            case format
+            when Hash
+              format_hash = format.deep_symbolize_keys
+
+              if format_hash[:type].to_s == "json_schema"
+                schema = format_hash[:json_schema]&.dig(:schema)
+                if schema
+                  schema = inject_additional_properties(schema.deep_dup)
+                end
+                {
+                  format: {
+                    type: "json_schema",
+                    schema: schema
+                  }.compact
+                }
+              elsif format_hash[:type].to_s == "json_object"
+                # json_object is not handled here; it remains prompt-emulated.
+                nil
+              elsif format_hash[:type].to_s == "text"
+                # text is not handled here; it remains prompt-emulated.
+                nil
+              else
+                # Pass through (already properly structured or Anthropic native format)
+                format_hash
+              end
+            when Symbol, String
+              # Bare :json_schema without a schema cannot use native output_config.
+              # Anthropic requires a valid JSON Schema — return nil to fall back.
+              nil
+            else
+              format
+            end
+          end
+
+          # Recursively injects `additionalProperties: false` into all object schemas.
+          #
+          # Anthropic's structured output API requires this field on all object types.
+          # Only inserts when not already explicitly set by the user.
+          #
+          # @param schema [Hash] JSON Schema hash
+          # @return [Hash] schema with additionalProperties injected
+          def inject_additional_properties(schema)
+            return schema unless schema.is_a?(Hash)
+
+            if schema[:type] == "object" && !schema.key?(:additionalProperties)
+              schema[:additionalProperties] = false
+            end
+
+            # Recurse into nested schemas
+            schema[:properties]&.each_value { |prop| inject_additional_properties(prop) }
+            schema[:items]&.then { |items| inject_additional_properties(items) }
+            schema[:anyOf]&.each { |s| inject_additional_properties(s) }
+            schema[:oneOf]&.each { |s| inject_additional_properties(s) }
+            schema[:allOf]&.each { |s| inject_additional_properties(s) }
+
+            if schema[:definitions]
+              schema[:definitions].each_value { |defn| inject_additional_properties(defn) }
+            end
+            if schema[:"$defs"]
+              schema[:"$defs"].each_value { |defn| inject_additional_properties(defn) }
+            end
+
+            schema
+          end
+
           # Merges consecutive same-role messages into single messages with multiple content blocks.
           #
           # Required by Anthropic API - consecutive messages with the same role must be combined.
@@ -437,6 +524,7 @@ module ActiveAgent
                 msg.delete(:model)
                 msg.delete(:stop_reason)
                 msg.delete(:stop_sequence)
+                msg.delete(:stop_details)
                 msg.delete(:type)
                 msg.delete(:usage)
               end

data/lib/active_agent/providers/bedrock_provider.rb

@@ -15,11 +15,11 @@ module ActiveAgent
     #   bedrock:
     #     service: "Bedrock"
     #     aws_region: "eu-west-2"
-    #     model: "eu.anthropic.claude-sonnet-4-5-20250929-v1:0"
+    #     model: "eu.anthropic.claude-sonnet-5-v1:0"
     #
     # @example Agent usage
     #   class SummaryAgent < ApplicationAgent
-    #     generate_with :bedrock, model: "eu.anthropic.claude-sonnet-4-5-20250929-v1:0"
+    #     generate_with :bedrock, model: "eu.anthropic.claude-sonnet-5-v1:0"
     #
     #     def summarize
     #       prompt(message: params[:message])

data/lib/active_agent/providers/concerns/exception_handler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../errors"
+
 module ActiveAgent
   module Providers
     # Provides exception handling for provider operations.
@@ -54,7 +56,16 @@ module ActiveAgent
       def with_exception_handling(&block)
         yield
       rescue => exception
-        rescue_with_handler(exception) || raise
+        # Vendor API failures are normalized into the framework taxonomy
+        # (Errors::RateLimited, Errors::ContextLengthExceeded, ...) so
+        # rescue_from policy is portable across providers; the original
+        # exception is preserved as #cause. Anything unrecognizable —
+        # including ordinary Ruby errors — passes through untouched.
+        exception = Errors::Taxonomy.normalize(
+          exception,
+          provider_tag: (tag_name if respond_to?(:tag_name))
+        )
+        rescue_with_handler(exception) || raise(exception)
         nil # Discard handler return value to prevent polluting raw_response
       end
 

data/lib/active_agent/providers/errors.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    # Typed provider failures, normalized across vendor SDKs.
+    #
+    # Every vendor raises its own exception classes for the same underlying
+    # conditions (rate limits, context overflows, content filters, outages),
+    # which makes retry/backoff/fallback policy impossible to express
+    # portably. The taxonomy classifies vendor errors into a small set of
+    # framework types — the original exception is preserved as +#cause+, so
+    # nothing is lost.
+    #
+    # @example Portable retry policy
+    #   rescue_from ActiveAgent::Providers::Errors::RateLimited do |error|
+    #     retry_job wait: 30.seconds
+    #   end
+    #
+    # @example Fallback on outage
+    #   rescue_from ActiveAgent::Providers::Errors::ServiceUnavailable do |error|
+    #     FallbackAgent.with(params).ask.generate_later
+    #   end
+    module Errors
+      # Base class for normalized provider failures.
+      class ProviderError < StandardError
+        # @return [Integer, nil] HTTP status from the vendor error, when known
+        attr_reader :status
+
+        # @return [String, nil] provider tag (e.g. "Anthropic", "OpenAI::Chat")
+        attr_reader :provider_tag
+
+        def initialize(message = nil, status: nil, provider_tag: nil)
+          super(message)
+          @status = status
+          @provider_tag = provider_tag
+        end
+      end
+
+      # 429s / vendor rate & quota limits. Retryable with backoff.
+      class RateLimited < ProviderError; end
+
+      # The prompt exceeded the model's context window. Not retryable
+      # without shrinking the input.
+      class ContextLengthExceeded < ProviderError; end
+
+      # Invalid, expired, or unauthorized credentials (401/403).
+      class AuthenticationFailed < ProviderError; end
+
+      # The vendor's safety layer refused the request or response.
+      class ContentFiltered < ProviderError; end
+
+      # Vendor-side failure or overload (5xx, timeouts, connection drops).
+      # Retryable; a natural trigger for provider fallback.
+      class ServiceUnavailable < ProviderError; end
+
+      # Malformed or unsupported request the vendor rejected (400/422)
+      # that doesn't classify more specifically.
+      class InvalidRequest < ProviderError; end
+
+      # Classifies vendor SDK exceptions into the taxonomy. Unrecognizable
+      # exceptions (including ordinary Ruby errors) pass through untouched —
+      # only errors that look like vendor API failures are normalized.
+      module Taxonomy
+        # Vendor SDK class names (demodulized) → taxonomy class. Covers the
+        # official anthropic/openai gems and SDKs following their naming.
+        NAME_MAP = {
+          "RateLimitError" => RateLimited,
+          "AuthenticationError" => AuthenticationFailed,
+          "PermissionDeniedError" => AuthenticationFailed,
+          "ContentFilterError" => ContentFiltered,
+          "InternalServerError" => ServiceUnavailable,
+          "APIConnectionError" => ServiceUnavailable,
+          "APIConnectionTimeoutError" => ServiceUnavailable,
+          "APITimeoutError" => ServiceUnavailable,
+          "OverloadedError" => ServiceUnavailable,
+          "ServiceUnavailableError" => ServiceUnavailable,
+          "BadRequestError" => InvalidRequest,
+          "UnprocessableEntityError" => InvalidRequest
+        }.freeze
+
+        STATUS_MAP = {
+          400 => InvalidRequest,
+          401 => AuthenticationFailed,
+          403 => AuthenticationFailed,
+          408 => ServiceUnavailable,
+          422 => InvalidRequest,
+          429 => RateLimited,
+          529 => ServiceUnavailable # Anthropic "overloaded"
+        }.freeze
+
+        CONTEXT_LENGTH_PATTERN = /context length|context_length|maximum context|context window|too many tokens|prompt is too long|input (?:is )?too long/i
+        CONTENT_FILTER_PATTERN = /content (?:filter|policy|management)|filtered due to|blocked by|safety (?:system|filter)/i
+
+        class << self
+          # @param exception [Exception]
+          # @param provider_tag [String, nil]
+          # @return [Exception] a taxonomy error, or the original exception
+          #   when it doesn't classify
+          def normalize(exception, provider_tag: nil)
+            return exception if exception.is_a?(ProviderError)
+
+            klass = classify(exception)
+            return exception unless klass
+
+            klass.new(exception.message, status: status_of(exception), provider_tag: provider_tag)
+          end
+
+          # @return [Class, nil]
+          def classify(exception)
+            name = exception.class.name.to_s.demodulize
+            status = status_of(exception)
+            api_error = NAME_MAP.key?(name) || !status.nil?
+            return nil unless api_error
+
+            message = exception.message.to_s
+            return ContextLengthExceeded if CONTEXT_LENGTH_PATTERN.match?(message)
+            return ContentFiltered if CONTENT_FILTER_PATTERN.match?(message)
+
+            NAME_MAP[name] || STATUS_MAP[status] || (status && status >= 500 ? ServiceUnavailable : nil)
+          end
+
+          # @return [Integer, nil]
+          def status_of(exception)
+            [ :status, :status_code, :http_status, :code ].each do |reader|
+              next unless exception.respond_to?(reader)
+
+              value = begin
+                exception.public_send(reader)
+              rescue StandardError
+                nil
+              end
+              return value if value.is_a?(Integer)
+            end
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/mock/request.rb

@@ -22,16 +22,13 @@ module ActiveAgent
         attribute :stream, :boolean, default: false
         attribute :tools # Array of tool definitions
         attribute :tool_choice # Tool choice configuration
+        attribute :response_format
 
         # Common Format Compatibility
         def message=(value)
           self.messages ||= []
           self.messages << value
         end
-
-        def response_format
-          { type: "text" }
-        end
       end
     end
   end

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

@@ -55,12 +55,18 @@ module ActiveAgent
               OpenAI::Chat::Transforms.normalize_messages(messages)
             end
 
-            # Normalizes instructions using OpenAI transforms
+            # Normalizes instructions using OpenAI transforms, then remaps the
+            # role: OpenAI's transforms emit the "developer" role, but the chat
+            # templates of Ollama-served models (qwen, llama, gemma, …) only
+            # know "system" — a "developer" message is silently dropped, so the
+            # model never sees its instructions.
             #
             # @param instructions [Array<String>, String]
-            # @return [Array<OpenAI::Models::Chat::ChatCompletionMessageParam>]
+            # @return [Array<Hash>] system messages
             def normalize_instructions(instructions)
-              OpenAI::Chat::Transforms.normalize_instructions(instructions)
+              OpenAI::Chat::Transforms.normalize_instructions(instructions).map do |message|
+                message.is_a?(Hash) ? message.merge(role: "system") : message
+              end
             end
 
             # Cleans up serialized request for API submission

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

@@ -104,7 +104,7 @@ module ActiveAgent
 
             # If we have a delta, we need to update a message in the stack
             message = find_or_create_message(api_message.index)
-            message = message_merge_delta(message, api_message.delta.as_json.deep_symbolize_keys)
+            message_merge_delta(message, api_message.delta.deep_to_h)
 
             # Stream back content changes as they come in
             if api_message.delta.content
@@ -140,7 +140,7 @@ module ActiveAgent
         def process_function_calls(api_function_calls)
           api_function_calls.each do |api_function_call|
             content = instrument("tool_call.active_agent", tool_name: api_function_call.dig(:function, :name)) do
-              case api_function_call[:type]
+              case api_function_call[:type].to_s
               when "function"
                 process_tool_call_function(api_function_call[:function])
               else
@@ -245,7 +245,7 @@ module ActiveAgent
                 end
               end
             when String
-              hash[key] += value
+              hash[key] += value.to_s
             else
               hash[key] = value
             end

data/lib/active_agent/providers/requesty/_types.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/chat/_types"
+require_relative "options"
+
+module ActiveAgent
+  module Providers
+    module Requesty
+      # ActiveModel type for casting and serializing Requesty requests.
+      #
+      # Requesty is OpenAI-compatible, so requests use the same shape as the
+      # OpenAI Chat API. This delegates entirely to OpenAI::Chat::RequestType.
+      RequestType = ActiveAgent::Providers::OpenAI::Chat::RequestType
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/options"
+
+module ActiveAgent
+  module Providers
+    module Requesty
+      # Configuration options for the Requesty provider.
+      #
+      # Extends OpenAI::Options, overriding the base URL to point at Requesty's
+      # OpenAI-compatible gateway and resolving the API key from REQUESTY_API_KEY.
+      # Requesty does not use organization or project identifiers.
+      #
+      # @example Basic configuration
+      #   options = Options.new(api_key: ENV["REQUESTY_API_KEY"])
+      #
+      # @see https://docs.requesty.ai
+      # @see https://app.requesty.ai/api-keys Requesty API Keys
+      class Options < ActiveAgent::Providers::OpenAI::Options
+        # @!attribute base_url
+        #   @return [String] API endpoint (default: "https://router.requesty.ai/v1")
+        attribute :base_url, :string, as: "https://router.requesty.ai/v1"
+
+        private
+
+        def resolve_api_key(kwargs)
+          kwargs[:api_key] ||
+            kwargs[:access_token] ||
+            ENV["REQUESTY_API_KEY"] ||
+            ENV["REQUESTY_ACCESS_TOKEN"]
+        end
+
+        # Not used as part of Requesty
+        def resolve_organization_id(kwargs) = nil
+        def resolve_project_id(kwargs)      = nil
+      end
+    end
+  end
+end

data/lib/active_agent/providers/requesty_provider.rb

@@ -0,0 +1,63 @@
+require_relative "_base_provider"
+
+require_gem!(:openai, __FILE__)
+
+require_relative "open_ai_provider"
+require_relative "requesty/_types"
+
+module ActiveAgent
+  module Providers
+    # Provides access to Requesty's OpenAI-compatible LLM gateway.
+    #
+    # Extends the OpenAI provider to work with Requesty's OpenAI-compatible API,
+    # enabling access to multiple AI models through a single interface using the
+    # +provider/model+ naming convention (e.g. +openai/gpt-4o-mini+).
+    #
+    # Requesty is a plain OpenAI-compatible gateway: requests, responses and
+    # transforms are identical to the OpenAI Chat API, so this provider reuses
+    # OpenAI::Chat::RequestType and OpenAI::Chat::Transforms directly. The only
+    # Requesty-specific configuration is the base URL and API key, which live in
+    # Requesty::Options.
+    #
+    # @example Configuration in active_agent.yml
+    #   requesty:
+    #     service: "Requesty"
+    #     api_key: <%= ENV["REQUESTY_API_KEY"] %>
+    #     model: "openai/gpt-4o-mini"
+    #
+    # @see OpenAI::ChatProvider
+    # @see https://docs.requesty.ai
+    class RequestyProvider < OpenAI::ChatProvider
+      # @return [String]
+      def self.service_name
+        "Requesty"
+      end
+
+      # @return [Class]
+      def self.options_klass
+        Requesty::Options
+      end
+
+      # @return [ActiveModel::Type::Value]
+      def self.prompt_request_type
+        OpenAI::Chat::RequestType.new
+      end
+
+      # @return [ActiveModel::Type::Value]
+      def self.embed_request_type
+        OpenAI::Embedding::RequestType.new
+      end
+
+      protected
+
+      # @see BaseProvider#api_response_normalize
+      # @param api_response [OpenAI::Models::ChatCompletion]
+      # @return [Hash] normalized response hash
+      def api_response_normalize(api_response)
+        return api_response unless api_response
+
+        OpenAI::Chat::Transforms.gem_to_hash(api_response)
+      end
+    end
+  end
+end

data/lib/active_agent/railtie.rb

@@ -67,6 +67,11 @@ module ActiveAgent
           include ActiveAgent::Telemetry::Instrumentation
           instrument_telemetry!
         end
+
+        # Flush remaining traces when the process exits — without this,
+        # short-lived processes (rails runner, jobs, deploys rolling a
+        # server) drop whatever was buffered since the last interval flush.
+        at_exit { ActiveAgent::Telemetry.shutdown }
       end
       # endregion telemetry_configuration