smith-agents 0.4.2 → 0.4.4

data/lib/smith/workflow/transition.rb

@@ -5,7 +5,8 @@ module Smith
     class Transition
       attr_reader :name, :from, :to, :agent_name, :agent_opts, :success_transition, :failure_transition,
                   :router_config, :workflow_class, :optimization_config, :orchestrator_config,
-                  :fanout_config, :retry_config, :deterministic_block, :deterministic_kind
+                  :fanout_config, :retry_config, :deterministic_block, :deterministic_kind,
+                  :deterministic_routes
 
       def initialize(name, from:, to:, &)
         @name = name
@@ -32,8 +33,12 @@ module Smith
       def route(agent_name, routes:, confidence_threshold:, fallback:)
         validate_route_conflicts!
 
-        @agent_name = agent_name
-        @router_config = { routes: routes, confidence_threshold: confidence_threshold, fallback: fallback }
+        @agent_name = normalize_agent_name!(agent_name, "router")
+        @router_config = {
+          routes: normalize_router_routes!(routes),
+          confidence_threshold: normalize_confidence_threshold!(confidence_threshold),
+          fallback: normalize_transition_reference!(fallback, "router fallback")
+        }
       end
 
       def workflow(klass)
@@ -104,12 +109,13 @@ module Smith
       end
 
       %i[compute run].each do |method_name|
-        define_method(method_name) do |&block|
+        define_method(method_name) do |routes: nil, &block|
           validate_deterministic_conflicts!
           raise WorkflowError, "#{method_name} requires a block" unless block
 
           @deterministic_block = block
           @deterministic_kind = method_name
+          @deterministic_routes = normalize_deterministic_routes!(routes)
         end
       end
 
@@ -241,6 +247,57 @@ module Smith
         normalized.freeze
       end
 
+      def normalize_agent_name!(agent_name, label)
+        value = agent_name.to_s.strip
+        raise WorkflowError, "#{label} agent must not be blank" if value.empty?
+
+        value.to_sym
+      end
+
+      def normalize_router_routes!(routes)
+        raise WorkflowError, "router routes must be a Hash" unless routes.is_a?(Hash)
+        raise WorkflowError, "router routes must not be empty" if routes.empty?
+
+        routes.each_with_object({}) do |(route_key, transition_name), map|
+          key = normalize_router_route_key!(route_key)
+          raise WorkflowError, "router route :#{key} is duplicated" if map.key?(key)
+
+          map[key] = normalize_transition_reference!(transition_name, "router route :#{key}")
+        end.freeze
+      end
+
+      def normalize_router_route_key!(route_key)
+        value = route_key.to_s.strip
+        raise WorkflowError, "router route keys must not be blank" if value.empty?
+
+        value.to_sym
+      end
+
+      def normalize_confidence_threshold!(threshold)
+        numeric = Float(threshold)
+        return numeric if numeric >= 0.0 && numeric <= 1.0
+
+        raise WorkflowError, "router confidence_threshold must be a number in 0.0..1.0"
+      rescue TypeError, ArgumentError
+        raise WorkflowError, "router confidence_threshold must be a number in 0.0..1.0"
+      end
+
+      def normalize_transition_reference!(transition_name, label)
+        case transition_name
+        when Symbol
+          raise WorkflowError, "#{label} transition must not be blank" if transition_name.to_s.empty?
+
+          transition_name
+        when String
+          value = transition_name.strip
+          raise WorkflowError, "#{label} transition must not be blank" if value.empty?
+
+          value.freeze
+        else
+          raise WorkflowError, "#{label} transition must be String or Symbol"
+        end
+      end
+
       def normalize_fanout_branch_key!(branch_key)
         key = branch_key.to_s.strip
         raise WorkflowError, "fan_out branch keys must not be blank" if key.empty?
@@ -278,6 +335,35 @@ module Smith
         validate_non_negative_numeric!(:max_delay, max_delay) unless max_delay.nil?
       end
 
+      def normalize_deterministic_routes!(routes)
+        return nil if routes.nil?
+        raise WorkflowError, "deterministic routes must be an Array" unless routes.is_a?(Array)
+        raise WorkflowError, "deterministic routes must not be empty" if routes.empty?
+
+        routes.each_with_object([]) do |route, list|
+          name = normalize_deterministic_route!(route)
+          raise WorkflowError, "deterministic route #{name.inspect} is duplicated" if list.include?(name)
+
+          list << name
+        end.freeze
+      end
+
+      def normalize_deterministic_route!(route)
+        case route
+        when Symbol
+          raise WorkflowError, "deterministic route names must not be blank" if route.to_s.empty?
+
+          route
+        when String
+          value = route.strip
+          raise WorkflowError, "deterministic route names must not be blank" if value.empty?
+
+          value.freeze
+        else
+          raise WorkflowError, "deterministic route names must be String or Symbol"
+        end
+      end
+
       def validate_non_negative_numeric!(name, value)
         numeric = Float(value)
         return if numeric >= 0.0

data/lib/smith/workflow/usage_entry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # One row per agent provider call. `usage_id` is a UUID generated at
+    # recording time and stable across persist/restore so hosts can use it as an
+    # idempotency anchor.
+    # rubocop:disable Style/RedundantStructKeywordInit
+    UsageEntry = Struct.new(
+      :usage_id,
+      :agent_name,
+      :model,
+      :input_tokens,
+      :output_tokens,
+      :cost,
+      :attempt_kind,
+      :recorded_at,
+      keyword_init: true
+    ) do
+      def self.from_h(hash)
+        sym = hash.transform_keys(&:to_sym)
+        filtered = sym.slice(*members)
+        filtered[:agent_name] = filtered[:agent_name].to_sym if filtered[:agent_name].is_a?(String)
+        filtered[:attempt_kind] = filtered[:attempt_kind].to_sym if filtered[:attempt_kind].is_a?(String)
+        new(**filtered)
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end

data/lib/smith/workflow/worker_execution.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Smith
+  class Workflow
+    WorkerExecution = Struct.new(:execution_id, :task, :output) do
+      def self.run(worker_class, task, schema, budget_runner)
+        new(SecureRandom.uuid, task, budget_runner.call(worker_class, task, schema))
+      end
+    end
+  end
+end

data/lib/smith/workflow.rb

@@ -6,6 +6,11 @@ require "securerandom"
 require "set"
 require "time"
 
+require_relative "workflow/agent_result"
+require_relative "workflow/branch_env"
+require_relative "workflow/run_result"
+require_relative "workflow/usage_entry"
+
 module Smith
   class Workflow
     include DSL
@@ -21,113 +26,6 @@ module Smith
 
     DEFAULT_MAX_TRANSITIONS = 100
 
-    # `keyword_init: true` is mandatory: `build_run_result` constructs
-    # the result via keyword arguments. Plain Ruby Structs treat the
-    # kwargs hash as the first positional field, silently leaving the
-    # remaining fields nil — verified empirically. The `keyword_init`
-    # flag routes kwargs to the right fields. `usage_entries` is the
-    # 10th field, added in this slice for hadithi billing.
-    RunResult = Struct.new(:state, :output, :steps, :total_cost, :total_tokens, :context, :session_messages,
-                           :tool_results, :outcome, :usage_entries, keyword_init: true) do
-      def done?
-        state == :done
-      end
-
-      def failed?
-        state == :failed
-      end
-
-      def terminal_output
-        output
-      end
-
-      def outcome_kind
-        outcome&.dig(:kind)
-      end
-
-      def outcome_payload
-        outcome&.dig(:payload)
-      end
-
-      def last_error
-        steps.reverse.map { |step| step[:error] }.compact.first
-      end
-
-      def failed_transition
-        failure_detail&.fetch(:transition)
-      end
-
-      def failure_detail
-        failed_step = steps.reverse.find { |step| step[:error] }
-        return nil unless failed_step
-
-        {
-          transition: failed_step[:transition],
-          from: failed_step[:from],
-          to: failed_step[:to],
-          error: failed_step[:error]
-        }
-      end
-    end
-
-    # keyword_init: true so adding new fields in future schema versions
-    # remains backward-compatible: `from_response` and `from_h` can fill
-    # extra fields without breaking existing call sites that pass the
-    # historical positional args. Reading old persisted records into a
-    # newer Struct shape: from_h slices to current members (unknown keys
-    # silently dropped; missing keys default to nil).
-    AgentResult = Struct.new(
-      :content, :input_tokens, :output_tokens, :cost, :model_used,
-      keyword_init: true
-    ) do
-      def self.from_response(response, content, model_used: nil)
-        new(
-          content: content,
-          input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : nil,
-          output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : nil,
-          cost: nil,
-          model_used: model_used
-        )
-      end
-
-      def usage_known?
-        !input_tokens.nil? && !output_tokens.nil?
-      end
-    end
-
-    # One row per agent provider call. `usage_id` is a UUID generated
-    # at recording time and stable across persist/restore — hadithi
-    # uses it as the idempotency anchor on `usage_events.smith_usage_id`.
-    # Includes `to_h`/`from_h` for JSON serialization (plain Struct
-    # JSON-encodes to `"#<struct ...>"` — useless).
-    #
-    # keyword_init: true gives forward/backward compatibility:
-    # - Adding a new field: old persisted hashes restore cleanly (new
-    #   field defaults to nil).
-    # - Reading new persisted hashes with an older Smith version: from_h
-    #   slices to known members (unknown keys silently dropped).
-    UsageEntry = Struct.new(
-      :usage_id,
-      :agent_name,
-      :model,
-      :input_tokens,
-      :output_tokens,
-      :cost,
-      :attempt_kind,
-      :recorded_at,
-      keyword_init: true
-    ) do
-      def self.from_h(hash)
-        sym = hash.transform_keys(&:to_sym)
-        filtered = sym.slice(*members)
-        # Symbolize :agent_name and :attempt_kind for backward compat
-        # with callers that consume the field as Symbol.
-        filtered[:agent_name] = filtered[:agent_name].to_sym if filtered[:agent_name].is_a?(String)
-        filtered[:attempt_kind] = filtered[:attempt_kind].to_sym if filtered[:attempt_kind].is_a?(String)
-        new(**filtered)
-      end
-    end
-
     # Reconstruct Smith error classes from `@last_failed_step` snapshots.
     # Order matters: more-specific subclasses first, so a real DSF doesn't
     # get caught by the WorkflowError handler. Each lambda preserves the
@@ -167,24 +65,6 @@ module Smith
     RETRYABLE_BEARING_FAMILIES = %w[deterministic_step_failure tool_guardrail_failed].freeze
     private_constant :RETRYABLE_BEARING_FAMILIES
 
-    # keyword_init: true for forward/backward compat (see UsageEntry).
-    BranchEnv = Struct.new(
-      :prepared_input, :guardrail_sources, :scoped_store, :branch_estimates, :deadline,
-      keyword_init: true
-    ) do
-      def setup_thread
-        Smith::Tool.current_guardrails = guardrail_sources
-        Smith::Tool.current_deadline = deadline
-        Smith.scoped_artifacts = scoped_store
-      end
-
-      def teardown_thread
-        Smith::Tool.current_guardrails = nil
-        Smith::Tool.current_deadline = nil
-        Smith.scoped_artifacts = nil
-      end
-    end
-
     attr_reader :state, :last_prepared_input, :session_messages, :ledger
 
     def initialize(context: {}, ledger: nil, created_at: nil)
@@ -239,12 +119,13 @@ module Smith
     end
 
     def advance!
-      max = self.class.max_transitions || DEFAULT_MAX_TRANSITIONS
-      raise MaxTransitionsExceeded if @step_count >= max
+      ensure_transition_budget!
+      @step_work_started = false
 
       transition = resolve_transition
       return if transition.nil?
 
+      @step_work_started = true
       step_result = execute_step(transition)
       @step_count += 1
       @updated_at = Time.now.utc.iso8601
@@ -274,11 +155,11 @@ module Smith
     end
 
     def done?
-      @state == :done
+      state_named?(:done)
     end
 
     def failed?
-      @state == :failed
+      state_named?(:failed)
     end
 
     def record_persisted_key!(key)
@@ -360,17 +241,40 @@ module Smith
       true
     end
 
+    def ensure_transition_budget!
+      max = self.class.max_transitions || DEFAULT_MAX_TRANSITIONS
+      raise MaxTransitionsExceeded if @step_count >= max
+    end
+
     def resolve_transition
       if @next_transition_name
         name = @next_transition_name
         @next_transition_name = nil
-        self.class.find_transition(name) ||
+        transition = self.class.find_transition(name) ||
           raise(UnresolvedTransitionError.new(name, self.class, @state))
+        validate_transition_origin!(transition)
+        transition
       else
         self.class.transitions_from(@state).first
       end
     end
 
+    def validate_transition_origin!(transition)
+      expected = transition.from
+      return if expected.nil? || expected == @state
+
+      raise WorkflowError,
+            "transition :#{transition.name} cannot run from state :#{@state}; expected :#{expected}"
+    end
+
+    def step_work_started?
+      @step_work_started == true
+    end
+
+    def state_named?(name)
+      @state == name || @state.to_s == name.to_s
+    end
+
     def build_run_result(steps)
       # `output` derivation matches existing semantics on fresh runs
       # (last non-nil step output via `compact.first`). Terminal-restore
@@ -416,8 +320,8 @@ module Smith
         # Skip const_get for retryable-bearing families. An unknown
         # subclass with a message-only constructor would const_get
         # successfully but discard the snapshot's `retryable`/`kind`/
-        # `details` (defaults to nil), and hadithi's `retryable?`
-        # check would misclassify a retryable failure as terminal.
+        # `details` (defaults to nil), and host retry classification
+        # could misclassify a retryable failure as terminal.
         # Family fallback rebuilds the parent class with kwargs intact.
         family_fallback(snap)
       else
@@ -436,9 +340,9 @@ module Smith
       # symbols; JSON round-trip stringifies them; coerce back to
       # match fresh-run shape exactly.
       {
-        transition: snap[:transition]&.to_sym,
-        from:       snap[:from]&.to_sym,
-        to:         snap[:to]&.to_sym,
+        transition: normalize_transition_name(snap[:transition]),
+        from:       normalize_state_name(snap[:from]),
+        to:         normalize_state_name(snap[:to]),
         error:      error
       }
     end
@@ -519,7 +423,7 @@ module Smith
     # `Struct#dup` is shallow — it shares mutable string fields between
     # the original and the duplicate. Smith's existing snapshot helpers
     # (`snapshot_context`, etc.) also use this round-trip pattern; the
-    # billing-facing RunResult must not alias mutable workflow state.
+    # usage-facing RunResult must not alias mutable workflow state.
     # Same rule applies to nested-workflow rollup (see
     # `nested_execution.rb`).
     def snapshot_usage_entries

data/lib/smith.rb

@@ -224,12 +224,20 @@ require_relative "smith/context/session"
 # Agent (depends on RubyLLM::Agent)
 require_relative "smith/agent"
 require_relative "smith/agent/lifecycle"
+require_relative "smith/agent/registry_binding"
 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/run_result"
+require_relative "smith/workflow/agent_result"
+require_relative "smith/workflow/usage_entry"
+require_relative "smith/workflow/branch_env"
+require_relative "smith/workflow/optimization_state"
+require_relative "smith/workflow/orchestration_state"
+require_relative "smith/workflow/worker_execution"
 require_relative "smith/workflow/dsl"
 require_relative "smith/workflow/persistence"
 require_relative "smith/workflow/durability"
@@ -254,6 +262,7 @@ require_relative "smith/workflow/execution_frame"
 require_relative "smith/workflow/pipeline"
 require_relative "smith/workflow/router"
 require_relative "smith/workflow/parallel"
+require_relative "smith/workflow/parallel/cancellation_signal"
 require_relative "smith/workflow/parallel/cancellation"
 
 # Conditional Rails integration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.4
 platform: ruby
 authors:
 - Samuel Ralak
@@ -135,6 +135,8 @@ files:
 - lib/smith/agent.rb
 - lib/smith/agent/lifecycle.rb
 - lib/smith/agent/registry.rb
+- lib/smith/agent/registry/introspection.rb
+- lib/smith/agent/registry_binding.rb
 - lib/smith/artifacts.rb
 - lib/smith/artifacts/file.rb
 - lib/smith/artifacts/memory.rb
@@ -206,7 +208,9 @@ files:
 - lib/smith/types.rb
 - lib/smith/version.rb
 - lib/smith/workflow.rb
+- lib/smith/workflow/agent_result.rb
 - lib/smith/workflow/artifact_integration.rb
+- lib/smith/workflow/branch_env.rb
 - lib/smith/workflow/budget_integration.rb
 - lib/smith/workflow/claim.rb
 - lib/smith/workflow/data_volume_policy.rb
@@ -221,12 +225,22 @@ files:
 - lib/smith/workflow/execution_frame.rb
 - lib/smith/workflow/fanout_execution.rb
 - lib/smith/workflow/graph.rb
+- lib/smith/workflow/graph/contract_helpers.rb
 - lib/smith/workflow/graph/diagnostic.rb
+- lib/smith/workflow/graph/fanout_contract.rb
 - lib/smith/workflow/graph/metrics.rb
+- lib/smith/workflow/graph/nested_readiness_diagnostics.rb
+- lib/smith/workflow/graph/optimization_contract.rb
+- lib/smith/workflow/graph/orchestration_contract.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/runtime_binding_diagnostic_builder.rb
+- lib/smith/workflow/graph/runtime_binding_diagnostics.rb
+- lib/smith/workflow/graph/runtime_readiness.rb
+- lib/smith/workflow/graph/runtime_readiness_metrics.rb
+- lib/smith/workflow/graph/runtime_readiness_report.rb
 - lib/smith/workflow/graph/state_diagnostics.rb
 - lib/smith/workflow/graph/targets.rb
 - lib/smith/workflow/graph/transition_diagnostics.rb
@@ -235,15 +249,21 @@ files:
 - lib/smith/workflow/graph_dsl.rb
 - lib/smith/workflow/guardrail_integration.rb
 - lib/smith/workflow/nested_execution.rb
+- lib/smith/workflow/optimization_state.rb
+- lib/smith/workflow/orchestration_state.rb
 - lib/smith/workflow/orchestrator_worker.rb
 - lib/smith/workflow/parallel.rb
 - lib/smith/workflow/parallel/cancellation.rb
+- lib/smith/workflow/parallel/cancellation_signal.rb
 - lib/smith/workflow/parallel_execution.rb
 - lib/smith/workflow/persistence.rb
 - lib/smith/workflow/pipeline.rb
 - lib/smith/workflow/retry_execution.rb
 - lib/smith/workflow/router.rb
+- lib/smith/workflow/run_result.rb
 - lib/smith/workflow/transition.rb
+- lib/smith/workflow/usage_entry.rb
+- lib/smith/workflow/worker_execution.rb
 - script/profile_tool_results.rb
 - sig/smith.rbs
 homepage: https://github.com/samuelralak/smith