ask-graph 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3062914e848e9fea15dd9b02bd001946b7a3fd0ab015a1805b4e21a371b68bf
-  data.tar.gz: 17866f6bfaf40d6e195c71655ac134430747e3690ce32c355036a8e30a62bbf1
+  metadata.gz: 5bcdf4454ef1639db46defba3c2b59377dd0aa719036b27be25b77a7a805fdec
+  data.tar.gz: eef23d886d551984bbd8f1514e7bdfacc38be0d4b029ec832b1e7c61f2d2036f
 SHA512:
-  metadata.gz: ac9dad679a58246c1bd04d67de6812e9126f8f341edad4a72e842b80b759bcf2e020a2ad0c5bedd625eff861f22f0cbb224d4d2dc058a136d4c13087c4420248
-  data.tar.gz: b0f7285fd1e447c3f48e06d061aa441f64bb37de1952022e22e44835c3b549c639bceec13d9a690d0d14becb5eb724e1d2f31c05ea47a514ba2be57d9680de3b
+  metadata.gz: bef581ebc5816f79ab0b8d7da98dd9cf53fba824e1e68691e5b39ef8ee0eca3380fa2994dde965ad17db24267f9541b4c537c87fa26a3852ba9fa128afc60237
+  data.tar.gz: 78d63a0b802ee4050d09a08ab4d6f62a7fa8e71425745ef055d2f02824c6fb92f48c3149fadb275723aefb93b04bf0a04c258246b115c4ad028b5a56179a9188

data/CHANGELOG.md

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

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

@@ -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.4.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

metadata

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