ask-graph 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67250ca086cc687aff14bda7a2365e1f170eea92c8cd4f88565ec8b678ee8d9c
-  data.tar.gz: 3450ffce0b35cadd19798757116e2bbc6a82a9460f4686187131061f63ba8663
+  metadata.gz: 8035b4d2c2a93881c2733cb41e33696fe6e7403b2233a709c89ac75e1035323a
+  data.tar.gz: 04c96e95ec9b0afa00133f100627250ae26dc87d9208be62b22246f80548eaa7
 SHA512:
-  metadata.gz: cbef57c596215023c161198fc5951316777ba9686428fce403ce62e498b24e22edc1d40d9a1eec56ad010c397419ad1069219e16bad22b1768ff516e03df7cff
-  data.tar.gz: 830f3ea4c53e3db5ef8e26ba1bb22f105bf05e2419dba92bc6a113d1b2ae7fe6f40d3c866fc8cf4429d7f5649717ad9c9f6a1d389e7d0cda49f4a49444b7b8b3
+  metadata.gz: 3a365f235bb392a4be69981dd816bc6f961ea68a1fe740e094fe07a4b1a5f7f39839261ba75784b5028a6a82b7add2351e9f10c97695a7a9edeb00b512cf4d67
+  data.tar.gz: fabd27780966a9877e4a17b014388fcad7c3c57fdfbe9df8bc433ba15d05960fe3542f09c6f9501e388d147197a5d84c85964b59646f3b245a44cdb03ba13a6d

data/CHANGELOG.md

@@ -1,3 +1,81 @@
+## [0.7.0] — 2026-07-31
+
+### Added
+
+- **`workflow_timeout`** — total runtime cap for the entire workflow. The
+  whole run aborts with `Ask::Graph::WorkflowTimeout` if it exceeds the
+  limit, regardless of individual step timeouts.
+
+  ```ruby
+  class MyWorkflow < Ask::Graph
+    workflow_timeout 60   # whole workflow must finish within 60s
+    step FetchData, timeout: 30
+    step ProcessData, timeout: 30
+  end
+  ```
+
+- **`Ask::Graph.default_workflow_timeout`** — global default total cap for
+  all graphs that don't set their own.
+
+### Changed
+
+- **`timeout` renamed to `step_timeout`** — the class-level default timeout
+  per step is now `step_timeout`. The inline step option `step X, timeout: 10`
+  is unchanged. No alias is kept — the gem is pre-1.0.
+
+  ```ruby
+  # Before
+  class MyWorkflow < Ask::Graph
+    timeout 30
+  end
+  Ask::Graph.timeout 30
+
+  # After
+  class MyWorkflow < Ask::Graph
+    step_timeout 30
+  end
+  Ask::Graph.default_step_timeout 30
+  ```
+
+### Tested
+
+- 95 tests, 129 assertions, 0 failures
+
+## [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

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

@@ -131,9 +131,10 @@ module Ask
       # @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(ShippingWorkflow)
+      #       context.run(Shipping::Workflow)
       #     end
       #   end
       def run(graph_class)

data/lib/ask/graph/runner.rb

@@ -11,6 +11,9 @@ module Ask
     # Error raised when a step times out.
     class StepTimeout < StandardError; end
 
+    # Error raised when the entire workflow exceeds its total runtime cap.
+    class WorkflowTimeout < StandardError; end
+
     # Error raised when a step pauses for human approval.
     class Paused < StandardError; end
 
@@ -24,39 +27,30 @@ module Ask
       # @param storage [#set, #get, #delete] key-value store for checkpoint data
       # @param hooks [Hash] lifecycle hook method names
       # @param graph_instance [Object] the graph instance (for hooks)
-      # @param default_timeout [Integer, nil] fallback timeout for steps with no explicit timeout
+      # @param step_timeout [Integer, nil] fallback timeout for steps with no explicit timeout
+      # @param workflow_timeout [Integer, nil] total runtime cap for the whole run
       def initialize(declarations, storage: nil,
                      hooks: { before_step: [], after_step: [], on_failure: [] },
                      graph_instance: nil,
-                     default_timeout: nil)
+                     step_timeout: nil,
+                     workflow_timeout: nil)
         @declarations = declarations
         @store = storage
         @hooks = hooks
         @graph = graph_instance
-        @default_timeout = default_timeout
+        @step_timeout = step_timeout
+        @workflow_timeout = workflow_timeout
         @completed_steps = []
       end
 
       def run(context)
-        resume_index = load_checkpoint(context)
-
-        @declarations.each_with_index do |decl, idx|
-          next if resume_index && idx <= resume_index
-
-          unless condition_met?(decl, context)
-            record_completion(idx, :skipped)
-            next
-          end
-
-          run_hooks(:before_step, decl, context)
-          execute_with_retry(decl, context)
-          run_hooks(:after_step, decl, context)
-
-          record_completion(idx, :completed)
-          save_checkpoint(context, idx)
+        if @workflow_timeout
+          ::Timeout.timeout(@workflow_timeout) { run_steps(context) }
+        else
+          run_steps(context)
         end
-
-        context
+      rescue ::Timeout::Error
+        raise WorkflowTimeout, "workflow timed out after #{@workflow_timeout}s"
       end
 
       def resume(context, input:)
@@ -77,6 +71,28 @@ module Ask
 
       private
 
+      def run_steps(context)
+        resume_index = load_checkpoint(context)
+
+        @declarations.each_with_index do |decl, idx|
+          next if resume_index && idx <= resume_index
+
+          unless condition_met?(decl, context)
+            record_completion(idx, :skipped)
+            next
+          end
+
+          run_hooks(:before_step, decl, context)
+          execute_with_retry(decl, context)
+          run_hooks(:after_step, decl, context)
+
+          record_completion(idx, :completed)
+          save_checkpoint(context, idx)
+        end
+
+        context
+      end
+
       def execute_with_retry(decl, context)
         retries = decl[:retry] || 0
 
@@ -93,7 +109,7 @@ module Ask
       end
 
       def run_with_timeout(decl, context, timeout_value)
-        timeout_value ||= @default_timeout
+        timeout_value ||= @step_timeout
         if timeout_value
           ::Timeout.timeout(timeout_value) { execute_step(decl, context) }
         else

data/lib/ask/graph/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   class Graph
-    VERSION = "0.6.0"
+    VERSION = "0.7.0"
   end
 end

data/lib/ask/graph.rb

@@ -11,28 +11,32 @@ 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
-  #   # Define a workflow
-  #   class NotifyCustomerWorkflow < Ask::Graph
-  #     step SendEmail
-  #     step LogNotification
+  #   # Define a reusable workflow
+  #   module NotifyCustomer
+  #     class Workflow < Ask::Graph
+  #       step SendEmail
+  #       step LogNotification
+  #     end
   #   end
   #
   #   # Wrap it in a PORO step
-  #   class NotifyCustomer
-  #     def call(context)
-  #       NotifyCustomerWorkflow.call(context)
+  #   module OrderFulfillment
+  #     class NotifyCustomer
+  #       def call(context)
+  #         NotifyCustomer::Workflow.call(context)
+  #       end
   #     end
   #   end
   #
   #   # Compose — every step is a PORO
-  #   class HandleOrder < Ask::Graph
+  #   class OrderFulfillment::Workflow < Ask::Graph
   #     step ValidatePayment
   #     step NotifyCustomer
   #     step ShipOrder
@@ -65,39 +69,72 @@ 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 ---
+      # --- Timeouts ---
 
-      # Set or get the default timeout (in seconds) for steps in this graph.
-      # Steps without an explicit +timeout:+ option will inherit this value.
+      # Set or get the default timeout (in seconds) for each step in this graph.
+      # Steps without an explicit +timeout:+ option inherit this value.
       # Setting on {Ask::Graph} itself applies to all graphs that don't set
       # their own default — a global default.
       #
       # @example Global default for all graphs
-      #   Ask::Graph.timeout 30
+      #   Ask::Graph.default_step_timeout 30
       #
       # @example Per-graph override
       #   class MyGraph < Ask::Graph
-      #     timeout 15
+      #     step_timeout 15
       #     step FastOp          # uses 15s
       #     step SlowOp, timeout: 60  # overrides
       #   end
       #
       # @param seconds [Integer, nil] timeout in seconds, or nil to clear
-      # @return [Integer, nil] the current default timeout for this graph
-      def timeout(seconds = :not_set)
+      # @return [Integer, nil] the current default step timeout for this graph
+      def step_timeout(seconds = :not_set)
+        if seconds == :not_set
+          if instance_variable_defined?(:@step_timeout)
+            @step_timeout
+          elsif superclass.respond_to?(:step_timeout)
+            superclass.step_timeout
+          end
+        else
+          @step_timeout = seconds
+        end
+      end
+      alias default_step_timeout step_timeout
+
+      # Set or get the total runtime cap (in seconds) for the entire graph.
+      # The whole workflow aborts with {Ask::Graph::WorkflowTimeout} if it
+      # exceeds this limit, regardless of individual step timeouts.
+      # Setting on {Ask::Graph} itself applies to all graphs that don't set
+      # their own default — a global default.
+      #
+      # @example Global default for all graphs
+      #   Ask::Graph.default_workflow_timeout 60
+      #
+      # @example Per-graph override
+      #   class MyGraph < Ask::Graph
+      #     workflow_timeout 30
+      #     step FetchData, timeout: 10
+      #     step ProcessData, timeout: 10
+      #   end
+      #
+      # @param seconds [Integer, nil] timeout in seconds, or nil to clear
+      # @return [Integer, nil] the current workflow timeout for this graph
+      def workflow_timeout(seconds = :not_set)
         if seconds == :not_set
-          if instance_variable_defined?(:@timeout)
-            @timeout
-          elsif superclass.respond_to?(:timeout)
-            superclass.timeout
+          if instance_variable_defined?(:@workflow_timeout)
+            @workflow_timeout
+          elsif superclass.respond_to?(:workflow_timeout)
+            superclass.workflow_timeout
           end
         else
-          @timeout = seconds
+          @workflow_timeout = seconds
         end
       end
+      alias default_workflow_timeout workflow_timeout
 
       # --- Storage ---
 
@@ -203,12 +240,12 @@ module Ask
       # are merged back into the original context automatically.
       #
       # @example Standalone — pass data
-      #   MyGraph.call({ user: "alice" })
+      #   OrderFulfillment::Workflow.call({ user: "alice" })
       #
       # @example Inside a step — pass the outer context
-      #   class MyStep
+      #   class ValidatePayment
       #     def call(context)
-      #       OtherGraph.call(context)
+      #       PaymentGateway::Workflow.call(context)
       #     end
       #   end
       def call(input = nil, storage: nil)
@@ -246,7 +283,8 @@ module Ask
                            storage: store,
                            hooks: hooks,
                            graph_instance: self,
-                           default_timeout: self.class.timeout)
+                           step_timeout: self.class.step_timeout,
+                           workflow_timeout: self.class.workflow_timeout)
       @context = nil
     end
 

metadata

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