composable_agents 1.0.0

data/lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb

@@ -0,0 +1,301 @@
+require 'json'
+
+module ComposableAgents
+  module PromptRenderingStrategy
+    # Render prompt as Markdown documents with a lot of emphasis for complex agentic systems.
+    # This prompt strategy needs to be used conjointly with the ArtifactContract mixin.
+    # 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 it.
+    # - `#artifact_ref(artifact_name) -> String` Returns the artifact name as seen by the assistant.
+    #     This can be used to refer to the artifact names properly in the user or system instructions.
+    module MarkdownHeavy
+      # @!group Internal
+
+      include Markdown
+
+      # Render an instruction of type ordered_list
+      #
+      # @param instruction [Array<String>] The instruction to render
+      # @return [String] The rendered instruction
+      def render_instruction_ordered_list(instruction)
+        return '' if instruction.empty?
+
+        checklist_name = "#{name || 'Agent'} Execution Checklist"
+        <<~EO_INSTRUCTIONS
+          Always follow all those sequential steps.
+
+          # 1. Create the #{checklist_name} (MANDATORY)
+
+          - Before executing anything, create a checklist named #{checklist_name} with all steps of these instructions.
+          - Do not create files to track this checklist: keep it in your memory.
+          - The #{checklist_name} must include all numbered steps explicitly.
+          - After completing each step of these instructions, mark the item in the #{checklist_name} as completed.
+          - Do not skip any item.
+          - If an item cannot be executed, explicitly explain why.
+          - Never mark the task as completed while any item from the #{checklist_name} remains open.
+
+          #{instruction.map.with_index { |step, step_idx| "# #{step_idx + 2}. #{Utils::Markdown.align_markdown_headers(step, level: 2).strip}" }.join("\n\n")}
+
+          # #{instruction.size + 2}. Final Verification (MANDATORY)
+
+          Before declaring the task complete:
+
+          - Re-list all numbered steps from the #{checklist_name}.
+          - Confirm each one was executed.
+          - If any step was not executed, execute it now.
+        EO_INSTRUCTIONS
+      end
+
+      # Render the system prompt
+      # The following instance variables are accessible to render the prompt:
+      # - `@input_artifacts`
+      # - `@role`
+      # - `@objective`
+      # - `@constraints`
+      #
+      # @param rendered_instructions [String, nil] The rendered system instructions, or nil if none
+      # @return [String] The rendered system prompt
+      def render_system_prompt(rendered_instructions)
+        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.map(&:strip).join("\n\n")
+      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
+
+            #{
+              input_artifacts.map do |artifact_name, artifact_content|
+                art_ref = artifact_ref(artifact_name)
+                <<~EO_ARTIFACT_SECTION.strip
+                  ## `#{art_ref}`
+
+                  ```json input_artifact=#{art_ref}
+                  #{JSON.dump(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 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)
+        log_debug "[Artifact] - Asking assistant for missing output artifacts `#{missing_output_artifacts.keys.join(', ')}` to be returned 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|
+              ["- `#{artifact_ref(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 provide each one of them in your next response using embedded JSON blocks like this:
+
+          #{
+            missing_output_artifacts.keys.map { |artifact_name| example_json_block(artifact_name) }.join("\n\n")
+          }
+
+          - You must return all those artifacts in your next response (MANDATORY).
+        EO_PROMPT
+      end
+
+      # Get the artifact reference name communicated to the assistant
+      #
+      # @param artifact_name [Symbol] The artifact name
+      # @return [String] The artifact reference name used for the assistant
+      def artifact_ref(artifact_name)
+        "ARTIFACT_#{artifact_name.to_s.upcase}"
+      end
+
+      # Parse some text to find output artifacts in it.
+      #
+      # @param text [String] The text to be parsed
+      def parse_output_artifacts(text)
+        # Scan for JSON documents with artifact markers in the format:
+        # ```json output_artifact=ARTIFACT_<NAME>
+        # {artifact_content}
+        # ```
+        text.scan(/```json\s+output_artifact=(\S+)\n(.*?)```(?=\n|\z)/m) do
+          art_ref = Regexp.last_match(1)
+          content = Regexp.last_match(2).strip
+          # Convert the assistant artifact name (e.g. ARTIFACT_PLAN) back to a symbol (e.g. :plan)
+          artifact_name = (art_ref.start_with?('ARTIFACT_') ? art_ref.sub(/^ARTIFACT_/, '') : art_ref).downcase.to_sym
+          artifact_json_content = nil
+          begin
+            artifact_json_content = JSON.parse(content)
+          rescue JSON::ParserError => e
+            report_error_for_output_artifact(artifact_name, e.to_s)
+            next
+          end
+          # Use the type info to better parse the JSON into the real artifact content
+          artifact_type = normalized_output_artifacts_contracts.dig(artifact_name, :type)
+          artifact_content =
+            case artifact_type
+            when nil, :json
+              artifact_json_content
+            when :text
+              if artifact_json_content.key?('text')
+                if artifact_json_content['text'].is_a?(String)
+                  artifact_json_content['text']
+                else
+                  report_error_for_output_artifact(
+                    artifact_name,
+                    'Wrong format for artifact content in key "text": ' \
+                      "expecting a raw String but got #{artifact_json_content['text'].class.name} instead."
+                  )
+                  nil
+                end
+              else
+                report_error_for_output_artifact(
+                  artifact_name,
+                  'Missing required key "text" containing the artifact text content in the JSON artifact response.'
+                )
+                nil
+              end
+            when :markdown
+              if artifact_json_content.key?('markdown')
+                if artifact_json_content['markdown'].is_a?(String)
+                  artifact_json_content['markdown']
+                else
+                  report_error_for_output_artifact(
+                    artifact_name,
+                    'Wrong format for artifact content in key "markdown": ' \
+                      "expecting a Markdown string but got #{artifact_json_content['markdown'].class.name} instead."
+                  )
+                  nil
+                end
+              else
+                report_error_for_output_artifact(
+                  artifact_name,
+                  'Missing required key "markdown" containing the artifact Markdown content in the JSON artifact response.'
+                )
+                nil
+              end
+            else
+              raise "Unknown artifact type: #{artifact_type}"
+            end
+          save_output_artifact(artifact_name, artifact_content) if artifact_content
+        end
+      end
+
+      private
+
+      # Provide a Markdown example of a JSON block for a given output artifact
+      #
+      # @param artifact_name [Symbol] The output artifact name
+      # @return [String] Corresponding Markdown example
+      def example_json_block(artifact_name)
+        art_ref = artifact_ref(artifact_name)
+        artifact_type = normalized_output_artifacts_contracts.dig(artifact_name, :type)
+        <<~EO_MARKDOWN.strip
+          ```json output_artifact=#{art_ref}
+          #{
+            case artifact_type
+            when nil
+              "#{art_ref}_content"
+            when :text
+              "{\"text\":\"#{art_ref}_raw_text_content\"}"
+            when :markdown
+              "{\"markdown\":\"#{art_ref}_markdown_content\"}"
+            when :json
+              "{#{art_ref}_json_content}"
+            else
+              raise "Unknown artifact type: #{artifact_type}"
+            end
+          }
+          ```
+        EO_MARKDOWN
+      end
+    end
+  end
+end

data/lib/composable_agents/ruby_agent.rb

@@ -0,0 +1,28 @@
+module ComposableAgents
+  # Agent implementation that wraps a Ruby Proc for custom logic
+  #
+  # This agent allows wrapping arbitrary Ruby logic as an Agent by providing
+  # a Proc that handles the transformation of input artifacts to output artifacts.
+  class RubyAgent < Agent
+    # @!group Public API
+
+    # Initialize a new RubyAgent with a processing proc
+    #
+    # @param processor [#call(Hash{Symbol => Object}) => Hash{Symbol => Object}] The agent logic.
+    #   This proc will receive the input artifacts hash and must return a hash of output artifacts.
+    #   - Param input_artifacts [Hash\\{Symbol => Object}] Input artifacts provided to the agent
+    #   - Return [Hash\\{Symbol => Object}] Output artifacts produced by the agent
+    def initialize(processor, *args, **kwargs)
+      super(*args, **kwargs)
+      @processor = processor
+    end
+
+    # Execute the agent to generate some output artifacts based on some input artifacts.
+    #
+    # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content, per artifact name
+    # @return [Hash{Symbol => Object}] The output artifacts returned by the Proc
+    def run(**input_artifacts)
+      @processor.call(input_artifacts)
+    end
+  end
+end

data/lib/composable_agents/utils/markdown.rb

@@ -0,0 +1,56 @@
+require 'commonmarker'
+
+module ComposableAgents
+  # Various internal helpers and utilities
+  module Utils
+    # Internal util methods to handle Markdown
+    module Markdown
+      class << self
+        # @!group Internal
+
+        # Align markdown headers in a String to a given level.
+        # This method parses the String as a markdown document, sees the minimum current header level,
+        # and changes it while preserving the structure and hierarchy so that this min level is equal to `level`.
+        #
+        # @param markdown [String] The markdown content to align
+        # @param level [Integer] The target level for the minimum header
+        # @return [String] The aligned markdown content
+        def align_markdown_headers(markdown, level: 2)
+          doc = Commonmarker.parse(markdown)
+          min_level = find_minimum_header_level(doc)
+          return markdown if min_level.nil? || min_level == level
+
+          adjust_header_levels(doc, level - min_level)
+          # Unescape dots in headers
+          # TODO: Remove this gsub when CommonMarker will be fixed.
+          doc.to_commonmark.gsub(/^\#{1,6}\s+\h+\K\\\. /, '. ')
+        end
+
+        # Find the minimum header level in a CommonMarker document
+        #
+        # @param doc [CommonMarker::Document] The parsed CommonMarker document
+        # @return [Integer, nil] The minimum header level found, or nil if no headers exist
+        def find_minimum_header_level(doc)
+          min_level = nil
+          doc.walk do |node|
+            if node.type == :heading
+              current_level = node.header_level
+              min_level = current_level if min_level.nil? || current_level < min_level
+            end
+          end
+          min_level
+        end
+
+        # Adjust header levels in a CommonMarker document by a given difference
+        #
+        # @param doc [CommonMarker::Document] The parsed CommonMarker document
+        # @param level_diff [Integer] The difference to add to each header level
+        def adjust_header_levels(doc, level_diff)
+          doc.walk do |node|
+            node.header_level = node.header_level + level_diff if node.type == :heading
+          end
+        end
+      end
+    end
+  end
+end

data/lib/composable_agents/version.rb

@@ -0,0 +1,6 @@
+module ComposableAgents
+  # @!group Public API
+
+  # Gem version
+  VERSION = '1.0.0'
+end

data/lib/composable_agents.rb

@@ -0,0 +1,7 @@
+require 'zeitwerk'
+
+Zeitwerk::Loader.for_gem.setup
+
+# Main module giving all needed classes to define aomposable agents.
+module ComposableAgents
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: composable_agents
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Muriel Salvan
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ai-agents
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: cline-rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: commonmarker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+email: muriel@x-aeon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- TODO.md
+- lib/composable_agents.rb
+- lib/composable_agents/agent.rb
+- lib/composable_agents/ai_agents/agent.rb
+- lib/composable_agents/ai_agents/tools/ask_user_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/cline/agent.rb
+- lib/composable_agents/instructions.rb
+- lib/composable_agents/mixins/ai_agent_user_interaction.rb
+- lib/composable_agents/mixins/artifact_contract.rb
+- lib/composable_agents/mixins/logger.rb
+- lib/composable_agents/mixins/resumable.rb
+- lib/composable_agents/mixins/user_interaction.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
+- lib/composable_agents/ruby_agent.rb
+- lib/composable_agents/utils/markdown.rb
+- lib/composable_agents/version.rb
+homepage: https://github.com/Muriel-Salvan/composable_agents
+licenses:
+- BSD-3-Clause
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Composable AI agents framework
+test_files: []