riffer 0.47.2 → 0.49.0

data/lib/riffer/providers/amazon_bedrock.rb

@@ -3,11 +3,8 @@
 
 require "base64"
 
-# Amazon Bedrock provider for Claude and other foundation models. Requires the
-# +aws-sdk-bedrockruntime+ gem.
 class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
-  # Matches Anthropic models on Bedrock — bare (+anthropic.claude-...+) and
-  # cross-region (+us.anthropic.claude-...+) ids.
+  # Bedrock ids are bare (+anthropic.claude-...+) or cross-region (+us.anthropic.claude-...+).
   ANTHROPIC_MODEL_PATTERN = /(?:^|\.)anthropic\./ #: Regexp
 
   FINISH_REASONS = {
@@ -22,8 +19,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     "model_context_window_exceeded" => :context_window,
   }.freeze #: Hash[String, Symbol]
 
-  # Returns the skill adapter for the Bedrock model — XML for Anthropic models
-  # (which Bedrock hosts alongside other vendors'), else Markdown.
+  # Only parts carrying this tag are replayed, so reasoning captured by another
+  # adapter, whose signatures Converse cannot verify, never reaches the request.
+  REASONING_FORMAT = "bedrock-converse-v1" #: String
+
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(model = nil)
@@ -32,7 +31,6 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     Riffer::Skills::MarkdownAdapter
   end
 
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -47,7 +45,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
@@ -60,13 +58,13 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     Riffer.config.amazon_bedrock.client
   end
 
-  # Compacted so an unset region stays absent: the AWS SDK resolves +AWS_REGION+
-  # and the shared config only for a missing argument, and raises
-  # +Aws::Errors::MissingRegionError+ on an explicit nil.
   #--
   #: () -> untyped
   def build_client
     api_token = Riffer.config.amazon_bedrock.api_token
+    # Compacted out when unset: the AWS SDK resolves +AWS_REGION+ and the shared
+    # config only for a missing argument, and raises
+    # +Aws::Errors::MissingRegionError+ on an explicit nil.
     region = Riffer.config.amazon_bedrock.region
 
     if api_token && !api_token.empty?
@@ -96,10 +94,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       **options.except(:tools, :structured_output, :cache_control, :tags),
     } #: Hash[Symbol, untyped]
 
-    # 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, so every tag (including the
+    # reserved user_id) rides along in requestMetadata; a tag wins over a
+    # model_options request_metadata key.
+    params[:request_metadata] = (params[:request_metadata] || {}).merge(tags) unless tags.empty?
 
     if tools && !tools.empty?
       params[:tool_config] = {
@@ -108,9 +106,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     end
 
     if structured_output
-      # Use strict schema to make optional fields nullable. Without this,
-      # Bedrock may return string literals like ": null," instead of actual
-      # null values for optional fields that the model has no value for.
+      # Strict makes optional fields nullable; otherwise Bedrock may return
+      # string literals like ": null," for optional fields with no value.
       params[:output_config] = {
         text_format: {
           type: "json_schema",
@@ -129,13 +126,13 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     params
   end
 
-  # Converse treats +tools -> system -> messages+ as one prefix and looks back
-  # from a +cachePoint+ for the longest cached run, so the point on the final
-  # message reuses the previous step's cache wherever that point sat. Mixed
-  # ttls must be ordered 1h before 5m, so both points share one.
   #--
   #: (Hash[Symbol, untyped], untyped) -> void
   def apply_cache_point(params, cache_control)
+    # Converse treats +tools -> system -> messages+ as one prefix and looks back
+    # from a +cachePoint+ for the longest cached run, so the point on the final
+    # message reuses the previous step's cache wherever that point sat. Mixed
+    # ttls must be ordered 1h before 5m, so both points share one.
     cache_point = { cache_point: build_cache_point(cache_control) }
     system = params[:system]
     tools = params.dig(:tool_config, :tools)
@@ -172,8 +169,6 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     build_token_usage(typed_response.usage)
   end
 
-  # Converse's +input_tokens+ excludes the cache buckets; TokenUsage's
-  # input includes them.
   #--
   #: (untyped) -> Riffer::Providers::TokenUsage
   def build_token_usage(usage)
@@ -182,6 +177,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
 
     apply_pricing(
       Riffer::Providers::TokenUsage.new(
+        # Converse's +input_tokens+ excludes the cache buckets; TokenUsage's includes them.
         input_tokens: usage.input_tokens + (cache_write || 0) + (cache_read || 0),
         output_tokens: usage.output_tokens,
         cache_write_tokens: cache_write,
@@ -244,12 +240,50 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     tool_calls
   end
 
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning(response)
+    typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+    content_blocks = typed_response.output&.message&.content || []
+
+    content_blocks.filter_map do |block|
+      case (reasoning = block.reasoning_content)
+      when Aws::BedrockRuntime::Types::ReasoningContentBlock::RedactedContent
+        build_reasoning_part(redacted_content: reasoning.redacted_content)
+      when Aws::BedrockRuntime::Types::ReasoningContentBlock::ReasoningText
+        build_reasoning_part(text: reasoning.reasoning_text.text, signature: reasoning.reasoning_text.signature)
+      end
+    end
+  end
+
+  # +redacted_content+ is raw bytes; it is stored Base64-encoded so the part
+  # survives JSON persistence.
+  #--
+  #: (?text: String?, ?signature: String?, ?redacted_content: String?) -> Riffer::Messages::Assistant::ReasoningPart
+  def build_reasoning_part(text: nil, signature: nil, redacted_content: nil)
+    if redacted_content
+      Riffer::Messages::Assistant::ReasoningPart.new(
+        type: :encrypted,
+        data: Base64.strict_encode64(redacted_content),
+        format: REASONING_FORMAT,
+      )
+    else
+      Riffer::Messages::Assistant::ReasoningPart.new(
+        type: :text,
+        text: text,
+        signature: signature,
+        format: REASONING_FORMAT,
+      )
+    end
+  end
+
   #--
   #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     current_state = {
       text: nil,
       tool_call: nil,
+      reasoning: nil,
     } #: Hash[Symbol, untyped]
 
     stream_completed = false
@@ -262,19 +296,19 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
         when Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
           handle_content_block_delta_text_delta(event, state: current_state, yielder: yielder) if event.delta&.text
           handle_content_block_delta_tool_use(event, state: current_state, yielder: yielder) if event.delta&.tool_use
+          handle_reasoning_delta(event, state: current_state, yielder: yielder) if event.delta&.reasoning_content
         when Aws::BedrockRuntime::Types::ContentBlockStopEvent
           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]
+          handle_reasoning_stop(event, state: current_state, yielder: yielder) if current_state[:reasoning]
         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.
+          # The SDK hands an event-stream +:message-type: error+ frame to this
+          # block as an EventError event rather than raising it.
           raise_stream_event_error!(event)
         else
           raise_if_stream_exception!(event)
@@ -287,27 +321,22 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     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)
+    # The SDK's own +#message+ is just the class name.
     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. 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)
+    # ConverseStream delivers API errors on the same channel as content.
+    # Unconsumed non-exception events (including the SDK's +:unknown_event+
+    # struct) are ignored for forward compatibility.
     klass_name = event.class.name&.split("::")&.last
     return unless klass_name&.end_with?("Exception")
 
@@ -332,11 +361,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def handle_content_block_delta_text_delta(event, state:, yielder:)
     typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
     delta_text = typed_event.delta.text
-    # Mutating append: += would reallocate and copy the whole accumulated
-    # buffer on every delta (O(n^2) per content block). state[:text] is handed
-    # off to TextDone and then cleared on block stop, so nothing reads the
-    # pre-append string, making in-place mutation safe. Seed with an unfrozen
-    # String (+"") so << does not raise under frozen_string_literal.
+    # << avoids += copying the whole buffer per delta (O(n^2)); safe because
+    # nothing reads the pre-append string before block stop clears it.
     state[:text] ||= +""
     state[:text] << delta_text
     yielder << Riffer::StreamEvents::TextDelta.new(delta_text)
@@ -357,6 +383,29 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     )
   end
 
+  # A reasoning block streams its text in pieces, then its signature (or its
+  # redacted bytes) in a delta of its own.
+  #--
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_reasoning_delta(event, state:, yielder:)
+    typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
+    delta = typed_event.delta.reasoning_content
+    reasoning = state[:reasoning] ||= { text: +"" }
+
+    reasoning[:text] << delta.text if delta.text
+    reasoning[:signature] = delta.signature if delta.signature
+    (reasoning[:redacted_content] ||= +"") << delta.redacted_content if delta.redacted_content
+
+    yielder << Riffer::StreamEvents::ReasoningDelta.new(delta.text) unless delta.text.nil? || delta.text.empty?
+  end
+
+  #--
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_reasoning_stop(_event, state:, yielder:)
+    yielder << Riffer::StreamEvents::ReasoningDone.new(build_reasoning_part(**state[:reasoning]))
+    state[:reasoning] = nil
+  end
+
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_text_delta(_event, state:, yielder:)
@@ -414,7 +463,9 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   #--
   #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
   def convert_assistant_to_bedrock_format(message)
-    content = [] #: Array[Hash[Symbol, untyped]]
+    content = message.reasoning.filter_map do |part|
+      convert_reasoning_part_to_bedrock_format(part) if part.format == REASONING_FORMAT
+    end
     content << { text: message.content } if message.content && !message.content.empty?
 
     message.tool_calls.each do |tc|
@@ -430,6 +481,15 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     { role: "assistant", content: content }
   end
 
+  #--
+  #: (Riffer::Messages::Assistant::ReasoningPart) -> Hash[Symbol, untyped]
+  def convert_reasoning_part_to_bedrock_format(part)
+    data = part.data
+    return { reasoning_content: { redacted_content: Base64.strict_decode64(data) } } if data
+
+    { reasoning_content: { reasoning_text: { text: part.text, signature: part.signature }.compact } }
+  end
+
   #--
   #: (Array[Hash[Symbol, untyped]], Riffer::Messages::Tool) -> void
   def append_tool_result(conversation_messages, message)
@@ -449,7 +509,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

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Anthropic provider for Claude models via the Anthropic API. Requires the
-# +anthropic+ gem.
 class Riffer::Providers::Anthropic < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_20250305" #: String
 
@@ -18,15 +16,12 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     "pause_turn" => :other,
   }.freeze #: Hash[String, Symbol]
 
-  # Returns the XML skill adapter for Anthropic/Claude.
-  #
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(_model = nil)
     Riffer::Skills::XmlAdapter
   end
 
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -48,12 +43,11 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     Riffer.config.anthropic.client
   end
 
-  # Compacted for the same reason as the other providers: never hand an SDK an
-  # explicit nil credential, so its own +ANTHROPIC_API_KEY+ resolution stays
-  # reachable regardless of how that SDK distinguishes nil from absent.
   #--
   #: () -> untyped
   def build_client
+    # Never pass an explicit nil credential, so the SDK's own
+    # ANTHROPIC_API_KEY resolution stays reachable.
     ::Anthropic::Client.new(**{ api_key: Riffer.config.anthropic.api_key }.compact)
   end
 
@@ -78,8 +72,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
 
     # Anthropic's only request-metadata field is metadata.user_id (opaque, no
-    # PII). It carries the reserved user_id tag; all other tags are dropped
-    # here and survive only on spans.
+    # PII); all other tags survive only on spans.
     user_id = tags["user_id"]
     params[:metadata] = { user_id: user_id } if user_id
 
@@ -93,13 +86,9 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     end
 
     if structured_output
-      # Use strict schema to make optional fields nullable. Without this,
-      # Anthropic may return empty strings or whitespace instead of null
-      # for optional fields that the model has no value for.
-      #
-      # Merged over any caller-supplied output_config (e.g. effort) so those
-      # keys survive; the structured-output format wins because the run loop
-      # validates the response against it.
+      # Strict schema makes optional fields nullable; otherwise Anthropic may
+      # return empty strings or whitespace instead of null. The format wins
+      # over caller output_config keys because the run loop validates against it.
       params[:output_config] = {
         **(params[:output_config] || {}),
         format: {
@@ -143,8 +132,6 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(raw, :other), raw: raw)
   end
 
-  # Anthropic's +input_tokens+ excludes the cache buckets; TokenUsage's
-  # input includes them.
   #--
   #: (untyped) -> Riffer::Providers::TokenUsage
   def build_token_usage(usage)
@@ -153,6 +140,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
 
     apply_pricing(
       Riffer::Providers::TokenUsage.new(
+        # Anthropic's input_tokens excludes the cache buckets; TokenUsage's includes them.
         input_tokens: usage.input_tokens + (cache_write || 0) + (cache_read || 0),
         output_tokens: usage.output_tokens,
         cache_write_tokens: cache_write,
@@ -287,11 +275,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_text_event(event, state:, yielder:)
-    # Mutating append instead of += to avoid reallocating and copying the whole
-    # accumulated buffer on every delta (O(n^2) per content block). The buffer
-    # is handed to TextDone and cleared on block stop, so no reader observes the
-    # pre-append string. Seed with an unfrozen String so << is legal under
-    # frozen_string_literal.
+    # Mutating append avoids O(n^2) copying per content block; the buffer is
+    # handed to TextDone and cleared on block stop, so no reader sees it mid-append.
     state[:text] ||= +""
     state[:text] << event.text
     yielder << Riffer::StreamEvents::TextDelta.new(event.text)
@@ -338,7 +323,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
 
@@ -444,7 +429,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/azure_open_ai.rb

@@ -1,11 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Azure OpenAI provider for GPT models hosted on Azure. Requires the +openai+
-# gem. Credentials resolve from config, then +AZURE_OPENAI_API_KEY+ /
-# +AZURE_OPENAI_ENDPOINT+.
 class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -20,15 +16,14 @@ class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
     Riffer.config.azure_openai.client
   end
 
-  # Deliberately not compacted: this borrows the OpenAI SDK to talk to Azure, so
-  # omitting an unset argument would let the SDK fall back to +OPENAI_API_KEY+
-  # and +OPENAI_BASE_URL+ — sending Azure traffic, and an OpenAI credential, to
-  # whatever those name. Passing nil raises in the SDK instead.
   #--
   #: () -> untyped
   def build_client
     api_key = Riffer.config.azure_openai.api_key || ENV.fetch("AZURE_OPENAI_API_KEY", nil)
     base_url = Riffer.config.azure_openai.endpoint || ENV.fetch("AZURE_OPENAI_ENDPOINT", nil)
+    # Pass nils rather than omitting them: an omitted argument lets the SDK fall
+    # back to OPENAI_API_KEY / OPENAI_BASE_URL, sending Azure traffic and an
+    # OpenAI credential elsewhere. A nil raises in the SDK instead.
     ::OpenAI::Client.new(api_key: api_key, base_url: base_url)
   end
 end

data/lib/riffer/providers/base.rb

@@ -3,10 +3,6 @@
 
 require "json"
 
-# Base class for all LLM providers. A template-method flow: subclasses implement
-# the hooks (+build_request_params+, +execute_generate+, +execute_stream+,
-# +extract_token_usage+, +extract_content+, +extract_tool_calls+) and the base
-# class orchestrates them.
 class Riffer::Providers::Base
   # @rbs @current_tools: Array[singleton(Riffer::Tool)]
   # @rbs @current_model: String?
@@ -15,18 +11,12 @@ class Riffer::Providers::Base
 
   WIRE_SEPARATOR = "__" #: String
 
-  # Returns the preferred skill adapter for this provider; override in
-  # subclasses (optionally introspecting +model+) for provider-specific formats.
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(_model = nil)
     Riffer::Skills::MarkdownAdapter
   end
 
-  # Returns the provider name stamped as <tt>gen_ai.provider.name</tt> on trace
-  # spans, ideally a GenAI semconv well-known value. Defaults to the snake_cased
-  # class name rather than raising like the abstract provider methods, so
-  # enabling tracing never breaks an otherwise-working custom provider.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -34,13 +24,13 @@ class Riffer::Providers::Base
     # later must pick up its real name, not a frozen "unknown".
     class_name = name or return "unknown"
 
+    # A default rather than NotImplementedError, so enabling tracing never
+    # breaks an otherwise-working custom provider.
     @semconv_provider_name ||= Riffer::Helpers::Identifier.derive(class_name.split("::").last)
   end
 
-  # 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)]
@@ -56,6 +46,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?
@@ -67,6 +58,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,
@@ -75,10 +67,8 @@ class Riffer::Providers::Base
     end
   end
 
-  # 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)]
@@ -105,7 +95,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(_file)
     :url
   end
@@ -117,21 +107,17 @@ class Riffer::Providers::Base
     Riffer::Helpers::Dependencies.depends_on(gem_name)
   end
 
-  # Returns the client for the current LLM call. A configured client wins,
-  # resolved on every call so a Proc can vary the client by process or
-  # credential lifetime; otherwise the provider builds one from the configured
-  # credentials, memoized for the life of the provider.
   #--
   #: () -> untyped
   def client
     configured = global_client
+    # Resolved on every call, never memoized, so a Proc can vary the client by
+    # process or credential lifetime.
     return Riffer::Helpers::CallOrValue.resolve(configured) if configured
 
     @client ||= build_client
   end
 
-  # Returns the consumer-configured client for this provider; nil when none is
-  # configured, and for providers that take no configuration at all.
   #--
   #: () -> untyped
   def global_client
@@ -216,14 +202,20 @@ class Riffer::Providers::Base
     pricing.rates_for("#{key}/#{model}")
   end
 
-  # Defaults to nil rather than raising — finish reasons are optional, so
-  # providers that don't report one stay valid.
   #--
   #: (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason(_response)
+    # Optional hook, so providers that don't report a finish reason stay valid.
     nil
   end
 
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning(_response)
+    # Optional hook, so providers that don't expose replayable reasoning stay valid.
+    []
+  end
+
   #--
   #: (untyped) -> String
   def extract_content(response)
@@ -285,8 +277,6 @@ class Riffer::Providers::Base
     attributes.merge(tag_attributes(options[:tags] || {}))
   end
 
-  # Maps normalized tags to their namespaced span attribute form. An empty map
-  # yields an empty hash, so merging it is a no-op.
   #--
   #: (Hash[String, String]) -> Hash[String, String]
   def tag_attributes(tags)
@@ -348,6 +338,14 @@ class Riffer::Providers::Base
     Riffer.config.tracing.capture_messages && span.recording?
   end
 
+  #--
+  #: (Riffer::Providers::_EventSink, String) -> void
+  def yield_reasoning_done(yielder, text)
+    # No +format+, so the reasoning persists for display but is never replayed.
+    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)
@@ -368,11 +366,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
 
   #--
@@ -397,7 +395,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"
@@ -407,7 +405,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

@@ -1,19 +1,13 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Normalized reason an LLM call finished, paired with the provider's raw
-# wire value. +reason+ carries the same meaning for every provider.
 class Riffer::Providers::FinishReason
-  # The normalized vocabulary every provider maps into.
   VALUES = %i[stop length tool_calls content_filter context_window malformed_output error other].freeze #: Array[Symbol]
 
-  # The normalized reason.
   attr_reader :reason #: Symbol # @dynamic reason
 
-  # The provider's raw finish-reason value, when one exists on the wire.
   attr_reader :raw #: String? # @dynamic raw
 
-  # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   #--
   #: (reason: Symbol, ?raw: String?) -> void
   def initialize(reason:, raw: nil)