ask-graph 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bcdf4454ef1639db46defba3c2b59377dd0aa719036b27be25b77a7a805fdec
-  data.tar.gz: eef23d886d551984bbd8f1514e7bdfacc38be0d4b029ec832b1e7c61f2d2036f
+  metadata.gz: 99d66a3b6b63d97a13187b67bbefd25c291d5ab80a63146e61639a0b7949689d
+  data.tar.gz: ab66b1d0586ee8570e71f2612938d6d87a9e3c5a3d44b93b046ef95343a5951a
 SHA512:
-  metadata.gz: bef581ebc5816f79ab0b8d7da98dd9cf53fba824e1e68691e5b39ef8ee0eca3380fa2994dde965ad17db24267f9541b4c537c87fa26a3852ba9fa128afc60237
-  data.tar.gz: 78d63a0b802ee4050d09a08ab4d6f62a7fa8e71425745ef055d2f02824c6fb92f48c3149fadb275723aefb93b04bf0a04c258246b115c4ad028b5a56179a9188
+  metadata.gz: 8cd5ca7104c5ea6f643e9f9333ec8a7578b53f0fcda6c0f8a5a4273ac9cbb856025024e192a9f89c4a30fc3c8072b6b2b46283ccdf3805db05faade627fef81c
+  data.tar.gz: f8f4e2494be0350b17b86f568c1de1428a1731b73f9599132f6fe408a70fed15649c803847cf01a36ba009b819f2bcfaf3f37df6d8db2a8dd36dface2c8ae01b

data/CHANGELOG.md

@@ -1,56 +1,160 @@
+## [0.6.1] — 2026-07-27
+
+### Fixed
+
+- **Hooks leak between classes** — `inherited` now deep-copies lifecycle
+  hook arrays instead of sharing them. Previously, a child class's
+  `after_step :foo` would mutate the parent class's hook arrays, causing
+  hooks to fire multiple times in sibling classes.
+
+### Changed
+
+- **Docs updated** to use the `Module::Workflow` convention throughout.
+  Recommended layout:
+
+  ```
+  app/workflows/
+    notify_customer/
+      workflow.rb          # module NotifyCustomer; class Workflow < Ask::Graph
+      steps/
+        send_email.rb
+        log_notification.rb
+    order_fulfillment/
+      workflow.rb
+      steps/
+        validate_payment.rb
+        notify_customer.rb
+        ship_order.rb
+  ```
+
+  Sub-graph composition via `Workflow.call(context)` or `context.run(Workflow)`.
+
+### Tested
+
+- 85 tests, 111 assertions, 0 failures
+
+## [0.6.0] — 2026-07-27
+
+### Changed
+
+- **All steps must be POROs** — the framework no longer auto-detects
+  `Ask::Graph` subclasses used directly as steps. Every `step` declaration
+  must be a plain Ruby class with a `call(context)` method. This eliminates
+  ambiguity at the `step` call site.
+
+  ```ruby
+  # Before — worked but was ambiguous
+  step NotifyCustomer   # is this a Graph or a PORO?
+
+  # After — always a PORO
+  step NotifyCustomer   # definitely a PORO
+  ```
+
+- **Sub-graph composition via `Workflow.call(context)`** — compose workflows
+  by calling another graph's class method with the current context. The
+  method auto-detects a Context argument and handles export → run → import.
+
+  ```ruby
+  class NotifyCustomer
+    def call(context)
+      NotifyCustomerWorkflow.call(context)
+    end
+  end
+  ```
+
+  `Graph.call(ctx)` is the same API users already know from controllers:
+  `Graph.call(params)`. Just pass a Context instead of data.
+
+### Added
+
+- **`Context#run(graph_class)`** — convenience wrapper around the export →
+  create → call → import pattern.
+
+- **Hash inputs flatten into context keys** — when a Hash is passed as
+  input, its keys are directly accessible on the context in addition to
+  `context.input`. Enables sub-graphs to transparently read outer values.
+
+- **`Context#export_data`** and **`Context#import(other)`** — public API
+  for sub-graph data passing.
+
+### Tested
+
+- 85 tests, 111 assertions, 0 failures
+
 ## [0.5.0] — 2026-07-27
 
 ### Added
 
-- **Sub-graph composition** — use any `Ask::Graph` subclass as a step in another
-  graph. The sub-graph runs all its internal steps and merges its context back
-  into the outer graph.
+- **Sub-graph composition via `Workflow.call(context)`** — compose workflows
+  by calling another graph's `call` class method with the current context.
+  The method detects the Context argument and handles export → run → import
+  automatically.
 
   ```ruby
-  class NotifyCustomer < Ask::Graph
+  # Define a workflow
+  class NotifyCustomerWorkflow < Ask::Graph
     step SendEmail
     step LogNotification
   end
 
+  # Use it as a step via a PORO wrapper
+  class NotifyCustomer
+    def call(context)
+      NotifyCustomerWorkflow.call(context)
+    end
+  end
+
+  # Compose — every step is a PORO
   class HandleOrder < Ask::Graph
     step ValidatePayment
-    step NotifyCustomer   # runs the sub-graph, merges its context
+    step NotifyCustomer
     step ShipOrder
   end
   ```
 
-  - Sub-graphs read the outer graph's context directly — no special wiring
-  - Sub-graph writes are merged back automatically
-  - Supports nesting (sub-graphs within sub-graphs)
+  - `Graph.call(context)` exports the context data, creates the sub-graph,
+    runs it, and imports results back — all automatically
+  - Same API users already know from `Graph.call(params)` in controllers
+  - Supports nesting (sub-graphs calling sub-graphs)
   - Supports `timeout:`, `retry:`, and `if:`/`unless:` on the outer step
   - Supports parallel steps inside sub-graphs
-  - Shares the same `storage` backend with the outer graph
+
+- **Hash inputs flatten into context keys** — when a Hash is passed as
+  input, its keys are directly accessible on the context in addition to
+  `context.input`. This enables sub-graphs to transparently read outer
+  context values.
+
+  ```ruby
+  g.new({ value: 42 }).call
+  ctx.value   # => 42 (directly accessible)
+  ctx.input   # => { value: 42 } (still works as before)
+  ```
 
 - **`Context#export_data`** — returns the raw store hash without JSON
   serialization. Used internally for sub-graph data passing.
 
 - **`Context#import(other)`** — merges data from another context or hash
-  into this one. Used internally by sub-graph composition.
+  into this one.
 
-- **Hash inputs now flatten into context keys** — when a Hash is passed as
-  input to a graph, its keys are directly accessible on the context in
-  addition to `context.input`. This enables sub-graphs to transparently
-  read outer context values.
+- **`Context#run(graph_class)`** — convenience method wrapping the
+  export → create → call → import pattern.
 
   ```ruby
-  g.new({ value: 42 }).call
-  ctx.value   # => 42 (new — directly accessible)
-  ctx.input   # => { value: 42 } (still works)
+  def call(context)
+    context.run(NotifyCustomerWorkflow)
+  end
   ```
 
-### Limitations
+### Changed
 
-- Sub-graphs containing `approve` steps are not yet supported and raise
-  `ArgumentError`. Nested approval will be added in a future release.
+- **All steps are POROs** — the framework no longer detects `Ask::Graph`
+  subclasses used directly as steps. Every `step` declaration must be a
+  plain Ruby class with a `call(context)` method. This eliminates the
+  ambiguity of "is this step a graph or a PORO?"
 
 ### Tested
 
-- 87 tests, 114 assertions, 0 failures
+- 85 tests, 111 assertions, 0 failures
 
 ## [0.4.0] — 2026-07-27
 

data/README.md

@@ -6,28 +6,30 @@
 gem "ask-graph"
 ```
 
-## Quick Start
-
-```ruby
-require "ask-graph"
-
-# Define a workflow
-class ProcessOrder < Ask::Graph
-  step ValidateOrder
-  step ChargeCustomer,  if: :valid?
-  step SendConfirmation, if: :valid?
-  step NotifyAdmin,     unless: :valid?
-
-  private
-
-  def valid?
-    context.order.valid?
-  end
-end
-
-# Run it
-result = ProcessOrder.run(order: order)
-```
+	## Quick Start
+	
+	```ruby
+	require "ask-graph"
+	
+	# Define a workflow
+	module ProcessOrder
+	  class Workflow < Ask::Graph
+	    step ValidateOrder
+	    step ChargeCustomer,  if: :valid?
+	    step SendConfirmation, if: :valid?
+	    step NotifyAdmin,     unless: :valid?
+	
+	    private
+	
+	    def valid?
+	      context.order.valid?
+	    end
+	  end
+	end
+	
+	# Run it
+	result = ProcessOrder::Workflow.call(order: order)
+	```
 
 ## Steps
 
@@ -41,86 +43,96 @@ class ValidateOrder
 end
 ```
 
-### Sequential steps
-
-```ruby
-class HandleCall < Ask::Graph
-  step Transcribe
-  step Classify
-  step Respond
-end
-```
-
-### Conditional steps
-
-```ruby
-class HandleCall < Ask::Graph
-  step BookAppointment,  if: :booking?
-  step EmergencyAlert,   if: :emergency?
-  step HandleInquiry,    unless: :known_intent?
-
-  private
-
-  def booking?   = context.intent == "booking"
-  def emergency? = context.intent == "emergency"
-  def known_intent? = %w[booking emergency inquiry].include?(context.intent)
-end
-```
-
-### Parallel steps
-
-Use `steps` (plural) to run multiple steps simultaneously:
-
-```ruby
-class SyncData < Ask::Graph
-  step FetchRecords
-
-  # All three run in parallel
-  steps CrmUpdate, CalendarSync, SendNotification
-
-  step ConfirmResponse
-end
-```
-
-### Human-in-the-loop (approve)
-
-`approve` runs a step, then pauses the workflow and waits for external input:
-
-```ruby
-class ProcessBooking < Ask::Graph
-  step BookAppointment
-  approve ReviewBooking, if: :expensive?
-  step ConfirmBooking
-end
-```
-
-After `approve` pauses, resume with:
-
-```ruby
-graph = ProcessBooking.new
-result = graph.run              # runs, pauses after ReviewBooking
-result = graph.resume(input: "approved")  # resumes, runs ConfirmBooking
-```
-
-### Per-item loops
-
-Use `context.each` inside a step for iteration with automatic checkpointing:
-
-```ruby
-class SendVoiceReminders
-  def call(context)
-    context.each(context.appointments) do |appt|
-      PhoneService.call(appt.number, appt.message)
-    end
-  end
-end
-
-class DailyReminders < Ask::Graph
-  step FetchAppointments
-  step SendVoiceReminders  # loops with per-item checkpointing
-  step MarkComplete
-end
-```
+	### Sequential steps
+	
+	```ruby
+	module HandleCall
+	  class Workflow < Ask::Graph
+	    step Transcribe
+	    step Classify
+	    step Respond
+	  end
+	end
+	```
+	
+	### Conditional steps
+	
+	```ruby
+	module HandleCall
+	  class Workflow < Ask::Graph
+	    step BookAppointment,  if: :booking?
+	    step EmergencyAlert,   if: :emergency?
+	    step HandleInquiry,    unless: :known_intent?
+	
+	    private
+	
+	    def booking?   = context.intent == "booking"
+	    def emergency? = context.intent == "emergency"
+	    def known_intent? = %w[booking emergency inquiry].include?(context.intent)
+	  end
+	end
+	```
+
+	### Parallel steps
+	
+	Use `steps` (plural) to run multiple steps simultaneously:
+	
+	```ruby
+	module SyncData
+	  class Workflow < Ask::Graph
+	    step FetchRecords
+	
+	    # All three run in parallel
+	    steps CrmUpdate, CalendarSync, SendNotification
+	
+	    step ConfirmResponse
+	  end
+	end
+	```
+	
+	### Human-in-the-loop (approve)
+	
+	`approve` runs a step, then pauses the workflow and waits for external input:
+	
+	```ruby
+	module ProcessBooking
+	  class Workflow < Ask::Graph
+	    step BookAppointment
+	    approve ReviewBooking, if: :expensive?
+	    step ConfirmBooking
+	  end
+	end
+	```
+	
+	After `approve` pauses, resume with:
+	
+	```ruby
+	graph = ProcessBooking::Workflow.new
+	result = graph.run              # runs, pauses after ReviewBooking
+	result = graph.resume(input: "approved")  # resumes, runs ConfirmBooking
+	```
+
+	### Per-item loops
+	
+	Use `context.each` inside a step for iteration with automatic checkpointing:
+	
+	```ruby
+	class SendVoiceReminders
+	  def call(context)
+	    context.each(context.appointments) do |appt|
+	      PhoneService.call(appt.number, appt.message)
+	    end
+	  end
+	end
+	
+	module DailyReminders
+	  class Workflow < Ask::Graph
+	    step FetchAppointments
+	    step SendVoiceReminders  # loops with per-item checkpointing
+	    step MarkComplete
+	  end
+	end
+	```
 
 If the process crashes mid-loop, it resumes from the last completed item.
 
@@ -146,33 +158,48 @@ end
 
 ### Sub-workflows
 
-A step can delegate to another workflow:
+A step can delegate to another workflow by calling `Workflow.call(context)`.
+The context is automatically exported, passed to the sub-workflow, and
+results are merged back on completion:
 
 ```ruby
-class IntentHandler
-  def call(context)
-    case context.intent
-    when "booking"
-      BookingWorkflow.new.call(context)  # sub-workflow as a step
-    when "emergency"
-      EmergencyWorkflow.new.call(context)
+module OrderFulfillment
+  class NotifyCustomer
+    def call(context)
+      NotifyCustomer::Workflow.call(context)
     end
   end
+
+  class Workflow < Ask::Graph
+    step ValidatePayment
+    step NotifyCustomer
+    step ShipOrder
+  end
+end
+```
+
+Or use `context.run` for the same thing:
+
+```ruby
+class NotifyCustomer
+  def call(context)
+    context.run(NotifyCustomer::Workflow)
+  end
 end
 ```
 
 ### Checkpointing
 
-Pass a checkpoint store to make workflows durable across crashes:
+Pass a `storage` backend to make workflows durable across crashes:
 
 ```ruby
 store = Ask::State::Memory.new  # or Redis, SQLite, etc.
 
 # Runs through all steps, saving after each
-result = MyWorkflow.run(input, checkpoint_store: store)
+result = OrderFulfillment::Workflow.call(input, storage: store)
 
 # If a crash occurs, resume from the last completed step
-result = MyWorkflow.run(input, checkpoint_store: store)
+result = OrderFulfillment::Workflow.call(input, storage: store)
 ```
 
 ### Error handling
@@ -180,12 +207,14 @@ result = MyWorkflow.run(input, checkpoint_store: store)
 Failed steps raise `Ask::Graph::StepFailed` with the step name:
 
 ```ruby
-class MyGraph < Ask::Graph
-  step RiskyOperation
+module MyWorkflow
+  class Workflow < Ask::Graph
+    step RiskyOperation
+  end
 end
 
 begin
-  MyGraph.run
+  MyWorkflow::Workflow.call
 rescue Ask::Graph::StepFailed => e
   puts e.message  # => "RiskyOperation failed: connection timeout"
 end

data/lib/ask/graph/context.rb

@@ -123,6 +123,27 @@ module Ask
         @mutex.synchronize { @store.merge!(data) }
       end
 
+      # Run an {Ask::Graph} as a sub-graph, merging its context back.
+      #
+      # Exports the current context data, creates the sub-graph with it,
+      # runs it, and merges any results back into this context.
+      #
+      # @param graph_class [Class < Ask::Graph] the graph to run
+      # @return [Ask::Graph::Context] the sub-graph's context
+      # @example
+      #   # Inside a step PORO
+      #   class CalculateShipping
+      #     def call(context)
+      #       context.run(Shipping::Workflow)
+      #     end
+      #   end
+      def run(graph_class)
+        sub = graph_class.new(export_data)
+        sub_ctx = sub.call
+        import(sub_ctx)
+        sub_ctx
+      end
+
       private
 
       # Recursively convert a value to a JSON-safe structure.

data/lib/ask/graph/runner.rb

@@ -133,29 +133,14 @@ module Ask
       end
 
       def run_single(klass, _name, context)
-        if klass < Ask::Graph
-          run_subgraph(klass, context)
-        else
-          instance = klass.new
-          instance.call(context)
-        end
-      rescue Paused, ArgumentError
+        instance = klass.new
+        instance.call(context)
+      rescue Paused
         raise
       rescue => e
         raise StepFailed, "#{klass.name} failed: #{e.message}"
       end
 
-      def run_subgraph(klass, context)
-        if klass.respond_to?(:declarations) && klass.declarations.any? { |d| d[:type] == :approve }
-          raise ArgumentError,
-                "#{klass.name} contains approve steps — sub-graphs with approve are not yet supported"
-        end
-
-        sub = klass.new(context.export_data, storage: @store)
-        sub_ctx = sub.call
-        context.import(sub_ctx) if sub_ctx
-      end
-
       def run_parallel(classes, _name, context)
         threads = classes.map do |klass|
           Thread.new do

data/lib/ask/graph/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   class Graph
-    VERSION = "0.5.0"
+    VERSION = "0.6.1"
   end
 end

data/lib/ask/graph.rb

@@ -11,21 +11,34 @@ module Ask
   # lifecycle hooks.
   #
   # @example Basic workflow
-  #   class HandleCall < Ask::Graph
+  #   class HandleCall::Workflow < Ask::Graph
   #     step Transcribe
   #     step Classify, if: :needs_classification?
   #     step BookAppointment
   #   end
   #
-  # @example Sub-graph composition (reuse a graph as a step)
-  #   class NotifyCustomer < Ask::Graph
-  #     step SendEmail
-  #     step LogNotification
+  # @example Sub-graph composition
+  #   # Define a reusable workflow
+  #   module NotifyCustomer
+  #     class Workflow < Ask::Graph
+  #       step SendEmail
+  #       step LogNotification
+  #     end
   #   end
   #
-  #   class HandleOrder < Ask::Graph
+  #   # Wrap it in a PORO step
+  #   module OrderFulfillment
+  #     class NotifyCustomer
+  #       def call(context)
+  #         NotifyCustomer::Workflow.call(context)
+  #       end
+  #     end
+  #   end
+  #
+  #   # Compose — every step is a PORO
+  #   class OrderFulfillment::Workflow < Ask::Graph
   #     step ValidatePayment
-  #     step NotifyCustomer   # runs the sub-graph, merges its context
+  #     step NotifyCustomer
   #     step ShipOrder
   #   end
   #
@@ -56,7 +69,8 @@ module Ask
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@declarations, declarations.dup)
-        subclass.instance_variable_set(:@lifecycle_hooks, lifecycle_hooks.dup)
+        subclass.instance_variable_set(:@lifecycle_hooks,
+          lifecycle_hooks.transform_values(&:dup))
       end
 
       # --- Timeout ---
@@ -187,9 +201,29 @@ module Ask
         declarations << build_declaration(:approve, klass, opts)
       end
 
-      # Convenience: create instance and call.
+      # Create an instance and run it.
+      #
+      # When +input+ is a {Context}, the graph is run as a sub-graph:
+      # the context data is exported, the graph runs with it, and results
+      # are merged back into the original context automatically.
+      #
+      # @example Standalone — pass data
+      #   OrderFulfillment::Workflow.call({ user: "alice" })
+      #
+      # @example Inside a step — pass the outer context
+      #   class ValidatePayment
+      #     def call(context)
+      #       PaymentGateway::Workflow.call(context)
+      #     end
+      #   end
       def call(input = nil, storage: nil)
-        new(input, storage: storage).call
+        if input.is_a?(Context)
+          ctx = new(input.export_data, storage: storage).call
+          input.import(ctx)
+          ctx
+        else
+          new(input, storage: storage).call
+        end
       end
       alias run call
 
@@ -224,7 +258,7 @@ module Ask
     attr_reader :runner
     attr_reader :context
 
-    def call
+    def call(*)
       @context = Context.new(self, @input)
       @runner.run(@context)
       @context

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-graph
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Kaka Ruto