composable_agents 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 491a6d82dbce4b508dc8d83cda6d067b1ad13db47c0099e682beb900bf7964de
-  data.tar.gz: 1b488811d68e2d2233621111cf053df6e1b55fd15d7a686502b8eded4a4a04e7
+  metadata.gz: 753d56bfc73e0b268d107ae37338f3efa465fc1fe559813228aa3498e6544d9e
+  data.tar.gz: 21ac2d0a614a3044f392675dd988dce82c4ffcc5cb2c5192ae9a8f32416bab1d
 SHA512:
-  metadata.gz: 50c6da2263939742f55d9f8e324e5ffc78ab266c053b5831918520cb2c1cbb0377e7980b9a979984446260abfec1f2fe05e9b27e72ba9276594b49106ae0d071
-  data.tar.gz: dad24a674070a0dc75c0c9b7eb3c04fd70140b521a12ff8058c86b16856150d828cf08934bd9506ab8af9df4f4065e6ebf615e626cd75ed94a73133e756944eb
+  metadata.gz: 39d7fb3e1d61adb4ed78ca652b1f1aa5fc9b689cea004305de6ba14a56646725762ffb1c72965a69a516c804c5f3231197b474ebdcc4119830f708c9c85135b0
+  data.tar.gz: b2a60316353effb352cd785e54faa5f0b3d07a01f3c46fdf447f0dfdb57dc990f495ed12fddaf70eeb800cccac4b05b71ac14543bf9057c17b32f90a313dd09a

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+# [v3.7.0](https://github.com/Muriel-Salvan/composable_agents/compare/v3.6.1...v3.7.0) (2026-11-12 12:08:18)
+
+## Global changes
+### Patches
+
+* [feat(MarkdownHeavyFiles): implement MarkdownHeavyFiles prompt rendering strategy](https://github.com/Muriel-Salvan/composable_agents/commit/f6d2e057a64a98c79e5d2566893bdd92bc16185e)
+
+## Changes for MarkdownHeavyFiles
+### Features
+
+* [feat(MarkdownHeavyFiles): implement MarkdownHeavyFiles prompt rendering strategy](https://github.com/Muriel-Salvan/composable_agents/commit/f6d2e057a64a98c79e5d2566893bdd92bc16185e)
+
+# [v3.6.1](https://github.com/Muriel-Salvan/composable_agents/compare/v3.6.0...v3.6.1) (2026-11-07 16:11:50)
+
+### Patches
+
+* [test: add logger coverage and improve SimpleCov configuration](https://github.com/Muriel-Salvan/composable_agents/commit/68804370a2d54917eb3792ec4932db3fc4941b4a)
+
 # [v3.6.0](https://github.com/Muriel-Salvan/composable_agents/compare/v3.5.0...v3.6.0) (2026-11-07 11:35:50)
 
 ## Global changes

data/README.md

@@ -203,7 +203,7 @@ itinerary_agent = ComposableAgents::Cline::Agent.new(
 - 🧠 **Three agent types** — Create LLM-powered agents via [`PromptDrivenAgent`](lib/composable_agents/prompt_driven_agent.rb), wrap plain Ruby logic with [`RubyAgent`](lib/composable_agents/ruby_agent.rb), or compose complex multi-step workflows using the [`Resumable`](lib/composable_agents/mixins/resumable.rb) mixin.
 - 🔄 **Composable pipelines** — Pass output artifacts from one agent directly as input to another, forming reusable, chainable workflows.
 - 🎯 **Multiple LLM backends** — Plug into different AI providers via the [`ai-agents`](https://github.com/nicbarker/ai-agents) gem (OpenRouter) or [`cline-rb`](https://github.com/Muriel-Salvan/cline-rb) (Claude, GPT, and many more).
-- 📝 **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.
+- 📝 **Three prompt rendering strategies** — Choose between clean **Markdown** for simple agents, **MarkdownHeavy** with structured output parsing, execution checklists, and typed artifact support for complex agentic systems, or **MarkdownHeavyFiles** which persists input and output artifacts as files on disk.
 - 📦 **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.
@@ -292,7 +292,7 @@ The project is a Ruby library (not a CLI) — users install the gem and use its
 
 #### `ComposableAgents::PromptDrivenAgent < Agent`
 
-- **Description:** An agent that uses a **prompt rendering strategy** (Markdown or MarkdownHeavy) to build prompts for an LLM. It manages role, objective, instructions, constraints, and a conversation history.
+- **Description:** An agent that uses a **prompt rendering strategy** (Markdown, MarkdownHeavy, or MarkdownHeavyFiles) to build prompts for an LLM. It manages role, objective, instructions, constraints, and a conversation history.
 - **Public methods:**
   - `#role` / `#role=` — Agent's role description.
   - `#objective` / `#objective=` — Agent's objective.
@@ -568,7 +568,7 @@ When a proc returns a policy, the agent waits `wait_secs` seconds, applies the `
 ### Additional notes
 
 - **No executables / CLI** — This gem is a library only; there are no scripts in `bin/`.
-- **Prompt rendering strategies** (`PromptRenderingStrategy::Markdown` and `PromptRenderingStrategy::MarkdownHeavy`) are not part of the public API themselves — they are included automatically by the agent's `strategy:` parameter.
+- **Prompt rendering strategies** (`PromptRenderingStrategy::Markdown`, `PromptRenderingStrategy::MarkdownHeavy`, and `PromptRenderingStrategy::MarkdownHeavyFiles`) are not part of the public API themselves — they are included automatically by the agent's `strategy:` parameter.
 - **The `AiAgentUserInteraction` mixin** (`ComposableAgents::Mixins::AiAgentUserInteraction`) is an internal bridge that combines `UserInteraction` with `AiAgents::Agent`; it is used by prepending it to an `AiAgents::Agent` subclass.
 - See the [examples/](https://github.com/Muriel-Salvan/composable_agents/tree/main/examples) directory for complete, runnable scripts demonstrating all the above APIs.
 
@@ -594,6 +594,7 @@ When a proc returns a policy, the agent waits `wait_secs` seconds, applies the `
   - [`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
+  - [`PromptRenderingStrategy::MarkdownHeavyFiles`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/prompt_rendering_strategy/markdown_heavy_files.rb) — Heavy Markdown prompt strategy persisting artifacts as files
   - [`Utils::Markdown`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/utils/markdown.rb) — Markdown header alignment utilities
 
 ## How it works
@@ -674,10 +675,11 @@ flowchart TD
 
 ### Prompt rendering strategies 📝
 
-Two strategies are included, mixed into the agent at initialization via `singleton_class.include strategy`:
+Three strategies are included, mixed into the agent at initialization via `singleton_class.include strategy`:
 
 - **`PromptRenderingStrategy::Markdown`** — Clean, minimal Markdown. Simple instructions and artifact references.
 - **`PromptRenderingStrategy::MarkdownHeavy`** (default for Cline) — Elaborate prompts with execution checklists, structured artifact definition sections, and **JSON-based output parsing**. Agents format their artifacts as JSON blocks tagged with `output_artifact=NAME`, which the strategy parses back into the output hash. Includes type-aware parsing (`:text`, `:markdown`, `:json`).
+- **`PromptRenderingStrategy::MarkdownHeavyFiles`** — Same heavy Markdown behavior as `MarkdownHeavy`, but artifacts are persisted as files on disk instead of being in-lined or returned as JSON. Input artifacts are written to files that the assistant is asked to open, and output artifacts are expected as files that are read back from disk. Accepts an `artifacts_directory` constructor parameter (defaults to `#{composable_agents_dir}/artifacts`).
 
 ### LLM backends: ai-agents vs cline-rb 🎯
 
@@ -764,7 +766,7 @@ npm install node-pty
 │       ├── ai_agents/            # ai-agents backend
 │       ├── cline/                # cline-rb backend
 │       ├── mixins/               # ArtifactContract, Logger, Resumable, Retriable, RetriableArtifacts, RetriableCline, UserInteraction
-│       ├── prompt_rendering_strategy/ # Markdown & MarkdownHeavy strategies
+│       ├── prompt_rendering_strategy/ # Markdown, MarkdownHeavy & MarkdownHeavyFiles strategies
 │       └── utils/                # Markdown utilities
 ├── spec/                         # Test suite
 │   ├── scenarios/                # RSpec test cases

data/lib/composable_agents/prompt_driven_agent.rb

@@ -52,8 +52,8 @@ module ComposableAgents
       strategy: PromptRenderingStrategy::Markdown,
       **kwargs
     )
-      super(*args, **kwargs)
       singleton_class.include strategy
+      super(*args, **kwargs)
       @role = role
       @objective = objective
       @system_instructions = system_instructions

data/lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb

@@ -59,68 +59,8 @@ module ComposableAgents
         sections = [super]
         # Don't document the user instructions themselves
         input_contracts = normalized_input_artifacts_contracts.except(:user_instructions)
-        unless input_contracts.empty?
-          sections << <<~EO_SECTION
-            # Input artifacts' concept and usage
-
-            - Artifacts are documents that you can get as input.
-            - Each artifact is identified by a name, like `#{artifact_ref(:plan)}`.
-            - You must consider all artifacts given in the "Input artifacts" section of the user prompt.
-            - All artifacts presented in the "Input artifacts" section of the user prompt provide their content in an in-line JSON document.
-            #{
-              input_contracts.map do |artifact_name, artifact_contract|
-                art_ref = artifact_ref(artifact_name)
-                [
-                  "- The content of input artifact `#{art_ref}` describes this: #{artifact_contract[:description]}"
-                ] + (
-                  if artifact_contract[:optional]
-                    ["- The input artifact `#{art_ref}` is optional and may not be given to you."]
-                  else
-                    ["- The input artifact `#{art_ref}` is expected to be in the user prompt."]
-                  end
-                ) + [
-                  "- The input artifact `#{art_ref}` artifact content is embedded directly in the user prompt as in-line JSON. It is NOT a file. Do NOT try to open it as a file."
-                ]
-              end.compact.flatten(1).join("\n")
-            }
-          EO_SECTION
-        end
-        unless normalized_output_artifacts_contracts.empty?
-          sections << <<~EO_SECTION
-            # Output artifacts' concept and usage
-
-            - The user will ask you to provide some artifacts as output.
-            - You must always return the required artifact as a JSON document in your response, with its name in the JSON header, like this:
-              ```json output_artifact=#{artifact_ref(:name)}
-              {artifact_content}
-              ```
-            - Do not create files for output artifacts: always give them inside embedded JSON in your last response.
-            - Always return output artifacts that the user is asking you to provide.
-            - You can return several output artifacts in your responses if needed.
-
-            Following sections enumerate all expected output artifacts.
-
-            #{
-              normalized_output_artifacts_contracts.map do |artifact_name, artifact_contract|
-                art_ref = artifact_ref(artifact_name)
-                (
-                  [
-                    "## Output artifact `#{art_ref}`",
-                    '',
-                    "- The content of output artifact `#{art_ref}` should describe this: #{artifact_contract[:description]}"
-                  ] + (
-                    artifact_contract[:type] ? ["- The output artifact `#{art_ref}` content format should be #{artifact_contract[:type]}"] : []
-                  ) + [
-                    <<~EO_ITEM.strip
-                      - The output artifact `#{art_ref}` should be given in a block like this:
-                      #{example_json_block(artifact_name)}
-                    EO_ITEM
-                  ]
-                ).join("\n")
-              end.join("\n\n")
-            }
-          EO_SECTION
-        end
+        sections << render_input_artifacts_system_prompt_section(input_contracts) unless input_contracts.empty?
+        sections << render_output_artifacts_system_prompt_section unless normalized_output_artifacts_contracts.empty?
         sections.map(&:strip).join("\n\n")
       end
 
@@ -288,6 +228,77 @@ module ComposableAgents
 
       private
 
+      # Render the input artifacts concept section of the system prompt.
+      #
+      # @param input_contracts [Hash{Symbol => Hash{Symbol => Object}}] The normalized input artifacts contracts
+      # @return [String] The rendered input artifacts' concept and usage section
+      def render_input_artifacts_system_prompt_section(input_contracts)
+        <<~EO_SECTION
+          # Input artifacts' concept and usage
+
+          - Artifacts are documents that you can get as input.
+          - Each artifact is identified by a name, like `#{artifact_ref(:plan)}`.
+          - You must consider all artifacts given in the "Input artifacts" section of the user prompt.
+          - All artifacts presented in the "Input artifacts" section of the user prompt provide their content in an in-line JSON document.
+          #{
+            input_contracts.map do |artifact_name, artifact_contract|
+              art_ref = artifact_ref(artifact_name)
+              [
+                "- The content of input artifact `#{art_ref}` describes this: #{artifact_contract[:description]}"
+              ] + (
+                if artifact_contract[:optional]
+                  ["- The input artifact `#{art_ref}` is optional and may not be given to you."]
+                else
+                  ["- The input artifact `#{art_ref}` is expected to be in the user prompt."]
+                end
+              ) + [
+                "- The input artifact `#{art_ref}` artifact content is embedded directly in the user prompt as in-line JSON. It is NOT a file. Do NOT try to open it as a file."
+              ]
+            end.compact.flatten(1).join("\n")
+          }
+        EO_SECTION
+      end
+
+      # Render the output artifacts concept section of the system prompt.
+      #
+      # @return [String] The rendered output artifacts' concept and usage section
+      def render_output_artifacts_system_prompt_section
+        <<~EO_SECTION
+          # Output artifacts' concept and usage
+
+          - The user will ask you to provide some artifacts as output.
+          - You must always return the required artifact as a JSON document in your response, with its name in the JSON header, like this:
+            ```json output_artifact=#{artifact_ref(:name)}
+            {artifact_content}
+            ```
+          - Do not create files for output artifacts: always give them inside embedded JSON in your last response.
+          - Always return output artifacts that the user is asking you to provide.
+          - You can return several output artifacts in your responses if needed.
+
+          Following sections enumerate all expected output artifacts.
+
+          #{
+            normalized_output_artifacts_contracts.map do |artifact_name, artifact_contract|
+              art_ref = artifact_ref(artifact_name)
+              (
+                [
+                  "## Output artifact `#{art_ref}`",
+                  '',
+                  "- The content of output artifact `#{art_ref}` should describe this: #{artifact_contract[:description]}"
+                ] + (
+                  artifact_contract[:type] ? ["- The output artifact `#{art_ref}` content format should be #{artifact_contract[:type]}"] : []
+                ) + [
+                  <<~EO_ITEM.strip
+                    - The output artifact `#{art_ref}` should be given in a block like this:
+                    #{example_json_block(artifact_name)}
+                  EO_ITEM
+                ]
+              ).join("\n")
+            end.join("\n\n")
+          }
+        EO_SECTION
+      end
+
       # Provide a Markdown example of a JSON block for a given output artifact
       #
       # @param artifact_name [Symbol] The output artifact name

data/lib/composable_agents/prompt_rendering_strategy/markdown_heavy_files.rb

@@ -0,0 +1,266 @@
+require 'json'
+require 'fileutils'
+
+module ComposableAgents
+  module PromptRenderingStrategy
+    # Render prompt as Markdown documents with a lot of emphasis for complex agentic systems,
+    # where input and output artifacts are persisted as files on disk instead of being in-lined
+    # as JSON in the prompts and responses.
+    # This prompt strategy needs to be used conjointly with the ArtifactContract mixin.
+    # It inherits from the {MarkdownHeavy} strategy and only differs in the way artifacts are handled:
+    # - Input artifacts are given to the assistant as absolute paths to files persisted on disk.
+    # - Output artifacts are expected to be written by the assistant to files, at absolute paths
+    #   that are then read back by {#parse_output_artifacts}.
+    # This mixin also adds the following methods to be used:
+    # - `#parse_output_artifacts(text)` Parses a text that comes from the agent to retrieve output artifacts from files.
+    # - `#artifact_ref(artifact_name) -> String` Returns the absolute path of the artifact file as seen by the assistant.
+    #     This can be used to refer to the artifact names properly in the user or system instructions.
+    # The constructor accepts the following extra parameter:
+    # - `artifacts_directory` [String, nil] Directory where artifacts are persisted, or nil to default to
+    #   `#{composable_agents_dir}/artifacts`. Input and output artifacts are persisted in the
+    #   `input` and `output` sub-directories respectively.
+    module MarkdownHeavyFiles
+      # @!group Internal
+
+      include MarkdownHeavy
+
+      # Constructor
+      #
+      # @param artifacts_directory [String, nil] Directory where artifacts are persisted, or nil to default to
+      #   `#{composable_agents_dir}/artifacts`
+      def initialize(*args, artifacts_directory: nil, **kwargs)
+        super(*args, **kwargs)
+        artifacts_directory ||= "#{@composable_agents_dir}/artifacts"
+        @input_artifacts_directory = File.join(artifacts_directory, 'input')
+        @output_artifacts_directory = File.join(artifacts_directory, 'output')
+        FileUtils.mkdir_p(@input_artifacts_directory)
+        FileUtils.mkdir_p(@output_artifacts_directory)
+      end
+
+      # Render the user prompt
+      # The following instance variables are accessible to render the prompt:
+      # - `@role`
+      # - `@objective`
+      # - `@constraints`
+      #
+      # @param rendered_instructions [String, nil] The rendered instructions, or nil if none
+      # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content for which we render this prompt, per artifact name
+      # @return [String] The rendered user prompt
+      def render_user_prompt(rendered_instructions, input_artifacts:)
+        sections = []
+        unless input_artifacts.empty?
+          sections << <<~EO_SECTION.strip
+            # Input artifacts
+
+            The following input artifacts are persisted as files on disk. Open and read each file whenever you need the corresponding input artifact content:
+
+            #{
+              input_artifacts.map do |artifact_name, artifact_content|
+                art_path = persist_input_artifact(artifact_name, artifact_content)
+                <<~EO_ARTIFACT_SECTION.strip
+                  ## `#{art_path}`
+
+                  - Open and read the file `#{art_path}` whenever you need the corresponding input artifact content.
+                EO_ARTIFACT_SECTION
+              end.join("\n\n")
+            }
+          EO_SECTION
+        end
+        sections << <<~EO_SECTION if rendered_instructions && !rendered_instructions.empty?
+          # User instructions
+
+          #{Utils::Markdown.align_markdown_headers(rendered_instructions, level: 2)}
+        EO_SECTION
+        sections.map(&:strip).join("\n\n")
+      end
+
+      # Get the artifact reference communicated to the assistant, as the absolute path of its file.
+      #
+      # @param artifact_name [Symbol] The artifact name
+      # @return [String] The absolute path of the artifact file used for the assistant
+      def artifact_ref(artifact_name)
+        if normalized_input_artifacts_contracts.key?(artifact_name)
+          input_artifact_path(artifact_name)
+        elsif normalized_output_artifacts_contracts.key?(artifact_name)
+          output_artifact_path(artifact_name)
+        else
+          raise "Unknown artifact: #{artifact_name}"
+        end
+      end
+
+      # Get user instructions for missing output artifacts
+      #
+      # @param missing_output_artifacts [Hash{Symbol => Object}] The missing output artifacts information, per artifact name
+      #   Information can contain the following attributes:
+      #   - description [String] The artifact's description.
+      #   - error [String, nil] An error message related to this missing artifact.
+      # @return [Object] The user instructions (see Instructions#initialize)
+      def missing_output_user_instructions(missing_output_artifacts)
+        logger.debug '[Artifact] - Asking assistant for missing output artifacts ' \
+          "`#{missing_output_artifacts.keys.join(', ')}` to be written as files in its next answer."
+        <<~EO_PROMPT
+          The following output artifacts are missing from your previous responses:
+          #{
+            missing_output_artifacts.map do |artifact_name, missing_info|
+              ["- `#{output_artifact_path(artifact_name)}`: #{missing_info[:description]}"] +
+                (missing_info[:error] ? ["  An error occurred while reading this artifact from your previous responses: #{missing_info[:error]}"] : [])
+            end.flatten(1).join("\n")
+          }
+
+          You must write each one of them to its expected file path (the absolute paths given above) in your next response (MANDATORY).
+        EO_PROMPT
+      end
+
+      # Parse some text to find output artifacts in the files they are persisted to.
+      #
+      # @param text [String] The text to be parsed
+      def parse_output_artifacts(text)
+        logger.debug "[Artifact] - Looking for output artifacts persisted as files (ignoring the assistant text response): #{text}"
+        normalized_output_artifacts_contracts.each_key do |artifact_name|
+          artifact_path = output_artifact_path(artifact_name)
+          next unless File.exist?(artifact_path)
+
+          artifact_type = normalized_output_artifacts_contracts.dig(artifact_name, :type)
+          artifact_content =
+            begin
+              read_output_artifact(artifact_path, artifact_type)
+            rescue JSON::ParserError => e
+              report_error_for_output_artifact(artifact_name, e.to_s)
+              nil
+            end
+          save_output_artifact(artifact_name, artifact_content) if artifact_content
+        end
+      end
+
+      private
+
+      # Render the input artifacts concept section of the system prompt.
+      #
+      # @param input_contracts [Hash{Symbol => Hash{Symbol => Object}}] The normalized input artifacts contracts
+      # @return [String] The rendered input artifacts' concept and usage section
+      def render_input_artifacts_system_prompt_section(input_contracts)
+        <<~EO_SECTION
+          # Input artifacts' concept and usage
+
+          - Artifacts are documents that you can get as input.
+          - Each input artifact is persisted as a file on disk, identified by its absolute path, like `#{input_artifact_path(input_contracts.keys.first)}`.
+          - You must consider all artifacts given in the "Input artifacts" section of the user prompt.
+          - The "Input artifacts" section of the user prompt gives you the absolute path of each input artifact file.
+          - Open and read the file at the given absolute path whenever you need the corresponding input artifact content.
+          - The file extension indicates the artifact content type: `.json` for JSON, `.md` for Markdown, `.txt` for raw text.
+          #{
+            input_contracts.map do |artifact_name, artifact_contract|
+              art_ref = input_artifact_path(artifact_name)
+              [
+                "- The content of input artifact `#{art_ref}` describes this: #{artifact_contract[:description]}"
+              ] + (
+                if artifact_contract[:optional]
+                  ["- The input artifact `#{art_ref}` is optional and may not be given to you."]
+                else
+                  ["- The input artifact `#{art_ref}` is expected in the user prompt."]
+                end
+              )
+            end.flatten(1).join("\n")
+          }
+        EO_SECTION
+      end
+
+      # Render the output artifacts concept section of the system prompt.
+      #
+      # @return [String] The rendered output artifacts' concept and usage section
+      def render_output_artifacts_system_prompt_section
+        <<~EO_SECTION
+          # Output artifacts' concept and usage
+
+          - The user will ask you to provide some artifacts as output.
+          - Each output artifact must be written to a file on disk, at the exact absolute path given in this system prompt.
+          - Do NOT return output artifacts inline in your response: always write each one of them to its expected file path.
+          - Always return output artifacts that the user is asking you to provide.
+          - You can return several output artifacts in your responses if needed.
+
+          Following sections enumerate all expected output artifacts.
+
+          #{
+            normalized_output_artifacts_contracts.map do |artifact_name, artifact_contract|
+              art_ref = output_artifact_path(artifact_name)
+              (
+                [
+                  "## Output artifact `#{art_ref}`",
+                  '',
+                  "- The content of output artifact `#{art_ref}` should describe this: #{artifact_contract[:description]}"
+                ] + (
+                  artifact_contract[:type] ? ["- The output artifact `#{art_ref}` content format should be #{artifact_contract[:type]}"] : []
+                ) + [
+                  "- Write the output artifact `#{art_ref}` to this exact absolute path. The file extension indicates the expected content type."
+                ]
+              ).join("\n")
+            end.join("\n\n")
+          }
+        EO_SECTION
+      end
+
+      # Get the file extension to use for a given artifact type.
+      #
+      # @param artifact_type [Symbol, nil] The artifact type
+      # @return [String] The corresponding file extension
+      def artifact_extension(artifact_type)
+        case artifact_type
+        when :text then '.txt'
+        when :markdown then '.md'
+        when :json, nil then '.json'
+        else raise "Unknown artifact type: #{artifact_type}"
+        end
+      end
+
+      # Get the absolute path of an input artifact file.
+      #
+      # @param artifact_name [Symbol] The input artifact name
+      # @return [String] The absolute path of the input artifact file
+      def input_artifact_path(artifact_name)
+        File.join(
+          @input_artifacts_directory,
+          "#{artifact_name}#{artifact_extension(normalized_input_artifacts_contracts.dig(artifact_name, :type))}"
+        )
+      end
+
+      # Get the absolute path of an output artifact file.
+      #
+      # @param artifact_name [Symbol] The output artifact name
+      # @return [String] The absolute path of the output artifact file
+      def output_artifact_path(artifact_name)
+        File.join(
+          @output_artifacts_directory,
+          "#{artifact_name}#{artifact_extension(normalized_output_artifacts_contracts.dig(artifact_name, :type))}"
+        )
+      end
+
+      # Persist an input artifact to its file.
+      #
+      # @param artifact_name [Symbol] The input artifact name
+      # @param artifact_content [Object] The input artifact content
+      # @return [String] The absolute path where the artifact was persisted
+      def persist_input_artifact(artifact_name, artifact_content)
+        artifact_path = input_artifact_path(artifact_name)
+        artifact_type = normalized_input_artifacts_contracts.dig(artifact_name, :type)
+        File.write(
+          artifact_path,
+          %i[text markdown].include?(artifact_type) ? artifact_content : JSON.pretty_generate(artifact_content)
+        )
+        artifact_path
+      end
+
+      # Read an output artifact from its file.
+      #
+      # @param artifact_path [String] The absolute path of the output artifact file
+      # @param artifact_type [Symbol, nil] The output artifact type
+      # @return [Object] The output artifact content
+      def read_output_artifact(artifact_path, artifact_type)
+        if %i[text markdown].include?(artifact_type)
+          File.read(artifact_path)
+        else
+          JSON.parse(File.read(artifact_path))
+        end
+      end
+    end
+  end
+end

data/lib/composable_agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -98,6 +98,7 @@ files:
 - lib/composable_agents/prompt_driven_agent.rb
 - lib/composable_agents/prompt_rendering_strategy/markdown.rb
 - lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb
+- lib/composable_agents/prompt_rendering_strategy/markdown_heavy_files.rb
 - lib/composable_agents/ruby_agent.rb
 - lib/composable_agents/run_info.rb
 - lib/composable_agents/utils/markdown.rb