phronomy 0.10.0 → 0.11.1

data/lib/phronomy/agent/checkpoint_store.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Default in-memory idempotency store for {Checkpoint} resume operations.
-    #
-    # Tracks consumed checkpoint IDs so that calling {Agent::Base#resume} twice
-    # with the same checkpoint raises {Phronomy::CheckpointAlreadyResumedError}
-    # instead of silently executing the approved tool a second time.
-    #
-    # This implementation is *not thread-safe*. It assumes a single agent instance
-    # is accessed from only one thread at a time, which is the expected usage pattern.
-    # Agent instances themselves are not thread-safe (state like +@messages+, +@config+
-    # is not protected), so concurrent calls to the same agent instance are unsupported.
-    #
-    # Each agent instance gets its own store by default, so no sharing occurs unless
-    # the caller explicitly assigns the same store object to multiple agents.
-    #
-    # For distributed environments (multiple processes or background jobs), swap this
-    # for a custom implementation backed by Redis, ActiveRecord, or another shared store.
-    # *Your custom store implementation is responsible for ensuring thread-safety* if
-    # your application shares the same store instance across multiple threads.
-    #
-    # @example Plugging in a custom store
-    #   agent = MyAgent.new
-    #   agent.checkpoint_store = MyRedis::CheckpointStore.new
-    #
-    # @example Duck-type contract required by any replacement
-    #   # consumed?(checkpoint_id) => Boolean
-    #   # consume!(checkpoint_id)  => void; raises CheckpointAlreadyResumedError if duplicate
-    #   # cleanup!(checkpoint_id)  => void (optional); removes tracking for the checkpoint
-    #   # clear!                   => void (optional); removes all tracked checkpoints
-    #
-    # @api public
-    class CheckpointStore
-      def initialize
-        @consumed = Set.new
-      end
-
-      # Returns +true+ if the given checkpoint ID has already been consumed.
-      #
-      # @param checkpoint_id [String]
-      # @return [Boolean]
-      # @api public
-      def consumed?(checkpoint_id)
-        @consumed.include?(checkpoint_id)
-      end
-
-      # Marks +checkpoint_id+ as consumed, or raises if it was already consumed.
-      #
-      # @param checkpoint_id [String]
-      # @raise [Phronomy::CheckpointAlreadyResumedError]
-      # @return [void]
-      # @api public
-      def consume!(checkpoint_id)
-        if @consumed.include?(checkpoint_id)
-          raise Phronomy::CheckpointAlreadyResumedError,
-            "checkpoint #{checkpoint_id} has already been resumed"
-        end
-        @consumed.add(checkpoint_id)
-        nil
-      end
-
-      # Removes tracking for a specific checkpoint ID.
-      #
-      # Use this to explicitly discard a checkpoint when the application
-      # determines it is no longer needed (e.g., user abandons an approval
-      # workflow).
-      #
-      # This method is optional in the duck-type contract. Custom store
-      # implementations may choose not to implement it.
-      #
-      # @param checkpoint_id [String]
-      # @return [void]
-      # @api public
-      def cleanup!(checkpoint_id)
-        @consumed.delete(checkpoint_id)
-        nil
-      end
-
-      # Removes all tracked checkpoint IDs.
-      #
-      # Use this for test cleanup, periodic maintenance, or application
-      # shutdown.
-      #
-      # This method is optional in the duck-type contract. Custom store
-      # implementations may choose not to implement it.
-      #
-      # @return [void]
-      # @api public
-      def clear!
-        @consumed.clear
-        nil
-      end
-    end
-  end
-end

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

@@ -1,45 +0,0 @@
-# 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.
-      # @api private
-      module Guardrailable
-        # Attach a guardrail that validates input before every #invoke call.
-        # @param guardrail [Phronomy::Guardrail::InputGuardrail]
-        # @return [self]
-        # @api private
-        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]
-        # @api private
-        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/suspendable.rb

@@ -1,190 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-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
-      # @api private
-      # {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]
-        # @api private
-        def on_approval_required(&block)
-          @approval_handler = block
-          self
-        end
-
-        # Registers a scope policy callable for this agent instance.
-        #
-        # The callable receives +(tool_class, scope, agent)+ and must return
-        # +:allow+, +:reject+, or +:approve+.
-        #
-        # @example Reject all write-scoped tools
-        #   agent.scope_policy = ->(_tc, scope, _agent) { scope == :write ? :reject : :allow }
-        #
-        # @param policy [#call]
-        # @return [void]
-        # @api public
-        def scope_policy=(policy)
-          @scope_policy = policy
-        end
-
-        # Sets the idempotency store used to guard against duplicate resumes.
-        #
-        # The store must respond to:
-        # - +consumed?(checkpoint_id)+ ⇒ Boolean
-        # - +consume!(checkpoint_id)+  ⇒ void; raises {Phronomy::CheckpointAlreadyResumedError} on duplicate
-        #
-        # Defaults to a per-instance {Phronomy::Agent::CheckpointStore} (in-memory, not thread-safe).
-        # Assign a shared persistent store when resuming across processes (e.g. Redis-backed).
-        # Custom stores are responsible for ensuring thread-safety if shared across threads.
-        #
-        # @param store [#consumed?, #consume!]
-        # @return [void]
-        # @api public
-        def checkpoint_store=(store)
-          @checkpoint_store = store
-        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 }+
-        #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint, messages: Array }+
-        #   when a second approval-required tool is encountered during continuation
-        # @raise [Phronomy::GuardrailError] when an output guardrail rejects the value
-        # @raise [Phronomy::CheckpointAlreadyResumedError] when the checkpoint has already been consumed
-        # @api private
-        def resume(checkpoint, approved:, config: {})
-          # Guard against duplicate resumes using the idempotency store.
-          _checkpoint_store.consume!(checkpoint.checkpoint_id)
-          # Build a fresh chat with all tools registered.
-          chat = build_chat
-
-          # Re-apply system instructions and register tools so the LLM has the
-          # same persona/context as the original invocation. build_context
-          # includes all tool classes (static + handoff) via add_capability.
-          context = build_context(checkpoint.original_input, messages: [])
-          apply_instructions(chat, context[:system]) if context[:system]
-          (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
-
-          # 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
-          )
-
-          # Re-register the suspension hook so that any further requires_approval
-          # tools encountered during continuation are intercepted rather than
-          # executed without approval (cascading / chained approval scenario).
-          _register_suspension_hook!(chat)
-
-          # Continue the LLM loop. Rescue SuspendSignal so that a second
-          # approval-required tool produces a new checkpoint instead of running
-          # without consent.
-          begin
-            response = chat.complete
-          rescue SuspendSignal => signal
-            new_checkpoint = Checkpoint.new(
-              checkpoint_id: SecureRandom.uuid,
-              agent_class: self.class.name,
-              requested_at: Time.now.utc,
-              thread_id: checkpoint.thread_id,
-              original_input: checkpoint.original_input,
-              messages: chat.messages.dup,
-              pending_tool_name: signal.tool_name,
-              pending_tool_args: signal.args,
-              pending_tool_call_id: signal.tool_call_id
-            )
-            return {output: nil, suspended: true, checkpoint: new_checkpoint, messages: chat.messages}
-          end
-
-          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]
-        # @api private
-        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
-
-        # Returns the checkpoint idempotency store for this instance, lazily
-        # initialising a default in-memory {Phronomy::Agent::CheckpointStore}.
-        #
-        # @return [#consumed?, #consume!]
-        # @api private
-        def _checkpoint_store
-          @checkpoint_store ||= CheckpointStore.new
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/suspend_signal.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Raised internally inside the on_tool_call hook when an approval-required
-    # tool is encountered and no synchronous on_approval_required handler has
-    # been registered.  Caught by Agent::Base#invoke_once to produce a
-    # suspended result hash containing a Checkpoint.
-    #
-    # This class is intentionally NOT part of the public API.  Callers should
-    # @api private
-    # inspect the +:suspended+ key in the result hash returned by #invoke.
-    #
-    # @api private
-    class SuspendSignal < StandardError
-      # @return [String] the name of the tool that triggered the suspension
-      attr_reader :tool_name
-
-      # @return [Hash] the arguments the LLM passed to the tool
-      attr_reader :args
-
-      # @return [String] the tool_call_id from the LLM response
-      attr_reader :tool_call_id
-
-      # @param tool_name    [String]
-      # @param args         [Hash]
-      # @param tool_call_id [String]
-      # @api private
-      def initialize(tool_name:, args:, tool_call_id:)
-        super("Agent suspended waiting for approval of tool: #{tool_name}")
-        @tool_name = tool_name
-        @args = args
-        @tool_call_id = tool_call_id
-      end
-    end
-  end
-end

data/lib/phronomy/context.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Context management utilities: token estimation, budget calculation, and
-  # context assembly.
-  #
-  # Sub-modules are auto-loaded by Zeitwerk:
-  #   Phronomy::LlmContextWindow::TokenEstimator
-  #   Phronomy::LlmContextWindow::TokenBudget
-  module Context
-  end
-end

data/lib/phronomy/guardrail/base.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Guardrail
-    # Abstract base class for all guardrails.
-    #
-    # Subclasses override #check to validate input or output.
-    # Call #fail! inside #check to reject with a reason.
-    #
-    # @example
-    #   class NoPIIGuardrail < Phronomy::Guardrail::InputGuardrail
-    #     def check(input)
-    #       fail!("PII detected") if input.to_s.match?(/\d{3}-\d{2}-\d{4}/)
-    #     end
-    #   end
-    class Base
-      # Validate the value. Subclasses must implement this method.
-      # @param value [Object] the input or output being checked
-      # @raise [Phronomy::GuardrailError] if the guardrail rejects the value
-      # @api public
-      def check(value)
-        raise NotImplementedError, "#{self.class}#check is not implemented"
-      end
-
-      # Run the check, raising GuardrailError on failure.
-      # @param value [Object]
-      # @return [Object] the original value (unchanged) when the check passes
-      # @api public
-      def run!(value)
-        check(value)
-        value
-      end
-
-      protected
-
-      # Call inside #check to reject the value.
-      # @param reason [String] human-readable rejection reason
-      # @raise [Phronomy::GuardrailError]
-      # @api public
-      def fail!(reason)
-        raise Phronomy::GuardrailError.new(reason, guardrail: self)
-      end
-    end
-  end
-end

data/lib/phronomy/guardrail/input_guardrail.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Guardrail
-    # Guardrail applied to agent/chain input before it reaches the LLM.
-    #
-    # @example
-    #   class NoCreditCardGuardrail < Phronomy::Guardrail::InputGuardrail
-    #     def check(input)
-    #       fail!("Credit card numbers are not allowed") if input.to_s.match?(/\d{4}[- ]\d{4}[- ]\d{4}[- ]\d{4}/)
-    #     end
-    #   end
-    #
-    #   agent = MyAgent.new
-    #   agent.add_input_guardrail(NoCreditCardGuardrail.new)
-    class InputGuardrail < Base
-    end
-  end
-end

data/lib/phronomy/guardrail/output_guardrail.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Guardrail
-    # Guardrail applied to agent/chain output before it is returned to the caller.
-    #
-    # @example
-    #   class NoSecretsGuardrail < Phronomy::Guardrail::OutputGuardrail
-    #     def check(output)
-    #       fail!("Response contains a secret key") if output.to_s.match?(/sk-[A-Za-z0-9]{32,}/)
-    #     end
-    #   end
-    #
-    #   agent = MyAgent.new
-    #   agent.add_output_guardrail(NoSecretsGuardrail.new)
-    class OutputGuardrail < Base
-    end
-  end
-end

data/lib/phronomy/guardrail.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-# Convenience require for Guardrail sub-classes.
-# Zeitwerk auto-loads individual files; this is only needed for explicit requires.
-require_relative "guardrail/base"
-require_relative "guardrail/input_guardrail"
-require_relative "guardrail/output_guardrail"

data/lib/phronomy/tool.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-# This file is intentionally empty.
-# Tool definitions have moved to Phronomy::Agent::Context::Capability.
-# See lib/phronomy/agent/context/capability/.
-module Phronomy
-  module Tool
-  end
-end