ask-graph 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59959ae9ec12f0d79aecfe21ae07748baa067bb47efb9c519d291dd352032873
-  data.tar.gz: ea54f68d9693259b6fbe2833693391e7844c26b9f442551af09fe3d1e4d6b84d
+  metadata.gz: 5bcdf4454ef1639db46defba3c2b59377dd0aa719036b27be25b77a7a805fdec
+  data.tar.gz: eef23d886d551984bbd8f1514e7bdfacc38be0d4b029ec832b1e7c61f2d2036f
 SHA512:
-  metadata.gz: 221a7565d2feb4ac3769793dbb510687b56f0058bc259ecf94a32acb59e4d8dcebe23a4d7cc14888a6001ffc53a3e06bbc940e45032138dcd734fb6476b76a28
-  data.tar.gz: 68e22b21cffae4f146781926d89dd7c767f31234212181ce60707f9dd8e35ec90841f868677517d772a0221ca80fe7a53b15f93a7a067f6c5a280c4ebd5e7ae4
+  metadata.gz: bef581ebc5816f79ab0b8d7da98dd9cf53fba824e1e68691e5b39ef8ee0eca3380fa2994dde965ad17db24267f9541b4c537c87fa26a3852ba9fa128afc60237
+  data.tar.gz: 78d63a0b802ee4050d09a08ab4d6f62a7fa8e71425745ef055d2f02824c6fb92f48c3149fadb275723aefb93b04bf0a04c258246b115c4ad028b5a56179a9188

data/CHANGELOG.md

@@ -1,3 +1,98 @@
+## [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.
+
+  ```ruby
+  class NotifyCustomer < Ask::Graph
+    step SendEmail
+    step LogNotification
+  end
+
+  class HandleOrder < Ask::Graph
+    step ValidatePayment
+    step NotifyCustomer   # runs the sub-graph, merges its context
+    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)
+  - 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
+
+- **`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.
+
+- **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.
+
+  ```ruby
+  g.new({ value: 42 }).call
+  ctx.value   # => 42 (new — directly accessible)
+  ctx.input   # => { value: 42 } (still works)
+  ```
+
+### Limitations
+
+- Sub-graphs containing `approve` steps are not yet supported and raise
+  `ArgumentError`. Nested approval will be added in a future release.
+
+### Tested
+
+- 87 tests, 114 assertions, 0 failures
+
+## [0.4.0] — 2026-07-27
+
+### Changed
+
+- **`checkpoint_store:` renamed to `storage:`** — shorter, more general name
+  for the backend that persists checkpoint data for crash recovery.
+
+  ```ruby
+  # Before
+  MyGraph.call(input, checkpoint_store: RedisPool.new)
+  g.new(input, checkpoint_store: RedisPool.new)
+
+  # After
+  MyGraph.call(input, storage: RedisPool.new)
+  g.new(input, storage: RedisPool.new)
+  ```
+
+### Added
+
+- **Class-level `storage`** — set once at the class level instead of passing
+  per-call. Works the same as `timeout`: per-call → graph class → global.
+
+  ```ruby
+  # Global default for all graphs
+  Ask::Graph.storage RedisPool.new
+
+  # Per-graph override
+  class MyGraph < Ask::Graph
+    storage PostgresStore.new
+  end
+
+  # Per-call override (overrides everything)
+  MyGraph.call(input, storage: InMemory.new)
+  ```
+
+  Falls back to `Ask::State::Memory.new` when nothing is configured.
+
+### Tested
+
+- 70 tests, 92 assertions, 0 failures
+
 ## [0.3.0] — 2026-07-27
 
 ### Added

data/lib/ask/graph/context.rb

@@ -31,7 +31,12 @@ module Ask
         @item = nil
         @mutex = Mutex.new
         @resume_input = nil
-        @store[:input] = input if input
+        if input.is_a?(Hash)
+          @store[:input] = input
+          @store.merge!(input)
+        elsif input
+          @store[:input] = input
+        end
       end
 
       # @return [Object, nil] input provided on resume for approval steps
@@ -102,6 +107,22 @@ module Ask
         end
       end
 
+      # @return [Hash] raw store data with original object references.
+      # Unlike {to_h}, this returns the actual Ruby objects without
+      # serialization. Useful for passing state to sub-graphs.
+      def export_data
+        @mutex.synchronize { @store.dup }
+      end
+
+      # Merge data from another context (or hash) into this one.
+      # Existing keys in this context are overwritten.
+      #
+      # @param other [Context, Hash] source of data to merge in
+      def import(other)
+        data = other.is_a?(Context) ? other.export_data : other
+        @mutex.synchronize { @store.merge!(data) }
+      end
+
       private
 
       # Recursively convert a value to a JSON-safe structure.

data/lib/ask/graph/runner.rb

@@ -21,16 +21,16 @@ module Ask
       attr_reader :declarations, :store
 
       # @param declarations [Array<Hash>] step declarations
-      # @param checkpoint_store [#set, #get, #delete] key-value store
+      # @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
-      def initialize(declarations, checkpoint_store: nil,
+      def initialize(declarations, storage: nil,
                      hooks: { before_step: [], after_step: [], on_failure: [] },
                      graph_instance: nil,
                      default_timeout: nil)
         @declarations = declarations
-        @store = checkpoint_store
+        @store = storage
         @hooks = hooks
         @graph = graph_instance
         @default_timeout = default_timeout
@@ -133,14 +133,29 @@ module Ask
       end
 
       def run_single(klass, _name, context)
-        instance = klass.new
-        instance.call(context)
-      rescue Paused
+        if klass < Ask::Graph
+          run_subgraph(klass, context)
+        else
+          instance = klass.new
+          instance.call(context)
+        end
+      rescue Paused, ArgumentError
         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.3.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/ask/graph.rb

@@ -6,8 +6,9 @@ require_relative "graph/runner"
 
 module Ask
   # Define durable workflow graphs with named steps, conditional routing,
-  # parallel execution, human-in-the-loop approval, per-item checkpointing
-  # loops, step timeouts, retry policies, and lifecycle hooks.
+  # parallel execution, sub-graph composition, human-in-the-loop approval,
+  # per-item checkpointing loops, step timeouts, retry policies, and
+  # lifecycle hooks.
   #
   # @example Basic workflow
   #   class HandleCall < Ask::Graph
@@ -16,6 +17,18 @@ module Ask
   #     step BookAppointment
   #   end
   #
+  # @example Sub-graph composition (reuse a graph as a step)
+  #   class NotifyCustomer < Ask::Graph
+  #     step SendEmail
+  #     step LogNotification
+  #   end
+  #
+  #   class HandleOrder < Ask::Graph
+  #     step ValidatePayment
+  #     step NotifyCustomer   # runs the sub-graph, merges its context
+  #     step ShipOrder
+  #   end
+  #
   # @example With timeout and retry
   #   class ApiWorkflow < Ask::Graph
   #     step FetchData, timeout: 30, retry: 3
@@ -77,6 +90,39 @@ module Ask
         end
       end
 
+      # --- Storage ---
+
+      # Set or get the default storage backend for checkpoint data.
+      # The storage object must respond to +#set(key, value)+ and +#get(key)+.
+      #
+      # Setting on {Ask::Graph} itself applies to all graphs that don't set
+      # their own storage — a global default.
+      #
+      # @example Global default for all graphs
+      #   Ask::Graph.storage RedisPool.new
+      #
+      # @example Per-graph override
+      #   class MyGraph < Ask::Graph
+      #     storage PostgresStore.new
+      #   end
+      #
+      # @example Per-call override
+      #   MyGraph.call(input, storage: InMemory.new)
+      #
+      # @param store [Object, nil] a backend that responds to +#set+ and +#get+
+      # @return [Object, nil] the current storage for this graph
+      def storage(store = :not_set)
+        if store == :not_set
+          if instance_variable_defined?(:@storage)
+            @storage
+          elsif superclass.respond_to?(:storage)
+            superclass.storage
+          end
+        else
+          @storage = store
+        end
+      end
+
       # --- Lifecycle hooks ---
 
       def lifecycle_hooks
@@ -142,8 +188,8 @@ module Ask
       end
 
       # Convenience: create instance and call.
-      def call(input = nil, checkpoint_store: nil)
-        new(input, checkpoint_store: checkpoint_store).call
+      def call(input = nil, storage: nil)
+        new(input, storage: storage).call
       end
       alias run call
 
@@ -163,12 +209,12 @@ module Ask
       end
     end
 
-    def initialize(input = nil, checkpoint_store: nil)
+    def initialize(input = nil, storage: nil)
       @input = input
-      store = checkpoint_store || Ask::State::Memory.new
+      store = storage || self.class.storage || Ask::State::Memory.new
       hooks = self.class.lifecycle_hooks
       @runner = Runner.new(self.class.declarations,
-                           checkpoint_store: store,
+                           storage: store,
                            hooks: hooks,
                            graph_instance: self,
                            default_timeout: self.class.timeout)

metadata

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