Class: Phronomy::Workflow

Inherits:
Object
  • Object
show all
Includes:
Runnable
Defined in:
lib/phronomy/workflow.rb,
lib/phronomy/workflow/phase_machine_builder.rb

Overview

StateChart-style workflow definition DSL.

Defines agent workflows in terms of states and events backed by Phronomy::WorkflowRunner. This is the primary high-level API for workflow-based execution in phronomy.

Basic usage

app = Phronomy::Workflow.define(MyContext) do
initial :fetch

state :fetch
state :process

entry :fetch,   FETCH_NODE
entry :process, PROCESS_NODE

transition from: :fetch,   to: :process
transition from: :process, to: :__finish__
end

result = app.invoke({ url: "https://example.com" })

Wait states

app = Phronomy::Workflow.define(MyContext) do
initial :propose

state :propose
wait_state :awaiting_approval
state :execute

entry :propose, PROPOSE_NODE
entry :execute, EXECUTE_NODE

transition from: :propose, to: :awaiting_approval
transition from: :execute, to: :__finish__

transition from: :awaiting_approval, on: :approve, to: :execute
transition from: :awaiting_approval, on: :reject,  to: :propose
end

halted = app.invoke({ ... })
final  = app.send_event(state: halted, event: :approve)

Conditional transitions

transition from: :decide, guard: ->(s) { s.score > 5 }, to: :high
transition from: :decide, to: :low   # fallback (no guard)

Defined Under Namespace

Classes: Builder, PhaseMachineBuilder

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Runnable

#batch, #trace

Constructor Details

#initialize(runner) ⇒ Workflow

Returns a new instance of Workflow.

Parameters:



77
78
79
 
# File 'lib/phronomy/workflow.rb', line 77

def initialize(runner)
  @runner = runner
end

Class Method Details

.define(context_class, state_store: nil) { ... } ⇒ Phronomy::Workflow

Defines a new Workflow.

Parameters:

  • context_class (Class) —

    class that includes Phronomy::WorkflowContext

  • state_store (Phronomy::StateStore::Base, nil) (defaults to: nil) —

    optional per-workflow state store. Takes precedence over the global Phronomy.configuration.state_store.

Yields:

  • block evaluated in DSL context

Returns:

Raises:

  • (ArgumentError) —

    if no states are declared (empty workflow)

  • (ArgumentError) —

    if any transition references an undeclared to: or from: state



69
70
71
72
73
 
# File 'lib/phronomy/workflow.rb', line 69

def self.define(context_class, state_store: nil, &block)
  builder = Builder.new(context_class, state_store: state_store)
  builder.instance_eval(&block)
  builder.build
end

Instance Method Details

#invoke(input, config: {}, invocation_context: nil) ⇒ Object

Executes the workflow from the initial state.

Parameters:

  • input (Hash) —

    initial context field values

  • config (Hash) (defaults to: {}) —

    { thread_id:, recursion_limit:, user_id:, session_id: }

  • invocation_context (Phronomy::InvocationContext, nil) (defaults to: nil) —

    optional first-class context object. When present, thread_id, cancellation_token, and deadline are derived from it (existing config: keys take precedence). The object is also stored in config[:invocation_context] for downstream tracing.

Returns:

  • (Object) —

    final context



90
91
92
93
94
95
 
# File 'lib/phronomy/workflow.rb', line 90

def invoke(input, config: {}, invocation_context: nil)
  if invocation_context
    config = _apply_invocation_context(config, invocation_context)
  end
  @runner.invoke(input, config: config)
end

#invoke_async(input, config: {}, invocation_context: nil) ⇒ Phronomy::Task

Invokes this workflow asynchronously and returns a Task.

Unlike #invoke, this method registers the workflow session with the EventLoop and returns immediately without spawning an extra OS thread. The returned Task resolves with the final context when the workflow finishes.

Parameters:

Returns:



109
110
111
112
113
114
 
# File 'lib/phronomy/workflow.rb', line 109

def invoke_async(input, config: {}, invocation_context: nil)
  if invocation_context
    config = _apply_invocation_context(config, invocation_context)
  end
  @runner.invoke_deferred(input, config: config)
end

#resume(state:, input: nil) ⇒ Object

Resumes a halted workflow. Generic resume that works for all halt types.

Parameters:

  • state (Object) —

    halted context

  • input (Hash, nil) (defaults to: nil) —

    optional field updates to merge before resuming

Returns:

  • (Object) —

    final context



121
122
123
 
# File 'lib/phronomy/workflow.rb', line 121

def resume(state:, input: nil)
  @runner.resume(state: state, input: input)
end

#send_event(state:, event:, input: nil) ⇒ Object

Fires a named event to advance a halted workflow.

Parameters:

  • state (Object) —

    halted context

  • event (Symbol) —

    event name (e.g. :approve, :reject, :resume)

  • input (Hash, nil) (defaults to: nil) —

    optional field updates to merge before resuming

Returns:

  • (Object) —

    final context



131
132
133
 
# File 'lib/phronomy/workflow.rb', line 131

def send_event(state:, event:, input: nil)
  @runner.send_event(state: state, event: event, input: input)
end

#stream(input, config: {}) {|Hash| ... } ⇒ Object

Streaming execution. Yields { state: Symbol, context: Object } after each state action.

Parameters:

  • input (Hash)
  • config (Hash) (defaults to: {})

Yields:

  • (Hash)

Returns:

  • (Object) —

    final context



141
142
143
 
# File 'lib/phronomy/workflow.rb', line 141

def stream(input, config: {}, &block)
  @runner.stream(input, config: config, &block)
end