agent_c 2.71828 → 2.718281

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8321a1602d20f566b59365d641fecb934340b043d6544e43b01b2951e947282b
-  data.tar.gz: bf3cd0d58944294f4e83e080ac7aebfff8677798c96426411e559c8f7e7f6a7d
+  metadata.gz: 84e8303cd68cc23d402d7c1e30928afd098d096adab7a82d278f49461935f409
+  data.tar.gz: dd379a4df652263f1f0af5ad5253f5d89900c0c8a3f205fb86caabaebab60b6c
 SHA512:
-  metadata.gz: 5dbe7a3d1ca921db961a5a3685c01f4e539b0358506cb45f9d6a04c462cb0657efa45eff16eea4f65c00bdb6f113b40551b38e71f5d61ceadf8463cec1ea9007
-  data.tar.gz: 4b407bc2cf7086536bce703b209552b8753c6b3eef37b096437728095945d247a5b6643113487ad739339e407b6e4c43c6b0cdd72aeca3f75551ab9e1ac763e0
+  metadata.gz: bd35cf2044c68580cf7b4acd2b054bbe0b30d72567af28ecda93e91a95dd57171229bab3861a29d6df2fc9ea3359d493fd1d55553d128e3b2a396d0dc722545a
+  data.tar.gz: '059f59eb9e1e859d95fe345a58a57e4da4ed1d02dd6b433e4c89c5e53b09e0f794b3e07c19157c61c3bcde6f7c6e33796c36e592a644b38be8a708d1134a6681'

data/docs/pipeline-tips-and-tricks.md

@@ -2,6 +2,11 @@
 
 This document contains useful patterns and techniques for working with AgentC pipelines.
 
+## Index
+
+- [Custom I18n Attributes](#custom-i18n-attributes)
+- [Rewinding to Previous Steps](#rewinding-to-previous-steps)
+
 ## Custom I18n Attributes
 
 By default, when using i18n interpolation in your prompts, AgentC will use `record.attributes` to provide values for interpolation. However, you can customize this behavior by implementing an `i18n_attributes` method on your record.
@@ -69,3 +74,128 @@ agent_step(:my_step)
 ### Return Value
 
 The `i18n_attributes` method should return a Hash with symbol or string keys. These keys will be used for interpolation in your i18n strings.
+
+## Rewinding to Previous Steps
+
+The `rewind_to!` method allows you to restart execution from a previously completed step. This is useful when you need to retry or re-execute steps based on runtime conditions.
+
+### Use Case
+
+This is useful when:
+- An agent determines that a previous step needs to be re-executed
+- You want to implement retry logic based on validation results
+- You need to loop through steps until certain conditions are met
+- A later step discovers that earlier work needs to be redone
+
+### Basic Usage
+
+```ruby
+class Store < AgentC::Store
+  record(:refactor) do
+    schema do
+      t.boolean(
+        :review_passed,
+        default: false
+      )
+
+      t.string(
+        :review_feedback,
+        default: "none"
+      )
+    end
+  end
+end
+
+class MyPipeline < AgentC::Pipeline
+  # prompt:
+  #   Perform the refactor.
+  #   Here is feedback from the reviewer (if any):
+  #   %{review_feedback}
+  agent_step(:perform_refactor)
+
+  # capture the diff
+  step(:capture_diff) do
+    record.update!(diff: git.diff)
+  end
+
+  # prompt:
+  #   Review this diff: %{diff}
+  # schema:
+  #  review_passed:
+  #    type: boolean
+  #  review_feedback:
+  #    type: string
+  agent_step(:review_refactor)
+
+  step(:verify_output) do
+    # if the review hasn't passed,
+    # then review_feedback is now
+    # present and will be passed
+    # back in to refactor step above
+    unless record.review_passed
+      rewind_to!(:perform_refactor)
+    end
+  end
+end
+```
+
+### How It Works
+
+When you call `rewind_to!(step_name)`, the pipeline:
+1. Validates that the specified step has already been completed
+2. Validates that the step name appears only once in `completed_steps`
+3. Removes the specified step and all subsequent steps from `completed_steps`
+4. Continues execution from the rewound step
+
+### Important Notes
+
+**Infinite loops**: There's no automatic infinite loop detection. Use your record's state to count rewinds if you are concerned about a potential infinite loop.
+
+**Must be called from within a step**: The `rewind_to!` method must be invoked from within a pipeline step during execution.
+
+**Step must be completed**: You can only rewind to steps that have already been completed in the current pipeline run. Attempting to rewind to a step that hasn't been completed will raise an `ArgumentError`.
+
+**Step must be unique**: If a step name appears multiple times in `completed_steps`, attempting to rewind to it will raise an `ArgumentError`. This prevents ambiguous rewind operations.
+
+**State considerations**: When rewinding, be aware that any side effects from the original execution of the rewound steps will remain unless explicitly cleaned up. The pipeline doesn't automatically rollback database changes or other state modifications.
+
+### Example: Retry Logic
+
+```ruby
+class ProcessWithRetry < AgentC::Pipeline
+  step(:attempt_processing) do
+    result = process_with_agent
+    record.update!(
+      attempt_count: record.attempt_count + 1,
+      last_result: result
+    )
+  end
+
+  step(:check_result) do
+    if record.last_result.failed? && record.attempt_count < 3
+      # Retry by going back to the processing step
+      rewind_to!(:attempt_processing)
+    elsif record.last_result.failed?
+      task.fail!("Failed after 3 attempts")
+    else
+      record.update!(status: "completed")
+    end
+  end
+end
+```
+
+### Error Handling
+
+If you try to rewind to a step that hasn't been completed yet:
+
+```ruby
+step(:early_step) do
+  rewind_to!(:later_step)  # ArgumentError: Cannot rewind to a step that's not been completed yet
+end
+```
+
+If a step name appears multiple times in `completed_steps`:
+
+```ruby
+# This will raise an ArgumentError about non-distinct step names
+rewind_to!(:duplicate_step)

data/lib/agent_c/pipeline.rb

@@ -123,18 +123,17 @@ module AgentC
 
       log("start")
 
-      self.class.steps.each do |step|
+      while(task.pending?)
         break if task.failed?
 
+        step = self.class.steps.find { !task.completed_steps.include?(_1.name.to_s) }
+        break if step.nil?
+
+        @rewind_to = nil
 
         store.transaction do
           log_prefix = "step: '#{step.name}'"
 
-          if task.completed_steps.include?(step.name.to_s)
-            log("#{log_prefix} already completed, skipping")
-            next
-          end
-
           log("#{log_prefix} start")
 
           instance_exec(&step.block)
@@ -142,6 +141,31 @@ module AgentC
           if task.failed?
             log("#{log_prefix} failed, executing on_failures")
             self.class.on_failures.each { instance_exec(&_1)}
+          elsif @rewind_to
+            matching_steps = task.completed_steps.select { _1 == @rewind_to }
+
+            if matching_steps.count == 0
+              raise ArgumentError, <<~TXT
+                Cannot rewind to a step that's not been completed yet:
+
+                rewind_to!(#{@rewind_to.inspect})
+                completed_steps: #{task.completed_steps.inspect}
+              TXT
+            elsif matching_steps.count > 1
+              raise ArgumentError, <<~TXT
+                Cannot rewind to a step with a non-distinct name. The step
+                name appears multiple times:
+
+                rewind_to!(#{@rewind_to.inspect})
+                completed_steps: #{task.completed_steps.inspect}
+              TXT
+            end
+
+            log("#{log_prefix} rewind_to! #{@rewind_to.inspect}")
+            task
+              .completed_steps
+              .index(@rewind_to)
+              .then { task.update!(completed_steps: task.completed_steps[0..._1]) }
           else
             log("#{log_prefix} done")
             task.completed_steps << step.name.to_s
@@ -173,6 +197,10 @@ module AgentC
       task.store
     end
 
+    def rewind_to!(step)
+      @rewind_to = step.to_s
+    end
+
     def repo
       @repo ||= @git.call(workspace.dir)
     end

data/lib/agent_c/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentC
-  VERSION = "2.71828"
+  VERSION = "2.718281"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent_c
 version: !ruby/object:Gem::Version
-  version: '2.71828'
+  version: '2.718281'
 platform: ruby
 authors:
 - Pete Kinnecom