ask-graph 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f25d9d9ca750cdb41cc6209ac0adf69346fc3da74a4a2a1cde787e27b13c81c3
-  data.tar.gz: 521f8841441fdf6efa497502588c772ace146585aa8ae1221f735d6838ee0429
+  metadata.gz: d76192a260425897adec826a504bcdf81b773abfd1d5d479945ad9e39dfa2387
+  data.tar.gz: d368fbc3f35957b443ab9f5795824b8715633c0ea77ca74484aeb8f9f96e3a6b
 SHA512:
-  metadata.gz: b23119776fe5892d3574c5fe0a9721742128b52a6205ee8d2b1fd5c457b9dc7b13a1a0dddc8a99bfda9d533e58a12dd4045f125b42c36b7b4f3e385b5006e5e0
-  data.tar.gz: 40943d5fc7cf5e09ad3cc6d676220141b93e88d8995b178a11a3a4130c12d5c9d25126d1b9602f53d4d313cb71d01f3313e99aecc2a7afa0af77f25df92fa2bb
+  metadata.gz: e963722c00c2fb40bcdaf05d9686a2aea00178c9847db2e1f6feaaf44f17c2917def642315846b8043f6826dab6e0e9c21f27951c8ad09afbaaa1961e5de0a89
+  data.tar.gz: c4751c4291f6f07c3cca869dbf368526701a8de74a0c2bfc358e5d3c4d37d75103e8b4d8a2581ffd2ff068760503f32c7bf97c29e7912acc047677b58d18cdf3

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.7.2] - 2026-08-04
+
+### Fixed
+
+- **Parallel steps inherit the caller's thread-local state.** `Runner#run_parallel` now copies `Thread.current` locals into each worker thread, so Rails `CurrentAttributes` and similar per-request context reach parallel steps instead of being nil.
+
 ## [0.7.1] — 2026-07-31
 
 ### Added

data/README.md

@@ -1,35 +1,42 @@
 # 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.
+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 with a `call(context)` method.
+
+ask-graph is for deterministic pipelines: you declare the steps and the
+routing. For LLM-driven loops that decide their own next step, use
+ask-agent instead.
+
+## Installation
 
 ```ruby
 gem "ask-graph"
 ```
 
-	## Quick Start
-	
-	```ruby
-	require "ask-graph"
-	
-	# Define a workflow
-	module ProcessOrder
-	  class Workflow < Ask::Graph
-	    step ValidateOrder
-	    step ChargeCustomer,  if: :valid?
-	    step SendConfirmation, if: :valid?
-	    step NotifyAdmin,     unless: :valid?
-	
-	    private
-	
-	    def valid?
-	      context.order.valid?
-	    end
-	  end
-	end
-	
-	# Run it
-	result = ProcessOrder::Workflow.call(order: order)
-	```
+## Quick Start
+
+```ruby
+require "ask-graph"
+
+module ProcessOrder
+  class Workflow < Ask::Graph
+    step ValidateOrder
+    step ChargeCustomer,  if: :valid?
+    step SendConfirmation, if: :valid?
+    step NotifyAdmin,     unless: :valid?
+
+    private
+
+    def valid?
+      context.order.valid?
+    end
+  end
+end
+
+result = ProcessOrder::Workflow.call(order: order)
+```
 
 ## Steps
 
@@ -43,188 +50,74 @@ class ValidateOrder
 end
 ```
 
-	### Sequential steps
-	
-	```ruby
-	module HandleCall
-	  class Workflow < Ask::Graph
-	    step Transcribe
-	    step Classify
-	    step Respond
-	  end
-	end
-	```
-	
-	### Conditional steps
-	
-	```ruby
-	module HandleCall
-	  class Workflow < 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
-	end
-	```
-
-	### Parallel steps
-	
-	Use `steps` (plural) to run multiple steps simultaneously:
-	
-	```ruby
-	module SyncData
-	  class Workflow < Ask::Graph
-	    step FetchRecords
-	
-	    # All three run in parallel
-	    steps CrmUpdate, CalendarSync, SendNotification
-	
-	    step ConfirmResponse
-	  end
-	end
-	```
-	
-	### Human-in-the-loop (approve)
-	
-	`approve` runs a step, then pauses the workflow and waits for external input:
-	
-	```ruby
-	module ProcessBooking
-	  class Workflow < Ask::Graph
-	    step BookAppointment
-	    approve ReviewBooking, if: :expensive?
-	    step ConfirmBooking
-	  end
-	end
-	```
-	
-	After `approve` pauses, resume with:
-	
-	```ruby
-	graph = ProcessBooking::Workflow.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
-	
-	module DailyReminders
-	  class Workflow < Ask::Graph
-	    step FetchAppointments
-	    step SendVoiceReminders  # loops with per-item checkpointing
-	    step MarkComplete
-	  end
-	end
-	```
+| Declaration | Behavior |
+|---|---|
+| `step Klass` | Run a step in order |
+| `step Klass, if: :method?` / `unless: :method?` | Conditional routing |
+| `step Klass, timeout: 30, retry: 3` | Per-step timeout and retry |
+| `step Klass, description: "..."` | Human-readable label |
+| `steps A, B, C` | Run multiple steps in parallel |
+| `approve Klass` | Run the step, then pause and wait for external input |
 
-If the process crashes mid-loop, it resumes from the last completed item.
+A paused workflow resumes with `graph.resume(input: "approved")` after
+`graph.run`.
 
 ### Context
 
-Shared state flows between steps via `context`:
+Shared state flows between steps. Set and read values by method or bracket,
+iterate with per-item checkpointing, and run sub-workflows:
 
 ```ruby
-class SetValue
+class SendVoiceReminders
   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
+    context.greeting = "hello"          # method access
+    context[:color] = "blue"            # bracket access
 
-A step can delegate to another workflow by calling `Workflow.call(context)`.
-The context is automatically exported, passed to the sub-workflow, and
-results are merged back on completion:
-
-```ruby
-module OrderFulfillment
-  class NotifyCustomer
-    def call(context)
-      NotifyCustomer::Workflow.call(context)
+    context.each(context.appointments) do |appt|  # per-item checkpointing
+      PhoneService.call(appt.number, appt.message)
     end
-  end
 
-  class Workflow < Ask::Graph
-    step ValidatePayment
-    step NotifyCustomer
-    step ShipOrder
+    context.run(NotifyCustomer::Workflow)         # sub-workflow
   end
 end
 ```
 
-Or use `context.run` for the same thing:
-
-```ruby
-class NotifyCustomer
-  def call(context)
-    context.run(NotifyCustomer::Workflow)
-  end
-end
-```
+If the process crashes mid-loop, it resumes from the last completed item.
 
-### Checkpointing
+## Storage and Checkpointing
 
-Pass a `storage` backend to make workflows durable across crashes:
+Pass a storage backend to make workflows durable across crashes. The default
+is `Ask::State::Memory`; any backend from ask-state-providers works:
 
 ```ruby
 store = Ask::State::Memory.new  # or Redis, SQLite, etc.
 
-# Runs through all steps, saving after each
-result = OrderFulfillment::Workflow.call(input, storage: store)
-
-# If a crash occurs, resume from the last completed step
+# Runs through all steps, saving after each; a later call resumes
 result = OrderFulfillment::Workflow.call(input, storage: store)
 ```
 
-### Error handling
+`Ask::Graph.storage(store)` sets a class-level default for the workflow.
 
-Failed steps raise `Ask::Graph::StepFailed` with the step name:
+## Errors and Hooks
 
-```ruby
-module MyWorkflow
-  class Workflow < Ask::Graph
-    step RiskyOperation
-  end
-end
+Failed steps raise `Ask::Graph::StepFailed`; timeouts raise `StepTimeout`,
+`WorkflowTimeout`, and approval pauses raise `Paused`.
 
-begin
-  MyWorkflow::Workflow.call
-rescue Ask::Graph::StepFailed => e
-  puts e.message  # => "RiskyOperation failed: connection timeout"
-end
-```
+Declare lifecycle hooks with `before_step :method`, `after_step :method`, and
+`on_failure :method`. Set timeouts at the class level with `step_timeout` (or
+its alias `default_step_timeout`) and `workflow_timeout`.
+
+## Full documentation
+
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+https://ask-rb.github.io/ask-docs/core/graph covers ask-graph in depth,
+including crash recovery, inheritance, and the full configuration reference.
+API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
+bundle install
 bundle exec rake test
-```
 
 ## License
 

data/lib/ask/graph/runner.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "timeout"
+require "time"
 
 module Ask
   class Graph
@@ -158,8 +159,15 @@ module Ask
       end
 
       def run_parallel(classes, _name, context)
+        # Inherit the caller's thread-local state (Rails CurrentAttributes
+        # and similar frameworks store per-request context in Thread.current)
+        # so parallel steps see the same context as sequential ones.
+        inherited_locals = {}
+        Thread.current.keys.each { |key| inherited_locals[key] = Thread.current[key] }
+
         threads = classes.map do |klass|
           Thread.new do
+            inherited_locals.each { |key, value| Thread.current[key] = value }
             instance = klass.new
             instance.call(context)
           rescue => e

data/lib/ask/graph/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   class Graph
-    VERSION = "0.7.1"
+    VERSION = "0.7.2"
   end
 end

metadata

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