riffer 0.47.2 → 0.49.0

data/lib/riffer/tools/runtime.rb

@@ -3,9 +3,6 @@
 
 require "json"
 
-# 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
   # @rbs @runner: Riffer::Runner
 
@@ -20,17 +17,15 @@ class Riffer::Tools::Runtime
     @runner = runner
   end
 
-  # 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(tool_calls, tools:, context:, assistant_message: nil, tags: {})
     # Each Runner worker runs in its own thread/fiber, where the OTEL context
     # starts empty — capture here so the execute_tool span parents correctly.
-    # tags are an ordinary local captured in the block, so they reach the
-    # worker's span without re-propagation.
     trace_context = Riffer::Tracing.current_context
     @runner.map(tool_calls, context: context) do |tool_call|
       Riffer::Tracing.with_context(trace_context) do
+        # Outside around_tool_call so host enrichment spans nest beneath it.
         instrument_tool_call(tool_call, tags) do
           around_tool_call(tool_call, context: context, assistant_message: assistant_message) do
             dispatch_tool_call(tool_call, tools: tools, context: context, assistant_message: assistant_message)
@@ -40,20 +35,7 @@ class Riffer::Tools::Runtime
     end
   end
 
-  # 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(_tool_call, context:, assistant_message: nil)
@@ -73,6 +55,7 @@ class Riffer::Tools::Runtime
     [tool_call, result] #: [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
   end
 
+  # 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(tool_call, tools:, context:, assistant_message: nil)
@@ -101,14 +84,13 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: (String?) -> untyped
+  #: (String) -> untyped
   def parse_arguments(arguments)
-    return {} if arguments.nil? || arguments.empty?
+    return {} if arguments.empty?
 
     JSON.parse(arguments, symbolize_names: true)
   end
 
-  # 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(tool_call, tags = {})
@@ -137,23 +119,20 @@ class Riffer::Tools::Runtime
     }.merge(tag_attributes(tags))
   end
 
-  # 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(tags)
     tags.transform_keys { |key| "riffer.tag.#{key}" }
   end
 
-  # 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(span, result)
     error_type = result.error_type
     span.set_attribute("error.type", error_type.to_s) if error_type
 
+    # A deliberate error Response is a handled outcome, so only one carrying the
+    # exception it was folded from gets an error status.
     exception = result.exception
     if exception
       span.record_exception(exception)
@@ -168,8 +147,7 @@ class Riffer::Tools::Runtime
   def capture_tool_arguments(span, tool_call)
     return unless capture_tool_content?(span)
 
-    arguments = tool_call.arguments
-    span.set_attribute("gen_ai.tool.call.arguments", arguments) if arguments
+    span.set_attribute("gen_ai.tool.call.arguments", tool_call.arguments)
   end
 
   #--

data/lib/riffer/tools/toolable.rb

@@ -1,20 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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
   # @rbs self.@extenders: Array[Module]?
@@ -26,8 +12,6 @@ module Riffer::Tools::Toolable
 
   DEFAULT_TIMEOUT = 10 #: Integer
 
-  # Tracks all classes that extend Toolable.
-  #
   #--
   #: (Module) -> void
   def self.extended(base)
@@ -35,16 +19,12 @@ module Riffer::Tools::Toolable
     extenders << base
   end
 
-  # Returns all classes that have extended Toolable.
-  #
   #--
   #: () -> Array[Module]
   def self.all
     @extenders || []
   end
 
-  # Gets or sets the tool description.
-  #
   #--
   #: (?String?) -> String?
   def description(value = nil)
@@ -53,8 +33,6 @@ module Riffer::Tools::Toolable
     @description = value.to_s
   end
 
-  # Gets or sets the tool identifier/name.
-  #
   #--
   #: (?String?) -> String
   def identifier(value = nil)
@@ -63,8 +41,6 @@ module Riffer::Tools::Toolable
     @identifier = value.to_s
   end
 
-  # Alias for identifier — used by providers.
-  #
   #--
   #: (?String?) -> String
   def name(value = nil)
@@ -73,8 +49,6 @@ module Riffer::Tools::Toolable
     identifier
   end
 
-  # Gets or sets the tool timeout in seconds.
-  #
   #--
   #: (?(Integer | Float)?) -> (Integer | Float)
   def timeout(value = nil)
@@ -83,8 +57,6 @@ module Riffer::Tools::Toolable
     @timeout = value.to_f
   end
 
-  # Defines parameters using the Params DSL.
-  #
   #--
   #: () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def params(&block)
@@ -95,15 +67,12 @@ module Riffer::Tools::Toolable
     @params_builder = builder
   end
 
-  # Returns the JSON Schema for the tool's parameters.
-  #
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def parameters_schema(strict: false)
     @params_builder&.to_json_schema(strict: strict) || empty_schema
   end
 
-  # Returns the kind of toolable entity; defaults to +:tool+.
   #--
   #: (?Symbol?) -> Symbol
   def kind(value = nil)
@@ -112,8 +81,6 @@ module Riffer::Tools::Toolable
     @kind = value.to_sym
   end
 
-  # Returns a provider-agnostic tool schema hash.
-  #
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_tool_schema(strict: false)
@@ -124,10 +91,6 @@ module Riffer::Tools::Toolable
     }
   end
 
-  # Validates that the minimum required metadata is present for LLM tool use.
-  #
-  # Raises Riffer::ArgumentError if validation fails.
-  #
   #--
   #: () -> true
   def validate_as_tool!

data/lib/riffer/tracing/capture.rb

@@ -3,9 +3,6 @@
 
 require "json"
 
-# 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 # :nodoc: all
   extend self
 
@@ -71,20 +68,19 @@ module Riffer::Tracing::Capture # :nodoc: all
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def file_part(file)
+    # Metadata only: file bytes and URLs must never reach a span attribute.
     part = { type: "file", media_type: file.media_type } #: Hash[Symbol, untyped]
     part[:name] = file.filename if file.filename
     part
   end
 
-  # 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
+  #: (String) -> untyped
   def parse_arguments(arguments)
-    return arguments unless arguments.is_a?(String)
-
     JSON.parse(arguments)
   rescue JSON::ParserError
     arguments

data/lib/riffer/tracing/no_op.rb

@@ -1,13 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# No-op tracing backend, used when OTEL is unavailable or tracing is
-# disabled.
 module Riffer::Tracing::NoOp # :nodoc: all
   extend self
 
-  # 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
@@ -34,21 +30,18 @@ module Riffer::Tracing::NoOp # :nodoc: all
 
   SPAN = Span.new.freeze #: 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(_name, **)
     yield SPAN
   end
 
-  # Returns +nil+; there is no trace context without OTEL.
   #--
   #: () -> nil
   def current_context
     nil
   end
 
-  # Yields immediately; there is no context to attach.
   #--
   #: [R] (untyped) { () -> R } -> R
   def with_context(_context)

data/lib/riffer/tracing/otel.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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.new(">= 1.1", "< 2") #: 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
     # @rbs @otel_span: untyped
 
@@ -36,7 +35,6 @@ class Riffer::Tracing::Otel # :nodoc: all
       @otel_span.record_exception(exception)
     end
 
-    # Marks the span status as error.
     #--
     #: (?String) -> void
     def error!(description = "")
@@ -51,9 +49,7 @@ class Riffer::Tracing::Otel # :nodoc: all
   end
 
   class << self
-    # 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 build(provider: nil)
@@ -69,7 +65,6 @@ class Riffer::Tracing::Otel # :nodoc: all
       new(provider: provider || ::OpenTelemetry.tracer_provider)
     end
 
-    # Whether the OpenTelemetry API gem is loadable at a supported version.
     #--
     #: () -> bool
     def available?
@@ -79,9 +74,8 @@ class Riffer::Tracing::Otel # :nodoc: all
       supported?(version)
     end
 
-    # 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 supported?(version)
@@ -109,7 +103,6 @@ class Riffer::Tracing::Otel # :nodoc: all
     @tracer = provider.tracer("riffer", Riffer::VERSION)
   end
 
-  # 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(name, attributes:, kind:)
@@ -118,14 +111,12 @@ class Riffer::Tracing::Otel # :nodoc: all
     end
   end
 
-  # Returns the active OTEL context.
   #--
   #: () -> untyped
   def current_context
     ::OpenTelemetry::Context.current
   end
 
-  # Runs the block with the given OTEL context active.
   #--
   #: [R] (untyped) { () -> R } -> R
   def with_context(context, &)

data/lib/riffer/tracing/stream_recorder.rb

@@ -1,23 +1,16 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Wraps a stream yielder to observe terminal events for span stamping while
-# forwarding every event downstream untouched.
 class Riffer::Tracing::StreamRecorder # :nodoc: all
   # @rbs @yielder: Enumerator::Yielder
   # @rbs @clock: ^() -> Float
   # @rbs @started_at: Float
 
   attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
-
   attr_reader :time_to_first_chunk #: Float? # @dynamic time_to_first_chunk
-
   attr_reader :finish_reason #: Symbol? # @dynamic finish_reason
-
   attr_reader :raw_finish_reason #: String? # @dynamic raw_finish_reason
-
   attr_reader :content #: String? # @dynamic content
-
   attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
 
   #--

data/lib/riffer/tracing.rb

@@ -1,21 +1,15 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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 # :nodoc: all
   extend self
 
-  # @rbs @backend: untyped
-
-  MUTEX = Mutex.new #: 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 = "https://opentelemetry.io/schemas/1.37.0" #: 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(name, attributes: nil, kind: :internal, &)
@@ -24,8 +18,7 @@ module Riffer::Tracing # :nodoc: all
     backend.in_span(name, attributes: attributes, kind: kind, &)
   end
 
-  # 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
@@ -34,8 +27,7 @@ module Riffer::Tracing # :nodoc: all
     backend.current_context
   end
 
-  # 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(context, &)
@@ -44,8 +36,6 @@ module Riffer::Tracing # :nodoc: all
     backend.with_context(context, &)
   end
 
-  # 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(span, usage)
@@ -58,24 +48,11 @@ module Riffer::Tracing # :nodoc: all
     span.set_attribute("riffer.cost", usage.cost) if usage.cost
   end
 
-  # Discards the resolved backend so the next span re-resolves it.
-  #--
-  #: () -> void
-  def reset!
-    MUTEX.synchronize { @backend = nil }
-  end
-
   private
 
   #--
   #: () -> untyped
   def backend
-    @backend || MUTEX.synchronize { @backend ||= resolve_backend }
-  end
-
-  #--
-  #: () -> untyped
-  def resolve_backend
     Riffer.config.tracing.backend || NoOp
   end
 end

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.47.2" #: String
+  VERSION = "0.49.0" #: String
 end

data/lib/riffer.rb

@@ -3,7 +3,6 @@
 
 require "zeitwerk"
 
-# Riffer is the main module for the Riffer AI framework.
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "open_ai" => "OpenAI",
@@ -24,78 +23,51 @@ module Riffer
 
   # @rbs @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
     @config ||= Config.new
   end
 
-  # 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(&)
     yield config if block_given?
   end
 
-  # Returns the gem version.
   #--
   #: () -> String
   def version