composable_agents 2.1.3 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b82cf2e2c4224e28888344a4b352dcbd74433103d15123361c1e88e8717708a
-  data.tar.gz: bda57cd1244fb916d68557aea692c52657db06a7d26ad6e578dcb1893923b7a7
+  metadata.gz: 28c6711f6b4e8807c0e62349cfd5e246bf3ed56c9c1a613d14843d5b1769477d
+  data.tar.gz: a7433cc6cc01b80eb12c1b4f0eb04c8b5391e2bd10ec88aa47608ab5d25e0f0b
 SHA512:
-  metadata.gz: 07c251a27221c7a59785f9c5ab442b97c3c6679ece82bca14057112e70021b3a8878c23b6aa8cf36adda474a158a64491e75d4c78228c6ce98886f3fafba8327
-  data.tar.gz: 8a758b5c34330e777253e19598e72b15705d3c81445df788fba73d79edcb3354693e3b5aa6ce85ff794056493128943510afb095d7b6ed725e403af0241e91e8
+  metadata.gz: dcffae4c60bfb6c5424cc41134ab5466e15c1f3a0b2580e4cef7d9d6c2634b5b43d721cd9f5e4bf604a968af35c02b561409cd9885f028b27bf61d7bbb2fc775
+  data.tar.gz: c83544d5ab8f321a63c87a7eb035763b12a573a3d3495e653b301c0ce71edc076838e5af84216d64395c497ec8efc7aff13be136e96c399e84b277f9cd7db0b0

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [v2.2.0](https://github.com/Muriel-Salvan/composable_agents/compare/v2.1.3...v2.2.0) (2026-10-29 20:11:23)
+
+## Global changes
+### Patches
+
+* [feat(composable_agents): add Retriable mixin with conditional retries](https://github.com/Muriel-Salvan/composable_agents/commit/5217fb5b448f7fffc155f864888d55da48d66074)
+
+## Changes for composable_agents
+### Features
+
+* [feat(composable_agents): add Retriable mixin with conditional retries](https://github.com/Muriel-Salvan/composable_agents/commit/5217fb5b448f7fffc155f864888d55da48d66074)
+
+## Changes for retriable
+### Features
+
+* [feat(composable_agents): add Retriable mixin with conditional retries](https://github.com/Muriel-Salvan/composable_agents/commit/5217fb5b448f7fffc155f864888d55da48d66074)
+
 # [v2.1.3](https://github.com/Muriel-Salvan/composable_agents/compare/v2.1.2...v2.1.3) (2026-10-27 13:52:46)
 
 ### Patches

data/README.md

@@ -53,6 +53,7 @@ Whether you're building a code review assistant, a document summarizer, or a mul
     - [`ComposableAgents::Mixins::Resumable`](#composableagentsmixinsresumable)
     - [`ComposableAgents::Mixins::UserInteraction`](#composableagentsmixinsuserinteraction)
     - [`ComposableAgents::Mixins::ArtifactContract`](#composableagentsmixinsartifactcontract)
+    - [`ComposableAgents::Mixins::Retriable`](#composableagentsmixinsretriable)
   - [Additional notes](#additional-notes)
 - [Documentation](#documentation)
 - [How it works](#how-it-works)
@@ -203,6 +204,7 @@ itinerary_agent = ComposableAgents::Cline::Agent.new(
 - 📝 **Two prompt rendering strategies** — Choose between clean **Markdown** for simple agents, or **MarkdownHeavy** with structured output parsing, execution checklists, and typed artifact support for complex agentic systems.
 - 📦 **Typed artifact contracts** — Define and validate input/output schemas with descriptions, optional flags, and types (`:text`, `:markdown`, `:json`). The framework raises clear `MissingInputArtifactError`, `MissingOutputArtifactError`, or `ArtifactTypeError` on violations.
 - 💾 **Resumable execution** — Persist step-by-step state to disk (via the `Resumable` mixin). Interrupted runs can be resumed seamlessly — previously completed steps are skipped, saving time and API costs.
+- 🔁 **Conditional retries** — Wrap an agent's `#run` with the `Retriable` mixin to retry on transient failures. Register condition procs via `#retry_on` that receive the agent and any raised exception (or `nil`) and return a policy hash (optional `:wait_secs`, optional `:modifier`) to wait-and-retry, or `nil` to skip. Unhandled exceptions are re-raised when no policy applies.
 - 🗣️ **User interaction** — Agents can ask users clarifying questions mid-execution. Works out of the box via the terminal, or through an `ai-agents` tool integration for LLM-controlled workflows.
 - 📋 **Automatic conversation tracking** — Every prompt and response is automatically recorded with timestamps in a structured `conversation` store, ready for debugging or replay.
 - ⚙️ **Flexible instruction system** — Use raw text, structured ordered-lists, or a mix of both to define agent instructions, rendered consistently by the chosen strategy.
@@ -448,8 +450,36 @@ Mixins are `prepend`-ed into an agent class to add specific capabilities.
   agent.run(name: 'World')           # => { greeting: "Hello, World!" }
   agent.run(foo: 'bar')              # Raises MissingInputArtifactError
   ```
+
 - **Full documentation:** [Mixins::ArtifactContract on RubyDoc](https://www.rubydoc.info/gems/composable_agents/ComposableAgents/Mixins/ArtifactContract) | [artifact_contract.rb on GitHub](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/artifact_contract.rb)
 
+#### `ComposableAgents::Mixins::Retriable`
+
+- **Description:** Adds conditional retry capabilities to agents. Retry condition procs are registered with `#retry_on` (or `#with_retry_on` for temporary activation) and are evaluated at the end of each run. A proc receives the agent instance and the exception raised by `run` (or `nil` if none) and returns either `nil` (no retry) or a policy hash with `:wait_secs` and optional `:modifier` keys. When a proc returns a policy, the agent waits `wait_secs` seconds, optionally calls the policy's `modifier`, and re-runs. If `run` raised an exception and no proc returned a retry policy, the exception is re-raised to the caller.
+- **Public methods:**
+  - `#retry_on(proc)` — Register a retry condition proc. Returns `self` so calls can be chained.
+  - `#with_retry_on(proc, &block)` — Register a retry proc for the duration of a block, then unregister it when the block returns (even if it raises).
+  - policy hash — Configuration with optional `:wait_secs` (seconds to wait before retrying, defaults to 0) and optional `:modifier` (proc called with the agent before retrying).
+- **Usage example:**
+  ```ruby
+  class MyAgent < ComposableAgents::Agent
+    prepend ComposableAgents::Mixins::Retriable
+
+    def run(**inputs)
+      # Your processing here, may raise transient errors
+      { result: inputs[:input].upcase }
+    end
+  end
+
+  agent = MyAgent.new
+  # Retry once with a short wait when the first run fails.
+  agent.retry_on(lambda do |agent_instance, exception|
+    agent_instance.run_count == 1 ? { wait_secs: 1 } : nil
+  end)
+  agent.run(input: 'hello')
+  ```
+- **Full documentation:** [Mixins::Retriable on RubyDoc](https://www.rubydoc.info/gems/composable_agents/ComposableAgents/Mixins/Retriable) | [retriable.rb on GitHub](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/retriable.rb)
+
 ---
 
 ### Additional notes
@@ -477,6 +507,7 @@ Mixins are `prepend`-ed into an agent class to add specific capabilities.
   - [`Mixins::Resumable`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/resumable.rb) — Resumable workflow mixin
   - [`Mixins::ArtifactContract`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/artifact_contract.rb) — Artifact validation mixin
   - [`Mixins::UserInteraction`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/user_interaction.rb) — User question-asking mixin
+  - [`Mixins::Retriable`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/retriable.rb) — Conditional retry mixin
   - [`Logger`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/logger.rb) — Standard logger class
   - [`PromptRenderingStrategy::Markdown`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/prompt_rendering_strategy/markdown.rb) — Markdown prompt strategy
   - [`PromptRenderingStrategy::MarkdownHeavy`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb) — Heavy Markdown prompt strategy
@@ -579,6 +610,7 @@ Two strategies are included, mixed into the agent at initialization via `singlet
 
 Mixins are **prepended** (using `prepend`) or **included** (using `include`) to override `#run` or add new methods:
 
+- **[`Mixins::Retriable`](lib/composable_agents/mixins/retriable.rb)** — Wraps `#run` with conditional retry logic. Register condition procs via `#retry_on` that receive the agent and any exception raised by `run` (or `nil`) and return a policy hash (`:wait_secs`, `:modifier`) to trigger a wait-and-retry, or `nil` to skip retrying. If `run` raises and no policy is returned, the exception is re-raised.
 - **[`Mixins::ArtifactContract`](lib/composable_agents/mixins/artifact_contract.rb)** — Wraps `#run` to validate inputs before and outputs after execution against declared contracts. Raises `MissingInputArtifactError`, `MissingOutputArtifactError`, or `ArtifactTypeError` on violations.
 - **[`Mixins::Resumable`](lib/composable_agents/mixins/resumable.rb)** — Overrides `#run` with a **step-based execution model**. Each `step` block is persisted to `.composable_agents/runs/{run_id}/` as JSON. On re-run, completed steps are skipped — only new steps execute. Supports nested steps and agent state serialization via `export_state`/`import_state`.
 - **[`Mixins::UserInteraction`](lib/composable_agents/mixins/user_interaction.rb)** — Adds an `#ask(question)` method. By default prompts the terminal; override `#answer_to` for custom behavior.

data/TODO.md

@@ -1,3 +1,7 @@
+* Add the Retriable mixin to Cline::Agent with proper methods or config to define fallback models or changes in case of errors, with exponential waits.
+* Use the Retriable mixin with ArtifactContract.
+* Add a way to detect infinite loops in agents and act on it (maybe a mixin looking at prompts/messages).
+* Add a way to kill an agent run on a given timeout (generic mixin).
 * Check Rubocop-rspec exceptions and try to remove them.
 * Add agents manifesto for contributors.
 * Add some info logging (not debug) that would allow detecting when infinite loops or blocked agents occur.

data/lib/composable_agents/mixins/retriable.rb

@@ -0,0 +1,118 @@
+module ComposableAgents
+  module Mixins
+    # Mixin adding retriable capabilities to agents.
+    #
+    # An agent prepending this mixin can define retry conditions that are
+    # evaluated at the end of each run. The first condition that decides to
+    # retry triggers a wait and a re-execution of the run.
+    #
+    # # Public interface
+    #
+    # * `#retry_on(&block)` registers a new retry condition proc.
+    # * `#with_retry_on(proc, &block)` registers a retry proc for the duration
+    #   of a code block and unregisters it afterwards.
+    #
+    # # Behaviour
+    #
+    # * Each registered proc is kept in an internal array, in registration order.
+    # * A proc receives the agent's instance and the exception raised by `run`
+    #   (or `nil` if none) and returns either `nil` (no retry) or a policy hash
+    #   with optional `:wait_secs` and optional `:modifier` keys.
+    # * The run method is wrapped: it calls the original run, then evaluates the
+    #   registered procs in order until one returns a non-nil policy hash.
+    # * If `run` raised an exception and no proc returned a non-nil policy hash,
+    #   the exception is re-raised to the caller.
+    # * If a proc decides to retry: wait for `wait_secs` seconds, then call the
+    #   `modifier` proc (if any), then call run again.
+    #
+    module Retriable
+      # @!group Public API
+
+      # Register a proc that evaluates whether the agent should be retried
+      # after a run.
+      #
+      # This method can be called several times with different procs to define
+      # various criteria to retry. The registered procs are evaluated in the
+      # order they were registered.
+      #
+      # @param proc [Proc] the retry condition proc. It receives the agent's
+      #   instance and the exception raised by `run` (or `nil` if none).
+      #   - param agent [Agent] The agent for which the retry is considered.
+      #   - param exception [Exception, nil] The exception that was raised by the run, or nil if none.
+      #   - result [Hash\\{Symbol => Object}] Definition of the retry policy, with optional properties:
+      #     - wait_secs [Integer, Float] Wait time in seconds before retrying (defaults to 0).
+      #     - modifier [Proc] Code called to modify the agent's state before retrying (defaults to doing nothing).
+      #       - param agent [Agent] The agent for which the retry is considered.
+      # @return [self]
+      def retry_on(proc)
+        retry_policies << proc
+        self
+      end
+
+      # Register a retry proc for the duration of a code block, then
+      # unregister it when the block returns (even if it raises).
+      #
+      # The block can itself register other procs (with {#retry_on}) and
+      # those are kept after the block ends; only the proc given to this
+      # method is unregistered.
+      #
+      # @param proc [Proc] the retry condition proc (see #retry_on)
+      # @yield the code block in which the proc is active
+      def with_retry_on(proc, &)
+        retry_on(proc)
+        yield
+      ensure
+        retry_policies.delete(proc)
+      end
+
+      # Wrap the agent's run method with retry logic.
+      #
+      # It calls the original run, then evaluates the registered procs in
+      # order until one returns a non-nil policy hash. Each proc receives
+      # the agent's instance and the exception raised by `run` (or `nil` if
+      # none). If `run` raised an exception and no proc returned a non-nil
+      # policy hash, the exception is re-raised to the caller. If one does,
+      # it waits for the policy's `wait_secs`, applies the `modifier` proc
+      # (if any) and calls run again.
+      #
+      # @param input_artifacts [Hash{Symbol => Object}] input artifacts
+      # @return [Hash{Symbol => Object}] output artifacts from the last run
+      def run(**input_artifacts)
+        output_artifacts = nil
+        retry_index = 0
+        loop do
+          exception = nil
+          begin
+            output_artifacts = super
+          rescue StandardError => e
+            exception = e
+          end
+          policy = nil
+          retry_policies.each do |policy_proc|
+            policy = policy_proc.call(self, exception)
+            break if policy
+          end
+          if policy
+            retry_index += 1
+            wait_secs = policy[:wait_secs] || 0
+            logger.debug "Retry ##{retry_index}: re-running in #{wait_secs}s#{" (exception #{exception})" if exception}"
+            sleep(wait_secs) if wait_secs.positive?
+            policy[:modifier]&.call(self)
+          else
+            raise exception if exception
+
+            break
+          end
+        end
+        output_artifacts
+      end
+
+      private
+
+      # @return [Array<Proc>] the registered retry condition procs
+      def retry_policies
+        @retry_policies ||= []
+      end
+    end
+  end
+end

data/lib/composable_agents/version.rb

@@ -2,5 +2,5 @@ module ComposableAgents
   # @!group Public API
 
   # Gem version
-  VERSION = '2.1.3'
+  VERSION = '2.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 2.1.3
+  version: 2.2.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -87,6 +87,7 @@ files:
 - lib/composable_agents/mixins/ai_agent_user_interaction.rb
 - lib/composable_agents/mixins/artifact_contract.rb
 - lib/composable_agents/mixins/resumable.rb
+- lib/composable_agents/mixins/retriable.rb
 - lib/composable_agents/mixins/user_interaction.rb
 - lib/composable_agents/prompt_driven_agent.rb
 - lib/composable_agents/prompt_rendering_strategy/markdown.rb