riffer 0.27.2 → 0.29.0

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

@@ -28,6 +28,24 @@ class Riffer::Messages::Base
   # : () -> Symbol
   def role: () -> Symbol
 
+  # Whether this message carries pending tool calls. Defaults to +false+;
+  # +Riffer::Messages::Assistant+ overrides this when its +tool_calls+
+  # array is non-empty.
+  #
+  # --
+  # : () -> bool
+  def has_tool_calls?: () -> bool
+
+  # Merges another same-role message into this one.
+  #
+  # Raises NotImplementedError unless implemented by subclass. Mergeable
+  # message types (+User+, +Assistant+, +System+) override this; +Tool+
+  # messages are never merged.
+  #
+  # --
+  # : (untyped) -> Riffer::Messages::Base
+  def +: (untyped) -> Riffer::Messages::Base
+
   private
 
   # : () -> String?

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

@@ -12,18 +12,18 @@ module Riffer::Messages::Converter
   # : ((Hash[Symbol, untyped] | Riffer::Messages::Base)) -> Riffer::Messages::Base
   def convert_to_message_object: (Hash[Symbol, untyped] | Riffer::Messages::Base) -> Riffer::Messages::Base
 
-  # Converts a hash or FilePart object to a Riffer::FilePart.
+  # Converts a hash or FilePart object to a Riffer::Messages::FilePart.
   #
   # Accepts:
-  # - +Riffer::FilePart+ objects (passed through)
+  # - +Riffer::Messages::FilePart+ objects (passed through)
   # - <tt>{url: "https://...", media_type: "..."}</tt> (URL source)
   # - <tt>{data: "...", media_type: "..."}</tt> (raw base64)
   #
   # Raises Riffer::ArgumentError if the hash format is invalid.
   #
   # --
-  # : ((Hash[Symbol, untyped] | Riffer::FilePart)) -> Riffer::FilePart
-  def convert_to_file_part: (Hash[Symbol, untyped] | Riffer::FilePart) -> Riffer::FilePart
+  # : ((Hash[Symbol, untyped] | Riffer::Messages::FilePart)) -> Riffer::Messages::FilePart
+  def convert_to_file_part: (Hash[Symbol, untyped] | Riffer::Messages::FilePart) -> Riffer::Messages::FilePart
 
   private
 

data/sig/generated/riffer/{file_part.rbs → messages/file_part.rbs}

@@ -1,4 +1,4 @@
-# Generated from lib/riffer/file_part.rb with RBS::Inline
+# Generated from lib/riffer/messages/file_part.rb with RBS::Inline
 
 # Represents a file attachment (image or document) in a conversation.
 #
@@ -6,10 +6,10 @@
 # - URLs (stored and passed to providers that support them via +from_url+)
 # - Raw base64 data (via +new+)
 #
-#   file = Riffer::FilePart.from_url("https://example.com/doc.pdf", media_type: "application/pdf")
+#   file = Riffer::Messages::FilePart.from_url("https://example.com/doc.pdf", media_type: "application/pdf")
 #   file.url?        # => true
 #   file.document?   # => true
-class Riffer::FilePart
+class Riffer::Messages::FilePart
   MEDIA_TYPES: Hash[String, String]
 
   SUPPORTED_MEDIA_TYPES: Array[String]
@@ -39,8 +39,8 @@ class Riffer::FilePart
   # Raises Riffer::ArgumentError if media_type cannot be detected.
   #
   # --
-  # : (String, ?media_type: String?) -> Riffer::FilePart
-  def self.from_url: (String, ?media_type: String?) -> Riffer::FilePart
+  # : (String, ?media_type: String?) -> Riffer::Messages::FilePart
+  def self.from_url: (String, ?media_type: String?) -> Riffer::Messages::FilePart
 
   # Returns the base64-encoded data, or nil for URL-only sources.
   attr_reader data: String?

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

@@ -7,16 +7,16 @@
 #   msg.content  # => "Hello!"
 #
 #   msg = Riffer::Messages::User.new("Describe this image", files: [file_part])
-#   msg.files    # => [#<Riffer::FilePart ...>]
+#   msg.files    # => [#<Riffer::Messages::FilePart ...>]
 class Riffer::Messages::User < Riffer::Messages::Base
   # File attachments for this message.
-  attr_reader files: Array[Riffer::FilePart]
+  attr_reader files: Array[Riffer::Messages::FilePart]
 
   # Initializes a user message.
   #
   # --
-  # : (String, ?id: String?, ?files: Array[Riffer::FilePart]) -> void
-  def initialize: (String, ?id: String?, ?files: Array[Riffer::FilePart]) -> void
+  # : (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
+  def initialize: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
 
   # --
   # : () -> Symbol

data/sig/generated/riffer/params/boolean.rbs

@@ -0,0 +1,10 @@
+# Generated from lib/riffer/params/boolean.rb with RBS::Inline
+
+# Riffer::Params::Boolean is a sentinel type for declaring boolean parameters.
+#
+# Ruby has no +Boolean+ class (+true+ is +TrueClass+, +false+ is +FalseClass+).
+# Use this module wherever you need a single type that means "boolean":
+#
+#   required :verbose, Riffer::Params::Boolean
+module Riffer::Params::Boolean
+end

data/sig/generated/riffer/{param.rbs → params/param.rbs}

@@ -1,9 +1,9 @@
-# Generated from lib/riffer/param.rb with RBS::Inline
+# Generated from lib/riffer/params/param.rb with RBS::Inline
 
-# Riffer::Param represents a single parameter definition.
+# Riffer::Params::Param represents a single parameter definition.
 #
 # Handles type validation and JSON Schema generation for individual parameters.
-class Riffer::Param
+class Riffer::Params::Param
   # Maps Ruby types to JSON Schema type strings
   TYPE_MAPPINGS: Hash[Module, String]
 

data/sig/generated/riffer/params.rbs

@@ -10,7 +10,7 @@
 #     optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
 #   end
 class Riffer::Params
-  attr_reader parameters: Array[Riffer::Param]
+  attr_reader parameters: Array[Riffer::Params::Param]
 
   # --
   # : () -> void
@@ -19,14 +19,14 @@ class Riffer::Params
   # Defines a required parameter.
   #
   # --
-  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ () -> void } -> void
-  def required: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ () -> void } -> void
+  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def required: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
 
   # Defines an optional parameter.
   #
   # --
-  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ () -> void } -> void
-  def optional: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ () -> void } -> void
+  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def optional: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
 
   # Validates arguments against parameter definitions.
   #
@@ -49,22 +49,22 @@ class Riffer::Params
   private
 
   # --
-  # : (Class, Class?) ?{ () -> void } -> Riffer::Params?
-  def build_nested: (Class, Class?) ?{ () -> void } -> Riffer::Params?
+  # : (Class, Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
+  def build_nested: (Class, Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
 
   # --
-  # : (Riffer::Param, untyped, Array[String]) -> untyped
-  def validate_nested: (Riffer::Param, untyped, Array[String]) -> untyped
+  # : (Riffer::Params::Param, untyped, Array[String]) -> untyped
+  def validate_nested: (Riffer::Params::Param, untyped, Array[String]) -> untyped
 
   # --
-  # : (Riffer::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
-  def validate_nested_hash: (Riffer::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+  # : (Riffer::Params::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+  def validate_nested_hash: (Riffer::Params::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
 
   # --
-  # : (Riffer::Param, Array[untyped], Array[String]) -> Array[untyped]
-  def validate_nested_array_of_objects: (Riffer::Param, Array[untyped], Array[String]) -> Array[untyped]
+  # : (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
+  def validate_nested_array_of_objects: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
 
   # --
-  # : (Riffer::Param, Array[untyped], Array[String]) -> void
-  def validate_typed_array: (Riffer::Param, Array[untyped], Array[String]) -> void
+  # : (Riffer::Params::Param, Array[untyped], Array[String]) -> void
+  def validate_typed_array: (Riffer::Params::Param, Array[untyped], Array[String]) -> void
 end

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

@@ -34,20 +34,20 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
   # --
-  # : (Hash[Symbol, untyped]) -> Aws::BedrockRuntime::Types::ConverseResponse
-  def execute_generate: (Hash[Symbol, untyped]) -> Aws::BedrockRuntime::Types::ConverseResponse
+  # : (Hash[Symbol, untyped]) -> Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+  def execute_generate: (Hash[Symbol, untyped]) -> Aws::BedrockRuntime::Client::_ConverseResponseSuccess
 
   # --
-  # : (Aws::BedrockRuntime::Types::ConverseResponse) -> Riffer::TokenUsage?
-  def extract_token_usage: (Aws::BedrockRuntime::Types::ConverseResponse) -> Riffer::TokenUsage?
+  # : (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> Riffer::Providers::TokenUsage?
 
   # --
-  # : (Aws::BedrockRuntime::Types::ConverseResponse) -> String
-  def extract_content: (Aws::BedrockRuntime::Types::ConverseResponse) -> String
+  # : (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> String
+  def extract_content: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> String
 
   # --
-  # : (Aws::BedrockRuntime::Types::ConverseResponse) -> Array[Riffer::Messages::Assistant::ToolCall]
-  def extract_tool_calls: (Aws::BedrockRuntime::Types::ConverseResponse) -> Array[Riffer::Messages::Assistant::ToolCall]
+  # : (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> Array[Riffer::Messages::Assistant::ToolCall]
+  def extract_tool_calls: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> Array[Riffer::Messages::Assistant::ToolCall]
 
   # --
   # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
@@ -67,28 +67,28 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def raise_if_stream_exception!: (untyped) -> void
 
   # --
-  # : (Aws::BedrockRuntime::Types::ContentBlockStartEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
-  def handle_content_block_start_tool_use: (Aws::BedrockRuntime::Types::ContentBlockStartEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  # : (Aws::BedrockRuntime::Types::ContentBlockStartEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_content_block_start_tool_use: (Aws::BedrockRuntime::Types::ContentBlockStartEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
 
   # --
-  # : (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
-  def handle_content_block_delta_text_delta: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  # : (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_content_block_delta_text_delta: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
 
   # --
-  # : (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
-  def handle_content_block_delta_tool_use: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  # : (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_content_block_delta_tool_use: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
 
   # --
-  # : (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
-  def handle_content_block_stop_text_delta: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  # : (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_content_block_stop_text_delta: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
 
   # --
-  # : (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
-  def handle_content_block_stop_tool_use: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  # : (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_content_block_stop_tool_use: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
 
   # --
-  # : (Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
-  def handle_metadata_usage: (Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  # : (Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_metadata_usage: (Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
 
   # --
   # : (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
@@ -103,8 +103,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def append_tool_result: (Array[Hash[Symbol, untyped]], Riffer::Messages::Tool) -> void
 
   # --
-  # : (Riffer::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_bedrock_format: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_bedrock_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
 
   BEDROCK_FORMAT_MAP: Hash[String, String]
 

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

@@ -31,8 +31,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   def execute_generate: (Hash[Symbol, untyped]) -> Anthropic::Models::Message
 
   # --
-  # : (Anthropic::Models::Message) -> Riffer::TokenUsage?
-  def extract_token_usage: (Anthropic::Models::Message) -> Riffer::TokenUsage?
+  # : (Anthropic::Models::Message) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage: (Anthropic::Models::Message) -> Riffer::Providers::TokenUsage?
 
   # --
   # : (Anthropic::Models::Message) -> String
@@ -99,8 +99,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   def convert_assistant_to_anthropic_format: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
 
   # --
-  # : (Riffer::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_anthropic_format: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_anthropic_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
 
   # --
   # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]

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

@@ -35,14 +35,14 @@ class Riffer::Providers::Base
   # Generates text using the provider.
   #
   # --
-  # : (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, **untyped) -> Riffer::Messages::Assistant
-  def generate_text: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, **untyped) -> Riffer::Messages::Assistant
+  # : (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Riffer::Messages::Assistant
+  def generate_text: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Riffer::Messages::Assistant
 
   # Streams text from the provider.
   #
   # --
-  # : (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::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::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?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]
 
   private
 
@@ -51,8 +51,8 @@ class Riffer::Providers::Base
   def encode_tool_name: (String) -> String
 
   # --
-  # : (String, tools: Array[Riffer::Tool]) -> String
-  def decode_tool_name: (String, tools: Array[Riffer::Tool]) -> String
+  # : (String, tools: Array[singleton(Riffer::Tool)]) -> String
+  def decode_tool_name: (String, tools: Array[singleton(Riffer::Tool)]) -> String
 
   # --
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -67,8 +67,8 @@ class Riffer::Providers::Base
   def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
 
   # --
-  # : (untyped) -> Riffer::TokenUsage?
-  def extract_token_usage: (untyped) -> Riffer::TokenUsage?
+  # : (untyped) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage: (untyped) -> Riffer::Providers::TokenUsage?
 
   # --
   # : (untyped) -> String
@@ -95,8 +95,8 @@ class Riffer::Providers::Base
   def validate_input!: (prompt: String?, system: String?, messages: Array[Hash[Symbol | String, untyped] | Riffer::Messages::Base]?) -> void
 
   # --
-  # : (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?) -> Array[Riffer::Messages::Base]
-  def normalize_messages: (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?) -> Array[Riffer::Messages::Base]
+  # : (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Array[Riffer::Messages::Base]
+  def normalize_messages: (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Array[Riffer::Messages::Base]
 
   # --
   # : (Array[Riffer::Messages::Base]) -> void

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

@@ -35,8 +35,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   def extract_tool_calls: (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::ToolCall]
 
   # --
-  # : (Hash[Symbol, untyped]) -> Riffer::TokenUsage?
-  def extract_token_usage: (Hash[Symbol, untyped]) -> Riffer::TokenUsage?
+  # : (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage?
 
   # --
   # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
@@ -51,8 +51,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   def convert_assistant_to_gemini_format: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
 
   # --
-  # : (Riffer::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_gemini_format: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_gemini_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
 
   # --
   # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]

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

@@ -21,6 +21,17 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
 
   # Initializes the mock provider.
   #
+  # +responses:+ accepts an array of response hashes in the same shape
+  # +#stub_response+ takes — raw +tool_calls:+ hashes are normalised to
+  # +Riffer::Messages::Assistant::ToolCall+ instances. This is the canonical
+  # way to pre-configure canned LLM responses on an agent via
+  # +provider_options responses: [...]+.
+  #
+  #   Riffer::Providers::Mock.new(responses: [
+  #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
+  #     {content: "Final answer"}
+  #   ])
+  #
   # --
   # : (**untyped) -> void
   def initialize: (**untyped) -> void
@@ -31,11 +42,11 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   #
   #   provider.stub_response("Hello")
   #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
-  #   provider.stub_response("Final response", token_usage: Riffer::TokenUsage.new(input_tokens: 10, output_tokens: 5))
+  #   provider.stub_response("Final response", token_usage: Riffer::Providers::TokenUsage.new(input_tokens: 10, output_tokens: 5))
   #
   # --
-  # : (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::TokenUsage?) -> void
-  def stub_response: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::TokenUsage?) -> void
+  # : (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?) -> void
+  def stub_response: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?) -> void
 
   # Clears all stubbed responses.
   #
@@ -45,6 +56,15 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
 
   private
 
+  # Normalises a response hash into Mock's internal format. Accepts the
+  # +#stub_response+ kwargs shape (+content:+, +tool_calls:+, +token_usage:+)
+  # or a pre-built hash with already-converted ToolCall instances. Raw
+  # +tool_calls:+ hashes are wrapped in +Riffer::Messages::Assistant::ToolCall+.
+  #
+  # --
+  # : (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def normalize_response: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
   # --
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -54,8 +74,8 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   def execute_generate: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
   # --
-  # : (untyped) -> Riffer::TokenUsage?
-  def extract_token_usage: (untyped) -> Riffer::TokenUsage?
+  # : (untyped) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage: (untyped) -> Riffer::Providers::TokenUsage?
 
   # --
   # : (untyped) -> String

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

@@ -23,8 +23,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def execute_generate: (Hash[Symbol, untyped]) -> OpenAI::Models::Responses::Response
 
   # --
-  # : (OpenAI::Models::Responses::Response) -> Riffer::TokenUsage?
-  def extract_token_usage: (OpenAI::Models::Responses::Response) -> Riffer::TokenUsage?
+  # : (OpenAI::Models::Responses::Response) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage: (OpenAI::Models::Responses::Response) -> Riffer::Providers::TokenUsage?
 
   # --
   # : (OpenAI::Models::Responses::Response) -> String
@@ -87,8 +87,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def convert_assistant_to_openai_format: (Riffer::Messages::Assistant) -> (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]])
 
   # --
-  # : (Riffer::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_openai_format: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_openai_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
 
   # --
   # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]

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

@@ -0,0 +1,85 @@
+# Generated from lib/riffer/providers/open_router.rb with RBS::Inline
+
+# OpenRouter provider for the OpenRouter unified gateway (https://openrouter.ai).
+#
+# Requires the +openai+ gem to be installed. OpenRouter exposes an
+# OpenAI-compatible Chat Completions endpoint, so this provider reuses
+# the OpenAI Ruby SDK with a +base_url+ override.
+#
+# The +api_key+ falls back to <tt>Riffer.config.openrouter.api_key</tt>
+# and then to +OPENROUTER_API_KEY+.
+class Riffer::Providers::OpenRouter < Riffer::Providers::Base
+  BASE_URL: String
+
+  # Initializes the OpenRouter provider.
+  #
+  # --
+  # : (?api_key: String?, **untyped) -> void
+  def initialize: (?api_key: String?, **untyped) -> void
+
+  private
+
+  # --
+  # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Hash[Symbol, untyped]) -> OpenAI::Models::Chat::ChatCompletion
+  def execute_generate: (Hash[Symbol, untyped]) -> OpenAI::Models::Chat::ChatCompletion
+
+  # --
+  # : (OpenAI::Models::Chat::ChatCompletion) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage: (OpenAI::Models::Chat::ChatCompletion) -> Riffer::Providers::TokenUsage?
+
+  # --
+  # : (OpenAI::Models::Chat::ChatCompletion) -> String
+  def extract_content: (OpenAI::Models::Chat::ChatCompletion) -> String
+
+  # --
+  # : (OpenAI::Models::Chat::ChatCompletion) -> Array[Riffer::Messages::Assistant::ToolCall]
+  def extract_tool_calls: (OpenAI::Models::Chat::ChatCompletion) -> Array[Riffer::Messages::Assistant::ToolCall]
+
+  # --
+  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+
+  # --
+  # : (OpenAI::Models::Chat::ChatCompletionChunk, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_stream_chunk: (OpenAI::Models::Chat::ChatCompletionChunk, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+
+  # --
+  # : (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_text_delta: (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+
+  # --
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_reasoning_delta: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+
+  # --
+  # : (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_tool_call_deltas: (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+
+  # --
+  # : (state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def emit_tool_call_done_events: (state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+
+  # --
+  # : (OpenAI::Models::Chat::ChatCompletionChunk::Choice) -> bool
+  def finish_reason_is_tool_calls?: (OpenAI::Models::Chat::ChatCompletionChunk::Choice) -> bool
+
+  # --
+  # : (Array[Riffer::Messages::Base]) -> Array[Hash[Symbol, untyped]]
+  def convert_messages_to_chat_completions_format: (Array[Riffer::Messages::Base]) -> Array[Hash[Symbol, untyped]]
+
+  # --
+  # : (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
+  def convert_assistant_to_chat_completions_format: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_chat_completions_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+
+  # --
+  # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+  def convert_tool_to_chat_completions_format: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+end

data/sig/generated/riffer/{token_usage.rbs → providers/token_usage.rbs}

@@ -1,14 +1,14 @@
-# Generated from lib/riffer/token_usage.rb with RBS::Inline
+# Generated from lib/riffer/providers/token_usage.rb with RBS::Inline
 
 # Represents token usage data from an LLM API call.
 #
 # Tracks input tokens, output tokens, and optional cache statistics.
 #
-#   token_usage = Riffer::TokenUsage.new(input_tokens: 100, output_tokens: 50)
+#   token_usage = Riffer::Providers::TokenUsage.new(input_tokens: 100, output_tokens: 50)
 #   token_usage.total_tokens  # => 150
 #
 #   combined = token_usage1 + token_usage2  # Combine multiple token usage objects
-class Riffer::TokenUsage
+class Riffer::Providers::TokenUsage
   # Number of tokens in the input/prompt.
   attr_reader input_tokens: Integer
 
@@ -34,8 +34,8 @@ class Riffer::TokenUsage
   # Combines two TokenUsage objects for cumulative tracking.
   #
   # --
-  # : (Riffer::TokenUsage) -> Riffer::TokenUsage
-  def +: (Riffer::TokenUsage) -> Riffer::TokenUsage
+  # : (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
+  def +: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
 
   # Converts the token usage to a hash representation.
   #

data/sig/generated/riffer/providers.rbs

@@ -6,6 +6,7 @@
 # - Riffer::Providers::OpenAI - OpenAI GPT models
 # - Riffer::Providers::AzureOpenAI - Azure OpenAI GPT models
 # - Riffer::Providers::AmazonBedrock - AWS Bedrock models
+# - Riffer::Providers::OpenRouter - OpenRouter unified gateway
 # - Riffer::Providers::Mock - Mock provider for testing
 module Riffer::Providers
 end

data/sig/generated/riffer/runner/fibers.rbs

@@ -22,6 +22,6 @@ class Riffer::Runner::Fibers < Riffer::Runner
   def initialize: (?max_concurrency: Integer?) -> void
 
   # --
-  # : (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
-  def map: (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
+  # : (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
+  def map: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
 end

data/sig/generated/riffer/runner/sequential.rbs

@@ -5,6 +5,6 @@
 # This is the default runner used when no concurrency is needed.
 class Riffer::Runner::Sequential < Riffer::Runner
   # --
-  # : (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
-  def map: (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
+  # : (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
+  def map: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
 end

data/sig/generated/riffer/runner/threaded.rbs

@@ -21,6 +21,6 @@ class Riffer::Runner::Threaded < Riffer::Runner
   def initialize: (?max_concurrency: Integer) -> void
 
   # --
-  # : (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
-  def map: (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
+  # : (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
+  def map: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
 end

data/sig/generated/riffer/runner.rbs

@@ -17,6 +17,6 @@ class Riffer::Runner
   # Raises NotImplementedError if not implemented by subclass.
   #
   # --
-  # : (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
-  def map: (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
+  # : (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
+  def map: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
 end

data/sig/generated/riffer/skills/activate_tool.rbs

@@ -9,10 +9,11 @@
 class Riffer::Skills::ActivateTool < Riffer::Tool
   # Activates a skill by name and returns its body.
   #
-  # [context] tool context containing +:skills+ (a Riffer::Skills::Context).
+  # [context] the agent's +Riffer::Agent::Context+, exposing +#skills+
+  #           (a +Riffer::Skills::Context+).
   # [name] the skill name to activate.
   #
   # --
-  # : (context: Hash[Symbol, untyped]?, name: String) -> Riffer::Tools::Response
-  def call: (context: Hash[Symbol, untyped]?, name: String) -> Riffer::Tools::Response
+  # : (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
+  def call: (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
 end