phronomy 0.3.0 → 0.5.0

data/lib/phronomy/agent/concerns/before_completion.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Concerns
+      # Adds before_completion hook support to an agent.
+      #
+      # Included in {Phronomy::Agent::Base}. Hooks are executed just before every
+      # LLM call (global → class → instance order) and may inject or override
+      # LLM parameters such as temperature or model.
+      module BeforeCompletion
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class-level DSL methods mixed into the including agent class.
+        module ClassMethods
+          # Sets or reads the class-level before_completion hook.
+          # The hook is called before every LLM request for instances of this class.
+          # Receives a {Phronomy::Agent::BeforeCompletionContext}; must return a Hash
+          # of params to merge into the LLM call, or nil to pass through unchanged.
+          #
+          # @param callable [#call, nil] lambda/proc to register, or nil to clear
+          # @return [#call, nil]
+          # @example
+          #   class MyAgent < Phronomy::Agent::Base
+          #     before_completion ->(ctx) { { temperature: 0.2 } }
+          #   end
+          def before_completion(callable = nil)
+            if callable.nil? && !block_given?
+              @before_completion
+            else
+              @before_completion = callable
+            end
+          end
+
+          # @return [#call, nil]
+          def _before_completion
+            @before_completion
+          end
+        end
+
+        # Instance-level before_completion hook. When set, takes precedence over
+        # the class-level hook for this specific agent instance only.
+        # @return [#call, nil]
+        attr_accessor :before_completion
+
+        private
+
+        # Collects and runs all registered before_completion hooks in order
+        # (global → class → instance) and applies the merged params to the chat.
+        #
+        # @param chat   [RubyLLM::Chat] the assembled chat object
+        # @param config [Hash] the invocation config hash
+        # @return [Hash] the merged params applied to the chat
+        def run_before_completion_hooks!(chat, config)
+          hooks = [
+            Phronomy.configuration.before_completion,
+            self.class._before_completion,
+            @before_completion
+          ].compact
+
+          return {} if hooks.empty?
+
+          ctx = BeforeCompletionContext.new(
+            agent: self,
+            messages: chat.messages,
+            config: config,
+            params: {}
+          )
+
+          merged = {}
+          hooks.each do |hook|
+            result = hook.call(ctx)
+            merged.merge!(result) if result.is_a?(Hash)
+          end
+
+          apply_before_completion_params!(chat, merged)
+          merged
+        end
+
+        # Applies a merged param hash returned by before_completion hooks to
+        # the chat object using the appropriate RubyLLM::Chat API methods.
+        # When overriding the model, reuses the agent's configured provider and
+        # assume_exists setting so that local/namespaced models continue to work.
+        #
+        # @param chat   [RubyLLM::Chat]
+        # @param params [Hash]
+        def apply_before_completion_params!(chat, params)
+          params.each do |key, value|
+            case key
+            when :model
+              prov = self.class.provider
+              chat.with_model(value, provider: prov, assume_exists: !prov.nil?)
+            when :temperature
+              chat.with_temperature(value)
+            else
+              chat.with_params(key => value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/concerns/guardrailable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Concerns
+      # Adds input and output guardrail support to an agent.
+      #
+      # Included in {Phronomy::Agent::Base}. Guardrails are run on the raw
+      # input string before the LLM is called, and on the raw output string
+      # before the result is returned to the caller.
+      module Guardrailable
+        # Attach a guardrail that validates input before every #invoke call.
+        # @param guardrail [Phronomy::Guardrail::InputGuardrail]
+        # @return [self]
+        def add_input_guardrail(guardrail)
+          @input_guardrails ||= []
+          @input_guardrails << guardrail
+          self
+        end
+
+        # Attach a guardrail that validates output before it is returned.
+        # @param guardrail [Phronomy::Guardrail::OutputGuardrail]
+        # @return [self]
+        def add_output_guardrail(guardrail)
+          @output_guardrails ||= []
+          @output_guardrails << guardrail
+          self
+        end
+
+        private
+
+        def run_input_guardrails!(input)
+          (@input_guardrails || []).each { |g| g.run!(input) }
+        end
+
+        def run_output_guardrails!(output)
+          (@output_guardrails || []).each { |g| g.run!(output) }
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/concerns/retryable.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Concerns
+      # Adds configurable retry behaviour to an agent.
+      #
+      # Included in {Phronomy::Agent::Base}. The retry loop wraps the full
+      # #invoke_once call; {Phronomy::GuardrailError} is never retried.
+      module Retryable
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class-level DSL methods mixed into the including agent class.
+        module ClassMethods
+          # Configures a retry policy that wraps the full #invoke call.
+          # GuardrailError is never retried regardless of this setting.
+          #
+          # @param times [Integer] maximum retry attempts (default: 0)
+          # @param wait  [Symbol, Numeric] :exponential, :linear, or a fixed Float
+          # @param base  [Float]  base wait time in seconds (default: 1.0)
+          #
+          # @example
+          #   class MyAgent < Phronomy::Agent::Base
+          #     retry_policy times: 2, wait: :exponential, base: 1.0
+          #   end
+          def retry_policy(times: 0, wait: 0, base: 1.0)
+            @_retry_policy = {times: times, wait: wait, base: base}
+          end
+
+          # Returns the configured retry policy, or nil when none is set.
+          # @return [Hash, nil]
+          attr_reader :_retry_policy
+
+          # Injectable sleep callable for testing (shared with Tool::Base pattern).
+          # @return [#call]
+          def _sleep_proc
+            @_sleep_proc || method(:sleep)
+          end
+
+          # Overrides the sleep callable used between retries.
+          # @param proc [#call]
+          attr_writer :_sleep_proc
+        end
+
+        private
+
+        # Retry loop for #invoke. Separated so that ReactAgent can override #invoke_once.
+        def _invoke_impl(input, messages: [], thread_id: nil, config: {})
+          policy = self.class._retry_policy
+          attempt = 0
+          begin
+            invoke_once(input, messages: messages, thread_id: thread_id, config: config)
+          rescue Phronomy::GuardrailError
+            raise
+          rescue
+            if policy && attempt < policy[:times]
+              wait = compute_agent_retry_wait(policy[:wait], policy[:base], attempt)
+              self.class._sleep_proc.call(wait) if wait > 0
+              attempt += 1
+              retry
+            end
+            raise
+          end
+        end
+
+        # Computes the agent-level retry wait duration.
+        # @param strategy [Symbol, Numeric]
+        # @param base     [Float]
+        # @param attempt  [Integer]
+        # @return [Float]
+        def compute_agent_retry_wait(strategy, base, attempt)
+          case strategy
+          when :exponential
+            (2**attempt) * base
+          when :linear
+            (attempt + 1) * base
+          when Numeric
+            strategy.to_f
+          else
+            base.to_f
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/concerns/suspendable.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Concerns
+      # Adds suspend/resume and tool-approval support to an agent.
+      #
+      # Included in {Phronomy::Agent::Base}. When a tool decorated with
+      # +requires_approval true+ is called and no synchronous approval handler
+      # has been registered, the invocation is suspended and a
+      # {Phronomy::Agent::Checkpoint} is returned so the caller can resume later.
+      module Suspendable
+        # Registers a callback that is invoked before executing any tool that has
+        # +requires_approval true+ set. The block receives the tool name (String)
+        # and the arguments Hash, and must return a truthy value to allow execution.
+        # Returning a falsy value causes the tool to return a denial message instead
+        # of executing.
+        #
+        # When no handler is registered and a tool with +requires_approval+ is
+        # called, #invoke returns a suspended result hash containing a
+        # {Phronomy::Agent::Checkpoint}. Call #resume to continue execution after
+        # obtaining an approval decision from the user or an external system.
+        #
+        # @example Synchronous handler
+        #   agent = MyAgent.new
+        #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
+        # @return [self]
+        def on_approval_required(&block)
+          @approval_handler = block
+          self
+        end
+
+        # Resumes a previously suspended invocation from a {Phronomy::Agent::Checkpoint}.
+        #
+        # This method reconstructs the conversation state captured at suspension
+        # time, injects the tool result (executed or denied), and continues the
+        # LLM loop until it produces a final answer.
+        #
+        # @param checkpoint [Phronomy::Agent::Checkpoint] the checkpoint returned by
+        #   the suspended #invoke call
+        # @param approved   [Boolean] +true+ to execute the pending tool; +false+
+        #   to inject a denial message and let the LLM handle it gracefully
+        # @param config     [Hash] same runtime options as #invoke
+        # @return [Hash] +{ output: String, suspended: false, messages: Array, usage: Phronomy::TokenUsage }+
+        # @raise [Phronomy::GuardrailError] when an output guardrail rejects the value
+        def resume(checkpoint, approved:, config: {})
+          # Build a fresh chat with all tools registered.
+          chat = build_chat
+
+          # Re-apply system instructions so the LLM has the same persona/context
+          # as the original invocation. build_cached_system_text is memoised, so
+          # a Proc- or PromptTemplate-based instructions block is re-evaluated
+          # against the original input rather than using a stale cached value.
+          system_text = build_cached_system_text(checkpoint.original_input)
+          apply_instructions(chat, system_text) if system_text
+
+          # Restore the full conversation (history + user + assistant with tool call).
+          checkpoint.messages.each { |msg| chat.messages << msg }
+
+          # Determine the tool result: execute it or inject a denial string.
+          tool_result =
+            if approved
+              tool_instance = chat.tools[checkpoint.pending_tool_name.to_sym]
+              tool_instance ? tool_instance.call(checkpoint.pending_tool_args) : "Tool not found."
+            else
+              "Tool execution denied."
+            end
+
+          # Inject the tool result so the LLM can continue.
+          chat.add_message(
+            role: :tool,
+            content: tool_result.to_s,
+            tool_call_id: checkpoint.pending_tool_call_id
+          )
+
+          # Continue the React loop.
+          response = chat.complete
+
+          output = response.content
+          usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+
+          run_output_guardrails!(output)
+
+          {output: output, suspended: false, messages: chat.messages, usage: usage}
+        end
+
+        private
+
+        # Registers an on_tool_call hook on the chat object that raises SuspendSignal
+        # when an approval-required tool is about to be executed and no synchronous
+        # on_approval_required handler has been registered.
+        #
+        # Does nothing when:
+        #   - a synchronous handler is already registered (@approval_handler is set), or
+        #   - none of the agent's tools have requires_approval set.
+        #
+        # @param chat [RubyLLM::Chat]
+        def _register_suspension_hook!(chat)
+          return if @approval_handler
+          return if self.class.tools.none? { |tc| tc.requires_approval }
+
+          chat.on_tool_call do |tool_call|
+            tool_instance = chat.tools[tool_call.name.to_sym]
+            if tool_instance&.requires_approval
+              raise SuspendSignal.new(
+                tool_name: tool_call.name,
+                args: tool_call.arguments,
+                tool_call_id: tool_call.id
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/orchestrator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Base class for orchestrator agents that coordinate multiple subagents.
+    # Implements the Orchestrator-Subagent multi-agent coordination pattern
+    # (Anthropic blog, Pattern 2).
+    #
+    # @see https://claude.com/blog/multi-agent-coordination-patterns
+    #
+    # Extends {Phronomy::Agent::Base} with:
+    # - A +subagent+ class-level DSL for declarative subagent registration. Each
+    #   declared subagent is automatically exposed as an LLM-callable tool.
+    # - +dispatch_parallel+ for programmatic parallel invocation of heterogeneous
+    #   agents.
+    # - +fan_out+ for parallel invocation of the same agent across multiple inputs.
+    #
+    # @example Declarative DSL
+    #   class ResearchOrchestrator < Phronomy::Agent::Orchestrator
+    #     model "gpt-4o"
+    #     instructions "You coordinate research tasks."
+    #     subagent :searcher,   SearchAgent
+    #     subagent :summarizer, SummaryAgent
+    #   end
+    #
+    #   result = ResearchOrchestrator.new.invoke("Research the latest AI news.")
+    #
+    # @example Programmatic parallel dispatch
+    #   class MyOrchestrator < Phronomy::Agent::Orchestrator
+    #     model "gpt-4o"
+    #     instructions "Dispatch tasks in parallel."
+    #
+    #     def run(input)
+    #       results = dispatch_parallel(
+    #         { agent: SearchAgent,   input: "topic A" },
+    #         { agent: AnalysisAgent, input: input }
+    #       )
+    #       results.map { |r| r[:output] }.join("\n")
+    #     end
+    #   end
+    #
+    # @example Fan-out (same agent, multiple inputs)
+    #   results = fan_out(agent: TranslationAgent, inputs: ["Hello", "World"])
+    class Orchestrator < Base
+      # Declares a named subagent and registers it as a tool accessible to the
+      # LLM during an +invoke+ call.
+      #
+      # Each call appends a new tool to this class's tool list.  The generated
+      # tool's function name is +dispatch_to_<name>+.  When the LLM calls the
+      # tool, a fresh instance of +agent_class+ is created and +invoke+ is called
+      # with the provided input string.
+      #
+      # @param name        [Symbol] logical name that identifies the subagent
+      # @param agent_class [Class]  subclass of {Phronomy::Agent::Base}
+      # @param on_error    [Symbol] +:raise+ (default) re-raises any exception
+      #   from the subagent; +:skip+ returns +nil+ so the LLM can decide how to
+      #   proceed
+      def self.subagent(name, agent_class, on_error: :raise)
+        tool_class = Class.new(Phronomy::Tool::Base) do
+          tool_name "dispatch_to_#{name}"
+          description "Dispatch work to the #{name} subagent (#{agent_class.name})"
+          param :input, type: :string, desc: "The task or question for the subagent"
+
+          define_method(:execute) do |input:|
+            result = agent_class.new.invoke(input)
+            result[:output]
+          rescue
+            raise if on_error == :raise
+            nil
+          end
+        end
+
+        # Append without clobbering previously registered tools or aliases.
+        @tools = (@tools || []) + [tool_class]
+        @tool_aliases ||= {}
+
+        registered_subagents[name] = {agent_class: agent_class, on_error: on_error}
+      end
+
+      # Returns the subagent registry for this specific class (not inherited).
+      #
+      # @return [Hash{Symbol => Hash}]
+      def self.registered_subagents
+        @registered_subagents ||= {}
+      end
+
+      # Dispatches multiple heterogeneous agent tasks in parallel using Ruby
+      # threads. Each task is a Hash describing one agent invocation.
+      #
+      # Results are returned in the same order as the input +tasks+ array.
+      # If any thread raises an exception, the exception is re-raised in the
+      # calling thread after all threads have completed (via +Thread#value+).
+      #
+      # @param tasks [Array<Hash>]
+      # @option task [Class]  :agent  agent class to invoke (required)
+      # @option task [String] :input  input string for the agent (required)
+      # @option task [Hash]   :config forwarded to +agent#invoke+ (default: +{}+)
+      # @return [Array<Hash>] agent results in the same order as +tasks+
+      def dispatch_parallel(*tasks)
+        threads = tasks.map do |task|
+          Thread.new do
+            task[:agent].new.invoke(task[:input], config: task.fetch(:config, {}))
+          end
+        end
+        threads.map(&:value)
+      end
+
+      # Runs the same agent against multiple inputs in parallel (fan-out pattern).
+      #
+      # @param agent  [Class]         agent class to invoke for every input
+      # @param inputs [Array<String>] list of input strings
+      # @param config [Hash]          forwarded to every +agent#invoke+ call
+      # @return [Array<Hash>] results in the same order as +inputs+
+      def fan_out(agent:, inputs:, config: {})
+        dispatch_parallel(*inputs.map { |input| {agent: agent, input: input, config: config} })
+      end
+    end
+  end
+end

data/lib/phronomy/agent/react_agent.rb

@@ -9,7 +9,7 @@ module Phronomy
 
       # Performs a single (non-retried) ReAct invocation.
       # Overrides Base#invoke_once so that Base#invoke's retry loop is inherited.
-      def invoke_once(input, config: {})
+      def invoke_once(input, messages: [], thread_id: nil, config: {})
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
@@ -18,17 +18,16 @@ module Phronomy
           # Run input guardrails before any LLM interaction.
           run_input_guardrails!(input)
 
-          config[:thread_id]
           max_iter = self.class.max_iterations
 
           # Seed with app-managed conversation history when provided.
-          messages = Array(config[:messages]).dup
+          messages = Array(messages).dup
           user_asked = false
           total_usage = Phronomy::TokenUsage.zero
           iterations_exhausted = true
 
           max_iter.times do
-            response = step(messages, input, user_asked: user_asked, config: config)
+            response = step(messages, input, user_asked: user_asked, thread_id: thread_id, config: config)
             user_asked = true
             messages = response[:messages]
             total_usage += response[:usage]
@@ -55,12 +54,14 @@ module Phronomy
       # Streaming version of #invoke for the ReAct loop.
       # Yields {Phronomy::Agent::StreamEvent} events while the LLM-tool loop runs.
       #
-      # @param input  [String, Hash]
-      # @param config [Hash]
+      # @param input     [String, Hash]
+      # @param messages  [Array<RubyLLM::Message>] same as #invoke
+      # @param thread_id [String, nil]              same as #invoke
+      # @param config    [Hash]
       # @yield [Phronomy::Agent::StreamEvent]
       # @return [Hash] { output:, messages:, usage: }
-      def stream(input, config: {}, &block)
-        return invoke(input, config: config) unless block
+      def stream(input, messages: [], thread_id: nil, config: {}, &block)
+        return invoke(input, messages: messages, thread_id: thread_id, config: config) unless block
 
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
@@ -69,16 +70,15 @@ module Phronomy
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           run_input_guardrails!(input)
 
-          config[:thread_id]
           max_iter = self.class.max_iterations
 
-          messages = Array(config[:messages]).dup
+          messages = Array(messages).dup
           user_asked = false
           total_usage = Phronomy::TokenUsage.zero
           iterations_exhausted = true
 
           max_iter.times do
-            response = stream_step(messages, input, user_asked: user_asked, config: config, &block)
+            response = stream_step(messages, input, user_asked: user_asked, thread_id: thread_id, config: config, &block)
             user_asked = true
             messages = response[:messages]
             total_usage += response[:usage]
@@ -104,11 +104,23 @@ module Phronomy
 
       private
 
-      def step(messages, initial_input, user_asked: false, config: {})
+      def step(messages, initial_input, user_asked: false, thread_id: nil, config: {})
         chat = build_chat
 
-        # Inject any existing history (from previous loop iterations or loaded memory).
-        messages.each { |m| chat.add_message(m) }
+        if user_asked
+          # Subsequent loop iteration — messages already contains the full conversation
+          # (including the user's original input from the first step); apply system
+          # instructions and replay the accumulated history, then let the LLM continue.
+          system_text = build_cached_system_text(initial_input)
+          apply_instructions(chat, system_text) if system_text
+          messages.each { |m| chat.add_message(m) }
+        else
+          # First iteration — assemble context (system + history) via build_context so
+          # that trimming, compaction, and knowledge sources are applied consistently.
+          context = build_context(initial_input, messages: messages, thread_id: thread_id, config: config)
+          apply_instructions(chat, context[:system]) if context[:system]
+          context[:messages].each { |m| chat.messages << m }
+        end
 
         # Run before_completion hooks before each LLM call in the ReAct loop.
         run_before_completion_hooks!(chat, config)
@@ -130,9 +142,18 @@ module Phronomy
 
       # Streaming variant of #step.  Yields :token / :tool_call / :tool_result events
       # via the block while the LLM call is in progress.
-      def stream_step(messages, initial_input, user_asked: false, config: {}, &block)
+      def stream_step(messages, initial_input, user_asked: false, thread_id: nil, config: {}, &block)
         chat = build_chat
-        messages.each { |m| chat.add_message(m) }
+
+        if user_asked
+          system_text = build_cached_system_text(initial_input)
+          apply_instructions(chat, system_text) if system_text
+          messages.each { |m| chat.add_message(m) }
+        else
+          context = build_context(initial_input, messages: messages, thread_id: thread_id, config: config)
+          apply_instructions(chat, context[:system]) if context[:system]
+          context[:messages].each { |m| chat.messages << m }
+        end
 
         current_tool_call = nil
         chat.on_tool_call do |tc|