composable_agents 2.1.3 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b82cf2e2c4224e28888344a4b352dcbd74433103d15123361c1e88e8717708a
-  data.tar.gz: bda57cd1244fb916d68557aea692c52657db06a7d26ad6e578dcb1893923b7a7
+  metadata.gz: a0ee11ea2faf7acea0c666c5dda07d94ba31eca150153c07c5ed8b8a8f408195
+  data.tar.gz: f5385011f38ce4ce3968e2b67f1866fe0134c94432dcc9c58d6373a8421af901
 SHA512:
-  metadata.gz: 07c251a27221c7a59785f9c5ab442b97c3c6679ece82bca14057112e70021b3a8878c23b6aa8cf36adda474a158a64491e75d4c78228c6ce98886f3fafba8327
-  data.tar.gz: 8a758b5c34330e777253e19598e72b15705d3c81445df788fba73d79edcb3354693e3b5aa6ce85ff794056493128943510afb095d7b6ed725e403af0241e91e8
+  metadata.gz: 21967310c2483efc63f164ca2a2c46f9d96c5965253bcd6fc036a4717d2ad0ce46536001a172ea440476df0e6c0039134d98baed9e8d359b429130882837f83b
+  data.tar.gz: 93d7d8bea59ec3a9a6aa7a7a021948a7af38a9292566418de1387dfc35ef22b98cad4bd56d4bee7c607e5591f1050bab6cb576488ba444db62184839572cc46b

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+# [v3.0.0](https://github.com/Muriel-Salvan/composable_agents/compare/v2.2.0...v3.0.0) (2026-11-01 12:34:56)
+
+## Global changes
+### Breaking changes
+
+* [break: add retriable artifacts mixin for auto-retry on missing outputs and remove any mixin from prompt driven agents](https://github.com/Muriel-Salvan/composable_agents/commit/76073bebe8ee247d24a3bc3279c1db822640f47a)
+
+## Changes for composable-agents
+### Features
+
+* [break: add retriable artifacts mixin for auto-retry on missing outputs and remove any mixin from prompt driven agents](https://github.com/Muriel-Salvan/composable_agents/commit/76073bebe8ee247d24a3bc3279c1db822640f47a)
+
+# [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,8 @@ 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)
+    - [`ComposableAgents::Mixins::RetriableArtifacts`](#composableagentsmixinsretriableartifacts)
   - [Additional notes](#additional-notes)
 - [Documentation](#documentation)
 - [How it works](#how-it-works)
@@ -203,6 +205,8 @@ 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.
+- 🔁 **Automatic artifact retry* — Prepend the RetriableArtifacts mixin to a PromptDrivenAgent subclass to automatically re-run when output artifacts declared in contracts are missing or in error. Configurable via `artifacts_errors_max_retries` (default: 3); raises `ArtifactsErrorsMaxRetriesExceededError` when the limit is exceeded.
 - 🗣️ **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 +452,64 @@ 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)
+
+
+#### `ComposableAgents::Mixins::RetriableArtifacts`
+
+- **Description:** Automatically retries the run when output artifacts declared in contracts are missing or in error on prompt-driven agents. Requires both the ArtifactContract and Retriable mixins to be prepended, and must be prepended on an agent descending from PromptDrivenAgent.
+- **Public methods:**
+  - `#initialize(*args, artifacts_errors_max_retries: 3, **kwargs)` — Registers a retry policy that re-executes the run with a prompt asking for missing artifacts when output artifacts are missing or in error. The artifacts_errors_max_retries parameter (default: 3) sets the maximum number of retries before raising ArtifactsErrorsMaxRetriesExceededError.
+- **Usage example:**
+  ```ruby
+  class MyAgent < ComposableAgents::PromptDrivenAgent
+    prepend ComposableAgents::Mixins::ArtifactContract
+    prepend ComposableAgents::Mixins::Retriable
+    prepend ComposableAgents::Mixins::RetriableArtifacts
+
+    def output_artifacts_contracts
+      { result: "Final result", logs: "Execution logs" }
+    end
+
+    def run(**inputs)
+      # Processing logic that may produce incomplete output artifacts
+      super
+    end
+  end
+
+  agent = MyAgent.new(artifacts_errors_max_retries: 3)
+  agent.run  # Automatically retries if result or logs are missing or in error
+  ```
+- **Raises:** ArtifactsErrorsMaxRetriesExceededError when the maximum number of retries is exceeded.
+
 ---
 
 ### Additional notes
@@ -477,6 +537,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 +640,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.
@@ -648,7 +710,7 @@ npm install node-pty
 │       ├── instructions.rb       # Instruction system
 │       ├── ai_agents/            # ai-agents backend
 │       ├── cline/                # cline-rb backend
-│       ├── mixins/               # Resumable, ArtifactContract, UserInteraction, Logger
+│       ├── mixins/               # ArtifactContract, Logger, Resumable, Retriable, RetriableArtifacts, UserInteraction
 │       ├── prompt_rendering_strategy/ # Markdown & MarkdownHeavy strategies
 │       └── utils/                # Markdown utilities
 ├── spec/                         # Test suite

data/TODO.md

@@ -1,3 +1,6 @@
+* 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.
+* 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/artifacts_errors_max_retries_exceeded_error.rb

@@ -0,0 +1,6 @@
+module ComposableAgents
+  # Custom exception raised when the maximum number of retries for output artifacts
+  # errors (missing or in error) is exceeded and the run cannot succeed.
+  class ArtifactsErrorsMaxRetriesExceededError < StandardError
+  end
+end

data/lib/composable_agents/cline/agent.rb

@@ -23,8 +23,6 @@ module ComposableAgents
     class Agent < PromptDrivenAgent
       # @!group Public API
 
-      prepend Mixins::ArtifactContract
-
       # Initialize a new agent that uses the Cline CLI in a dedicated config
       #
       # @param strategy [Module] The prompt rendering strategy

data/lib/composable_agents/mixins/artifact_contract.rb

@@ -64,6 +64,15 @@ module ComposableAgents
 
       private
 
+      # Restrict the output artifacts errors that should raise an {OutputArtifactsError} at the end of a run
+      #   to only those concerning artifacts defined in the output artifacts contracts.
+      # Errors on artifacts that are not part of the contracts are ignored.
+      #
+      # @return [Hash{Symbol => String}] The output artifacts errors that should raise, per artifact name
+      def output_artifacts_errors_to_raise
+        (defined?(super) ? super : {}).slice(*normalized_output_artifacts_contracts.keys)
+      end
+
       # Define input artifacts contracts
       #
       # @return [Hash{Symbol => Object}] Set of input artifacts contract, per artifact name

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/mixins/retriable_artifacts.rb

@@ -0,0 +1,92 @@
+module ComposableAgents
+  module Mixins
+    # Mixin adding automatic retry of the run when output artifacts are missing on prompt-driven agents.
+    # This mixin requires the following mixins to be prepended:
+    # - The {ArtifactContract} mixin.
+    # - The {Retriable} mixin.
+    # This mixin requires to be prepended on an agent descending from {PromptDrivenAgent}.
+    #
+    # When prepended to an agent descending from PromptDrivenAgent, the run method will
+    # automatically re-execute until all expected output artifacts have been provided.
+    #
+    # On retry, the overridden #run method uses a prompt asking for missing artifacts
+    # as +user_instructions+ instead of the original one.
+    # When the run raised an {OutputArtifactsError}, artifacts having errors are also
+    # included in the prompt, taken from the exception data.
+    module RetriableArtifacts
+      # Initialize a new agent with the retry-on-missing-artifacts policy registered.
+      #
+      # @param artifacts_errors_max_retries [Integer] Maximum number of retries when output
+      #   artifacts are missing or in error. Defaults to 3. When the number of retries
+      #   exceeds this value, a {ArtifactsErrorsMaxRetriesExceededError} is raised.
+      # @param args [Array] Arguments passed to the parent initializer
+      # @param kwargs [Hash] Keyword arguments passed to the parent initializer
+      def initialize(*args, artifacts_errors_max_retries: 3, **kwargs)
+        super(*args, **kwargs)
+        @overridden_user_instructions = nil
+        max_retries = artifacts_errors_max_retries
+        artifacts_errors_retries = 0
+        last_artifact_keys = nil
+        retry_on(
+          proc do |_agent, exception|
+            output_artifacts_errors = exception.is_a?(OutputArtifactsError) ? exception.output_artifacts_errors : {}
+            missing = missing_artifacts(output_artifacts_errors)
+            artifact_keys = missing.keys
+
+            # Reset counter when the set of artifacts needing retry changes between iterations
+            if artifact_keys != last_artifact_keys
+              artifacts_errors_retries = 0
+              last_artifact_keys = artifact_keys
+            end
+
+            # If no artifacts need retry, return nil (no retry)
+            if artifact_keys.empty?
+              nil
+            elsif artifacts_errors_retries >= max_retries
+              artifacts_errors_retries = 0
+              last_artifact_keys = []
+              raise ArtifactsErrorsMaxRetriesExceededError,
+                    "Maximum number of retries (#{max_retries}) exceeded. Missing or errored artifacts: #{artifact_keys.join(', ')}"
+            else
+              artifacts_errors_retries += 1
+              { modifier: proc { @overridden_user_instructions = missing_output_user_instructions(missing) } }
+            end
+          end
+        )
+      end
+
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      # On retry, uses +@overridden_user_instructions+ (set by the retry policy's modifier)
+      # instead of the original +user_instructions+.
+      #
+      # @param user_instructions [Object, nil] Instructions for the user prompt, that will be rendered.
+      # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content, per artifact name
+      # @return [Hash{Symbol => Object}] The output artifacts
+      def run(user_instructions: nil, **input_artifacts)
+        if @overridden_user_instructions
+          user_instructions = @overridden_user_instructions
+          @overridden_user_instructions = nil
+        end
+        super
+      end
+
+      private
+
+      # Compute the missing output artifacts with their descriptions and errors.
+      #
+      # @param output_artifacts_errors [Hash{Symbol => String}] Artifacts having errors, per artifact name,
+      #   as given by the {OutputArtifactsError} raised by the run (or empty if none).
+      # @return [Hash{Symbol => Hash{Symbol => Object}}] Missing artifacts, per artifact name.
+      def missing_artifacts(output_artifacts_errors)
+        normalized_output_artifacts_contracts
+          .reject { |artifact_name, _artifact_description| @output_artifacts.key?(artifact_name) }
+          .to_h do |artifact_name, artifact_description|
+            [
+              artifact_name,
+              artifact_description.merge(output_artifacts_errors[artifact_name] ? { error: output_artifacts_errors[artifact_name] } : {})
+            ]
+          end
+      end
+    end
+  end
+end

data/lib/composable_agents/output_artifacts_error.rb

@@ -0,0 +1,16 @@
+module ComposableAgents
+  # Custom exception raised when output artifacts have errors.
+  # The whole output_artifacts_errors structure is embedded in the exception.
+  class OutputArtifactsError < StandardError
+    # @return [Hash{Symbol => String}] The list of artifacts in error, with their corresponding error message.
+    attr_reader :output_artifacts_errors
+
+    # Initialize a new OutputArtifactsError with the errors hash.
+    #
+    # @param output_artifacts_errors [Hash] Hash of artifact names to errors
+    def initialize(output_artifacts_errors)
+      @output_artifacts_errors = output_artifacts_errors
+      super("Output artifacts errors: #{output_artifacts_errors.inspect}")
+    end
+  end
+end

data/lib/composable_agents/prompt_driven_agent.rb

@@ -59,6 +59,8 @@ module ComposableAgents
       @system_instructions = system_instructions
       @constraints = constraints
       @conversation = []
+      @output_artifacts = {}
+      @output_artifacts_errors = {}
     end
 
     # Execute the agent to generate some output artifacts based on some input artifacts.
@@ -70,29 +72,14 @@ module ComposableAgents
     def run(user_instructions: nil, **input_artifacts)
       super
       @input_artifacts = input_artifacts
-      @output_artifacts = {}
-      @output_artifacts_errors = {}
       @system_prompt = render_system_prompt(render_instructions(@system_instructions))
       logger.debug "System prompt: #{@system_prompt}"
+      # TODO: Merge converse and prompt directly here. No need for this extra complexity now that Retriable has been moved out.
       converse(user_instructions, input_artifacts: @input_artifacts, author: 'User')
-      if respond_to?(:normalized_output_artifacts_contracts, true)
-        # We know which output artifacts we are expecting.
-        # Therefore check if some are missing and prompt again if that's the case.
-        # TODO: Implement a max number of retries and throw an exception if it exceeds.
-        loop do
-          missing_artifacts = normalized_output_artifacts_contracts
-            .reject { |artifact_name, _artifact_description| @output_artifacts.key?(artifact_name) }
-            .to_h do |artifact_name, artifact_description|
-              [
-                artifact_name,
-                artifact_description.merge(@output_artifacts_errors[artifact_name] ? { error: @output_artifacts_errors[artifact_name] } : {})
-              ]
-            end
-          break if missing_artifacts.empty?
-
-          converse(missing_output_user_instructions(missing_artifacts))
-        end
-      end
+      # Raise an exception if some output artifacts have errors.
+      output_artifacts_errors = output_artifacts_errors_to_raise
+      raise OutputArtifactsError, output_artifacts_errors unless output_artifacts_errors.empty?
+
       @output_artifacts
     end
 
@@ -168,6 +155,15 @@ module ComposableAgents
 
     private
 
+    # Get the output artifacts errors that should raise an {OutputArtifactsError} at the end of a run.
+    # By default, all the errors that were reported during the run should raise.
+    # This is a hook that other mixins can override to restrict the errors that should raise.
+    #
+    # @return [Hash{Symbol => String}] The output artifacts errors that should raise, per artifact name
+    def output_artifacts_errors_to_raise
+      @output_artifacts_errors
+    end
+
     # Render instructions using the prompt rendering strategy.
     # Returns nil if instructions is nil.
     #

data/lib/composable_agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 2.1.3
+  version: 3.0.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -80,6 +80,7 @@ files:
 - lib/composable_agents/ai_agents/tools/base_tool.rb
 - lib/composable_agents/ai_agents/tools/create_artifact_tool.rb
 - lib/composable_agents/ai_agents/tools/get_artifact_tool.rb
+- lib/composable_agents/artifacts_errors_max_retries_exceeded_error.rb
 - lib/composable_agents/cline/agent.rb
 - lib/composable_agents/instructions.rb
 - lib/composable_agents/logger.rb
@@ -87,7 +88,10 @@ 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/retriable_artifacts.rb
 - lib/composable_agents/mixins/user_interaction.rb
+- lib/composable_agents/output_artifacts_error.rb
 - lib/composable_agents/prompt_driven_agent.rb
 - lib/composable_agents/prompt_rendering_strategy/markdown.rb
 - lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb