smith-agents 0.5.0 → 0.6.0

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

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "json"
+
+require_relative "../message_value_normalizer"
+
+module Smith
+  class Workflow
+    module Composite
+      class Payload < Dry::Struct
+        MAX_SERIALIZED_BYTES = MessageValueNormalizer::MAX_BYTES
+        HASH_EACH_PAIR = Hash.instance_method(:each_pair)
+        private_constant :HASH_EACH_PAIR
+
+        class << self
+          def deserialize(value)
+            attributes = parse_attributes(value)
+            preflight_attributes!(attributes)
+            bounded = MessageValueNormalizer.new(attributes, label: payload_name).call
+            new(normalize_attributes(bounded))
+          rescue JSON::ParserError, TypeError => e
+            raise ArgumentError, "#{payload_name} is invalid: #{e.message}"
+          end
+
+          def normalize_attributes(attributes)
+            raise ArgumentError, "#{payload_name} must contain an object" unless attributes.is_a?(Hash)
+
+            result = normalize_attribute_keys(attributes)
+            validate_known_attributes!(result)
+            result
+          end
+
+          def payload_name
+            name.split("::").last.gsub(/([a-z])([A-Z])/, '\\1-\\2').downcase
+          end
+
+          def preflight_attributes!(attributes) = attributes
+
+          private
+
+          def normalize_attribute_keys(attributes)
+            result = {}
+            HASH_EACH_PAIR.bind_call(attributes) do |key, value|
+              normalized_key = normalize_attribute_key(key)
+              raise ArgumentError, "#{payload_name} contains duplicate attributes" if result.key?(normalized_key)
+
+              result[normalized_key] = value
+            end
+            result
+          end
+
+          def normalize_attribute_key(key)
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise ArgumentError, "#{payload_name} attribute names must be strings or symbols"
+            end
+
+            return key if key.is_a?(Symbol)
+
+            payload_attribute_lookup.fetch(key) { key.dup.freeze }
+          end
+
+          def validate_known_attributes!(attributes)
+            unknown = attributes.keys - payload_attribute_names
+            missing = payload_attribute_names - attributes.keys
+            raise ArgumentError, "#{payload_name} contains unknown attributes: #{unknown.join(", ")}" if unknown.any?
+            return if missing.empty?
+
+            raise ArgumentError, "#{payload_name} is missing attributes: #{missing.join(", ")}"
+          end
+
+          def payload_attribute_names
+            @payload_attribute_names ||= schema.keys.map(&:name).freeze
+          end
+
+          def payload_attribute_lookup
+            @payload_attribute_lookup ||= payload_attribute_names.to_h do |name|
+              [name.to_s.freeze, name]
+            end.freeze
+          end
+
+          def raw_attribute(attributes, name)
+            symbol_present = Hash.instance_method(:key?).bind_call(attributes, name)
+            string_present = Hash.instance_method(:key?).bind_call(attributes, name.to_s)
+            raise ArgumentError, "#{payload_name} contains duplicate attributes" if symbol_present && string_present
+
+            Hash.instance_method(:[]).bind_call(attributes, symbol_present ? name : name.to_s)
+          end
+
+          def parse_attributes(value)
+            return value if value.is_a?(Hash)
+            unless value.is_a?(String) && value.bytesize <= MAX_SERIALIZED_BYTES
+              raise ArgumentError, "#{payload_name} must be a bounded Hash or JSON object"
+            end
+
+            JSON.parse(value).tap do |parsed|
+              raise ArgumentError, "#{payload_name} JSON must contain an object" unless parsed.is_a?(Hash)
+            end
+          end
+        end
+
+        def serialize
+          JSON.generate(to_h).tap do |payload|
+            raise WorkflowError, "#{self.class.payload_name} exceeds maximum bytes" if
+              payload.bytesize > self.class::MAX_SERIALIZED_BYTES
+          end
+        end
+
+        def initialize(attributes)
+          super
+          validate_serialized_size!
+          self.attributes.freeze
+          freeze
+        end
+
+        private
+
+        def validate_serialized_size!
+          return if JSON.generate(to_h).bytesize <= self.class::MAX_SERIALIZED_BYTES
+
+          raise ArgumentError, "#{self.class.payload_name} exceeds maximum encoded bytes"
+        end
+      end
+
+      private_constant :Payload
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "digest"
+require "dry-initializer"
+require "json"
+
+require_relative "../message_value_normalizer"
+
+module Smith
+  class Workflow
+    module Composite
+      class PayloadDigest
+        extend Dry::Initializer
+
+        param :value
+
+        def self.call(value) = new(value).call
+
+        def call
+          normalized = MessageValueNormalizer.new(value, label: "composite payload").call
+          Digest::SHA256.hexdigest(JSON.generate(normalized))
+        end
+      end
+
+      private_constant :PayloadDigest
+    end
+  end
+end