riffer 0.31.0 → 0.32.0

data/lib/riffer/config.rb

@@ -2,20 +2,6 @@
 # rbs_inline: enabled
 
 # Configuration for the Riffer framework.
-#
-# Provides configuration options for AI providers and other settings.
-#
-#   Riffer.config.openai.api_key = "sk-..."
-#
-#   Riffer.config.amazon_bedrock.region = "us-east-1"
-#   Riffer.config.amazon_bedrock.api_token = "..."
-#
-#   Riffer.config.anthropic.api_key = "sk-ant-..."
-#
-#   Riffer.config.openrouter.api_key = "sk-or-..."
-#
-#   Riffer.config.evals.judge_model = "anthropic/claude-sonnet-4-20250514"
-#
 class Riffer::Config
   AmazonBedrock = Struct.new(:api_token, :region, keyword_init: true)
   Anthropic = Struct.new(:api_key, keyword_init: true)
@@ -27,22 +13,13 @@ class Riffer::Config
   Mcp = Struct.new(:credentials, :discovery_runner, keyword_init: true)
 
   # Skills-related global configuration.
-  #
-  # See <tt>Riffer.config.skills.default_activate_tool</tt> and
-  # <tt>Riffer.config.skills.default_backend</tt>.
   class Skills
-    # Default skill activation tool class.
-    #
-    # The tool class the LLM calls to activate a skill. Defaults to
-    # <tt>Riffer::Skills::ActivateTool</tt>. Per-agent override is available
-    # via <tt>skills do; activate_tool ...; end</tt>.
+    # The tool class the LLM calls to activate a skill; defaults to
+    # <tt>Riffer::Skills::ActivateTool</tt>.
     attr_reader :default_activate_tool #: singleton(Riffer::Tool)
 
-    # Default skills backend.
-    #
-    # Used by agents that declare a +skills+ block without specifying a
-    # backend. Accepts a Riffer::Skills::Backend instance or a Proc.
-    # Defaults to +nil+ (no global default).
+    # Default skills backend for agents that declare a +skills+ block without
+    # one; defaults to +nil+.
     attr_reader :default_backend #: (Riffer::Skills::Backend | Proc)?
 
     #--
@@ -52,10 +29,8 @@ class Riffer::Config
       @default_backend = nil
     end
 
-    # Sets the default skill activation tool class.
-    #
-    # Raises +Riffer::ArgumentError+ if the value is not a Riffer::Tool subclass.
-    #
+    # Sets the default skill activation tool class. Raises Riffer::ArgumentError
+    # on an invalid value.
     #--
     #: (singleton(Riffer::Tool)) -> void
     def default_activate_tool=(value)
@@ -63,11 +38,8 @@ class Riffer::Config
       @default_activate_tool = value
     end
 
-    # Sets the default skills backend.
-    #
-    # Raises +Riffer::ArgumentError+ if the value is not a
-    # Riffer::Skills::Backend instance, a Proc, or +nil+.
-    #
+    # Sets the default skills backend. Raises Riffer::ArgumentError on an
+    # invalid value.
     #--
     #: ((Riffer::Skills::Backend | Proc)?) -> void
     def default_backend=(value)
@@ -79,49 +51,38 @@ class Riffer::Config
 
   VALID_MESSAGE_ID_STRATEGIES = %i[none uuid uuidv7].freeze
 
-  # Amazon Bedrock configuration (Struct with +api_token+ and +region+).
+  # Amazon Bedrock configuration.
   attr_reader :amazon_bedrock #: Riffer::Config::AmazonBedrock
 
-  # Anthropic configuration (Struct with +api_key+).
+  # Anthropic configuration.
   attr_reader :anthropic #: Riffer::Config::Anthropic
 
-  # Azure OpenAI configuration (Struct with +api_key+ and +endpoint+).
+  # Azure OpenAI configuration.
   attr_reader :azure_openai #: Riffer::Config::AzureOpenAI
 
-  # Google Gemini configuration (Struct with +api_key+, +open_timeout+, and +read_timeout+).
+  # Google Gemini configuration.
   attr_reader :gemini #: Riffer::Config::Gemini
 
-  # OpenAI configuration (Struct with +api_key+).
+  # OpenAI configuration.
   attr_reader :openai #: Riffer::Config::OpenAI
 
-  # OpenRouter configuration (Struct with +api_key+).
+  # OpenRouter configuration.
   attr_reader :openrouter #: Riffer::Config::OpenRouter
 
-  # Evals configuration (Struct with +judge_model+).
+  # Evals configuration.
   attr_reader :evals #: Riffer::Config::Evals
 
-  # MCP configuration (Struct with +credentials+ and +discovery_runner+).
-  #
-  # +credentials+ is an optional Proc for per-run MCP +tools/call+ HTTP headers.
-  # Signature: +->(manifest:, matched_tags:, context:) { Hash or nil }+.
-  # +nil+ from the proc at tool-resolution time omits that server's tools; +nil+
-  # at tool-call time raises Riffer::Mcp::CredentialsDeniedError.
-  #
-  # +discovery_runner+ is the Riffer::Runner used to execute tool discovery
-  # (default +Runner::Sequential+).
+  # MCP configuration. +credentials+ is an optional Proc returning per-run
+  # +tools/call+ headers (or +nil+ to deny); +discovery_runner+ runs tool
+  # discovery.
   attr_reader :mcp #: Riffer::Config::Mcp
 
-  # Global tool runtime configuration (experimental).
-  #
-  # Accepts a Riffer::Tools::Runtime subclass, a Riffer::Tools::Runtime instance,
-  # or a Proc. Defaults to <tt>Riffer::Tools::Runtime::Inline.new</tt>.
+  # Global tool runtime configuration (experimental); defaults to
+  # <tt>Riffer::Tools::Runtime::Inline.new</tt>.
   attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
 
-  # Sets the global tool runtime.
-  #
-  # Raises +Riffer::ArgumentError+ if the value is not a valid runtime
-  # (ToolRuntime subclass, ToolRuntime instance, or Proc).
-  #
+  # Sets the global tool runtime. Raises Riffer::ArgumentError on an invalid
+  # value.
   #--
   #: ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> void
   def tool_runtime=(value)
@@ -130,23 +91,16 @@ class Riffer::Config
     @tool_runtime = value
   end
 
-  # Skills-related global configuration. Returns a Riffer::Config::Skills
-  # object — see <tt>Riffer.config.skills.default_activate_tool</tt>.
+  # Skills-related global configuration.
   attr_reader :skills #: Riffer::Config::Skills
 
-  # Strategy for auto-generating message ids. One of +:none+ (default, no id),
-  # +:uuid+ (UUIDv4), or +:uuidv7+ (time-ordered UUIDv7).
-  #
-  # When set to anything other than +:none+, each +Riffer::Messages::Base+
-  # instance gets an +id+ populated at construction time, and seeded messages
-  # passed to +Riffer::Agent#generate+ must carry their own +:id+.
+  # Strategy for auto-generating message ids: +:none+ (default), +:uuid+, or
+  # +:uuidv7+. When not +:none+, messages get an +id+ at construction, and
+  # seeded messages passed to +Riffer::Agent#generate+ must carry their own.
   attr_reader :message_id_strategy #: Symbol
 
-  # Sets the message id strategy.
-  #
-  # Raises +Riffer::ArgumentError+ if the value is not one of
-  # +:none+, +:uuid+, or +:uuidv7+.
-  #
+  # Sets the message id strategy. Raises Riffer::ArgumentError unless the value
+  # is +:none+, +:uuid+, or +:uuidv7+.
   #--
   #: (Symbol) -> void
   def message_id_strategy=(value)
@@ -157,35 +111,14 @@ class Riffer::Config
     @message_id_strategy = value
   end
 
-  # Experimental: when +true+, riffer keeps the +tool_use+ ↔ +tool_result+
-  # invariant intact on its own.
-  #
-  # - On +Riffer::Agent#generate(messages_array)+, orphaned +tool_use+
-  #   exchanges and parentless +Riffer::Messages::Tool+ messages are
-  #   silently stripped from the seed. Pending tool calls on the resume
-  #   boundary (last assistant whose tail is purely Tool results) are
-  #   preserved for +execute_pending_tool_calls+.
-  # - On any interrupt (caller-issued +interrupt!+ or
-  #   +INTERRUPT_MAX_STEPS+), riffer fills any orphaned +tool_use+ with a
-  #   placeholder +Riffer::Messages::Tool+ carrying
-  #   +error_type: :interrupted+, leaving history valid for the next turn.
-  #   Filled call_ids are exposed on
-  #   +Riffer::Agent::Response#healed_tool_call_ids+ (and the streaming
-  #   +Riffer::StreamEvents::Interrupt+ event).
-  #
-  # Defaults to +false+ — the pre-healing behavior. Experimental: the
-  # surface and default may change without notice.
+  # Experimental: when +true+, riffer maintains the +tool_use+ ↔ +tool_result+
+  # invariant itself — stripping orphaned exchanges and filling interrupted
+  # ones. Defaults to +false+; the surface may change without notice.
   attr_reader :experimental_history_healing #: bool
 
-  # Sets the +experimental_history_healing+ flag.
-  #
-  # Coerces common boolean representations so values pulled from
-  # environment variables don't silently enable healing — the string
-  # +"false"+ is truthy in Ruby and would otherwise flip the flag on.
-  # Accepts +true+/+false+, +"true"+/+"false"+, +1+/+0+, +"1"+/+"0"+, and
-  # +nil+ (treated as +false+, the default). Raises
-  # +Riffer::ArgumentError+ for any other value.
-  #
+  # Sets the +experimental_history_healing+ flag, coercing boolean-ish values so
+  # an env-var +"false"+ (truthy in Ruby) doesn't silently enable healing.
+  # Raises Riffer::ArgumentError on an unrecognized value.
   #--
   #: (untyped) -> void
   def experimental_history_healing=(value)

data/lib/riffer/evals/evaluator.rb

@@ -1,13 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Base class for all evaluators in the Riffer framework.
-#
-# Provides a DSL for defining evaluator metadata and the evaluate method.
-# Simple evaluators only need to set +instructions+ — the base class
-# handles calling the judge automatically.
-#
-# See examples/evaluators/ for reference implementations.
+# Base class for all evaluators. Set +instructions+ and the base class calls
+# the judge automatically; override +#evaluate+ for custom logic. See
+# examples/evaluators/ for reference implementations.
 #
 #   class MyEvaluator < Riffer::Evals::Evaluator
 #     instructions "Assess medical accuracy of the response..."
@@ -54,18 +50,9 @@ class Riffer::Evals::Evaluator
     end
   end
 
-  # Evaluates an input/output pair.
-  #
-  # The default implementation calls the judge with the class-level +instructions+.
-  # Override this method for custom evaluation logic (e.g. rule-based evaluators).
-  #
-  # [input] the input to evaluate; String or Array of message hashes/Message objects.
-  # [output] the agent's response to evaluate.
-  # [ground_truth] optional reference answer for comparison.
-  # [messages] the full message history from the agent conversation.
-  #
-  # Raises NotImplementedError if neither +instructions+ is set nor +evaluate+ is overridden.
-  #
+  # Evaluates an input/output pair. The default calls the judge with the
+  # class-level +instructions+; override for custom logic (e.g. rule-based
+  # evaluators).
   #--
   #: (input: String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base], output: String, ?ground_truth: String?, ?messages: Array[Riffer::Messages::Base]) -> Riffer::Evals::Result
   def evaluate(input:, output:, ground_truth: nil, messages: [])
@@ -84,12 +71,6 @@ class Riffer::Evals::Evaluator
 
   private
 
-  # Formats the input for the judge.
-  #
-  # String inputs are passed through as-is.
-  # Array inputs (message hashes or Message objects) are formatted
-  # as labeled role/content pairs separated by blank lines.
-  #
   #--
   #: (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> String
   def format_input(input)
@@ -122,8 +103,7 @@ class Riffer::Evals::Evaluator
     end
   end
 
-  # Helper to build a Result object.
-  #
+  # Builds a Result for this evaluator.
   #--
   #: (score: Float, ?reason: String?, ?metadata: Hash[Symbol, untyped]) -> Riffer::Evals::Result
   def result(score:, reason: nil, metadata: {})

data/lib/riffer/evals/evaluator_runner.rb

@@ -3,10 +3,6 @@
 
 # Orchestrates running evaluators against an agent across multiple scenarios.
 #
-# Accepts an agent class, a list of scenarios, and evaluator classes.
-# Generates agent output for each scenario and runs all evaluators,
-# returning a RunResult with per-scenario details and aggregate scores.
-#
 #   result = Riffer::Evals::EvaluatorRunner.run(
 #     agent: MyAgent,
 #     scenarios: [
@@ -18,20 +14,14 @@
 #
 #   result.scores   # => { AnswerRelevancyEvaluator => 0.85 }
 #
-class Riffer::Evals::EvaluatorRunner
-  # Runs evaluators against an agent for the given scenarios.
-  #
-  # [agent] an Agent subclass (not an instance).
-  # [scenarios] array of hashes with +:input+, optional +:ground_truth+, and optional +:context+.
-  # [evaluators] array of Evaluator subclasses to run against each scenario.
-  # [context] optional hash passed to +agent.generate+. Per-scenario +:context+ takes precedence.
-  #
-  # Raises Riffer::ArgumentError if agent is not a Riffer::Agent subclass
-  # or any eval is not a Riffer::Evals::Evaluator subclass.
-  #
+module Riffer::Evals::EvaluatorRunner
+  extend self
+
+  # Runs evaluators against an agent for the given scenarios. Raises
+  # Riffer::ArgumentError on an invalid agent or evaluator.
   #--
   #: (agent: singleton(Riffer::Agent), scenarios: Array[Hash[Symbol, untyped]], evaluators: Array[singleton(Riffer::Evals::Evaluator)], ?context: Hash[Symbol, untyped]?) -> Riffer::Evals::RunResult
-  def self.run(agent:, scenarios:, evaluators:, context: nil)
+  def run(agent:, scenarios:, evaluators:, context: nil)
     validate_agent!(agent)
     validate_evaluators!(evaluators)
 
@@ -42,9 +32,11 @@ class Riffer::Evals::EvaluatorRunner
     Riffer::Evals::RunResult.new(scenario_results: scenario_results)
   end
 
+  private
+
   #--
   #: (singleton(Riffer::Agent)) -> void
-  private_class_method def self.validate_agent!(agent)
+  def validate_agent!(agent)
     return if agent.is_a?(Class) && agent < Riffer::Agent
 
     raise Riffer::ArgumentError, "agent must be a subclass of Riffer::Agent, got #{agent.inspect}"
@@ -52,7 +44,7 @@ class Riffer::Evals::EvaluatorRunner
 
   #--
   #: (Array[singleton(Riffer::Evals::Evaluator)]) -> void
-  private_class_method def self.validate_evaluators!(evaluators)
+  def validate_evaluators!(evaluators)
     evaluators.each do |evaluator_class|
       next if evaluator_class.is_a?(Class) && evaluator_class < Riffer::Evals::Evaluator
 
@@ -62,7 +54,7 @@ class Riffer::Evals::EvaluatorRunner
 
   #--
   #: (agent: singleton(Riffer::Agent), scenario: Hash[Symbol, untyped], evaluators: Array[singleton(Riffer::Evals::Evaluator)], ?context: Hash[Symbol, untyped]?) -> Riffer::Evals::ScenarioResult
-  private_class_method def self.run_scenario(agent:, scenario:, evaluators:, context: nil)
+  def run_scenario(agent:, scenario:, evaluators:, context: nil)
     input = scenario[:input]
     ground_truth = scenario[:ground_truth]
     resolved_context = scenario[:context] || context

data/lib/riffer/evals/judge.rb

@@ -3,21 +3,8 @@
 
 require "json"
 
-# Executes LLM-as-judge evaluations using the provider infrastructure.
-#
-# The Judge class handles calling an LLM to evaluate agent outputs
-# and parsing the structured response. It uses tool calling internally
-# to get guaranteed structured output from the judge model.
-#
-#   judge = Riffer::Evals::Judge.new(model: "anthropic/claude-opus-4-5-20251101")
-#   result = judge.evaluate(
-#     instructions: "Assess answer relevancy...",
-#     input: "What is Ruby?",
-#     output: "Ruby is a programming language."
-#   )
-#   result[:score]  # => 0.85
-#   result[:reason] # => "The response is relevant..."
-#
+# Executes LLM-as-judge evaluations, using tool calling internally to get
+# structured output from the judge model.
 class Riffer::Evals::Judge
   # @rbs @provider_options: Hash[Symbol, untyped]
   # @rbs @provider_instance: Riffer::Providers::Base?
@@ -44,8 +31,7 @@ class Riffer::Evals::Judge
   # The model string (provider/model format).
   attr_reader :model #: String
 
-  # Initializes a new judge.
-  #
+  # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   #--
   #: (model: String, ?provider_options: Hash[Symbol, untyped]) -> void
   def initialize(model:, provider_options: {})
@@ -58,14 +44,7 @@ class Riffer::Evals::Judge
     @provider_options = provider_options
   end
 
-  # Evaluates using the configured LLM.
-  #
-  # Composes system and user messages from the semantic fields:
-  # [instructions] evaluation criteria and scoring rubric.
-  # [input] the original input/question.
-  # [output] the agent's response to evaluate.
-  # [ground_truth] optional reference answer for comparison.
-  #
+  # Evaluates an input/output pair using the configured LLM.
   #--
   #: (instructions: String, input: String, output: String, ?ground_truth: String?) -> Hash[Symbol, untyped]
   def evaluate(instructions:, input:, output:, ground_truth: nil)

data/lib/riffer/evals/result.rb

@@ -2,20 +2,6 @@
 # rbs_inline: enabled
 
 # Represents the result of a single evaluation.
-#
-# Contains the score, reason, and metadata from running an evaluator.
-#
-#   result = Riffer::Evals::Result.new(
-#     evaluator: AnswerRelevancyEvaluator,
-#     score: 0.85,
-#     reason: "The response addresses the question directly.",
-#     higher_is_better: true
-#   )
-#
-#   result.score           # => 0.85
-#   result.evaluator       # => AnswerRelevancyEvaluator
-#   result.higher_is_better # => true
-#
 class Riffer::Evals::Result
   # The evaluator class that produced this result.
   attr_reader :evaluator #: singleton(Riffer::Evals::Evaluator)
@@ -32,10 +18,7 @@ class Riffer::Evals::Result
   # Whether higher scores are better for this evaluator.
   attr_reader :higher_is_better #: bool
 
-  # Initializes a new evaluation result.
-  #
-  # Raises Riffer::ArgumentError if score is not between 0.0 and 1.0.
-  #
+  # Raises Riffer::ArgumentError if +score+ is not between 0.0 and 1.0.
   #--
   #: (evaluator: singleton(Riffer::Evals::Evaluator), score: Float, ?reason: String?, ?metadata: Hash[Symbol, untyped], ?higher_is_better: bool) -> void
   def initialize(evaluator:, score:, reason: nil, metadata: {}, higher_is_better: true)

data/lib/riffer/evals/run_result.rb

@@ -2,21 +2,10 @@
 # rbs_inline: enabled
 
 # Represents the complete result of an evaluation run across multiple scenarios.
-#
-# Contains per-scenario results and provides aggregate scores.
-#
-#   run_result = Riffer::Evals::RunResult.new(
-#     scenario_results: [scenario_result1, scenario_result2]
-#   )
-#
-#   run_result.scores   # => { MyEvaluator => 0.85 }
-#
 class Riffer::Evals::RunResult
   # Per-scenario evaluation results.
   attr_reader :scenario_results #: Array[Riffer::Evals::ScenarioResult]
 
-  # Initializes a new run result.
-  #
   #--
   #: (scenario_results: Array[Riffer::Evals::ScenarioResult]) -> void
   def initialize(scenario_results:)

data/lib/riffer/evals/scenario_result.rb

@@ -2,18 +2,6 @@
 # rbs_inline: enabled
 
 # Represents the result of evaluating a single scenario.
-#
-# Contains the input, output, ground truth, and individual evaluator results.
-#
-#   scenario_result = Riffer::Evals::ScenarioResult.new(
-#     input: "What is Ruby?",
-#     output: "A programming language.",
-#     ground_truth: "A programming language",
-#     results: [result1, result2]
-#   )
-#
-#   scenario_result.scores  # => { MyEvaluator => 0.85 }
-#
 class Riffer::Evals::ScenarioResult
   # The input that was evaluated.
   attr_reader :input #: String
@@ -30,8 +18,6 @@ class Riffer::Evals::ScenarioResult
   # The full message history from the agent conversation.
   attr_reader :messages #: Array[Riffer::Messages::Base]
 
-  # Initializes a new scenario result.
-  #
   #--
   #: (input: String, output: String, ground_truth: String?, results: Array[Riffer::Evals::Result], ?messages: Array[Riffer::Messages::Base]) -> void
   def initialize(input:, output:, ground_truth:, results:, messages: [])

data/lib/riffer/evals.rb

@@ -1,11 +1,5 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Evals provides LLM-as-judge evaluation capabilities.
-#
-# Evals allow you to measure the quality of agent outputs using
-# configurable evaluators and scenarios.
-#
-# See Riffer::Evals::Evaluator, Riffer::Evals::EvaluatorRunner, and Riffer::Evals::RunResult.
 module Riffer::Evals
 end

data/lib/riffer/guardrail.rb

@@ -3,8 +3,6 @@
 
 # Base class for guardrails that process input and output in the agent pipeline.
 #
-# Subclass this to create custom guardrails:
-#
 #   class MyGuardrail < Riffer::Guardrail
 #     def process_input(messages, context:)
 #       # Return pass(messages), transform(modified_messages), or block(reason)
@@ -17,27 +15,16 @@
 #     end
 #   end
 class Riffer::Guardrail
-  # Processes input messages before they are sent to the LLM.
-  #
-  # Override this method in subclasses to implement input processing.
-  #
-  # [messages] the input messages.
-  # [context] optional context passed to the agent.
-  #
+  # Processes input messages before they're sent to the LLM; override in
+  # subclasses.
   #--
   #: (Array[Riffer::Messages::Base], context: untyped) -> Riffer::Guardrails::Result
   def process_input(messages, context:)
     pass(messages)
   end
 
-  # Processes output response after it is received from the LLM.
-  #
-  # Override this method in subclasses to implement output processing.
-  #
-  # [response] the LLM response.
-  # [messages] the conversation messages.
-  # [context] optional context passed to the agent.
-  #
+  # Processes the output response after it's received from the LLM; override in
+  # subclasses.
   #--
   #: (Riffer::Messages::Assistant, messages: Array[Riffer::Messages::Base], context: untyped) -> Riffer::Guardrails::Result
   def process_output(response, messages:, context:)
@@ -47,9 +34,6 @@ class Riffer::Guardrail
   protected
 
   # Creates a pass result that continues with unchanged data.
-  #
-  # [data] the original data to pass through.
-  #
   #--
   #: (untyped) -> Riffer::Guardrails::Result
   def pass(data)
@@ -57,9 +41,6 @@ class Riffer::Guardrail
   end
 
   # Creates a transform result that continues with transformed data.
-  #
-  # [data] the transformed data.
-  #
   #--
   #: (untyped) -> Riffer::Guardrails::Result
   def transform(data)
@@ -67,10 +48,6 @@ class Riffer::Guardrail
   end
 
   # Creates a block result that halts execution.
-  #
-  # [reason] the reason for blocking.
-  # [metadata] optional additional information.
-  #
   #--
   #: (String, ?metadata: Hash[Symbol, untyped]?) -> Riffer::Guardrails::Result
   def block(reason, metadata: nil)

data/lib/riffer/guardrails/modification.rb

@@ -2,10 +2,6 @@
 # rbs_inline: enabled
 
 # Records a guardrail transformation event.
-#
-# When a guardrail transforms data (via +transform+), a Modification is
-# created to record which guardrail made the change, in which phase, and
-# which message indices were affected.
 class Riffer::Guardrails::Modification
   # The guardrail class that transformed data.
   attr_reader :guardrail #: singleton(Riffer::Guardrail)
@@ -16,12 +12,6 @@ class Riffer::Guardrails::Modification
   # The indices of messages that were changed.
   attr_reader :message_indices #: Array[Integer]
 
-  # Creates a new modification record.
-  #
-  # [guardrail] the guardrail class that transformed.
-  # [phase] :before or :after.
-  # [message_indices] indices of changed messages.
-  #
   #--
   #: (guardrail: singleton(Riffer::Guardrail), phase: Symbol, message_indices: Array[Integer]) -> void
   def initialize(guardrail:, phase:, message_indices:)

data/lib/riffer/guardrails/result.rb

@@ -1,18 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents the result of a guardrail execution.
-#
-# Results can be one of three types:
-# - pass: Continue with the original data unchanged
-# - transform: Continue with transformed data
-# - block: Halt execution with a reason
-#
-# Use the factory methods to create results:
-#
-#   Result.pass(data)
-#   Result.transform(data)
-#   Result.block(reason, metadata: nil)
+# Represents the result of a guardrail execution: +pass+ (continue unchanged),
+# +transform+ (continue with changed data), or +block+ (halt with a reason).
 class Riffer::Guardrails::Result
   TYPES = %i[pass transform block].freeze #: Array[Symbol]
 
@@ -27,9 +17,6 @@ class Riffer::Guardrails::Result
 
   class << self
     # Creates a pass result that continues with unchanged data.
-    #
-    # [data] the original data to pass through.
-    #
     #--
     #: (untyped) -> Riffer::Guardrails::Result
     def pass(data)
@@ -37,9 +24,6 @@ class Riffer::Guardrails::Result
     end
 
     # Creates a transform result that continues with transformed data.
-    #
-    # [data] the transformed data.
-    #
     #--
     #: (untyped) -> Riffer::Guardrails::Result
     def transform(data)
@@ -47,10 +31,6 @@ class Riffer::Guardrails::Result
     end
 
     # Creates a block result that halts execution.
-    #
-    # [reason] the reason for blocking.
-    # [metadata] optional additional information.
-    #
     #--
     #: (String, ?metadata: Hash[Symbol, untyped]?) -> Riffer::Guardrails::Result
     def block(reason, metadata: nil)
@@ -58,14 +38,7 @@ class Riffer::Guardrails::Result
     end
   end
 
-  # Creates a new result.
-  #
-  # [type] the result type (:pass, :transform, or :block).
-  # [data] the data or reason.
-  # [metadata] optional metadata for block results.
-  #
-  # Raises Riffer::ArgumentError if the result type is invalid.
-  #
+  # Raises Riffer::ArgumentError if +type+ is not :pass, :transform, or :block.
   #--
   #: (Symbol, untyped, ?metadata: Hash[Symbol, untyped]?) -> void
   def initialize(type, data, metadata: nil)