phronomy 0.16.0 → 0.17.0

data/lib/phronomy/agent/shared_state.rb

@@ -2,79 +2,24 @@
 
 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
+    # Implements peer coordination through a shared KnowledgeStore.
     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>]
         # @api public
         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]
         # @api public
         def write(agent:, content:, cycle:)
           @findings << {agent: agent, content: content, cycle: cycle}
           nil
         end
 
-        # Returns the number of findings recorded so far.
-        # @return [Integer]
         # @api public
         def size
           @findings.size
@@ -82,96 +27,45 @@ module Phronomy
       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
         # @api public
         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
-        # @api public
-        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
         # @api public
         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]
         # @api public
         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]
         # @api public
         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
         # @api public
         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+
         # @api public
         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
       # @api public
       def invoke(input, config: {})
         validate_termination!
@@ -181,12 +75,17 @@ module Phronomy
         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])
+            invoke_researcher(
+              member_config[:klass],
+              store,
+              cycle,
+              input,
+              member_config[:instruction]
+            )
           end
           completed_cycles = cycle
 
@@ -199,8 +98,6 @@ module Phronomy
             terminated_by = :timeout
             break
           end
-
-          terminated_by = :max_cycles
         end
 
         output = if self.class._aggregator
@@ -216,33 +113,37 @@ module Phronomy
 
       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)
+      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,
+        prompt = build_prompt(
+          original_input,
+          store,
+          cycle,
           extra_tools: extra_tools,
-          per_agent_instruction: per_agent_instruction)
+          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::Agent::Context::Capability::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."
+            "Call this to see what other researchers have discovered."
 
           define_method(:execute) { store.read_all.to_json }
         end
@@ -250,7 +151,7 @@ module Phronomy
         write_tool = Class.new(Phronomy::Agent::Context::Capability::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."
+            "that other researchers can build on your discovery."
           param :content, type: :string, desc: "The finding to record"
 
           define_method(:execute) do |content:|
@@ -259,16 +160,22 @@ module Phronomy
           end
         end
 
-        parent_tools = researcher_class.tools
-        Class.new(researcher_class) { tools(*parent_tools, read_tool, write_tool) }
+        definitions = researcher_class.tools.to_h do |tool_class|
+          [tool_class, researcher_class.tool_aliases[tool_class]]
+        end
+        definitions[read_tool] = nil
+        definitions[write_tool] = nil
+
+        Class.new(researcher_class) { tools(definitions) }
       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)
+      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]
@@ -281,20 +188,21 @@ module Phronomy
         return base if store.size == 0
 
         findings_text = store.read_all
-          .map { |f| "- [#{f[:agent]} / cycle #{f[:cycle]}] #{f[:content]}" }
+          .map { |finding|
+            "- [#{finding[:agent]} / cycle #{finding[:cycle]}] #{finding[: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"
+          tool_names = extra_tools.map do |tool|
+            tool.respond_to?(:tool_name) ? tool.tool_name : tool.name.to_s
+          end.join(", ")
+          "  You also have access to additional tools (#{tool_names}) — " \
+            "use them to gather information before writing findings.\n"
         else
           ""
         end

data/lib/phronomy/agent/token_budget_resolver.rb

@@ -43,9 +43,8 @@ module Phronomy
             "set max_output_tokens or Phronomy.configuration.default_output_reserve"
         end
 
-        # ContextAssembler passes the actual mandatory Manifest content to
-        # ContextSelector. Reserving context_overhead here would count system
-        # instructions and tool definitions a second time.
+        # Mandatory Manifest content is accounted separately by ContextAssembler
+        # and the final budget validator. TokenBudget reserves output capacity only.
         Phronomy::LlmContextWindow::TokenBudget.new(
           context_window: context_window,
           max_output_tokens: reserve
@@ -62,7 +61,9 @@ module Phronomy
       end
 
       def stringify_keys(hash)
-        hash.to_h.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+        hash.to_h.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value
+        end
       end
     end
   end