smith-agents 0.4.1 → 0.4.3

data/lib/smith/workflow/fanout_execution.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "branch_env"
+
+module Smith
+  class Workflow
+    module FanoutExecution
+      private
+
+      def run_guarded_fanout_step(transition)
+        branches = transition.fanout_config.fetch(:branches)
+        branch_agent_classes = fanout_agent_classes(transition, branches)
+        run_workflow_input_guardrails
+        run_fanout_agent_input_guardrails(branch_agent_classes)
+        prepared_input = build_session&.prepare!
+        output = execute_fanout_step(
+          transition,
+          branches: branches,
+          branch_agent_classes: branch_agent_classes,
+          prepared_input: prepared_input
+        )
+        run_workflow_output_guardrails(output)
+        output
+      end
+
+      def execute_fanout_step(transition, branches: nil, branch_agent_classes: nil, prepared_input: nil)
+        branches ||= transition.fanout_config.fetch(:branches)
+        branch_agent_classes ||= fanout_agent_classes(transition, branches)
+        env = BranchEnv.new(
+          prepared_input: prepared_input,
+          guardrail_sources: nil,
+          scoped_store: propagate_scoped_artifacts,
+          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
+          deadline: wall_clock_deadline
+        )
+
+        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
+        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
+          end
+        end
+      ensure
+        teardown_branch_context(env)
+      end
+
+      def guarded_fanout_branch_call(agent_class, env, signal)
+        check_cancellation!(signal)
+        check_deadline!
+        result = agent_class.model_configured? ? invoke_agent(agent_class, env.prepared_input) : nil
+        output = result.is_a?(AgentResult) ? result.content : result
+        validate_data_volume!(output, agent_class)
+        run_agent_output_guardrails(output, agent_class)
+        check_cancellation!(signal)
+        result
+      end
+
+      def setup_fanout_branch_context(env, ledger, agent_class)
+        setup_branch_context(env, ledger)
+        apply_tool_guardrails(agent_class)
+      end
+
+      def reserve_fanout_branch_call(branch_ledger, branch_estimates, agent_class)
+        return reserve_branch_budget(branch_ledger, branch_estimates: branch_estimates) if @ledger
+
+        reserve_serial_budget(branch_ledger, agent_budget: agent_class&.budget) if branch_ledger
+      end
+
+      def fanout_agent_classes(transition, branches)
+        branches.to_h do |branch_key, agent_name|
+          [branch_key, resolve_fanout_agent_class(transition, agent_name)]
+        end
+      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
+      end
+
+      def fanout_branch_estimates(branches, branch_agent_classes)
+        return {} unless @ledger
+
+        branch_count = branches.length
+        branches.each_with_object({}) do |(branch_key, _agent_name), map|
+          agent_class = branch_agent_classes.fetch(branch_key)
+          map[branch_key] = compute_branch_estimates(
+            @ledger,
+            branch_count: branch_count,
+            agent_budget: agent_class&.budget
+          )
+        end
+      end
+
+      def resolve_fanout_agent_class(transition, agent_name)
+        Agent::Registry.fetch!(
+          agent_name,
+          workflow_class: self.class,
+          transition_name: transition&.name,
+          role: :fanout_agent
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      module ContractHelpers
+        private
+
+        def label_for(value)
+          label = if value.respond_to?(:name) && value.name && !value.name.empty?
+                    value.name
+                  elsif value.respond_to?(:inspect)
+                    value.inspect
+                  else
+                    value.to_s
+                  end
+
+          immutable_value(label)
+        end
+
+        def idempotency_mode
+          return :unknown unless workflow_class.respond_to?(:idempotency_mode)
+
+          workflow_class.idempotency_mode
+        end
+
+        def in_flight_resume
+          return :blocked_by_step_in_progress if idempotency_mode == :strict
+          return :unknown unless %i[strict lax].include?(idempotency_mode)
+
+          :reruns_transition
+        end
+
+        def immutable_value(value)
+          return value if immediate_value?(value)
+
+          duplicate = value.dup
+          return value if duplicate.equal?(value)
+
+          duplicate.freeze
+        rescue TypeError
+          value
+        end
+
+        def immediate_value?(value)
+          value.nil? || value.is_a?(Symbol) || value.is_a?(Numeric) ||
+            value == true || value == false
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each_value { |nested| deep_freeze(nested) }
+            value.freeze
+          when Array
+            value.each { |nested| deep_freeze(nested) }
+            value.freeze
+          end
+
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class FanoutContract
+        attr_reader :transition, :workflow_class
+
+        def self.from_transition(transition, workflow_class: nil)
+          branches = transition.fanout_config&.fetch(:branches, nil)
+          return unless branches
+
+          new(transition, workflow_class: workflow_class).to_h
+        end
+
+        def initialize(transition, workflow_class: nil)
+          @transition = transition
+          @workflow_class = workflow_class
+        end
+
+        def to_h
+          deep_freeze(
+            branch_count: branches.length,
+            join_state: immutable_value(transition.to),
+            output_shape: :named_branch_results,
+            branch_order: :declaration_order,
+            join: join_contract,
+            output_contract: output_contract,
+            resume_contract: resume_contract,
+            branches: branch_summaries,
+            branch_contracts: branch_contracts
+          )
+        end
+
+        private
+
+        def branches
+          transition.fanout_config.fetch(:branches)
+        end
+
+        def join_contract
+          {
+            state: immutable_value(transition.to),
+            transition: immutable_value(transition.name)
+          }
+        end
+
+        def output_contract
+          {
+            collection: :array,
+            item_shape: :named_branch_result,
+            ordering: :branch_declaration_order,
+            branch_key_field: :branch,
+            agent_field: :agent,
+            output_field: :output,
+            failure: :discard_all_branch_results_on_failure
+          }
+        end
+
+        def resume_contract
+          {
+            granularity: :transition,
+            branch_checkpointing: false,
+            idempotency_mode: idempotency_mode,
+            in_flight_resume: in_flight_resume
+          }
+        end
+
+        def branch_summaries
+          branches.map do |branch, agent|
+            { branch: immutable_value(branch), agent: immutable_value(agent) }
+          end
+        end
+
+        def branch_contracts
+          branches.map do |branch, agent|
+            branch_value = immutable_value(branch)
+            agent_value = immutable_value(agent)
+
+            {
+              branch: branch_value,
+              agent: agent_value,
+              result_branch_value: branch_value,
+              result_shape: {
+                branch: branch_value,
+                agent: agent_value,
+                output: :agent_output
+              }
+            }
+          end
+        end
+
+        def immutable_value(value)
+          return value if immediate_value?(value)
+
+          duplicate = value.dup
+          return value if duplicate.equal?(value)
+
+          duplicate.freeze
+        rescue TypeError
+          # Some host-owned topology values intentionally refuse duplication.
+          # Leave them untouched; the graph contract containers are still
+          # frozen, and inspection must never mutate workflow-owned values.
+          value
+        end
+
+        def immediate_value?(value)
+          value.nil? || value.is_a?(Symbol) || value.is_a?(Numeric) ||
+            value == true || value == false
+        end
+
+        def idempotency_mode
+          return :unknown unless workflow_class&.respond_to?(:idempotency_mode)
+
+          workflow_class.idempotency_mode
+        end
+
+        def in_flight_resume
+          return :blocked_by_step_in_progress if idempotency_mode == :strict
+          return :unknown unless %i[strict lax].include?(idempotency_mode)
+
+          :reruns_transition
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each_value { |nested| deep_freeze(nested) }
+            value.freeze
+          when Array
+            value.each { |nested| deep_freeze(nested) }
+            value.freeze
+          end
+
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class NestedReadinessDiagnostics
+        extend Dry::Initializer
+
+        param :graph
+        option :visited, default: proc {}
+
+        def to_a
+          cycle_diagnostics + report_entries.flat_map { |entry| diagnostics_for(entry) }
+        end
+
+        def child_reports
+          report_entries.map { |entry| entry.fetch(:report) }
+        end
+
+        private
+
+        def diagnostics_for(entry)
+          entry.fetch(:report).diagnostics.map do |diagnostic|
+            nested_diagnostic(entry.fetch(:transition), entry.fetch(:workflow_class), diagnostic)
+          end
+        end
+
+        def cycle_diagnostics
+          nested_workflow_transitions.filter_map do |transition|
+            workflow_class = transition.workflow_class
+            cycle_diagnostic(transition, workflow_class) if visited_workflows.include?(workflow_class)
+          end
+        end
+
+        def report_entries
+          @report_entries ||= nested_workflow_transitions.filter_map do |transition|
+            workflow_class = transition.workflow_class
+            next if visited_workflows.include?(workflow_class)
+
+            {
+              transition: transition,
+              workflow_class: workflow_class,
+              report: workflow_class.graph.runtime_readiness(visited: visited_workflows)
+            }.freeze
+          end.freeze
+        end
+
+        def nested_workflow_transitions
+          @nested_workflow_transitions ||= graph.transitions.values.select(&:nested?)
+        end
+
+        def cycle_diagnostic(transition, workflow_class)
+          label = workflow_label(workflow_class)
+
+          Diagnostic.new(
+            severity: :error,
+            code: :nested_workflow_cycle,
+            transition: transition.name,
+            target: label,
+            message: "Transition #{ref(transition.name)} nests #{label}, " \
+                     "which is already in the readiness inspection stack.",
+            suggestion: "Break the nested workflow cycle before runtime execution."
+          )
+        end
+
+        def nested_diagnostic(transition, workflow_class, diagnostic)
+          label = workflow_label(workflow_class)
+
+          Diagnostic.new(
+            severity: diagnostic.severity,
+            code: :"nested_#{diagnostic.code}",
+            transition: transition.name,
+            target: label,
+            message: "Nested workflow #{label}: #{diagnostic.message}",
+            suggestion: diagnostic.suggestion
+          )
+        end
+
+        def visited_workflows
+          @visited_workflows ||= Set.new(Array(visited)).add(graph.workflow_class)
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+
+        def workflow_label(workflow_class)
+          name = workflow_class.name
+          return name if name && !name.empty?
+
+          workflow_class.inspect
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "contract_helpers"
+
+module Smith
+  class Workflow
+    class Graph
+      class OptimizationContract
+        extend Dry::Initializer
+        include ContractHelpers
+
+        param :transition
+        option :workflow_class, default: proc {}
+
+        def self.from_transition(transition, workflow_class: nil)
+          new(transition, workflow_class: workflow_class).to_h if transition.optimization_config
+        end
+
+        def to_h
+          deep_freeze(
+            transition_contract.merge(
+              exit_modes: exit_modes,
+              output_contract: output_contract,
+              resume_contract: resume_contract
+            ).compact
+          )
+        end
+
+        private
+
+        def config
+          transition.optimization_config
+        end
+
+        def transition_contract
+          {
+            generator: immutable_value(config.fetch(:generator)),
+            evaluator: immutable_value(config.fetch(:evaluator)),
+            max_rounds: config.fetch(:max_rounds)
+          }.merge(evaluation_contract)
+        end
+
+        def evaluation_contract
+          {
+            evaluator_schema: label_for(config.fetch(:evaluator_schema)),
+            evaluator_context: config[:evaluator_context],
+            improvement_threshold: config[:improvement_threshold],
+            before_eval: callable_label(config[:before_eval])
+          }
+        end
+
+        def exit_modes
+          {
+            exhaustion: exit_mode_label(config.fetch(:on_exhaustion)),
+            converged: exit_mode_label(config.fetch(:on_converged)),
+            threshold: exit_mode_label(config.fetch(:on_threshold))
+          }
+        end
+
+        def output_contract
+          {
+            success: :accepted_or_configured_exit_candidate,
+            failure: :workflow_error_on_malformed_or_unaccepted_evaluation,
+            evaluator_output: {
+              required: { accept: :boolean },
+              rejection_requires: %i[feedback],
+              threshold_requires: %i[score],
+              optional: %i[score converged]
+            }
+          }
+        end
+
+        def resume_contract
+          {
+            granularity: :transition,
+            round_checkpointing: false,
+            idempotency_mode: idempotency_mode,
+            in_flight_resume: in_flight_resume
+          }
+        end
+
+        def exit_mode_label(value)
+          return value if value.is_a?(Symbol)
+
+          callable_label(value)
+        end
+
+        def callable_label(value)
+          value.respond_to?(:call) ? :callable : nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "contract_helpers"
+
+module Smith
+  class Workflow
+    class Graph
+      class OrchestrationContract
+        extend Dry::Initializer
+        include ContractHelpers
+
+        param :transition
+        option :workflow_class, default: proc {}
+
+        def self.from_transition(transition, workflow_class: nil)
+          new(transition, workflow_class: workflow_class).to_h if transition.orchestrator_config
+        end
+
+        def to_h
+          deep_freeze(
+            transition_contract.merge(
+              decision_contract: decision_contract,
+              output_contract: output_contract,
+              resume_contract: resume_contract
+            )
+          )
+        end
+
+        private
+
+        def config
+          transition.orchestrator_config
+        end
+
+        def transition_contract
+          {
+            orchestrator: immutable_value(config.fetch(:orchestrator)),
+            worker: immutable_value(config.fetch(:worker)),
+            max_workers: config.fetch(:max_workers),
+            max_delegation_rounds: config.fetch(:max_delegation_rounds),
+            worker_dispatch: :serial
+          }.merge(schema_contract)
+        end
+
+        def schema_contract
+          {
+            task_schema: label_for(config.fetch(:task_schema)),
+            worker_output_schema: label_for(config.fetch(:worker_output_schema)),
+            final_output_schema: label_for(config.fetch(:final_output_schema))
+          }
+        end
+
+        def decision_contract
+          {
+            shape: :hash,
+            exactly_one_of: %i[tasks final stop],
+            tasks_limit: config.fetch(:max_workers)
+          }
+        end
+
+        def output_contract
+          {
+            success: :final_output_schema,
+            worker_result_shape: :execution_id_task_output,
+            failure: :workflow_error_on_stop_exhaustion_or_schema_violation
+          }
+        end
+
+        def resume_contract
+          {
+            granularity: :transition,
+            round_checkpointing: false,
+            worker_checkpointing: false,
+            idempotency_mode: idempotency_mode,
+            in_flight_resume: in_flight_resume
+          }
+        end
+      end
+    end
+  end
+end