smith-agents 0.5.0 → 0.6.1

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

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../../errors"
+require_relative "error"
+
+module Smith
+  class Workflow
+    module Composite
+      class ErrorEvidence
+        extend Dry::Initializer
+
+        param :error
+
+        def self.call(error) = new(error).call
+
+        def call
+          Error.new(
+            class_name: error_class_name,
+            family: error_family,
+            retryable: retryable_error?,
+            kind: error_kind
+          )
+        end
+
+        private
+
+        def error_class_name
+          value = error.class.name.to_s
+          value.empty? || value.length > 256 ? "StandardError" : value
+        end
+
+        def retryable_error?
+          Errors.retryable?(error)
+        end
+
+        def error_kind
+          return unless error.is_a?(DeterministicStepFailure)
+
+          value = error.kind
+          string = value.to_s if value
+          string if string&.length&.between?(1, 128)
+        rescue StandardError
+          nil
+        end
+
+        def error_family
+          case error
+          when ToolGuardrailFailed then "tool_guardrail_failed"
+          when DeterministicStepFailure then "deterministic_step_failure"
+          when DeadlineExceeded then "deadline_exceeded"
+          when AgentError then "agent_error"
+          when WorkflowError then "workflow_error"
+          else "other"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "payload_digest"
+
+module Smith
+  class Workflow
+    module Composite
+      module ExecutionContract
+        private
+
+        def validate_composite_dispatch!(authorization, plan)
+          validate_composite_dispatch_value!(authorization, plan.dispatch)
+        end
+
+        def validate_composite_dispatch_value!(authorization, dispatch)
+          return if dispatch.to_h == authorization.dispatch_claim.to_h
+
+          raise WorkflowError, "composite plan does not belong to the prepared dispatch"
+        end
+
+        def validate_composite_input!(plan, input)
+          validate_composite_input_digest!(plan.input_digest, input)
+        end
+
+        def validate_composite_input_digest!(expected_digest, input)
+          return if input.digest == expected_digest
+
+          raise WorkflowError, "composite input does not match plan"
+        end
+
+        def validate_composite_budget_state!(plan)
+          validate_composite_budget_state_digest!(plan.budget_state_digest)
+        end
+
+        def validate_composite_budget_state_digest!(expected_digest)
+          return if expected_digest == composite_budget_state_digest
+
+          raise WorkflowError, "composite plan budget state has changed"
+        end
+
+        def validate_composite_execution_namespace!(plan)
+          validate_composite_execution_namespace_value!(plan.execution_namespace)
+        end
+
+        def validate_composite_execution_namespace_value!(expected_namespace)
+          return if @execution_namespace.nil? || @execution_namespace == expected_namespace
+
+          raise WorkflowError, "composite plan execution namespace has changed"
+        end
+
+        def validate_composite_transition_identity!(plan, transition)
+          validate_composite_transition_values!(plan, transition)
+        end
+
+        def validate_composite_transition_values!(contract, transition)
+          expected = [transition.name.to_s, transition.from.to_s, composite_kind(transition)]
+          return if expected == [contract.transition, contract.from, contract.kind]
+
+          raise WorkflowError, "composite plan does not match the prepared transition"
+        end
+
+        def composite_kind(transition)
+          transition.parallel? ? :parallel : :fanout
+        end
+
+        def composite_budget_state_digest
+          state = @ledger ? { limits: @ledger.limits, consumed: @ledger.consumed } : { limits: {}, consumed: {} }
+          PayloadDigest.call(state)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module Composite
+      module FanoutBranchContract
+        private
+
+        def fanout_branch_specs(authorization, transition)
+          branches = transition.fanout_config.fetch(:branches)
+          count = branches.length
+          Parallel.validate_branch_count!(count)
+          validate_composite_branch_count!(count)
+          allocator = composite_budget_allocator(count)
+          branches.map.with_index do |(key, agent), ordinal|
+            agent_class = captured_agent(authorization, transition, agent, :fanout_agent)
+            fanout_branch_spec(key, agent, agent_class, allocator, ordinal)
+          end.freeze
+        end
+
+        def fanout_branch_spec(key, agent, agent_class, allocator, ordinal)
+          {
+            key: key.to_s,
+            agent: agent.to_s,
+            binding_identity: composite_binding_identity!(agent_class, agent),
+            budget: composite_branch_budget(allocator, ordinal, agent_class&.budget)
+          }.freeze
+        end
+
+        def selected_fanout_branch_spec(authorization, execution, transition)
+          branches = transition.fanout_config.fetch(:branches)
+          Parallel.validate_branch_count!(branches.length)
+          validate_selected_fanout_count!(branches, execution)
+
+          agent = Transition
+                  .instance_method(:fetch_fanout_agent!)
+                  .bind_call(transition, execution.branch.key)
+          agent_class = captured_agent(authorization, transition, agent, :fanout_agent)
+          selected_fanout_spec(execution, agent, agent_class)
+        end
+
+        def validate_selected_fanout_count!(branches, execution)
+          return if branches.length == execution.branch_count
+
+          raise WorkflowError, "composite branch count does not match the prepared transition"
+        end
+
+        def selected_fanout_spec(execution, agent, agent_class)
+          branch = execution.branch
+          fanout_branch_spec(
+            branch.key,
+            agent,
+            agent_class,
+            composite_budget_allocator(execution.branch_count),
+            branch.ordinal
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../message_value_normalizer"
+require_relative "../prepared_step"
+require_relative "payload"
+require_relative "payload_digest"
+
+module Smith
+  class Workflow
+    module Composite
+      class Input < Payload
+        OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
+        private_constant :OwnedString
+
+        attribute :agent_messages, Types::Any
+        attribute :session_messages, Types::Array
+        attribute :digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+        def self.build(agent_messages:, session_messages:)
+          values = normalized_values(agent_messages:, session_messages:)
+          new(values.merge(digest: PayloadDigest.call(values)))
+        end
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          values = self.class.send(
+            :normalized_values,
+            agent_messages: owned[:agent_messages],
+            session_messages: owned[:session_messages]
+          )
+          super(values.merge(digest: owned[:digest]))
+          raise ArgumentError, "composite input digest does not match" unless digest == PayloadDigest.call(values)
+        end
+
+        class << self
+          private
+
+          def normalized_values(agent_messages:, session_messages:)
+            {
+              agent_messages: normalize(agent_messages),
+              session_messages: normalize(session_messages)
+            }.freeze
+          end
+
+          def normalize(value)
+            MessageValueNormalizer.new(value, label: "composite input").call
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../execution_result_snapshot"
+require_relative "../message_value_normalizer"
+require_relative "encoded_value_budget"
+require_relative "outcome_set"
+require_relative "value_budget"
+
+module Smith
+  class Workflow
+    module Composite
+      class OutcomeAccumulator
+        extend Dry::Initializer
+
+        ARRAY_EACH = Array.instance_method(:each)
+        private_constant :ARRAY_EACH
+
+        option :plan
+        option :outcomes
+
+        def call
+          validate_array_count!
+          initialize_accumulators
+          each_outcome { insert!(_1) }
+          complete_outcome_set
+        end
+
+        private
+
+        def initialize_accumulators
+          @seen = 0
+          @ordered = Array.new(plan.branches.length)
+          @output = Array.new(plan.branches.length)
+          @effects_budget = value_budget(MessageValueNormalizer::MAX_BYTES, "composite aggregate effects")
+          @encoded_effects_budget = EncodedValueBudget.new(
+            max_bytes: MessageValueNormalizer::MAX_BYTES,
+            label: "composite aggregate effects"
+          )
+          @output_budget = value_budget(ExecutionResultSnapshot::MAX_BYTES, "composite aggregate output")
+          @encoded_output_budget = EncodedValueBudget.new(
+            max_bytes: ExecutionResultSnapshot::MAX_BYTES,
+            label: "composite aggregate output"
+          )
+          @output_budget.add(nil)
+        end
+
+        def complete_outcome_set
+          raise ArgumentError, "composite outcomes are incomplete" unless @seen == plan.branches.length
+
+          OutcomeSet.new(ordered: @ordered.freeze, output: @output.freeze)
+        end
+
+        def validate_array_count!
+          return unless outcomes.is_a?(Array)
+          return if Array.instance_method(:length).bind_call(outcomes) == plan.branches.length
+
+          raise ArgumentError, "composite outcome count does not match plan"
+        end
+
+        def each_outcome(&)
+          if outcomes.is_a?(Array)
+            ARRAY_EACH.bind_call(outcomes, &)
+          elsif outcomes.is_a?(Enumerator)
+            outcomes.each(&)
+          else
+            raise ArgumentError, "composite outcomes must be an Array or Enumerator"
+          end
+        end
+
+        def insert!(outcome)
+          raise ArgumentError, "composite outcome count does not match plan" if @seen >= plan.branches.length
+
+          branch = outcome_branch(outcome)
+          validate_identity!(outcome, branch)
+          raise ArgumentError, "composite outcome ordinal is duplicated" if @ordered[outcome.ordinal]
+
+          output = output_entry(outcome, branch)
+          add_to_budgets(outcome, output)
+          store(outcome, output)
+        end
+
+        def outcome_branch(outcome)
+          raise ArgumentError, "composite outcome must be typed" unless outcome.is_a?(BranchOutcome)
+
+          plan.branches.fetch(outcome.ordinal) do
+            raise ArgumentError, "composite outcome ordinal is invalid"
+          end
+        end
+
+        def add_to_budgets(outcome, output)
+          effects = outcome.effects.to_h
+          @effects_budget.add(effects)
+          @encoded_effects_budget.add(effects)
+          @output_budget.add(output, depth: 1)
+          @encoded_output_budget.add(output)
+        end
+
+        def store(outcome, output)
+          @ordered[outcome.ordinal] = outcome
+          @output[outcome.ordinal] = output
+          @seen += 1
+        end
+
+        def validate_identity!(outcome, branch)
+          valid = outcome.plan_digest == plan.plan_digest &&
+                  outcome.branch_digest == branch.digest &&
+                  outcome.branch_key == branch.key &&
+                  outcome.agent == branch.agent
+          raise ArgumentError, "composite outcome does not match its branch" unless valid
+        end
+
+        def output_entry(outcome, branch)
+          branch_key = plan.kind == :parallel ? branch.ordinal : branch.key
+          { "branch" => branch_key, "agent" => branch.agent, "output" => outcome.output }.freeze
+        end
+
+        def value_budget(max_bytes, label)
+          result_budget = label == "composite aggregate output"
+          ValueBudget.new(
+            max_bytes:,
+            max_nodes: result_budget ? ExecutionResultSnapshot::MAX_NODES : MessageValueNormalizer::MAX_NODES,
+            max_depth: result_budget ? ExecutionResultSnapshot::MAX_DEPTH : MessageValueNormalizer::MAX_DEPTH,
+            label:
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "branch_outcome"
+
+module Smith
+  class Workflow
+    module Composite
+      class OutcomeSet < Dry::Struct
+        attribute :ordered, Types::Array.of(Types.Instance(BranchOutcome))
+        attribute :output, Types::Array.of(Types::Hash)
+
+        def initialize(attributes)
+          super
+          ordered.freeze
+          output.freeze
+          self.attributes.freeze
+          freeze
+        end
+      end
+    end
+  end
+end