riffer 0.43.0 → 0.44.0

data/lib/riffer/testing.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# 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
+  extend self
+
+  # @rbs self.@registrations: Array[[Class, String?]]?
+
+  CONST_NAME_PATTERN = /\A[A-Z][A-Za-z0-9_]*\z/ #: Regexp
+  private_constant :CONST_NAME_PATTERN
+
+  # 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(name = nil, base: Riffer::Agent, &body)
+    build_stub(name, base: base, &body) #: singleton(Riffer::Agent)
+  end
+
+  # 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(name = nil, base: Riffer::Tool, &body)
+    build_stub(name, base: base, &body) #: singleton(Riffer::Tool)
+  end
+
+  # 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!
+    tracked = Riffer::Testing.registrations
+    tracked.reverse_each do |stub, const_name|
+      registrable = stub.superclass #: untyped
+      registrable.unregister(stub)
+      remove_stub_const(const_name, stub) if const_name
+    end
+    tracked.clear
+  end
+
+  # 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 # :nodoc:
+    @registrations ||= []
+  end
+
+  private
+
+  #--
+  #: ((String | Symbol)?, base: Class) ?{ () [self: untyped] -> void } -> Class
+  def build_stub(name, base:, &body)
+    const_name = validate_const_name(name)
+    stub = Class.new(base)
+    configurable = stub #: untyped
+    configurable.identifier(Riffer::Helpers::Identifier.derive(const_name)) if const_name
+    configurable.class_eval(&body) if body
+    if configurable.identifier.to_s.strip.empty?
+      raise Riffer::ArgumentError, "a stub needs a name, or an identifier set in its block"
+    end
+
+    # The class must be registered while still anonymous: naming it first makes
+    # it implicitly live, and +register+ rejects an identifier the registry
+    # already resolves — even to this same class.
+    registrable = base #: untyped
+    registrable.register(stub)
+    Object.const_set(const_name, stub) if const_name
+    Riffer::Testing.registrations << [stub, const_name]
+
+    stub
+  end
+
+  #--
+  #: ((String | Symbol)?) -> String?
+  def validate_const_name(name)
+    return nil if name.nil?
+
+    const_name = name.to_s
+    unless CONST_NAME_PATTERN.match?(const_name)
+      raise Riffer::ArgumentError, "#{const_name.inspect} is not a simple top-level constant name"
+    end
+
+    # True of a pending autoload too — the name is taken either way.
+    if Object.const_defined?(const_name, false)
+      raise Riffer::ArgumentError, "#{const_name} is already defined; use stub_const to replace a real class"
+    end
+
+    const_name
+  end
+
+  # 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(const_name, stub)
+    return unless Object.const_defined?(const_name, false) && Object.const_get(const_name, false).equal?(stub)
+
+    Object.send(:remove_const, const_name)
+  end
+end

data/lib/riffer/version.rb

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

data/lib/riffer.rb

@@ -10,6 +10,13 @@ loader.inflector.inflect(
   "azure_open_ai" => "AzureOpenAI",
   "open_router" => "OpenRouter",
 )
+# Test-framework wiring a consumer requires by hand; neither file defines the
+# constant its path implies, and both reference framework constants riffer
+# never loads itself.
+loader.ignore(
+  "#{__dir__}/riffer/testing/rspec.rb",
+  "#{__dir__}/riffer/testing/minitest.rb",
+)
 loader.setup
 
 module Riffer
@@ -34,6 +41,30 @@ module Riffer
   # Raised when a tool encounters an expected execution error.
   class ToolExecutionError < 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
 

data/sig/_private/minitest.rbs

@@ -0,0 +1,9 @@
+# Minimal signatures for `minitest`, a development-only framework riffer never
+# depends on. Only the surface `lib/riffer/testing/minitest.rb` touches is
+# declared; the file is required by hand from a consumer's test_helper, so this
+# stub keeps Steep aware of the constants without a `library` dependency.
+module Minitest
+  class Test
+    def after_teardown: () -> void
+  end
+end

data/sig/_private/riffer/testing/minitest.rbs

@@ -0,0 +1,6 @@
+# Hand-written because the signature names `Minitest`, an optional
+# development-only framework that must never appear in a shipped signature —
+# `lib/riffer/testing/minitest.rb` therefore leaves rbs-inline disabled.
+module Riffer::Testing::MinitestCleanup : Minitest::Test
+  def after_teardown: () -> void
+end

data/sig/_private/rspec.rbs

@@ -0,0 +1,7 @@
+# Minimal signatures for `rspec`, a development-only framework riffer never
+# depends on. Only the surface `lib/riffer/testing/rspec.rb` touches is
+# declared; the file is required by hand from a consumer's spec_helper, so this
+# stub keeps Steep aware of the constants without a `library` dependency.
+module RSpec
+  def self.configure: () { (untyped) -> void } -> void
+end

data/sig/_private/zeitwerk.rbs

@@ -5,6 +5,8 @@ module Zeitwerk
   class Loader
     def self.for_gem: (*untyped) -> Zeitwerk::Loader
 
+    def ignore: (*String) -> void
+
     def inflector: () -> untyped
 
     def setup: () -> void

data/sig/generated/riffer/config.rbs

@@ -147,6 +147,68 @@ class Riffer::Config
     def backend=: (untyped) -> void
   end
 
+  # File-attachment-download policy for +Riffer::Messages::FilePart+ URL sources
+  class Files
+    # Allow file attachments to be downloaded to send to providers.
+    attr_reader allow_downloads: bool
+
+    # Maximum file size to download before failing.
+    attr_reader max_bytes: Integer
+
+    # Maximum amount of time to spend downloading a file before failing.
+    attr_reader timeout: Integer
+
+    # Maximum number of files to include in an individual message.
+    attr_reader max_per_message: Integer?
+
+    # Execution pattern for downloading files.
+    attr_reader runner: Riffer::Runner
+
+    # The object used to fetch a URL source's bytes
+    attr_reader downloader: untyped
+
+    # --
+    # : () -> void
+    def initialize: () -> void
+
+    # 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=: (untyped) -> void
+
+    # 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=: (untyped) -> void
+
+    # 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=: (untyped) -> void
+
+    # 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=: (untyped) -> void
+
+    # 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=: (untyped) -> void
+
+    # Sets the object used to download bytes from a URL.
+    # Raises Riffer::ArgumentError if value does not respond to +#call+.
+    # --
+    # : (untyped) -> void
+    def downloader=: (untyped) -> void
+  end
+
   # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer
   # ships no price table, so an unconfigured model carries no cost.
   class Pricing
@@ -256,6 +318,8 @@ class Riffer::Config
   # Tracing-related global configuration.
   attr_reader tracing: Riffer::Config::Tracing
 
+  attr_reader files: Riffer::Config::Files
+
   # Consumer-configured per-model token pricing.
   attr_reader pricing: Riffer::Config::Pricing
 

data/sig/generated/riffer/files/downloader.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/riffer/files/downloader.rb with RBS::Inline
+
+class Riffer::Files::Downloader
+  MAX_REDIRECTS: Integer
+
+  # : (String, max_bytes: Integer, timeout: Integer) -> String
+  def call: (String, max_bytes: Integer, timeout: Integer) -> String
+
+  private
+
+  # : (String, max_bytes: Integer, timeout: Integer, redirects_remaining: Integer) -> String
+  def fetch: (String, max_bytes: Integer, timeout: Integer, redirects_remaining: Integer) -> String
+
+  # : (Net::HTTPResponse, max_bytes: Integer) -> String
+  def read_capped: (Net::HTTPResponse, max_bytes: Integer) -> String
+end

data/sig/generated/riffer/files/resolver.rbs

@@ -0,0 +1,36 @@
+# Generated from lib/riffer/files/resolver.rb with RBS::Inline
+
+class Riffer::Files::Resolver
+  @provider: Riffer::Providers::Base
+
+  @config: Riffer::Config::Files
+
+  # : (provider: Riffer::Providers::Base) -> void
+  def initialize: (provider: Riffer::Providers::Base) -> void
+
+  # Resolves every file in every User message in place - downloading,
+  # verifying, and caching as the provider's capability and each file's
+  # sha256 require.  Raises Riffer::FileError on any file that can't be
+  # resolved
+  # : (Array[Riffer::Messages::Base]) -> void
+  def resolve!: (Array[Riffer::Messages::Base]) -> void
+
+  private
+
+  # : (Riffer::Messages::User) -> void
+  def check_file_count!: (Riffer::Messages::User) -> void
+
+  # : (Riffer::Messages::FilePart) -> void
+  def resolve_file!: (Riffer::Messages::FilePart) -> void
+
+  # : (Riffer::Messages::FilePart) -> void
+  def verify_inline!: (Riffer::Messages::FilePart) -> void
+
+  # +cache:+ is false for a :url-delivery provider verifying a sha256 — the
+  # request still sends the URL, never the downloaded bytes, so caching them
+  # would hold memory nothing reads and let later turns skip re-verifying.
+  # : (Riffer::Messages::FilePart, cache: (false | Symbol)) -> void
+  def download!: (Riffer::Messages::FilePart, cache: false | Symbol) -> void
+
+  def verify_bytes!: (untyped bytes, untyped sha256) -> untyped
+end

data/sig/generated/riffer/files.rbs

@@ -0,0 +1,4 @@
+# Generated from lib/riffer/files.rb with RBS::Inline
+
+module Riffer::Files
+end

data/sig/generated/riffer/helpers/identifier.rbs

@@ -16,4 +16,12 @@ module Riffer::Helpers::Identifier
   # --
   # : (Module) -> String
   def for: (Module) -> String
+
+  # Returns the class-path name of a class or module, or +nil+ when anonymous.
+  # Tool classes shadow Module#name with the identifier DSL, so the real name
+  # must come from Module's own implementation.
+  #
+  # --
+  # : (Module) -> String?
+  def real_name: (Module) -> String?
 end

data/sig/generated/riffer/messages/file_part.rbs

@@ -3,29 +3,40 @@
 # Represents a file attachment (image or document) — from a URL (+from_url+) or
 # raw base64 data (+new+).
 class Riffer::Messages::FilePart
+  @data_bytes: String?
+
+  @downloaded_data: String?
+
+  @data: String?
+
   @url_string: String?
 
   MEDIA_TYPES: Hash[String, String]
 
   SUPPORTED_MEDIA_TYPES: Array[String]
 
+  SHA256_PATTERN: Regexp
+
   # The MIME type of the file.
   attr_reader media_type: String
 
   # The filename, if available.
   attr_reader filename: String?
 
+  # The expected SHA-256 of the file contents, if the caller supplied one.
+  attr_reader sha256: String?
+
   # Raises Riffer::ArgumentError unless +data+ or +url+ is given and
   # +media_type+ is supported.
   # --
-  # : (media_type: String, ?data: String?, ?filename: String?, ?url: String?) -> void
-  def initialize: (media_type: String, ?data: String?, ?filename: String?, ?url: String?) -> void
+  # : (media_type: String, ?data: String?, ?filename: String?, ?url: String?, ?sha256: String?) -> void
+  def initialize: (media_type: String, ?data: String?, ?filename: String?, ?url: String?, ?sha256: String?) -> void
 
   # Creates a FilePart from a URL, detecting +media_type+ from the path
   # extension when omitted. Raises Riffer::ArgumentError if it can't be detected.
   # --
-  # : (String, ?media_type: String?) -> Riffer::Messages::FilePart
-  def self.from_url: (String, ?media_type: String?) -> Riffer::Messages::FilePart
+  # : (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::FilePart
+  def self.from_url: (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::FilePart
 
   # Builds a FilePart from a +{url:, media_type:}+ or +{data:, media_type:}+ hash,
   # or returns +file+ unchanged when it is already a FilePart. Raises
@@ -34,8 +45,29 @@ class Riffer::Messages::FilePart
   # : ((Hash[Symbol, untyped] | Riffer::Messages::FilePart)) -> Riffer::Messages::FilePart
   def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::FilePart) -> Riffer::Messages::FilePart
 
-  # Returns the base64-encoded data, or nil for URL-only sources.
-  attr_reader data: String?
+  # The base64-encoded contents - caller-supplied, or filled in by the file
+  # resolver after a download.  Nil for a URL source riffer hasn't fetched.
+  # --
+  # : () -> String?
+  def data: () -> String?
+
+  # : () -> String?
+  def data_bytes: () -> String?
+
+  # : (String) -> void
+  def cache_data_bytes: (String) -> void
+
+  # Whether data was supplied directly, as opposed to filled in later by the
+  # file resolver after a download
+  # : () -> bool
+  def inline_data?: () -> bool
+
+  # Caches bytes fetched for a URL source.  Deliberately absent from +to_h+:
+  # the agent loop re-sends history on every turn, so the cache saves refreshing
+  # the same file, while persisted history stays free of megabytes of base64
+  # --
+  # : (String) -> void
+  def cache_downloaded_data: (String) -> void
 
   # Returns the URL if the source was a URL, nil otherwise.
   #

data/sig/generated/riffer/providers/amazon_bedrock.rbs

@@ -24,6 +24,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # : () -> void
   def initialize: () -> void
 
+  # --
+  # : (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+
   private
 
   # --

data/sig/generated/riffer/providers/base.rbs

@@ -41,6 +41,10 @@ class Riffer::Providers::Base
   # : (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream_text: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
 
+  # --
+  # : (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+
   private
 
   # : (String) -> true

data/sig/generated/riffer/providers/gemini.rbs

@@ -11,6 +11,10 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   # : () -> String
   def self.semconv_provider_name: () -> String
 
+  # --
+  # : (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+
   private
 
   # --

data/sig/generated/riffer/providers/open_ai.rbs

@@ -13,6 +13,10 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : () -> void
   def initialize: () -> void
 
+  # --
+  # : (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+
   private
 
   # --

data/sig/generated/riffer/providers/open_router.rbs

@@ -18,6 +18,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : () -> void
   def initialize: () -> void
 
+  # --
+  # : (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+
   private
 
   # --

data/sig/generated/riffer/registrable.rbs

@@ -1,7 +1,11 @@
 # Generated from lib/riffer/registrable.rb with RBS::Inline
 
-# Registry of a class's named direct subclasses, keyed by identifier. Extend it
+# Registry of a class's direct subclasses, keyed by identifier. Extend it
 # onto a base class to look up subclasses in constant time via +find+ and +all+.
+# Subclasses join implicitly by inheriting; +register+ adds one explicitly, for
+# ephemeral classes a test suite builds and tears down. Registration is not
+# synchronized — register during boot or from a single-threaded test, before
+# concurrent lookups begin.
 #
 #   class Riffer::Tool
 #     extend Riffer::Registrable
@@ -13,25 +17,47 @@
 module Riffer::Registrable : Class
   @identifier_registry: Hash[String, Class]?
 
+  @explicit_registrations: Hash[String, Class]?
+
   # Finds a registered subclass by identifier, or +nil+ when none matches.
-  # Only *named direct* subclasses are registered: grandchildren are not
-  # visible to a grandparent's +find+ (call +find+ on their direct parent
-  # instead), anonymous classes are never registered, and duplicate identifiers
-  # raise Riffer::DuplicateIdentifierError at first lookup.
+  # Implicit registration covers only *named direct* subclasses: grandchildren
+  # are not visible to a grandparent's +find+ (call +find+ on their direct
+  # parent instead), anonymous classes are never registered implicitly, and a
+  # subclass whose name no longer resolves back to it is dropped at the next
+  # registry rebuild. Duplicate identifiers raise
+  # Riffer::DuplicateIdentifierError at first lookup.
   #
   # --
   # : (String | Symbol) -> Class?
   def find: (String | Symbol) -> Class?
 
-  # Returns all registered subclasses. Only *named direct* subclasses are
-  # registered: grandchildren are not included (call +all+ on their direct
-  # parent instead), anonymous classes are never registered, and duplicate
-  # identifiers raise Riffer::DuplicateIdentifierError at first lookup.
+  # Returns all registered subclasses, implicit and explicit. Carries the same
+  # registration rules as +find+.
   #
   # --
   # : () -> Array[Class]
   def all: () -> Array[Class]
 
+  # Registers a direct subclass under its +identifier+, whether or not it is
+  # named — unlike implicit registration, it survives a name that no longer
+  # resolves, so an ephemeral class stays findable until +unregister+. Prefer
+  # Riffer::Testing for ordinary test setup, which stubs and cleans up
+  # automatically.
+  #
+  # Raises Riffer::ArgumentError when the identifier is blank or the class is
+  # not a direct subclass, and Riffer::DuplicateIdentifierError when the
+  # identifier is already taken — including by this same class.
+  #
+  # --
+  # : (Class) -> void
+  def register: (Class) -> void
+
+  # Removes an explicit registration of +klass+, leaving implicit registrations
+  # untouched.
+  # --
+  # : (Class) -> void
+  def unregister: (Class) -> void
+
   private
 
   # Ruby invokes +inherited+ with +self+ bound to the direct superclass — the
@@ -45,7 +71,29 @@ module Riffer::Registrable : Class
   # : () -> Hash[String, Class]
   def identifier_registry: () -> Hash[String, Class]
 
+  # --
+  # : () -> Hash[String, Class]
+  def explicit_registrations: () -> Hash[String, Class]
+
   # --
   # : () -> Hash[String, Class]
   def build_identifier_registry: () -> Hash[String, Class]
+
+  # Class#subclasses keeps returning superseded generations of a reloaded or
+  # stubbed class, so a subclass counts only while its own name still resolves
+  # back to it. An anonymous class has no name to resolve and is skipped even
+  # with an explicit identifier — the MCP factory and serializer shells
+  # synthesize short-lived anonymous classes whose registration would flake
+  # with GC timing.
+  # --
+  # : (Class) -> bool
+  def live?: (Class) -> bool
+
+  # --
+  # : (Class) -> String
+  def identifier_key: (Class) -> String
+
+  # --
+  # : (String, Class, Class) -> void
+  def raise_duplicate_identifier!: (String, Class, Class) -> void
 end

data/sig/generated/riffer/testing/rspec.rbs

@@ -0,0 +1,2 @@
+# Generated from lib/riffer/testing/rspec.rb with RBS::Inline
+