phronomy 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8bcaf54fe256791053b04c22df3b58595d267b2c0ee16b67369fe2ecb36f19d
-  data.tar.gz: 9be01ec03a79ec5d557a3c51fc442992cd012a07e682a43cfa4c9e0358110fc8
+  metadata.gz: e73d1b49c4638232021afad5cc807466c4bb7b2cfcfe60446930288e868a3db9
+  data.tar.gz: 624e783c532fc2ea009db99a7bda4a1308f06019bc0e776a78d206b70031b352
 SHA512:
-  metadata.gz: 44de75b5cc59ddf380aeb0be3abcf2a2c566cb8a1db6c35540525b86c74e7e0c06e75a3581e30276a25eea7f5f0334226e05b54d7d9694ed8f2b881d04a54e60
-  data.tar.gz: 76821f0cad1a918b762bb1d5737f902cc67b726f8dafb0dcf646b5cfc8dd4173527733a8a04e92e71ebea9a152fdb6ebaea20d9ccde3037f32d7fc32f5b05497
+  metadata.gz: 0ce003a8f0b0c85cd29a744b86ee89ad7414c511ea46c1ad446227824100174b6bfae76de8a4caa32428a50f77606af8006c17ae307eb514692a92829331570c
+  data.tar.gz: 10a3e965b58c730d5ba21eefc3c7151725a26e6accc24dbde04dd91546aa6c65bea801faae0fe5ef1908995a78c259159712c0f8dffe3f19938fa64b14988c16

data/CHANGELOG.md

@@ -9,7 +9,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
----
+### Added
+
+- **`Phronomy::Filter::Base` — unified value filter interface** (#389):
+  A single abstract base class `Filter::Base` with one method `call(value, **context)`
+  covers all three agent boundaries — user input, LLM output, and tool return values.
+  Subclasses return the (possibly transformed) value to continue, or call `block!` /
+  `raise Phronomy::FilterBlockError` to reject.  The same filter instance can be
+  registered at multiple sites.  Guardrails registered via `add_input_guardrail` /
+  `add_output_guardrail` are automatically included at the front of the filter chain.
+
+  ```ruby
+  class PiiMaskFilter < Phronomy::Filter::Base
+    def call(value, **_context)
+      value.to_s.gsub(/\b\d{2,4}-\d{2,4}-\d{4}\b/, "[PHONE]")
+    end
+  end
+
+  f = PiiMaskFilter.new
+  agent.add_input_filter(f)
+  agent.add_output_filter(f)
+  agent.add_tool_result_filter(CustomerDataTool, f)
+  ```
+
+  Class-level DSL counterparts: `input_filter`, `output_filter`, `tool_result_filter`.
+  The `tools(Hash)` DSL also accepts a `:result_filter` key for per-tool scoping.
+
+- **`Guardrail::Base#call` — Filter::Base-compatible interface**:
+  `Guardrail::Base` now implements `call(value, **_context)`, which calls `check(value)`
+  and returns the value unchanged (or raises `GuardrailError`).  Existing guardrail
+  subclasses require no changes.
+
+### Changed
+
+- **Guardrail execution unified into the filter chain**:
+  Guardrails registered via `add_input_guardrail` / `add_output_guardrail` now run
+  as the first entries in `run_input_filters!` / `run_output_filters!`.  The separate
+  `run_input_guardrails!` / `run_output_guardrails!` call sites in `invoke_once`,
+  `_stream_impl`, and `Suspendable#resume` have been removed.  Behaviour is unchanged
+  — guardrails still run before any filters and `GuardrailError` still propagates.
+
+
 
 ## [0.10.0] - 2026-06-08
 

data/README.md

@@ -7,7 +7,7 @@
 > We apologise for the instability this may cause.
 
 **Phronomy** is a Ruby AI agent framework inspired by open-source AI agent frameworks.  
-It provides composable building blocks — Workflows, Agents, Tools, Guardrails, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
+It provides composable building blocks — Workflows, Agents, Tools, Filters, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
 
 ## Features
 
@@ -31,8 +31,8 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Agent** — ReAct-style tool-calling agents with guardrails and conversation history | Stable |
 | **Before-Completion Hook** — Three-tier LLM parameter injection | Stable |
 | **Context Management** — Token budget calculation, estimation, and pruning; `Agent::Base` protected hooks: `build_context` (overridable), `trim_messages`, `trim_to_budget`, `compact_messages`, `budget_exceeded?`, `drop_messages_over` | Stable |
-| **Guardrails** — Input/output validation with custom `InputGuardrail`/`OutputGuardrail` | Beta |
-| **`PromptInjectionGuardrail`** — Built-in `InputGuardrail` subclass that detects prompt-injection patterns; usable standalone or as part of a guardrail chain | Beta |
+| **Filters** — Input/output transformation and blocking via `Filter::Base`; call `block!(reason)` to reject and raise `FilterBlockError` | Beta |
+| **`PromptInjectionFilter`** — Built-in `Filter::Base` subclass that detects prompt-injection patterns; usable standalone or as part of a filter chain | Beta |
 | **`Agent::Context::Capability::Base.redact_params` / `.max_result_size`** — Class-level DSL: `redact_params` masks parameter values in log/trace output; `max_result_size` truncates oversized tool results before they reach the LLM | Beta |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
@@ -78,6 +78,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
 | **`ScopePolicy`** — Configurable policy callable that maps (tool, scope, agent) to `:allow`/`:approve`/`:reject`; default policy auto-routes high-risk scopes through the approval gate | Experimental |
 | **HITL Checkpoint/Resume** — `Agent::Base#invoke` returns `{ suspended: true, checkpoint: Checkpoint }` when an approval-required tool is encountered without a synchronous handler; `Agent::Base#resume(checkpoint, approved:)` resumes execution; `Agent::Base.resume(checkpoint, approved:)` (class-level) resolves the agent class automatically; `Checkpoint#to_h` / `Checkpoint.from_h` for serialization; `Agent::Base#checkpoint_store=` for custom idempotency backends; `CheckpointAlreadyResumedError` raised on duplicate resume | Experimental |
+| **`Filter::Base` — unified value filter interface** — `Phronomy::Filter::Base` with a single abstract method `call(value, **context)`; apply to user input (`add_input_filter` / `input_filter` DSL), final LLM output (`add_output_filter` / `output_filter` DSL), or individual tool return values (`add_tool_result_filter(tool_class?, filter)` / `tool_result_filter` DSL); filters transform values and return the result, or raise `Phronomy::FilterBlockError` to reject; filter chains are composable; the same filter instance can be reused across all three sites | Beta |
 
 > **Public API boundary**: The tables above are the complete list of classes, modules, and features
 > intended for gem consumers. Every entry has an associated stability label.
@@ -252,30 +253,31 @@ result = OrchestratorAgent.new.invoke("Write a blog post about Ruby 3.4 features
 puts result[:output]
 ```
 
-### Guardrails — Input/output validation
+### Filters — Input/output transformation and blocking
 
-Call `fail!(reason)` inside `check` to reject — it raises `Phronomy::GuardrailError`.
-When a guardrail rejects, `invoke` raises instead of returning an output.
+Filters sit between user input and the LLM (input filters) or between the LLM response and the caller (output filters).
+A filter may **transform** the value (return the modified value) or **block** it (call `block!(reason)`, which raises `Phronomy::FilterBlockError`).
 
 ```ruby
-class NoSensitiveDataGuardrail < Phronomy::Guardrail::InputGuardrail
-  def check(input)
-    fail!("Credit card numbers are not allowed") if input.match?(/\d{4}-\d{4}-\d{4}-\d{4}/)
+class NoCreditCardFilter < Phronomy::Filter::Base
+  def call(value, **_context)
+    block!("Credit card numbers are not allowed") if value.match?(/\d{4}-\d{4}-\d{4}-\d{4}/)
+    value
   end
 end
 
 agent = ResearchAgent.new
-agent.add_input_guardrail(NoSensitiveDataGuardrail.new)
+agent.add_input_filter(NoCreditCardFilter.new)
 
 begin
   agent.invoke("Charge 4111-1111-1111-1111")
-rescue Phronomy::GuardrailError => e
+rescue Phronomy::FilterBlockError => e
   puts e.message   # => "Credit card numbers are not allowed"
 end
 ```
 
-> **Note:** Phronomy includes `PromptInjectionGuardrail`, a built-in pattern-based
-> input guardrail that detects common injection patterns (see the feature table above).
+> **Note:** Phronomy includes `PromptInjectionFilter`, a built-in pattern-based
+> input filter that detects common injection patterns (see the feature table above).
 > PII scanning and content classification are **not** provided by the framework;
 > that logic must be implemented by the application. Reference implementations for
 > common patterns are available in `phronomy-examples` (example 06).
@@ -851,11 +853,11 @@ span attributes by default (`trace_pii: false`). To include full content in trac
 Phronomy configuration. Evaluate whether your tracing backend (OTLP collector, Jaeger,
 Honeycomb, etc.) meets your data-retention and privacy requirements.
 
-**Prompt injection** — Phronomy provides `PromptInjectionGuardrail`, a built-in
-pattern-based input guardrail that detects common injection patterns (ignore/override
+**Prompt injection** — Phronomy provides `PromptInjectionFilter`, a built-in
+pattern-based input filter that detects common injection patterns (ignore/override
 instructions, role-switching phrases, etc.). It is a useful starting point, not a
 comprehensive defence; applications processing untrusted input should layer additional
-custom guardrails as needed (see the Guardrails section above).
+custom filters as needed (see the Filters section above).
 
 **Tool and MCP security** — Tools can perform real-world side effects (database
 writes, API calls, file deletion). Treat tool execution as a privileged operation:

data/lib/phronomy/agent/base.rb

@@ -3,7 +3,7 @@
 require "securerandom"
 require_relative "checkpoint_store"
 require_relative "concerns/retryable"
-require_relative "concerns/guardrailable"
+require_relative "concerns/filterable"
 require_relative "concerns/before_completion"
 require_relative "concerns/suspendable"
 require_relative "concerns/error_translation"
@@ -34,7 +34,7 @@ module Phronomy
     class Base
       include Phronomy::Runnable
       include Concerns::Retryable
-      include Concerns::Guardrailable
+      include Concerns::Filterable
       include Concerns::BeforeCompletion
       include Concerns::Suspendable
       include Concerns::ErrorTranslation
@@ -418,7 +418,7 @@ module Phronomy
 
       # Invokes the agent with the given input and returns a result Hash.
       # Applies the retry policy configured via {.retry_policy} when transient
-      # errors occur. {Phronomy::GuardrailError} is never retried.
+      # errors occur. {Phronomy::FilterBlockError} is never retried.
       #
       # @param input     [String, Hash] the user message; a Hash may supply
       #   +:message+, +:query+, or +:user+ as the text key, plus any template
@@ -439,7 +439,7 @@ module Phronomy
       # @return [Hash] +{ output: String, messages: Array, usage: Phronomy::TokenUsage }+,
       #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint,
       #   messages: Array }+ when the invocation was suspended awaiting tool approval.
-      # @raise [Phronomy::GuardrailError] when an input or output guardrail rejects the value
+      # @raise [Phronomy::FilterBlockError] when an input or output filter rejects the value
       # @example Normal invocation
       #   result = MyAgent.new.invoke("What is Ruby?")
       #   puts result[:output]
@@ -603,7 +603,7 @@ module Phronomy
       # Streaming implementation for #stream.
       def _stream_impl(input, messages: [], thread_id: nil, config: {}, &block)
         trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          run_input_guardrails!(input)
+          input = run_input_filters!(input)
 
           chat = build_chat
           user_message = extract_message(input)
@@ -634,7 +634,7 @@ module Phronomy
           run_before_completion_hooks!(chat, config)
 
           output, usage = _drain_stream(chat, user_message, config, &block)
-          run_output_guardrails!(output)
+          output = run_output_filters!(output)
 
           result = {output: output, messages: chat.messages, usage: usage}
           block.call(StreamEvent.new(type: :done, payload: result))
@@ -813,7 +813,7 @@ module Phronomy
       # wrap it in a retry loop without duplicating the LLM interaction logic.
       def invoke_once(input, messages: [], thread_id: nil, config: {})
         trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          run_input_guardrails!(input)
+          input = run_input_filters!(input)
 
           user_message = extract_message(input)
           chat = build_chat
@@ -835,7 +835,8 @@ module Phronomy
           )
           next [result, usage] if result[:suspended]
 
-          run_output_guardrails!(result[:output])
+          filtered_output = run_output_filters!(result[:output])
+          result = result.merge(output: filtered_output) unless filtered_output.equal?(result[:output])
           [result, usage]
         end
       end
@@ -1076,21 +1077,34 @@ module Phronomy
         end
 
         # Step 3: wrap with approval gate when handler is registered.
-        return resolved unless resolved.requires_approval && @approval_handler
+        if resolved.requires_approval && @approval_handler
+          handler = @approval_handler
+          # Capture the effective tool name before building the anonymous subclass.
+          # Class-level instance variables (@tool_name) are not inherited through
+          # subclassing, so the wrapper must set it explicitly.
+          effective_name = resolved.new.name
+          resolved = Class.new(resolved) do
+            tool_name effective_name
+            define_method(:call) do |args|
+              if handler.call(name, args)
+                super(args)
+              else
+                "Tool execution denied."
+              end
+            end
+          end
+        end
+
+        # Step 4: wrap with tool result filters when registered.
+        result_filters = _tool_result_filters_for(tool_class)
+        return resolved if result_filters.empty?
 
-        handler = @approval_handler
-        # Capture the effective tool name before building the anonymous subclass.
-        # Class-level instance variables (@tool_name) are not inherited through
-        # subclassing, so the wrapper must set it explicitly.
-        effective_name = resolved.new.name
+        effective_name4 = resolved.new.name
         Class.new(resolved) do
-          tool_name effective_name
+          tool_name effective_name4
           define_method(:call) do |args|
-            if handler.call(name, args)
-              super(args)
-            else
-              "Tool execution denied."
-            end
+            result = super(args)
+            result_filters.inject(result) { |val, f| f.call(val, tool_name: name, args: args) }
           end
         end
       end

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Concerns
+      # Adds input, output, and tool-result filter support to an agent.
+      #
+      # Filters transform (or block) values at three call sites:
+      #   - *input*       — the raw user input string, before the LLM is called
+      #   - *output*      — the final LLM output string, before it is returned
+      #   - *tool result* — the return value of each tool call
+      #
+      # Each filter in the chain receives the value returned by the previous one.
+      # A {Phronomy::FilterBlockError} raised inside any filter propagates to the
+      # caller.
+      #
+      # @api private
+      module Filterable
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class-level DSL mixed into the including agent class.
+        module ClassMethods
+          # Registers a filter applied to every invocation's user input.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def input_filter(filter)
+            @_class_input_filters ||= []
+            @_class_input_filters << _resolve_filter(filter)
+          end
+
+          # Registers a filter applied to every invocation's final LLM output.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def output_filter(filter)
+            @_class_output_filters ||= []
+            @_class_output_filters << _resolve_filter(filter)
+          end
+
+          # Registers a filter applied to every tool result for all tools.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def tool_result_filter(filter)
+            @_class_tool_result_filters ||= []
+            @_class_tool_result_filters << _resolve_filter(filter)
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_input_filters
+            @_class_input_filters || []
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_output_filters
+            @_class_output_filters || []
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_tool_result_filters
+            @_class_tool_result_filters || []
+          end
+
+          private
+
+          # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+          # otherwise return the object as-is.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [Phronomy::Filter::Base]
+          # @api private
+          def _resolve_filter(filter)
+            filter.is_a?(Class) ? filter.new : filter
+          end
+        end
+
+        # Registers an input filter on this instance.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # Runs in addition to any class-level input filters.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_input_filter(filter)
+          @_instance_input_filters ||= []
+          @_instance_input_filters << _resolve_filter(filter)
+          self
+        end
+
+        # Registers an output filter on this instance.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # Runs in addition to any class-level output filters.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_output_filter(filter)
+          @_instance_output_filters ||= []
+          @_instance_output_filters << _resolve_filter(filter)
+          self
+        end
+
+        # Registers a tool result filter on this instance.
+        #
+        # When called with two arguments, the filter is scoped to the given tool
+        # class only.  When called with one argument, it applies to all tools.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        #
+        # @overload add_tool_result_filter(filter)
+        #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>] applied to every tool
+        # @overload add_tool_result_filter(tool_class, filter)
+        #   @param tool_class [Class] scope the filter to this tool
+        #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_tool_result_filter(tool_class_or_filter, filter = nil)
+          if filter.nil?
+            # Single-argument form: apply to all tools.
+            @_instance_tool_result_filters ||= []
+            @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
+          else
+            # Two-argument form: scoped to one tool class.
+            @_scoped_tool_result_filters ||= {}
+            (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+          end
+          self
+        end
+
+        private
+
+        # Run input filters (class-level then instance-level).
+        # @param input [String, Hash] the raw user input
+        # @return [String, Hash] the (possibly transformed) input
+        # @api private
+        def run_input_filters!(input)
+          class_filters = self.class._class_input_filters
+          inst_filters = @_instance_input_filters || []
+          (class_filters + inst_filters).inject(input) { |val, f| f.call(val) }
+        end
+
+        # Run output filters (class-level then instance-level).
+        # @param output [String] the LLM output
+        # @return [String] the (possibly transformed) output
+        # @api private
+        def run_output_filters!(output)
+          class_filters = self.class._class_output_filters
+          inst_filters = @_instance_output_filters || []
+          (class_filters + inst_filters).inject(output) { |val, f| f.call(val) }
+        end
+
+        # Collect all tool-result filters (global + scoped) for a given tool class.
+        # @param tool_class [Class]
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _tool_result_filters_for(tool_class)
+          global = self.class._class_tool_result_filters + (@_instance_tool_result_filters || [])
+          scoped = (@_scoped_tool_result_filters || {})[tool_class] || []
+          global + scoped
+        end
+
+        # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+        # otherwise return the object as-is.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [Phronomy::Filter::Base]
+        # @api private
+        def _resolve_filter(filter)
+          filter.is_a?(Class) ? filter.new : filter
+        end
+      end
+    end
+  end
+end

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

@@ -6,7 +6,7 @@ module Phronomy
       # 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.
+      # #invoke_once call; {Phronomy::FilterBlockError} is never retried.
       # @api private
       module Retryable
         def self.included(base)
@@ -16,7 +16,7 @@ module Phronomy
         # 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.
+          # FilterBlockError 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
@@ -60,7 +60,7 @@ module Phronomy
           attempt = 0
           begin
             invoke_once(input, messages: messages, thread_id: thread_id, config: config)
-          rescue Phronomy::GuardrailError
+          rescue Phronomy::FilterBlockError
             raise
           rescue Phronomy::CancellationError
             raise # Never retry after cancellation.

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

@@ -80,7 +80,7 @@ module Phronomy
         # @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::FilterBlockError] when an output filter rejects the value
         # @raise [Phronomy::CheckpointAlreadyResumedError] when the checkpoint has already been consumed
         # @api private
         def resume(checkpoint, approved:, config: {})
@@ -143,7 +143,7 @@ module Phronomy
           output = response.content
           usage = Phronomy::TokenUsage.from_tokens(response.tokens)
 
-          run_output_guardrails!(output)
+          output = run_output_filters!(output)
 
           {output: output, suspended: false, messages: chat.messages, usage: usage}
         end

data/lib/phronomy/agent/context/capability/base.rb

@@ -92,7 +92,7 @@ module Phronomy
             public
 
             # Sets the access scope for this tool (metadata; enforcement is the responsibility of
-            # the Workflow/Guardrail layer).
+            # the Workflow/Filter layer).
             # @param value [Symbol] e.g. :read_only, :write, :admin
             # @api public
             # mutant:disable - neutral failure: unparser round-trip produces different source
@@ -218,7 +218,7 @@ module Phronomy
             # retried up to +times+ times with the specified wait strategy.
             # Multiple policies can be registered and are evaluated in order.
             #
-            # GuardrailError is never retried regardless of this configuration.
+            # FilterBlockError is never retried regardless of this configuration.
             #
             # @param exception_classes [Array<Class>] exception classes to retry on
             # @param times  [Integer] maximum retry attempts (default: 1)

data/lib/phronomy/filter/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Filter
+    # Abstract base class for value filters.
+    #
+    # A filter may either transform a value (return the new value) or block it
+    # (raise {Phronomy::FilterBlockError}).  The same filter instance can be
+    # registered at multiple call sites — input, output, and tool result.
+    #
+    # @example PII masking filter
+    #   class PiiMaskFilter < Phronomy::Filter::Base
+    #     def call(value, **_context)
+    #       value.to_s
+    #            .gsub(/\b\d{2,4}-\d{2,4}-\d{4}\b/, "[PHONE]")
+    #            .gsub(/\b(?:\d{4}[- ]?){3}\d{4}\b/, "[CARD]")
+    #     end
+    #   end
+    #
+    # @example Blocking filter
+    #   class NoBadWordFilter < Phronomy::Filter::Base
+    #     def call(value, **_context)
+    #       block!("Forbidden content detected") if value.to_s.include?("badword")
+    #       value
+    #     end
+    #   end
+    #
+    # @api public
+    class Base
+      # Process +value+ and return the (possibly transformed) result.
+      #
+      # The +context+ keyword arguments vary by call site:
+      #   - Tool result: +{ tool_name: String, args: Hash }+
+      #   - Input / output: +(empty)+
+      #
+      # @param value   [Object] the value being filtered
+      # @param context [Hash]   optional call-site metadata
+      # @return [Object] the transformed value (or the original if unchanged)
+      # @raise [Phronomy::FilterBlockError] to reject the value
+      # @api public
+      def call(value, **_context)
+        raise NotImplementedError, "#{self.class}#call is not implemented"
+      end
+
+      protected
+
+      # Reject the value with a human-readable reason.
+      # @param reason [String]
+      # @raise [Phronomy::FilterBlockError]
+      # @api public
+      def block!(reason)
+        raise Phronomy::FilterBlockError.new(reason, filter: self)
+      end
+    end
+  end
+end

data/lib/phronomy/{guardrail/prompt_injection_guardrail.rb → filter/prompt_injection_filter.rb}

@@ -1,28 +1,31 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Guardrail
+  module Filter
     # Detects potential prompt injection attempts in the agent input.
     #
     # Prompt injection is an attack where an adversary embeds LLM instructions
     # inside data sources (e.g. RAG chunks, tool results, user input) to override
     # the agent's intended behaviour.
     #
-    # This guardrail scans the input string for common injection patterns and
-    # calls {#fail!} when a match is found.  It is intended to be registered as
-    # an input guardrail on agents that consume untrusted external content.
+    # This filter scans the input string for common injection patterns and
+    # calls {#block!} when a match is found.  It is intended to be registered as
+    # an input filter on agents that consume untrusted external content.
     #
     # @example
     #   class MyAgent < Phronomy::Agent::Base
     #     model "gpt-4o"
-    #     input_guardrails Phronomy::Guardrail::PromptInjectionGuardrail.new
+    #     input_filter Phronomy::Filter::PromptInjectionFilter
     #   end
     #
     # @example Custom patterns
-    #   guard = Phronomy::Guardrail::PromptInjectionGuardrail.new(
+    #   filter = Phronomy::Filter::PromptInjectionFilter.new(
     #     extra_patterns: [/exfiltrate/i]
     #   )
-    class PromptInjectionGuardrail < InputGuardrail
+    #   agent.add_input_filter(filter)
+    #
+    # @api public
+    class PromptInjectionFilter < Base
       # Common prompt injection / jailbreak patterns.
       DEFAULT_PATTERNS = [
         /ignore\s+(previous|prior|all)\s+instructions?/i,
@@ -38,20 +41,24 @@ module Phronomy
       ].freeze
 
       # @param extra_patterns [Array<Regexp>] additional patterns to scan for
-      # @api private
+      # @api public
       def initialize(extra_patterns: [])
         super()
         @patterns = DEFAULT_PATTERNS + extra_patterns
       end
 
       # Scans the input string for injection patterns.
-      # @param input [String, Hash]
-      # @api private
-      def check(input)
-        text = input.is_a?(Hash) ? input.values.join(" ") : input.to_s
+      # @param value [String, Hash]
+      # @param context [Hash]
+      # @return [String, Hash] the original value when no injection is detected
+      # @raise [Phronomy::FilterBlockError] when a pattern matches
+      # @api public
+      def call(value, **_context)
+        text = value.is_a?(Hash) ? value.values.join(" ") : value.to_s
         @patterns.each do |pattern|
-          fail!("Potential prompt injection detected") if text.match?(pattern)
+          block!("Potential prompt injection detected") if text.match?(pattern)
         end
+        value
       end
     end
   end

data/lib/phronomy/filter.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Convenience require for Filter sub-classes.
+require_relative "filter/base"
+require_relative "filter/prompt_injection_filter"

data/lib/phronomy/generator_verifier.rb

@@ -66,8 +66,7 @@ module Phronomy
     # @!attribute [r] trusted
     #   @return [Boolean] true when confidence >= threshold
     Result = Struct.new(
-      :output, :confidence, :citations, :iterations, :review_notes, :trusted,
-      keyword_init: true
+      :output, :confidence, :citations, :iterations, :review_notes, :trusted
     ) do
       # @return [Boolean] true when confidence >= threshold
       alias_method :trusted?, :trusted

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -47,8 +47,7 @@ module Phronomy
         :index,    # Integer — 0-based worker index
         :agent,    # Agent::Base instance
         :messages, # Array  — accumulated conversation history
-        :status,   # Symbol — :idle | :available | :done
-        keyword_init: true
+        :status    # Symbol — :idle | :available | :done
       ) do
         # Returns true when this worker is ready to accept the next task.
         def available? = [:idle, :available].include?(status)

data/lib/phronomy/version.rb

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

data/lib/phronomy.rb

@@ -87,12 +87,15 @@ module Phronomy
     end
   end
 
-  class GuardrailError < Error
-    attr_reader :guardrail
+  # Raised by a {Phronomy::Filter::Base} subclass when the filter rejects a
+  # value without transforming it (blocking the pipeline).
+  # @api public
+  class FilterBlockError < Error
+    attr_reader :filter
 
-    def initialize(message, guardrail: nil)
+    def initialize(message, filter: nil)
       super(message)
-      @guardrail = guardrail
+      @filter = filter
     end
   end
 

data/scripts/api_snapshot.rb

@@ -32,8 +32,8 @@ PUBLIC_API_ENTRIES = [
   # Beta
   Phronomy::MultiAgent::Orchestrator,
   Phronomy::MultiAgent::TeamCoordinator,
-  Phronomy::Guardrail::InputGuardrail,
-  Phronomy::Guardrail::OutputGuardrail,
+  Phronomy::Filter::Base,
+  Phronomy::Filter::PromptInjectionFilter,
   Phronomy::VectorStore::Base,
   Phronomy::VectorStore::InMemory,
   Phronomy::VectorStore::Embeddings::Base,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-07 00:00:00.000000000 Z
+date: 2026-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -64,9 +64,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
-description: Phronomy provides composable building blocks — Agents, Workflows, Tools,
-  Guardrails, and Tracing — for building AI agents in Ruby. Powered by RubyLLM for
-  LLM abstraction.
+description: Phronomy is a Ruby AI agent framework that provides composable building
+  blocks — Agents, Workflows, Tools, Filters, and Tracing — for building AI agents
+  in Ruby. Powered by RubyLLM for LLM abstraction.
 email:
 - raizo.tcs@gmail.com
 executables: []
@@ -109,7 +109,7 @@ files:
 - lib/phronomy/agent/checkpoint_store.rb
 - lib/phronomy/agent/concerns/before_completion.rb
 - lib/phronomy/agent/concerns/error_translation.rb
-- lib/phronomy/agent/concerns/guardrailable.rb
+- lib/phronomy/agent/concerns/filterable.rb
 - lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/concerns/suspendable.rb
 - lib/phronomy/agent/context/capability/base.rb
@@ -147,12 +147,10 @@ files:
 - lib/phronomy/eval/scorer/llm_judge.rb
 - lib/phronomy/event.rb
 - lib/phronomy/event_loop.rb
+- lib/phronomy/filter.rb
+- lib/phronomy/filter/base.rb
+- lib/phronomy/filter/prompt_injection_filter.rb
 - lib/phronomy/generator_verifier.rb
-- lib/phronomy/guardrail.rb
-- lib/phronomy/guardrail/base.rb
-- lib/phronomy/guardrail/input_guardrail.rb
-- lib/phronomy/guardrail/output_guardrail.rb
-- lib/phronomy/guardrail/prompt_injection_guardrail.rb
 - lib/phronomy/invocation_context.rb
 - lib/phronomy/knowledge_source.rb
 - lib/phronomy/llm_adapter.rb

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/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"