smith-agents 0.4.5 → 0.6.0

data/lib/smith/workflow/composite/budget_allocator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "dry-initializer"
+
+require_relative "../../budget/decimal_context"
+require_relative "../../budget/ledger"
+require_relative "plan"
+
+module Smith
+  class Workflow
+    module Composite
+      class BudgetAllocator
+        extend Dry::Initializer
+
+        TOKEN_DIMENSIONS = %i[total_tokens token_limit].freeze
+        SUPPORTED_DIMENSIONS = (TOKEN_DIMENSIONS + %i[total_cost]).freeze
+
+        option :ledger
+        option :branch_count
+
+        def initialize(...)
+          super
+          unless ledger.is_a?(Budget::Ledger)
+            raise ArgumentError, "composite budget allocation requires a budget ledger"
+          end
+
+          Plan.validate_branch_count!(branch_count)
+          @remaining = ledger.limits.to_h { |dimension, _| [dimension, ledger.remaining(dimension)] }.freeze
+        end
+
+        def call(ordinal:, caps: {})
+          validate_ordinal!(ordinal)
+
+          @remaining.to_h do |dimension, amount|
+            [dimension, capped_share(dimension, amount, ordinal, caps[dimension])]
+          end.freeze
+        end
+
+        private
+
+        def validate_ordinal!(ordinal)
+          return if ordinal.is_a?(Integer) && ordinal.between?(0, branch_count - 1)
+
+          raise ArgumentError, "composite branch ordinal is outside the allocation"
+        end
+
+        def capped_share(dimension, amount, ordinal, cap)
+          unless cap.nil? || (cap.is_a?(Numeric) && cap.finite? && cap >= 0)
+            raise ArgumentError, "composite branch budget cap must be a finite non-negative number"
+          end
+
+          allocation = share(dimension, amount, ordinal)
+          cap.nil? ? allocation : [allocation, cap].min
+        end
+
+        def share(dimension, amount, ordinal)
+          return 0 unless SUPPORTED_DIMENSIONS.include?(dimension)
+          return integer_share(amount, ordinal) if TOKEN_DIMENSIONS.include?(dimension) && amount.is_a?(Integer)
+
+          decimal_share(amount)
+        end
+
+        def integer_share(amount, ordinal)
+          quotient, remainder = amount.divmod(branch_count)
+          quotient + (ordinal < remainder ? 1 : 0)
+        end
+
+        def decimal_share(amount)
+          exact = Budget::DecimalContext.call { BigDecimal(amount.to_s) / branch_count }
+          candidate = exact.to_f
+          candidate = candidate.prev_float if BigDecimal(candidate.to_s) > exact
+          candidate
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/budget_math.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "dry-initializer"
+
+require_relative "../../budget/decimal_context"
+
+module Smith
+  class Workflow
+    module Composite
+      class BudgetMath
+        extend Dry::Initializer
+
+        HASH_EACH_PAIR = Hash.instance_method(:each_pair)
+        private_constant :HASH_EACH_PAIR
+
+        param :consumptions
+
+        def self.sum(consumptions) = new(consumptions).sum
+
+        def sum
+          Budget::DecimalContext.call do
+            totals = {}
+            integer_dimensions = {}
+            consumptions.each { accumulate!(_1, totals, integer_dimensions) }
+            externalize(totals, integer_dimensions)
+          end
+        end
+
+        private
+
+        def accumulate!(value, totals, integer_dimensions)
+          raise ArgumentError, "composite budget consumption must be a Hash" unless value.is_a?(Hash)
+
+          HASH_EACH_PAIR.bind_call(value) do |dimension, amount|
+            key = dimension.to_s
+            totals[key] = totals.fetch(key, BigDecimal("0")) + BigDecimal(amount.to_s)
+            integer_dimensions[key] = integer_dimensions.fetch(key, true) && amount.is_a?(Integer)
+          end
+        end
+
+        def externalize(totals, integer_dimensions)
+          totals.to_h do |dimension, total|
+            value = integer_dimensions.fetch(dimension) ? total.to_i : total.to_f
+            [dimension, value]
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/contract.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "branch_contract"
+require_relative "branch_execution"
+require_relative "execution_contract"
+require_relative "input"
+require_relative "plan"
+require_relative "../composite_branch_execution_authorization"
+
+module Smith
+  class Workflow
+    module Composite
+      module Contract
+        include BranchContract
+        include ExecutionContract
+
+        private
+
+        def validate_composite_authorization!(authorization)
+          authorization = validate_split_step_execution_authorization!(authorization)
+          @split_step_mutex.synchronize do
+            unless active_split_step_execution_authorization?(authorization)
+              raise WorkflowError, "the prepared-step execution authorization is no longer active"
+            end
+
+            ensure_split_step_definition_current!
+            ensure_prepared_split_step_transition_matches!
+          end
+          validate_composite_transition!(@split_step_transition)
+          unless authorization.dispatch_claim
+            raise WorkflowError, "durable composite execution requires a prepared-step dispatch"
+          end
+
+          authorization
+        end
+
+        def validate_composite_transition!(transition)
+          unless transition&.fanout? || transition&.parallel?
+            raise WorkflowError, "prepared transition is not a supported composite"
+          end
+          raise WorkflowError, "durable composite retries are not supported" if transition.retry_config
+
+          transition
+        end
+
+        def validate_composite_plan!(authorization, plan, input)
+          validate_composite_payload_types!(plan, input)
+          validate_composite_dispatch!(authorization, plan)
+          validate_composite_input!(plan, input)
+          validate_composite_budget_state!(plan)
+          validate_composite_execution_namespace!(plan)
+          transition = @split_step_transition
+          validate_composite_transition_identity!(plan, transition)
+          plan
+        end
+
+        def validate_composite_branch_execution!(authorization, execution, input)
+          validate_composite_branch_payload_types!(execution, input)
+          validate_composite_dispatch_value!(authorization, execution.dispatch)
+          validate_composite_input_digest!(execution.input_digest, input)
+          validate_composite_budget_state_digest!(execution.budget_state_digest)
+          validate_composite_execution_namespace_value!(execution.execution_namespace)
+          validate_composite_transition_values!(execution, @split_step_transition)
+          validate_composite_branch_count!(execution.branch_count)
+          validate_composite_branch_authorization!(authorization, execution, input)
+          validate_composite_selected_branch!(authorization, execution, @split_step_transition)
+          execution
+        end
+
+        def validate_composite_reduction_plan!(authorization, plan, input)
+          validate_composite_plan!(authorization, plan, input)
+          validate_composite_branches!(authorization, plan, @split_step_transition)
+          plan
+        end
+
+        def validate_composite_payload_types!(plan, input)
+          raise ArgumentError, "plan must be a Smith composite plan" unless plan.is_a?(Plan)
+          raise ArgumentError, "input must be a Smith composite input" unless input.is_a?(Input)
+        end
+
+        def validate_composite_branch_payload_types!(execution, input)
+          unless execution.is_a?(BranchExecution)
+            raise ArgumentError, "execution must be a Smith composite branch execution"
+          end
+          raise ArgumentError, "input must be a Smith composite input" unless input.is_a?(Input)
+        end
+
+        def validate_composite_branch_authorization!(authorization, execution, input)
+          unless authorization.instance_of?(CompositeBranchExecutionAuthorization)
+            raise ArgumentError, "authorization must be a Smith composite branch authorization"
+          end
+
+          CompositeBranchExecutionAuthorization
+            .instance_method(:verify_composite_branch!)
+            .bind_call(authorization, execution, input)
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/effects.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../../budget/decimal_context"
+require_relative "../message_value_normalizer"
+require_relative "../prepared_step"
+require_relative "payload"
+
+module Smith
+  class Workflow
+    module Composite
+      class Effects < Payload
+        attr_reader :total_tokens, :total_cost
+
+        USAGE_ATTRIBUTES = %w[
+          usage_id agent_name model input_tokens output_tokens cost attempt_kind recorded_at
+        ].freeze
+        TOOL_ATTRIBUTES = %w[tool captured].freeze
+        private_constant :USAGE_ATTRIBUTES, :TOOL_ATTRIBUTES
+
+        attribute :usage_entries, Types::Array
+        attribute :tool_results, Types::Array
+        attribute :budget_consumed, Types::Hash
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          normalized = MessageValueNormalizer.new(owned, label: "composite effects").call
+          usage_entries = normalized.fetch("usage_entries")
+          tool_results = normalized.fetch("tool_results")
+          budget_consumed = normalized.fetch("budget_consumed")
+          @total_tokens, @total_cost = validate_usage_entries!(usage_entries)
+          validate_tool_results!(tool_results)
+          validate_budget!(budget_consumed)
+          super(
+            usage_entries:,
+            tool_results:,
+            budget_consumed:
+          )
+        end
+
+        private
+
+        def validate_usage_entries!(entries)
+          raise ArgumentError, "composite usage entries must be an Array" unless entries.is_a?(Array)
+
+          entries.each do |entry|
+            validate_exact_keys!(entry, USAGE_ATTRIBUTES, "composite usage entry")
+            validate_usage_identity!(entry)
+            validate_usage_amount!(entry.fetch("input_tokens"), "input_tokens")
+            validate_usage_amount!(entry.fetch("output_tokens"), "output_tokens")
+            validate_cost!(entry.fetch("cost"))
+          end
+          usage_totals(entries)
+        end
+
+        def usage_totals(entries)
+          tokens = entries.sum { _1.fetch("input_tokens") + _1.fetch("output_tokens") }
+          if tokens > PreparedStep::MAX_COUNTER_VALUE
+            raise ArgumentError, "composite usage token total exceeds the signed 64-bit limit"
+          end
+
+          cost = Budget::DecimalContext.call do
+            entries.sum(BigDecimal("0")) { BigDecimal((_1.fetch("cost") || 0).to_s) }
+          end.to_f
+          raise ArgumentError, "composite usage cost total must be finite" unless cost.finite?
+
+          [tokens, cost]
+        end
+
+        def validate_usage_identity!(entry)
+          validate_usage_id!(entry.fetch("usage_id"))
+          validate_agent_name!(entry.fetch("agent_name"))
+          %w[model attempt_kind recorded_at].each do |key|
+            validate_nonempty_string!(entry.fetch(key), "composite usage entry #{key}")
+          end
+        end
+
+        def validate_usage_id!(usage_id)
+          return if usage_id.is_a?(String) && PreparedStep::UUID_PATTERN.match?(usage_id)
+
+          raise ArgumentError, "composite usage entry usage_id must be a UUID"
+        end
+
+        def validate_agent_name!(agent_name)
+          return if agent_name.nil?
+
+          validate_nonempty_string!(agent_name, "composite usage entry agent_name")
+        end
+
+        def validate_nonempty_string!(value, label)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, "#{label} must be a non-empty String"
+        end
+
+        def validate_usage_amount!(amount, name)
+          return if amount.is_a?(Integer) && amount >= 0
+
+          raise ArgumentError, "composite usage entry #{name} must be a non-negative Integer"
+        end
+
+        def validate_cost!(cost)
+          return if cost.nil?
+          return if cost.is_a?(Numeric) && cost.finite? && cost >= 0
+
+          raise ArgumentError, "composite usage entry cost must be a finite non-negative number or nil"
+        end
+
+        def validate_tool_results!(entries)
+          raise ArgumentError, "composite tool results must be an Array" unless entries.is_a?(Array)
+
+          entries.each do |entry|
+            validate_exact_keys!(entry, TOOL_ATTRIBUTES, "composite tool result")
+            tool = entry.fetch("tool")
+            unless tool.is_a?(String) && tool.length.between?(1, 256)
+              raise ArgumentError, "composite tool result tool must be a bounded non-empty String"
+            end
+          end
+        end
+
+        def validate_budget!(budget)
+          raise ArgumentError, "composite budget consumption must be a Hash" unless budget.is_a?(Hash)
+
+          budget.each do |dimension, amount|
+            unless !dimension.empty? && amount.is_a?(Numeric) && amount.finite? && amount >= 0
+              raise ArgumentError, "composite budget consumption is invalid"
+            end
+          end
+        end
+
+        def validate_exact_keys!(value, expected, label)
+          raise ArgumentError, "#{label} must be a Hash" unless value.is_a?(Hash)
+          return if value.keys.sort == expected.sort
+
+          raise ArgumentError, "#{label} attributes are invalid"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/effects_application.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../../budget/ledger"
+require_relative "../usage_entry"
+require_relative "effects_baseline"
+
+module Smith
+  class Workflow
+    module Composite
+      class EffectsApplication < Dry::Struct
+        NumericType = Types::Integer | Types::Float
+        private_constant :NumericType
+
+        attribute :usage_entries, Types::Array.of(Types.Instance(UsageEntry))
+        attribute :tool_results, Types::Array.of(Types::Hash)
+        attribute :total_tokens, Types::Integer
+        attribute :total_cost, NumericType
+        attribute :ledger, Types.Instance(Budget::Ledger).optional
+        attribute :baseline, Types.Instance(EffectsBaseline)
+
+        def initialize(attributes)
+          super
+          unless total_tokens >= 0 && total_cost.finite? && total_cost >= 0
+            raise ArgumentError, "composite effects application totals are invalid"
+          end
+
+          usage_entries.freeze
+          tool_results.freeze
+          self.attributes.freeze
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/effects_baseline.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../../budget/ledger"
+require_relative "../usage_entry"
+
+module Smith
+  class Workflow
+    module Composite
+      class EffectsBaseline < Dry::Struct
+        NumericType = Types::Integer | Types::Float
+        private_constant :NumericType
+
+        attribute :usage_entries, Types::Array.of(Types.Instance(UsageEntry))
+        attribute :tool_results, Types::Array.of(Types::Hash)
+        attribute :total_tokens, Types::Integer
+        attribute :total_cost, NumericType
+        attribute :ledger, Types.Instance(Budget::Ledger).optional
+        attribute :budget_consumed, Types::Hash
+
+        def initialize(attributes)
+          super
+          unless total_tokens >= 0 && total_cost.finite? && total_cost >= 0
+            raise ArgumentError, "composite effects baseline totals are invalid"
+          end
+
+          usage_entries.freeze
+          tool_results.freeze
+          budget_consumed.freeze
+          self.attributes.freeze
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/effects_preflight.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "dry-initializer"
+
+require_relative "../../budget/decimal_context"
+require_relative "../../budget/ledger"
+require_relative "../prepared_step"
+require_relative "../usage_entry"
+require_relative "budget_math"
+require_relative "effects_application"
+
+module Smith
+  class Workflow
+    module Composite
+      class EffectsPreflight
+        extend Dry::Initializer
+
+        option :effects
+        option :baseline
+        option :snapshotter
+
+        def call
+          next_total_tokens = total_tokens
+          next_total_cost = total_cost
+          next_usage = incoming_usage
+          next_ledger = ledger
+          next_tools = incoming_tools
+          tool_results = baseline.tool_results + next_tools
+          EffectsApplication.new(
+            usage_entries: baseline.usage_entries + next_usage,
+            tool_results:,
+            total_tokens: next_total_tokens,
+            total_cost: next_total_cost,
+            ledger: next_ledger,
+            baseline:
+          )
+        end
+
+        private
+
+        def incoming_usage
+          @incoming_usage ||= effects.usage_entries.map { UsageEntry.from_h(_1) }.tap do |entries|
+            known = baseline.usage_entries.to_h { [_1.usage_id, true] }
+            raise WorkflowError, "composite usage entry was already applied" if
+              entries.any? { known.key?(_1.usage_id) }
+          end
+        end
+
+        def incoming_tools
+          @incoming_tools ||= effects.tool_results.map do |entry|
+            snapshotter.call(entry).transform_keys { _1.respond_to?(:to_sym) ? _1.to_sym : _1 }
+          end
+        end
+
+        def total_tokens
+          current = baseline.total_tokens
+          raise WorkflowError, "workflow token total is invalid" unless current.is_a?(Integer) && current >= 0
+
+          total = current + effects.total_tokens
+          return total if total <= PreparedStep::MAX_COUNTER_VALUE
+
+          raise WorkflowError, "workflow token total exceeds the signed 64-bit limit"
+        end
+
+        def total_cost
+          current = baseline.total_cost
+          unless current.is_a?(Numeric) && current.finite? && current >= 0
+            raise WorkflowError, "workflow cost total is invalid"
+          end
+
+          total = Budget::DecimalContext.call do
+            BigDecimal(current.to_s) + BigDecimal(effects.total_cost.to_s)
+          end.to_f
+          return total if total.finite?
+
+          raise WorkflowError, "workflow cost total must be finite"
+        end
+
+        def ledger
+          return baseline.ledger if effects.budget_consumed.empty?
+          raise WorkflowError, "composite budget effects require a workflow ledger" unless baseline.ledger
+
+          Budget::Ledger.new(
+            limits: baseline.ledger.limits,
+            consumed: combined_budget_consumed
+          )
+        end
+
+        def combined_budget_consumed
+          combined = BudgetMath
+                     .sum([baseline.budget_consumed, effects.budget_consumed])
+                     .transform_keys(&:to_sym)
+          combined.each do |dimension, amount|
+            raise BudgetExceeded if amount > baseline.ledger.limits.fetch(dimension)
+          end
+          combined
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/encoded_value_budget.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+require "json"
+
+require_relative "../../errors"
+
+module Smith
+  class Workflow
+    module Composite
+      class EncodedValueBudget
+        extend Dry::Initializer
+
+        option :max_bytes
+        option :label
+
+        def initialize(...)
+          super
+          @bytes = 2
+          @entries = 0
+        end
+
+        def add(value)
+          @bytes += JSON.generate(value, max_nesting: false).bytesize
+          @bytes += 1 if @entries.positive?
+          @entries += 1
+          raise WorkflowError, "#{label} exceeds maximum bytes #{max_bytes}" if @bytes > max_bytes
+
+          self
+        rescue JSON::GeneratorError => e
+          raise WorkflowError, "#{label} cannot be encoded: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/enums.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module Composite
+      module Enums
+        VALUES = {
+          kind: { "parallel" => :parallel, "fanout" => :fanout }.freeze,
+          status: { "succeeded" => :succeeded, "failed" => :failed }.freeze,
+          resume_policy: { "incomplete_only" => :incomplete_only }.freeze,
+          failure_policy: { "host_committed_primary" => :host_committed_primary }.freeze,
+          reduction_policy: { "ordered_all_success" => :ordered_all_success }.freeze,
+          retry_policy: { "none" => :none }.freeze
+        }.freeze
+        private_constant :VALUES
+
+        def self.normalize(name, value)
+          return value unless value.is_a?(String)
+
+          VALUES.fetch(name).fetch(value, value)
+        end
+      end
+
+      private_constant :Enums
+    end
+  end
+end

data/lib/smith/workflow/composite/error.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "payload"
+
+module Smith
+  class Workflow
+    module Composite
+      class Error < Payload
+        FAMILIES = %w[
+          tool_guardrail_failed deterministic_step_failure deadline_exceeded
+          agent_error workflow_error other
+        ].freeze
+        ALWAYS_RETRYABLE_FAMILIES = %w[deadline_exceeded agent_error].freeze
+        CONDITIONALLY_RETRYABLE_FAMILIES = %w[tool_guardrail_failed deterministic_step_failure].freeze
+        private_constant :ALWAYS_RETRYABLE_FAMILIES, :CONDITIONALLY_RETRYABLE_FAMILIES
+        OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
+        private_constant :OwnedString
+
+        attribute :class_name, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :family, OwnedString.enum(*FAMILIES)
+        attribute :retryable, Types::Bool
+        attribute? :kind, OwnedString.constrained(min_size: 1, max_size: 128).optional
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          owned[:kind] = owned[:kind].to_s if owned[:kind]
+          super(owned)
+          validate_retryability!
+          validate_kind!
+        end
+
+        private
+
+        def validate_retryability!
+          valid = if ALWAYS_RETRYABLE_FAMILIES.include?(family)
+                    retryable
+                  elsif CONDITIONALLY_RETRYABLE_FAMILIES.include?(family)
+                    [true, false].include?(retryable)
+                  else
+                    !retryable
+                  end
+          raise ArgumentError, "composite error retryability does not match its family" unless valid
+        end
+
+        def validate_kind!
+          return if kind.nil? || family == "deterministic_step_failure"
+
+          raise ArgumentError, "composite error kind is not valid for its family"
+        end
+      end
+    end
+  end
+end