smith-agents 0.4.5 → 0.6.0

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

@@ -9,7 +9,8 @@ module Smith
         extend Dry::Initializer
 
         param :graph
-        option :visited, default: proc {}
+        option :reports
+        option :cycle_transitions, default: proc { {}.compare_by_identity }
 
         def to_a
           cycle_diagnostics + report_entries.flat_map { |entry| diagnostics_for(entry) }
@@ -28,27 +29,30 @@ module Smith
         end
 
         def cycle_diagnostics
-          nested_workflow_transitions.filter_map do |transition|
+          cycle_transitions.keys.map do |transition|
             workflow_class = transition.workflow_class
-            cycle_diagnostic(transition, workflow_class) if visited_workflows.include?(workflow_class)
+            cycle_diagnostic(transition, workflow_class)
           end
         end
 
         def report_entries
           @report_entries ||= nested_workflow_transitions.filter_map do |transition|
+            next if cycle_transitions.key?(transition)
+
             workflow_class = transition.workflow_class
-            next if visited_workflows.include?(workflow_class)
+            report = reports[workflow_class]
+            next unless report
 
             {
               transition: transition,
               workflow_class: workflow_class,
-              report: workflow_class.graph.runtime_readiness(visited: visited_workflows)
+              report: report
             }.freeze
           end.freeze
         end
 
         def nested_workflow_transitions
-          @nested_workflow_transitions ||= graph.transitions.values.select(&:nested?)
+          @nested_workflow_transitions ||= graph.reachable_transitions.select(&:nested?)
         end
 
         def cycle_diagnostic(transition, workflow_class)
@@ -67,21 +71,16 @@ module Smith
 
         def nested_diagnostic(transition, workflow_class, diagnostic)
           label = workflow_label(workflow_class)
+          code = diagnostic.code.to_s.start_with?("nested_") ? diagnostic.code : :"nested_#{diagnostic.code}"
 
-          Diagnostic.new(
-            severity: diagnostic.severity,
-            code: :"nested_#{diagnostic.code}",
+          diagnostic.nested(
+            label: label,
+            code: code,
             transition: transition.name,
-            target: label,
-            message: "Nested workflow #{label}: #{diagnostic.message}",
-            suggestion: diagnostic.suggestion
+            target: label
           )
         end
 
-        def visited_workflows
-          @visited_workflows ||= Set.new(Array(visited)).add(graph.workflow_class)
-        end
-
         def ref(value)
           Reference.format(value)
         end

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

@@ -44,10 +44,10 @@ module Smith
 
         def evaluation_contract
           {
-            evaluator_schema: label_for(config.fetch(:evaluator_schema)),
+            evaluator_schema: config.fetch(:evaluator_schema_label),
             evaluator_context: config[:evaluator_context],
             improvement_threshold: config[:improvement_threshold],
-            before_eval: callable_label(config[:before_eval])
+            before_eval: config[:before_eval]
           }
         end
 

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

@@ -46,9 +46,9 @@ module Smith
 
         def schema_contract
           {
-            task_schema: label_for(config.fetch(:task_schema)),
-            worker_output_schema: label_for(config.fetch(:worker_output_schema)),
-            final_output_schema: label_for(config.fetch(:final_output_schema))
+            task_schema: config.fetch(:task_schema_label),
+            worker_output_schema: config.fetch(:worker_output_schema_label),
+            final_output_schema: config.fetch(:final_output_schema_label)
           }
         end
 

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

@@ -11,47 +11,35 @@ module Smith
         end
 
         def transition_names
-          return [] unless graph.initial_state
-
-          reset_walk
-          drain_queue
-          @seen_transitions.keys
+          each_transition.map(&:name)
         end
 
-        private
+        def each_transition
+          return enum_for(__method__) unless block_given?
 
-        def reset_walk
-          @seen_states = { graph.initial_state => true }
-          @seen_transitions = {}
-          @queue = [graph.initial_state]
-        end
+          root = successors.initial_transition
+          return unless root
 
-        def drain_queue
-          transitions_from(@queue.shift).each { |transition| visit_transition(transition) } until @queue.empty?
+          walk(root) { yield _1 }
         end
 
-        def visit_transition(transition)
-          return if @seen_transitions.key?(transition.name)
-
-          @seen_transitions[transition.name] = true
-          enqueue_state(transition.to)
-          Targets.for(transition).each { |target_name| visit_named_transition(target_name) }
-        end
+        private
 
-        def visit_named_transition(target_name)
-          target = graph.transitions[target_name]
-          visit_transition(target) if target
+        def successors
+          @successors ||= ExecutionSuccessors.new(graph)
         end
 
-        def enqueue_state(state)
-          return if state.nil? || @seen_states.key?(state)
-
-          @seen_states[state] = true
-          @queue << state
-        end
+        def walk(root)
+          seen = {}
+          stack = [root]
+          until stack.empty?
+            transition = stack.pop
+            next if seen.key?(transition.name)
 
-        def transitions_from(state)
-          graph.transitions.values.select { |transition| transition.from == state }
+            seen[transition.name] = true
+            yield transition
+            successors.for(transition).reverse_each { stack << _1 }
+          end
         end
       end
     end

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

@@ -9,11 +9,13 @@ module Smith
         def initialize(graph, reachable_transition_names)
           @graph = graph
           @reachable_transition_names = reachable_transition_names
+          @reachable_transition_index = reachable_transition_names.to_h { [_1, true] }.freeze
+          @control_marker_index = control_marker_index
         end
 
         def to_a
           (graph.transitions.keys - reachable_transition_names).filter_map do |transition_name|
-            next if auto_fail_transition?(transition_name)
+            next if auto_fail_transition?(transition_name) || control_marker?(transition_name)
 
             diagnostic_for(transition_name)
           end
@@ -25,6 +27,20 @@ module Smith
           transition_name == :fail && graph.transitions[transition_name]&.from.nil?
         end
 
+        def control_marker?(transition_name)
+          @control_marker_index.key?(transition_name)
+        end
+
+        def control_marker_index
+          successors = ExecutionSuccessors.new(graph)
+          graph.transitions.each_value.with_object({}) do |transition, index|
+            next unless @reachable_transition_index.key?(transition.name)
+
+            marker = successors.failure_control_marker(transition)
+            index[marker.name] = true if marker
+          end.freeze
+        end
+
         def diagnostic_for(transition_name)
           transition = graph.transitions.fetch(transition_name)
           Diagnostic.new(

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class RetryPolicyDiagnostic
+        extend Dry::Initializer
+
+        option :transition
+
+        def call
+          attempts = transition.retry_config&.fetch(:attempts, nil)
+          limit = Smith.config.retry_attempt_limit
+          return unless attempts && attempts > limit
+
+          Diagnostic.new(
+            severity: :error,
+            code: :retry_attempt_limit_exceeded,
+            transition: transition.name,
+            message: "Transition #{ref(transition.name)} declares #{attempts} retry attempts, " \
+                     "exceeding the configured limit #{limit}.",
+            suggestion: "Reduce the retry attempts or explicitly raise Smith.config.retry_attempt_limit."
+          )
+        end
+
+        private
+
+        def ref(value)
+          Reference.format(value)
+        end
+      end
+    end
+  end
+end

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

@@ -17,9 +17,9 @@ module Smith
         end
 
         def agent_bindings
-          @agent_bindings ||= graph.transitions.values.flat_map do |transition|
+          @agent_bindings ||= graph.reachable_transitions.flat_map do |transition|
             bindings_for_transition(transition)
-          end
+          end.freeze
         end
 
         private

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

@@ -2,6 +2,8 @@
 
 require "dry-initializer"
 
+require_relative "runtime_readiness_traversal"
+
 module Smith
   class Workflow
     class Graph
@@ -12,50 +14,7 @@ module Smith
         option :visited, default: proc {}
 
         def report
-          RuntimeReadinessReport.new(
-            workflow_class: workflow_label(graph.workflow_class),
-            topology_report: topology_report,
-            runtime_diagnostics: runtime_diagnostics,
-            metrics: runtime_metrics
-          )
-        end
-
-        private
-
-        def topology_report
-          @topology_report ||= graph.validate
-        end
-
-        def runtime_diagnostics
-          @runtime_diagnostics ||= [
-            *binding_diagnostics.to_a,
-            *nested_diagnostics.to_a
-          ]
-        end
-
-        def binding_diagnostics
-          @binding_diagnostics ||= RuntimeBindingDiagnostics.new(graph)
-        end
-
-        def nested_diagnostics
-          @nested_diagnostics ||= NestedReadinessDiagnostics.new(graph, visited: visited)
-        end
-
-        def runtime_metrics
-          RuntimeReadinessMetrics.new(
-            graph,
-            topology_report: topology_report,
-            runtime_diagnostics: runtime_diagnostics,
-            agent_bindings: binding_diagnostics.agent_bindings,
-            nested_reports: nested_diagnostics.child_reports
-          ).to_h
-        end
-
-        def workflow_label(workflow_class)
-          name = workflow_class.name
-          return name if name && !name.empty?
-
-          workflow_class.inspect
+          RuntimeReadinessTraversal.new(graph, visited:).report
         end
       end
     end

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

@@ -75,11 +75,11 @@ module Smith
         end
 
         def fanout_transitions
-          @fanout_transitions ||= graph.transitions.values.select(&:fanout?)
+          @fanout_transitions ||= graph.reachable_transitions.select(&:fanout?)
         end
 
         def direct_nested_workflow_count
-          graph.transitions.values.count(&:nested?)
+          graph.reachable_transitions.count(&:nested?)
         end
       end
     end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class RuntimeReadinessReportBuilder
+        extend Dry::Initializer
+
+        param :graph
+        option :reports
+        option :cycle_transitions
+
+        def call
+          topology_report = graph.validate
+          bindings = RuntimeBindingDiagnostics.new(graph)
+          nested = NestedReadinessDiagnostics.new(graph, reports:, cycle_transitions:)
+          diagnostics = [*bindings.to_a, *nested.to_a]
+          RuntimeReadinessReport.new(
+            workflow_class: workflow_label,
+            topology_report: topology_report,
+            runtime_diagnostics: diagnostics,
+            metrics: metrics(topology_report, diagnostics, bindings, nested)
+          )
+        end
+
+        private
+
+        def metrics(topology_report, diagnostics, bindings, nested)
+          RuntimeReadinessMetrics.new(
+            graph,
+            topology_report: topology_report,
+            runtime_diagnostics: diagnostics,
+            agent_bindings: bindings.agent_bindings,
+            nested_reports: nested.child_reports
+          ).to_h
+        end
+
+        def workflow_label
+          name = graph.workflow_class.name
+          name && !name.empty? ? name : graph.workflow_class.inspect
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "runtime_readiness_report_builder"
+
+module Smith
+  class Workflow
+    class Graph
+      class RuntimeReadinessTraversal
+        extend Dry::Initializer
+
+        param :graph
+        option :visited, default: proc {}
+
+        def report
+          initialize_walk
+          inspect_graphs
+          @reports.fetch(graph.workflow_class)
+        end
+
+        private
+
+        def initialize_walk
+          @states = {}.compare_by_identity
+          @reports = {}.compare_by_identity
+          @graphs = {}.compare_by_identity
+          @nested_transitions = {}.compare_by_identity
+          @cycle_transitions = {}.compare_by_identity
+          visited_workflows.each { @states[_1] = :visiting }
+          @graphs[graph.workflow_class] = graph
+          @states[graph.workflow_class] = :visiting
+        end
+
+        def inspect_graphs
+          frames = [frame_for(graph)]
+          until frames.empty?
+            frame = frames.last
+            if frame.fetch(:index) >= frame.fetch(:transitions).length
+              complete_graph(frame.fetch(:graph))
+              frames.pop
+              next
+            end
+
+            transition = next_transition(frame)
+            visit_child(frame.fetch(:graph), transition, frames)
+          end
+        end
+
+        def frame_for(current_graph)
+          {
+            graph: current_graph,
+            transitions: nested_transitions_for(current_graph),
+            index: 0
+          }
+        end
+
+        def next_transition(frame)
+          transition = frame.fetch(:transitions).fetch(frame.fetch(:index))
+          frame[:index] += 1
+          transition
+        end
+
+        def visit_child(parent_graph, transition, frames)
+          workflow_class = transition.workflow_class
+          case @states[workflow_class]
+          when :visiting then mark_cycle(parent_graph, transition)
+          when :done then nil
+          else
+            child_graph = graph_for(workflow_class)
+            @states[workflow_class] = :visiting
+            frames << frame_for(child_graph)
+          end
+        end
+
+        def complete_graph(current_graph)
+          workflow_class = current_graph.workflow_class
+          @reports[workflow_class] = RuntimeReadinessReportBuilder.new(
+            current_graph,
+            reports: @reports,
+            cycle_transitions: cycles_for(current_graph)
+          ).call
+          @states[workflow_class] = :done
+        end
+
+        def graph_for(workflow_class)
+          @graphs[workflow_class] ||= workflow_class.graph
+        end
+
+        def nested_transitions_for(current_graph)
+          @nested_transitions[current_graph] ||= current_graph.reachable_transitions.select(&:nested?).freeze
+        end
+
+        def mark_cycle(current_graph, transition)
+          cycles_for(current_graph)[transition] = true
+        end
+
+        def cycles_for(current_graph)
+          @cycle_transitions[current_graph] ||= {}.compare_by_identity
+        end
+
+        def visited_workflows
+          visited.respond_to?(:keys) ? visited.keys : Array(visited)
+        end
+      end
+    end
+  end
+end

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

@@ -20,7 +20,7 @@ module Smith
         private
 
         def initial_state_diagnostics
-          return [] if graph.initial_state && graph.states.include?(graph.initial_state)
+          return [] if graph.initial_state && graph.state?(graph.initial_state)
 
           [
             Diagnostic.new(
@@ -44,7 +44,7 @@ module Smith
 
         def undefined_state_diagnostic(transition, edge, state)
           return if edge == :from && state.nil?
-          return if graph.states.include?(state)
+          return if graph.state?(state)
 
           Diagnostic.new(
             severity: :error,

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "transition_contract_attributes"
+
+module Smith
+  class Workflow
+    class Graph
+      class TransitionContract
+        extend Dry::Initializer
+
+        option :name
+        option :definition_index
+        option :from
+        option :to
+        option :agent_name, default: proc {}
+        option :success_transition, default: proc {}
+        option :failure_transition, default: proc {}
+        option :router_config, default: proc {}
+        option :workflow_class, default: proc {}
+        option :optimization_config, default: proc {}
+        option :orchestrator_config, default: proc {}
+        option :fanout_config, default: proc {}
+        option :retry_config, default: proc {}
+        option :deterministic_kind, default: proc {}
+        option :deterministic_routes, default: proc {}
+        option :deterministic, default: proc { false }
+        option :parallel, default: proc { false }
+        option :parallel_count, default: proc {}
+
+        def self.from_transition(transition, identifiers:, definition_index:)
+          attributes = TransitionContractAttributes.new(transition, identifiers:).to_h
+          new(**attributes, definition_index:).freeze
+        end
+
+        def deterministic? = deterministic
+        def orchestrated? = !orchestrator_config.nil?
+        def fanout? = !fanout_config.nil?
+        def optimized? = !optimization_config.nil?
+        def nested? = !workflow_class.nil?
+        def routed? = !router_config.nil?
+        def parallel? = parallel
+      end
+    end
+  end
+end

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