riffer 0.48.0 → 0.50.0

data/lib/riffer/config.rb

@@ -1,365 +1,27 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Configuration for the Riffer framework.
 class Riffer::Config
-  AmazonBedrock = Struct.new(:api_token, :region, :client)
-  Anthropic = Struct.new(:api_key, :client)
-  AzureOpenAI = Struct.new(:api_key, :endpoint, :client)
-  Gemini = Struct.new(:api_key, :client)
-  OpenAI = Struct.new(:api_key, :base_url, :client)
-  OpenRouter = Struct.new(:api_key, :client)
-  Evals = Struct.new(:judge_model)
-  Mcp = Struct.new(:credentials, :discovery_runner)
-
-  # Skills-related global configuration.
-  class Skills
-    # 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) # @dynamic default_activate_tool
-
-    # Default skills backend for agents that declare a +skills+ block without
-    # one; defaults to +nil+.
-    attr_reader :default_backend #: (Riffer::Skills::Backend | Proc)? # @dynamic default_backend
-
-    #--
-    #: () -> void
-    def initialize
-      @default_activate_tool = Riffer::Skills::ActivateTool
-      @default_backend = nil
-    end
-
-    # Sets the default skill activation tool class. Raises Riffer::ArgumentError
-    # on an invalid value.
-    #--
-    #: (singleton(Riffer::Tool)) -> void
-    def default_activate_tool=(value)
-      unless value.is_a?(Class) && value < Riffer::Tool
-        raise Riffer::ArgumentError,
-              "default_activate_tool must be a Riffer::Tool subclass"
-      end
-
-      @default_activate_tool = value
-    end
-
-    # Sets the default skills backend. Raises Riffer::ArgumentError on an
-    # invalid value.
-    #--
-    #: ((Riffer::Skills::Backend | Proc)?) -> void
-    def default_backend=(value)
-      valid = value.nil? || value.is_a?(Riffer::Skills::Backend) || value.is_a?(Proc)
-      unless valid
-        raise Riffer::ArgumentError,
-              "default_backend must be a Riffer::Skills::Backend instance, Proc, or nil"
-      end
-
-      @default_backend = value
-    end
-  end
-
-  # Tracing-related global configuration.
-  class Tracing
-    # Whether riffer emits OTEL spans; defaults to +true+, a no-op until a
-    # host wires an OTEL SDK.
-    attr_reader :enabled #: bool # @dynamic enabled
-
-    # Whether LLM-call spans capture full message content
-    # (<tt>gen_ai.input.messages</tt>, <tt>gen_ai.output.messages</tt>,
-    # <tt>gen_ai.system_instructions</tt>); defaults to +false+ — message
-    # content routinely carries sensitive data.
-    attr_reader :capture_messages #: bool # @dynamic capture_messages
-
-    # The backend riffer routes spans through; defaults to +nil+, a no-op.
-    # Riffer auto-detects no backend; assigning one is opt-in.
-    attr_reader :backend #: untyped # @dynamic backend
-
-    #--
-    #: () -> void
-    def initialize
-      @enabled = true
-      @capture_messages = false
-      @backend = nil
-    end
-
-    # Sets the enabled flag, coercing boolean-ish values so an env-var
-    # +"false"+ (truthy in Ruby) doesn't silently keep tracing on. Raises
-    # Riffer::ArgumentError on an unrecognized value.
-    #--
-    #: (untyped) -> void
-    def enabled=(value)
-      @enabled = Riffer::Helpers::Boolean.coerce(value, attribute: "enabled")
-    end
-
-    # Sets the capture_messages flag, coercing boolean-ish values so an
-    # env-var +"false"+ (truthy in Ruby) doesn't silently enable content
-    # capture. Raises Riffer::ArgumentError on an unrecognized value.
-    #--
-    #: (untyped) -> void
-    def capture_messages=(value)
-      @capture_messages = Riffer::Helpers::Boolean.coerce(value, attribute: "capture_messages")
-    end
-
-    # Sets the tracing backend riffer routes spans through. Raises
-    # Riffer::ArgumentError unless the value is +nil+ or responds to the full
-    # delegated contract: +in_span+, +current_context+, and +with_context+.
-    #--
-    #: (untyped) -> void
-    def backend=(value)
-      contract = %i[in_span current_context with_context]
-      unless value.nil? || contract.all? { |method| value.respond_to?(method) }
-        raise Riffer::ArgumentError, "tracing backend must respond to #in_span, #current_context, and #with_context"
-      end
-
-      @backend = value
-      Riffer::Tracing.reset!
-    end
-  end
-
-  # File-attachment-download policy for +Riffer::Messages::User::FilePart+ URL sources
-  class Files
-    # Allow file attachments to be downloaded to send to providers.
-    attr_reader :allow_downloads #: bool # @dynamic allow_downloads
-    # Maximum file size to download before failing.
-    attr_reader :max_bytes #: Integer # @dynamic max_bytes
-    # Maximum amount of time to spend downloading a file before failing.
-    attr_reader :timeout #: Integer # @dynamic timeout
-    # Maximum number of files to include in an individual message.
-    attr_reader :max_per_message #: Integer? # @dynamic max_per_message
-    # Execution pattern for downloading files.
-    attr_reader :runner #: Riffer::Runner # @dynamic runner
-    # The object used to fetch a URL source's bytes
-    attr_reader :downloader #: untyped # @dynamic downloader
-
-    #--
-    #: () -> void
-    def initialize
-      @allow_downloads = false
-      @max_bytes = 3_500_000
-      @timeout = 60
-      @max_per_message = nil
-      @runner = Riffer::Runner::Sequential.new
-      @downloader = Riffer::Files::Downloader.new
-    end
-
-    # Sets the allow_downloads flag, coercing boolean-ish values so an env-var
-    # +"false"+ (truthy in Ruby) doesn't silently enable downloads.  Raises
-    # Riffer::ArgumentError on an unrecognized value.
-    #--
-    #: (untyped) -> void
-    def allow_downloads=(value)
-      @allow_downloads = Riffer::Helpers::Boolean.coerce(value, attribute: "allow_downloads")
-    end
-
-    # Sets max_bytes, provided value is a positive integer.
-    # Raises Riffer::ArgumentError if value is not an Integer or less than or equal to 0.
-    #--
-    #: (untyped) -> void
-    def max_bytes=(value)
-      raise Riffer::ArgumentError, "max_bytes must be a positive integer" unless value.is_a?(Integer) && value.positive?
-
-      @max_bytes = value
-    end
-
-    # Sets timeout, provided value is a positive integer.
-    # Raises Riffer::ArgumentError if value is not an Integer or is less than or equal to 0.
-    #--
-    #: (untyped) -> void
-    def timeout=(value)
-      raise Riffer::ArgumentError, "timeout must be a positive integer" unless value.is_a?(Integer) && value.positive?
-
-      @timeout = value
-    end
-
-    # Sets max_per_message, provided value is either nil or a positive integer.
-    # Raises Riffer::ArgumentError if value is not an Integer or nil, or is less than or equal to 0.
-    #--
-    #: (untyped) -> void
-    def max_per_message=(value)
-      if value.is_a?(Integer) && value.positive?
-        @max_per_message = value
-      elsif value.nil?
-        @max_per_message = nil
-      else
-        raise Riffer::ArgumentError, "max_per_message must be a positive integer or nil"
-      end
-    end
-
-    # Sets the runner used to process file downloads, provided value is a Riffer::Runner.
-    # Raises Riffer::ArgumentError if value is not a Riffer::Runner.
-    #--
-    #: (untyped) -> void
-    def runner=(value)
-      valid = value.is_a?(Riffer::Runner)
-      raise Riffer::ArgumentError, "runner must be a Riffer::Runner instance" unless valid
-
-      @runner = value
-    end
-
-    # Sets the object used to download bytes from a URL.
-    # Raises Riffer::ArgumentError if value does not respond to +#call+.
-    #--
-    #: (untyped) -> void
-    def downloader=(value)
-      raise Riffer::ArgumentError, "downloader must respond to #call" unless value.respond_to?(:call)
-
-      @downloader = value
-    end
-  end
-
-  # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer
-  # ships no price table, so an unconfigured model carries no cost.
-  class Pricing
-    # @rbs @rates: Hash[String, Riffer::Config::Pricing::Rates]
-
-    # Per-million-token rates for one model's four token buckets. +cache_read+
-    # and +cache_write+ fall back to the +input+ rate when unset.
-    class Rates
-      # Input rate per million tokens.
-      attr_reader :input #: Float # @dynamic input
-
-      # Output rate per million tokens.
-      attr_reader :output #: Float # @dynamic output
-
-      # Cache-read rate per million tokens.
-      attr_reader :cache_read #: Float? # @dynamic cache_read
-
-      # Cache-write rate per million tokens.
-      attr_reader :cache_write #: Float? # @dynamic cache_write
-
-      #--
-      #: (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
-      def initialize(input:, output:, cache_read: nil, cache_write: nil)
-        @input = input
-        @output = output
-        @cache_read = cache_read
-        @cache_write = cache_write
-      end
-
-      # Returns the cost for the given token counts.
-      #--
-      #: (input_tokens: Integer, output_tokens: Integer, ?cache_read_tokens: Integer?, ?cache_write_tokens: Integer?) -> Float
-      def cost_for(input_tokens:, output_tokens:, cache_read_tokens: nil, cache_write_tokens: nil)
-        read = cache_read_tokens || 0
-        write = cache_write_tokens || 0
-        uncached = input_tokens - read - write
-        uncached = 0 if uncached.negative?
-
-        per_million = (uncached * input) +
-                      (read * (cache_read || input)) +
-                      (write * (cache_write || input)) +
-                      (output_tokens * output)
-        per_million / 1_000_000.0
-      end
-    end
-
-    #--
-    #: () -> void
-    def initialize
-      @rates = {}
-    end
-
-    # Registers per-million-token rates for a +provider/model+ id/s. Raises
-    # Riffer::ArgumentError on a malformed id or a negative/non-numeric rate.
-    #--
-    #: ((String | Array[String]), input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
-    def set(models, input:, output:, cache_read: nil, cache_write: nil)
-      ids = models.is_a?(Array) ? models : [models]
-      raise Riffer::ArgumentError, "at least one model id is required" if ids.empty?
-
-      ids.each { |id| validate_model!(id) }
-
-      rates = Rates.new(
-        input: coerce_rate(input, "input"),
-        output: coerce_rate(output, "output"),
-        cache_read: coerce_optional_rate(cache_read, "cache_read"),
-        cache_write: coerce_optional_rate(cache_write, "cache_write"),
-      )
-      ids.each { |id| @rates[id] = rates }
-    end
-
-    # Returns the rates registered for a +provider/model+ id.
-    #--
-    #: (String) -> Riffer::Config::Pricing::Rates?
-    def rates_for(model)
-      @rates[model]
-    end
-
-    # Returns true when no rates are registered.
-    #--
-    #: () -> bool
-    def empty?
-      @rates.empty?
-    end
-
-    private
-
-    #--
-    #: (String) -> void
-    def validate_model!(model)
-      segments = model.to_s.split("/", 2)
-      valid = segments.length == 2 && segments.none? { |segment| segment.strip.empty? }
-      return if valid
-
-      raise Riffer::ArgumentError,
-            "pricing model id must be in \"provider/model\" form, got #{model.inspect}"
-    end
-
-    #--
-    #: (untyped, String) -> Float
-    def coerce_rate(value, attribute)
-      number = value
-      float = value.is_a?(Numeric) ? number.to_f : nil #: Float?
-      unless float&.finite? && float >= 0
-        raise Riffer::ArgumentError,
-              "#{attribute} rate must be a non-negative number, got #{value.inspect}"
-      end
-
-      float
-    end
-
-    #--
-    #: (untyped, String) -> Float?
-    def coerce_optional_rate(value, attribute)
-      return nil if value.nil?
-
-      coerce_rate(value, attribute)
-    end
-  end
-
   VALID_MESSAGE_ID_STRATEGIES = %i[none uuid uuidv7].freeze
 
-  # Amazon Bedrock configuration.
   attr_reader :amazon_bedrock #: Riffer::Config::AmazonBedrock # @dynamic amazon_bedrock
 
-  # Anthropic configuration.
   attr_reader :anthropic #: Riffer::Config::Anthropic # @dynamic anthropic
 
-  # Azure OpenAI configuration.
   attr_reader :azure_openai #: Riffer::Config::AzureOpenAI # @dynamic azure_openai
 
-  # Google Gemini configuration.
   attr_reader :gemini #: Riffer::Config::Gemini # @dynamic gemini
 
-  # OpenAI configuration.
   attr_reader :openai #: Riffer::Config::OpenAI # @dynamic openai
 
-  # OpenRouter configuration.
   attr_reader :openrouter #: Riffer::Config::OpenRouter # @dynamic openrouter
 
-  # Evals configuration.
   attr_reader :evals #: Riffer::Config::Evals # @dynamic evals
 
-  # 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 # @dynamic mcp
 
-  # 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) # @dynamic tool_runtime
 
-  # 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)
@@ -373,24 +35,18 @@ class Riffer::Config
     @tool_runtime = value
   end
 
-  # Skills-related global configuration.
   attr_reader :skills #: Riffer::Config::Skills # @dynamic skills
 
-  # Tracing-related global configuration.
   attr_reader :tracing #: Riffer::Config::Tracing # @dynamic tracing
 
   attr_reader :files #: Riffer::Config::Files # @dynamic files
 
-  # Consumer-configured per-model token pricing.
   attr_reader :pricing #: Riffer::Config::Pricing # @dynamic pricing
 
-  # 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.
+  # When not +:none+, seeded messages passed to +Riffer::Agent#generate+ must
+  # carry their own +id+.
   attr_reader :message_id_strategy #: Symbol # @dynamic message_id_strategy
 
-  # Sets the message id strategy. Raises Riffer::ArgumentError unless the value
-  # is +:none+, +:uuid+, or +:uuidv7+.
   #--
   #: (Symbol) -> void
   def message_id_strategy=(value)
@@ -401,20 +57,6 @@ class Riffer::Config
     @message_id_strategy = value
   end
 
-  # 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 # @dynamic experimental_history_healing
-
-  # 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)
-    @experimental_history_healing = Riffer::Helpers::Boolean.coerce(value, attribute: "experimental_history_healing")
-  end
-
   #--
   #: () -> void
   def initialize
@@ -425,13 +67,12 @@ class Riffer::Config
     @openai = OpenAI.new
     @openrouter = OpenRouter.new
     @evals = Evals.new
-    @mcp = Mcp.new(credentials: nil, discovery_runner: Riffer::Runner::Sequential.new)
+    @mcp = Mcp.new
     @tool_runtime = Riffer::Tools::Runtime::Inline.new
     @skills = Skills.new
     @tracing = Tracing.new
     @files = Files.new
     @pricing = Pricing.new
     @message_id_strategy = :none
-    @experimental_history_healing = false
   end
 end

data/lib/riffer/evals/evaluator.rb

@@ -1,16 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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..."
-#     higher_is_better true
-#     judge_model "anthropic/claude-opus-4-5-20251101"
-#   end
-#
 class Riffer::Evals::Evaluator
   # @rbs self.@instructions: String?
   # @rbs self.@higher_is_better: bool?
@@ -18,12 +8,9 @@ class Riffer::Evals::Evaluator
   # @rbs self.@identifier: String?
   # @rbs @judge: Riffer::Evals::Judge?
 
-  # The identifier for an anonymous evaluator class.
   DEFAULT_IDENTIFIER = "riffer/judge" #: String
 
   class << self
-    # Gets or sets the evaluation instructions (criteria and scoring rubric).
-    #
     #--
     #: (?String?) -> String?
     def instructions(value = nil)
@@ -32,8 +19,6 @@ class Riffer::Evals::Evaluator
       @instructions = value.to_s
     end
 
-    # Gets or sets whether higher scores are better.
-    #
     #--
     #: (?bool?) -> bool
     def higher_is_better(value = nil)
@@ -46,8 +31,6 @@ class Riffer::Evals::Evaluator
       @higher_is_better = value
     end
 
-    # Gets or sets the judge model for LLM-as-judge evaluations.
-    #
     #--
     #: (?String?) -> String?
     def judge_model(value = nil)
@@ -56,10 +39,6 @@ class Riffer::Evals::Evaluator
       @judge_model = value.to_s
     end
 
-    # Gets or sets the evaluator identifier, sent as the +agent+ tag on judge
-    # calls. Defaults to the snake_cased class name, or DEFAULT_IDENTIFIER for
-    # an anonymous class.
-    #
     #--
     #: (?String?) -> String
     def identifier(value = nil)
@@ -70,18 +49,15 @@ class Riffer::Evals::Evaluator
 
     private
 
-    # Anonymous classes derive an empty identifier.
     #--
     #: () -> String
     def derived_identifier
+      # Anonymous classes derive an empty identifier.
       derived = Riffer::Helpers::Identifier.for(self)
       derived.empty? ? DEFAULT_IDENTIFIER : derived
     end
   end
 
-  # 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: [])
@@ -120,9 +96,6 @@ class Riffer::Evals::Evaluator
 
   protected
 
-  # Returns a Judge instance configured for this evaluator. Its calls carry
-  # the +kind+ (+"judge"+) and +agent+ (the evaluator identifier) tags.
-  #
   #--
   #: () -> Riffer::Evals::Judge
   def judge
@@ -137,7 +110,6 @@ class Riffer::Evals::Evaluator
     end
   end
 
-  # Builds a Result for this evaluator.
   #--
   #: (score: Float, ?reason: String?, ?metadata: Hash[Symbol, untyped], ?token_usage: Riffer::Providers::TokenUsage?) -> Riffer::Evals::Result
   def result(score:, reason: nil, metadata: {}, token_usage: nil)

data/lib/riffer/evals/evaluator_runner.rb

@@ -1,24 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Orchestrates running evaluators against an agent across multiple scenarios.
-#
-#   result = Riffer::Evals::EvaluatorRunner.run(
-#     agent: MyAgent,
-#     scenarios: [
-#       { input: "What is Ruby?", ground_truth: "A programming language" },
-#       { input: "What is Python?" }
-#     ],
-#     evaluators: [AnswerRelevancyEvaluator]
-#   )
-#
-#   result.scores   # => { AnswerRelevancyEvaluator => 0.85 }
-#
 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 run(agent:, scenarios:, evaluators:, context: nil)

data/lib/riffer/evals/judge.rb

@@ -3,14 +3,11 @@
 
 require "json"
 
-# Executes LLM-as-judge evaluations, using tool calling internally to get
-# structured output from the judge model.
 class Riffer::Evals::Judge
   # @rbs @provider_instance: Riffer::Providers::Base?
   # @rbs @provider_name: String?
   # @rbs @model_name: String?
 
-  # Internal tool for structured evaluation output.
   class EvaluationTool < Riffer::Tool
     identifier "evaluation"
     description "Submit your evaluation score and reasoning"
@@ -27,13 +24,9 @@ class Riffer::Evals::Judge
     end
   end
 
-  # The model string (provider/model format).
   attr_reader :model #: String # @dynamic model
-
-  # The tags passed to the provider on every call.
   attr_reader :tags #: Hash[String, String] # @dynamic tags
 
-  # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   #--
   #: (model: String, ?tags: Hash[String, String]) -> void
   def initialize(model:, tags: {})
@@ -46,7 +39,6 @@ class Riffer::Evals::Judge
     @tags = tags
   end
 
-  # 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

@@ -1,28 +1,20 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents the result of a single evaluation.
 class Riffer::Evals::Result
-  # The evaluator class that produced this result.
   attr_reader :evaluator #: singleton(Riffer::Evals::Evaluator) # @dynamic evaluator
 
-  # The evaluation score (0.0 to 1.0).
   attr_reader :score #: Float # @dynamic score
 
-  # Human-readable explanation of the score.
   attr_reader :reason #: String? # @dynamic reason
 
-  # Additional metadata from the evaluation.
   attr_reader :metadata #: Hash[Symbol, untyped] # @dynamic metadata
 
-  # Whether higher scores are better for this evaluator.
   attr_reader :higher_is_better #: bool # @dynamic higher_is_better
 
-  # Token usage for the judge call that produced this result, when the
-  # evaluator used an LLM. Nil for rule-based evaluators.
+  # Nil for rule-based evaluators.
   attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
-  # 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, ?token_usage: Riffer::Providers::TokenUsage?) -> void
   def initialize(evaluator:, score:, reason: nil, metadata: {}, higher_is_better: true, token_usage: nil)
@@ -35,8 +27,6 @@ class Riffer::Evals::Result
     @token_usage = token_usage
   end
 
-  # Returns a hash representation of the result.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/evals/run_result.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents the complete result of an evaluation run across multiple scenarios.
 class Riffer::Evals::RunResult
-  # Per-scenario evaluation results.
   attr_reader :scenario_results #: Array[Riffer::Evals::ScenarioResult] # @dynamic scenario_results
 
   #--
@@ -12,8 +10,6 @@ class Riffer::Evals::RunResult
     @scenario_results = scenario_results
   end
 
-  # Returns average scores keyed by evaluator class across all scenarios.
-  #
   #--
   #: () -> Hash[singleton(Riffer::Evals::Evaluator), Float]
   def scores
@@ -35,26 +31,18 @@ class Riffer::Evals::RunResult
     end
   end
 
-  # Returns the summed token usage the agents under test spent across every
-  # scenario, or nil when none reported usage.
-  #
   #--
   #: () -> Riffer::Providers::TokenUsage?
   def token_usage
     scenario_results.filter_map(&:token_usage).reduce(:+)
   end
 
-  # Returns the summed token usage across every scenario's LLM-as-judge
-  # evaluators, or nil when none reported usage.
-  #
   #--
   #: () -> Riffer::Providers::TokenUsage?
   def evaluator_token_usage
     scenario_results.filter_map(&:evaluator_token_usage).reduce(:+)
   end
 
-  # Returns a hash representation of the run result.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h