activeagent 1.2.0 → 1.3.0

data/lib/active_agent/delegation/backend.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Delegation
+    # The provider and options a delegated call runs against.
+    #
+    # A sub-agent's contract — what it accepts, what it returns — is separate
+    # from what actually serves it. Backend is that seam: the same
+    # +SummarizerAgent+ can run on a cheap local model inside one parent and on
+    # a frontier model inside another, and neither parent's code changes when
+    # you move it.
+    #
+    # @example Swap the model, keep the provider
+    #   delegate_to SummarizerAgent, backend: { model: "gpt-4o-mini", temperature: 0 }
+    #
+    # @example Swap the provider entirely
+    #   delegate_to SummarizerAgent, backend: :ollama
+    #
+    # @example Swap both
+    #   delegate_to SummarizerAgent, backend: { provider: :anthropic, model: "claude-haiku-4-5" }
+    class Backend
+      # @return [Symbol, nil] provider reference (+:openai+, +:anthropic+, ...)
+      attr_reader :provider
+      # @return [Hash] prompt options applied at the call site
+      attr_reader :options
+
+      # @param spec [Backend, Symbol, String, Hash, nil]
+      # @return [Backend]
+      def self.build(spec = nil)
+        case spec
+        when Backend        then spec
+        when nil            then new
+        when Symbol, String then new(provider: spec)
+        when Hash           then new(**spec.symbolize_keys)
+        else
+          raise ArgumentError, "Delegation backend must be a Symbol, Hash or #{name}, got #{spec.inspect}"
+        end
+      end
+
+      # @param provider [Symbol, String, nil]
+      # @param options [Hash] prompt options (model, temperature, ...)
+      def initialize(provider: nil, **options)
+        @provider = provider&.to_sym
+        @options  = options
+        @mutex    = Mutex.new
+      end
+
+      # @return [Boolean] whether this backend changes anything
+      def overrides?
+        provider.present? || options.any?
+      end
+
+      # Resolves the class a delegated call should instantiate.
+      #
+      # Swapping providers means rebuilding provider configuration (host, keys,
+      # service), not just merging a hash — so the swap goes through a cached
+      # subclass configured by +generate_with+, the same code path a
+      # hand-written agent takes. The subclass reports its parent's name so
+      # template lookup keeps resolving to the original agent's views.
+      #
+      # @param agent_class [Class] the declared sub-agent class
+      # @return [Class]
+      def agent_class_for(agent_class)
+        return agent_class if provider.blank?
+
+        @mutex.synchronize do
+          @agent_classes ||= {}
+          @agent_classes[agent_class] ||= build_agent_class(agent_class)
+        end
+      end
+
+      # Applies call-site options to a prepared agent instance.
+      #
+      # Applied after the action has run so the delegation site wins over the
+      # sub-agent's own +prompt+ options — a call-site override is runtime
+      # configuration, which outranks class configuration everywhere else in
+      # ActiveAgent.
+      #
+      # @param agent [ActiveAgent::Base]
+      # @return [ActiveAgent::Base]
+      def apply(agent)
+        agent.prompt_options.merge!(options) if options.any?
+        agent
+      end
+
+      # @return [Hash]
+      def to_h
+        { provider: provider }.compact.merge(options)
+      end
+
+      private
+
+      # @param agent_class [Class]
+      # @return [Class]
+      def build_agent_class(agent_class)
+        backend_provider = provider
+        inherited_name   = agent_class.name
+
+        Class.new(agent_class) do
+          # Keep the parent's identity so `agent_name`, and therefore view
+          # lookup, resolves to the original agent's templates.
+          define_singleton_method(:name) { inherited_name }
+
+          generate_with backend_provider
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/delegation/budget.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Delegation
+    # Cost and latency limits for delegated work.
+    #
+    # A sub-agent is a loop inside a loop: the parent model decides how often
+    # to call it, and each call spends tokens and wall-clock time nobody
+    # explicitly authorized. A budget puts a ceiling on that — per delegation
+    # and across the agent as a whole — so a runaway hand-off degrades into a
+    # bounded answer instead of an unbounded bill.
+    #
+    # Every limit is optional; an empty budget imposes nothing.
+    #
+    # @example Per delegation
+    #   delegate_to SummarizerAgent, budget: { max_calls: 3, max_tokens: 8_000, timeout: 20 }
+    #
+    # @example Across every delegation this agent makes
+    #   delegation_budget max_calls: 10, max_duration: 60, max_cost: 0.25,
+    #                     rates: { input: 0.15, output: 0.60 }
+    class Budget
+      # What to do when a limit is reached.
+      #
+      # +:stop+  — return a structured "budget exhausted" result to the calling
+      #            model so it can finish with what it already has (default).
+      # +:raise+ — raise {BudgetExceededError} and abort the generation.
+      POLICIES = %i[stop raise].freeze
+
+      LIMITS = %i[max_calls max_tokens max_cost max_duration].freeze
+      KEYS   = (LIMITS + %i[timeout rates on_exceeded]).freeze
+
+      # A limit that has been reached.
+      Violation = Struct.new(:limit, :allowed, :used, keyword_init: true) do
+        # @return [String] wording aimed at the calling model, not at a developer
+        def message
+          "Delegation budget exhausted (#{limit}: #{format_number(used)} of #{format_number(allowed)} used). " \
+            "Do not retry this tool; answer with the information you already have."
+        end
+
+        private
+
+        def format_number(value)
+          value.is_a?(Float) ? value.round(6) : value
+        end
+      end
+
+      # @return [Integer, nil] maximum number of delegated calls
+      attr_reader :max_calls
+      # @return [Integer, nil] maximum cumulative tokens across delegated calls
+      attr_reader :max_tokens
+      # @return [Float, nil] maximum cumulative spend in USD
+      attr_reader :max_cost
+      # @return [Float, nil] maximum cumulative wall-clock seconds
+      attr_reader :max_duration
+      # @return [Float, nil] per-call wall-clock timeout in seconds
+      attr_reader :timeout
+      # @return [Hash, nil] inline token rates in USD per 1M tokens
+      attr_reader :rates
+      # @return [Symbol, nil] :stop or :raise
+      attr_reader :on_exceeded
+
+      # Coerces a budget spec into a Budget.
+      #
+      # @param spec [Budget, Hash, nil]
+      # @return [Budget]
+      # @raise [ArgumentError] on unknown keys or an invalid policy
+      def self.build(spec = nil)
+        case spec
+        when Budget then spec
+        when nil    then new
+        when Hash   then new(**spec.symbolize_keys)
+        else
+          raise ArgumentError, "Delegation budget must be a Hash or #{name}, got #{spec.inspect}"
+        end
+      end
+
+      def initialize(**options)
+        unknown = options.keys - KEYS
+        raise ArgumentError, "Unknown delegation budget keys: #{unknown.join(", ")}. Valid keys: #{KEYS.join(", ")}" if unknown.any?
+
+        @max_calls    = options[:max_calls]
+        @max_tokens   = options[:max_tokens]
+        @max_cost     = options[:max_cost]
+        @max_duration = options[:max_duration]
+        @timeout      = options[:timeout]
+        @rates        = options[:rates]
+        @on_exceeded  = options[:on_exceeded]&.to_sym
+
+        if @on_exceeded && !POLICIES.include?(@on_exceeded)
+          raise ArgumentError, "Unknown delegation budget policy #{@on_exceeded.inspect}. Valid policies: #{POLICIES.join(", ")}"
+        end
+      end
+
+      # Returns a budget where +other+'s settings win over this one's.
+      #
+      # @param other [Budget, nil]
+      # @return [Budget]
+      def merge(other)
+        return self if other.nil?
+
+        self.class.new(**to_h.merge(other.to_h))
+      end
+
+      # @return [Boolean] whether any limit is set
+      def limited?
+        LIMITS.any? { |limit| public_send(limit) }
+      end
+
+      # @return [Symbol] the effective policy
+      def policy
+        on_exceeded || :stop
+      end
+
+      # Finds the first limit the ledger has already reached.
+      #
+      # Limits are checked *before* a call runs, because token spend can only
+      # be measured after the fact. A budget of +max_tokens: 8_000+ therefore
+      # means "stop delegating once 8,000 tokens have been spent", not "never
+      # exceed 8,000 tokens".
+      #
+      # @param ledger [Ledger]
+      # @return [Violation, nil]
+      def violation_for(ledger)
+        return Violation.new(limit: :max_calls,    allowed: max_calls,    used: ledger.calls)    if max_calls    && ledger.calls    >= max_calls
+        return Violation.new(limit: :max_tokens,   allowed: max_tokens,   used: ledger.tokens)   if max_tokens   && ledger.tokens   >= max_tokens
+        return Violation.new(limit: :max_cost,     allowed: max_cost,     used: ledger.cost)     if max_cost     && ledger.cost     >= max_cost
+        return Violation.new(limit: :max_duration, allowed: max_duration, used: ledger.duration) if max_duration && ledger.duration >= max_duration
+
+        nil
+      end
+
+      # @return [Hash] only the settings that were actually provided
+      def to_h
+        KEYS.index_with { |key| public_send(key) }.compact
+      end
+    end
+  end
+end

data/lib/active_agent/delegation/contract.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ActiveAgent
+  module Delegation
+    # What a sub-agent promises: one action, its inputs, and optionally the
+    # shape of what it returns.
+    #
+    # The contract is declared on the sub-agent itself, next to the action it
+    # describes, so a delegation stays correct when the action changes. Callers
+    # then say only which agent they want — they never restate its parameters.
+    #
+    # @example
+    #   class SummarizerAgent < ApplicationAgent
+    #     delegation :summarize, description: "Condense a document into key points" do
+    #       string  :text, required: true, description: "Full document text"
+    #       integer :limit, description: "Maximum number of key points"
+    #
+    #       returns do
+    #         string :summary, required: true, description: "One-paragraph summary"
+    #         array  :points, of: :string, required: true, description: "Key points"
+    #       end
+    #     end
+    #
+    #     def summarize(text:, limit: 5)
+    #       prompt(message: text, limit: limit)
+    #     end
+    #   end
+    class Contract
+      # What to do when a sub-agent's output does not satisfy its +returns+ schema.
+      #
+      # +:error+ — hand the calling model a structured error so it can retry or
+      #            route around the failure (default).
+      # +:raise+ — raise {InvalidResultError} and abort the generation.
+      INVALID_POLICIES = %i[error raise].freeze
+
+      # @return [Symbol] the sub-agent action this contract describes
+      attr_reader :action
+      # @return [String] what the action does, written for the calling model
+      attr_reader :description
+      # @return [Schema] declared inputs
+      attr_reader :schema
+      # @return [Schema, nil] declared output shape, when the action returns structured data
+      attr_reader :returns
+      # @return [Budget] default budget suggested by the sub-agent
+      attr_reader :budget
+      # @return [Symbol] :error or :raise
+      attr_reader :on_invalid
+
+      # @param action [Symbol, String]
+      # @param description [String]
+      # @param schema [Schema, Hash, Class, nil] inputs, or nil to use the block DSL
+      # @param returns [Schema, Hash, Class, nil] declared output shape
+      # @param budget [Budget, Hash, nil] default budget for callers
+      # @param on_invalid [Symbol] :error or :raise
+      # @yield input DSL; may also call +returns+ to declare the output shape
+      def initialize(action:, description:, schema: nil, returns: nil, budget: nil, on_invalid: :error, &block)
+        @action      = action.to_sym
+        @description = description
+        @returns     = returns && Schema.build(returns)
+        @budget      = Budget.build(budget)
+        @on_invalid  = on_invalid.to_sym
+
+        unless INVALID_POLICIES.include?(@on_invalid)
+          raise ArgumentError, "Unknown delegation on_invalid policy #{@on_invalid.inspect}. " \
+            "Valid policies: #{INVALID_POLICIES.join(", ")}"
+        end
+
+        raise ArgumentError, "A delegation needs a description — it is the only thing the calling model reads" if @description.blank?
+
+        @schema = Schema.build(schema)
+
+        if block
+          dsl = DSL.new(self, @schema)
+          block.arity == 1 ? block.call(dsl) : dsl.instance_eval(&block)
+        end
+      end
+
+      # @return [Boolean]
+      def structured?
+        returns.present?
+      end
+
+      # Sets the declared output shape. Used by the DSL's +returns+ helper.
+      #
+      # @param schema [Schema]
+      # @return [Schema]
+      # @api private
+      def returns=(schema)
+        @returns = schema
+      end
+
+      # Wraps the input schema DSL so that +returns+ inside a delegation block
+      # declares the *output* shape rather than an input property.
+      #
+      # @api private
+      class DSL < SimpleDelegator
+        # @param contract [Contract]
+        # @param schema [Schema]
+        def initialize(contract, schema)
+          @contract = contract
+          super(schema)
+        end
+
+        # Declares the shape the action returns.
+        #
+        # @param source [Schema, Hash, Class, nil]
+        # @yield output DSL
+        # @return [Schema]
+        def returns(source = nil, &block)
+          @contract.returns = Schema.build(source, &block)
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/delegation/definition.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Delegation
+    # A sub-agent bound into a calling agent as a tool.
+    #
+    # Pairs the sub-agent's {Contract} — what it accepts and returns — with the
+    # decisions that belong to the caller: what to call it, what it may spend,
+    # and which backend serves it.
+    class Definition
+      # @return [Class] the sub-agent class
+      attr_reader :agent_class
+      # @return [Contract]
+      attr_reader :contract
+      # @return [Symbol] the tool name exposed to the calling model
+      attr_reader :tool_name
+      # @return [String]
+      attr_reader :description
+      # @return [Backend]
+      attr_reader :backend
+      # @return [Budget]
+      attr_reader :budget
+      # @return [Hash, Symbol, Proc, nil] params forwarded to the sub-agent
+      attr_reader :params
+
+      # @param agent_class [Class]
+      # @param contract [Contract]
+      # @param tool_name [Symbol, String, nil] defaults to the contract's action
+      # @param description [String, nil] overrides the contract's description
+      # @param backend [Backend, Symbol, Hash, nil]
+      # @param budget [Budget, Hash, nil] merged over the contract's default budget
+      # @param params [Hash, Symbol, Proc, nil]
+      def initialize(agent_class:, contract:, tool_name: nil, description: nil, backend: nil, budget: nil, params: nil)
+        @agent_class = agent_class
+        @contract    = contract
+        @tool_name   = (tool_name || contract.action).to_sym
+        @description = description.presence || contract.description
+        @backend     = Backend.build(backend)
+        @budget      = contract.budget.merge(Budget.build(budget))
+        @params      = params
+      end
+
+      # @return [Symbol] the sub-agent action invoked
+      def action = contract.action
+
+      # @return [Schema] declared inputs
+      def schema = contract.schema
+
+      # @return [Schema, nil] declared outputs
+      def returns = contract.returns
+
+      # @return [Boolean]
+      def structured? = contract.structured?
+
+      # @return [Symbol]
+      def on_invalid = contract.on_invalid
+
+      # The class a call actually instantiates, after any backend swap.
+      #
+      # @return [Class]
+      def resolved_agent_class
+        backend.agent_class_for(agent_class)
+      end
+
+      # Tool definition in ActiveAgent's common tools format.
+      #
+      # This is what the calling model sees — the whole point of declaring a
+      # schema rather than describing the sub-agent in prose.
+      #
+      # @return [Hash]
+      def to_tool
+        {
+          name: tool_name.to_s,
+          description: description,
+          parameters: schema.to_json_schema
+        }
+      end
+
+      # Returns a copy with call-site overrides applied.
+      #
+      # @return [Definition]
+      def with(tool_name: nil, description: nil, backend: nil, budget: nil, params: nil)
+        self.class.new(
+          agent_class: agent_class,
+          contract: contract,
+          tool_name: tool_name || self.tool_name,
+          description: description || self.description,
+          backend: backend || self.backend,
+          budget: budget ? self.budget.merge(Budget.build(budget)) : self.budget,
+          params: params || self.params
+        )
+      end
+    end
+  end
+end

data/lib/active_agent/delegation/ledger.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Delegation
+    # Running tally of what delegated work has consumed.
+    #
+    # One ledger is kept per delegation plus one for the agent as a whole, and
+    # both live on the agent instance — which is created fresh for every
+    # generation. A budget is therefore scoped to a single generation and its
+    # entire tool loop, with no cross-request bleed and nothing to reset.
+    #
+    # @example Inspecting spend after a generation
+    #   agent = ResearchAgent.new
+    #   agent.process(:research, topic: "hydrogen storage")
+    #   agent.process_prompt
+    #   agent.delegation_ledger.to_h
+    #   #=> { calls: 2, tokens: 1_840, cost: 0.0004, duration: 3.1 }
+    class Ledger
+      # @return [Integer] delegated calls completed
+      attr_reader :calls
+      # @return [Integer] cumulative total tokens
+      attr_reader :tokens
+      # @return [Float] cumulative USD spend (0.0 when no rates are known)
+      attr_reader :cost
+      # @return [Float] cumulative wall-clock seconds
+      attr_reader :duration
+
+      def initialize
+        @calls    = 0
+        @tokens   = 0
+        @cost     = 0.0
+        @duration = 0.0
+      end
+
+      # Records one delegated call.
+      #
+      # @param tokens [Integer, nil]
+      # @param cost [Float, nil] nil when the model's rates are unknown
+      # @param duration [Float] seconds
+      # @return [self]
+      def record(tokens: 0, cost: nil, duration: 0.0)
+        @calls    += 1
+        @tokens   += tokens.to_i
+        @cost     += cost.to_f
+        @duration += duration.to_f
+
+        self
+      end
+
+      # @return [Hash]
+      def to_h
+        { calls: calls, tokens: tokens, cost: cost, duration: duration }
+      end
+    end
+  end
+end

data/lib/active_agent/delegation/pricing.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Delegation
+    # Token price registry used to turn usage into dollars for cost budgets.
+    #
+    # ActiveAgent deliberately ships no built-in price list: vendor pricing
+    # changes far faster than a gem release, and a stale table silently
+    # under-reports spend. Register the rates your app actually pays — once,
+    # in an initializer — and every cost budget in the app uses them.
+    #
+    # Rates are expressed in **USD per one million tokens**, matching how
+    # every major provider publishes them.
+    #
+    # @example Register rates for the models you use
+    #   # config/initializers/active_agent.rb
+    #   ActiveAgent::Delegation::Pricing.register("gpt-4o-mini", input: 0.15, output: 0.60)
+    #   ActiveAgent::Delegation::Pricing.register(/\Aclaude-haiku/, input: 1.00, output: 5.00)
+    #
+    # @example Or state rates inline on a single budget
+    #   delegate_to SummarizerAgent, budget: { max_cost: 0.05, rates: { input: 0.15, output: 0.60 } }
+    module Pricing
+      # A registered rate card.
+      Rate = Struct.new(:pattern, :input, :output, keyword_init: true) do
+        # @param model [String]
+        # @return [Boolean]
+        def matches?(model)
+          case pattern
+          when Regexp then pattern.match?(model)
+          else model.to_s.start_with?(pattern.to_s)
+          end
+        end
+      end
+
+      class << self
+        # @return [Array<Rate>] registered rates, most recently registered first
+        def rates
+          @rates ||= []
+        end
+
+        # Registers a rate card.
+        #
+        # String patterns match by prefix (so +"gpt-4o-mini"+ covers
+        # +"gpt-4o-mini-2024-07-18"+); Regexp patterns match as written. Later
+        # registrations win over earlier ones.
+        #
+        # @param pattern [String, Regexp] matched against the model name
+        # @param input [Float] USD per 1M input tokens
+        # @param output [Float] USD per 1M output tokens
+        # @return [Rate]
+        def register(pattern, input:, output:)
+          Rate.new(pattern: pattern, input: input.to_f, output: output.to_f).tap do |rate|
+            rates.unshift(rate)
+          end
+        end
+
+        # Clears the registry. Mostly useful in tests.
+        #
+        # @return [void]
+        def reset!
+          @rates = []
+        end
+
+        # @param model [String, nil]
+        # @return [Hash, nil] +{ input:, output: }+ in USD per 1M tokens
+        def rates_for(model)
+          return nil if model.blank?
+
+          rate = rates.find { |candidate| candidate.matches?(model) }
+          { input: rate.input, output: rate.output } if rate
+        end
+
+        # Computes the dollar cost of a single generation.
+        #
+        # @param usage [ActiveAgent::Providers::Common::Usage, nil]
+        # @param model [String, nil] used to look up registered rates
+        # @param rates [Hash, nil] inline +{ input:, output: }+ overriding the registry
+        # @return [Float, nil] nil when no rates are known for the model
+        def cost_for(usage:, model: nil, rates: nil)
+          return nil if usage.nil?
+
+          resolved = normalize(rates) || rates_for(model)
+          return nil if resolved.nil?
+
+          input  = (usage.input_tokens  || 0) * resolved[:input]
+          output = (usage.output_tokens || 0) * resolved[:output]
+
+          (input + output) / 1_000_000.0
+        end
+
+        private
+
+        # @param rates [Hash, nil]
+        # @return [Hash, nil]
+        def normalize(rates)
+          return nil if rates.blank?
+
+          rates = rates.symbolize_keys
+          return nil unless rates[:input] || rates[:output]
+
+          { input: rates[:input].to_f, output: rates[:output].to_f }
+        end
+      end
+    end
+  end
+end