riffer 0.47.1 → 0.48.0

data/lib/riffer/messages/base.rb

@@ -12,40 +12,22 @@ class Riffer::Messages::Base
   def self.from_hash(msg)
     return msg if msg.is_a?(Riffer::Messages::Base)
 
-    raise Riffer::ArgumentError, "Message must be a Hash or Message object, got #{msg.class}" unless msg.is_a?(Hash)
-
     raise Riffer::ArgumentError, "Message hash must include a 'role' key" if msg[:role].nil? || msg[:role].empty?
 
     case msg[:role].to_sym
-    when :user
-      files = (msg[:files] || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
-      Riffer::Messages::User.new(msg[:content], id: msg[:id], files: files)
-    when :assistant
-      tool_calls = (msg[:tool_calls] || []).map do |tc|
-        tc.is_a?(Riffer::Messages::Assistant::ToolCall) ? tc : Riffer::Messages::Assistant::ToolCall.new(**tc)
-      end
-      Riffer::Messages::Assistant.new(
-        msg[:content],
-        id: msg[:id],
-        tool_calls: tool_calls,
-        structured_output: msg[:structured_output],
-        finish_reason: msg[:finish_reason]&.to_sym,
-        finish_reason_raw: msg[:finish_reason_raw],
-      )
-    when :system
-      Riffer::Messages::System.new(msg[:content], id: msg[:id])
-    when :tool
-      Riffer::Messages::Tool.new(msg[:content], id: msg[:id], tool_call_id: msg[:tool_call_id], name: msg[:name])
-    else
-      raise Riffer::ArgumentError, "Unknown message role: #{msg[:role]}"
+    when :user then Riffer::Messages::User.from_hash(msg)
+    when :assistant then Riffer::Messages::Assistant.from_hash(msg)
+    when :system then Riffer::Messages::System.from_hash(msg)
+    when :tool then Riffer::Messages::Tool.from_hash(msg)
+    else raise Riffer::ArgumentError, "Unknown message role: #{msg[:role]}"
     end
   end
 
   # The message content.
-  attr_reader :content #: String
+  attr_reader :content #: String # @dynamic content
 
   # The message id, or nil when +Riffer.config.message_id_strategy+ is +:none+.
-  attr_reader :id #: String?
+  attr_reader :id #: String? # @dynamic id
 
   #--
   #: (String, ?id: String?) -> void

data/lib/riffer/messages/system.rb

@@ -3,6 +3,16 @@
 
 # Represents a system message (instructions) in a conversation.
 class Riffer::Messages::System < Riffer::Messages::Base
+  # Builds a System message from a hash, or returns +msg+ unchanged when it is
+  # already a System message.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::System)) -> Riffer::Messages::System
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::System)
+
+    new(msg[:content], id: msg[:id])
+  end
+
   #--
   #: () -> Symbol
   def role

data/lib/riffer/messages/tool.rb

@@ -3,18 +3,35 @@
 
 # Represents a tool execution result in a conversation.
 class Riffer::Messages::Tool < Riffer::Messages::Base
+  # Builds a Tool message from a hash, or returns +msg+ unchanged when it is
+  # already a Tool message.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Tool)) -> Riffer::Messages::Tool
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::Tool)
+
+    new(
+      msg[:content],
+      id: msg[:id],
+      tool_call_id: msg[:tool_call_id],
+      name: msg[:name],
+      error: msg[:error],
+      error_type: msg[:error_type]&.to_sym,
+    )
+  end
+
   # The ID of the tool call this result responds to.
-  attr_reader :tool_call_id #: String
+  attr_reader :tool_call_id #: String # @dynamic tool_call_id
 
   # The name of the tool that was called.
-  attr_reader :name #: String
+  attr_reader :name #: String # @dynamic name
 
   # The error message if the tool execution failed.
-  attr_reader :error #: String?
+  attr_reader :error #: String? # @dynamic error
 
   # The type of error (:unknown_tool, :validation_error, :execution_error,
   # :timeout_error, :unhandled_error).
-  attr_reader :error_type #: Symbol?
+  attr_reader :error_type #: Symbol? # @dynamic error_type
 
   #--
   #: (String, tool_call_id: String, name: String, ?id: String?, ?error: String?, ?error_type: Symbol?) -> void

data/lib/riffer/messages/{file_part.rb → user/file_part.rb}

@@ -6,7 +6,7 @@ require "uri"
 
 # Represents a file attachment (image or document) — from a URL (+from_url+) or
 # raw base64 data (+new+).
-class Riffer::Messages::FilePart
+class Riffer::Messages::User::FilePart
   # @rbs @url_string: String?
   # @rbs @data: String?
   # @rbs @downloaded_data: String?
@@ -29,13 +29,13 @@ class Riffer::Messages::FilePart
   SHA256_PATTERN = /\A[0-9a-f]{64}\z/i #: Regexp
 
   # The MIME type of the file.
-  attr_reader :media_type #: String
+  attr_reader :media_type #: String # @dynamic media_type
 
   # The filename, if available.
-  attr_reader :filename #: String?
+  attr_reader :filename #: String? # @dynamic filename
 
   # The expected SHA-256 of the file contents, if the caller supplied one.
-  attr_reader :sha256 #: String?
+  attr_reader :sha256 #: String? # @dynamic sha256
 
   # Raises Riffer::ArgumentError unless +data+ or +url+ is given and
   # +media_type+ is supported.
@@ -62,26 +62,18 @@ class Riffer::Messages::FilePart
   # 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?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::FilePart
+  #: (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::User::FilePart
   def self.from_url(url, media_type: nil, filename: nil, sha256: nil)
-    unless media_type
-      ext = ::File.extname(URI.parse(url).path.to_s).downcase
-      media_type = MEDIA_TYPES[ext]
-      raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" unless media_type
-    end
-
-    new(url: url, media_type: media_type, filename: filename, sha256: sha256)
+    new(url: url, media_type: media_type || detect_media_type(url), filename: filename, sha256: sha256)
   end
 
   # Builds a FilePart from a +{url:, media_type:}+ or +{data:, media_type:}+ hash,
   # or returns +file+ unchanged when it is already a FilePart. Raises
   # Riffer::ArgumentError on an invalid hash.
   #--
-  #: ((Hash[Symbol, untyped] | Riffer::Messages::FilePart)) -> Riffer::Messages::FilePart
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::User::FilePart)) -> Riffer::Messages::User::FilePart
   def self.from_hash(file)
-    return file if file.is_a?(Riffer::Messages::FilePart)
-
-    raise Riffer::ArgumentError, "File must be a Hash or FilePart object, got #{file.class}" unless file.is_a?(Hash)
+    return file if file.is_a?(Riffer::Messages::User::FilePart)
 
     url = file[:url]
     data = file[:data]
@@ -90,7 +82,7 @@ class Riffer::Messages::FilePart
     sha256 = file[:sha256]
 
     if url
-      from_url(url, media_type: media_type, filename: filename, sha256: sha256)
+      new(url: url, data: data, media_type: media_type || detect_media_type(url), filename: filename, sha256: sha256)
     elsif data && media_type
       new(data: data, media_type: media_type, filename: filename, sha256: sha256)
     else
@@ -98,6 +90,15 @@ class Riffer::Messages::FilePart
     end
   end
 
+  # Raises Riffer::ArgumentError when the URL's extension isn't a known media type.
+  #--
+  #: (String) -> String
+  def self.detect_media_type(url)
+    ext = ::File.extname(URI.parse(url).path.to_s).downcase
+    MEDIA_TYPES.fetch(ext) { raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" }
+  end
+  private_class_method :detect_media_type
+
   # 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.
   #--

data/lib/riffer/messages/user.rb

@@ -3,11 +3,22 @@
 
 # Represents a user message in a conversation.
 class Riffer::Messages::User < Riffer::Messages::Base
+  # Builds a User message from a hash, or returns +msg+ unchanged when it is
+  # already a User message. Raises Riffer::ArgumentError on an invalid file.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::User)) -> Riffer::Messages::User
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::User)
+
+    files = (msg[:files] || []).map { |f| Riffer::Messages::User::FilePart.from_hash(f) }
+    new(msg[:content], id: msg[:id], files: files)
+  end
+
   # File attachments for this message.
-  attr_reader :files #: Array[Riffer::Messages::FilePart]
+  attr_reader :files #: Array[Riffer::Messages::User::FilePart] # @dynamic files
 
   #--
-  #: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
+  #: (String, ?id: String?, ?files: Array[Riffer::Messages::User::FilePart]) -> void
   def initialize(content, id: nil, files: [])
     super(content, id: id)
     @files = files

data/lib/riffer/params/param.rb

@@ -31,28 +31,28 @@ class Riffer::Params::Param
   }.freeze #: Hash[String, Module]
 
   # The parameter name.
-  attr_reader :name #: Symbol
+  attr_reader :name #: Symbol # @dynamic name
 
   # The Ruby type.
-  attr_reader :type #: Module
+  attr_reader :type #: Module # @dynamic type
 
   # Whether the parameter is required.
-  attr_reader :required #: bool
+  attr_reader :required #: bool # @dynamic required
 
   # The parameter description, if any.
-  attr_reader :description #: String?
+  attr_reader :description #: String? # @dynamic description
 
   # Allowed values, if constrained.
-  attr_reader :enum #: Array[untyped]?
+  attr_reader :enum #: Array[untyped]? # @dynamic enum
 
   # The default value, if any.
-  attr_reader :default #: untyped
+  attr_reader :default #: untyped # @dynamic default
 
   # Element type for a typed array (+of:+).
-  attr_reader :item_type #: Module?
+  attr_reader :item_type #: Module? # @dynamic item_type
 
   # Nested Params for object / array-of-object types.
-  attr_reader :nested_params #: Riffer::Params?
+  attr_reader :nested_params #: Riffer::Params? # @dynamic nested_params
 
   # Reconstructs a Param from a single JSON Schema property. Raises
   # Riffer::ArgumentError on a type outside the Params-expressible subset.
@@ -181,6 +181,18 @@ class Riffer::Params::Param
 
   private
 
+  # +dup+ would leave the copy sharing this one's nested Params, enum list and
+  # default, so defining a parameter or editing either value on one would reach
+  # the other.
+  #--
+  #: (Riffer::Params::Param) -> void
+  def initialize_copy(source)
+    super
+    @nested_params = source.nested_params&.dup
+    @enum = Riffer::Helpers::DeepDup.call(source.enum)
+    @default = Riffer::Helpers::DeepDup.call(source.default)
+  end
+
   #--
   #: () -> void
   def validate_strict_shape!

data/lib/riffer/params.rb

@@ -11,7 +11,7 @@
 #
 class Riffer::Params
   # The defined parameters.
-  attr_reader :parameters #: Array[Riffer::Params::Param]
+  attr_reader :parameters #: Array[Riffer::Params::Param] # @dynamic parameters
 
   #--
   #: () -> void
@@ -151,6 +151,15 @@ class Riffer::Params
 
   private
 
+  # +dup+ would leave the copy sharing this one's parameters, so a caller
+  # defining a parameter on either would reach the other.
+  #--
+  #: (Riffer::Params) -> void
+  def initialize_copy(source)
+    super
+    @parameters = source.parameters.map(&:dup)
+  end
+
   #--
   #: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def build_nested(type, of, &block)

data/lib/riffer/providers/amazon_bedrock.rb

@@ -47,7 +47,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(file)
     file.url&.start_with?("s3://") ? :url : :bytes
   end
@@ -98,8 +98,9 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
 
     # requestMetadata is a flat String=>String map used to filter invocation
     # logs; every tag (including the reserved user_id) rides along, since
-    # Converse has no dedicated end-user field.
-    params[:request_metadata] = tags unless tags.empty?
+    # Converse has no dedicated end-user field. Merged over any request_metadata
+    # set in model_options; a tag wins on a shared key.
+    params[:request_metadata] = (params[:request_metadata] || {}).merge(tags) unless tags.empty?
 
     if tools && !tools.empty?
       params[:tool_config] = {
@@ -154,7 +155,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   #: (untyped) -> Hash[Symbol, untyped]
   def build_cache_point(cache_control)
     point = { type: "default" } #: Hash[Symbol, untyped]
-    ttl = cache_control.is_a?(Hash) ? cache_control[:ttl] : nil
+    ttl = cache_control[:ttl] if cache_control.is_a?(Hash)
     point[:ttl] = ttl if ttl
     point
   end
@@ -252,6 +253,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       tool_call: nil,
     } #: Hash[Symbol, untyped]
 
+    stream_completed = false
+
     client.converse_stream(**params) do |stream|
       stream.on_event do |event|
         case event
@@ -264,20 +267,45 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
           handle_content_block_stop_text_delta(event, state: current_state, yielder: yielder) if current_state[:text]
           handle_content_block_stop_tool_use(event, state: current_state, yielder: yielder) if current_state[:tool_call]
         when Aws::BedrockRuntime::Types::MessageStopEvent
+          stream_completed = true
           yield_finish_reason(yielder, build_finish_reason(event.stop_reason))
         when Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent
           handle_metadata_usage(event, state: current_state, yielder: yielder) if event.usage
+        when Aws::Errors::EventError
+          # The SDK turns an event-stream +:message-type: error+ frame into an
+          # EventError instance and hands it to this block as an event; it is
+          # never raised. Re-raise it here so the failure surfaces instead of
+          # truncating the stream.
+          raise_stream_event_error!(event)
         else
           raise_if_stream_exception!(event)
         end
       end
     end
+
+    return if stream_completed
+
+    raise Riffer::IncompleteStreamError, "Bedrock ConverseStream ended without a messageStop event"
+  end
+
+  # Re-raises an +Aws::Errors::EventError+ event with a message built from its
+  # error code and message. The SDK's own +#message+ is just the class name,
+  # so without this the failure would be unreadable.
+  #--
+  #: (untyped) -> void
+  def raise_stream_event_error!(event)
+    details = [event.error_code, event.error_message].compact.join(": ")
+    details = "Bedrock ConverseStream error event" if details.empty?
+
+    raise event.exception(details)
   end
 
   # Re-raises a Bedrock stream-exception event as the matching
   # +Aws::BedrockRuntime::Errors+ class. ConverseStream delivers API errors on
   # the same channel as content, so without this a mid-stream failure would
-  # silently end the stream with no content.
+  # silently end the stream with no content. Non-exception events that we do
+  # not consume (including the SDK's +:unknown_event+ struct) are ignored for
+  # forward compatibility.
   #--
   #: (untyped) -> void
   def raise_if_stream_exception!(event)
@@ -422,7 +450,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_bedrock_format(file)
     format = bedrock_format(file.media_type)
 

data/lib/riffer/providers/anthropic.rb

@@ -211,6 +211,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       web_search_query: nil,
     } #: Hash[Symbol, untyped]
 
+    stream_completed = false
+
     # Workaround for anthropics/anthropic-sdk-ruby#182: force identity
     # encoding so Net::HTTP/Zlib doesn't buffer SSE chunks until EOF.
     stream = client.messages.stream(
@@ -247,6 +249,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
             handle_content_block_stop_web_search_result(event, state: current_state, yielder: yielder)
           end
         when ::Anthropic::Helpers::Streaming::MessageStopEvent
+          stream_completed = true
           handle_message_stop(event, accumulated_message: stream.accumulated_message, yielder: yielder)
         end
       end
@@ -256,6 +259,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       # socket leaks until GC. close is idempotent and a no-op after EOF.
       stream.close
     end
+
+    return if stream_completed
+
+    raise Riffer::IncompleteStreamError, "Anthropic stream ended without a message_stop event"
   end
 
   #--
@@ -331,7 +338,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_thinking(_event, state:, yielder:)
-    yielder << Riffer::StreamEvents::ReasoningDone.new(state[:reasoning])
+    yield_reasoning_done(yielder, state[:reasoning])
     state[:reasoning] = nil
   end
 
@@ -437,7 +444,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_anthropic_format(file)
     type = file.image? ? "image" : "document"
 

data/lib/riffer/providers/base.rb

@@ -30,10 +30,9 @@ class Riffer::Providers::Base
   #--
   #: () -> String
   def self.semconv_provider_name
-    class_name = name
     # Anonymous classes stay uncached: a class assigned to a constant
     # later must pick up its real name, not a frozen "unknown".
-    return "unknown" unless class_name
+    class_name = name or return "unknown"
 
     @semconv_provider_name ||= Riffer::Helpers::Identifier.derive(class_name.split("::").last)
   end
@@ -41,7 +40,7 @@ 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::Messages::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::User::FilePart]?, **untyped) -> Riffer::Messages::Assistant
   def generate_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
     @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
@@ -57,6 +56,7 @@ class Riffer::Providers::Base
 
       content = extract_content(response)
       tool_calls = extract_tool_calls(response)
+      reasoning = extract_reasoning(response)
       token_usage = extract_token_usage(response)
       finish_reason = extract_finish_reason(response)
       structured_output = parse_structured_output(content) if options[:structured_output] && tool_calls.empty?
@@ -68,6 +68,7 @@ class Riffer::Providers::Base
       Riffer::Messages::Assistant.new(
         content,
         tool_calls: tool_calls,
+        reasoning: reasoning,
         token_usage: token_usage,
         structured_output: structured_output,
         finish_reason: finish_reason&.reason,
@@ -79,7 +80,7 @@ class Riffer::Providers::Base
   # 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::Messages::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::User::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
     @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
@@ -106,7 +107,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(_file)
     :url
   end
@@ -225,6 +226,14 @@ class Riffer::Providers::Base
     nil
   end
 
+  # Defaults to no parts rather than raising — reasoning parts are optional, so
+  # providers that don't expose replayable reasoning stay valid.
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning(_response)
+    []
+  end
+
   #--
   #: (untyped) -> String
   def extract_content(response)
@@ -349,6 +358,15 @@ class Riffer::Providers::Base
     Riffer.config.tracing.capture_messages && span.recording?
   end
 
+  # Wraps reasoning text that an adapter cannot yet replay in a +:text+ part
+  # with no +format+, so it persists for display but is never sent back.
+  #--
+  #: (Riffer::Providers::_EventSink, String) -> void
+  def yield_reasoning_done(yielder, text)
+    part = Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: text)
+    yielder << Riffer::StreamEvents::ReasoningDone.new(part)
+  end
+
   #--
   #: (Riffer::Providers::_EventSink, Riffer::Providers::FinishReason?) -> void
   def yield_finish_reason(yielder, finish_reason)
@@ -369,11 +387,11 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((String | Hash[String, untyped])?) -> Hash[String, untyped]
+  #: (String) -> Hash[String, untyped]
   def parse_tool_arguments(arguments)
-    return {} if arguments.nil? || arguments.empty?
+    return {} if arguments.empty?
 
-    arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+    JSON.parse(arguments)
   end
 
   #--
@@ -398,7 +416,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Array[Riffer::Messages::Base]
+  #: (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> Array[Riffer::Messages::Base]
   def normalize_messages(prompt:, system:, messages:, files: nil)
     if messages && files && !files.empty?
       raise Riffer::ArgumentError, "cannot provide both files and messages; attach files to individual messages instead"
@@ -408,7 +426,7 @@ class Riffer::Providers::Base
 
     result = [] #: Array[Riffer::Messages::Base]
     result << Riffer::Messages::System.new(system) if system
-    file_parts = (files || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
+    file_parts = (files || []).map { |f| Riffer::Messages::User::FilePart.from_hash(f) }
     prompt_text = prompt #: String
     result << Riffer::Messages::User.new(prompt_text, files: file_parts)
     result

data/lib/riffer/providers/finish_reason.rb

@@ -8,10 +8,10 @@ class Riffer::Providers::FinishReason
   VALUES = %i[stop length tool_calls content_filter context_window malformed_output error other].freeze #: Array[Symbol]
 
   # The normalized reason.
-  attr_reader :reason #: Symbol
+  attr_reader :reason #: Symbol # @dynamic reason
 
   # The provider's raw finish-reason value, when one exists on the wire.
-  attr_reader :raw #: String?
+  attr_reader :raw #: String? # @dynamic raw
 
   # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   #--

data/lib/riffer/providers/gemini.rb

@@ -37,7 +37,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(_file)
     :base64
   end
@@ -287,7 +287,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_gemini_format(file)
     { inlineData: { mimeType: file.media_type, data: file.data } }
   end

data/lib/riffer/providers/mock.rb

@@ -25,7 +25,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   end
 
   # Array of recorded method calls for assertions.
-  attr_reader :calls #: Array[Hash[Symbol, untyped]]
+  attr_reader :calls #: Array[Hash[Symbol, untyped]] # @dynamic calls
 
   # +responses:+ pre-configures canned responses (same shape as
   # +#stub_response+) for standalone use; agent tests queue responses on
@@ -54,15 +54,17 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   #   provider.stub_response("Final response",
   #                          token_usage: Riffer::Providers::TokenUsage.new(input_tokens: 10, output_tokens: 5))
   #   provider.stub_response("Truncated...", finish_reason: :length)
+  #   provider.stub_response("Answer", reasoning: [{type: :text, text: "Thinking...", format: "mock-v1"}])
   #
   #--
-  #: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?) -> void
-  def stub_response(content, tool_calls: [], token_usage: nil, finish_reason: nil)
+  #: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?, ?reasoning: Array[Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart]) -> void
+  def stub_response(content, tool_calls: [], token_usage: nil, finish_reason: nil, reasoning: [])
     @stubbed_responses << normalize_response(
       content: content,
       tool_calls: tool_calls,
       token_usage: token_usage,
       finish_reason: finish_reason,
+      reasoning: reasoning,
     )
   end
 
@@ -92,6 +94,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
       role: response[:role] || "assistant",
       content: response[:content] || "",
       tool_calls: formatted_tool_calls,
+      reasoning: (response[:reasoning] || []).map { |part| Riffer::Messages::Assistant::ReasoningPart.from_hash(part) },
       token_usage: response[:token_usage],
       finish_reason: response[:finish_reason] || (formatted_tool_calls.empty? ? :stop : :tool_calls),
     }
@@ -129,6 +132,12 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     reason ? Riffer::Providers::FinishReason.new(reason: reason) : nil
   end
 
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning(response)
+    response[:reasoning] || []
+  end
+
   #--
   #: (untyped) -> String
   def extract_content(response)
@@ -149,6 +158,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     tool_calls = response[:tool_calls] || []
     token_usage = response[:token_usage]
     web_search = response[:web_search]
+    reasoning = response[:reasoning] || []
 
     if web_search
       yielder << Riffer::StreamEvents::WebSearchStatus.new("in_progress")
@@ -161,6 +171,12 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
       )
     end
 
+    reasoning.each do |part|
+      text = part.text
+      yielder << Riffer::StreamEvents::ReasoningDelta.new(text) if text
+      yielder << Riffer::StreamEvents::ReasoningDone.new(part)
+    end
+
     unless full_content.empty?
       content_parts = full_content.split(". ").map { |part| part + (part.end_with?(".") ? "" : ".") }
       content_parts.each do |part|