smith-agents 0.4.1 → 0.4.3

data/lib/smith/workflow/guardrail_integration.rb

@@ -6,34 +6,69 @@ 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
+        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
+        end
+
+        @state = fail_transition.to
+      end
+
+      def actionable_failure_transition?(transition)
+        transition.agent_name ||
+          transition.deterministic? ||
+          transition.routed? ||
+          transition.fanout? ||
+          transition.nested? ||
+          transition.optimized? ||
+          transition.orchestrated? ||
+          transition.success_transition
+      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/nested_execution.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "usage_entry"
+
 module Smith
   class Workflow
     module NestedExecution
@@ -29,10 +31,9 @@ module Smith
       # Roll up child totals AND usage_entries BEFORE the failed-step
       # check raises. Previously the rollup only fired on child success
       # — billable agent work inside a failed child was silently
-      # dropped from the parent's totals/entries. The drift guard at
-      # the hadithi boundary wouldn't catch it (parent rollups + entries
-      # consistently undercount the same way; sum invariant still holds
-      # incorrectly). Roll up first, then re-raise, so the parent's
+      # dropped from the parent's totals/entries. Simple aggregate drift
+      # checks can miss this when parent rollups and entries undercount
+      # the same way. Roll up first, then re-raise, so the parent's
       # terminal state reflects the child's billable work even when the
       # child failed.
       def handle_child_result(child_result)

data/lib/smith/workflow/optimization_state.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    OptimizationState = Struct.new(
+      :config, :prepared_input, :candidate, :feedback, :last_score, :generator_class, :evaluator_class
+    ) do
+      def initialize(config, prepared_input)
+        super(config, prepared_input, nil, nil, nil, nil, nil)
+      end
+    end
+  end
+end

data/lib/smith/workflow/orchestration_state.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    OrchestrationState = Struct.new(
+      :config, :prepared_input, :orchestrator_class, :worker_class, :worker_results
+    ) do
+      def initialize(config, prepared_input)
+        super(config, prepared_input, nil, nil, nil)
+      end
+    end
+  end
+end

data/lib/smith/workflow/orchestrator_worker.rb

@@ -1,29 +1,18 @@
 # frozen_string_literal: true
 
 require "json"
-require "securerandom"
+
+require_relative "orchestration_state"
+require_relative "worker_execution"
 
 module Smith
   class Workflow
     module OrchestratorWorker
-      OrchestrationState = Struct.new(
-        :config, :prepared_input, :orchestrator_class, :worker_class, :worker_results
-      ) do
-        def initialize(config, prepared_input)
-          super(config, prepared_input, nil, nil, nil)
-        end
-      end
-
-      WorkerExecution = Struct.new(:execution_id, :task, :output) do
-        def self.run(worker_class, task, schema, budget_runner)
-          new(SecureRandom.uuid, task, budget_runner.call(worker_class, task, schema))
-        end
-      end
-
       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/cancellation_signal.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Parallel
+      CancellationSignal = Struct.new(:cancelled, :mutex) do
+        def initialize
+          super(false, Mutex.new)
+        end
+
+        def cancel!
+          mutex.synchronize { self.cancelled = true }
+        end
+
+        def cancelled?
+          mutex.synchronize { cancelled }
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/parallel.rb

@@ -2,26 +2,17 @@
 
 require "concurrent"
 
+require_relative "parallel/cancellation_signal"
+
 module Smith
   class Workflow
     class Parallel
-      CancellationSignal = Struct.new(:cancelled, :mutex) do
-        def initialize
-          super(false, Mutex.new)
-        end
-
-        def cancel!
-          mutex.synchronize { self.cancelled = true }
-        end
-
-        def cancelled?
-          mutex.synchronize { cancelled }
-        end
-      end
-
       def self.resolve_branch_count(transition, context)
         count = transition.agent_opts[:count]
-        count.respond_to?(:call) ? count.call(context) : (count || 1)
+        resolved = count.respond_to?(:call) ? count.call(context) : (count || 1)
+        return resolved if resolved.is_a?(Integer) && resolved.positive?
+
+        raise WorkflowError, "parallel branch count must be a positive integer"
       end
 
       def self.execute(branches:)
@@ -39,12 +30,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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "branch_env"
+
 module Smith
   class Workflow
     module ParallelExecution
@@ -50,10 +52,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 +72,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/persistence.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "usage_entry"
+
 module Smith
   class Workflow
     module Persistence
@@ -20,7 +22,7 @@ module Smith
           total_tokens: @total_tokens || 0,
           tool_results: @tool_results || [],
           outcome: snapshot_outcome,
-          # New durable fields for hadithi billing. All wrapped in
+          # Durable usage fields. All wrapped in
           # snapshot_value so non-JSON-safe runtime values (e.g.
           # custom Hash details on DeterministicStepFailure) get the
           # same deep-copy treatment as context/session_messages/etc.
@@ -163,9 +165,9 @@ module Smith
 
         h = raw.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
         {
-          transition: h[:transition]&.to_sym,
-          from: h[:from]&.to_sym,
-          to: h[:to]&.to_sym,
+          transition: normalize_transition_name(h[:transition]),
+          from: normalize_state_name(h[:from]),
+          to: normalize_state_name(h[:to]),
           error_class: h[:error_class],
           error_family: h[:error_family],
           error_message: h[:error_message],
@@ -255,7 +257,7 @@ module Smith
       end
 
       def normalize_symbol_fields!(normalized)
-        normalized[:state] = normalized[:state]&.to_sym
+        normalized[:state] = normalize_state_name(normalized[:state])
         if normalized[:outcome].is_a?(Hash) && normalized[:outcome].key?(:kind)
           normalized[:outcome][:kind] = normalized[:outcome][:kind]&.to_sym
         elsif normalized[:outcome].is_a?(Hash) && normalized[:outcome].key?("kind")
@@ -263,7 +265,36 @@ module Smith
         end
         return unless normalized.key?(:next_transition_name)
 
-        normalized[:next_transition_name] = normalized[:next_transition_name]&.to_sym
+        normalized[:next_transition_name] = normalize_transition_name(normalized[:next_transition_name])
+      end
+
+      def normalize_transition_name(value)
+        return if value.nil?
+        transition = self.class.find_transition(value)
+        return transition.name if transition
+        return value unless value.is_a?(String)
+
+        symbolized = value.to_sym
+        transition = self.class.find_transition(symbolized)
+        return transition.name if transition
+
+        symbolized
+      end
+
+      def normalize_state_name(value)
+        return if value.nil?
+        return value if declared_state?(value)
+        return value unless value.is_a?(String)
+
+        symbolized = value.to_sym
+        return symbolized if declared_state?(symbolized)
+
+        symbolized
+      end
+
+      def declared_state?(value)
+        states = self.class.instance_variable_get(:@states) || []
+        states.include?(value)
       end
 
       def normalize_nested_hashes!(normalized)

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

data/lib/smith/workflow/router.rb

@@ -4,16 +4,23 @@ module Smith
   class Workflow
     class Router
       def self.resolve(classifier_output, config, workflow_class:)
-        validate!(classifier_output, config)
-        transition_name = select_transition(classifier_output, config)
+        output = normalize_output(classifier_output)
+        validate!(output, config)
+        transition_name = select_transition(output, config)
         validate_transition_exists!(transition_name, workflow_class)
         transition_name
       end
 
+      def self.normalize_output(output)
+        return output unless output.is_a?(Hash)
+
+        output.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+      end
+
       def self.validate!(output, config)
         validate_structure!(output)
         validate_confidence!(output[:confidence])
-        validate_route_key!(output[:route].to_sym, output[:confidence], config)
+        validate_route_key!(normalize_route_key(output[:route]), output[:confidence], config)
       end
 
       def self.validate_structure!(output)
@@ -37,12 +44,16 @@ module Smith
 
       def self.select_transition(output, config)
         if output[:confidence] >= config[:confidence_threshold]
-          config[:routes][output[:route].to_sym]
+          config[:routes][normalize_route_key(output[:route])]
         else
           config[:fallback]
         end
       end
 
+      def self.normalize_route_key(route)
+        route.to_s.strip.to_sym
+      end
+
       def self.validate_transition_exists!(transition_name, workflow_class)
         return if workflow_class.find_transition(transition_name)
 

data/lib/smith/workflow/run_result.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # rubocop:disable Style/RedundantStructKeywordInit
+    RunResult = Struct.new(:state, :output, :steps, :total_cost, :total_tokens, :context, :session_messages,
+                           :tool_results, :outcome, :usage_entries, keyword_init: true) do
+      def done?
+        state_named?(:done)
+      end
+
+      def failed?
+        state_named?(:failed)
+      end
+
+      def state_named?(name)
+        state == name || state.to_s == name.to_s
+      end
+
+      def terminal_output
+        output
+      end
+
+      def outcome_kind
+        outcome&.dig(:kind)
+      end
+
+      def outcome_payload
+        outcome&.dig(:payload)
+      end
+
+      def last_error
+        steps.reverse.map { |step| step[:error] }.compact.first
+      end
+
+      def failed_transition
+        failure_detail&.fetch(:transition)
+      end
+
+      def failure_detail
+        failed_step = steps.reverse.find { |step| step[:error] }
+        return nil unless failed_step
+
+        {
+          transition: failed_step[:transition],
+          from: failed_step[:from],
+          to: failed_step[:to],
+          error: failed_step[:error]
+        }
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end