riffer 0.47.2 → 0.49.0

data/sig/generated/riffer/testing.rbs

@@ -1,58 +1,22 @@
 # Generated from lib/riffer/testing.rb with RBS::Inline
 
-# Builds throwaway agents and tools a test suite can resolve by identifier or
-# constant name, and removes them again. Require <tt>riffer/testing/rspec</tt>
-# or <tt>riffer/testing/minitest</tt> to get +stub_agent+/+stub_tool+ in every
-# example plus per-test cleanup; otherwise include this module and call +reset!+
-# from your own teardown, or call the methods on the module directly.
-#
-# Tracking is not synchronized — stub from a single-threaded test, before
-# concurrent lookups begin.
 module Riffer::Testing
   self.@registrations: Array[[ Class, String? ]]?
 
   CONST_NAME_PATTERN: Regexp
 
-  # Builds an agent class, evaluates the optional body in it, and makes it
-  # resolvable until the next +reset!+. A +name+ assigns a top-level constant
-  # and derives the identifier; the body may set +identifier+ like any other
-  # agent config.
-  #
-  #   agent = stub_agent("SupportAgent") { model "mock/gpt-5-mini" }
-  #
-  # Raises Riffer::ArgumentError when the constant is already defined or the
-  # stub ends up with no identifier, and Riffer::DuplicateIdentifierError when
-  # another agent already holds the identifier.
-  #
   # --
   # : (?(String | Symbol)?, ?base: singleton(Riffer::Agent)) ?{ () [self: singleton(Riffer::Agent)] -> void } -> singleton(Riffer::Agent)
   def stub_agent: (?(String | Symbol)?, ?base: singleton(Riffer::Agent)) ?{ () [self: singleton(Riffer::Agent)] -> void } -> singleton(Riffer::Agent)
 
-  # Builds a tool class, evaluates the optional body in it, and makes it
-  # resolvable until the next +reset!+. A +name+ assigns a top-level constant
-  # and derives the identifier; the body may set +identifier+ like any other
-  # tool config.
-  #
-  #   tool = stub_tool("KbSearch") { def call(context:, **) = text("stubbed") }
-  #
-  # Raises Riffer::ArgumentError when the constant is already defined or the
-  # stub ends up with no identifier, and Riffer::DuplicateIdentifierError when
-  # another tool already holds the identifier.
-  #
   # --
   # : (?(String | Symbol)?, ?base: singleton(Riffer::Tool)) ?{ () [self: singleton(Riffer::Tool)] -> void } -> singleton(Riffer::Tool)
   def stub_tool: (?(String | Symbol)?, ?base: singleton(Riffer::Tool)) ?{ () [self: singleton(Riffer::Tool)] -> void } -> singleton(Riffer::Tool)
 
-  # Removes every stub built since the last reset — its registration and any
-  # constant it created — newest first, and forgets them. A no-op when nothing
-  # has been stubbed.
   # --
   # : () -> void
   def reset!: () -> void
 
-  # The stub classes awaiting cleanup. Lives on the module rather than the
-  # caller so an including test case and a direct
-  # <tt>Riffer::Testing.stub_*</tt> call share one list.
   # --
   # : () -> Array[[Class, String?]]
   def self.registrations: () -> Array[[ Class, String? ]]
@@ -67,8 +31,6 @@ module Riffer::Testing
   # : ((String | Symbol)?) -> String?
   def validate_const_name: ((String | Symbol)?) -> String?
 
-  # A test may have removed or replaced the constant itself, so never clobber
-  # one that no longer points at the stub.
   # --
   # : (String, Class) -> void
   def remove_stub_const: (String, Class) -> void

data/sig/generated/riffer/tool.rbs

@@ -1,53 +1,26 @@
 # Generated from lib/riffer/tool.rb with RBS::Inline
 
-# Base class for all tools in the Riffer framework. Subclasses must implement
-# the +call+ method.
-#
-#   class WeatherLookupTool < Riffer::Tool
-#     description "Provides current weather information for a specified city."
-#
-#     params do
-#       required :city, String, description: "The city to look up"
-#       optional :units, String, default: "celsius"
-#     end
-#
-#     def call(context:, city:, units: nil)
-#       # Implementation
-#     end
-#   end
 class Riffer::Tool
   extend Riffer::Tools::Toolable
 
   extend Riffer::Registrable
 
-  # Executes the tool with the given arguments.
   # --
   # : (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response
   def call: (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response
 
-  # Creates a text response.
-  #
   # --
   # : (untyped) -> Riffer::Tools::Response
   def text: (untyped) -> Riffer::Tools::Response
 
-  # Creates a JSON response.
-  #
   # --
   # : (untyped) -> Riffer::Tools::Response
   def json: (untyped) -> Riffer::Tools::Response
 
-  # Creates an error response.
-  #
   # --
   # : (String, ?type: Symbol) -> Riffer::Tools::Response
   def error: (String, ?type: Symbol) -> Riffer::Tools::Response
 
-  # Executes the tool with validation and timeout, folding every +StandardError+
-  # into an error Response. Anything outside +StandardError+ — an unimplemented
-  # +#call+ above all — still propagates, because a broken tool is a broken
-  # deploy rather than a bad request.
-  #
   # --
   # : (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response
   def call_with_validation: (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response

data/sig/generated/riffer/tools/response.rbs

@@ -1,71 +1,45 @@
 # Generated from lib/riffer/tools/response.rb with RBS::Inline
 
-# Represents the result of a tool execution; every tool's +call+ must return one.
-#
-#   class MyTool < Riffer::Tool
-#     def call(context:, **kwargs)
-#       result = perform_operation
-#       Riffer::Tools::Response.success(result)
-#     rescue MyError => e
-#       Riffer::Tools::Response.error(e.message)
-#     end
-#   end
+# Every tool's +call+ must return one.
 class Riffer::Tools::Response
   @success: bool
 
   VALID_FORMATS: Array[Symbol]
 
-  # The response content.
   attr_reader content: String
 
-  # The error message, or +nil+ on success.
   attr_reader error_message: String?
 
-  # The error type, or +nil+ on success.
   attr_reader error_type: Symbol?
 
-  # The exception an unhandled failure was folded from, or +nil+. Kept out of
-  # every serialized form so it never reaches an LLM or a message payload.
+  # Kept out of every serialized form so it never reaches an LLM or a message
+  # payload.
   attr_reader exception: Exception?
 
-  # Creates a success response.
-  #
-  # Raises Riffer::ArgumentError if format is invalid.
-  #
   # --
   # : (untyped, ?format: Symbol) -> Riffer::Tools::Response
   def self.success: (untyped, ?format: Symbol) -> Riffer::Tools::Response
 
-  # Creates a success response with text format.
-  #
   # --
   # : (untyped) -> Riffer::Tools::Response
   def self.text: (untyped) -> Riffer::Tools::Response
 
-  # Creates a success response with JSON format.
-  #
   # --
   # : (untyped) -> Riffer::Tools::Response
   def self.json: (untyped) -> Riffer::Tools::Response
 
-  # Creates an error response.
-  #
   # --
   # : (String, ?type: Symbol, ?exception: Exception?) -> Riffer::Tools::Response
   def self.error: (String, ?type: Symbol, ?exception: Exception?) -> Riffer::Tools::Response
 
-  # Returns true if the tool execution succeeded.
   # --
   # : () -> bool
   def success?: () -> bool
 
-  # Returns true if the tool execution failed.
   # --
   # : () -> bool
   def error?: () -> bool
 
-  # Returns a hash representation of the response.
-  #
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]

data/sig/generated/riffer/tools/runtime/fibers.rbs

@@ -1,10 +1,5 @@
 # Generated from lib/riffer/tools/runtime/fibers.rb with RBS::Inline
 
-# Executes tool calls concurrently using fibers via the +async+ gem.
-#
-#   class MyAgent < Riffer::Agent
-#     tool_runtime Riffer::Tools::Runtime::Fibers
-#   end
 class Riffer::Tools::Runtime::Fibers < Riffer::Tools::Runtime
   # --
   # : (?max_concurrency: Integer?) -> void

data/sig/generated/riffer/tools/runtime/inline.rbs

@@ -1,6 +1,5 @@
 # Generated from lib/riffer/tools/runtime/inline.rb with RBS::Inline
 
-# Executes tool calls sequentially in the current thread — the default runtime.
 class Riffer::Tools::Runtime::Inline < Riffer::Tools::Runtime
   # --
   # : () -> void

data/sig/generated/riffer/tools/runtime/threaded.rbs

@@ -1,10 +1,5 @@
 # Generated from lib/riffer/tools/runtime/threaded.rb with RBS::Inline
 
-# Executes tool calls concurrently using threads.
-#
-#   class MyAgent < Riffer::Agent
-#     tool_runtime Riffer::Tools::Runtime::Threaded
-#   end
 class Riffer::Tools::Runtime::Threaded < Riffer::Tools::Runtime
   DEFAULT_MAX_CONCURRENCY: Integer
 

data/sig/generated/riffer/tools/runtime.rbs

@@ -1,8 +1,5 @@
 # Generated from lib/riffer/tools/runtime.rb with RBS::Inline
 
-# Handles tool call execution for an agent, composing with a Riffer::Runner for
-# concurrency. Subclass and override +dispatch_tool_call+ to customize dispatch
-# (e.g. HTTP, gRPC).
 class Riffer::Tools::Runtime
   @runner: Riffer::Runner
 
@@ -10,25 +7,11 @@ class Riffer::Tools::Runtime
   # : (runner: Riffer::Runner) -> void
   def initialize: (runner: Riffer::Runner) -> void
 
-  # Executes a batch of tool calls, returning <tt>[tool_call, response]</tt> pairs.
   # --
   # : (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?, ?tags: Hash[String, String]) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
   def execute: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?, ?tags: Hash[String, String]) -> Array[[ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]]
 
-  # Hook wrapping each tool call; override in subclasses to instrument or
-  # customize. Must +yield+ to continue.
-  #
-  #   class InstrumentedRuntime < Riffer::Tools::Runtime::Inline
-  #     private
-  #
-  #     def around_tool_call(tool_call, context:, assistant_message: nil)
-  #       start = Time.now
-  #       result = yield
-  #       Rails.logger.info("Tool #{tool_call.name} took #{Time.now - start}s")
-  #       result
-  #     end
-  #   end
-  #
+  # Overrides must +yield+ and return its Response.
   # --
   # : (Riffer::Messages::Assistant::ToolCall, context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
   def around_tool_call: (Riffer::Messages::Assistant::ToolCall, context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
@@ -39,15 +22,15 @@ class Riffer::Tools::Runtime
   # : (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
   def instrument_tool_call: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { () -> Riffer::Tools::Response } -> [ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]
 
+  # Subclasses override this to dispatch elsewhere (e.g. HTTP, gRPC).
   # --
   # : (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
   def dispatch_tool_call: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
 
   # --
-  # : (String?) -> untyped
-  def parse_arguments: (String?) -> untyped
+  # : (String) -> untyped
+  def parse_arguments: (String) -> untyped
 
-  # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   # --
   # : [R] (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
   def in_tool_span: [R] (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
@@ -56,15 +39,10 @@ class Riffer::Tools::Runtime
   # : (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) -> Hash[String, untyped]
   def tool_span_attributes: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) -> Hash[String, untyped]
 
-  # Maps normalized tags to their namespaced span attribute form. An empty map
-  # yields an empty hash, so merging it is a no-op.
   # --
   # : (Hash[String, String]) -> Hash[String, String]
   def tag_attributes: (Hash[String, String]) -> Hash[String, String]
 
-  # A deliberate error Response is a handled outcome, so its status stays unset.
-  # An error status is reserved for a Response carrying the exception it was
-  # folded from — the tool failed for a reason nobody anticipated.
   # --
   # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
   def record_tool_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Tools::Response) -> void

data/sig/generated/riffer/tools/toolable.rbs

@@ -1,19 +1,5 @@
 # Generated from lib/riffer/tools/toolable.rb with RBS::Inline
 
-# Shared class-level DSL for anything that presents as a tool to an LLM. Extend
-# it to make a class discoverable as a tool; instance-level execution (+call+,
-# +call_with_validation+) lives on Riffer::Tool instead.
-#
-#   class MyTool
-#     extend Riffer::Tools::Toolable
-#
-#     description "Does something useful"
-#
-#     params do
-#       required :input, String
-#     end
-#   end
-#
 # @rbs module-self Module
 module Riffer::Tools::Toolable : Module
   @kind: Symbol?
@@ -30,69 +16,46 @@ module Riffer::Tools::Toolable : Module
 
   DEFAULT_TIMEOUT: Integer
 
-  # Tracks all classes that extend Toolable.
-  #
   # --
   # : (Module) -> void
   def self.extended: (Module) -> void
 
-  # Returns all classes that have extended Toolable.
-  #
   # --
   # : () -> Array[Module]
   def self.all: () -> Array[Module]
 
-  # Gets or sets the tool description.
-  #
   # --
   # : (?String?) -> String?
   def description: (?String?) -> String?
 
-  # Gets or sets the tool identifier/name.
-  #
   # --
   # : (?String?) -> String
   def identifier: (?String?) -> String
 
-  # Alias for identifier — used by providers.
-  #
   # --
   # : (?String?) -> String
   def name: (?String?) -> String
 
-  # Gets or sets the tool timeout in seconds.
-  #
   # --
   # : (?(Integer | Float)?) -> (Integer | Float)
   def timeout: (?(Integer | Float)?) -> (Integer | Float)
 
-  # Defines parameters using the Params DSL.
-  #
   # --
   # : () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def params: () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
 
-  # Returns the JSON Schema for the tool's parameters.
-  #
   # --
   # : (?strict: bool) -> Hash[Symbol, untyped]
   def parameters_schema: (?strict: bool) -> Hash[Symbol, untyped]
 
-  # Returns the kind of toolable entity; defaults to +:tool+.
   # --
   # : (?Symbol?) -> Symbol
   def kind: (?Symbol?) -> Symbol
 
-  # Returns a provider-agnostic tool schema hash.
-  #
   # --
   # : (?strict: bool) -> Hash[Symbol, untyped]
   def to_tool_schema: (?strict: bool) -> Hash[Symbol, untyped]
 
-  # Validates that the minimum required metadata is present for LLM tool use.
-  #
-  # Raises Riffer::ArgumentError if validation fails.
-  #
   # --
   # : () -> true
   def validate_as_tool!: () -> true

data/sig/generated/riffer/tracing/capture.rbs

@@ -1,8 +1,5 @@
 # Generated from lib/riffer/tracing/capture.rb with RBS::Inline
 
-# Serializes riffer messages into the GenAI semconv JSON message structure
-# for opt-in span content capture. File parts become metadata-only stubs —
-# bytes and URLs never reach a span attribute.
 module Riffer::Tracing::Capture
   # --
   # : (Array[Riffer::Messages::Base]) -> String
@@ -35,12 +32,12 @@ module Riffer::Tracing::Capture
   def tool_call_part: (Riffer::Messages::Assistant::ToolCall) -> Hash[Symbol, untyped]
 
   # --
-  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
-  def file_part: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
+  def file_part: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
 
-  # Semconv's tool_call part carries arguments as a JSON object; riffer holds
-  # them as a string — parse so the captured payload isn't double-encoded.
+  # Semconv's tool_call part carries arguments as a JSON object, so a string
+  # would be double-encoded.
   # --
-  # : (untyped) -> untyped
-  def parse_arguments: (untyped) -> untyped
+  # : (String) -> untyped
+  def parse_arguments: (String) -> untyped
 end

data/sig/generated/riffer/tracing/no_op.rbs

@@ -1,10 +1,6 @@
 # Generated from lib/riffer/tracing/no_op.rb with RBS::Inline
 
-# No-op tracing backend, used when OTEL is unavailable or tracing is
-# disabled.
 module Riffer::Tracing::NoOp
-  # No-op stand-in for a span; answers <tt>recording?</tt> with +false+ so
-  # callers can skip expensive attribute serialization.
   class Span
     # --
     # : (String, untyped) -> void
@@ -29,17 +25,14 @@ module Riffer::Tracing::NoOp
 
   SPAN: Riffer::Tracing::NoOp::Span
 
-  # Yields the no-op span, ignoring all span options.
   # --
   # : [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_span: [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
 
-  # Returns +nil+; there is no trace context without OTEL.
   # --
   # : () -> nil
   def current_context: () -> nil
 
-  # Yields immediately; there is no context to attach.
   # --
   # : [R] (untyped) { () -> R } -> R
   def with_context: [R] (untyped) { () -> R } -> R

data/sig/generated/riffer/tracing/otel.rbs

@@ -1,14 +1,13 @@
 # Generated from lib/riffer/tracing/otel.rb with RBS::Inline
 
-# OTEL-backed tracing backend. <tt>::OpenTelemetry</tt> constants appear only
-# inside method bodies here, so the gem loads and eager-loads cleanly when the
-# OpenTelemetry API is absent.
+# <tt>::OpenTelemetry</tt> constants must appear only inside method bodies, so
+# the gem eager-loads cleanly when the OpenTelemetry API is absent.
 class Riffer::Tracing::Otel
   # :nodoc: all
   SUPPORTED_API_VERSIONS: Gem::Requirement
 
-  # Wraps a live OTEL span behind the port's span surface, so callers never
-  # touch <tt>::OpenTelemetry</tt> constants (status objects in particular).
+  # Keeps callers from touching <tt>::OpenTelemetry</tt> constants (status
+  # objects in particular).
   class Span
     @otel_span: untyped
 
@@ -28,7 +27,6 @@ class Riffer::Tracing::Otel
     # : (Exception) -> void
     def record_exception: (Exception) -> void
 
-    # Marks the span status as error.
     # --
     # : (?String) -> void
     def error!: (?String) -> void
@@ -38,21 +36,17 @@ class Riffer::Tracing::Otel
     def recording?: () -> bool
   end
 
-  # Builds a backend when the OpenTelemetry API is loadable at a supported
-  # version; returns +nil+ so resolution falls back to NoOp. +provider+
-  # defaults to the global <tt>OpenTelemetry.tracer_provider</tt>.
+  # Returns +nil+ so resolution falls back to NoOp.
   # --
   # : (?provider: untyped) -> Riffer::Tracing::Otel?
   def self.build: (?provider: untyped) -> Riffer::Tracing::Otel?
 
-  # Whether the OpenTelemetry API gem is loadable at a supported version.
   # --
   # : () -> bool
   def self.available?: () -> bool
 
-  # Whether the given opentelemetry-api version is one riffer codes
-  # against. The gem is undeclared, so this guard is the only protection
-  # against an incompatible API.
+  # opentelemetry-api is undeclared, so this is the only protection against
+  # an incompatible API.
   # --
   # : (Gem::Version) -> bool
   def self.supported?: (Gem::Version) -> bool
@@ -67,17 +61,14 @@ class Riffer::Tracing::Otel
   # : (provider: untyped) -> void
   def initialize: (provider: untyped) -> void
 
-  # Opens an OTEL span around the block, yielding the wrapped span.
   # --
   # : [R] (String, attributes: Hash[String, untyped]?, kind: Symbol) { (Riffer::Tracing::Otel::Span) -> R } -> R
   def in_span: [R] (String, attributes: Hash[String, untyped]?, kind: Symbol) { (Riffer::Tracing::Otel::Span) -> R } -> R
 
-  # Returns the active OTEL context.
   # --
   # : () -> untyped
   def current_context: () -> untyped
 
-  # Runs the block with the given OTEL context active.
   # --
   # : [R] (untyped) { () -> R } -> R
   def with_context: [R] (untyped) { () -> R } -> R

data/sig/generated/riffer/tracing/stream_recorder.rbs

@@ -1,7 +1,5 @@
 # Generated from lib/riffer/tracing/stream_recorder.rb with RBS::Inline
 
-# Wraps a stream yielder to observe terminal events for span stamping while
-# forwarding every event downstream untouched.
 class Riffer::Tracing::StreamRecorder
   @yielder: Enumerator::Yielder
 

data/sig/generated/riffer/tracing.rbs

@@ -1,52 +1,33 @@
 # Generated from lib/riffer/tracing.rb with RBS::Inline
 
-# Internal tracing port — emits OTEL spans when the host bundles the
-# OpenTelemetry API and no-ops otherwise, so riffer never declares an OTEL
-# dependency.
+# No-ops unless the host bundles the OpenTelemetry API, so riffer never
+# declares an OTEL dependency.
 module Riffer::Tracing
-  @backend: untyped
-
-  MUTEX: Mutex
-
   # The Ruby API cannot attach a schema URL to a tracer, so the semconv pin
   # lives here as the documented contract version.
   SCHEMA_URL: String
 
-  # Opens a span around the block, yielding the span.
   # --
   # : [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_span: [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
 
-  # Returns the active trace context, for re-attachment across fiber or
-  # thread boundaries.
+  # For re-attachment across fiber or thread boundaries.
   # --
   # : () -> untyped
   def current_context: () -> untyped
 
-  # Runs the block with the given trace context active; +nil+ passes through
-  # so captures taken while tracing was dark stay harmless.
+  # +nil+ passes through so captures taken while tracing was off stay harmless.
   # --
   # : [R] (untyped) { () -> R } -> R
   def with_context: [R] (untyped) { () -> R } -> R
 
-  # Stamps token usage onto the span — the <tt>gen_ai.usage.*</tt> counts and,
-  # when the model was priced, <tt>riffer.cost</tt>.
   # --
   # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Providers::TokenUsage?) -> void
   def record_usage: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Providers::TokenUsage?) -> void
 
-  # Discards the resolved backend so the next span re-resolves it.
-  # --
-  # : () -> void
-  def reset!: () -> void
-
   private
 
   # --
   # : () -> untyped
   def backend: () -> untyped
-
-  # --
-  # : () -> untyped
-  def resolve_backend: () -> untyped
 end

data/sig/generated/riffer.rbs

@@ -3,89 +3,62 @@
 module Riffer
   @config: Riffer::Config?
 
-  # Base error class for Riffer.
   class Error < StandardError
   end
 
-  # Raised when invalid arguments are provided.
   class ArgumentError < ::ArgumentError
   end
 
-  # Raised when tool parameter validation fails.
   class ValidationError < Error
   end
 
-  # Raised inside a tool's +call+ when execution exceeds the configured
-  # timeout. Rescue it in the tool to clean up; otherwise it becomes a
+  # Rescue it in the tool to clean up; otherwise it becomes a
   # +:timeout_error+ response.
   class TimeoutError < Error
   end
 
-  # Raised when a tool encounters an expected execution error.
   class ToolExecutionError < Error
   end
 
-  # Raised when a provider's stream ends before its terminal event (Bedrock's
-  # messageStop, Anthropic's message_stop, OpenAI's response.completed /
-  # incomplete / failed), so a truncated or empty response is never returned
-  # as a complete message. Events already yielded were delivered; the
-  # request is safe to retry.
+  # Events already yielded were delivered; the request is safe to retry.
   class IncompleteStreamError < Error
   end
 
-  # Base error for a file attachment that can't be resolved for the provider.
   class FileError < Error
   end
 
-  # Raised when the provider can't accept the file at all.
   class FileUnsupportedError < FileError
   end
 
-  # Raised when a download is required but Riffer.config.files.allow_downloads is false.
   class FileDownloadsDisabledError < FileError
   end
 
-  # Raised when a message carries more files than Riffer.config.files.max_per_message allows.
   class TooManyFilesError < FileError
   end
 
-  # Raised when there's an issue downloading a file
   class FileDownloadError < FileError
   end
 
-  # Raised when a file size exceeds Riffer.config.files.max_bytes
   class FileTooLargeError < FileError
   end
 
-  # Raised when a downloaded or inline file's sha256 doesn't match.
   class FileChecksumMismatchError < FileError
   end
 
-  # Raised when a FilePart's data isn't valid base64
   class FileEncodingError < FileError
   end
 
-  # Raised when two registered subclasses share the same identifier.
   class DuplicateIdentifierError < Error
   end
 
-  # Returns the Riffer configuration.
-  #
   # --
   # : () -> Riffer::Config
   def config: () -> Riffer::Config
 
-  # Yields the configuration for block-based setup.
-  #
-  #   Riffer.configure do |config|
-  #     config.openai.api_key = ENV['OPENAI_API_KEY']
-  #   end
-  #
   # --
   # : () ?{ (Riffer::Config) -> void } -> void
   def configure: () ?{ (Riffer::Config) -> void } -> void
 
-  # Returns the gem version.
   # --
   # : () -> String
   def version: () -> String