ask-graph 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99d66a3b6b63d97a13187b67bbefd25c291d5ab80a63146e61639a0b7949689d
-  data.tar.gz: ab66b1d0586ee8570e71f2612938d6d87a9e3c5a3d44b93b046ef95343a5951a
+  metadata.gz: 8035b4d2c2a93881c2733cb41e33696fe6e7403b2233a709c89ac75e1035323a
+  data.tar.gz: 04c96e95ec9b0afa00133f100627250ae26dc87d9208be62b22246f80548eaa7
 SHA512:
-  metadata.gz: 8cd5ca7104c5ea6f643e9f9333ec8a7578b53f0fcda6c0f8a5a4273ac9cbb856025024e192a9f89c4a30fc3c8072b6b2b46283ccdf3805db05faade627fef81c
-  data.tar.gz: f8f4e2494be0350b17b86f568c1de1428a1731b73f9599132f6fe408a70fed15649c803847cf01a36ba009b819f2bcfaf3f37df6d8db2a8dd36dface2c8ae01b
+  metadata.gz: 3a365f235bb392a4be69981dd816bc6f961ea68a1fe740e094fe07a4b1a5f7f39839261ba75784b5028a6a82b7add2351e9f10c97695a7a9edeb00b512cf4d67
+  data.tar.gz: fabd27780966a9877e4a17b014388fcad7c3c57fdfbe9df8bc433ba15d05960fe3542f09c6f9501e388d147197a5d84c85964b59646f3b245a44cdb03ba13a6d

data/CHANGELOG.md

@@ -1,3 +1,46 @@
+## [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

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.1"
+    VERSION = "0.7.0"
   end
 end

data/lib/ask/graph.rb

@@ -73,36 +73,68 @@ module Ask
           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?(:@timeout)
-            @timeout
-          elsif superclass.respond_to?(:timeout)
-            superclass.timeout
+          if instance_variable_defined?(:@step_timeout)
+            @step_timeout
+          elsif superclass.respond_to?(:step_timeout)
+            superclass.step_timeout
           end
         else
-          @timeout = seconds
+          @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?(:@workflow_timeout)
+            @workflow_timeout
+          elsif superclass.respond_to?(:workflow_timeout)
+            superclass.workflow_timeout
+          end
+        else
+          @workflow_timeout = seconds
+        end
+      end
+      alias default_workflow_timeout workflow_timeout
 
       # --- Storage ---
 
@@ -251,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.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Kaka Ruto