smith-agents 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6e0cbabc0bd3db4447206b0326a96996b5b3a6b46ec82e0533298f4074b0659
-  data.tar.gz: 1e4f9346f46675db971627676f5d85621120d3387e95fab5258ef5de88f22939
+  metadata.gz: fce22e9b87caf5c01417a5e7d8fe7a6f4ee179abebc61644074400452a078791
+  data.tar.gz: e7d2ae59746ff545f5d45215bcec20dea95ee82a37d7fa765c4ded95484d4029
 SHA512:
-  metadata.gz: c91ea9dfb9d21c284278a46a12380b94aba48091370a9db358ea2a5ddb96a21b1a18a453d6d0b431f2839a153a20e5d93bd9a611573f93c99efb59b9e48a21dd
-  data.tar.gz: f75d0d058c722e640c1299cb62beaafb7a3051f13d786460b289187a7c4a15c5e32aa2f2f5d8b68369d5b5d1b8d6e479147bbf2beb668a2273e740ef7a21f882
+  metadata.gz: 8d8515c459487f57c20301581e6f1d5cc786f8bfe7089b4e628548145ac56e0c9c93e9560ac37f1fa7818f95a71a1c8753cb275267b341fb39ca4bf63d5e5f3e
+  data.tar.gz: b3e05ca16fc7fec62e8172d9d6ccb84b0bc3f7546af22b9f47c8a36ce4b7e6e5bfb35b0fb47eb51c0b86cf4ab4fbe47e651406c1666fcc63d4b2c16b0ccb0bf9

data/CHANGELOG.md

@@ -8,6 +8,22 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 No unreleased changes.
 
+## [0.4.1] - 2026-06-28
+
+Patch release for static workflow graph inspection. This is additive and diagnostic-only: Smith exposes declared workflow topology for hosts to render, lint, or cache without executing agents, advancing state, owning progress projection, or changing durability/recovery boundaries.
+
+### Added
+
+- `Smith::Workflow.graph` — returns a read-only inspection object for a workflow class.
+- `Smith::Workflow.validate_graph` — returns a structured report with validity status, diagnostics, suggestions, transition snapshots, and graph metrics.
+- Pre-runtime graph diagnostics for missing initial states, undefined transition states, unresolved `on_success` / `on_failure` targets, unresolved router route/fallback targets, target-state mismatch warnings, and unreachable-transition warnings.
+- Transition snapshots that preserve declared names exactly and expose `name`, `from`, `to`, `kind`, success/failure targets, router routes, and router fallback.
+
+### Test coverage
+
+- Default suite: 862 examples, 0 failures.
+- Touched Ruby files: 17 files inspected by RuboCop, 0 offenses.
+
 ## [0.4.0] - 2026-06-24
 
 Two more host-ergonomic primitives that close the deferred-from-0.3.0 backlog: `Workflow.stuck_for?` for liveness probing and `Context.persist :auto` for write-tracked context persistence. Both are purely additive.

data/README.md

@@ -94,6 +94,21 @@ end
 
 The full pattern guide with working examples for each lives in [`docs/PATTERNS.md`](docs/PATTERNS.md).
 
+## Workflow Graph Inspection
+
+Smith can inspect a workflow's declared graph without running agents or advancing state. This is useful for host apps that want to render, lint, or cache a workflow shape before execution.
+
+```ruby
+report = ReplyWorkflow.validate_graph
+
+report.valid?        # => true
+report.transitions   # => read-only transition snapshots
+report.diagnostics   # => errors and warnings for missing states or routes
+report.metrics       # => state, transition, reachability, and terminal-state counts
+```
+
+Graph inspection is static and diagnostic-only. Runtime execution, persistence, progress projection, retries, and recovery remain host-owned concerns.
+
 ## Configuration
 
 ```ruby

data/lib/smith/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Diagnostic
+        attr_reader :severity, :code, :message, :state, :transition, :target, :suggestion
+
+        def initialize(**attributes)
+          @severity = attributes.fetch(:severity)
+          @code = attributes.fetch(:code)
+          @message = attributes.fetch(:message)
+          @state = attributes[:state]
+          @transition = attributes[:transition]
+          @target = attributes[:target]
+          @suggestion = attributes[:suggestion]
+        end
+
+        def to_h
+          {
+            severity: severity,
+            code: code,
+            message: message,
+            state: state,
+            transition: transition,
+            target: target,
+            suggestion: suggestion
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Metrics
+        attr_reader :graph, :reachable_transition_names
+
+        def initialize(graph, reachable_transition_names)
+          @graph = graph
+          @reachable_transition_names = reachable_transition_names
+        end
+
+        def to_h
+          {
+            states_count: graph.states.length,
+            transitions_count: graph.transitions.length,
+            reachable_transitions_count: reachable_transition_names.length,
+            terminal_states: terminal_states
+          }
+        end
+
+        private
+
+        def terminal_states
+          graph.states.select do |state|
+            graph.transitions.values.none? { |transition| transition.from == state }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Reachability
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def transition_names
+          return [] unless graph.initial_state
+
+          reset_walk
+          drain_queue
+          @seen_transitions.keys
+        end
+
+        private
+
+        def reset_walk
+          @seen_states = { graph.initial_state => true }
+          @seen_transitions = {}
+          @queue = [graph.initial_state]
+        end
+
+        def drain_queue
+          transitions_from(@queue.shift).each { |transition| visit_transition(transition) } until @queue.empty?
+        end
+
+        def visit_transition(transition)
+          return if @seen_transitions.key?(transition.name)
+
+          @seen_transitions[transition.name] = true
+          enqueue_state(transition.to)
+          Targets.for(transition).each { |target_name| visit_named_transition(target_name) }
+        end
+
+        def visit_named_transition(target_name)
+          target = graph.transitions[target_name]
+          visit_transition(target) if target
+        end
+
+        def enqueue_state(state)
+          return if state.nil? || @seen_states.key?(state)
+
+          @seen_states[state] = true
+          @queue << state
+        end
+
+        def transitions_from(state)
+          graph.transitions.values.select { |transition| transition.from == state }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class ReachabilityDiagnostics
+        attr_reader :graph, :reachable_transition_names
+
+        def initialize(graph, reachable_transition_names)
+          @graph = graph
+          @reachable_transition_names = reachable_transition_names
+        end
+
+        def to_a
+          (graph.transitions.keys - reachable_transition_names).filter_map do |transition_name|
+            next if auto_fail_transition?(transition_name)
+
+            diagnostic_for(transition_name)
+          end
+        end
+
+        private
+
+        def auto_fail_transition?(transition_name)
+          transition_name == :fail && graph.transitions[transition_name]&.from.nil?
+        end
+
+        def diagnostic_for(transition_name)
+          transition = graph.transitions.fetch(transition_name)
+          Diagnostic.new(
+            severity: :warning,
+            code: :unreachable_transition,
+            transition: transition_name,
+            state: transition.from,
+            message: "Transition #{ref(transition_name)} is not reachable from " \
+                     "initial_state #{ref(graph.initial_state)}.",
+            suggestion: "Connect transition #{ref(transition_name)} from a reachable state or remove it."
+          )
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      module Reference
+        def self.format(value)
+          return ":#{value}" if value.is_a?(Symbol)
+
+          value.inspect
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Report
+        attr_reader :status, :workflow_class, :initial_state, :states, :transitions, :diagnostics, :metrics
+
+        def initialize(**attributes)
+          @status = attributes.fetch(:status)
+          @workflow_class = attributes.fetch(:workflow_class)
+          @initial_state = attributes.fetch(:initial_state)
+          @states = attributes.fetch(:states)
+          @transitions = attributes.fetch(:transitions)
+          @diagnostics = attributes.fetch(:diagnostics)
+          @metrics = attributes.fetch(:metrics)
+        end
+
+        def valid?
+          errors.empty?
+        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,
+            initial_state: initial_state,
+            states: states,
+            transitions: transitions.map(&:to_h),
+            diagnostics: diagnostics.map(&:to_h),
+            suggestions: suggestions,
+            metrics: metrics
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class StateDiagnostics
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def to_a
+          [
+            *initial_state_diagnostics,
+            *state_reference_diagnostics
+          ]
+        end
+
+        private
+
+        def initial_state_diagnostics
+          return [] if graph.initial_state && graph.states.include?(graph.initial_state)
+
+          [
+            Diagnostic.new(
+              severity: :error,
+              code: :missing_initial_state,
+              state: graph.initial_state,
+              message: "Workflow initial_state is not declared as a state.",
+              suggestion: "Declare an initial_state and ensure it is included in the workflow states."
+            )
+          ]
+        end
+
+        def state_reference_diagnostics
+          graph.transitions.values.flat_map do |transition|
+            [
+              undefined_state_diagnostic(transition, :from, transition.from),
+              undefined_state_diagnostic(transition, :to, transition.to)
+            ].compact
+          end
+        end
+
+        def undefined_state_diagnostic(transition, edge, state)
+          return if edge == :from && state.nil?
+          return if graph.states.include?(state)
+
+          Diagnostic.new(
+            severity: :error,
+            code: :"undefined_#{edge}_state",
+            state: state,
+            transition: transition.name,
+            message: "Transition #{ref(transition.name)} references undefined #{edge} state #{ref(state)}.",
+            suggestion: "Declare state #{ref(state)} or update transition #{ref(transition.name)}."
+          )
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Targets
+        attr_reader :transition
+
+        def self.for(transition)
+          new(transition).names
+        end
+
+        def self.router_for(transition)
+          new(transition).router_names
+        end
+
+        def initialize(transition)
+          @transition = transition
+        end
+
+        def names
+          names = [transition.success_transition, transition.failure_transition]
+          names.concat(router_names)
+          names.compact.uniq
+        end
+
+        def router_names
+          return [] unless transition.router_config
+
+          [
+            *transition.router_config.fetch(:routes).values,
+            transition.router_config.fetch(:fallback)
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class TransitionDiagnostics
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def to_a
+          graph.transitions.values.flat_map do |transition|
+            [
+              transition_target_diagnostic(transition, :success_transition, transition.success_transition),
+              transition_target_diagnostic(transition, :failure_transition, transition.failure_transition),
+              *router_target_diagnostics(transition),
+              *target_state_mismatch_diagnostics(transition)
+            ].compact
+          end
+        end
+
+        private
+
+        def transition_target_diagnostic(transition, code, target)
+          return if target.nil?
+          return if graph.transitions.key?(target)
+
+          Diagnostic.new(
+            severity: :error,
+            code: :"unresolved_#{code}",
+            transition: transition.name,
+            target: target,
+            message: "Transition #{ref(transition.name)} references missing transition #{ref(target)}.",
+            suggestion: "Declare transition #{ref(target)} or update transition #{ref(transition.name)}."
+          )
+        end
+
+        def router_target_diagnostics(transition)
+          return [] unless transition.router_config
+
+          Targets.router_for(transition).filter_map do |target|
+            transition_target_diagnostic(transition, :router_target, target)
+          end
+        end
+
+        def target_state_mismatch_diagnostics(transition)
+          Targets.for(transition).filter_map do |target_name|
+            target = graph.transitions[target_name]
+            next unless target
+            next if target.from.nil? || target.from == transition.to
+
+            mismatch_diagnostic(transition, target_name, target)
+          end
+        end
+
+        def mismatch_diagnostic(transition, target_name, target)
+          Diagnostic.new(
+            severity: :warning,
+            code: :target_from_state_mismatch,
+            transition: transition.name,
+            target: target_name,
+            state: transition.to,
+            message: "Transition #{ref(transition.name)} can route to #{ref(target_name)}, " \
+                     "but #{ref(target_name)} starts from #{ref(target.from)} instead of #{ref(transition.to)}.",
+            suggestion: "Align #{ref(target_name)}'s from state with #{ref(transition.to)}, " \
+                        "or remove the named route."
+          )
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class TransitionSnapshot
+        KINDS = [
+          %i[deterministic deterministic?],
+          %i[router routed?],
+          %i[nested_workflow nested?],
+          %i[optimizer optimized?],
+          %i[orchestrator orchestrated?],
+          %i[parallel parallel?]
+        ].freeze
+
+        attr_reader :name, :from, :to, :kind, :success_transition, :failure_transition, :routes, :fallback
+
+        def self.from_transition(transition)
+          new(
+            name: transition.name,
+            from: transition.from,
+            to: transition.to,
+            kind: kind_for(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)
+          )
+        end
+
+        def self.kind_for(transition)
+          kind = KINDS.find { |_name, predicate| transition.public_send(predicate) }
+          return kind.first if kind
+          return :agent if transition.agent_name
+
+          :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,
+            from: from,
+            to: to,
+            kind: kind,
+            success_transition: success_transition,
+            failure_transition: failure_transition,
+            routes: routes,
+            fallback: fallback
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Validator
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def report
+          diagnostics = all_diagnostics
+
+          Report.new(
+            status: status_for(diagnostics),
+            workflow_class: graph.workflow_class.name,
+            initial_state: graph.initial_state,
+            states: graph.states,
+            transitions: graph.transition_snapshots,
+            diagnostics: diagnostics,
+            metrics: Metrics.new(graph, reachable_transition_names).to_h
+          )
+        end
+
+        private
+
+        def all_diagnostics
+          [
+            *StateDiagnostics.new(graph).to_a,
+            *TransitionDiagnostics.new(graph).to_a,
+            *ReachabilityDiagnostics.new(graph, reachable_transition_names).to_a
+          ]
+        end
+
+        def reachable_transition_names
+          @reachable_transition_names ||= Reachability.new(graph).transition_names
+        end
+
+        def status_for(diagnostics)
+          return :invalid if diagnostics.any? { |diagnostic| diagnostic.severity == :error }
+          return :warning if diagnostics.any?
+
+          :valid
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      attr_reader :workflow_class, :initial_state, :states, :transitions
+
+      def initialize(workflow_class:, initial_state:, states:, transitions:)
+        @workflow_class = workflow_class
+        @initial_state = initial_state
+        @states = Array(states).uniq.freeze
+        @transitions = transitions.dup.freeze
+      end
+
+      def validate
+        Validator.new(self).report
+      end
+
+      def transition_snapshots
+        transitions.values.map { |transition| TransitionSnapshot.from_transition(transition) }
+      end
+    end
+  end
+end
+
+require_relative "graph/reference"
+require_relative "graph/diagnostic"
+require_relative "graph/state_diagnostics"
+require_relative "graph/reachability"
+require_relative "graph/reachability_diagnostics"
+require_relative "graph/metrics"
+require_relative "graph/report"
+require_relative "graph/targets"
+require_relative "graph/transition_snapshot"
+require_relative "graph/transition_diagnostics"
+require_relative "graph/validator"

data/lib/smith/workflow/graph_dsl.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    def self.graph
+      Graph.new(
+        workflow_class: self,
+        initial_state: initial_state,
+        states: @states || [],
+        transitions: @transitions || {}
+      )
+    end
+
+    def self.validate_graph
+      graph.validate
+    end
+  end
+end

data/lib/smith.rb

@@ -70,6 +70,7 @@ module Smith
     unless %i[off auto].include?(value)
       raise ArgumentError, "Smith.config.openai_api_mode must be :off or :auto, got #{value.inspect}"
     end
+
     value
   }
 
@@ -227,6 +228,8 @@ require_relative "smith/agent/registry"
 
 # Workflow (Transition, DSL, Persistence, and Execution must load before Workflow)
 require_relative "smith/workflow/transition"
+require_relative "smith/workflow/graph"
+require_relative "smith/workflow/graph_dsl"
 require_relative "smith/workflow/dsl"
 require_relative "smith/workflow/persistence"
 require_relative "smith/workflow/durability"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Samuel Ralak
@@ -219,6 +219,19 @@ files:
 - lib/smith/workflow/event_integration.rb
 - lib/smith/workflow/execution.rb
 - lib/smith/workflow/execution_frame.rb
+- lib/smith/workflow/graph.rb
+- lib/smith/workflow/graph/diagnostic.rb
+- lib/smith/workflow/graph/metrics.rb
+- lib/smith/workflow/graph/reachability.rb
+- lib/smith/workflow/graph/reachability_diagnostics.rb
+- lib/smith/workflow/graph/reference.rb
+- lib/smith/workflow/graph/report.rb
+- lib/smith/workflow/graph/state_diagnostics.rb
+- lib/smith/workflow/graph/targets.rb
+- lib/smith/workflow/graph/transition_diagnostics.rb
+- lib/smith/workflow/graph/transition_snapshot.rb
+- lib/smith/workflow/graph/validator.rb
+- lib/smith/workflow/graph_dsl.rb
 - lib/smith/workflow/guardrail_integration.rb
 - lib/smith/workflow/nested_execution.rb
 - lib/smith/workflow/orchestrator_worker.rb