phronomy 0.3.0 → 0.4.0

data/lib/phronomy/agent/team_coordinator.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Implements the "Agent teams" coordination pattern (Anthropic blog, Pattern 3).
+    #
+    # @see https://claude.com/blog/multi-agent-coordination-patterns
+    #
+    # A coordinator LLM agent decomposes work into tasks and enqueues them
+    # dynamically via built-in tools. A fixed pool of worker agents claims tasks
+    # from the shared queue, carrying forward their conversation history across
+    # assignments to accumulate domain context over time.
+    #
+    # The coordinator is an {Agent::Base} subclass that has two built-in tools:
+    # - +enqueue_task+ — adds a task description to the queue
+    # - +finalize+     — signals that all tasks have been enqueued
+    #
+    # Worker persistence is implemented by passing each worker's accumulated
+    # +messages+ array back via +config[:messages]+ on every subsequent +invoke+
+    # call, so the LLM retains context across multiple task assignments.
+    #
+    # @example Basic usage
+    #   class MigrationTeam < Phronomy::Agent::TeamCoordinator
+    #     coordinator_model        "claude-3-5-sonnet-20241022"
+    #     coordinator_instructions <<~INST
+    #       Analyze the request and enqueue one migration task per service.
+    #       Call enqueue_task for each service, then call finalize.
+    #     INST
+    #
+    #     pool size: 3, agent: MigrationAgent
+    #
+    #     aggregate do |assignments|
+    #       { reports: assignments.map { |a| { task: a[:task][:description], result: a[:result] } } }
+    #     end
+    #   end
+    #
+    #   result = MigrationTeam.new.invoke("Migrate all services to Rails 8")
+    class TeamCoordinator
+      # Holds per-worker context between task invocations.
+      # Worker persistence is implemented by carrying +messages+ forward on each
+      # successive +agent#invoke+ call via +config[:messages]+.
+      WorkerState = Struct.new(
+        :index,    # Integer — 0-based worker index
+        :agent,    # Agent::Base instance
+        :messages, # Array  — accumulated conversation history
+        :status,   # Symbol — :idle | :available | :done
+        keyword_init: true
+      ) do
+        # Returns true when this worker is ready to accept the next task.
+        def available? = [:idle, :available].include?(status)
+      end
+      private_constant :WorkerState
+
+      class << self
+        # Sets the LLM model for the coordinator agent.
+        # Falls back to +Phronomy.configuration.default_model+ when not set.
+        #
+        # @param value [String, nil]
+        def coordinator_model(value = nil)
+          value ? @coordinator_model = value : @coordinator_model
+        end
+
+        # Sets the system instructions for the coordinator agent.
+        # The prompt should direct the LLM to call +enqueue_task+ for each task
+        # and then call +finalize+ when all tasks are enqueued.
+        #
+        # @param value [String, nil]
+        def coordinator_instructions(value = nil)
+          value ? @coordinator_instructions = value : @coordinator_instructions
+        end
+
+        # Sets the LLM provider for the coordinator agent.
+        # Required when using a custom +BASE_URL+ (e.g. LM Studio, Ollama, vLLM)
+        # so that RubyLLM does not attempt to resolve an unknown model name.
+        # Pass the same value as +LLMConfig::PROVIDER+ in your examples.
+        #
+        # @param value [Symbol, nil]
+        def coordinator_provider(value = nil)
+          value ? @coordinator_provider = value : @coordinator_provider
+        end
+
+        # Configures the worker pool.
+        #
+        # @param size     [Integer] number of persistent worker instances
+        # @param agent    [Class]   Agent::Base subclass used for all workers
+        # @param on_error [Symbol]  +:raise+ (default) propagates worker exceptions;
+        #                           +:skip+ records the failure and continues with remaining tasks
+        def pool(size:, agent:, on_error: :raise)
+          @pool_size = Integer(size)
+          @worker_agent = agent
+          @on_error = on_error
+        end
+
+        # Customises the worker selection algorithm.
+        # The block receives an Array of available WorkerState objects and must
+        # return the one to assign the next task to.
+        # Default: worker with the fewest accumulated messages (round-robin-like).
+        #
+        # @yield [Array<WorkerState>] available workers
+        # @yieldreturn [WorkerState] the chosen worker
+        def schedule(&block)
+          @scheduler = block
+        end
+
+        # Defines how task assignments are merged into the final return value.
+        # The block receives an Array of assignment Hashes:
+        #   { task: Hash, result: String|nil, worker: Integer, error: Exception|nil }
+        # When omitted, the raw assignments array is returned.
+        #
+        # @yield [Array<Hash>] all completed (and skipped) task assignments
+        def aggregate(&block)
+          @aggregator = block
+        end
+
+        # @!visibility private
+        def _coordinator_model = @coordinator_model
+        # @!visibility private
+        def _coordinator_instructions = @coordinator_instructions
+        # @!visibility private
+        def _coordinator_provider = @coordinator_provider
+        # @!visibility private
+        def _pool_size = @pool_size || 1
+        # @!visibility private
+        def _worker_agent = @worker_agent
+        # @!visibility private
+        def _on_error = @on_error || :raise
+        # @!visibility private
+        def _scheduler = @scheduler
+        # @!visibility private
+        def _aggregator = @aggregator
+      end
+
+      # Runs the full team coordination: coordinator generates tasks, workers
+      # process them sequentially, and the aggregate block merges the results.
+      #
+      # @param team_input [String, Hash] the high-level objective given to the coordinator
+      # @param config     [Hash]         reserved for future use
+      # @return [Object] the return value of the aggregate block, or the raw assignments Array
+      # @raise [ArgumentError] when +pool :agent+ has not been configured
+      def invoke(team_input, config: {})
+        raise ArgumentError, "pool :agent must be configured before invoking" unless self.class._worker_agent
+
+        task_queue = []
+        run_coordinator(team_input, task_queue)
+        assignments = run_workers(task_queue)
+        finalize_result(assignments)
+      end
+
+      # Streaming version of +invoke+. Yields a Hash event for each completed or
+      # failed task assignment.
+      #
+      # Yielded Hash keys:
+      #   :type   — +:task_completed+ or +:task_failed+
+      #   :worker — worker index (Integer)
+      #   :task   — the task Hash from the queue ({ id:, description:, metadata:, enqueued_at: })
+      #   :result — output string, or +nil+ on failure
+      #   :error  — Exception, or +nil+ on success
+      #
+      # @param team_input [String, Hash]
+      # @param config     [Hash]
+      # @yield [Hash] one event per completed/failed task
+      # @return [Object] same as +invoke+
+      # @raise [ArgumentError] when +pool :agent+ has not been configured
+      def stream(team_input, config: {}, &block)
+        return invoke(team_input, config: config) unless block
+
+        raise ArgumentError, "pool :agent must be configured before invoking" unless self.class._worker_agent
+
+        task_queue = []
+        run_coordinator(team_input, task_queue)
+        assignments = run_workers(task_queue, &block)
+        finalize_result(assignments)
+      end
+
+      private
+
+      # Phase 1: Run the coordinator LLM agent to populate task_queue.
+      def run_coordinator(team_input, task_queue)
+        coordinator = build_coordinator_agent(task_queue)
+        input = team_input.is_a?(String) ? team_input : team_input.to_s
+        coordinator.invoke(input)
+      end
+
+      # Phase 2: Process tasks from the queue using the worker pool.
+      # Workers accumulate message history across assignments.
+      def run_workers(task_queue, &event_block)
+        pool_size = self.class._pool_size
+        agent_class = self.class._worker_agent
+        on_error = self.class._on_error
+        scheduler = self.class._scheduler
+
+        workers = Array.new(pool_size) do |i|
+          WorkerState.new(index: i, agent: agent_class.new, messages: [], status: :idle)
+        end
+
+        assignments = []
+
+        until task_queue.empty?
+          task = task_queue.shift
+          available = workers.select(&:available?)
+          worker = scheduler ? scheduler.call(available) : default_scheduler(available)
+
+          begin
+            result = worker.agent.invoke(task[:description], config: {messages: worker.messages})
+            worker.messages = result[:messages]
+            worker.status = :available
+            entry = {task: task, result: result[:output], worker: worker.index, error: nil}
+            assignments << entry
+            event_block&.call(entry.merge(type: :task_completed))
+          rescue => e
+            worker.status = :available
+            raise unless on_error == :skip
+
+            entry = {task: task, result: nil, worker: worker.index, error: e}
+            assignments << entry
+            event_block&.call(entry.merge(type: :task_failed))
+          end
+        end
+
+        workers.each { |w| w.status = :done }
+        assignments
+      end
+
+      # Phase 3: Apply the aggregate block (or return raw assignments).
+      def finalize_result(assignments)
+        aggregator = self.class._aggregator
+        aggregator ? aggregator.call(assignments) : assignments
+      end
+
+      # Default scheduler: assign to the worker with the fewest accumulated
+      # messages (promotes round-robin-like distribution across the pool).
+      def default_scheduler(available_workers)
+        available_workers.min_by { |w| w.messages.size }
+      end
+
+      # Build an anonymous coordinator Agent::Base with the two built-in tools.
+      def build_coordinator_agent(task_queue)
+        coordinator_model_val = self.class._coordinator_model
+        coordinator_instructions_val = self.class._coordinator_instructions
+        coordinator_provider_val = self.class._coordinator_provider
+        enqueue_tool = build_enqueue_tool(task_queue)
+        finalize_tool = build_finalize_tool(task_queue)
+
+        coordinator_class = Class.new(Phronomy::Agent::Base) do
+          model coordinator_model_val
+          provider coordinator_provider_val if coordinator_provider_val
+          instructions coordinator_instructions_val
+          tools enqueue_tool, finalize_tool
+        end
+
+        coordinator_class.new
+      end
+
+      # Builds the +enqueue_task+ tool. Each call appends a task Hash to task_queue.
+      def build_enqueue_tool(task_queue)
+        Class.new(Phronomy::Tool::Base) do
+          tool_name "enqueue_task"
+          description "Add a task to the worker queue."
+          param :description, type: :string, desc: "What the worker agent should do"
+          param :metadata, type: :string, desc: "Optional metadata", required: false
+
+          define_method(:execute) do |description:, metadata: nil|
+            task = {id: task_queue.size + 1, description: description, metadata: metadata, enqueued_at: Time.now}
+            task_queue << task
+            "Task ##{task[:id]} enqueued: #{description}"
+          end
+        end
+      end
+
+      # Builds the +finalize+ tool. Signals to the coordinator LLM that all tasks
+      # have been enqueued; returns a confirmation string.
+      def build_finalize_tool(task_queue)
+        Class.new(Phronomy::Tool::Base) do
+          tool_name "finalize"
+          description "Signal that task generation is complete. Call this after all tasks have been enqueued."
+          param :summary, type: :string, desc: "Brief summary of what was enqueued", required: false
+
+          define_method(:execute) do |summary: ""|
+            "Finalized. #{task_queue.size} task(s) enqueued. #{summary}".strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/{trust_pipeline.rb → generator_verifier.rb}

@@ -1,40 +1,53 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Orchestrates three trust mechanisms in a single pipeline:
+  # Implements the Generator-Verifier multi-agent coordination pattern
+  # (Anthropic blog, Pattern 1): a generator agent produces an
+  # answer while a verifier agent evaluates its quality.
   #
-  # 1. **Citation Tracking** — the DraftAgent is prompted to list the knowledge
-  #    sources it relied on. Citations are extracted and attached to the result.
+  # @see https://claude.com/blog/multi-agent-coordination-patterns
   #
-  # 2. **Self-Review Loop** — a dedicated ReviewAgent evaluates each draft,
-  #    assigns a quality score, and provides actionable feedback. Rejected drafts
-  #    are retried with the reviewer's feedback embedded in the next prompt.
+  # All prompt construction and result parsing are provided by the caller,
+  # giving full control over the LLM dialogue.
+  # The generator and verifier agents are configurable, and the pipeline
+  # retries until confidence passes the threshold or max iterations are reached.
   #
-  # 3. **Confidence Gate** — a combined confidence score (the minimum of the
-  #    DraftAgent's self-reported confidence and the ReviewAgent's score) is
-  #    compared against a threshold. The pipeline finishes early when the gate
-  #    passes; after +max_iterations+ cycles it finishes regardless and marks
-  #    the result as untrusted when the threshold was not reached.
-  #
-  # @example
-  #   pipeline = Phronomy::TrustPipeline.new(
-  #     draft_agent:          PolicyDraftAgent,
-  #     review_agent:         PolicyReviewAgent,
-  #     confidence_threshold: 0.7,
-  #     max_iterations:       3
+  # @example Basic usage with custom prompt builders
+  #   pipeline = Phronomy::GeneratorVerifier.new(
+  #     draft_agent:           MyDraftAgent,
+  #     review_agent:          MyReviewAgent,
+  #     draft_prompt_builder:  ->(input, feedback) { "Question: #{input}" },
+  #     review_prompt_builder: ->(input, draft, citations) { "Review: #{draft}" }
   #   )
   #   result = pipeline.invoke("What is the refund policy?")
   #   puts result.output      # the final answer string
   #   puts result.trusted?    # true when confidence >= threshold
-  #   result.citations.each { |c| puts "#{c[:source]}: #{c[:excerpt]}" }
-  class TrustPipeline
+  #
+  # @example Custom result parsers
+  #   pipeline = Phronomy::GeneratorVerifier.new(
+  #     ...,
+  #     draft_result_parser:  ->(text) { my_parse_draft(text) },
+  #     review_result_parser: ->(text) { my_parse_review(text) }
+  #   )
+  #
+  # @example Raising on low confidence
+  #   pipeline = Phronomy::GeneratorVerifier.new(
+  #     ...,
+  #     raise_if_untrusted: true
+  #   )
+  #   begin
+  #     result = pipeline.invoke("question")
+  #   rescue Phronomy::LowConfidenceError => e
+  #     puts "Untrusted: #{e.result.confidence}"
+  #   end
+  class GeneratorVerifier
     # Default confidence threshold for trusting an answer.
     DEFAULT_CONFIDENCE_THRESHOLD = 0.7
 
     # Default maximum draft-review cycles before returning best effort.
     DEFAULT_MAX_ITERATIONS = 3
 
-    # Immutable value object returned by {TrustPipeline#invoke}.
+    # Immutable value object returned by {GeneratorVerifier#invoke}.
     #
     # @!attribute [r] output
     #   @return [String] the final answer text
@@ -43,17 +56,19 @@ module Phronomy
     # @!attribute [r] citations
     #   @return [Array<Hash>] [{source:, excerpt:}, ...]
     #
-    #   **WARNING**: These citations are extracted from the LLM's own response via
-    #   the ReviewAgent and are **not** verified against any external knowledge base,
-    #   document store, or URL.  Do not treat them as authoritative without
-    #   independent verification.
+    #   **WARNING**: These citations are extracted from the LLM's own response
+    #   and are **not** verified against any external knowledge base or URL.
+    #   Do not treat them as authoritative without independent verification.
     # @!attribute [r] iterations
     #   @return [Integer] number of draft-review cycles executed
     # @!attribute [r] review_notes
     #   @return [Array<String>] reviewer feedback for each cycle
     # @!attribute [r] trusted
     #   @return [Boolean] true when confidence >= threshold
-    Result = Struct.new(:output, :confidence, :citations, :iterations, :review_notes, :trusted, keyword_init: true) do
+    Result = Struct.new(
+      :output, :confidence, :citations, :iterations, :review_notes, :trusted,
+      keyword_init: true
+    ) do
       # @return [Boolean] true when confidence >= threshold
       alias_method :trusted?, :trusted
     end
@@ -76,44 +91,73 @@ module Phronomy
 
     private_constant :PipelineState
 
-    # @param draft_agent          [Class]   subclass of Phronomy::Agent::Base
-    # @param review_agent         [Class]   subclass of Phronomy::Agent::Base
-    # @param confidence_threshold [Float]   answers below this are retried (default: 0.7)
-    # @param max_iterations       [Integer] maximum draft-review cycles (default: 3)
-    # @param input_delimiter      [Array<String>, nil] optional two-element array
-    #   [start_tag, end_tag] used to wrap user input in prompts, e.g.
-    #   ["<user_input>", "</user_input>"] or
-    #   ["=== user input start ===", "=== user input end ==="].
-    #   When nil (default), input is embedded as-is for backward compatibility.
-    def initialize(draft_agent:, review_agent:,
+    # @param draft_agent           [Class]   subclass of Phronomy::Agent::Base
+    #   used to generate answer drafts
+    # @param review_agent          [Class]   subclass of Phronomy::Agent::Base
+    #   used to evaluate each draft
+    # @param draft_prompt_builder  [#call]   +call(input, feedback)+ → String
+    #   prompt for the generator. +feedback+ is nil on the first iteration and
+    #   contains the reviewer's feedback string on subsequent iterations.
+    # @param review_prompt_builder [#call]   +call(input, draft, citations)+ → String
+    #   prompt for the verifier. +citations+ is an Array of Hashes.
+    # @param draft_result_parser   [#call, nil]  +call(text)+ → Hash with
+    #   +:answer+, +:confidence+, and +:citations+ keys. Defaults to JSON parsing
+    #   with a safe fallback when the response cannot be parsed.
+    # @param review_result_parser  [#call, nil]  +call(text)+ → Hash with
+    #   +:approved+, +:score+, and +:feedback+ keys. Defaults to JSON parsing
+    #   with a safe fallback.
+    # @param confidence_threshold  [Float]   minimum combined confidence to
+    #   trust an answer (default: 0.7)
+    # @param max_iterations        [Integer] maximum draft-review cycles
+    #   before returning the best-effort answer (default: 3)
+    # @param raise_if_untrusted    [Boolean] when +true+, raises
+    #   {Phronomy::LowConfidenceError} if the final result does not meet the
+    #   confidence threshold (default: false)
+    def initialize(
+      draft_agent:,
+      review_agent:,
+      draft_prompt_builder:,
+      review_prompt_builder:,
+      draft_result_parser: nil,
+      review_result_parser: nil,
       confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
       max_iterations: DEFAULT_MAX_ITERATIONS,
-      input_delimiter: nil)
+      raise_if_untrusted: false
+    )
       @draft_agent_class = draft_agent
       @review_agent_class = review_agent
+      @draft_prompt_builder = draft_prompt_builder
+      @review_prompt_builder = review_prompt_builder
+      @draft_result_parser = draft_result_parser || method(:default_parse_draft)
+      @review_result_parser = review_result_parser || method(:default_parse_review)
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
-      @input_delimiter = input_delimiter
+      @raise_if_untrusted = raise_if_untrusted
       @compiled_graph = nil
     end
 
-    # Run the pipeline.
+    # Run the generator-verifier pipeline.
     #
     # @param input  [String] the user question or task description
     # @param config [Hash]   forwarded to the underlying agents (e.g. thread_id)
     # @return [Result]
+    # @raise [Phronomy::LowConfidenceError] when +raise_if_untrusted:+ is +true+
+    #   and the result does not meet the confidence threshold
     def invoke(input, config: {})
       app = compiled_graph
       state = app.invoke({input: input}, config: config)
       confidence = combined_confidence(state)
-      Result.new(
+      trusted = confidence >= @threshold
+      result = Result.new(
         output: state.output || state.draft.to_s,
         confidence: confidence,
         citations: state.citations,
         iterations: state.iteration,
         review_notes: state.review_notes,
-        trusted: confidence >= @threshold
+        trusted: trusted
       )
+      raise LowConfidenceError.new(result) if @raise_if_untrusted && !trusted
+      result
     end
 
     private
@@ -122,7 +166,6 @@ module Phronomy
       [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
     end
 
-    # Returns the compiled workflow, building and caching it on first call.
     def compiled_graph
       @compiled_graph ||= build_workflow
     end
@@ -132,6 +175,10 @@ module Phronomy
       review_agent = @review_agent_class.new
       threshold = @threshold
       max_iter = @max_iterations
+      dpb = @draft_prompt_builder
+      rpb = @review_prompt_builder
+      drp = @draft_result_parser
+      rrp = @review_result_parser
       pipeline = self
 
       Phronomy::Workflow.define(PipelineState) do
@@ -139,9 +186,9 @@ module Phronomy
 
         state :draft, action: ->(state) {
           feedback = state.review_notes.last
-          prompt = pipeline.__send__(:draft_prompt, state.input, feedback)
+          prompt = dpb.call(state.input, feedback)
           result = draft_agent.invoke(prompt)
-          parsed = pipeline.__send__(:safe_parse_draft, result[:output])
+          parsed = drp.call(result[:output])
           state.merge(
             draft: parsed[:answer].to_s,
             self_score: pipeline.__send__(:clamp, parsed[:confidence]),
@@ -151,9 +198,9 @@ module Phronomy
         }
 
         state :review, action: ->(state) {
-          prompt = pipeline.__send__(:review_prompt, state.input, state.draft, state.citations)
+          prompt = rpb.call(state.input, state.draft, state.citations)
           result = review_agent.invoke(prompt)
-          parsed = pipeline.__send__(:safe_parse_review, result[:output])
+          parsed = rrp.call(result[:output])
           state.merge(
             review_score: pipeline.__send__(:clamp, parsed[:score]),
             approved: parsed[:approved] == true,
@@ -176,73 +223,13 @@ module Phronomy
       end
     end
 
-    # Wraps +input+ with the configured delimiter pair when +input_delimiter+ is set.
-    # When no delimiter is configured the input is returned unchanged.
-    def wrap_input(input)
-      return input unless @input_delimiter
-
-      start_tag, end_tag = @input_delimiter
-      "#{start_tag}\n#{input}\n#{end_tag}"
-    end
-
-    # Builds the prompt sent to the DraftAgent for each iteration.
-    def draft_prompt(input, feedback)
-      lines = [
-        "Answer the following question as accurately as possible.",
-        "Use any knowledge provided in <context> tags and cite your sources."
-      ]
-      if feedback && !feedback.strip.empty?
-        lines << ""
-        lines << "Your previous draft was reviewed and rejected. Address ALL of this feedback:"
-        lines << feedback.strip
-      end
-      lines += [
-        "",
-        "Question: #{wrap_input(input)}",
-        "",
-        "RESPOND ONLY WITH VALID JSON (no text outside the JSON block):",
-        '{"answer":"<full answer>","confidence":<0.0-1.0>,' \
-          '"citations":[{"source":"<doc name>","excerpt":"<exact quote>"}]}'
-      ]
-      lines.join("\n")
-    end
-
-    # Builds the prompt sent to the ReviewAgent.
-    def review_prompt(input, draft, citations)
-      citation_text = if citations.empty?
-        "  (none)"
-      else
-        citations.map { |c| "  - #{c[:source]}: \"#{c[:excerpt]}\"" }.join("\n")
-      end
-      [
-        "You are a rigorous quality reviewer. Evaluate the draft answer below.",
-        "",
-        "Question: #{wrap_input(input)}",
-        "",
-        "Draft answer:",
-        draft.to_s,
-        "",
-        "Citations provided:",
-        citation_text,
-        "",
-        "Evaluation criteria:",
-        "  1. Is the answer factually accurate and complete?",
-        "  2. Is every significant claim backed by a citation?",
-        "  3. Is the self-reported confidence realistic?",
-        "",
-        "RESPOND ONLY WITH VALID JSON (no text outside the JSON block):",
-        '{"approved":<true|false>,"score":<0.0-1.0>,' \
-          '"feedback":"<specific actionable feedback, or empty string if approved>"}'
-      ].join("\n")
-    end
-
-    def safe_parse_draft(text)
+    def default_parse_draft(text)
       json_parser.parse(text)
     rescue Phronomy::ParseError
       {answer: text.to_s, confidence: 0.0, citations: []}
     end
 
-    def safe_parse_review(text)
+    def default_parse_review(text)
       json_parser.parse(text)
     rescue Phronomy::ParseError
       {approved: false, score: 0.0, feedback: "Review output could not be parsed: #{text}"}

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end