riffer 0.48.0 → 0.49.0

data/lib/riffer/providers/gemini/client.rb

@@ -5,18 +5,8 @@ require "json"
 require "net/http"
 require "uri"
 
-# HTTP transport for the Gemini REST API. Riffer builds one from the
-# configured +api_key+ by default; construct your own to tune the HTTP knobs
-# and assign it to <tt>Riffer.config.gemini.client</tt>. Any object
-# implementing +post+ and +post_stream+ with these contracts works there —
-# the class is a default implementation, not a required base.
-#
-#   Riffer.configure do |config|
-#     config.gemini.client = Riffer::Providers::Gemini::Client.new(
-#       api_key: ENV["GEMINI_API_KEY"],
-#       read_timeout: 120
-#     )
-#   end
+# <tt>Riffer.config.gemini.client</tt> accepts any object implementing +post+ and +post_stream+
+# with these contracts; this class is the default, not a required base.
 class Riffer::Providers::Gemini::Client
   # @rbs @api_key: String?
   # @rbs @base_url: String
@@ -43,8 +33,7 @@ class Riffer::Providers::Gemini::Client
     @proxy_port = proxy_port
   end
 
-  # POSTs a JSON body to an API path and returns the parsed response hash.
-  # Raises Riffer::Error when the API responds with a non-success status.
+  # Raises Riffer::Error on a non-success status.
   #--
   #: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def post(path, body)
@@ -54,9 +43,7 @@ class Riffer::Providers::Gemini::Client
     JSON.parse(response.body, symbolize_names: true)
   end
 
-  # POSTs a JSON body to an API path, yielding raw response body chunks as
-  # they arrive. Raises Riffer::Error when the API responds with a
-  # non-success status.
+  # Raises Riffer::Error on a non-success status.
   #--
   #: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
   def post_stream(path, body, &block)

data/lib/riffer/providers/gemini.rb

@@ -4,7 +4,6 @@
 require "json"
 require "securerandom"
 
-# Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
   VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._-]+\z/ #: Regexp
 
@@ -29,7 +28,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     "FINISH_REASON_UNSPECIFIED" => :other,
   }.freeze #: Hash[String, Symbol]
 
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -76,10 +74,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       }]
     end
 
-    # tags propagate to observability only: the Gemini Developer API has no
-    # request labels field (unknown body fields are rejected), so :tags is
-    # stripped here rather than mapped. Native labels would arrive with a Vertex
-    # adapter. See docs/CONFIGURATION.md.
+    # The Gemini Developer API has no request labels field and rejects unknown
+    # body fields, so :tags reach observability only.
     generation_config = options.except(:tools, :structured_output, :tags)
 
     if structured_output
@@ -144,8 +140,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     build_finish_reason(response.dig(:candidates, 0, :finishReason), tool_calls: has_function_call)
   end
 
-  # Gemini reports STOP even when the candidate carries functionCall parts,
-  # so tool-call presence overrides the raw value.
   #--
   #: (String?, tool_calls: bool) -> Riffer::Providers::FinishReason?
   def build_finish_reason(raw_reason, tool_calls:)
@@ -153,18 +147,18 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
 
     raw = raw_reason.to_s
     reason = FINISH_REASONS.fetch(raw, :other)
+    # Gemini reports STOP even when the candidate carries functionCall parts.
     reason = :tool_calls if reason == :stop && tool_calls
     Riffer::Providers::FinishReason.new(reason: reason, raw: raw)
   end
 
-  # Gemini reports thinking tokens outside +candidatesTokenCount+;
-  # TokenUsage's output includes them.
   #--
   #: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage
   def build_token_usage(usage)
     apply_pricing(
       Riffer::Providers::TokenUsage.new(
         input_tokens: usage[:promptTokenCount] || 0,
+        # Gemini reports thinking tokens outside candidatesTokenCount.
         output_tokens: (usage[:candidatesTokenCount] || 0) + (usage[:thoughtsTokenCount] || 0),
         cache_read_tokens: usage[:cachedContentTokenCount],
       ),

data/lib/riffer/providers/mock.rb

@@ -1,41 +1,28 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Mock provider for mocking LLM responses in tests; no external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
   # @rbs @responses: Array[Hash[Symbol, untyped]]
   # @rbs @current_index: Integer
   # @rbs @stubbed_responses: Array[Hash[Symbol, untyped]]
 
-  # Returns the skill adapter for the mock model — XML when the model name
-  # contains +claude+ (mirroring a real Claude provider), else Markdown.
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(model = nil)
+    # Mirrors the adapter a real Claude provider picks.
     return Riffer::Skills::XmlAdapter if model&.include?("claude")
 
     Riffer::Skills::MarkdownAdapter
   end
 
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
     "mock"
   end
 
-  # Array of recorded method calls for assertions.
   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
-  # <tt>agent.provider</tt> via +#stub_response+ instead.
-  #
-  #   Riffer::Providers::Mock.new(responses: [
-  #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
-  #     {content: "Final answer"}
-  #   ])
-  #
   #--
   #: (?responses: Array[Hash[Symbol, untyped]]) -> void
   def initialize(responses: [])
@@ -46,16 +33,6 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     @stubbed_responses = []
   end
 
-  # Stubs the next response; call repeatedly to queue several. +finish_reason+
-  # defaults to +:tool_calls+ when tool calls are present, else +:stop+.
-  #
-  #   provider.stub_response("Hello")
-  #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
-  #   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?, ?reasoning: Array[Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart]) -> void
   def stub_response(content, tool_calls: [], token_usage: nil, finish_reason: nil, reasoning: [])
@@ -68,8 +45,6 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     )
   end
 
-  # Clears all stubbed responses.
-  #
   #--
   #: () -> void
   def clear_stubs

data/lib/riffer/providers/open_ai.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# OpenAI provider for GPT models. Requires the +openai+ gem.
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_preview" #: String
 
-  # The Responses API has no finish_reason field. The response +status+ is
-  # the primary signal; an +incomplete+ status is only meaningful together
-  # with <tt>incomplete_details.reason</tt>, so that branch nests one level.
+  # The Responses API has no finish_reason field, and an +incomplete+ status is only meaningful
+  # together with <tt>incomplete_details.reason</tt>.
   FINISH_REASONS = {
     "completed" => :stop,
     "incomplete" => {
@@ -20,7 +18,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     "queued" => :other,
   }.freeze #: Hash[String, Symbol | Hash[String, Symbol]]
 
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -48,12 +45,11 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     Riffer.config.openai.client
   end
 
-  # Compacted so an unset value stays absent: the SDK reads +OPENAI_API_KEY+ /
-  # +OPENAI_BASE_URL+ only for a missing argument, and an explicit nil would
-  # suppress that fallback.
   #--
   #: () -> untyped
   def build_client
+    # The SDK falls back to +OPENAI_API_KEY+ / +OPENAI_BASE_URL+ only for a missing argument; an
+    # explicit nil suppresses that fallback.
     ::OpenAI::Client.new(**{
       api_key: Riffer.config.openai.api_key,
       base_url: Riffer.config.openai.base_url,
@@ -80,10 +76,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     } #: Hash[Symbol, untyped]
 
     unless tags.empty?
-      # Merged over any metadata set in model_options; a tag wins on a shared key.
       params[:metadata] = (params[:metadata] || {}).merge(tags)
-      # The reserved user_id also maps to the native safety identifier while
-      # staying in metadata as an ordinary tag.
       user_id = tags["user_id"]
       params[:safety_identifier] = user_id if user_id
     end
@@ -165,7 +158,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     Riffer::Providers::FinishReason.new(reason: reason, raw: detail || status)
   end
 
-  # The nested field that names the cause behind an ambiguous status.
   #--
   #: (untyped, String) -> String?
   def finish_detail(response, status)
@@ -255,9 +247,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         end
       end
     ensure
-      # OpenAI SDK does not auto-close the underlying HTTP stream when
-      # iteration is interrupted (raise / fiber cancellation), so the SSE
-      # socket leaks until GC. close is idempotent and a no-op after EOF.
+      # The SDK doesn't close the SSE socket when iteration is interrupted (raise / fiber
+      # cancellation), so it leaks until GC. close is idempotent and a no-op after EOF.
       stream.close
     end
 
@@ -349,8 +340,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     action = event.item.action
     case action
     when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::OpenPage
-      # OpenPage carries a url but no query or sources, so it doesn't fit
-      # WebSearchDone — emit as a status notification instead.
+      # OpenPage carries a url but no query or sources, so it doesn't fit WebSearchDone.
       yielder << Riffer::StreamEvents::WebSearchStatus.new("open_page", url: action.url)
     when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::Search
       sources = (action.sources || []).map { |s| { title: nil, url: s.url } }

data/lib/riffer/providers/open_router.rb

@@ -3,10 +3,6 @@
 
 require "json"
 
-# OpenRouter provider (https://openrouter.ai). Requires the +openai+ gem —
-# OpenRouter exposes an OpenAI-compatible endpoint, so this reuses the OpenAI
-# SDK with a +base_url+ override. +api_key+ resolves from config, then
-# +OPENROUTER_API_KEY+.
 class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   BASE_URL = "https://openrouter.ai/api/v1" #: String
 
@@ -19,7 +15,27 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     "error" => :error,
   }.freeze #: Hash[String, Symbol]
 
-  # The GenAI semconv well-known provider name.
+  REASONING_TYPES = {
+    "reasoning.text" => :text,
+    "reasoning.summary" => :summary,
+    "reasoning.encrypted" => :encrypted,
+  }.freeze #: Hash[String, Symbol]
+
+  # The +reasoning_details+ formats OpenRouter documents. Only parts tagged with
+  # one of them are replayed, so parts from other adapters, or with no format,
+  # never reach the request.
+  REASONING_FORMATS = %w[
+    unknown
+    openai-responses-v1
+    azure-openai-responses-v1
+    bedrock-openai-responses-v1
+    bedrock-xai-responses-v1
+    xai-responses-v1
+    meta-responses-v1
+    anthropic-claude-v1
+    google-gemini-v1
+  ].freeze #: Array[String]
+
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -47,15 +63,12 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     Riffer.config.openrouter.client
   end
 
-  # Deliberately not compacted: this borrows the OpenAI SDK to talk to a
-  # different vendor, so omitting an unset +api_key+ would let the SDK fall
-  # back to +OPENAI_API_KEY+ and send an OpenAI credential to OpenRouter.
-  # Passing nil raises in the SDK instead. +OPENROUTER_API_KEY+ is read here
-  # rather than left to the SDK for the same reason.
   #--
   #: () -> untyped
   def build_client
     api_key = Riffer.config.openrouter.api_key || ENV.fetch("OPENROUTER_API_KEY", nil)
+    # Pass a nil api_key rather than omitting it: an omitted key lets the SDK
+    # fall back to OPENAI_API_KEY and send an OpenAI credential to OpenRouter.
     ::OpenAI::Client.new(api_key: api_key, base_url: BASE_URL)
   end
 
@@ -74,7 +87,6 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     } #: Hash[Symbol, untyped]
 
     unless tags.empty?
-      # Merged over any metadata set in model_options; a tag wins on a shared key.
       params[:metadata] = (params[:metadata] || {}).merge(tags)
       # OpenRouter exposes the legacy Chat Completions user field rather than
       # safety_identifier; the reserved user_id maps there and stays in metadata.
@@ -138,8 +150,6 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     build_finish_reason(choice&.finish_reason, native: native_finish_reason(choice))
   end
 
-  # +native+ is the upstream model's own finish reason, which OpenRouter
-  # reports alongside its normalized one; it wins as +raw+ when present.
   #--
   #: (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason(finish_reason, native: nil)
@@ -148,15 +158,17 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     normalized = finish_reason.to_s
     return nil if normalized.empty?
 
+    # OpenRouter reports the upstream model's own finish reason alongside its
+    # normalized one.
     raw = native.to_s.empty? ? normalized : native.to_s
     Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(normalized, :other), raw: raw)
   end
 
-  # +native_finish_reason+ is outside the OpenAI schema, so it is only
-  # reachable through the SDK model's raw data hash.
   #--
   #: (untyped) -> untyped
   def native_finish_reason(choice)
+    # Outside the OpenAI schema, so only reachable through the SDK model's raw
+    # data hash.
     choice && choice.to_h[:native_finish_reason]
   end
 
@@ -188,6 +200,39 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     end
   end
 
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning(response)
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    message = typed_response.choices.first&.message
+    details = message && reasoning_details(message)
+    (details || []).filter_map { |detail| build_reasoning_part(detail) }
+  end
+
+  # The openai gem's typed models strip fields outside OpenAI's spec, so
+  # +reasoning_details+ is only reachable through the model's raw data hash.
+  #--
+  #: (untyped) -> Array[Hash[Symbol, untyped]]?
+  def reasoning_details(model)
+    model[:reasoning_details]
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
+  def build_reasoning_part(detail)
+    type = REASONING_TYPES.fetch(detail[:type], nil)
+    return nil unless type
+
+    Riffer::Messages::Assistant::ReasoningPart.new(
+      type: type,
+      text: detail[:text] || detail[:summary],
+      data: detail[:data],
+      signature: detail[:signature],
+      id: detail[:id],
+      format: detail[:format],
+    )
+  end
+
   #--
   #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
@@ -197,17 +242,14 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
 
     state = {
       text: +"",
-      reasoning: +"",
+      reasoning_details: {},
       tool_calls: {},
       finish_reason: nil,
       native_finish_reason: nil,
     } #: Hash[Symbol, untyped]
 
-    # Use stream_raw (not stream) — the latter yields a higher-level
-    # ChatChunkEvent helper that aggregates content/tool calls into typed
-    # events. We want raw ChatCompletionChunk objects with
-    # +choices.first.delta+ so we can map deltas to Riffer::StreamEvents
-    # ourselves.
+    # stream_raw, not stream: stream aggregates chunks into higher-level
+    # events, but mapping to Riffer::StreamEvents needs the raw deltas.
     stream = client.chat.completions.stream_raw(**stream_params)
     begin
       stream.each do |chunk|
@@ -224,7 +266,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     emit_tool_call_done_events(state: state, yielder: yielder) unless state[:tool_calls].empty?
 
     yielder << Riffer::StreamEvents::TextDone.new(state[:text]) unless state[:text].empty?
-    yield_reasoning_done(yielder, state[:reasoning]) unless state[:reasoning].empty?
+    state[:reasoning_details].each_value do |detail|
+      part = build_reasoning_part(detail)
+      yielder << Riffer::StreamEvents::ReasoningDone.new(part) if part
+    end
     yield_finish_reason(yielder, build_finish_reason(state[:finish_reason], native: state[:native_finish_reason]))
   end
 
@@ -265,14 +310,26 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_reasoning_delta(delta, state:, yielder:)
-    # The openai gem's typed Delta model strips fields not in OpenAI's spec
-    # (so +delta.reasoning+ raises NoMethodError), but the underlying data
-    # hash retains them. Access via +#[]+ which reads from BaseModel#@data.
-    reasoning = delta[:reasoning] if delta.respond_to?(:[])
-    return if reasoning.nil? || reasoning.empty?
-
-    state[:reasoning] << reasoning
-    yielder << Riffer::StreamEvents::ReasoningDelta.new(reasoning)
+    details = reasoning_details(delta)
+    return if details.nil?
+
+    details.each do |detail|
+      accumulate_reasoning_detail(state[:reasoning_details], detail)
+      text = detail[:text] || detail[:summary]
+      yielder << Riffer::StreamEvents::ReasoningDelta.new(text) unless text.nil? || text.empty?
+    end
+  end
+
+  # OpenRouter streams one reasoning block as many fragments sharing an
+  # +index+: prose and payload arrive in pieces to concatenate, while the
+  # signature, id, and format arrive once, often on the last fragment. Keying
+  # on +type+ as well keeps index-less fragments of different kinds apart.
+  #--
+  #: (Hash[untyped, Hash[Symbol, untyped]], Hash[Symbol, untyped]) -> void
+  def accumulate_reasoning_detail(accumulated, detail)
+    entry = accumulated[[detail[:index], detail[:type]]] ||= { type: detail[:type] }
+    %i[text summary data].each { |key| (entry[key] ||= +"") << detail[key] if detail[key] }
+    %i[signature id format].each { |key| entry[key] = detail[key] if detail[key] }
   end
 
   #--
@@ -369,9 +426,27 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
       end
     end
 
+    details = message.reasoning.filter_map do |part|
+      convert_reasoning_part_to_detail(part) if REASONING_FORMATS.include?(part.format)
+    end
+    msg[:reasoning_details] = details unless details.empty?
+
     msg
   end
 
+  #--
+  #: (Riffer::Messages::Assistant::ReasoningPart) -> Hash[Symbol, untyped]
+  def convert_reasoning_part_to_detail(part)
+    {
+      type: REASONING_TYPES.key(part.type),
+      (part.type == :summary ? :summary : :text) => part.text,
+      data: part.data,
+      signature: part.signature,
+      id: part.id,
+      format: part.format,
+    }.compact
+  end
+
   #--
   #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_chat_completions_format(file)

data/lib/riffer/providers/repository.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Resolves provider classes by identifier, combining the built-in REPO with
-# consumer registrations added through +register+. Registration is not
-# synchronized — register during boot, before concurrent generation begins.
 module Riffer::Providers::Repository
   extend self
 
@@ -22,11 +19,8 @@ module Riffer::Providers::Repository
 
   @registrations = {} #: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
-  # Registers a custom provider under +identifier+, resolved lazily by the block.
-  # Takes precedence over a built-in sharing the identifier.
-  #
-  #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
-  #
+  # Not synchronized — register during boot, before concurrent generation
+  # begins.
   #--
   #: ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
   def register(identifier, &factory)
@@ -34,8 +28,6 @@ module Riffer::Providers::Repository
     @key_for = nil
   end
 
-  # Removes a custom registration by identifier, leaving any built-in of the
-  # same name intact.
   #--
   #: ((String | Symbol)) -> void
   def unregister(identifier)
@@ -43,9 +35,6 @@ module Riffer::Providers::Repository
     @key_for = nil
   end
 
-  # Finds a provider class by identifier, preferring a custom registration over
-  # a built-in of the same name.
-  #
   #--
   #: ((String | Symbol)) -> singleton(Riffer::Providers::Base)?
   def find(identifier)
@@ -53,7 +42,6 @@ module Riffer::Providers::Repository
     (@registrations[key] || REPO[key])&.call
   end
 
-  # Returns the registry identifier for a provider class, or nil when unregistered.
   #--
   #: (singleton(Riffer::Providers::Base)) -> Symbol?
   def key_for(provider_class)

data/lib/riffer/providers/token_usage.rb

@@ -1,11 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Normalized token usage for an LLM API call. Buckets carry the same
-# meaning for every provider.
 class Riffer::Providers::TokenUsage
-  # Builds a TokenUsage from a hash, or returns +usage+ unchanged when it is
-  # already a TokenUsage.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Providers::TokenUsage)) -> Riffer::Providers::TokenUsage
   def self.from_hash(usage)
@@ -20,19 +16,19 @@ class Riffer::Providers::TokenUsage
     )
   end
 
-  # Number of tokens entering the context window, including cache reads and writes.
+  # Normalized across providers: includes cache reads and writes.
   attr_reader :input_tokens #: Integer # @dynamic input_tokens
 
-  # Number of tokens generated by the model, including reasoning/thinking tokens.
+  # Includes reasoning/thinking tokens.
   attr_reader :output_tokens #: Integer # @dynamic output_tokens
 
-  # Subset of +input_tokens+ written to the provider's prompt cache, when the provider reports it.
+  # Subset of +input_tokens+.
   attr_reader :cache_write_tokens #: Integer? # @dynamic cache_write_tokens
 
-  # Subset of +input_tokens+ read from the provider's prompt cache, when the provider reports it.
+  # Subset of +input_tokens+.
   attr_reader :cache_read_tokens #: Integer? # @dynamic cache_read_tokens
 
-  # Cost of the call, set when the model is priced. For observability, not billing.
+  # For observability, not billing.
   attr_reader :cost #: Float? # @dynamic cost
 
   #--
@@ -45,16 +41,12 @@ class Riffer::Providers::TokenUsage
     @cost = cost
   end
 
-  # Returns the total number of tokens (input + output).
-  #
   #--
   #: () -> Integer
   def total_tokens
     input_tokens + output_tokens
   end
 
-  # Combines two TokenUsage objects for cumulative tracking.
-  #
   #--
   #: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
   def +(other)
@@ -67,7 +59,6 @@ class Riffer::Providers::TokenUsage
     )
   end
 
-  # Converts the token usage to a hash; cache tokens and cost are omitted when nil.
   #--
   #: () -> Hash[Symbol, (Integer | Float)]
   def to_h