smith-agents 0.5.0 → 0.6.1

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+require_relative "error"
+
+module Smith
+  class Workflow
+    module Composite
+      class BranchFailure < WorkflowError
+        DETAIL_KEYS = {
+          "branch_key" => :branch_key,
+          "error_class" => :error_class,
+          "error_family" => :error_family,
+          "retryable" => :retryable,
+          "kind" => :kind
+        }.freeze
+        DETAIL_NAMES = DETAIL_KEYS.values.freeze
+        private_constant :DETAIL_KEYS, :DETAIL_NAMES
+
+        attr_reader :branch_key, :error_class, :error_family, :retryable, :kind, :details
+
+        def self.from_details(details)
+          values = normalize_details(details)
+          error = Error.new(
+            class_name: values.fetch(:error_class),
+            family: values.fetch(:error_family),
+            retryable: values.fetch(:retryable),
+            kind: values.fetch(:kind)
+          )
+          new(branch_key: values.fetch(:branch_key), error:)
+        end
+
+        def self.normalize_details(details)
+          raise ArgumentError, "composite branch failure details must be a Hash" unless details.is_a?(Hash)
+
+          normalized = {}
+          Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+            name = normalize_detail_key(key)
+            if normalized.key?(name)
+              raise ArgumentError, "composite branch failure details contain a duplicate attribute"
+            end
+
+            normalized[name] = value
+          end
+          missing = DETAIL_NAMES - normalized.keys
+          raise ArgumentError, "composite branch failure details are missing required attributes" if missing.any?
+
+          normalized
+        end
+
+        def self.normalize_detail_key(key)
+          name = key.is_a?(Symbol) ? key : DETAIL_KEYS.fetch(key, key)
+          return name if DETAIL_NAMES.include?(name)
+
+          raise ArgumentError, "composite branch failure details contain an unknown attribute"
+        end
+        private_class_method :normalize_details
+        private_class_method :normalize_detail_key
+
+        def initialize(branch_key:, error:)
+          validate_arguments!(branch_key, error)
+          @branch_key = branch_key.dup.freeze
+          @error_class = error.class_name.dup.freeze
+          @error_family = error.family.dup.freeze
+          @retryable = error.retryable
+          @kind = error.kind&.dup&.freeze
+          @details = failure_details
+          super("composite branch #{branch_key.inspect} failed")
+        end
+
+        private
+
+        def validate_arguments!(branch_key, error)
+          valid_key = branch_key.is_a?(String) && branch_key.length.between?(1, 256)
+          raise ArgumentError, "composite branch failure key must be a bounded non-empty String" unless valid_key
+          raise ArgumentError, "composite branch failure requires typed error evidence" unless error.is_a?(Error)
+        end
+
+        def failure_details
+          {
+            branch_key: @branch_key,
+            error_class: @error_class,
+            error_family: @error_family,
+            retryable: @retryable,
+            kind: @kind
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../message_value_normalizer"
+require_relative "../prepared_step"
+require_relative "effects"
+require_relative "enums"
+require_relative "error"
+require_relative "payload"
+require_relative "payload_digest"
+
+module Smith
+  class Workflow
+    module Composite
+      class BranchOutcome < Payload
+        OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
+        private_constant :OwnedString
+
+        attribute :plan_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :branch_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :ordinal, Types::Integer.constrained(gteq: 0, lteq: PreparedStep::MAX_COUNTER_VALUE)
+        attribute :branch_key, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :agent, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :status, Types::Symbol.enum(:succeeded, :failed)
+        attribute? :output, Types::Any.optional
+        attribute? :error, Types.Instance(Error).optional
+        attribute :effects, Types.Instance(Effects)
+        attribute :digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+        class << self
+          def succeeded(plan_digest:, branch:, output:, effects:)
+            build(plan_digest:, branch:, effects:, status: :succeeded, output:, error: nil)
+          end
+
+          def failed(plan_digest:, branch:, error:, effects:)
+            build(plan_digest:, branch:, effects:, status: :failed, output: nil, error:)
+          end
+
+          def normalize_attributes(attributes)
+            normalized = super
+            normalize_status!(normalized)
+            normalize_error!(normalized)
+            normalize_effects!(normalized)
+            normalized
+          end
+
+          private
+
+          def build(plan_digest:, branch:, effects:, **result)
+            values = {
+              plan_digest:,
+              branch_digest: branch.digest,
+              ordinal: branch.ordinal,
+              branch_key: branch.key,
+              agent: branch.agent,
+              status: result.fetch(:status),
+              output: normalize_output(result.fetch(:output)),
+              error: result.fetch(:error),
+              effects:
+            }
+            new(values.merge(digest: PayloadDigest.call(serializable(values))))
+          end
+
+          def normalize_status!(attributes)
+            attributes[:status] = Enums.normalize(:status, attributes[:status])
+          end
+
+          def normalize_error!(attributes)
+            error = attributes[:error]
+            attributes[:error] = Error.deserialize(error) if error && !error.is_a?(Error)
+          end
+
+          def normalize_effects!(attributes)
+            effects = attributes[:effects]
+            attributes[:effects] = Effects.deserialize(effects) unless effects.is_a?(Effects)
+          end
+
+          def normalize_output(value)
+            MessageValueNormalizer.new(value, label: "composite branch output").call
+          end
+
+          def serializable(values)
+            values.merge(error: values[:error]&.to_h, effects: values.fetch(:effects).to_h)
+          end
+        end
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          owned[:output] = self.class.send(:normalize_output, owned[:output])
+          super(owned)
+          validate_shape!
+          expected = PayloadDigest.call(self.class.send(:serializable, to_h.except(:digest)))
+          raise ArgumentError, "composite branch outcome digest does not match" unless digest == expected
+        end
+
+        def succeeded? = status == :succeeded
+        def failed? = status == :failed
+
+        private
+
+        def validate_shape!
+          valid = succeeded? ? error.nil? : error && output.nil?
+          raise ArgumentError, "composite branch outcome fields do not match status" unless valid
+        end
+      end
+    end
+  end
+end

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