smith-agents 0.4.1 → 0.4.3

data/lib/smith/workflow/transition.rb

@@ -5,7 +5,8 @@ module Smith
     class Transition
       attr_reader :name, :from, :to, :agent_name, :agent_opts, :success_transition, :failure_transition,
                   :router_config, :workflow_class, :optimization_config, :orchestrator_config,
-                  :deterministic_block, :deterministic_kind
+                  :fanout_config, :retry_config, :deterministic_block, :deterministic_kind,
+                  :deterministic_routes
 
       def initialize(name, from:, to:, &)
         @name = name
@@ -15,7 +16,7 @@ module Smith
       end
 
       def execute(agent_name, **opts)
-        raise WorkflowError, "transition cannot declare both execute and compute/run" if @deterministic_block
+        validate_execute_conflicts!
 
         @agent_name = agent_name
         @agent_opts = opts
@@ -30,18 +31,29 @@ module Smith
       end
 
       def route(agent_name, routes:, confidence_threshold:, fallback:)
-        raise WorkflowError, "transition cannot declare both route and compute/run" if @deterministic_block
+        validate_route_conflicts!
 
-        @agent_name = agent_name
-        @router_config = { routes: routes, confidence_threshold: confidence_threshold, fallback: fallback }
+        @agent_name = normalize_agent_name!(agent_name, "router")
+        @router_config = {
+          routes: normalize_router_routes!(routes),
+          confidence_threshold: normalize_confidence_threshold!(confidence_threshold),
+          fallback: normalize_transition_reference!(fallback, "router fallback")
+        }
       end
 
       def workflow(klass)
         raise WorkflowError, "workflow binding must be a Class" unless klass.is_a?(Class)
         raise WorkflowError, "workflow binding must be a Smith::Workflow subclass" unless klass < Workflow
-        raise WorkflowError, "transition cannot declare both workflow and execute" if @agent_name && !@router_config
-        raise WorkflowError, "transition cannot declare both workflow and route" if @router_config
-        raise WorkflowError, "transition cannot declare both workflow and compute/run" if @deterministic_block
+
+        validate_conflicts!(
+          "workflow",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
 
         @workflow_class = klass
       end
@@ -77,13 +89,33 @@ module Smith
         @orchestrator_config = opts
       end
 
+      def fan_out(branches:)
+        validate_fanout_conflicts!
+
+        @fanout_config = { branches: normalize_fanout_branches!(branches) }
+      end
+      alias fanout fan_out
+
+      def retry_on(*error_classes, attempts:, backoff: 0, max_delay: nil, jitter: 0)
+        validate_retry_controls!(error_classes, attempts:, backoff:, max_delay:, jitter:)
+
+        @retry_config = {
+          error_classes: error_classes.freeze,
+          attempts: attempts,
+          backoff: Float(backoff),
+          max_delay: max_delay.nil? ? nil : Float(max_delay),
+          jitter: Float(jitter)
+        }.freeze
+      end
+
       %i[compute run].each do |method_name|
-        define_method(method_name) do |&block|
+        define_method(method_name) do |routes: nil, &block|
           validate_deterministic_conflicts!
           raise WorkflowError, "#{method_name} requires a block" unless block
 
           @deterministic_block = block
           @deterministic_kind = method_name
+          @deterministic_routes = normalize_deterministic_routes!(routes)
         end
       end
 
@@ -95,6 +127,10 @@ module Smith
         !@orchestrator_config.nil?
       end
 
+      def fanout?
+        !@fanout_config.nil?
+      end
+
       def optimized?
         !@optimization_config.nil?
       end
@@ -113,28 +149,228 @@ module Smith
 
       private
 
+      def validate_execute_conflicts!
+        validate_conflicts!(
+          "execute",
+          [
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
+      end
+
+      def validate_route_conflicts!
+        validate_conflicts!(
+          "route",
+          [
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
+      end
+
       def validate_deterministic_conflicts!
-        raise WorkflowError, "transition cannot declare both compute/run and execute" if @agent_name && !@router_config
-        raise WorkflowError, "transition cannot declare both compute/run and route" if @router_config
-        raise WorkflowError, "transition cannot declare both compute/run and workflow" if @workflow_class
-        raise WorkflowError, "transition cannot declare both compute/run and optimize" if @optimization_config
-        raise WorkflowError, "transition cannot declare both compute/run and orchestrate" if @orchestrator_config
+        validate_conflicts!(
+          "compute/run",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["workflow", @workflow_class],
+            ["optimize", @optimization_config],
+            ["orchestrate", @orchestrator_config],
+            ["fan_out", @fanout_config]
+          ]
+        )
         raise WorkflowError, "transition cannot declare both compute and run" if @deterministic_block
       end
 
       def validate_optimize_conflicts!
-        raise WorkflowError, "transition cannot declare both optimize and execute" if @agent_name && !@router_config
-        raise WorkflowError, "transition cannot declare both optimize and route" if @router_config
-        raise WorkflowError, "transition cannot declare both optimize and workflow" if @workflow_class
-        raise WorkflowError, "transition cannot declare both optimize and compute/run" if @deterministic_block
+        validate_conflicts!(
+          "optimize",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["workflow", @workflow_class],
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
       end
 
       def validate_orchestrate_conflicts!
-        raise WorkflowError, "transition cannot declare both orchestrate and execute" if @agent_name && !@router_config
-        raise WorkflowError, "transition cannot declare both orchestrate and route" if @router_config
-        raise WorkflowError, "transition cannot declare both orchestrate and workflow" if @workflow_class
-        raise WorkflowError, "transition cannot declare both orchestrate and optimize" if @optimization_config
-        raise WorkflowError, "transition cannot declare both orchestrate and compute/run" if @deterministic_block
+        validate_conflicts!(
+          "orchestrate",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["workflow", @workflow_class],
+            ["optimize", @optimization_config],
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
+      end
+
+      def validate_fanout_conflicts!
+        validate_conflicts!(
+          "fan_out",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["workflow", @workflow_class],
+            ["optimize", @optimization_config],
+            ["orchestrate", @orchestrator_config],
+            ["compute/run", @deterministic_block]
+          ]
+        )
+      end
+
+      def validate_conflicts!(primitive, conflicts)
+        conflicts.each do |other, present|
+          raise WorkflowError, "transition cannot declare both #{primitive} and #{other}" if present
+        end
+      end
+
+      def normalize_fanout_branches!(branches)
+        raise WorkflowError, "fan_out branches must be a Hash" unless branches.is_a?(Hash)
+        raise WorkflowError, "fan_out requires at least one branch" if branches.empty?
+
+        normalized = branches.each_with_object({}) do |(branch_key, agent_name), map|
+          key = normalize_fanout_branch_key!(branch_key)
+          agent = normalize_fanout_agent_name!(agent_name, key)
+          raise WorkflowError, "fan_out branch #{key.inspect} is duplicated" if map.key?(key)
+
+          map[key] = agent
+        end
+
+        validate_distinct_fanout_agents!(normalized)
+        normalized.freeze
+      end
+
+      def normalize_agent_name!(agent_name, label)
+        value = agent_name.to_s.strip
+        raise WorkflowError, "#{label} agent must not be blank" if value.empty?
+
+        value.to_sym
+      end
+
+      def normalize_router_routes!(routes)
+        raise WorkflowError, "router routes must be a Hash" unless routes.is_a?(Hash)
+        raise WorkflowError, "router routes must not be empty" if routes.empty?
+
+        routes.each_with_object({}) do |(route_key, transition_name), map|
+          key = normalize_router_route_key!(route_key)
+          raise WorkflowError, "router route :#{key} is duplicated" if map.key?(key)
+
+          map[key] = normalize_transition_reference!(transition_name, "router route :#{key}")
+        end.freeze
+      end
+
+      def normalize_router_route_key!(route_key)
+        value = route_key.to_s.strip
+        raise WorkflowError, "router route keys must not be blank" if value.empty?
+
+        value.to_sym
+      end
+
+      def normalize_confidence_threshold!(threshold)
+        numeric = Float(threshold)
+        return numeric if numeric >= 0.0 && numeric <= 1.0
+
+        raise WorkflowError, "router confidence_threshold must be a number in 0.0..1.0"
+      rescue TypeError, ArgumentError
+        raise WorkflowError, "router confidence_threshold must be a number in 0.0..1.0"
+      end
+
+      def normalize_transition_reference!(transition_name, label)
+        case transition_name
+        when Symbol
+          raise WorkflowError, "#{label} transition must not be blank" if transition_name.to_s.empty?
+
+          transition_name
+        when String
+          value = transition_name.strip
+          raise WorkflowError, "#{label} transition must not be blank" if value.empty?
+
+          value.freeze
+        else
+          raise WorkflowError, "#{label} transition must be String or Symbol"
+        end
+      end
+
+      def normalize_fanout_branch_key!(branch_key)
+        key = branch_key.to_s.strip
+        raise WorkflowError, "fan_out branch keys must not be blank" if key.empty?
+
+        key.to_sym
+      end
+
+      def normalize_fanout_agent_name!(agent_name, branch_key)
+        value = agent_name.to_s.strip
+        raise WorkflowError, "fan_out branch #{branch_key.inspect} must declare an agent" if value.empty?
+
+        value.to_sym
+      end
+
+      def validate_distinct_fanout_agents!(branches)
+        duplicates = branches.values.tally.select { |_agent, count| count > 1 }.keys
+        return if duplicates.empty?
+
+        raise WorkflowError, "fan_out branch agents must be distinct: #{duplicates.map(&:inspect).join(", ")}"
+      end
+
+      def validate_retry_controls!(error_classes, attempts:, backoff:, max_delay:, jitter:)
+        unless attempts.is_a?(Integer) && attempts.positive?
+          raise WorkflowError, "retry_on attempts must be a positive integer"
+        end
+
+        error_classes.each do |error_class|
+          next if error_class.is_a?(Class) && error_class <= StandardError
+
+          raise WorkflowError, "retry_on error classes must inherit from StandardError"
+        end
+
+        validate_non_negative_numeric!(:backoff, backoff)
+        validate_non_negative_numeric!(:jitter, jitter)
+        validate_non_negative_numeric!(:max_delay, max_delay) unless max_delay.nil?
+      end
+
+      def normalize_deterministic_routes!(routes)
+        return nil if routes.nil?
+        raise WorkflowError, "deterministic routes must be an Array" unless routes.is_a?(Array)
+        raise WorkflowError, "deterministic routes must not be empty" if routes.empty?
+
+        routes.each_with_object([]) do |route, list|
+          name = normalize_deterministic_route!(route)
+          raise WorkflowError, "deterministic route #{name.inspect} is duplicated" if list.include?(name)
+
+          list << name
+        end.freeze
+      end
+
+      def normalize_deterministic_route!(route)
+        case route
+        when Symbol
+          raise WorkflowError, "deterministic route names must not be blank" if route.to_s.empty?
+
+          route
+        when String
+          value = route.strip
+          raise WorkflowError, "deterministic route names must not be blank" if value.empty?
+
+          value.freeze
+        else
+          raise WorkflowError, "deterministic route names must be String or Symbol"
+        end
+      end
+
+      def validate_non_negative_numeric!(name, value)
+        numeric = Float(value)
+        return if numeric >= 0.0
+
+        raise WorkflowError, "retry_on #{name} must be non-negative"
+      rescue TypeError, ArgumentError
+        raise WorkflowError, "retry_on #{name} must be numeric"
       end
 
       def validate_orchestrate_controls!(opts)
@@ -177,7 +413,7 @@ module Smith
         raise WorkflowError, "optimize max_rounds must be a positive integer"
       end
 
-      VALID_EXIT_MODES = [:raise, :return_last].freeze
+      VALID_EXIT_MODES = %i[raise return_last].freeze
       private_constant :VALID_EXIT_MODES
 
       def validate_optimize_exit_modes!(on_exhaustion:, on_converged:, on_threshold:)

data/lib/smith/workflow/usage_entry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # One row per agent provider call. `usage_id` is a UUID generated at
+    # recording time and stable across persist/restore so hosts can use it as an
+    # idempotency anchor.
+    # rubocop:disable Style/RedundantStructKeywordInit
+    UsageEntry = Struct.new(
+      :usage_id,
+      :agent_name,
+      :model,
+      :input_tokens,
+      :output_tokens,
+      :cost,
+      :attempt_kind,
+      :recorded_at,
+      keyword_init: true
+    ) do
+      def self.from_h(hash)
+        sym = hash.transform_keys(&:to_sym)
+        filtered = sym.slice(*members)
+        filtered[:agent_name] = filtered[:agent_name].to_sym if filtered[:agent_name].is_a?(String)
+        filtered[:attempt_kind] = filtered[:attempt_kind].to_sym if filtered[:attempt_kind].is_a?(String)
+        new(**filtered)
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end

data/lib/smith/workflow/worker_execution.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Smith
+  class Workflow
+    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
+  end
+end

data/lib/smith/workflow.rb

@@ -6,6 +6,11 @@ require "securerandom"
 require "set"
 require "time"
 
+require_relative "workflow/agent_result"
+require_relative "workflow/branch_env"
+require_relative "workflow/run_result"
+require_relative "workflow/usage_entry"
+
 module Smith
   class Workflow
     include DSL
@@ -21,113 +26,6 @@ module Smith
 
     DEFAULT_MAX_TRANSITIONS = 100
 
-    # `keyword_init: true` is mandatory: `build_run_result` constructs
-    # the result via keyword arguments. Plain Ruby Structs treat the
-    # kwargs hash as the first positional field, silently leaving the
-    # remaining fields nil — verified empirically. The `keyword_init`
-    # flag routes kwargs to the right fields. `usage_entries` is the
-    # 10th field, added in this slice for hadithi billing.
-    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 == :done
-      end
-
-      def failed?
-        state == :failed
-      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
-
-    # keyword_init: true so adding new fields in future schema versions
-    # remains backward-compatible: `from_response` and `from_h` can fill
-    # extra fields without breaking existing call sites that pass the
-    # historical positional args. Reading old persisted records into a
-    # newer Struct shape: from_h slices to current members (unknown keys
-    # silently dropped; missing keys default to nil).
-    AgentResult = Struct.new(
-      :content, :input_tokens, :output_tokens, :cost, :model_used,
-      keyword_init: true
-    ) do
-      def self.from_response(response, content, model_used: nil)
-        new(
-          content: content,
-          input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : nil,
-          output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : nil,
-          cost: nil,
-          model_used: model_used
-        )
-      end
-
-      def usage_known?
-        !input_tokens.nil? && !output_tokens.nil?
-      end
-    end
-
-    # One row per agent provider call. `usage_id` is a UUID generated
-    # at recording time and stable across persist/restore — hadithi
-    # uses it as the idempotency anchor on `usage_events.smith_usage_id`.
-    # Includes `to_h`/`from_h` for JSON serialization (plain Struct
-    # JSON-encodes to `"#<struct ...>"` — useless).
-    #
-    # keyword_init: true gives forward/backward compatibility:
-    # - Adding a new field: old persisted hashes restore cleanly (new
-    #   field defaults to nil).
-    # - Reading new persisted hashes with an older Smith version: from_h
-    #   slices to known members (unknown keys silently dropped).
-    UsageEntry = Struct.new(
-      :usage_id,
-      :agent_name,
-      :model,
-      :input_tokens,
-      :output_tokens,
-      :cost,
-      :attempt_kind,
-      :recorded_at,
-      keyword_init: true
-    ) do
-      def self.from_h(hash)
-        sym = hash.transform_keys(&:to_sym)
-        filtered = sym.slice(*members)
-        # Symbolize :agent_name and :attempt_kind for backward compat
-        # with callers that consume the field as Symbol.
-        filtered[:agent_name] = filtered[:agent_name].to_sym if filtered[:agent_name].is_a?(String)
-        filtered[:attempt_kind] = filtered[:attempt_kind].to_sym if filtered[:attempt_kind].is_a?(String)
-        new(**filtered)
-      end
-    end
-
     # Reconstruct Smith error classes from `@last_failed_step` snapshots.
     # Order matters: more-specific subclasses first, so a real DSF doesn't
     # get caught by the WorkflowError handler. Each lambda preserves the
@@ -167,24 +65,6 @@ module Smith
     RETRYABLE_BEARING_FAMILIES = %w[deterministic_step_failure tool_guardrail_failed].freeze
     private_constant :RETRYABLE_BEARING_FAMILIES
 
-    # keyword_init: true for forward/backward compat (see UsageEntry).
-    BranchEnv = Struct.new(
-      :prepared_input, :guardrail_sources, :scoped_store, :branch_estimates, :deadline,
-      keyword_init: true
-    ) do
-      def setup_thread
-        Smith::Tool.current_guardrails = guardrail_sources
-        Smith::Tool.current_deadline = deadline
-        Smith.scoped_artifacts = scoped_store
-      end
-
-      def teardown_thread
-        Smith::Tool.current_guardrails = nil
-        Smith::Tool.current_deadline = nil
-        Smith.scoped_artifacts = nil
-      end
-    end
-
     attr_reader :state, :last_prepared_input, :session_messages, :ledger
 
     def initialize(context: {}, ledger: nil, created_at: nil)
@@ -239,12 +119,13 @@ module Smith
     end
 
     def advance!
-      max = self.class.max_transitions || DEFAULT_MAX_TRANSITIONS
-      raise MaxTransitionsExceeded if @step_count >= max
+      ensure_transition_budget!
+      @step_work_started = false
 
       transition = resolve_transition
       return if transition.nil?
 
+      @step_work_started = true
       step_result = execute_step(transition)
       @step_count += 1
       @updated_at = Time.now.utc.iso8601
@@ -274,11 +155,11 @@ module Smith
     end
 
     def done?
-      @state == :done
+      state_named?(:done)
     end
 
     def failed?
-      @state == :failed
+      state_named?(:failed)
     end
 
     def record_persisted_key!(key)
@@ -360,17 +241,40 @@ module Smith
       true
     end
 
+    def ensure_transition_budget!
+      max = self.class.max_transitions || DEFAULT_MAX_TRANSITIONS
+      raise MaxTransitionsExceeded if @step_count >= max
+    end
+
     def resolve_transition
       if @next_transition_name
         name = @next_transition_name
         @next_transition_name = nil
-        self.class.find_transition(name) ||
+        transition = self.class.find_transition(name) ||
           raise(UnresolvedTransitionError.new(name, self.class, @state))
+        validate_transition_origin!(transition)
+        transition
       else
         self.class.transitions_from(@state).first
       end
     end
 
+    def validate_transition_origin!(transition)
+      expected = transition.from
+      return if expected.nil? || expected == @state
+
+      raise WorkflowError,
+            "transition :#{transition.name} cannot run from state :#{@state}; expected :#{expected}"
+    end
+
+    def step_work_started?
+      @step_work_started == true
+    end
+
+    def state_named?(name)
+      @state == name || @state.to_s == name.to_s
+    end
+
     def build_run_result(steps)
       # `output` derivation matches existing semantics on fresh runs
       # (last non-nil step output via `compact.first`). Terminal-restore
@@ -416,8 +320,8 @@ module Smith
         # Skip const_get for retryable-bearing families. An unknown
         # subclass with a message-only constructor would const_get
         # successfully but discard the snapshot's `retryable`/`kind`/
-        # `details` (defaults to nil), and hadithi's `retryable?`
-        # check would misclassify a retryable failure as terminal.
+        # `details` (defaults to nil), and host retry classification
+        # could misclassify a retryable failure as terminal.
         # Family fallback rebuilds the parent class with kwargs intact.
         family_fallback(snap)
       else
@@ -436,9 +340,9 @@ module Smith
       # symbols; JSON round-trip stringifies them; coerce back to
       # match fresh-run shape exactly.
       {
-        transition: snap[:transition]&.to_sym,
-        from:       snap[:from]&.to_sym,
-        to:         snap[:to]&.to_sym,
+        transition: normalize_transition_name(snap[:transition]),
+        from:       normalize_state_name(snap[:from]),
+        to:         normalize_state_name(snap[:to]),
         error:      error
       }
     end
@@ -519,7 +423,7 @@ module Smith
     # `Struct#dup` is shallow — it shares mutable string fields between
     # the original and the duplicate. Smith's existing snapshot helpers
     # (`snapshot_context`, etc.) also use this round-trip pattern; the
-    # billing-facing RunResult must not alias mutable workflow state.
+    # usage-facing RunResult must not alias mutable workflow state.
     # Same rule applies to nested-workflow rollup (see
     # `nested_execution.rb`).
     def snapshot_usage_entries

data/lib/smith.rb

@@ -224,12 +224,20 @@ require_relative "smith/context/session"
 # Agent (depends on RubyLLM::Agent)
 require_relative "smith/agent"
 require_relative "smith/agent/lifecycle"
+require_relative "smith/agent/registry_binding"
 require_relative "smith/agent/registry"
 
 # Workflow (Transition, DSL, Persistence, and Execution must load before Workflow)
 require_relative "smith/workflow/transition"
 require_relative "smith/workflow/graph"
 require_relative "smith/workflow/graph_dsl"
+require_relative "smith/workflow/run_result"
+require_relative "smith/workflow/agent_result"
+require_relative "smith/workflow/usage_entry"
+require_relative "smith/workflow/branch_env"
+require_relative "smith/workflow/optimization_state"
+require_relative "smith/workflow/orchestration_state"
+require_relative "smith/workflow/worker_execution"
 require_relative "smith/workflow/dsl"
 require_relative "smith/workflow/persistence"
 require_relative "smith/workflow/durability"
@@ -243,6 +251,8 @@ require_relative "smith/workflow/nested_execution"
 require_relative "smith/workflow/evaluator_optimizer"
 require_relative "smith/workflow/orchestrator_worker"
 require_relative "smith/workflow/parallel_execution"
+require_relative "smith/workflow/fanout_execution"
+require_relative "smith/workflow/retry_execution"
 require_relative "smith/workflow/deterministic_step"
 require_relative "smith/workflow/deterministic_execution"
 require_relative "smith/workflow/execution"
@@ -252,6 +262,8 @@ require_relative "smith/workflow/execution_frame"
 require_relative "smith/workflow/pipeline"
 require_relative "smith/workflow/router"
 require_relative "smith/workflow/parallel"
+require_relative "smith/workflow/parallel/cancellation_signal"
+require_relative "smith/workflow/parallel/cancellation"
 
 # Conditional Rails integration
 require_relative "smith/railtie" if defined?(Rails::Railtie)