activeagent 1.1.0 → 1.3.0

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

data/lib/active_agent/delegation/runner.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module ActiveAgent
+  module Delegation
+    # Executes one delegated call: budget check, sub-agent generation, result
+    # validation, accounting.
+    #
+    # The runner is what makes a sub-agent a *tool* rather than a method call.
+    # It answers to the calling model in the model's own terms — a refused call
+    # comes back as a structured result the model can reason about, not as an
+    # exception that ends the conversation.
+    #
+    # @api private
+    class Runner
+      # @return [Definition]
+      attr_reader :definition
+      # @return [ActiveAgent::Base] the delegating agent instance
+      attr_reader :owner
+
+      # @param definition [Definition]
+      # @param owner [ActiveAgent::Base]
+      def initialize(definition, owner:)
+        @definition = definition
+        @owner      = owner
+      end
+
+      # Runs the delegated call.
+      #
+      # @param arguments [Hash] arguments supplied by the calling model
+      # @return [Object] the sub-agent's result, or a structured error the
+      #   calling model can act on
+      # @raise [BudgetExceededError] when the budget policy is +:raise+
+      # @raise [InvalidResultError] when the returns policy is +:raise+
+      def call(**arguments)
+        if (violation = budget_violation)
+          return refuse(violation)
+        end
+
+        arguments = coerce_arguments(arguments)
+
+        instrument(arguments) do |payload|
+          started  = clock
+          response = nil
+
+          begin
+            response = with_timeout { generate(arguments) }
+          rescue Timeout::Error
+            duration = clock - started
+            record(duration: duration)
+            payload[:status]      = :timed_out
+            payload[:duration_ms] = (duration * 1_000).round
+
+            next timed_out(duration)
+          end
+
+          duration = clock - started
+          usage    = response.usage
+          model    = response.model.presence || generation_model(response)
+          cost     = Pricing.cost_for(usage: usage, model: model, rates: budget.rates)
+
+          record(tokens: usage&.total_tokens, cost: cost, duration: duration)
+
+          payload[:status]      = :ok
+          payload[:model]       = model
+          payload[:duration_ms] = (duration * 1_000).round
+          payload[:usage]       = usage
+          payload[:cost]        = cost
+          payload[:ledger]      = ledgers.last.to_h
+
+          result(response, payload)
+        end
+      end
+
+      private
+
+      # @return [Budget]
+      def budget = definition.budget
+
+      # Agent-wide ledger first, then this delegation's own — a call has to
+      # clear both.
+      #
+      # @return [Array<Ledger>]
+      def ledgers
+        @ledgers ||= [ owner.delegation_ledger, owner.delegation_ledger_for(definition.tool_name) ]
+      end
+
+      # @return [Budget::Violation, nil]
+      def budget_violation
+        owner.class.delegation_budget.violation_for(ledgers.first) || budget.violation_for(ledgers.last)
+      end
+
+      # @param tokens [Integer, nil]
+      # @param cost [Float, nil]
+      # @param duration [Float]
+      # @return [void]
+      def record(tokens: 0, cost: nil, duration: 0.0)
+        ledgers.each { |ledger| ledger.record(tokens: tokens, cost: cost, duration: duration) }
+      end
+
+      # Drops arguments the contract never declared, so a model that
+      # hallucinates an extra key gets a working call instead of an
+      # +ArgumentError+ from the sub-agent's method signature.
+      #
+      # @param arguments [Hash]
+      # @return [Hash]
+      def coerce_arguments(arguments)
+        arguments = arguments.symbolize_keys
+        return arguments if definition.schema.empty?
+
+        arguments.slice(*definition.schema.keys)
+      end
+
+      # @param arguments [Hash]
+      # @return [ActiveAgent::Providers::Common::PromptResponse]
+      def generate(arguments)
+        agent = definition.resolved_agent_class.new
+        agent.params = resolved_params(arguments)
+        agent.process(definition.action, **arguments)
+
+        definition.backend.apply(agent)
+        apply_returns_format(agent)
+        inherit_trace_id(agent)
+
+        agent.process_prompt
+      end
+
+      # A delegated generation is part of its parent's work, so it carries the
+      # parent's trace id — otherwise the sub-agent's tokens and latency land
+      # in a separate trace and the budget you set has nothing to show for it.
+      #
+      # @param agent [ActiveAgent::Base]
+      # @return [void]
+      def inherit_trace_id(agent)
+        trace_id = owner.prompt_options[:trace_id]
+        agent.prompt_options[:trace_id] ||= trace_id if trace_id
+      end
+
+      # A declared +returns+ schema *is* the response format for the delegated
+      # call; the sub-agent does not have to restate it.
+      #
+      # @param agent [ActiveAgent::Base]
+      # @return [void]
+      def apply_returns_format(agent)
+        return unless definition.structured?
+
+        agent.prompt_options[:response_format] = {
+          type: :json_schema,
+          json_schema: definition.returns.to_response_format(name: "#{definition.tool_name}_result")
+        }
+      end
+
+      # @param arguments [Hash]
+      # @return [Hash]
+      def resolved_params(arguments)
+        case (params = definition.params)
+        when nil    then {}
+        when Hash   then params
+        when Symbol then owner.send(params)
+        when Proc   then params.arity == 1 ? owner.instance_exec(arguments, &params) : owner.instance_exec(&params)
+        else
+          raise ArgumentError, "Delegation params must be a Hash, Symbol or Proc, got #{params.inspect}"
+        end.to_h.symbolize_keys
+      end
+
+      # @yield the delegated generation
+      # @return [Object]
+      def with_timeout
+        return yield unless budget.timeout
+
+        Timeout.timeout(budget.timeout) { yield }
+      end
+
+      # @param response [ActiveAgent::Providers::Common::PromptResponse]
+      # @param payload [Hash] instrumentation payload
+      # @return [Object]
+      def result(response, payload)
+        message = response.message
+        return nil if message.nil?
+
+        return text_of(message) unless definition.structured?
+
+        parsed  = message.respond_to?(:parsed_json) ? message.parsed_json : nil
+        missing = definition.returns.missing_keys(parsed)
+        return parsed if missing.empty?
+
+        payload[:status]  = :invalid_result
+        payload[:missing] = missing
+
+        invalid(missing, text_of(message))
+      end
+
+      # @param message [Object]
+      # @return [String]
+      def text_of(message)
+        message.respond_to?(:text) ? message.text : message.content.to_s
+      end
+
+      # @param response [ActiveAgent::Providers::Common::PromptResponse]
+      # @return [String, nil]
+      def generation_model(response)
+        response.context.is_a?(Hash) ? response.context[:model] : nil
+      end
+
+      # @param violation [Budget::Violation]
+      # @return [Hash]
+      def refuse(violation)
+        ActiveSupport::Notifications.instrument("delegation_refused.active_agent", instrument_payload.merge(
+          status: :budget_exceeded, limit: violation.limit, allowed: violation.allowed, used: violation.used
+        ))
+
+        if budget.policy == :raise
+          raise BudgetExceededError.new(violation, definition: definition)
+        end
+
+        { error: "budget_exceeded", limit: violation.limit.to_s, allowed: violation.allowed, used: violation.used, message: violation.message }
+      end
+
+      # @param duration [Float]
+      # @return [Hash]
+      def timed_out(duration)
+        if budget.policy == :raise
+          raise TimeoutError, "#{definition.agent_class}##{definition.action} exceeded its #{budget.timeout}s delegation timeout"
+        end
+
+        {
+          error: "timeout",
+          limit: "timeout",
+          allowed: budget.timeout,
+          used: duration.round(3),
+          message: "The #{definition.tool_name} delegation timed out after #{budget.timeout}s. " \
+                   "Answer with the information you already have, or call it with a smaller request."
+        }
+      end
+
+      # @param missing [Array<Symbol>]
+      # @param content [String]
+      # @return [Hash]
+      def invalid(missing, content)
+        if definition.on_invalid == :raise
+          raise InvalidResultError, "#{definition.agent_class}##{definition.action} returned a result missing " \
+            "required #{"key".pluralize(missing.size)}: #{missing.join(", ")}"
+        end
+
+        {
+          error: "invalid_result",
+          missing: missing.map(&:to_s),
+          message: "The #{definition.tool_name} delegation returned a result missing required " \
+                   "#{"key".pluralize(missing.size)}: #{missing.join(", ")}.",
+          content: content
+        }
+      end
+
+      # @param arguments [Hash]
+      # @yield [Hash] instrumentation payload
+      def instrument(arguments, &block)
+        ActiveSupport::Notifications.instrument(
+          "delegate.active_agent", instrument_payload.merge(arguments: arguments), &block
+        )
+      end
+
+      # @return [Hash]
+      def instrument_payload
+        {
+          agent: owner.class.name,
+          delegate: definition.agent_class.name,
+          action: definition.action,
+          tool: definition.tool_name.to_s,
+          provider: definition.backend.provider,
+          budget: budget.to_h.except(:rates)
+        }.compact
+      end
+
+      # Monotonic so a clock adjustment mid-generation can't corrupt a latency budget.
+      #
+      # @return [Float]
+      def clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end