ask-graph 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bcc4cd34c3c6b401b4a5e6e47ea28bfeb8fcfe6cc117c46230ddf58df6249f8
-  data.tar.gz: 20bec4635a80dd53b1b497c38985327efcef79a7acace61d8725fac85842e2ce
+  metadata.gz: c00714c8b8feb0d71aa93636f39f077b14f19ef5405efdc667317f4fe99cc6a2
+  data.tar.gz: 29cc8acc5187762918a2084bd2f3578df5ee5e6383a3b6d1edde1e4df519604a
 SHA512:
-  metadata.gz: a122a01aa42024e4be602f8fe859e0b3148867c248e36d434e86b63ad62561b53ea081cc1903c033d6aa603b89e232d981b94fda01b1f6fcf09356b31ef801eb
-  data.tar.gz: 96d289a9595599a663da22cef7357af63dc74dde4a6c399589eea339441c5a32f7b49ff77f82bfbf1232e1f548b6c3ae85aa0dd4bd2b6e430ff26a3d689d28fd
+  metadata.gz: 7291024a6f4b113e87f0cf2b6005e6dd44aa3e913dc509350e6d15fb061d64b091d05c7cd6c72dca4dae291a7a329c5d95dda94c80122b128773fda1ae510102
+  data.tar.gz: 1d5692fdd06f6a3a626f704f32bef5f75e70078846567650fb583325b188f16f2647ac17e87c0bc3c441f71ac6d1fd8ffce580fddf8f3fa7b999f462b2227079

data/CHANGELOG.md

@@ -1,3 +1,41 @@
+## [0.1.2] — 2026-07-28
+
+### Changed
+
+- **`Graph.new(input).call` API** — input is now passed to the constructor, not to `call`. This reads more naturally: create a graph with data, then execute it. `Graph.call(input, checkpoint_store:)` class method still available for convenience.
+
+  ```ruby
+  # Before
+  HandleCall.new.call(recording: "call.wav")
+
+  # After
+  HandleCall.new({ recording: "call.wav" }).call
+  ```
+
+### Tested
+
+- 36 tests, 52 assertions, 0 failures
+
+## [0.1.1] — 2026-07-28
+
+### Fixed
+
+- **Full context checkpointing** — Checkpoints now save the complete context state alongside the step index. On resume, all data produced by completed steps is restored. Previously only the step index was persisted, causing nil errors when resumed steps referenced prior outputs.
+
+- **`call` as primary API** — `Graph.new.call(input)` is now the primary interface, consistent with step classes. `Graph.call` and `Graph.run` remain as convenience class methods.
+
+- **Default in-memory store** — Checkpoint store defaults to `Ask::State::Memory` (shipped with `ask-core`, zero additional dependencies). No database, migration, or configuration needed. Pass a persistent store for crash recovery across restarts.
+
+### Changed
+
+- `context.to_h` now produces JSON-safe hashes (string keys, symbols converted to strings, arrays recursed). Checkpoints serialize correctly in Ruby 4.0.
+
+- `initialize(checkpoint_store:)` stores the checkpoint store on the instance. Pass `nil` to use the default in-memory store.
+
+### Tested
+
+- 36 tests, 52 assertions, 0 failures
+
 ## [0.1.0] — 2026-07-28
 
 ### Added

data/lib/ask/graph/context.rb

@@ -30,9 +30,13 @@ module Ask
         @each_items = nil
         @item = nil
         @mutex = Mutex.new
+        @resume_input = nil
         @store[:input] = input if input
       end
 
+      # @return [Object, nil] input provided on resume for approval steps
+      attr_accessor :resume_input
+
       # Access a stored value by method name.
       def method_missing(name, *args, &block)
         if name.to_s.end_with?("=")
@@ -89,14 +93,30 @@ module Ask
         @item = nil
       end
 
-      # @return [Hash] serializable snapshot of the context state
+      # @return [Hash] serializable snapshot of the context state.
+      # All keys and values are converted to JSON-safe types (string keys,
+      # symbols converted to strings, arrays recursed).
       def to_h
         @mutex.synchronize do
-          serializable = {}
-          @store.each do |k, v|
-            serializable[k] = v.respond_to?(:to_h) ? v.to_h : v
-          end
-          serializable
+          deep_json_safe(@store)
+        end
+      end
+
+      private
+
+      # Recursively convert a value to a JSON-safe structure.
+      def deep_json_safe(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_json_safe(v) }
+        when Array
+          value.map { |v| deep_json_safe(v) }
+        when Symbol
+          value.to_s
+        when String, Numeric, true, false, nil
+          value
+        else
+          value.respond_to?(:to_h) ? deep_json_safe(value.to_h) : value.to_s
         end
       end
     end

data/lib/ask/graph/runner.rb

@@ -12,12 +12,21 @@ module Ask
 
     # 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.
     class Runner
       # @return [Array<Hash>] step declarations with name, type, condition
       attr_reader :declarations
 
+      # @return [#set, #get, #delete] the checkpoint store
+      attr_reader :store
+
       # @param declarations [Array<Hash>] step declarations
-      # @param checkpoint_store [#set, #get, #delete] optional persistent store
+      # @param checkpoint_store [#set, #get, #delete] key-value store.
+      #   Defaults to in-memory (no durability across restarts).
       def initialize(declarations, checkpoint_store: nil)
         @declarations = declarations
         @store = checkpoint_store
@@ -28,7 +37,7 @@ module Ask
       # @param context [Ask::Graph::Context] the shared context
       # @return [Ask::Graph::Context] the completed context
       def run(context)
-        resume_index = load_checkpoint
+        resume_index = load_checkpoint(context)
 
         @declarations.each_with_index do |decl, idx|
           next if resume_index && idx <= resume_index
@@ -40,7 +49,7 @@ module Ask
 
           execute_step(decl, context)
           record_completion(idx, :completed)
-          save_checkpoint(idx)
+          save_checkpoint(context, idx)
         end
 
         context
@@ -60,7 +69,7 @@ module Ask
       # @return [Integer, nil] the index to resume from, or nil
       def resume_index_for(items)
         key = each_checkpoint_key
-        raw = @store&.get(key)
+        raw = @store.get(key)
         raw ? raw.to_i : nil
       end
 
@@ -68,7 +77,7 @@ module Ask
       # @param index [Integer] the completed iteration index
       def checkpoint_each!(index)
         key = each_checkpoint_key
-        @store&.set(key, index.to_s)
+        @store.set(key, index.to_s)
       end
 
       private
@@ -110,8 +119,7 @@ module Ask
       def run_approve(klass, _name, context)
         instance = klass.new
         instance.call(context)
-        # After the step runs, pause and wait for human input
-        save_checkpoint(current_index)
+        save_checkpoint(context, current_index)
         raise Paused, "Graph paused for approval after #{klass.name}"
       end
 
@@ -141,16 +149,28 @@ module Ask
         "#{checkpoint_key}:each"
       end
 
-      def save_checkpoint(idx)
-        data = { completed_index: idx, timestamp: Time.now.iso8601 }
-        @store&.set(checkpoint_key, JSON.generate(data))
+      # 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,
+          context: context.to_h,
+          timestamp: Time.now.iso8601
+        }
+        @store.set(checkpoint_key, JSON.generate(data))
       end
 
-      def load_checkpoint
-        raw = @store&.get(checkpoint_key)
+      # 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 = JSON.parse(raw)
+        restored = data["context"]
+        if restored.is_a?(Hash)
+          restored.each { |k, v| context[k.to_sym] = v }
+        end
         data["completed_index"]
       end
 

data/lib/ask/graph/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   class Graph
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/ask/graph.rb

@@ -16,28 +16,11 @@ module Ask
   #     step BookAppointment
   #   end
   #
-  # @example With parallel steps
-  #   class SyncData < Ask::Graph
-  #     step FetchRecords
+  #   result = HandleCall.new.call(recording: "call.wav")
   #
-  #     steps CrmUpdate, CalendarSync, SendNotification
-  #
-  #     step ConfirmResponse
-  #   end
-  #
-  # @example With human-in-the-loop
-  #   class ProcessBooking < Ask::Graph
-  #     step BookAppointment
-  #     approve ReviewBooking, if: :expensive?
-  #     step ConfirmBooking
-  #   end
-  #
-  # @example With per-item looping
-  #   class SendReminders < Ask::Graph
-  #     step FetchAppointments
-  #     step RemindEach   # calls context.each(:appointments) internally
-  #     step MarkComplete
-  #   end
+  # @example With checkpointing
+  #   store = Ask::State::Memory.new
+  #   result = HandleCall.new.call(input, checkpoint_store: store)
   #
   class Graph
     class << self
@@ -95,26 +78,23 @@ module Ask
         }
       end
 
-      # Create a new instance and run the graph.
-      # @param input [Object] optional initial input
+      # 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 run(input = nil, checkpoint_store: nil)
-        new(checkpoint_store: checkpoint_store).run(input)
-      end
-
-      # Resume a paused graph with human input.
-      # @param input [Object] the human's input
-      # @param checkpoint_store [#set, #get, #delete] the same store used for the original run
-      # @return [Ask::Graph::Context] the completed context
-      def resume(input:, checkpoint_store:)
-        new(checkpoint_store: checkpoint_store).resume(input: input)
+      def call(input = nil, checkpoint_store: nil)
+        new(input, checkpoint_store: checkpoint_store).call
       end
+      alias run call
     end
 
-    # @param checkpoint_store [#set, #get, #delete, nil] optional persistent store
-    def initialize(checkpoint_store: nil)
-      @runner = Runner.new(self.class.declarations, checkpoint_store: checkpoint_store)
+    # @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)
       @context = nil
     end
 
@@ -124,17 +104,17 @@ module Ask
     # @return [Ask::Graph::Context, nil] the shared context
     attr_reader :context
 
-    # Run the graph with the given input.
-    # @param input [Object] optional initial input
+    # Execute the graph.
     # @return [Ask::Graph::Context] the completed context
-    def run(input = nil)
-      @context = Context.new(self, input)
+    def call
+      @context = Context.new(self, @input)
       @runner.run(@context)
       @context
     rescue => e
-      raise unless e.class.name&.end_with?("Paused")
+      raise unless e.is_a?(Paused)
       @context
     end
+    alias run call
 
     # Resume a paused graph with human input.
     # @param input [Object] the human's input

metadata

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