smith-agents 0.4.0

data/lib/smith/workflow/pipeline.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Pipeline
+      attr_reader :name, :from, :to, :stages, :failure_transition
+
+      def initialize(name, from:, to:, &)
+        raise WorkflowError, "pipeline name is required" if name.nil?
+        raise WorkflowError, "pipeline :#{name} requires from:" if from.nil?
+        raise WorkflowError, "pipeline :#{name} requires to:" if to.nil?
+
+        @name = name
+        @from = from
+        @to = to
+        @stages = []
+        @failure_transition = nil
+        instance_eval(&)
+      end
+
+      def stage(stage_name, execute:)
+        raise WorkflowError, "pipeline :#{name} stage name is required" if stage_name.nil?
+        raise WorkflowError, "pipeline :#{name} stage :#{stage_name} requires execute:" if execute.nil?
+
+        @stages << { name: stage_name, agent: execute }
+      end
+
+      def on_failure(transition_name)
+        @failure_transition = transition_name
+      end
+
+      def compile!(workflow_class)
+        validate!
+        validate_no_collisions!(workflow_class)
+        generate_transitions(workflow_class)
+      end
+
+      private
+
+      def validate!
+        raise WorkflowError, "pipeline :#{name} must declare at least one stage" if stages.empty?
+
+        seen = {}
+        stages.each do |stg|
+          raise WorkflowError, "pipeline :#{name} has duplicate stage :#{stg[:name]}" if seen[stg[:name]]
+
+          seen[stg[:name]] = true
+        end
+      end
+
+      def validate_no_collisions!(workflow_class)
+        stages.each do |stg|
+          t_name = stage_transition_name(stg)
+          next unless workflow_class.find_transition(t_name)
+
+          raise WorkflowError, "pipeline :#{name} transition :#{t_name} collides with existing transition"
+        end
+      end
+
+      def generate_transitions(workflow_class)
+        stages.each_with_index do |stg, idx|
+          declare_intermediate_state(workflow_class, idx)
+          register_stage_transition(workflow_class, stg, idx)
+        end
+      end
+
+      def declare_intermediate_state(workflow_class, idx)
+        return if idx.zero?
+
+        workflow_class.state(stage_after_state(stages[idx - 1]))
+      end
+
+      def register_stage_transition(workflow_class, stg, idx)
+        attrs = stage_attributes(stg, idx)
+
+        workflow_class.transition(attrs[:name], from: attrs[:from], to: attrs[:to]) do
+          execute attrs[:agent]
+          on_success attrs[:next] if attrs[:next]
+          on_failure attrs[:fail] if attrs[:fail]
+        end
+      end
+
+      def stage_attributes(stg, idx)
+        { name: stage_transition_name(stg), from: stage_from(idx), to: stage_to(stg, idx),
+          next: stage_next(idx), fail: failure_transition, agent: stg[:agent] }
+      end
+
+      def stage_from(idx)
+        idx.zero? ? from : stage_after_state(stages[idx - 1])
+      end
+
+      def stage_to(stg, idx)
+        idx == stages.length - 1 ? to : stage_after_state(stg)
+      end
+
+      def stage_next(idx)
+        idx < stages.length - 1 ? stage_transition_name(stages[idx + 1]) : nil
+      end
+
+      def stage_transition_name(stg)
+        :"#{name}__#{stg[:name]}"
+      end
+
+      def stage_after_state(stg)
+        :"#{name}__after_#{stg[:name]}"
+      end
+    end
+
+    module DSL
+      module ClassMethods
+        def pipeline(name, from:, to:, &)
+          Pipeline.new(name, from: from, to: to, &).compile!(self)
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/router.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+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)
+        validate_transition_exists!(transition_name, workflow_class)
+        transition_name
+      end
+
+      def self.validate!(output, config)
+        validate_structure!(output)
+        validate_confidence!(output[:confidence])
+        validate_route_key!(output[:route].to_sym, output[:confidence], config)
+      end
+
+      def self.validate_structure!(output)
+        raise WorkflowError, "router classifier output must be a Hash" unless output.is_a?(Hash)
+        raise WorkflowError, "router classifier output missing :route" unless output.key?(:route)
+        raise WorkflowError, "router classifier output missing :confidence" unless output.key?(:confidence)
+      end
+
+      def self.validate_confidence!(confidence)
+        return if confidence.is_a?(Numeric) && confidence >= 0.0 && confidence <= 1.0
+
+        raise WorkflowError, "router confidence must be a number in 0.0..1.0"
+      end
+
+      def self.validate_route_key!(route_key, confidence, config)
+        return if confidence < config[:confidence_threshold]
+        return if config[:routes].key?(route_key)
+
+        raise WorkflowError, "router route :#{route_key} not found in declared routes"
+      end
+
+      def self.select_transition(output, config)
+        if output[:confidence] >= config[:confidence_threshold]
+          config[:routes][output[:route].to_sym]
+        else
+          config[:fallback]
+        end
+      end
+
+      def self.validate_transition_exists!(transition_name, workflow_class)
+        return if workflow_class.find_transition(transition_name)
+
+        raise WorkflowError, "router selected transition :#{transition_name} which is not declared on the workflow"
+      end
+    end
+  end
+end

data/lib/smith/workflow/transition.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    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
+
+      def initialize(name, from:, to:, &)
+        @name = name
+        @from = from
+        @to = to
+        instance_eval(&) if block_given?
+      end
+
+      def execute(agent_name, **opts)
+        raise WorkflowError, "transition cannot declare both execute and compute/run" if @deterministic_block
+
+        @agent_name = agent_name
+        @agent_opts = opts
+      end
+
+      def on_success(transition_name)
+        @success_transition = transition_name
+      end
+
+      def on_failure(transition_name)
+        @failure_transition = transition_name
+      end
+
+      def route(agent_name, routes:, confidence_threshold:, fallback:)
+        raise WorkflowError, "transition cannot declare both route and compute/run" if @deterministic_block
+
+        @agent_name = agent_name
+        @router_config = { routes: routes, confidence_threshold: confidence_threshold, fallback: 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
+
+        @workflow_class = klass
+      end
+
+      def optimize(generator:, evaluator:, max_rounds:, evaluator_schema:,
+                   improvement_threshold: nil,
+                   evaluator_context: nil,
+                   before_eval: nil,
+                   on_exhaustion: :raise,
+                   on_converged: :raise,
+                   on_threshold: :raise)
+        validate_optimize_conflicts!
+        validate_optimize_controls!(generator, evaluator, max_rounds, evaluator_schema)
+        validate_optimize_exit_modes!(on_exhaustion: on_exhaustion, on_converged: on_converged,
+                                      on_threshold: on_threshold)
+        validate_optimize_evaluator_context!(evaluator_context)
+        validate_optimize_before_eval!(before_eval)
+
+        @optimization_config = {
+          generator: generator, evaluator: evaluator, max_rounds: max_rounds,
+          evaluator_schema: evaluator_schema, improvement_threshold: improvement_threshold,
+          evaluator_context: evaluator_context,
+          before_eval: before_eval,
+          on_exhaustion: on_exhaustion,
+          on_converged: on_converged,
+          on_threshold: on_threshold
+        }
+      end
+
+      def orchestrate(**opts)
+        validate_orchestrate_conflicts!
+        validate_orchestrate_controls!(opts)
+        @orchestrator_config = opts
+      end
+
+      %i[compute run].each do |method_name|
+        define_method(method_name) do |&block|
+          validate_deterministic_conflicts!
+          raise WorkflowError, "#{method_name} requires a block" unless block
+
+          @deterministic_block = block
+          @deterministic_kind = method_name
+        end
+      end
+
+      def deterministic?
+        !@deterministic_block.nil?
+      end
+
+      def orchestrated?
+        !@orchestrator_config.nil?
+      end
+
+      def optimized?
+        !@optimization_config.nil?
+      end
+
+      def nested?
+        !@workflow_class.nil?
+      end
+
+      def routed?
+        !@router_config.nil?
+      end
+
+      def parallel?
+        agent_opts&.dig(:parallel) == true
+      end
+
+      private
+
+      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
+        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
+      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
+      end
+
+      def validate_orchestrate_controls!(opts)
+        validate_orchestrate_required_fields!(opts)
+        validate_orchestrate_bounds!(opts)
+      end
+
+      def validate_orchestrate_required_fields!(opts)
+        raise WorkflowError, "orchestrate requires an orchestrator" if opts[:orchestrator].nil?
+        raise WorkflowError, "orchestrate requires a worker" if opts[:worker].nil?
+
+        validate_schema_surface!(:task_schema, opts[:task_schema])
+        validate_schema_surface!(:worker_output_schema, opts[:worker_output_schema])
+        validate_schema_surface!(:final_output_schema, opts[:final_output_schema])
+      end
+
+      def validate_schema_surface!(name, schema)
+        raise WorkflowError, "orchestrate requires a #{name}" if schema.nil?
+        return if schema.respond_to?(:required_keys)
+
+        raise WorkflowError, "orchestrate #{name} must respond to :required_keys"
+      end
+
+      def validate_orchestrate_bounds!(opts)
+        unless opts[:max_workers].is_a?(Integer) && opts[:max_workers].positive?
+          raise WorkflowError, "orchestrate max_workers must be a positive integer"
+        end
+        return if opts[:max_delegation_rounds].is_a?(Integer) && opts[:max_delegation_rounds].positive?
+
+        raise WorkflowError, "orchestrate max_delegation_rounds must be a positive integer"
+      end
+
+      def validate_optimize_controls!(generator, evaluator, max_rounds, evaluator_schema)
+        raise WorkflowError, "optimize requires a generator" if generator.nil?
+        raise WorkflowError, "optimize requires an evaluator" if evaluator.nil?
+        raise WorkflowError, "optimize requires an evaluator_schema" if evaluator_schema.nil?
+
+        return if max_rounds.is_a?(Integer) && max_rounds.positive?
+
+        raise WorkflowError, "optimize max_rounds must be a positive integer"
+      end
+
+      VALID_EXIT_MODES = [:raise, :return_last].freeze
+      private_constant :VALID_EXIT_MODES
+
+      def validate_optimize_exit_modes!(on_exhaustion:, on_converged:, on_threshold:)
+        { on_exhaustion: on_exhaustion, on_converged: on_converged, on_threshold: on_threshold }.each do |name, value|
+          next if VALID_EXIT_MODES.include?(value)
+          next if value.respond_to?(:call)
+
+          raise WorkflowError,
+                "optimize #{name} must be :raise, :return_last, or a callable; got #{value.inspect}"
+        end
+      end
+
+      def validate_optimize_evaluator_context!(evaluator_context)
+        return if evaluator_context.nil? || evaluator_context == :inject_state
+
+        raise WorkflowError,
+              "optimize evaluator_context must be nil or :inject_state; got #{evaluator_context.inspect}"
+      end
+
+      def validate_optimize_before_eval!(before_eval)
+        return if before_eval.nil?
+        return if before_eval.respond_to?(:call)
+
+        raise WorkflowError, "optimize before_eval must respond to :call; got #{before_eval.inspect}"
+      end
+    end
+  end
+end