riffer 0.43.0 → 0.45.0

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

@@ -4,6 +4,11 @@
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE: String
 
+  # The Responses API has no finish_reason field. The response +status+ is
+  # the primary signal; an +incomplete+ status is only meaningful together
+  # with <tt>incomplete_details.reason</tt>, so that branch nests one level.
+  FINISH_REASONS: Hash[String, Symbol | Hash[String, Symbol]]
+
   # The GenAI semconv well-known provider name.
   # --
   # : () -> String
@@ -13,6 +18,10 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : () -> void
   def initialize: () -> void
 
+  # --
+  # : (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+
   private
 
   # --
@@ -46,14 +55,14 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
-  # The Responses API reports no finish_reason field, so one is derived.
   # --
   # : (untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
+  # The nested field that names the cause behind an ambiguous status.
   # --
-  # : (untyped) -> Riffer::Providers::FinishReason
-  def incomplete_finish_reason: (untyped) -> Riffer::Providers::FinishReason
+  # : (untyped, String) -> String?
+  def finish_detail: (untyped, String) -> String?
 
   # --
   # : (untyped) -> String

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
 
   # --
@@ -53,9 +57,17 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
+  # +native+ is the upstream model's own finish reason, which OpenRouter
+  # reports alongside its normalized one; it wins as +raw+ when present.
   # --
-  # : (untyped) -> Riffer::Providers::FinishReason?
-  def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+  # : (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason: (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
+
+  # +native_finish_reason+ is outside the OpenAI schema, so it is only
+  # reachable through the SDK model's raw data hash.
+  # --
+  # : (untyped) -> untyped
+  def native_finish_reason: (untyped) -> untyped
 
   # --
   # : (untyped) -> String

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
+

data/sig/generated/riffer/testing.rbs

@@ -0,0 +1,75 @@
+# 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? ]]
+
+  private
+
+  # --
+  # : ((String | Symbol)?, base: Class) ?{ () [self: untyped] -> void } -> Class
+  def build_stub: ((String | Symbol)?, base: Class) ?{ () [self: untyped] -> void } -> Class
+
+  # --
+  # : ((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
+end

data/sig/generated/riffer.rbs

@@ -25,6 +25,38 @@ module Riffer
   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/manifest.yaml

@@ -1,3 +1,4 @@
 dependencies:
   - name: uri
   - name: net-http
+  - name: digest

data/sig/manual/riffer/testing.rbs

@@ -0,0 +1,5 @@
+# `Riffer::Testing` uses `extend self`; rbs-inline doesn't emit that, so
+# re-extend here to expose its instance methods as singleton methods.
+module Riffer::Testing
+  extend ::Riffer::Testing
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.43.0
+  version: 0.45.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -29,6 +29,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.6.0
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Riffer is a comprehensive Ruby framework designed to simplify the development
   of AI-powered applications and agents. It provides a complete toolkit for integrating
   artificial intelligence capabilities into your Ruby projects.
@@ -79,6 +93,7 @@ files:
 - docs/SERIALIZATION.md
 - docs/SKILLS.md
 - docs/STREAM_EVENTS.md
+- docs/TESTING.md
 - docs/TOOLS.md
 - docs/TOOL_ADVANCED.md
 - docs/TRACING.md
@@ -110,6 +125,9 @@ files:
 - lib/riffer/evals/result.rb
 - lib/riffer/evals/run_result.rb
 - lib/riffer/evals/scenario_result.rb
+- lib/riffer/files.rb
+- lib/riffer/files/downloader.rb
+- lib/riffer/files/resolver.rb
 - lib/riffer/guardrail.rb
 - lib/riffer/guardrails.rb
 - lib/riffer/guardrails/modification.rb
@@ -184,6 +202,9 @@ files:
 - lib/riffer/stream_events/tool_call_done.rb
 - lib/riffer/stream_events/web_search_done.rb
 - lib/riffer/stream_events/web_search_status.rb
+- lib/riffer/testing.rb
+- lib/riffer/testing/minitest.rb
+- lib/riffer/testing/rspec.rb
 - lib/riffer/tool.rb
 - lib/riffer/tools.rb
 - lib/riffer/tools/response.rb
@@ -203,6 +224,7 @@ files:
 - sig/_private/aws-sdk-core/seahorse_request_context.rbs
 - sig/_private/aws-sdk-core/static_token_provider.rbs
 - sig/_private/mcp.rbs
+- sig/_private/minitest.rbs
 - sig/_private/openai.rbs
 - sig/_private/opentelemetry.rbs
 - sig/_private/riffer/providers/amazon_bedrock.rbs
@@ -210,6 +232,8 @@ files:
 - sig/_private/riffer/providers/gemini.rbs
 - sig/_private/riffer/providers/open_ai.rbs
 - sig/_private/riffer/providers/open_router.rbs
+- sig/_private/riffer/testing/minitest.rbs
+- sig/_private/rspec.rbs
 - sig/_private/zeitwerk.rbs
 - sig/generated/riffer.rbs
 - sig/generated/riffer/agent.rbs
@@ -230,6 +254,9 @@ files:
 - sig/generated/riffer/evals/result.rbs
 - sig/generated/riffer/evals/run_result.rbs
 - sig/generated/riffer/evals/scenario_result.rbs
+- sig/generated/riffer/files.rbs
+- sig/generated/riffer/files/downloader.rbs
+- sig/generated/riffer/files/resolver.rbs
 - sig/generated/riffer/guardrail.rbs
 - sig/generated/riffer/guardrails.rbs
 - sig/generated/riffer/guardrails/modification.rbs
@@ -304,6 +331,8 @@ files:
 - sig/generated/riffer/stream_events/tool_call_done.rbs
 - sig/generated/riffer/stream_events/web_search_done.rbs
 - sig/generated/riffer/stream_events/web_search_status.rbs
+- sig/generated/riffer/testing.rbs
+- sig/generated/riffer/testing/rspec.rbs
 - sig/generated/riffer/tool.rbs
 - sig/generated/riffer/tools.rbs
 - sig/generated/riffer/tools/response.rbs
@@ -335,6 +364,7 @@ files:
 - sig/manual/riffer/mcp/tool_factory.rbs
 - sig/manual/riffer/providers.rbs
 - sig/manual/riffer/providers/repository.rbs
+- sig/manual/riffer/testing.rbs
 - sig/manual/riffer/tool.rbs
 - sig/manual/riffer/tracing.rbs
 - sig/manual/riffer/tracing/capture.rbs