smith-agents 0.4.2 → 0.4.4

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

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class RuntimeBindingDiagnosticBuilder
+        extend Dry::Initializer
+
+        param :graph
+        option :binding
+
+        def to_diagnostic
+          registry_binding = Agent::Registry.binding_for(agent)
+          return unresolved_agent_diagnostic unless registry_binding
+
+          if registry_binding.fetch(:agent_class).nil?
+            return uninspectable_agent_diagnostic(registry_binding) if registry_binding.fetch(:call)
+
+            return invalid_agent_diagnostic(registry_binding.fetch(:raw_binding))
+          end
+
+          agent_class = registry_binding.fetch(:agent_class)
+          return if agent_class.model_configured?
+          return required_model_diagnostic if model_required?
+
+          model_warning
+        end
+
+        private
+
+        def unresolved_agent_diagnostic
+          Diagnostic.new(
+            severity: :error,
+            code: :unresolved_agent_binding,
+            transition: transition.name,
+            target: agent,
+            message: "Transition #{ref(transition.name)} references unregistered #{role} #{ref(agent)}.",
+            suggestion: "Load and register agent #{ref(agent)} before running workflow #{workflow_label}."
+          )
+        end
+
+        def invalid_agent_diagnostic(raw_binding)
+          Diagnostic.new(
+            severity: :error,
+            code: :invalid_agent_binding,
+            transition: transition.name,
+            target: agent,
+            message: "Transition #{ref(transition.name)} references #{role} #{ref(agent)}, " \
+                     "but the registry binding is not a Smith::Agent subclass.",
+            suggestion: "Register #{ref(agent)} as a Smith::Agent subclass instead of " \
+                        "#{raw_binding.class}."
+          )
+        end
+
+        def uninspectable_agent_diagnostic(registry_binding)
+          Diagnostic.new(
+            severity: model_required? ? :error : :warning,
+            code: :uninspectable_agent_binding,
+            transition: transition.name,
+            target: agent,
+            message: "Transition #{ref(transition.name)} references #{role} #{ref(agent)}, " \
+                     "but the registry binding is lazy and cannot be inspected without resolving it.",
+            suggestion: "Register #{ref(registry_binding.fetch(:key))} as a concrete Smith::Agent subclass " \
+                        "before relying on static runtime readiness."
+          )
+        end
+
+        def required_model_diagnostic
+          Diagnostic.new(
+            severity: :error,
+            code: :agent_without_required_model,
+            transition: transition.name,
+            target: agent,
+            message: "Transition #{ref(transition.name)} references #{role} #{ref(agent)}, " \
+                     "but that role requires model output at runtime.",
+            suggestion: "Configure a model for agent #{ref(agent)} or move this transition to a " \
+                        "deterministic/nested workflow pattern."
+          )
+        end
+
+        def model_warning
+          Diagnostic.new(
+            severity: :warning,
+            code: :agent_without_model,
+            transition: transition.name,
+            target: agent,
+            message: "Transition #{ref(transition.name)} references #{role} #{ref(agent)}, " \
+                     "but the registered agent has no model configured.",
+            suggestion: "Configure a model for agent #{ref(agent)} if this transition should call a provider."
+          )
+        end
+
+        def agent
+          binding.fetch(:agent)
+        end
+
+        def transition
+          binding.fetch(:transition)
+        end
+
+        def role
+          binding.fetch(:role)
+        end
+
+        def model_required?
+          binding.fetch(:requires_model)
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+
+        def workflow_label
+          name = graph.workflow_class.name
+          return name if name && !name.empty?
+
+          graph.workflow_class.inspect
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class RuntimeBindingDiagnostics
+        extend Dry::Initializer
+
+        param :graph
+
+        def to_a
+          agent_bindings.filter_map do |binding|
+            RuntimeBindingDiagnosticBuilder.new(graph, binding: binding).to_diagnostic
+          end
+        end
+
+        def agent_bindings
+          @agent_bindings ||= graph.transitions.values.flat_map do |transition|
+            bindings_for_transition(transition)
+          end
+        end
+
+        private
+
+        def bindings_for_transition(transition)
+          [
+            primary_agent_binding(transition),
+            *optimizer_agent_bindings(transition),
+            *orchestrator_agent_bindings(transition),
+            *fanout_agent_bindings(transition)
+          ].compact
+        end
+
+        def primary_agent_binding(transition)
+          return unless transition.agent_name
+
+          {
+            transition: transition,
+            role: agent_role_for(transition),
+            agent: transition.agent_name,
+            requires_model: transition.routed?
+          }
+        end
+
+        def optimizer_agent_bindings(transition)
+          config = transition.optimization_config
+          return [] unless config
+
+          [
+            {
+              transition: transition,
+              role: "optimizer generator",
+              agent: config.fetch(:generator),
+              requires_model: true
+            },
+            {
+              transition: transition,
+              role: "optimizer evaluator",
+              agent: config.fetch(:evaluator),
+              requires_model: true
+            }
+          ]
+        end
+
+        def orchestrator_agent_bindings(transition)
+          config = transition.orchestrator_config
+          return [] unless config
+
+          [
+            {
+              transition: transition,
+              role: "orchestrator",
+              agent: config.fetch(:orchestrator),
+              requires_model: true
+            },
+            {
+              transition: transition,
+              role: "worker",
+              agent: config.fetch(:worker),
+              requires_model: true
+            }
+          ]
+        end
+
+        def fanout_agent_bindings(transition)
+          branches = transition.fanout_config&.fetch(:branches, nil)
+          return [] unless branches
+
+          branches.map do |branch, agent|
+            {
+              transition: transition,
+              role: "fan-out branch #{ref(branch)}",
+              agent: agent,
+              requires_model: false
+            }
+          end
+        end
+
+        def agent_role_for(transition)
+          return "router agent" if transition.routed?
+          return "parallel agent" if transition.parallel?
+
+          "agent"
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class RuntimeReadiness
+        extend Dry::Initializer
+
+        param :graph
+        option :visited, default: proc {}
+
+        def report
+          RuntimeReadinessReport.new(
+            workflow_class: workflow_label(graph.workflow_class),
+            topology_report: topology_report,
+            runtime_diagnostics: runtime_diagnostics,
+            metrics: runtime_metrics
+          )
+        end
+
+        private
+
+        def topology_report
+          @topology_report ||= graph.validate
+        end
+
+        def runtime_diagnostics
+          @runtime_diagnostics ||= [
+            *binding_diagnostics.to_a,
+            *nested_diagnostics.to_a
+          ]
+        end
+
+        def binding_diagnostics
+          @binding_diagnostics ||= RuntimeBindingDiagnostics.new(graph)
+        end
+
+        def nested_diagnostics
+          @nested_diagnostics ||= NestedReadinessDiagnostics.new(graph, visited: visited)
+        end
+
+        def runtime_metrics
+          RuntimeReadinessMetrics.new(
+            graph,
+            topology_report: topology_report,
+            runtime_diagnostics: runtime_diagnostics,
+            agent_bindings: binding_diagnostics.agent_bindings,
+            nested_reports: nested_diagnostics.child_reports
+          ).to_h
+        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/runtime_readiness_metrics.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class RuntimeReadinessMetrics
+        extend Dry::Initializer
+
+        param :graph
+        option :topology_report
+        option :runtime_diagnostics
+        option :agent_bindings
+        option :nested_reports, default: proc { [] }
+
+        def to_h
+          core_metrics.merge(
+            binding_metrics,
+            nested_workflow_metrics,
+            fanout_metrics
+          )
+        end
+
+        private
+
+        def core_metrics
+          {
+            topology_status: topology_report.status,
+            unresolved_agent_bindings_count: diagnostic_count(:unresolved_agent_binding),
+            invalid_agent_bindings_count: diagnostic_count(:invalid_agent_binding),
+            uninspectable_agent_bindings_count: diagnostic_count(:uninspectable_agent_binding),
+            modelless_agent_bindings_count: diagnostic_count(:agent_without_model),
+            required_model_missing_count: diagnostic_count(:agent_without_required_model)
+          }
+        end
+
+        def binding_metrics
+          {
+            direct_agent_bindings_count: agent_bindings.length,
+            agent_bindings_count: agent_bindings.length + nested_metric_sum(:agent_bindings_count)
+          }
+        end
+
+        def nested_workflow_metrics
+          {
+            direct_nested_workflow_count: direct_nested_workflow_count,
+            nested_workflow_count: direct_nested_workflow_count + nested_metric_sum(:nested_workflow_count)
+          }
+        end
+
+        def fanout_metrics
+          {
+            direct_fanout_groups_count: fanout_transitions.length,
+            fanout_groups_count: fanout_transitions.length + nested_metric_sum(:fanout_groups_count),
+            direct_fanout_branches_count: fanout_branch_count,
+            fanout_branches_count: fanout_branch_count + nested_metric_sum(:fanout_branches_count)
+          }
+        end
+
+        def nested_metric_sum(key)
+          nested_reports.sum { |report| report.metrics.fetch(key, 0) }
+        end
+
+        def diagnostic_count(code)
+          runtime_diagnostics.count do |diagnostic|
+            diagnostic.code.to_s.end_with?(code.to_s)
+          end
+        end
+
+        def fanout_branch_count
+          fanout_transitions.sum do |transition|
+            transition.fanout_config.fetch(:branches).length
+          end
+        end
+
+        def fanout_transitions
+          @fanout_transitions ||= graph.transitions.values.select(&:fanout?)
+        end
+
+        def direct_nested_workflow_count
+          graph.transitions.values.count(&:nested?)
+        end
+      end
+    end
+  end
+end