smith-agents 0.4.2 → 0.4.4

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class RuntimeReadinessReport
+        extend Dry::Initializer
+
+        option :workflow_class
+        option :topology_report
+        option :runtime_diagnostics
+        option :metrics
+
+        def ready?
+          errors.empty?
+        end
+        alias valid? ready?
+
+        def status
+          return :not_ready if errors.any?
+          return :warning if warnings.any?
+
+          :ready
+        end
+
+        def topology_status
+          topology_report.status
+        end
+
+        def diagnostics
+          topology_report.diagnostics + runtime_diagnostics
+        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,
+            topology_status: topology_status,
+            ready: ready?,
+            diagnostics: diagnostics.map(&:to_h),
+            runtime_diagnostics: runtime_diagnostics.map(&:to_h),
+            topology_diagnostics: topology_report.diagnostics.map(&:to_h),
+            suggestions: suggestions,
+            metrics: metrics,
+            graph: topology_report.to_h
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -21,6 +21,7 @@ module Smith
         def names
           names = [transition.success_transition, transition.failure_transition]
           names.concat(router_names)
+          names.concat(deterministic_route_names)
           names.compact.uniq
         end
 
@@ -32,6 +33,10 @@ module Smith
             transition.router_config.fetch(:fallback)
           ]
         end
+
+        def deterministic_route_names
+          transition.deterministic_routes || []
+        end
       end
     end
   end

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

@@ -16,6 +16,7 @@ module Smith
               transition_target_diagnostic(transition, :success_transition, transition.success_transition),
               transition_target_diagnostic(transition, :failure_transition, transition.failure_transition),
               *router_target_diagnostics(transition),
+              *deterministic_route_diagnostics(transition),
               *target_state_mismatch_diagnostics(transition)
             ].compact
           end
@@ -45,6 +46,12 @@ module Smith
           end
         end
 
+        def deterministic_route_diagnostics(transition)
+          Array(transition.deterministic_routes).filter_map do |target|
+            transition_target_diagnostic(transition, :deterministic_route, target)
+          end
+        end
+
         def target_state_mismatch_diagnostics(transition)
           Targets.for(transition).filter_map do |target_name|
             target = graph.transitions[target_name]

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

@@ -1,9 +1,17 @@
 # frozen_string_literal: true
 
+require "dry-initializer"
+
+require_relative "fanout_contract"
+require_relative "optimization_contract"
+require_relative "orchestration_contract"
+
 module Smith
   class Workflow
     class Graph
       class TransitionSnapshot
+        extend Dry::Initializer
+
         KINDS = [
           %i[deterministic deterministic?],
           %i[router routed?],
@@ -14,22 +22,64 @@ module Smith
           %i[parallel parallel?]
         ].freeze
 
-        attr_reader :name, :from, :to, :kind, :success_transition, :failure_transition, :routes, :fallback,
-                    :fanout_branches, :retry_policy
+        option :name
+        option :from
+        option :to
+        option :kind
+        option :success_transition, default: proc {}
+        option :failure_transition, default: proc {}
+        option :routes, default: proc {}
+        option :fallback, default: proc {}
+        option :deterministic_routes, default: proc {}
+        option :fanout_branches, default: proc {}
+        option :fanout, default: proc {}
+        option :optimization, default: proc {}
+        option :orchestration, default: proc {}
+        option :retry_policy, default: proc {}
+
+        def self.from_transition(transition, workflow_class: nil)
+          new(**attributes_for(transition, workflow_class: workflow_class))
+        end
 
-        def self.from_transition(transition)
-          new(
+        def self.attributes_for(transition, workflow_class:)
+          {
             name: transition.name,
             from: transition.from,
             to: transition.to,
-            kind: kind_for(transition),
+            kind: kind_for(transition)
+          }.merge(routing_attributes(transition), contract_attributes(transition, workflow_class: workflow_class))
+        end
+
+        def self.routing_attributes(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),
+            deterministic_routes: transition.deterministic_routes,
+            fanout_branches: transition.fanout_config&.fetch(:branches, nil)
+          }
+        end
+
+        def self.contract_attributes(transition, workflow_class:)
+          {
+            fanout: fanout_for(transition, workflow_class: workflow_class),
+            optimization: optimization_for(transition, workflow_class: workflow_class),
+            orchestration: orchestration_for(transition, workflow_class: workflow_class),
             retry_policy: retry_policy_for(transition)
-          )
+          }
+        end
+
+        def self.fanout_for(transition, workflow_class:)
+          FanoutContract.from_transition(transition, workflow_class: workflow_class)
+        end
+
+        def self.optimization_for(transition, workflow_class:)
+          OptimizationContract.from_transition(transition, workflow_class: workflow_class)
+        end
+
+        def self.orchestration_for(transition, workflow_class:)
+          OrchestrationContract.from_transition(transition, workflow_class: workflow_class)
         end
 
         def self.retry_policy_for(transition)
@@ -53,19 +103,6 @@ module Smith
           :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,
@@ -76,7 +113,11 @@ module Smith
             failure_transition: failure_transition,
             routes: routes,
             fallback: fallback,
+            deterministic_routes: deterministic_routes,
             fanout_branches: fanout_branches,
+            fanout: fanout,
+            optimization: optimization,
+            orchestration: orchestration,
             retry_policy: retry_policy
           }.compact
         end

data/lib/smith/workflow/graph.rb

@@ -16,8 +16,14 @@ module Smith
         Validator.new(self).report
       end
 
+      def runtime_readiness(visited: nil)
+        RuntimeReadiness.new(self, visited: visited).report
+      end
+
       def transition_snapshots
-        transitions.values.map { |transition| TransitionSnapshot.from_transition(transition) }
+        transitions.values.map do |transition|
+          TransitionSnapshot.from_transition(transition, workflow_class: workflow_class)
+        end
       end
     end
   end
@@ -29,8 +35,17 @@ require_relative "graph/state_diagnostics"
 require_relative "graph/reachability"
 require_relative "graph/reachability_diagnostics"
 require_relative "graph/metrics"
+require_relative "graph/nested_readiness_diagnostics"
 require_relative "graph/report"
+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/transition_diagnostics"
 require_relative "graph/validator"
+require_relative "graph/runtime_readiness"

data/lib/smith/workflow/graph_dsl.rb

@@ -14,5 +14,9 @@ module Smith
     def self.validate_graph
       graph.validate
     end
+
+    def self.runtime_readiness
+      graph.runtime_readiness
+    end
   end
 end

data/lib/smith/workflow/guardrail_integration.rb

@@ -20,16 +20,33 @@ module Smith
         run_agent_output_guardrails(output, agent_class)
       end
 
-      def handle_step_failure(transition, _error)
+      def handle_step_failure(transition, error)
         failure_name = transition.failure_transition
-        return unless failure_name
+        raise error unless failure_name
 
         fail_transition = self.class.find_transition(failure_name)
-        return unless fail_transition
+        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

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,25 +1,13 @@
 # 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)

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:)

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

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/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