phronomy 0.3.0 → 0.5.0

data/lib/phronomy/agent/shared_state.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Implements the "Shared state" coordination pattern (Anthropic blog, Pattern 5).
+    #
+    # @see https://claude.com/blog/multi-agent-coordination-patterns
+    #
+    # Multiple peer agents collaborate through a shared {KnowledgeStore}.
+    # There is no central coordinator. Each agent reads the store, acts on what it
+    # finds, and writes new findings back. Later agents in a cycle immediately see
+    # findings written by earlier agents in the same cycle.
+    #
+    # Two tools are automatically injected into every member agent at runtime:
+    # - +read_store+    — returns all current findings as a JSON string
+    # - +write_finding+ — appends a Hash finding to the store
+    #
+    # Use +member+ to register agents and optionally provide per-agent coordination
+    # instructions. Use +coordination+ to define the team-level protocol that all
+    # members receive instead of the built-in default guide.
+    #
+    # @example Basic usage with per-agent instructions
+    #   class CodeReviewTeam < Phronomy::Agent::SharedState
+    #     member StructureAnalyst
+    #     member SecurityAuditor, instruction: "Focus on authentication and injection risks."
+    #     member QualityReviewer,  instruction: "Flag methods longer than 10 lines."
+    #     max_cycles  3
+    #     aggregate   { |store| { findings: store.read_all, total: store.size } }
+    #   end
+    #
+    #   result = CodeReviewTeam.new.invoke("Review the files in ./src")
+    #   # => { output: { findings: [...], total: N }, cycles: 3, terminated_by: :max_cycles }
+    #
+    # @example With custom team-level coordination protocol
+    #   class ResearchTeam < Phronomy::Agent::SharedState
+    #     coordination <<~TEXT
+    #       Shared store tools: read_store (no params), write_finding(content:).
+    #       Workflow: read first, then write one finding per insight.
+    #     TEXT
+    #     member LiteratureAgent
+    #     member IndustryAgent
+    #     max_cycles  10
+    #     terminate_when { |store| store.size >= 20 }
+    #   end
+    class SharedState
+      # Thread-safe (serialised by sequential execution) knowledge store shared
+      # across all researcher agents within a single {SharedState#invoke} call.
+      #
+      # Each finding is stored as a Hash with the keys:
+      #   :agent   — Symbol derived from the researcher class name
+      #   :content — String written by the researcher
+      #   :cycle   — Integer cycle number in which the finding was recorded
+      class KnowledgeStore
+        def initialize
+          @findings = []
+        end
+
+        # Returns a shallow copy of all findings in insertion order.
+        # @return [Array<Hash>]
+        def read_all
+          @findings.dup
+        end
+
+        # Appends a new finding to the store.
+        # @param agent   [Symbol]  researcher identifier
+        # @param content [String]  the finding text
+        # @param cycle   [Integer] the current cycle number
+        # @return [nil]
+        def write(agent:, content:, cycle:)
+          @findings << {agent: agent, content: content, cycle: cycle}
+          nil
+        end
+
+        # Returns the number of findings recorded so far.
+        # @return [Integer]
+        def size
+          @findings.size
+        end
+      end
+
+      class << self
+        # Registers a member agent class that will collaborate via the shared store.
+        # Members are invoked sequentially within each cycle in declaration order.
+        #
+        # @param klass [Class] an Agent::Base subclass
+        # @param instruction [String, nil] optional per-agent coordination instruction
+        #   appended to the team coordination text in this agent's prompt
+        def member(klass, instruction: nil)
+          @members ||= []
+          @members << {klass: klass, instruction: instruction}
+        end
+
+        # Backward-compatible alias. Registers each class as a member without a
+        # per-agent instruction. Prefer {.member} for new code.
+        #
+        # @param classes [Array<Class>] Agent::Base subclasses
+        def researchers(*classes)
+          classes.flatten.each { |klass| member(klass) }
+        end
+
+        # Defines the team-level coordination protocol text injected into every
+        # member's prompt. When omitted the built-in default guide is used, which
+        # explains +read_store+ / +write_finding+ usage and enforces the standard
+        # workflow. Override this when you need a different protocol or tone.
+        #
+        # @param text [String, nil] the coordination instructions
+        def coordination(text = nil)
+          text ? @coordination = text : @coordination
+        end
+
+        # Sets the maximum number of cycles to run.
+        # At least one of +max_cycles+ or +timeout+ must be configured.
+        #
+        # @param value [Integer, nil]
+        def max_cycles(value = nil)
+          value ? @max_cycles = Integer(value) : @max_cycles
+        end
+
+        # Sets the maximum wall-clock seconds for the entire invocation.
+        # At least one of +max_cycles+ or +timeout+ must be configured.
+        #
+        # @param value [Numeric, nil]
+        def timeout(value = nil)
+          value ? @timeout = value.to_f : @timeout
+        end
+
+        # Registers an optional convergence block. Evaluated after each completed
+        # cycle; when it returns +true+ the loop terminates early.
+        #
+        # @yield [KnowledgeStore] receives the store; return +true+ to stop
+        def terminate_when(&block)
+          block ? @terminate_when = block : @terminate_when
+        end
+
+        # Defines how the final store is converted into the +:output+ of the result.
+        # When omitted, +store.read_all+ is used as-is.
+        #
+        # @yield [KnowledgeStore] receives the final store; return value becomes +:output+
+        def aggregate(&block)
+          block ? @aggregator = block : @aggregator
+        end
+
+        # @!visibility private
+        def _members = Array(@members)
+        # @!visibility private — derives class list from _members for backward compat
+        def _researchers = _members.map { |m| m[:klass] }
+        # @!visibility private
+        def _coordination = @coordination
+        # @!visibility private
+        def _max_cycles = @max_cycles
+        # @!visibility private
+        def _timeout = @timeout
+        # @!visibility private
+        def _terminate_when = @terminate_when
+        # @!visibility private
+        def _aggregator = @aggregator
+      end
+
+      # Runs the shared-state coordination loop.
+      #
+      # @param input  [String] the seed question or task description
+      # @param config [Hash]   reserved for future use
+      # @return [Hash] +:output+, +:cycles+, +:terminated_by+
+      # @raise [ArgumentError] when neither +max_cycles+ nor +timeout+ is configured
+      def invoke(input, config: {})
+        validate_termination!
+
+        store = KnowledgeStore.new
+        max_cycles = self.class._max_cycles
+        deadline = self.class._timeout ? Time.now + self.class._timeout : nil
+        terminated_by = :max_cycles
+        completed_cycles = 0
+
+        cycle_limit = max_cycles || Float::INFINITY
+
+        (1..cycle_limit).each do |cycle|
+          self.class._members.each do |member_config|
+            invoke_researcher(member_config[:klass], store, cycle, input, member_config[:instruction])
+          end
+          completed_cycles = cycle
+
+          if self.class._terminate_when&.call(store)
+            terminated_by = :terminate_when
+            break
+          end
+
+          if deadline && Time.now >= deadline
+            terminated_by = :timeout
+            break
+          end
+
+          terminated_by = :max_cycles
+        end
+
+        output = if self.class._aggregator
+          self.class._aggregator.call(store)
+        else
+          store.read_all
+        end
+
+        {output: output, cycles: completed_cycles, terminated_by: terminated_by}
+      end
+
+      private
+
+      def validate_termination!
+        return if self.class._max_cycles || self.class._timeout
+        raise ArgumentError,
+          "max_cycles or timeout must be configured before invoking SharedState"
+      end
+
+      # Invokes a single member agent for one cycle.
+      # Builds an anonymous subclass with +read_store+ and +write_finding+ injected,
+      # then calls +invoke+ with a prompt that includes the coordination guide,
+      # any per-agent instruction, and the current store contents.
+      def invoke_researcher(researcher_class, store, cycle, original_input, per_agent_instruction = nil)
+        instrumented = build_instrumented_researcher(researcher_class, store, cycle)
+        extra_tools = researcher_class.tools
+        prompt = build_prompt(original_input, store, cycle,
+          extra_tools: extra_tools,
+          per_agent_instruction: per_agent_instruction)
+        instrumented.new.invoke(prompt)
+      end
+
+      # Builds an anonymous subclass of +researcher_class+ with two store tools
+      # injected. The tools close over the +store+ instance so that writes and
+      # reads are reflected in the live store.
+      def build_instrumented_researcher(researcher_class, store, cycle)
+        agent_key = researcher_class.name&.to_sym || researcher_class.object_id.to_s.to_sym
+
+        read_tool = Class.new(Phronomy::Tool::Base) do
+          tool_name "read_store"
+          description "Read all current findings from the shared knowledge store. " \
+                      "Call this to see what other researchers have discovered."
+
+          define_method(:execute) { store.read_all.to_json }
+        end
+
+        write_tool = Class.new(Phronomy::Tool::Base) do
+          tool_name "write_finding"
+          description "Record a new finding into the shared knowledge store so " \
+                      "that other researchers can build on your discovery."
+          param :content, type: :string, desc: "The finding to record"
+
+          define_method(:execute) do |content:|
+            store.write(agent: agent_key, content: content, cycle: cycle)
+            "Finding recorded."
+          end
+        end
+
+        parent_tools = researcher_class.tools
+        Class.new(researcher_class) { tools(*parent_tools, read_tool, write_tool) }
+      end
+
+      # Builds the invocation prompt for a member agent.
+      # Uses the team-level coordination text when defined via {.coordination},
+      # otherwise falls back to the built-in default guide. Appends any per-agent
+      # instruction after the coordination text. Subsequent cycles also include
+      # the current store contents so agents can build on prior findings.
+      def build_prompt(original_input, store, cycle, extra_tools: [], per_agent_instruction: nil)
+        guide = self.class._coordination || default_coordination_guide(extra_tools)
+
+        prompt_parts = [guide]
+        if per_agent_instruction
+          prompt_parts << "\nYour specific focus for this session: #{per_agent_instruction}"
+        end
+        header = prompt_parts.join
+
+        base = "#{header}\n\nTask: #{original_input}"
+        return base if store.size == 0
+
+        findings_text = store.read_all
+          .map { |f| "- [#{f[:agent]} / cycle #{f[:cycle]}] #{f[:content]}" }
+          .join("\n")
+
+        "#{header}\n\nTask: #{original_input}\n\nFindings so far:\n#{findings_text}"
+      end
+
+      # Builds the default tool-usage guide for member agents.
+      # Describes +read_store+ / +write_finding+ and the required workflow.
+      # When extra_tools are present, lists their names so the agent knows
+      # what additional tools are available.
+      def default_coordination_guide(extra_tools)
+        extra_line = if extra_tools.any?
+          tool_names = extra_tools.map { |t| t.respond_to?(:tool_name) ? t.tool_name : t.name.to_s }.join(", ")
+          "  You also have access to additional tools (#{tool_names}) — use them to gather information before writing findings.\n"
+        else
+          ""
+        end
+
+        <<~TEXT.chomp
+          You have access to a shared knowledge store via two tools:
+            read_store     — returns all current findings as JSON (no parameters)
+            write_finding  — records one finding to the store (param: content)
+          #{extra_line}Required workflow: first call read_store, then call write_finding once per insight.
+          Each call to write_finding must contain exactly one unique insight — do not call it twice with the same content.
+          If you have no new insights to contribute, call write_finding exactly once with: "No new findings in this cycle."
+          Do not output plain text — every insight must be submitted via write_finding.
+        TEXT
+      end
+    end
+  end
+end

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 as a top-level +messages:+ argument 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 as the top-level +messages:+ argument..
+      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], 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