ask-graph 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad07fb878d69dbb0a0bd0065e5c26275bfeda6169fa36fb6aa5688e129534b20
-  data.tar.gz: b583bbe7555a92bfdb2bb5430e7498925e6aa6019f185e5147780861f9da94d8
+  metadata.gz: 59959ae9ec12f0d79aecfe21ae07748baa067bb47efb9c519d291dd352032873
+  data.tar.gz: ea54f68d9693259b6fbe2833693391e7844c26b9f442551af09fe3d1e4d6b84d
 SHA512:
-  metadata.gz: b2baa9116d362d868462bd420c968a52b887f27df32fef51f040180012df815af84b1f33b29ddc7794e896bae3e53779995019ce9515835a83371b9d3d572513
-  data.tar.gz: 7b3bcde81e887dddb9b9e2a51f2844eff4ea4d5f4197f40d41c3bf15c5d79b986b2153d409ebf37d902b3c05fdddf55a2596de153cd4b2732fd501d7786234fc
+  metadata.gz: 221a7565d2feb4ac3769793dbb510687b56f0058bc259ecf94a32acb59e4d8dcebe23a4d7cc14888a6001ffc53a3e06bbc940e45032138dcd734fb6476b76a28
+  data.tar.gz: 68e22b21cffae4f146781926d89dd7c767f31234212181ce60707f9dd8e35ec90841f868677517d772a0221ca80fe7a53b15f93a7a067f6c5a280c4ebd5e7ae4

data/CHANGELOG.md

@@ -1,3 +1,69 @@
+## [0.3.0] — 2026-07-27
+
+### Added
+
+- **Class-level `timeout`** — set a default timeout for all steps in a graph.
+  Steps without an explicit `timeout:` option inherit the class default.
+
+  ```ruby
+  class MyGraph < Ask::Graph
+    timeout 30
+    step FastOp   # uses 30s
+    step SlowOp, timeout: 120  # overrides
+  end
+  ```
+
+- **Global default timeout** — `Ask::Graph.timeout 30` applies to all graphs
+  that don't set their own `timeout`. Resolution order: step option → graph
+  class → `Ask::Graph`.
+
+  ```ruby
+  Ask::Graph.timeout 30
+  ```
+
+- **Child override and clearing** — child graphs can override or clear
+  (`timeout nil`) the parent's default.
+
+### Tested
+
+- 62 tests, 83 assertions, 0 failures
+
+## [0.2.0] — 2026-07-29
+
+### Added
+
+- **Step timeouts** — `step SlowOp, timeout: 30` raises `StepFailed` if a step takes longer than the given seconds.
+
+  ```ruby
+  step FetchApi, timeout: 10, retry: 2
+  ```
+
+- **Retry policy** — `step FlakyOp, retry: 3` retries failed steps up to the specified number of times with exponential backoff.
+
+  ```ruby
+  step ApiCall, retry: 3
+  ```
+
+- **Lifecycle hooks** — `before_step`, `after_step`, and `on_failure` hooks for observability, logging, and monitoring.
+
+  ```ruby
+  class MyGraph < Ask::Graph
+    before_step :log_start
+    after_step  :log_completion
+    on_failure  :alert_team
+
+    step ProcessPayment, timeout: 15, retry: 2
+  end
+  ```
+
+  Hooks receive `declaration:` and `context:` keyword args. `on_failure` also receives `error:`.
+
+- **Step metadata** — `step X, description: "Human-readable label"` stores metadata in the declaration for debugging and monitoring.
+
+### Tested
+
+- 55 tests, 73 assertions, 0 failures
+
 ## [0.1.3] — 2026-07-28
 
 ### Changed

data/lib/ask/graph/runner.rb

@@ -1,41 +1,42 @@
 # frozen_string_literal: true
 
 require "json"
+require "timeout"
 
 module Ask
   class Graph
     # Error raised when a step fails.
     class StepFailed < StandardError; end
 
+    # Error raised when a step times out.
+    class StepTimeout < StandardError; end
+
     # Error raised when a step pauses for human approval.
     class Paused < StandardError; end
 
     # Executes the declared steps of a graph, managing checkpointing,
-    # condition evaluation, parallel execution, and human-in-the-loop pauses.
-    #
-    # Checkpoints save the full context state after each step so that
-    # crashes resume from the last completed step with all data intact.
-    # Uses an in-memory store by default; pass a persistent store for
-    # crash recovery across restarts.
+    # condition evaluation, parallel execution, timeouts, retries,
+    # lifecycle hooks, and human-in-the-loop pauses.
     class Runner
-      # @return [Array<Hash>] step declarations with name, type, condition
-      attr_reader :declarations
-
-      # @return [#set, #get, #delete] the checkpoint store
-      attr_reader :store
+      attr_reader :declarations, :store
 
       # @param declarations [Array<Hash>] step declarations
-      # @param checkpoint_store [#set, #get, #delete] key-value store.
-      #   Defaults to in-memory (no durability across restarts).
-      def initialize(declarations, checkpoint_store: nil)
+      # @param checkpoint_store [#set, #get, #delete] key-value store
+      # @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
+      def initialize(declarations, checkpoint_store: nil,
+                     hooks: { before_step: [], after_step: [], on_failure: [] },
+                     graph_instance: nil,
+                     default_timeout: nil)
         @declarations = declarations
         @store = checkpoint_store
+        @hooks = hooks
+        @graph = graph_instance
+        @default_timeout = default_timeout
         @completed_steps = []
       end
 
-      # Run the graph from the beginning or resume from the last checkpoint.
-      # @param context [Ask::Graph::Context] the shared context
-      # @return [Ask::Graph::Context] the completed context
       def run(context)
         resume_index = load_checkpoint(context)
 
@@ -47,7 +48,10 @@ module Ask
             next
           end
 
-          execute_step(decl, context)
+          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
@@ -55,26 +59,17 @@ module Ask
         context
       end
 
-      # Resume a paused graph with human input.
-      # @param context [Ask::Graph::Context] the context at pause point
-      # @param input [Object] the human's input
-      # @return [Ask::Graph::Context] the completed context
       def resume(context, input:)
         context.resume_input = input
         run(context)
       end
 
-      # Get the index to resume from for an {Context#each} iteration.
-      # @param items [Array] the full list of items
-      # @return [Integer, nil] the index to resume from, or nil
       def resume_index_for(items)
         key = each_checkpoint_key
         raw = @store.get(key)
         raw ? raw.to_i : nil
       end
 
-      # Checkpoint after a single iteration of {Context#each}.
-      # @param index [Integer] the completed iteration index
       def checkpoint_each!(index)
         key = each_checkpoint_key
         @store.set(key, index.to_s)
@@ -82,6 +77,50 @@ module Ask
 
       private
 
+      def execute_with_retry(decl, context)
+        retries = decl[:retry] || 0
+
+        (retries + 1).times do |attempt|
+          begin
+            run_with_timeout(decl, context, decl[:timeout])
+            return
+          rescue StepFailed => e
+            run_hooks(:on_failure, decl, context, error: e)
+            raise if attempt >= retries
+            sleep backoff_seconds(attempt, decl[:backoff])
+          end
+        end
+      end
+
+      def run_with_timeout(decl, context, timeout_value)
+        timeout_value ||= @default_timeout
+        if timeout_value
+          ::Timeout.timeout(timeout_value) { execute_step(decl, context) }
+        else
+          execute_step(decl, context)
+        end
+      rescue ::Timeout::Error
+        raise StepFailed, "#{decl[:name]} timed out after #{timeout_value}s"
+      end
+
+      def backoff_seconds(attempt, strategy)
+        return 0 if attempt == 0
+        case strategy
+        when :exponential then 2 ** attempt
+        when :constant then 2
+        else 2 ** attempt
+        end
+      end
+
+      def run_hooks(hook_type, decl, context, error: nil)
+        @hooks[hook_type]&.each do |method_name|
+          next unless @graph&.respond_to?(method_name, true)
+          args = { declaration: decl, context: context }
+          args[:error] = error if error
+          @graph.send(method_name, **args)
+        end
+      end
+
       def execute_step(decl, context)
         case decl[:type]
         when :step
@@ -98,19 +137,17 @@ module Ask
         instance.call(context)
       rescue Paused
         raise
-      rescue StandardError => e
+      rescue => e
         raise StepFailed, "#{klass.name} failed: #{e.message}"
       end
 
       def run_parallel(classes, _name, context)
         threads = classes.map do |klass|
           Thread.new do
-            begin
-              instance = klass.new
-              instance.call(context)
-            rescue StandardError => e
-              raise StepFailed, "#{klass.name} failed: #{e.message}"
-            end
+            instance = klass.new
+            instance.call(context)
+          rescue => e
+            raise StepFailed, "#{klass.name} failed: #{e.message}"
           end
         end
         threads.each(&:join)
@@ -149,8 +186,6 @@ module Ask
         "#{checkpoint_key}:each"
       end
 
-      # Save checkpoint with full context state so resumed graphs
-      # have access to all data produced by completed steps.
       def save_checkpoint(context, idx)
         data = {
           completed_index: idx,
@@ -160,8 +195,6 @@ module Ask
         @store.set(checkpoint_key, JSON.generate(data))
       end
 
-      # Load checkpoint and restore context state if available.
-      # Returns the completed_index to skip, or nil for a fresh run.
       def load_checkpoint(context)
         raw = @store.get(checkpoint_key)
         return nil unless raw

data/lib/ask/graph/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   class Graph
-    VERSION = "0.1.3"
+    VERSION = "0.3.0"
   end
 end

data/lib/ask/graph.rb

@@ -6,8 +6,8 @@ require_relative "graph/runner"
 
 module Ask
   # Define durable workflow graphs with named steps, conditional routing,
-  # parallel execution, human-in-the-loop approval, and per-item
-  # checkpointing loops.
+  # parallel execution, human-in-the-loop approval, per-item checkpointing
+  # loops, step timeouts, retry policies, and lifecycle hooks.
   #
   # @example Basic workflow
   #   class HandleCall < Ask::Graph
@@ -16,11 +16,21 @@ module Ask
   #     step BookAppointment
   #   end
   #
-  #   result = HandleCall.new.call(recording: "call.wav")
+  # @example With timeout and retry
+  #   class ApiWorkflow < Ask::Graph
+  #     step FetchData, timeout: 30, retry: 3
+  #     step ProcessData, description: "Transform raw data into reports"
+  #   end
+  #
+  # @example With lifecycle hooks
+  #   class MonitoredWorkflow < Ask::Graph
+  #     before_step :log_start
+  #     after_step  :log_completion
+  #     on_failure  :alert_team
   #
-  # @example With checkpointing
-  #   store = Ask::State::Memory.new
-  #   result = HandleCall.new.call(input, checkpoint_store: store)
+  #     step ValidateOrder
+  #     step ProcessPayment, timeout: 15, retry: 2
+  #   end
   #
   class Graph
     class << self
@@ -33,33 +43,91 @@ module Ask
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@declarations, declarations.dup)
+        subclass.instance_variable_set(:@lifecycle_hooks, lifecycle_hooks.dup)
+      end
+
+      # --- Timeout ---
+
+      # Set or get the default timeout (in seconds) for steps in this graph.
+      # Steps without an explicit +timeout:+ option will 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
+      #
+      # @example Per-graph override
+      #   class MyGraph < Ask::Graph
+      #     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)
+        if seconds == :not_set
+          if instance_variable_defined?(:@timeout)
+            @timeout
+          elsif superclass.respond_to?(:timeout)
+            superclass.timeout
+          end
+        else
+          @timeout = seconds
+        end
+      end
+
+      # --- Lifecycle hooks ---
+
+      def lifecycle_hooks
+        @lifecycle_hooks ||= { before_step: [], after_step: [], on_failure: [] }
+      end
+
+      # Register a callback to run before every step.
+      # @param method_name [Symbol] method name on the graph class
+      def before_step(method_name)
+        lifecycle_hooks[:before_step] << method_name
+      end
+
+      # Register a callback to run after every successful step.
+      # @param method_name [Symbol] method name on the graph class
+      def after_step(method_name)
+        lifecycle_hooks[:after_step] << method_name
+      end
+
+      # Register a callback to run when a step fails.
+      # @param method_name [Symbol] method name on the graph class
+      def on_failure(method_name)
+        lifecycle_hooks[:on_failure] << method_name
       end
 
+      # --- Step declarations ---
+
       # Declare a sequential step.
       #
       # @param klass [Class] a class that responds to +#call(context)+
-      # @param conditions [Hash] optional +if:+ or +unless:+ condition method name
-      def step(klass, **conditions)
-        declarations << {
-          class: klass,
-          type: :step,
-          name: klass.name || klass.to_s,
-          if: conditions[:if],
-          unless: conditions[:unless]
-        }
+      # @param conditions [Hash] optional +if:+ or +unless:+ condition method name,
+      #   +description:+ human-readable label, +timeout:+ seconds,
+      #   +retry:+ number of retries on failure
+      def step(klass, **opts)
+        declarations << build_declaration(:step, klass, opts)
       end
 
       # Declare parallel steps — all run simultaneously.
       #
       # @param klasses [Array<Class>] step classes to run in parallel
-      # @param conditions [Hash] optional +if:+ or +unless:+ condition method name
-      def steps(*klasses, **conditions)
+      # @param opts [Hash] optional +if:+, +unless:+, +timeout:+ seconds,
+      #   +retry:+ number of retries
+      def steps(*klasses, **opts)
         declarations << {
           classes: klasses,
           type: :steps,
           name: klasses.map { |k| k.name || k.to_s }.join(", "),
-          if: conditions[:if],
-          unless: conditions[:unless]
+          if: opts[:if],
+          unless: opts[:unless],
+          description: opts[:description],
+          timeout: opts[:timeout],
+          retry: opts[:retry]
         }
       end
 
@@ -67,45 +135,49 @@ module Ask
       # and waits for external input via {Ask::Graph#resume}.
       #
       # @param klass [Class] a class that responds to +#call(context)+
-      # @param conditions [Hash] optional +if:+ or +unless:+ condition method name
-      def approve(klass, **conditions)
-        declarations << {
-          class: klass,
-          type: :approve,
-          name: klass.name || klass.to_s,
-          if: conditions[:if],
-          unless: conditions[:unless]
-        }
+      # @param opts [Hash] optional +if:+, +unless:+, +description:+,
+      #   +timeout:+, +retry:+
+      def approve(klass, **opts)
+        declarations << build_declaration(:approve, klass, opts)
       end
 
       # Convenience: create instance and call.
-      # @param input [Object] optional input
-      # @param checkpoint_store [#set, #get, #delete] optional persistent store
-      # @return [Ask::Graph::Context] the completed context
       def call(input = nil, checkpoint_store: nil)
         new(input, checkpoint_store: checkpoint_store).call
       end
       alias run call
+
+      private
+
+      def build_declaration(type, klass, opts)
+        {
+          class: klass,
+          type: type,
+          name: klass.name || klass.to_s,
+          if: opts[:if],
+          unless: opts[:unless],
+          description: opts[:description],
+          timeout: opts[:timeout],
+          retry: opts[:retry]
+        }
+      end
     end
 
-    # @param input [Object, nil] initial input for the graph execution
-    # @param checkpoint_store [#set, #get, #delete, nil] optional persistent store.
-    #   Defaults to in-memory store. Pass a persistent store for crash recovery.
     def initialize(input = nil, checkpoint_store: nil)
       @input = input
       store = checkpoint_store || Ask::State::Memory.new
-      @runner = Runner.new(self.class.declarations, checkpoint_store: store)
+      hooks = self.class.lifecycle_hooks
+      @runner = Runner.new(self.class.declarations,
+                           checkpoint_store: store,
+                           hooks: hooks,
+                           graph_instance: self,
+                           default_timeout: self.class.timeout)
       @context = nil
     end
 
-    # @return [Ask::Graph::Runner] the runner (exposed for checkpoint coordination)
     attr_reader :runner
-
-    # @return [Ask::Graph::Context, nil] the shared context
     attr_reader :context
 
-    # Execute the graph.
-    # @return [Ask::Graph::Context] the completed context
     def call
       @context = Context.new(self, @input)
       @runner.run(@context)
@@ -116,9 +188,6 @@ module Ask
     end
     alias run call
 
-    # Resume a paused graph with human input.
-    # @param input [Object] the human's input
-    # @return [Ask::Graph::Context] the completed context
     def resume(input:)
       @context.resume_input = input.to_s
       @runner.run(@context)

metadata

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