smith-agents 0.4.1 → 0.4.3

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

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,31 +1,98 @@
 # 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?],
           %i[nested_workflow nested?],
           %i[optimizer optimized?],
           %i[orchestrator orchestrated?],
+          %i[fanout fanout?],
           %i[parallel parallel?]
         ].freeze
 
-        attr_reader :name, :from, :to, :kind, :success_transition, :failure_transition, :routes, :fallback
+        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)
-          new(
+        def self.from_transition(transition, workflow_class: nil)
+          new(**attributes_for(transition, workflow_class: workflow_class))
+        end
+
+        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)
-          )
+            fallback: transition.router_config&.fetch(:fallback, 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)
+          config = transition.retry_config
+          return unless config
+
+          {
+            attempts: config.fetch(:attempts),
+            error_classes: config.fetch(:error_classes).map(&:name),
+            backoff: config.fetch(:backoff),
+            max_delay: config[:max_delay],
+            jitter: config.fetch(:jitter)
+          }.compact
         end
 
         def self.kind_for(transition)
@@ -36,17 +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]
-        end
-
         def to_h
           {
             name: name,
@@ -56,7 +112,13 @@ module Smith
             success_transition: success_transition,
             failure_transition: failure_transition,
             routes: routes,
-            fallback: fallback
+            fallback: fallback,
+            deterministic_routes: deterministic_routes,
+            fanout_branches: fanout_branches,
+            fanout: fanout,
+            optimization: optimization,
+            orchestration: orchestration,
+            retry_policy: retry_policy
           }.compact
         end
       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