smith-agents 0.4.5 → 0.6.0

data/lib/smith/workflow/dsl.rb

@@ -12,6 +12,12 @@ module Smith
           super
           subclass.instance_variable_set(:@states, (@states || []).dup)
           subclass.instance_variable_set(:@transitions, (@transitions || {}).dup)
+          subclass.instance_variable_set(
+            :@transitions_by_state,
+            duplicate_transition_index(@transitions_by_state)
+          )
+          subclass.instance_variable_set(:@transition_order, (@transition_order || {}).dup)
+          subclass.instance_variable_set(:@transition_sequence, @transition_sequence)
           subclass.instance_variable_set(:@initial_state_name, @initial_state_name)
           subclass.instance_variable_set(:@budget_config, @budget_config&.dup)
           subclass.instance_variable_set(:@max_transitions_count, @max_transitions_count)
@@ -29,19 +35,24 @@ module Smith
         def initial_state(name = nil)
           return @initial_state_name if name.nil?
 
-          @initial_state_name = name
-          state(name)
+          @initial_state_name = own_identifier(name)
+          state(@initial_state_name)
         end
 
         def state(name)
+          name = own_identifier(name)
           @states ||= []
           @states << name unless @states.include?(name)
           generate_fail_transition if name == :failed
         end
 
         def transition(name, from:, to:, &)
+          declared = Transition.new(name, from: from, to: to, &)
+          name = declared.name
           @transitions ||= {}
-          @transitions[name] = Transition.new(name, from: from, to: to, &)
+          remove_from_transition_index(@transitions[name]) if @transitions.key?(name)
+          @transitions[name] = declared
+          insert_into_transition_index(declared)
         end
 
         def budget(**opts)
@@ -196,13 +207,25 @@ module Smith
         end
 
         def transitions_from(state)
-          (@transitions || {}).values.select { |t| t.from == state }
+          transitions_by_state.fetch(state, []).dup
+        end
+
+        def first_transition_from(state)
+          transitions_by_state.fetch(state, []).first
+        end
+
+        def transition_from?(state)
+          transitions_by_state.fetch(state, []).any?
         end
 
         def find_transition(name)
           (@transitions || {})[name]
         end
 
+        def transition_at(index)
+          (@transitions || {}).values.fetch(index)
+        end
+
         def from_state(hash)
           workflow = allocate
           workflow.send(:restore_state, hash)
@@ -211,11 +234,56 @@ module Smith
 
         private
 
+        def own_identifier(identifier)
+          Identifier.normalize(identifier, label: "workflow identifier")
+        end
+
+        def transitions_by_state
+          @transitions_by_state ||= Hash.new { |index, state| index[state] = [] }
+        end
+
+        def transition_order
+          @transition_order ||= {}
+        end
+
+        def transition_sequence
+          @transition_sequence ||= 0
+        end
+
+        def insert_into_transition_index(transition)
+          order = transition_order_for(transition.name)
+          indexed = transitions_by_state[transition.from]
+          insertion = indexed.bsearch_index { |candidate| transition_order.fetch(candidate.name) > order }
+          indexed.insert(insertion || indexed.length, transition)
+        end
+
+        def transition_order_for(name)
+          return transition_order.fetch(name) if transition_order.key?(name)
+
+          transition_order[name] = transition_sequence
+          @transition_sequence = transition_sequence + 1
+          transition_order.fetch(name)
+        end
+
+        def duplicate_transition_index(source)
+          source.to_h.each_with_object(Hash.new { |index, state| index[state] = [] }) do |(state, transitions), copy|
+            copy[state] = transitions.dup
+          end
+        end
+
+        def remove_from_transition_index(transition)
+          return unless transition
+
+          indexed = transitions_by_state[transition.from]
+          indexed.delete(transition)
+          transitions_by_state.delete(transition.from) if indexed.empty?
+        end
+
         def generate_fail_transition
           @transitions ||= {}
           return if @transitions.key?(:fail)
 
-          @transitions[:fail] = Transition.new(:fail, from: nil, to: :failed)
+          transition(:fail, from: nil, to: :failed)
         end
       end
     end

data/lib/smith/workflow/durability.rb

@@ -164,7 +164,7 @@ module Smith
 
           klass = Object.const_get(class_name)
           state = state_name_for_payload(klass, state_name)
-          klass.transitions_from(state).empty? && next_transition.nil?
+          !klass.transition_from?(state) && next_transition.nil?
         rescue JSON::ParserError, NameError, NoMethodError
           false
         end

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -12,13 +12,13 @@ module Smith
 
       def execute_optimization_step(transition, prepared_input: nil)
         state = OptimizationState.new(transition.optimization_config, prepared_input)
-        state.generator_class = Agent::Registry.fetch!(
+        state.generator_class = resolve_registered_agent!(
           state.config[:generator],
           workflow_class: self.class,
           transition_name: transition.name,
           role: :generator
         )
-        state.evaluator_class = Agent::Registry.fetch!(
+        state.evaluator_class = resolve_registered_agent!(
           state.config[:evaluator],
           workflow_class: self.class,
           transition_name: transition.name,
@@ -143,28 +143,24 @@ module Smith
       end
 
       def invoke_with_evaluator_schema(evaluator_class, schema, input)
-        original_schema = evaluator_class.output_schema
-        evaluator_class.output_schema(schema)
-        invoke_agent_with_budget(evaluator_class, input)
-      ensure
-        evaluator_class.output_schema(original_schema)
+        invoke_agent_with_budget(evaluator_class, input, output_schema: schema)
       end
 
-      def invoke_agent_with_budget(agent_class, prepared_input)
+      def invoke_agent_with_budget(agent_class, prepared_input, output_schema: agent_class.output_schema)
         Thread.current[:smith_last_agent_result] = nil
         clear_failed_billable_attempts
         with_agent_context(agent_class) do
-          invoke_with_call_ledger(agent_class, prepared_input)
+          invoke_with_call_ledger(agent_class, prepared_input, output_schema:)
         end
       ensure
         clear_failed_billable_attempts
       end
 
-      def invoke_with_call_ledger(agent_class, prepared_input)
+      def invoke_with_call_ledger(agent_class, prepared_input, output_schema:)
         ledger = effective_call_ledger
         reserved = reserve_serial_budget(ledger, agent_budget: agent_class&.budget)
         begin
-          result = invoke_agent(agent_class, prepared_input)
+          result = invoke_agent(agent_class, prepared_input, output_schema:)
           agent_result = result.is_a?(AgentResult) ? result : nil
           reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
           reserved = nil

data/lib/smith/workflow/execution.rb

@@ -1,10 +1,18 @@
 # frozen_string_literal: true
 
 require_relative "agent_result"
+require_relative "execution_binding_resolution"
+require_relative "prepared_branch_execution"
+require_relative "step_completion"
+require_relative "step_context"
 
 module Smith
   class Workflow
     module Execution
+      include ExecutionBindingResolution
+      include PreparedBranchExecution
+      include StepCompletion
+      include StepContext
       include Agent::Lifecycle
       include NestedExecution
       include EvaluatorOptimizer
@@ -17,15 +25,12 @@ module Smith
       private
 
       def execute_step(transition)
-        setup_step_context
+        with_step_context(transition) { execute_step_body(transition) }
+      end
+
+      def execute_step_body(transition)
         output = with_scoped_artifacts { run_with_retry_policy(transition) }
-        complete_step(transition, output)
-      rescue StandardError => e
-        @outcome = nil
-        handle_step_failure(transition, e)
-        { transition: transition.name, from: transition.from, to: transition.to, error: e }
-      ensure
-        teardown_step_context
+        StepCompletion.instance_method(:complete_step).bind_call(self, transition, output)
       end
 
       def setup_step_context
@@ -34,15 +39,16 @@ module Smith
         Tool.current_tool_result_collector = tool_result_collector
       end
 
-      def teardown_step_context
-        Tool.current_guardrails = nil
-        Tool.current_deadline = nil
-        Tool.current_ledger = nil
-        Tool.current_tool_result_collector = nil
-        Smith.scoped_artifacts = nil
+      def run_guarded_step(transition)
+        return apply_composite_reduction!(transition) if @composite_reduction
+
+        @resolved_parallel_branch_count = preflight_branch_count(transition)
+        run_standard_guarded_step(transition)
+      ensure
+        @resolved_parallel_branch_count = nil
       end
 
-      def run_guarded_step(transition)
+      def run_standard_guarded_step(transition)
         return dispatch_step(transition) if transition.deterministic?
         return run_guarded_fanout_step(transition) if transition.fanout?
 
@@ -60,20 +66,10 @@ module Smith
         resolve_router_output(transition, output)
       end
 
-      def complete_step(transition, output)
-        @state = transition.to
-        @next_transition_name = @router_next_transition || transition.success_transition
-        @router_next_transition = nil
-        append_accepted_output(output)
-        emit_step_completed(transition, output)
-        { transition: transition.name, from: transition.from, to: transition.to, output: output }
-      end
+      def preflight_branch_count(transition)
+        return Parallel.validate_branch_count!(transition.fanout_config.fetch(:branches).length) if transition.fanout?
 
-      def append_accepted_output(output)
-        return unless @session_messages
-        return if output.nil?
-
-        @session_messages << { role: :assistant, content: output }
+        Parallel.resolve_branch_count(transition, @context) if transition.parallel?
       end
 
       def resolve_router_output(transition, output)
@@ -120,9 +116,11 @@ module Smith
       end
 
       def resolve_agent_class(transition)
-        return nil unless transition.agent_name
+        parallel_binding = Thread.current[:smith_parallel_agent_binding]
+        parallel_agent_class = parallel_binding&.resolve(workflow: self, transition:)
+        return parallel_agent_class if parallel_agent_class
 
-        Agent::Registry.fetch!(
+        transition.agent_name && resolve_registered_agent!(
           transition.agent_name,
           workflow_class: self.class,
           transition_name: transition.name,

data/lib/smith/workflow/execution_binding_resolution.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module ExecutionBindingResolution
+      private
+
+      def resolve_registered_agent!(name, workflow_class:, transition_name:, role:)
+        authorization = @split_step_active_execution_authorization
+        return authorization.fetch_agent!(name, workflow_class:, transition_name:, role:) if authorization
+
+        Agent::Registry.fetch!(name, workflow_class:, transition_name:, role:)
+      end
+    end
+  end
+end

data/lib/smith/workflow/execution_result_snapshot.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../errors"
+require_relative "string_snapshot"
+
+module Smith
+  class Workflow
+    class ExecutionResultSnapshot
+      MAX_DEPTH = 128
+      MAX_NODES = 100_000
+      MAX_BYTES = 4 * 1024 * 1024
+
+      extend Dry::Initializer
+
+      param :value
+      option :freeze_copy, default: proc { true }
+      option :preserved_error, default: proc {}
+
+      def call
+        reset
+        root = copy_value(value, depth: 0, preserve_error: true)
+        drain
+        @containers.each(&:freeze) if freeze_copy
+        root
+      end
+
+      private
+
+      def reset
+        @bytes = 0
+        @nodes = 0
+        @copies = {}.compare_by_identity
+        @containers = []
+        @pending = []
+      end
+
+      def drain
+        until @pending.empty?
+          source, copy, depth, preserve_error = @pending.pop
+          source.is_a?(Hash) ? copy_hash(source, copy, depth, preserve_error) : copy_array(source, copy, depth)
+        end
+      end
+
+      def copy_value(item, depth:, preserve_error: false)
+        visit!(depth)
+        return @copies.fetch(item) if @copies.key?(item)
+
+        case item
+        when Hash then prepare_container(item, {}, depth, preserve_error)
+        when Array then prepare_container(item, [], depth, false)
+        when String then copy_string(item)
+        when Float then copy_float(item)
+        when Symbol, Integer, true, false, nil then item
+        else
+          raise WorkflowError,
+                "prepared-step execution result contains unsupported mutable value #{item.class}"
+        end
+      end
+
+      def prepare_container(source, copy, depth, preserve_error)
+        @copies[source] = copy
+        @containers << copy
+        @pending << [source, copy, depth, preserve_error]
+        copy
+      end
+
+      def copy_hash(source, copy, depth, preserve_error)
+        source.each do |key, item|
+          copied_key = copy_hash_key(key, depth + 1)
+          copied_item = preserved_error?(copied_key, item, preserve_error) ? item : copy_value(item, depth: depth + 1)
+          copy[copied_key] = copied_item
+        end
+      end
+
+      def copy_hash_key(key, depth)
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise WorkflowError,
+                "prepared-step execution result contains unsupported Hash key #{key.class}"
+        end
+
+        copy_value(key, depth: depth)
+      end
+
+      def copy_array(source, copy, depth)
+        source.each { |item| copy << copy_value(item, depth: depth + 1) }
+      end
+
+      def preserved_error?(key, item, permitted)
+        permitted && key == :error && item.equal?(preserved_error)
+      end
+
+      def copy_string(string)
+        @bytes += StringSnapshot.bytesize(string)
+        raise WorkflowError, "prepared-step execution result exceeds maximum bytes #{MAX_BYTES}" if
+          @bytes > MAX_BYTES
+
+        StringSnapshot.copy(string, freeze: freeze_copy)
+      end
+
+      def copy_float(float)
+        return float if float.finite?
+
+        raise WorkflowError, "prepared-step execution result contains non-finite Float"
+      end
+
+      def visit!(depth)
+        raise WorkflowError, "prepared-step execution result exceeds maximum depth #{MAX_DEPTH}" if depth > MAX_DEPTH
+
+        @nodes += 1
+        return if @nodes <= MAX_NODES
+
+        raise WorkflowError, "prepared-step execution result exceeds maximum size #{MAX_NODES}"
+      end
+    end
+  end
+end

data/lib/smith/workflow/fanout_execution.rb

@@ -35,29 +35,32 @@ module Smith
         )
 
         branch_calls = branches.map do |branch_key, agent_name|
-          proc do |signal|
-            run_fanout_branch(branch_key, agent_name, branch_agent_classes.fetch(branch_key), env, signal)
-          end
+          PreparedBranchExecution.instance_method(:prepared_branch).bind_call(
+            self,
+            FanoutExecution.instance_method(:run_fanout_branch),
+            branch_key,
+            agent_name,
+            branch_agent_classes.fetch(branch_key),
+            env
+          )
         end
 
         Parallel.execute(branches: branch_calls)
       end
 
       def run_fanout_branch(branch_key, agent_name, agent_class, env, signal)
-        setup_fanout_branch_context(env, @ledger, agent_class)
-
-        with_agent_context(agent_class) do
-          branch_ledger = effective_call_ledger
-          reserved = reserve_fanout_branch_call(branch_ledger, env.branch_estimates[branch_key], agent_class)
-          begin
-            result = guarded_fanout_branch_call(agent_class, env, signal)
-            finalize_named_branch(branch_key, agent_name, result, branch_ledger, reserved).tap { reserved = nil }
-          ensure
-            settle_budget_on_failure(branch_ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+        with_branch_context(env, @ledger, agent_class:) do
+          with_agent_context(agent_class) do
+            branch_ledger = effective_call_ledger
+            reserved = reserve_fanout_branch_call(branch_ledger, env.branch_estimates[branch_key], agent_class)
+            begin
+              result = guarded_fanout_branch_call(agent_class, env, signal)
+              finalize_named_branch(branch_key, agent_name, result, branch_ledger, reserved).tap { reserved = nil }
+            ensure
+              settle_budget_on_failure(branch_ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+            end
           end
         end
-      ensure
-        teardown_branch_context(env)
       end
 
       def guarded_fanout_branch_call(agent_class, env, signal)
@@ -89,9 +92,7 @@ module Smith
       end
 
       def run_fanout_agent_input_guardrails(branch_agent_classes)
-        branch_agent_classes.each_value do |agent_class|
-          run_agent_input_guardrails(agent_class)
-        end
+        branch_agent_classes.each_value { |agent_class| run_agent_input_guardrails(agent_class) }
       end
 
       def fanout_branch_estimates(branches, branch_agent_classes)
@@ -109,7 +110,7 @@ module Smith
       end
 
       def resolve_fanout_agent_class(transition, agent_name)
-        Agent::Registry.fetch!(
+        resolve_registered_agent!(
           agent_name,
           workflow_class: self.class,
           transition_name: transition&.name,

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

@@ -1,21 +1,47 @@
 # frozen_string_literal: true
 
+require_relative "diagnostic_path"
+
 module Smith
   class Workflow
     class Graph
       class Diagnostic
-        attr_reader :severity, :code, :message, :state, :transition, :target, :suggestion
+        attr_reader :severity, :code, :state, :transition, :target, :suggestion
 
         def initialize(**attributes)
           @severity = attributes.fetch(:severity)
           @code = attributes.fetch(:code)
           @message = attributes.fetch(:message)
+          @path = attributes[:path]
           @state = attributes[:state]
           @transition = attributes[:transition]
           @target = attributes[:target]
           @suggestion = attributes[:suggestion]
         end
 
+        def message
+          return @message unless @path
+          return @rendered_message if defined?(@rendered_message)
+
+          @rendered_message = String.new.tap do |rendered|
+            @path.each_label { |label| rendered << "Nested workflow #{label}: " }
+            rendered << @message
+          end.freeze
+        end
+
+        def nested(label:, code:, transition:, target:)
+          self.class.new(
+            severity: severity,
+            code: code,
+            message: @message,
+            path: DiagnosticPath.new(label:, tail: @path),
+            state: state,
+            transition: transition,
+            target: target,
+            suggestion: suggestion
+          )
+        end
+
         def to_h
           {
             severity: severity,

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class DiagnosticPath
+        extend Dry::Initializer
+
+        option :label
+        option :tail, default: proc {}
+
+        def each_label
+          current = self
+          while current
+            yield current.label
+            current = current.tail
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../transition_actionability"
+
+module Smith
+  class Workflow
+    class Graph
+      class ExecutionSuccessors
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def initial_transition
+          graph.first_transition_from(graph.initial_state)
+        end
+
+        def for(transition)
+          successful_successors(transition) + failure_successors(transition)
+        end
+
+        def failure_control_marker(transition)
+          target = executable_target(transition.failure_transition, expected_state: transition.from)
+          target if target && !TransitionActionability.call(target)
+        end
+
+        private
+
+        def successful_successors(transition)
+          successful_target_names(transition).filter_map do |name|
+            executable_target(name, expected_state: transition.to)
+          end
+        end
+
+        def failure_successors(transition)
+          target = executable_target(transition.failure_transition, expected_state: transition.from)
+          return [] unless target
+          return [target] if TransitionActionability.call(target)
+
+          successor = graph.first_transition_from(target.to)
+          successor ? [successor] : []
+        end
+
+        def successful_target_names(transition)
+          return Targets.router_for(transition) if transition.routed?
+
+          names = Array(transition.deterministic_routes).dup
+          name = transition.success_transition || graph.first_transition_from(transition.to)&.name
+          names << name if name
+          names.uniq
+        end
+
+        def executable_target(name, expected_state:)
+          return if name.nil?
+
+          target = graph.transitions[name]
+          return unless target
+
+          target if target.from.nil? || target.from == expected_state
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class IdentifierProjection
+        def call(value)
+          Identifier.normalize(value, label: "graph identifier", allow_nil: true)
+        end
+      end
+    end
+  end
+end

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

@@ -23,9 +23,7 @@ module Smith
         private
 
         def terminal_states
-          graph.states.select do |state|
-            graph.transitions.values.none? { |transition| transition.from == state }
-          end
+          graph.states.select { |state| graph.transitions_from(state).empty? }
         end
       end
     end