smith-agents 0.4.5 → 0.5.0

data/lib/smith/workflow/graph/transition_contract_attributes.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "transition_contract_configurations"
+
+module Smith
+  class Workflow
+    class Graph
+      class TransitionContractAttributes
+        extend Dry::Initializer
+
+        param :transition
+        option :identifiers
+
+        def to_h
+          identity_attributes
+            .merge(routing_attributes)
+            .merge(kind_attributes)
+            .merge(TransitionContractConfigurations.new(transition, identifiers:).to_h)
+        end
+
+        private
+
+        def identity_attributes
+          {
+            name: identifiers.call(transition.name),
+            from: identifiers.call(transition.from),
+            to: identifiers.call(transition.to),
+            agent_name: own(transition.agent_name),
+            workflow_class: transition.workflow_class
+          }
+        end
+
+        def routing_attributes
+          {
+            success_transition: project(transition.success_transition),
+            failure_transition: project(transition.failure_transition),
+            deterministic_routes: project_array(transition.deterministic_routes)
+          }
+        end
+
+        def kind_attributes
+          {
+            deterministic_kind: transition.deterministic_kind,
+            deterministic: transition.deterministic?,
+            parallel: transition.parallel?,
+            parallel_count: static_parallel_count
+          }
+        end
+
+        def static_parallel_count
+          return unless transition.parallel?
+
+          count = transition.agent_opts[:count]
+          count.respond_to?(:call) ? nil : (count || 1)
+        end
+
+        def project_array(array)
+          array&.map { identifiers.call(_1) }&.freeze
+        end
+
+        def project(value)
+          identifiers.call(value) unless value.nil?
+        end
+
+        def own(value)
+          value.is_a?(String) ? value.dup.freeze : value
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/transition_contract_configurations.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "transition_optimization_configuration"
+
+module Smith
+  class Workflow
+    class Graph
+      class TransitionContractConfigurations
+        extend Dry::Initializer
+
+        param :transition
+        option :identifiers
+
+        def to_h
+          {
+            router_config: router_config,
+            optimization_config: optimization_config,
+            orchestrator_config: orchestrator_config,
+            fanout_config: fanout_config,
+            retry_config: retry_config
+          }
+        end
+
+        private
+
+        def router_config
+          config = transition.router_config
+          return unless config
+
+          {
+            routes: project_routes(config.fetch(:routes)),
+            confidence_threshold: config.fetch(:confidence_threshold),
+            fallback: identifiers.call(config.fetch(:fallback))
+          }.freeze
+        end
+
+        def optimization_config
+          config = transition.optimization_config
+          TransitionOptimizationConfiguration.new(config).to_h if config
+        end
+
+        def orchestrator_config
+          config = transition.orchestrator_config
+          return unless config
+
+          {
+            orchestrator: own(config.fetch(:orchestrator)),
+            worker: own(config.fetch(:worker)),
+            max_workers: config.fetch(:max_workers),
+            max_delegation_rounds: config.fetch(:max_delegation_rounds),
+            task_schema_label: label(config.fetch(:task_schema)),
+            worker_output_schema_label: label(config.fetch(:worker_output_schema)),
+            final_output_schema_label: label(config.fetch(:final_output_schema))
+          }.freeze
+        end
+
+        def fanout_config
+          branches = transition.fanout_config&.fetch(:branches, nil)
+          { branches: own_hash(branches) }.freeze if branches
+        end
+
+        def retry_config
+          config = transition.retry_config
+          return unless config
+
+          {
+            error_classes: config.fetch(:error_classes).dup.freeze,
+            attempts: config.fetch(:attempts),
+            backoff: config.fetch(:backoff),
+            max_delay: config[:max_delay],
+            jitter: config.fetch(:jitter)
+          }.freeze
+        end
+
+        def own_hash(hash)
+          hash.each_with_object({}) do |(key, value), copy|
+            copy[own(key)] = own(value)
+          end.freeze
+        end
+
+        def project_routes(routes)
+          routes.each_with_object({}) do |(key, transition_name), copy|
+            copy[own(key)] = identifiers.call(transition_name)
+          end.freeze
+        end
+
+        def own(value)
+          value.is_a?(String) ? value.dup.freeze : value
+        end
+
+        def label(value)
+          result = value.respond_to?(:name) && value.name && !value.name.empty? ? value.name : value.inspect
+          result.dup.freeze
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/transition_diagnostics.rb

@@ -17,7 +17,9 @@ module Smith
               transition_target_diagnostic(transition, :failure_transition, transition.failure_transition),
               *router_target_diagnostics(transition),
               *deterministic_route_diagnostics(transition),
-              *target_state_mismatch_diagnostics(transition)
+              *target_state_mismatch_diagnostics(transition),
+              branch_limit_diagnostic(transition),
+              RetryPolicyDiagnostic.new(transition:).call
             ].compact
           end
         end
@@ -53,25 +55,65 @@ module Smith
         end
 
         def target_state_mismatch_diagnostics(transition)
-          Targets.for(transition).filter_map do |target_name|
-            target = graph.transitions[target_name]
-            next unless target
-            next if target.from.nil? || target.from == transition.to
-
-            mismatch_diagnostic(transition, target_name, target)
+          success = successful_target_names(transition).filter_map do |target_name|
+            target_state_mismatch_diagnostic(transition, target_name, expected_state: transition.to)
           end
+          failure = target_state_mismatch_diagnostic(
+            transition,
+            transition.failure_transition,
+            expected_state: transition.from
+          )
+
+          [*success, failure].compact
         end
 
-        def mismatch_diagnostic(transition, target_name, target)
+        def branch_limit_diagnostic(transition)
+          branch_count = static_branch_count(transition)
+          limit = Smith.config.parallel_branch_limit
+          return unless branch_count && branch_count > limit
+
           Diagnostic.new(
-            severity: :warning,
+            severity: :error,
+            code: :parallel_branch_limit_exceeded,
+            transition: transition.name,
+            message: "Transition #{ref(transition.name)} declares #{branch_count} parallel branches, " \
+                     "exceeding the configured limit #{limit}.",
+            suggestion: "Reduce the branch count or explicitly raise Smith.config.parallel_branch_limit."
+          )
+        end
+
+        def static_branch_count(transition)
+          return transition.fanout_config.fetch(:branches).length if transition.fanout?
+
+          transition.parallel_count if transition.parallel?
+        end
+
+        def successful_target_names(transition)
+          return Targets.router_for(transition) if transition.routed?
+
+          [transition.success_transition, *Array(transition.deterministic_routes)].compact.uniq
+        end
+
+        def target_state_mismatch_diagnostic(transition, target_name, expected_state:)
+          return if target_name.nil?
+
+          target = graph.transitions[target_name]
+          return unless target
+          return if target.from.nil? || target.from == expected_state
+
+          mismatch_diagnostic(transition, target_name, target, expected_state:)
+        end
+
+        def mismatch_diagnostic(transition, target_name, target, expected_state:)
+          Diagnostic.new(
+            severity: :error,
             code: :target_from_state_mismatch,
             transition: transition.name,
             target: target_name,
-            state: transition.to,
+            state: expected_state,
             message: "Transition #{ref(transition.name)} can route to #{ref(target_name)}, " \
-                     "but #{ref(target_name)} starts from #{ref(target.from)} instead of #{ref(transition.to)}.",
-            suggestion: "Align #{ref(target_name)}'s from state with #{ref(transition.to)}, " \
+                     "but #{ref(target_name)} starts from #{ref(target.from)} instead of #{ref(expected_state)}.",
+            suggestion: "Align #{ref(target_name)}'s from state with #{ref(expected_state)}, " \
                         "or remove the named route."
           )
         end

data/lib/smith/workflow/graph/transition_optimization_configuration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class TransitionOptimizationConfiguration
+        extend Dry::Initializer
+
+        param :config
+
+        def to_h
+          identity
+            .merge(evaluation)
+            .merge(exit_modes)
+            .freeze
+        end
+
+        private
+
+        def identity
+          {
+            generator: own(config.fetch(:generator)),
+            evaluator: own(config.fetch(:evaluator)),
+            max_rounds: config.fetch(:max_rounds)
+          }
+        end
+
+        def evaluation
+          {
+            evaluator_schema_label: label(config.fetch(:evaluator_schema)),
+            evaluator_context: callable_marker(config[:evaluator_context]),
+            improvement_threshold: config[:improvement_threshold],
+            before_eval: callable_marker(config[:before_eval])
+          }
+        end
+
+        def exit_modes
+          {
+            on_exhaustion: callable_marker(config.fetch(:on_exhaustion)),
+            on_converged: callable_marker(config.fetch(:on_converged)),
+            on_threshold: callable_marker(config.fetch(:on_threshold))
+          }
+        end
+
+        def own(value)
+          value.is_a?(String) ? value.dup.freeze : value
+        end
+
+        def label(value)
+          result = value.respond_to?(:name) && value.name && !value.name.empty? ? value.name : value.inspect
+          result.dup.freeze
+        end
+
+        def callable_marker(value)
+          value.respond_to?(:call) ? :callable : own(value)
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/transition_snapshot.rb

@@ -26,6 +26,7 @@ module Smith
         option :from
         option :to
         option :kind
+        option :parallel_count, default: proc {}
         option :success_transition, default: proc {}
         option :failure_transition, default: proc {}
         option :routes, default: proc {}
@@ -46,7 +47,8 @@ module Smith
             name: transition.name,
             from: transition.from,
             to: transition.to,
-            kind: kind_for(transition)
+            kind: kind_for(transition),
+            parallel_count: transition.parallel_count
           }.merge(routing_attributes(transition), contract_attributes(transition, workflow_class: workflow_class))
         end
 
@@ -109,6 +111,7 @@ module Smith
             from: from,
             to: to,
             kind: kind,
+            parallel_count: parallel_count,
             success_transition: success_transition,
             failure_transition: failure_transition,
             routes: routes,

data/lib/smith/workflow/graph/validator.rb

@@ -35,7 +35,7 @@ module Smith
         end
 
         def reachable_transition_names
-          @reachable_transition_names ||= Reachability.new(graph).transition_names
+          @reachable_transition_names ||= graph.reachable_transitions.map(&:name).freeze
         end
 
         def status_for(diagnostics)

data/lib/smith/workflow/graph.rb

@@ -3,13 +3,18 @@
 module Smith
   class Workflow
     class Graph
+      EMPTY_TRANSITIONS = [].freeze
+
       attr_reader :workflow_class, :initial_state, :states, :transitions
 
       def initialize(workflow_class:, initial_state:, states:, transitions:)
+        @identifier_projection = IdentifierProjection.new
         @workflow_class = workflow_class
-        @initial_state = initial_state
-        @states = Array(states).uniq.freeze
-        @transitions = transitions.dup.freeze
+        @initial_state = project_identifier(initial_state)
+        @states = own_states(states)
+        @state_index = index_states
+        @transitions = own_transitions(transitions)
+        @transitions_by_state = build_transitions_by_state
       end
 
       def validate
@@ -25,13 +30,66 @@ module Smith
           TransitionSnapshot.from_transition(transition, workflow_class: workflow_class)
         end
       end
+
+      def transitions_from(state)
+        @transitions_by_state.fetch(state, EMPTY_TRANSITIONS)
+      end
+
+      def first_transition_from(state)
+        transitions_from(state).first
+      end
+
+      def reachable_transitions
+        @reachable_transitions ||= Reachability.new(self).each_transition.to_a.freeze
+      end
+
+      def state?(state)
+        @state_index.key?(state)
+      end
+
+      private
+
+      def project_identifier(identifier)
+        @identifier_projection.call(identifier)
+      end
+
+      def own_states(states)
+        Array(states).map { project_identifier(_1) }.uniq.freeze
+      end
+
+      def index_states
+        states.to_h { [_1, true] }.freeze
+      end
+
+      def own_transitions(transitions)
+        transitions.each_value.with_index.with_object({}) do |(transition, definition_index), snapshot|
+          contract = TransitionContract.from_transition(
+            transition,
+            identifiers: @identifier_projection,
+            definition_index:
+          )
+          snapshot[contract.name] = contract
+        end.freeze
+      end
+
+      def build_transitions_by_state
+        index = transitions.values.each_with_object({}) do |transition, result|
+          (result[transition.from] ||= []) << transition
+        end
+        index.each_value(&:freeze)
+        index.freeze
+      end
     end
   end
 end
 
 require_relative "graph/reference"
+require_relative "graph/identifier_projection"
+require_relative "graph/transition_contract"
 require_relative "graph/diagnostic"
 require_relative "graph/state_diagnostics"
+require_relative "graph/targets"
+require_relative "graph/execution_successors"
 require_relative "graph/reachability"
 require_relative "graph/reachability_diagnostics"
 require_relative "graph/metrics"
@@ -41,11 +99,11 @@ require_relative "graph/runtime_binding_diagnostic_builder"
 require_relative "graph/runtime_binding_diagnostics"
 require_relative "graph/runtime_readiness_report"
 require_relative "graph/runtime_readiness_metrics"
-require_relative "graph/targets"
 require_relative "graph/fanout_contract"
 require_relative "graph/optimization_contract"
 require_relative "graph/orchestration_contract"
 require_relative "graph/transition_snapshot"
+require_relative "graph/retry_policy_diagnostic"
 require_relative "graph/transition_diagnostics"
 require_relative "graph/validator"
 require_relative "graph/runtime_readiness"

data/lib/smith/workflow/guardrail_integration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "transition_actionability"
+
 module Smith
   class Workflow
     module GuardrailIntegration
@@ -21,30 +23,42 @@ module Smith
       end
 
       def handle_step_failure(transition, error)
+        step = { transition: transition.name, from: transition.from, to: transition.to, error: error }
+        SplitStepPersistence
+          .instance_method(:capture_split_step_execution_result!)
+          .bind_call(self, step)
         failure_name = transition.failure_transition
         raise error unless failure_name
 
         fail_transition = self.class.find_transition(failure_name)
         raise error unless fail_transition
+
         validate_transition_origin!(fail_transition)
 
         if actionable_failure_transition?(fail_transition)
           @next_transition_name = failure_name
-          return
+          return step
         end
 
         @state = fail_transition.to
+        step
+      end
+
+      def handle_unresolved_transition_failure(error)
+        fail_transition = self.class.find_transition(:fail)
+        raise error unless fail_transition
+
+        @outcome = nil
+        step = { transition: error.requested_name, from: @state, to: fail_transition.to, error: error }
+        SplitStepPersistence
+          .instance_method(:capture_split_step_execution_result!)
+          .bind_call(self, step)
+        @state = fail_transition.to
+        step
       end
 
       def actionable_failure_transition?(transition)
-        transition.agent_name ||
-          transition.deterministic? ||
-          transition.routed? ||
-          transition.fanout? ||
-          transition.nested? ||
-          transition.optimized? ||
-          transition.orchestrated? ||
-          transition.success_transition
+        TransitionActionability.call(transition)
       end
 
       def run_workflow_input_guardrails

data/lib/smith/workflow/identifier.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Identifier
+      def self.normalize(value, label:, allow_nil: false)
+        return if value.nil? && allow_nil
+
+        case value
+        when String
+          raise WorkflowError, "#{label} must not be blank" if value.strip.empty?
+
+          value.dup.freeze
+        when Symbol
+          raise WorkflowError, "#{label} must not be blank" if value.to_s.empty?
+
+          value
+        else
+          raise WorkflowError, "#{label} must be a String or Symbol"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/message_admission.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "digest"
+require "dry-struct"
+require "json"
+
+require_relative "../errors"
+require_relative "../types"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    class MessageAdmission < Dry::Struct
+      transform_keys(&:to_sym)
+      schema schema.strict
+
+      attribute :messages, Types::Array.of(Types::Hash)
+
+      attr_reader :message_digest
+
+      def initialize(attributes)
+        normalized = MessageValueNormalizer.new(attributes.fetch(:messages)).call
+        payload = JSON.generate(normalized, max_nesting: MessageValueNormalizer::MAX_DEPTH)
+        if payload.bytesize > MessageValueNormalizer::MAX_BYTES
+          raise WorkflowError,
+                "session message batch exceeds maximum bytes #{MessageValueNormalizer::MAX_BYTES}"
+        end
+
+        super(messages: normalized)
+        @message_digest = Digest::SHA256.hexdigest(payload).freeze
+        self.attributes.freeze
+        freeze
+      rescue JSON::GeneratorError, JSON::NestingError => e
+        raise WorkflowError, "session message batch is not canonical JSON: #{e.message}"
+      end
+
+      def message_count = messages.length
+    end
+  end
+end

data/lib/smith/workflow/message_admission_boundary.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "message_batch"
+
+module Smith
+  class Workflow
+    module MessageAdmissionBoundary
+      def append_session_messages!(messages)
+        admission = MessageBatch.new(messages).call
+        @split_step_mutex.synchronize do
+          SplitStepPersistence.instance_method(:ensure_no_split_step_boundary!).bind_call(self)
+          unless @session_messages.nil? || @session_messages.is_a?(Array)
+            raise WorkflowError, "workflow session messages are not appendable"
+          end
+
+          (@session_messages ||= []).concat(admission.messages)
+        end
+        admission
+      end
+    end
+  end
+end

data/lib/smith/workflow/message_batch.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../errors"
+require_relative "message_admission"
+
+module Smith
+  class Workflow
+    class MessageBatch
+      MAX_MESSAGES = 100
+      MAX_DEPTH = MessageValueNormalizer::MAX_DEPTH
+      MAX_NODES = MessageValueNormalizer::MAX_NODES
+      MAX_BYTES = MessageValueNormalizer::MAX_BYTES
+      ARRAY_EACH = Array.instance_method(:each)
+      private_constant :ARRAY_EACH
+
+      extend Dry::Initializer
+
+      param :messages
+
+      def call
+        batch = normalize_batch
+        batch.each { reject!("each session message must be a Hash") unless _1.is_a?(Hash) }
+        admission = MessageAdmission.new(messages: batch)
+        admission.messages.each { validate_message!(_1) }
+        admission
+      end
+
+      private
+
+      def normalize_batch
+        return [messages] if messages.is_a?(Hash)
+
+        reject!("session messages must be a message Hash or an Array of message Hashes") unless messages.is_a?(Array)
+
+        batch = []
+        ARRAY_EACH.bind_call(messages) do |message|
+          reject!("session message batch exceeds maximum count #{MAX_MESSAGES}") if batch.length == MAX_MESSAGES
+
+          batch << message
+        end
+        reject!("session message batch must not be empty") if batch.empty?
+
+        batch
+      end
+
+      def validate_message!(message)
+        reject!("each session message must be a Hash") unless message.is_a?(Hash)
+        role = message["role"]
+        reject!("each session message requires a non-empty role") unless
+          role.is_a?(String) && !role.strip.empty?
+      end
+
+      def reject!(message)
+        raise WorkflowError, message
+      end
+    end
+  end
+end