riffer 0.48.0 → 0.49.0

data/lib/riffer/params.rb

@@ -1,16 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# A DSL for defining tool parameters and structured-output schemas, used within
-# a Tool's +params+ block.
-#
-#   params do
-#     required :city, String, description: "The city name"
-#     optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
-#   end
-#
 class Riffer::Params
-  # The defined parameters.
   attr_reader :parameters #: Array[Riffer::Params::Param] # @dynamic parameters
 
   #--
@@ -19,13 +10,8 @@ class Riffer::Params
     @parameters = []
   end
 
-  # Reconstructs a Params from a JSON Schema object — the inverse of
-  # +to_json_schema(strict: false)+. Raises Riffer::ArgumentError on features
-  # outside the Params-expressible subset of JSON Schema.
-  #
-  #   schema = params.to_json_schema(strict: false)
-  #   Riffer::Params.from_json_schema(schema) # => equivalent Riffer::Params
-  #
+  # The inverse of +to_json_schema(strict: false)+. Raises Riffer::ArgumentError
+  # on features outside the Params-expressible subset of JSON Schema.
   #--
   #: (Hash[Symbol, untyped]) -> Riffer::Params
   def self.from_json_schema(schema)
@@ -42,8 +28,6 @@ class Riffer::Params
     params
   end
 
-  # Defines a required parameter.
-  #
   #--
   #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
   def required(name, type, description: nil, enum: nil, of: nil, &)
@@ -59,8 +43,6 @@ class Riffer::Params
     )
   end
 
-  # Defines an optional parameter.
-  #
   #--
   #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
   def optional(name, type, description: nil, enum: nil, default: nil, of: nil, &)
@@ -77,15 +59,6 @@ class Riffer::Params
     )
   end
 
-  # Validates arguments against parameter definitions.
-  #
-  # A Float param accepts an Integer (JSON Schema <tt>"number"</tt> covers
-  # integers) and its value is coerced with +to_f+, so callers always get a
-  # Float. The same holds for the items of an <tt>of: Float</tt> array. No other
-  # type is coerced.
-  #
-  # Raises Riffer::ValidationError if validation fails.
-  #
   #--
   #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def validate(arguments)
@@ -125,11 +98,6 @@ class Riffer::Params
     validated
   end
 
-  # Converts all parameters to JSON Schema format. When +strict+ is true, every
-  # property is listed in +required+ and optional ones are made nullable
-  # instead, satisfying providers that enforce strict structured output schemas.
-  # Raises Riffer::ArgumentError when +strict+ and a Hash param (at any depth)
-  # has no block or an Array param has neither a block nor <tt>of:</tt>.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)
@@ -138,6 +106,8 @@ class Riffer::Params
 
     @parameters.each do |param|
       properties[param.name.to_s] = param.to_json_schema(strict: strict)
+      # Providers enforcing strict structured output require every property in
+      # +required+; strict mode makes optional ones nullable instead.
       required_params << param.name.to_s if strict || param.required
     end
 
@@ -151,8 +121,8 @@ 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.
+  # Without this, +dup+ shares parameters, so defining one on either copy
+  # would reach the other.
   #--
   #: (Riffer::Params) -> void
   def initialize_copy(source)
@@ -233,7 +203,6 @@ class Riffer::Params
     end
   end
 
-  # Returns the array with its valid items coerced by +coerce_value+.
   #--
   #: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
   def validate_typed_array(param, value, errors)
@@ -258,13 +227,11 @@ class Riffer::Params
     end
   end
 
-  # Coerces an already-validated value to the Ruby type its param declares.
-  # Only Float coerces today, because JSON Schema "number" accepts integers and
-  # callers should not get a type that depends on whether the model wrote a
-  # decimal point. Add a branch here rather than inline at a call site.
   #--
   #: (Module, untyped) -> untyped
   def coerce_value(type, value)
+    # JSON Schema "number" accepts integers; callers shouldn't get a type that
+    # depends on whether the model wrote a decimal point.
     return value.to_f if type == Float
 
     value

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
@@ -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,9 @@ 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. Merged over any request_metadata
-    # set in model_options; a tag wins on a shared key.
+    # 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?
@@ -109,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",
@@ -130,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)
@@ -173,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)
@@ -183,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,
@@ -245,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
@@ -263,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)
@@ -288,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")
 
@@ -333,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)
@@ -358,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:)
@@ -415,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|
@@ -431,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)

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)

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,11 +24,11 @@ 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::User::FilePart]?, **untyped) -> Riffer::Messages::Assistant
   def generate_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
@@ -77,8 +67,6 @@ 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::User::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
@@ -119,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
@@ -218,19 +202,17 @@ 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
 
-  # 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)
+    # Optional hook, so providers that don't expose replayable reasoning stay valid.
     []
   end
 
@@ -295,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)
@@ -358,11 +338,10 @@ 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)
+    # 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

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)