smith-agents 0.4.0 → 0.4.2

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class ReachabilityDiagnostics
+        attr_reader :graph, :reachable_transition_names
+
+        def initialize(graph, reachable_transition_names)
+          @graph = graph
+          @reachable_transition_names = reachable_transition_names
+        end
+
+        def to_a
+          (graph.transitions.keys - reachable_transition_names).filter_map do |transition_name|
+            next if auto_fail_transition?(transition_name)
+
+            diagnostic_for(transition_name)
+          end
+        end
+
+        private
+
+        def auto_fail_transition?(transition_name)
+          transition_name == :fail && graph.transitions[transition_name]&.from.nil?
+        end
+
+        def diagnostic_for(transition_name)
+          transition = graph.transitions.fetch(transition_name)
+          Diagnostic.new(
+            severity: :warning,
+            code: :unreachable_transition,
+            transition: transition_name,
+            state: transition.from,
+            message: "Transition #{ref(transition_name)} is not reachable from " \
+                     "initial_state #{ref(graph.initial_state)}.",
+            suggestion: "Connect transition #{ref(transition_name)} from a reachable state or remove it."
+          )
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      module Reference
+        def self.format(value)
+          return ":#{value}" if value.is_a?(Symbol)
+
+          value.inspect
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Report
+        attr_reader :status, :workflow_class, :initial_state, :states, :transitions, :diagnostics, :metrics
+
+        def initialize(**attributes)
+          @status = attributes.fetch(:status)
+          @workflow_class = attributes.fetch(:workflow_class)
+          @initial_state = attributes.fetch(:initial_state)
+          @states = attributes.fetch(:states)
+          @transitions = attributes.fetch(:transitions)
+          @diagnostics = attributes.fetch(:diagnostics)
+          @metrics = attributes.fetch(:metrics)
+        end
+
+        def valid?
+          errors.empty?
+        end
+
+        def errors
+          diagnostics.select { |diagnostic| diagnostic.severity == :error }
+        end
+
+        def warnings
+          diagnostics.select { |diagnostic| diagnostic.severity == :warning }
+        end
+
+        def suggestions
+          diagnostics.map(&:suggestion).compact.uniq
+        end
+
+        def to_h
+          {
+            status: status,
+            workflow_class: workflow_class,
+            initial_state: initial_state,
+            states: states,
+            transitions: transitions.map(&:to_h),
+            diagnostics: diagnostics.map(&:to_h),
+            suggestions: suggestions,
+            metrics: metrics
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class StateDiagnostics
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def to_a
+          [
+            *initial_state_diagnostics,
+            *state_reference_diagnostics
+          ]
+        end
+
+        private
+
+        def initial_state_diagnostics
+          return [] if graph.initial_state && graph.states.include?(graph.initial_state)
+
+          [
+            Diagnostic.new(
+              severity: :error,
+              code: :missing_initial_state,
+              state: graph.initial_state,
+              message: "Workflow initial_state is not declared as a state.",
+              suggestion: "Declare an initial_state and ensure it is included in the workflow states."
+            )
+          ]
+        end
+
+        def state_reference_diagnostics
+          graph.transitions.values.flat_map do |transition|
+            [
+              undefined_state_diagnostic(transition, :from, transition.from),
+              undefined_state_diagnostic(transition, :to, transition.to)
+            ].compact
+          end
+        end
+
+        def undefined_state_diagnostic(transition, edge, state)
+          return if edge == :from && state.nil?
+          return if graph.states.include?(state)
+
+          Diagnostic.new(
+            severity: :error,
+            code: :"undefined_#{edge}_state",
+            state: state,
+            transition: transition.name,
+            message: "Transition #{ref(transition.name)} references undefined #{edge} state #{ref(state)}.",
+            suggestion: "Declare state #{ref(state)} or update transition #{ref(transition.name)}."
+          )
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Targets
+        attr_reader :transition
+
+        def self.for(transition)
+          new(transition).names
+        end
+
+        def self.router_for(transition)
+          new(transition).router_names
+        end
+
+        def initialize(transition)
+          @transition = transition
+        end
+
+        def names
+          names = [transition.success_transition, transition.failure_transition]
+          names.concat(router_names)
+          names.compact.uniq
+        end
+
+        def router_names
+          return [] unless transition.router_config
+
+          [
+            *transition.router_config.fetch(:routes).values,
+            transition.router_config.fetch(:fallback)
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class TransitionDiagnostics
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def to_a
+          graph.transitions.values.flat_map do |transition|
+            [
+              transition_target_diagnostic(transition, :success_transition, transition.success_transition),
+              transition_target_diagnostic(transition, :failure_transition, transition.failure_transition),
+              *router_target_diagnostics(transition),
+              *target_state_mismatch_diagnostics(transition)
+            ].compact
+          end
+        end
+
+        private
+
+        def transition_target_diagnostic(transition, code, target)
+          return if target.nil?
+          return if graph.transitions.key?(target)
+
+          Diagnostic.new(
+            severity: :error,
+            code: :"unresolved_#{code}",
+            transition: transition.name,
+            target: target,
+            message: "Transition #{ref(transition.name)} references missing transition #{ref(target)}.",
+            suggestion: "Declare transition #{ref(target)} or update transition #{ref(transition.name)}."
+          )
+        end
+
+        def router_target_diagnostics(transition)
+          return [] unless transition.router_config
+
+          Targets.router_for(transition).filter_map do |target|
+            transition_target_diagnostic(transition, :router_target, target)
+          end
+        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)
+          end
+        end
+
+        def mismatch_diagnostic(transition, target_name, target)
+          Diagnostic.new(
+            severity: :warning,
+            code: :target_from_state_mismatch,
+            transition: transition.name,
+            target: target_name,
+            state: transition.to,
+            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)}, " \
+                        "or remove the named route."
+          )
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class TransitionSnapshot
+        KINDS = [
+          %i[deterministic deterministic?],
+          %i[router routed?],
+          %i[nested_workflow nested?],
+          %i[optimizer optimized?],
+          %i[orchestrator orchestrated?],
+          %i[fanout fanout?],
+          %i[parallel parallel?]
+        ].freeze
+
+        attr_reader :name, :from, :to, :kind, :success_transition, :failure_transition, :routes, :fallback,
+                    :fanout_branches, :retry_policy
+
+        def self.from_transition(transition)
+          new(
+            name: transition.name,
+            from: transition.from,
+            to: transition.to,
+            kind: kind_for(transition),
+            success_transition: transition.success_transition,
+            failure_transition: transition.failure_transition,
+            routes: transition.router_config&.fetch(:routes, nil),
+            fallback: transition.router_config&.fetch(:fallback, nil),
+            fanout_branches: transition.fanout_config&.fetch(:branches, nil),
+            retry_policy: retry_policy_for(transition)
+          )
+        end
+
+        def self.retry_policy_for(transition)
+          config = transition.retry_config
+          return unless config
+
+          {
+            attempts: config.fetch(:attempts),
+            error_classes: config.fetch(:error_classes).map(&:name),
+            backoff: config.fetch(:backoff),
+            max_delay: config[:max_delay],
+            jitter: config.fetch(:jitter)
+          }.compact
+        end
+
+        def self.kind_for(transition)
+          kind = KINDS.find { |_name, predicate| transition.public_send(predicate) }
+          return kind.first if kind
+          return :agent if transition.agent_name
+
+          :noop
+        end
+
+        def initialize(**attributes)
+          @name = attributes.fetch(:name)
+          @from = attributes.fetch(:from)
+          @to = attributes.fetch(:to)
+          @kind = attributes.fetch(:kind)
+          @success_transition = attributes[:success_transition]
+          @failure_transition = attributes[:failure_transition]
+          @routes = attributes[:routes]
+          @fallback = attributes[:fallback]
+          @fanout_branches = attributes[:fanout_branches]
+          @retry_policy = attributes[:retry_policy]
+        end
+
+        def to_h
+          {
+            name: name,
+            from: from,
+            to: to,
+            kind: kind,
+            success_transition: success_transition,
+            failure_transition: failure_transition,
+            routes: routes,
+            fallback: fallback,
+            fanout_branches: fanout_branches,
+            retry_policy: retry_policy
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Validator
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def report
+          diagnostics = all_diagnostics
+
+          Report.new(
+            status: status_for(diagnostics),
+            workflow_class: graph.workflow_class.name,
+            initial_state: graph.initial_state,
+            states: graph.states,
+            transitions: graph.transition_snapshots,
+            diagnostics: diagnostics,
+            metrics: Metrics.new(graph, reachable_transition_names).to_h
+          )
+        end
+
+        private
+
+        def all_diagnostics
+          [
+            *StateDiagnostics.new(graph).to_a,
+            *TransitionDiagnostics.new(graph).to_a,
+            *ReachabilityDiagnostics.new(graph, reachable_transition_names).to_a
+          ]
+        end
+
+        def reachable_transition_names
+          @reachable_transition_names ||= Reachability.new(graph).transition_names
+        end
+
+        def status_for(diagnostics)
+          return :invalid if diagnostics.any? { |diagnostic| diagnostic.severity == :error }
+          return :warning if diagnostics.any?
+
+          :valid
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      attr_reader :workflow_class, :initial_state, :states, :transitions
+
+      def initialize(workflow_class:, initial_state:, states:, transitions:)
+        @workflow_class = workflow_class
+        @initial_state = initial_state
+        @states = Array(states).uniq.freeze
+        @transitions = transitions.dup.freeze
+      end
+
+      def validate
+        Validator.new(self).report
+      end
+
+      def transition_snapshots
+        transitions.values.map { |transition| TransitionSnapshot.from_transition(transition) }
+      end
+    end
+  end
+end
+
+require_relative "graph/reference"
+require_relative "graph/diagnostic"
+require_relative "graph/state_diagnostics"
+require_relative "graph/reachability"
+require_relative "graph/reachability_diagnostics"
+require_relative "graph/metrics"
+require_relative "graph/report"
+require_relative "graph/targets"
+require_relative "graph/transition_snapshot"
+require_relative "graph/transition_diagnostics"
+require_relative "graph/validator"

data/lib/smith/workflow/graph_dsl.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    def self.graph
+      Graph.new(
+        workflow_class: self,
+        initial_state: initial_state,
+        states: @states || [],
+        transitions: @transitions || {}
+      )
+    end
+
+    def self.validate_graph
+      graph.validate
+    end
+  end
+end

data/lib/smith/workflow/guardrail_integration.rb

@@ -6,34 +6,52 @@ module Smith
       private
 
       def apply_tool_guardrails(agent_class)
-        sources = [self.class.guardrails, agent_class&.guardrails].compact
+        sources = tool_guardrail_sources(agent_class)
         Tool.current_guardrails = sources.empty? ? nil : sources
       end
 
       def run_input_guardrails(agent_class)
+        run_workflow_input_guardrails
+        run_agent_input_guardrails(agent_class)
+      end
+
+      def run_output_guardrails(output, agent_class)
+        run_workflow_output_guardrails(output)
+        run_agent_output_guardrails(output, agent_class)
+      end
+
+      def handle_step_failure(transition, _error)
+        failure_name = transition.failure_transition
+        return unless failure_name
+
+        fail_transition = self.class.find_transition(failure_name)
+        return unless fail_transition
+
+        @state = fail_transition.to
+      end
+
+      def run_workflow_input_guardrails
         wf_guardrails = self.class.guardrails
         Guardrails::Runner.run_inputs(wf_guardrails, @context) if wf_guardrails
+      end
 
+      def run_agent_input_guardrails(agent_class)
         agent_guardrails = agent_class&.guardrails
         Guardrails::Runner.run_inputs(agent_guardrails, @context) if agent_guardrails
       end
 
-      def run_output_guardrails(output, agent_class)
+      def run_workflow_output_guardrails(output)
         wf_guardrails = self.class.guardrails
         Guardrails::Runner.run_outputs(wf_guardrails, output) if wf_guardrails
+      end
 
+      def run_agent_output_guardrails(output, agent_class)
         agent_guardrails = agent_class&.guardrails
         Guardrails::Runner.run_outputs(agent_guardrails, output) if agent_guardrails
       end
 
-      def handle_step_failure(transition, _error)
-        failure_name = transition.failure_transition
-        return unless failure_name
-
-        fail_transition = self.class.find_transition(failure_name)
-        return unless fail_transition
-
-        @state = fail_transition.to
+      def tool_guardrail_sources(agent_class)
+        [self.class.guardrails, agent_class&.guardrails].compact
       end
     end
   end

data/lib/smith/workflow/orchestrator_worker.rb

@@ -23,7 +23,8 @@ module Smith
       private
 
       def dispatch_step(transition, prepared_input: nil)
-        if transition.parallel? then execute_parallel_step(transition, prepared_input: prepared_input)
+        if transition.fanout? then execute_fanout_step(transition, prepared_input: prepared_input)
+        elsif transition.parallel? then execute_parallel_step(transition, prepared_input: prepared_input)
         elsif transition.nested? then execute_nested_workflow(transition)
         elsif transition.optimized? then execute_optimization_step(transition, prepared_input: prepared_input)
         elsif transition.orchestrated? then execute_orchestration_step(transition, prepared_input: prepared_input)

data/lib/smith/workflow/parallel/cancellation.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Parallel
+      class Cancellation < WorkflowError; end
+    end
+  end
+end

data/lib/smith/workflow/parallel.rb

@@ -39,12 +39,17 @@ module Smith
         fulfilled, values, reasons = Concurrent::Promises.zip(*futures).result
 
         unless fulfilled
-          error = reasons.compact.first
+          error = preferred_error(reasons)
           raise error
         end
 
         values
       end
+
+      def self.preferred_error(reasons)
+        errors = reasons.compact
+        errors.find { |error| !error.is_a?(Cancellation) } || errors.first
+      end
     end
   end
 end

data/lib/smith/workflow/parallel_execution.rb

@@ -50,10 +50,12 @@ module Smith
         Tool.current_ledger = ledger
         Tool.current_tool_result_collector = tool_result_collector
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
       end
 
       def teardown_branch_context(env)
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
         Tool.current_ledger = nil
         Tool.current_tool_result_collector = nil
         env.teardown_thread
@@ -68,7 +70,7 @@ module Smith
       end
 
       def check_cancellation!(signal)
-        raise Smith::WorkflowError, "cancelled" if signal.cancelled?
+        raise Parallel::Cancellation, "cancelled" if signal.cancelled?
       end
     end
   end

data/lib/smith/workflow/retry_execution.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module RetryExecution
+      private
+
+      def run_with_retry_policy(transition)
+        config = transition.retry_config
+        return run_guarded_step(transition) unless config
+
+        attempt = 0
+        begin
+          attempt += 1
+          run_guarded_step(transition)
+        rescue StandardError => e
+          raise unless retry_transition_error?(config, e, attempt)
+
+          sleep_for_retry(config, attempt)
+          retry
+        end
+      end
+
+      def retry_transition_error?(config, error, attempt)
+        return false if attempt >= config.fetch(:attempts)
+
+        classes = config.fetch(:error_classes)
+        if classes.any?
+          classes.any? { |error_class| error.is_a?(error_class) }
+        else
+          Smith::Errors.retryable?(error)
+        end
+      end
+
+      def sleep_for_retry(config, failed_attempt)
+        delay = retry_delay(config, failed_attempt)
+        sleep(delay) if delay.positive?
+      end
+
+      def retry_delay(config, failed_attempt)
+        delay = config.fetch(:backoff) * (2**[failed_attempt - 1, 0].max)
+        max_delay = config[:max_delay]
+        delay = [delay, max_delay].min if max_delay
+
+        jitter = config.fetch(:jitter)
+        delay += rand * jitter if jitter.positive?
+        delay = [delay, max_delay].min if max_delay
+        delay
+      end
+    end
+  end
+end