agent_c 2.9979 → 2.71828

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24e17363e73084fdbcf50fda975a5822e622a80c04b0822e4017dfe02f46240a
-  data.tar.gz: fe16a11e5ac880e18f5bc4c0317d2b8f7386542de99aec3217c06af8e4625186
+  metadata.gz: 8321a1602d20f566b59365d641fecb934340b043d6544e43b01b2951e947282b
+  data.tar.gz: bf3cd0d58944294f4e83e080ac7aebfff8677798c96426411e559c8f7e7f6a7d
 SHA512:
-  metadata.gz: 6937e2b0cdb4c9db5b5aca19e2093ed1810ff2ed058baec3f017ab7f32c567726020d98973c2ca277bbd4ea653325afd6934555113bd25cbec8ad03e79a66431
-  data.tar.gz: 2649e8a916012ff96ff200d2b749e376137dbee4e59cec89fbfc244d42226acc67c2b5812483dda14e3d815126ae14030eb488ef7b70db738a89d927a20cf1b3
+  metadata.gz: 5dbe7a3d1ca921db961a5a3685c01f4e539b0358506cb45f9d6a04c462cb0657efa45eff16eea4f65c00bdb6f113b40551b38e71f5d61ceadf8463cec1ea9007
+  data.tar.gz: 4b407bc2cf7086536bce703b209552b8753c6b3eef37b096437728095945d247a5b6643113487ad739339e407b6e4c43c6b0cdd72aeca3f75551ab9e1ac763e0

data/CLAUDE.md

@@ -8,7 +8,7 @@
 - DO NOT add example scripts. Either add it to the readme or make a test.
 - DO NOT add documentation outside of the README
 - DO NOT program defensively. If something should respond_to?() a method then just invoke the method. An error is better than a false positive
-- DO NOT write a one-off script for debugging, write a test-case and run it instead.
+- If you need to test a one-off script, write a test-case and run it instad of writing a temporary file or using a giant shell script
 - DO NOT edit the singleton class of an object. If you think you need to do this, ideas for avoiding: inject an object, create a module and include it, make a base class.
 
 # TESTING

data/README.md

@@ -336,7 +336,7 @@ I suggest following the structure of the [example template](./template).
 
 Detailed guides for all features:
 
-- **[Batch](docs/batch.md)** - Batch configuration, methods, and pipeline integration
+- **[Main README](../README.md)** - Batch and Pipeline usage (primary approach)
 - **[Pipeline Tips and Tricks](docs/pipeline-tips-and-tricks.md)** - Useful patterns and techniques for pipelines
 - **[Chat Methods](docs/chat-methods.md)** - Using session.prompt and session.chat for direct interactions
 - **[Tools](docs/tools.md)** - Built-in tools for file operations and code interaction

data/TODO.md

@@ -5,101 +5,8 @@ Things I'd like to work on:
 - Make injecting a Chat record simpler.
 - Make injecting Git simpler (make injecting anything easier)
 - Add a request queue to AgentC::Chat so that we can rate-limit and retry on error
-- Use spring for run_rails_test, but add a timeout condition where it kills the process if no stdout appears for a while and tries again without spring.
-- tool calls should write the full results to file (except for readfile) and pass back a reference for future queries. For example, if RunRailsTest gives way too much output, we have to truncate but how to see the rest?
-
-## Immplement plan, implement, review looping
-
-Some scratch:
-
-```ruby
-agent_iterate_loop(
-  :implement_query_object,
-  max_tries: 17,
-  plan: [
-    :plan_step_1,
-    :plan_step_2,
-  ],
-  implement: [
-    :implement_step_1,
-    :implement_step_2,
-  ],
-  # optional: defaults to implement
-  iterate: [
-    :address_feedback_1
-  ]
-  review: [
-    :review_step_1,
-    :review_step_2
-  ],
-)
-```
-
-Thoughts:
-
-- This makes a demand on the `response_schema` of the prompts.
-- Does the `task` track the looping here or the `record`?
-  - Is the progress tracked in memory? This can be one step...
-- What if you have multiple `agent_iterate_loop` invocations? How do we store diffs/reviews for each of those?
-- The `agent_step` applies the result to the record. If we track it on the task, we could get the attributes to the right place. Can we extend the response schema? The `plan` step definitely needs to update the record, so it needs to specify response_schema. The `implement/iterate` steps *might* need to accept response_schema (eg, path of file created? Or not necessary?, maybe not necessary.)
-- Does a failed review trigger plan -> iterate -> review or just iterate -> review
-  - The implement/iterate arrays could include "plan" steps so that they know if they're starting from scratch or not.
-  - Do we run every review or stop at the first one?
-
-
-```ruby
-def agent_iterate_loop(
-  name,
-  max_tries: 3,
-  implement: [],
-  iterate: implement,
-  review: [],
-)
-  step(name) do
-    tries = 0
-
-    while(tries < max_tries)
-      if tries == 0
-        implement.each do |name|
-          process_prompt(name)
-        end
-      else
-        iterate.each do |name|
-          process_prompt(
-            name,
-            additional_i18n_attrs: {
-              feedback: feedback.join("\n---\n")
-            }
-          )
-        end
-      end
-
-      feedbacks = []
-
-      diff = git.diff
-      review.each do |name|
-        result = process_prompt(
-          name,
-          schema: -> {
-            t.boolean(:pass)
-            t.string(:feedback)
-          },
-          additional_i18n_attrs: {
-            diff:
-          }
-        )
-
-        if !result.fetch("pass")
-          feedbacks << result.fetch("feedback")
-        end
-      end
-
-      if record.respond_to?(:add_review)
-        record.add_review(diff:, feedbacks:)
-      end
-
-      break if feedbacks.empty?
-    end
-  end
-end
-```
+- Use spring for run_rails_test, but add a timeout condition where it kills the
+  process if no stdout appears for a while and tries again without spring.
+- tool calls should write the full results to file (except for readfile) and pass
+  back a reference for future queries. For example, if RunRailsTest gives way too
+  much output, we have to truncate but how to see the rest?

data/docs/chat-methods.md

@@ -43,14 +43,15 @@ answer = chat.get("What is 2 + 2?")
 # give a reason why.
 #
 # The response will look like one of the following:
-# Success response (just the data fields):
 # {
+#   status: "success",
 #   name: "...",
 #   email: "...",
 # }
-# OR error response:
+# OR:
 # {
-#   unable_to_fulfill_request_error: "some reason why it couldn't do it"
+#   status: "failure",
+#   message: "some reason why it couldn't do it"
 # }
 
 schema = AgentC::Schema.result do
@@ -62,10 +63,10 @@ result = chat.get(
   "Extract the name and email from this text: 'Contact John at john@example.com'",
   schema: schema
 )
-# => { "name" => "John", "email" => "john@example.com" }
+# => { "status" => "success", "name" => "John", "email" => "john@example.com" }
 
 # If the LLM can't complete the task, it returns an error response:
-# => { "unable_to_fulfill_request_error" => "No email found in the text" }
+# => { "status" => "error", "message" => "No email found in the text" }
 ```
 
 ### Using confirm and out_of for consensus

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

@@ -2,12 +2,6 @@
 
 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)
-- [Agent Review Loop](#agent-review-loop)
-
 ## 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.
@@ -75,379 +69,3 @@ 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)
-```
-
-## Agent Review Loop
-
-The `agent_review_loop` method provides a declarative way to implement iterative review and refinement workflows. It automatically handles the loop logic where an agent implements a solution, reviewers provide feedback, and the agent iterates based on that feedback until the reviewers approve or a maximum number of tries is reached.
-
-### Use Case
-
-This is useful when:
-- You need an agent to generate code, designs, or content that requires review
-- Multiple reviewers need to evaluate the work from different perspectives
-- The agent should iterate based on feedback until reviewers approve
-- You want to capture review history for audit or debugging purposes
-- You need to limit the number of iteration attempts
-
-### Basic Example
-
-```ruby
-class RefactorPipeline < AgentC::Pipeline
-  agent_review_loop(
-    :refactor_code,
-    max_tries: 5,
-    implement: :initial_refactor,
-    iterate: :improve_refactor,
-    review: :code_review
-  )
-end
-```
-
-With i18n translations:
-
-```yaml
-en:
-  initial_refactor:
-    prompt: "Refactor the code to improve readability"
-    response_schema:
-      code:
-        description: "The refactored code"
-
-  improve_refactor:
-    prompt: |
-      The previous refactor received this feedback:
-      %{feedback}
-
-      Please improve the refactor based on this feedback.
-    response_schema:
-      code:
-        description: "The improved refactored code"
-
-  code_review:
-    prompt: |
-      Review this code change:
-      %{diff}
-
-      Is it ready to merge?
-    response_schema:
-      approved:
-        type: boolean
-        description: "Whether the code is approved"
-      feedback:
-        type: string
-        description: "Feedback if not approved (empty if approved)"
-```
-
-### How It Works
-
-The `agent_review_loop` executes in iterations:
-
-1. **First iteration (try 0)**:
-   - Runs all `implement` steps in order
-   - If any implement step fails, the loop stops and marks the task as failed
-   - Captures git diff of changes
-   - Runs all `review` steps with the diff
-   - Collects feedback from any reviewers who don't approve
-
-2. **Subsequent iterations (try 1+)**:
-   - Runs all `iterate` steps with accumulated feedback
-   - If any iterate step fails, the loop stops and marks the task as failed
-   - Captures git diff of changes
-   - Runs all `review` steps with the new diff
-   - Collects feedback from any reviewers who don't approve
-
-3. **Loop continues until**:
-   - All reviewers approve (feedback list is empty), OR
-   - `max_tries` is reached, OR
-   - Any step fails, OR
-   - The task is marked as failed by other means
-
-### Multiple Steps
-
-You can specify multiple steps for implement, iterate, and review:
-
-```ruby
-agent_review_loop(
-  :multi_file_refactor,
-  max_tries: 5,
-  implement: [
-    :refactor_controller,
-    :refactor_model,
-    :refactor_view
-  ],
-  iterate: [
-    :improve_controller,
-    :improve_model,
-    :improve_view
-  ],
-  review: [
-    :code_quality_review,
-    :security_review,
-    :performance_review
-  ]
-)
-```
-
-Steps are executed in order. If any step fails, the loop stops immediately.
-
-### Feedback Interpolation
-
-The `iterate` steps automatically receive a `%{feedback}` interpolation variable containing all feedback from reviewers, joined with `"\n---\n"` as a separator:
-
-```yaml
-improve_refactor:
-  prompt: |
-    Previous feedback from reviewers:
-    %{feedback}
-
-    Please address all concerns.
-```
-
-### Review Schema
-
-Your "review" I18n should **not** include any response schema. AgentC will
-configure the schema for you.
-
-Review steps must return a response with these fields:
-- `approved` (boolean): Whether the work is approved
-- `feedback` (string): Feedback message if not approved (can be empty string if approved)
-
-If a review step fails to return valid data, the task is marked as failed.
-
-### Optional: Recording Reviews
-
-If your record implements an `add_review` method, it will be called after each review iteration with the diff and collected feedback:
-
-```ruby
-record(:my_record) do
-  schema do |t|
-    t.json(:reviews, default: [])
-  end
-
-  def add_review(diff:, feedbacks:)
-    self.reviews ||= []
-    self.reviews << {
-      timestamp: Time.now.iso8601,
-      diff: diff,
-      feedbacks: feedbacks
-    }
-    save!
-  end
-end
-```
-
-This allows you to maintain a complete history of all review iterations.
-
-### Default Iterate Behavior
-
-If you don't specify `iterate`, it defaults to the same value as `implement`:
-
-```ruby
-# These are equivalent:
-agent_review_loop(:refactor, implement: :refactor_code, review: :review)
-agent_review_loop(:refactor, implement: :refactor_code, iterate: :refactor_code, review: :review)
-```
-
-This is useful when the same prompt can handle both initial implementation and iteration based on feedback.
-
-### Important Notes
-
-**Required parameters**: You must provide either `implement` or `iterate` (or both). Providing only `review` will raise an `ArgumentError`.
-
-**Max tries behavior**: When `max_tries` is reached, the loop completes the step successfully even if reviews haven't all approved. The loop doesn't fail the task when max tries is exceeded.
-
-**Git diff**: The git diff is captured after each iteration's implementation/iteration steps complete, and is passed to review steps via the `%{diff}` interpolation variable.
-
-**Failure handling**: If any implement, iterate, or review step returns invalid data or raises an exception, the entire agent_review_loop step is marked as failed and the task stops.
-
-**Step naming**: The `agent_review_loop` counts as a single pipeline step with the name you provide (e.g., `:refactor_code`), not separate steps for each iteration.
-
-### Complete Example
-
-```ruby
-class DocumentationPipeline < AgentC::Pipeline
-  agent_review_loop(
-    :write_documentation,
-    max_tries: 3,
-    implement: [:draft_readme, :draft_examples],
-    iterate: [:improve_readme, :improve_examples],
-    review: [:technical_review, :style_review]
-  )
-
-  step(:publish) do
-    # Only reached if reviews passed or max_tries exceeded
-    record.update!(published: true)
-  end
-end
-```
-
-With a record that tracks review history:
-
-```ruby
-record(:documentation) do
-  schema do |t|
-    t.text(:readme_content)
-    t.text(:examples_content)
-    t.json(:review_history, default: [])
-    t.boolean(:published, default: false)
-  end
-
-  def add_review(diff:, feedbacks:)
-    self.review_history << {
-      iteration: review_history.length + 1,
-      timestamp: Time.now.iso8601,
-      diff_size: diff.length,
-      feedback_count: feedbacks.length,
-      feedbacks: feedbacks
-    }
-    save!
-  end
-
-  def i18n_attributes
-    attributes.merge(
-      total_reviews: review_history.length,
-      last_feedback: review_history.last&.dig("feedbacks")&.join("\n---\n") || "none"
-    )
-  end
-end
-```
-
-### When to Use agent_review_loop vs rewind_to!
-
-Use `agent_review_loop` when:
-- The review and iteration logic is straightforward and consistent
-- You want a declarative approach with less boilerplate
-- Multiple reviewers are involved
-- You want automatic feedback collection and interpolation
-
-Use `rewind_to!` when:
-- You need custom logic to determine whether to retry
-- The retry conditions are complex or context-dependent
-- You need to rewind to steps other than the immediate previous one
-- You want explicit control over the retry logic