ask-graph 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2bcc4cd34c3c6b401b4a5e6e47ea28bfeb8fcfe6cc117c46230ddf58df6249f8
+  data.tar.gz: 20bec4635a80dd53b1b497c38985327efcef79a7acace61d8725fac85842e2ce
+SHA512:
+  metadata.gz: a122a01aa42024e4be602f8fe859e0b3148867c248e36d434e86b63ad62561b53ea081cc1903c033d6aa603b89e232d981b94fda01b1f6fcf09356b31ef801eb
+  data.tar.gz: 96d289a9595599a663da22cef7357af63dc74dde4a6c399589eea339441c5a32f7b49ff77f82bfbf1232e1f548b6c3ae85aa0dd4bd2b6e430ff26a3d689d28fd

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+## [0.1.0] — 2026-07-28
+
+### Added
+
+- **Initial release** — Durable workflow graphs for the ask-rb ecosystem.
+
+- **Graph definition** — Define workflows with declarative steps:
+
+  ```ruby
+  class HandleCall < Ask::Graph
+    step Transcribe
+    step Classify, if: :needs_classification?
+    step BookAppointment
+  end
+  ```
+
+- **Conditional steps** — `step ClassName, if: :method?` and `step ClassName, unless: :method?` — methods on the graph class control whether a step runs.
+
+- **Parallel execution** — `steps ClassA, ClassB, ClassC` runs multiple steps simultaneously and waits for all to complete before continuing.
+
+- **Human-in-the-loop** — `approve ReviewBooking` runs a step then pauses execution, persisting state and waiting for external input via `resume`.
+
+- **Per-item checkpointing** — `context.each(items)` iterates with automatic checkpointing after each item. Crashes resume from the last completed item, not the beginning.
+
+- **Step checkpointing** — every completed step is persisted via an optional store. Crashes resume from the last completed step.
+
+- **Step failure handling** — failed steps raise `Ask::Graph::StepFailed` with the step name in the message.
+
+- **Inheritance** — child graphs inherit parent steps without affecting the parent.
+
+- **Class and instance execution** — `Graph.run` (class method) or `Graph.new.run` (instance method).
+
+### Tested
+
+- 31 tests, 42 assertions, 0 failures
+- Covers: step order, conditions, parallel, approve, checkpointing, context, inheritance, edge cases

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,202 @@
+# ask-graph
+
+**Durable workflow graphs for the ask-rb ecosystem.** Define workflows as graphs of named steps with conditional routing, parallel execution, human-in-the-loop approval, per-item checkpointing loops, and sub-graph composition. Each step is a plain Ruby class.
+
+```ruby
+gem "ask-graph"
+```
+
+## Quick Start
+
+```ruby
+require "ask-graph"
+
+# Define a workflow
+class ProcessOrder < Ask::Graph
+  step ValidateOrder
+  step ChargeCustomer,  if: :valid?
+  step SendConfirmation, if: :valid?
+  step NotifyAdmin,     unless: :valid?
+
+  private
+
+  def valid?
+    context.order.valid?
+  end
+end
+
+# Run it
+result = ProcessOrder.run(order: order)
+```
+
+## Steps
+
+Steps are plain Ruby classes with a `call(context)` method:
+
+```ruby
+class ValidateOrder
+  def call(context)
+    context.order = OrderValidator.validate(context.order)
+  end
+end
+```
+
+### Sequential steps
+
+```ruby
+class HandleCall < Ask::Graph
+  step Transcribe
+  step Classify
+  step Respond
+end
+```
+
+### Conditional steps
+
+```ruby
+class HandleCall < Ask::Graph
+  step BookAppointment,  if: :booking?
+  step EmergencyAlert,   if: :emergency?
+  step HandleInquiry,    unless: :known_intent?
+
+  private
+
+  def booking?   = context.intent == "booking"
+  def emergency? = context.intent == "emergency"
+  def known_intent? = %w[booking emergency inquiry].include?(context.intent)
+end
+```
+
+### Parallel steps
+
+Use `steps` (plural) to run multiple steps simultaneously:
+
+```ruby
+class SyncData < Ask::Graph
+  step FetchRecords
+
+  # All three run in parallel
+  steps CrmUpdate, CalendarSync, SendNotification
+
+  step ConfirmResponse
+end
+```
+
+### Human-in-the-loop (approve)
+
+`approve` runs a step, then pauses the workflow and waits for external input:
+
+```ruby
+class ProcessBooking < Ask::Graph
+  step BookAppointment
+  approve ReviewBooking, if: :expensive?
+  step ConfirmBooking
+end
+```
+
+After `approve` pauses, resume with:
+
+```ruby
+graph = ProcessBooking.new
+result = graph.run              # runs, pauses after ReviewBooking
+result = graph.resume(input: "approved")  # resumes, runs ConfirmBooking
+```
+
+### Per-item loops
+
+Use `context.each` inside a step for iteration with automatic checkpointing:
+
+```ruby
+class SendVoiceReminders
+  def call(context)
+    context.each(context.appointments) do |appt|
+      PhoneService.call(appt.number, appt.message)
+    end
+  end
+end
+
+class DailyReminders < Ask::Graph
+  step FetchAppointments
+  step SendVoiceReminders  # loops with per-item checkpointing
+  step MarkComplete
+end
+```
+
+If the process crashes mid-loop, it resumes from the last completed item.
+
+### Context
+
+Shared state flows between steps via `context`:
+
+```ruby
+class SetValue
+  def call(context)
+    context.greeting = "hello"        # set via method
+    context[:color] = "blue"          # set via bracket
+  end
+end
+
+class ReadValue
+  def call(context)
+    puts context.greeting             # => "hello"
+    puts context[:color]              # => "blue"
+  end
+end
+```
+
+### Sub-workflows
+
+A step can delegate to another workflow:
+
+```ruby
+class IntentHandler
+  def call(context)
+    case context.intent
+    when "booking"
+      BookingWorkflow.new.call(context)  # sub-workflow as a step
+    when "emergency"
+      EmergencyWorkflow.new.call(context)
+    end
+  end
+end
+```
+
+### Checkpointing
+
+Pass a checkpoint store to make workflows durable across crashes:
+
+```ruby
+store = Ask::State::Memory.new  # or Redis, SQLite, etc.
+
+# Runs through all steps, saving after each
+result = MyWorkflow.run(input, checkpoint_store: store)
+
+# If a crash occurs, resume from the last completed step
+result = MyWorkflow.run(input, checkpoint_store: store)
+```
+
+### Error handling
+
+Failed steps raise `Ask::Graph::StepFailed` with the step name:
+
+```ruby
+class MyGraph < Ask::Graph
+  step RiskyOperation
+end
+
+begin
+  MyGraph.run
+rescue Ask::Graph::StepFailed => e
+  puts e.message  # => "RiskyOperation failed: connection timeout"
+end
+```
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/graph/context.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Ask
+  class Graph
+    # Shared state that flows through every step of a graph execution.
+    #
+    # Stores input, output, and intermediate data produced by steps.
+    # Accessed by step classes via +context.data_key+ or +context[:data_key]+.
+    # Thread-safe by design — each context is scoped to one graph run.
+    #
+    # @example
+    #   class MyStep
+    #     def call(context)
+    #       context.transcript = "Hello"
+    #       context[:classification] = "booking"
+    #     end
+    #   end
+    #
+    class Context
+      # @return [Ask::Graph] the graph this context belongs to
+      attr_reader :graph
+
+      # @return [Object, nil] the current item when iterating via {#each}
+      attr_reader :item
+
+      def initialize(graph, input = nil)
+        @graph = graph
+        @store = {}
+        @each_index = nil
+        @each_items = nil
+        @item = nil
+        @mutex = Mutex.new
+        @store[:input] = input if input
+      end
+
+      # Access a stored value by method name.
+      def method_missing(name, *args, &block)
+        if name.to_s.end_with?("=")
+          key = name.to_s.chomp("=").to_sym
+          @mutex.synchronize { @store[key] = args.first }
+        elsif args.empty? && !block
+          @mutex.synchronize { @store[name] }
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        clean = name.to_s.sub(/=$/, "").to_sym
+        @store.key?(clean) || super
+      end
+
+      # Access a stored value by key.
+      # @param key [Symbol] the key
+      # @return [Object, nil]
+      def [](key)
+        @mutex.synchronize { @store[key.to_sym] }
+      end
+
+      # Store a value by key.
+      # @param key [Symbol] the key
+      # @param value [Object] the value
+      def []=(key, value)
+        @mutex.synchronize { @store[key.to_sym] = value }
+      end
+
+      # Iterate over items with per-item checkpointing.
+      #
+      # Each iteration is checkpointed so that if the process crashes,
+      # it resumes from the last completed item rather than starting over.
+      #
+      # @param items [Array] the items to iterate over
+      # @yield [item] called once per item
+      # @yieldparam item [Object] the current item
+      def each(items, &block)
+        @each_index = graph.runner.resume_index_for(items) || 0
+        @each_items = items
+
+        items.each_with_index do |item, idx|
+          break if idx < @each_index
+
+          @item = item
+          block.call(item)
+          graph.runner.checkpoint_each!(idx)
+        end
+      ensure
+        @each_index = nil
+        @each_items = nil
+        @item = nil
+      end
+
+      # @return [Hash] serializable snapshot of the context state
+      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
+        end
+      end
+    end
+  end
+end

data/lib/ask/graph/runner.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  class Graph
+    # Error raised when a step fails.
+    class StepFailed < 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.
+    class Runner
+      # @return [Array<Hash>] step declarations with name, type, condition
+      attr_reader :declarations
+
+      # @param declarations [Array<Hash>] step declarations
+      # @param checkpoint_store [#set, #get, #delete] optional persistent store
+      def initialize(declarations, checkpoint_store: nil)
+        @declarations = declarations
+        @store = checkpoint_store
+        @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
+
+        @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
+
+          execute_step(decl, context)
+          record_completion(idx, :completed)
+          save_checkpoint(idx)
+        end
+
+        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)
+      end
+
+      private
+
+      def execute_step(decl, context)
+        case decl[:type]
+        when :step
+          run_single(decl[:class], decl[:name], context)
+        when :steps
+          run_parallel(decl[:classes], decl[:name], context)
+        when :approve
+          run_approve(decl[:class], decl[:name], context)
+        end
+      end
+
+      def run_single(klass, _name, context)
+        instance = klass.new
+        instance.call(context)
+      rescue Paused
+        raise
+      rescue StandardError => 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
+          end
+        end
+        threads.each(&:join)
+      end
+
+      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)
+        raise Paused, "Graph paused for approval after #{klass.name}"
+      end
+
+      def condition_met?(decl, context)
+        if decl[:if]
+          context.graph.send(decl[:if])
+        elsif decl[:unless]
+          !context.graph.send(decl[:unless])
+        else
+          true
+        end
+      end
+
+      def record_completion(idx, status)
+        @completed_steps << { index: idx, status: status }
+      end
+
+      # --- Checkpointing ---
+
+      RUN_KEY = "ask:graph:run:%s"
+
+      def checkpoint_key
+        RUN_KEY % @declarations.object_id.to_s
+      end
+
+      def each_checkpoint_key
+        "#{checkpoint_key}:each"
+      end
+
+      def save_checkpoint(idx)
+        data = { completed_index: idx, timestamp: Time.now.iso8601 }
+        @store&.set(checkpoint_key, JSON.generate(data))
+      end
+
+      def load_checkpoint
+        raw = @store&.get(checkpoint_key)
+        return nil unless raw
+
+        data = JSON.parse(raw)
+        data["completed_index"]
+      end
+
+      def current_index
+        @completed_steps.size
+      end
+    end
+  end
+end

data/lib/ask/graph/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  class Graph
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/graph.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "graph/version"
+require_relative "graph/context"
+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.
+  #
+  # @example Basic workflow
+  #   class HandleCall < Ask::Graph
+  #     step Transcribe
+  #     step Classify, if: :needs_classification?
+  #     step BookAppointment
+  #   end
+  #
+  # @example With parallel steps
+  #   class SyncData < Ask::Graph
+  #     step FetchRecords
+  #
+  #     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
+  #
+  class Graph
+    class << self
+      # All step declarations collected across the class hierarchy.
+      def declarations
+        @declarations ||= []
+      end
+
+      # Inherited hook — copies declarations to subclasses.
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@declarations, declarations.dup)
+      end
+
+      # 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]
+        }
+      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)
+        declarations << {
+          classes: klasses,
+          type: :steps,
+          name: klasses.map { |k| k.name || k.to_s }.join(", "),
+          if: conditions[:if],
+          unless: conditions[:unless]
+        }
+      end
+
+      # Declare a human-in-the-loop step. Runs the step, then pauses
+      # 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]
+        }
+      end
+
+      # Create a new instance and run the graph.
+      # @param input [Object] optional initial 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)
+      end
+    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)
+      @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
+
+    # Run the graph with the given input.
+    # @param input [Object] optional initial input
+    # @return [Ask::Graph::Context] the completed context
+    def run(input = nil)
+      @context = Context.new(self, input)
+      @runner.run(@context)
+      @context
+    rescue => e
+      raise unless e.class.name&.end_with?("Paused")
+      @context
+    end
+
+    # 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)
+      @context
+    end
+  end
+end

data/lib/ask-graph.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "ask"
+require_relative "ask/graph"

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: ask-graph
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Define workflows as graphs of named steps with conditional routing, parallel
+  execution, human-in-the-loop approval, per-item checkpointing loops, and sub-graph
+  composition. Each step is a plain Ruby class.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-graph.rb
+- lib/ask/graph.rb
+- lib/ask/graph/context.rb
+- lib/ask/graph/runner.rb
+- lib/ask/graph/version.rb
+homepage: https://github.com/ask-rb/ask-graph
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-graph
+  source_code_uri: https://github.com/ask-rb/ask-graph
+  changelog_uri: https://github.com/ask-rb/ask-graph/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Durable workflow graphs for the ask-rb ecosystem
+test_files: []