riffer 0.32.0 → 0.33.0

data/lib/riffer/providers/anthropic.rb

@@ -6,6 +6,14 @@
 class Riffer::Providers::Anthropic < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_20250305" #: String
 
+  FINISH_REASONS = {
+    "end_turn" => :stop,
+    "stop_sequence" => :stop,
+    "max_tokens" => :length,
+    "tool_use" => :tool_calls,
+    "refusal" => :content_filter
+  }.freeze #: Hash[String, Symbol]
+
   # Returns the XML skill adapter for Anthropic/Claude.
   #
   #--
@@ -14,6 +22,13 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     Riffer::Skills::XmlAdapter
   end
 
+  # The GenAI semconv well-known provider name.
+  #--
+  #: () -> String
+  def self.semconv_provider_name
+    "anthropic"
+  end
+
   #--
   #: (?api_key: String?, **untyped) -> void
   def initialize(api_key: nil, **options)
@@ -81,14 +96,39 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     message = response #: Anthropic::Models::Message
-    usage = message.usage
+    build_token_usage(message.usage)
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason(response)
+    message = response #: Anthropic::Models::Message
+    build_finish_reason(message.stop_reason)
+  end
 
-    Riffer::Providers::TokenUsage.new(
-      input_tokens: usage.input_tokens,
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason(stop_reason)
+    return nil unless stop_reason
+
+    raw = stop_reason.to_s
+    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)
+    cache_write = usage.cache_creation_input_tokens
+    cache_read = usage.cache_read_input_tokens
+
+    apply_pricing(Riffer::Providers::TokenUsage.new(
+      input_tokens: usage.input_tokens + (cache_write || 0) + (cache_read || 0),
       output_tokens: usage.output_tokens,
-      cache_write_tokens: usage.cache_creation_input_tokens,
-      cache_read_tokens: usage.cache_read_input_tokens
-    )
+      cache_write_tokens: cache_write,
+      cache_read_tokens: cache_read
+    ))
   end
 
   #--
@@ -130,7 +170,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     current_state = {
       text: nil,
@@ -200,7 +240,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_text_event(event, state:, yielder:)
     state[:text] ||= ""
     state[:text] += event.text
@@ -208,7 +248,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_thinking_event(event, state:, yielder:)
     state[:reasoning] ||= ""
     state[:reasoning] += event.thinking
@@ -216,7 +256,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_input_json_event(event, state:, yielder:)
     if state[:tool_call].nil?
       state[:tool_call] = {id: nil, name: nil, arguments: ""}
@@ -230,7 +270,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_tool_use(event, state:, yielder:)
     content_block = event.content_block
     arguments = content_block.input.is_a?(String) ? content_block.input : content_block.input.to_json
@@ -244,21 +284,21 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (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])
     state[:reasoning] = nil
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_text(_event, state:, yielder:)
     yielder << Riffer::StreamEvents::TextDone.new(state[:text])
     state[:text] = nil
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_server_tool_use(_event, state:, yielder:)
     return unless state[:web_search_json]
 
@@ -270,7 +310,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_web_search_result(event, state:, yielder:)
     content_block = event.content_block
     sources = (content_block.content || []).filter_map do |item|
@@ -283,20 +323,15 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, accumulated_message: untyped, yielder: Enumerator::Yielder) -> void
+  #: (untyped, accumulated_message: untyped, yielder: Riffer::Providers::_EventSink) -> void
   def handle_message_stop(_event, accumulated_message:, yielder:)
     message = accumulated_message #: Anthropic::Models::Message?
+    yield_finish_reason(yielder, build_finish_reason(message&.stop_reason))
+
     usage = message&.usage
     return unless usage
 
-    yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::Providers::TokenUsage.new(
-        input_tokens: usage.input_tokens,
-        output_tokens: usage.output_tokens,
-        cache_write_tokens: usage.cache_creation_input_tokens,
-        cache_read_tokens: usage.cache_read_input_tokens
-      )
-    )
+    yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: build_token_usage(usage))
   end
 
   #--

data/lib/riffer/providers/azure_open_ai.rb

@@ -5,6 +5,13 @@
 # gem. Credentials resolve from kwargs, then 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
+    "azure.ai.openai"
+  end
+
   #--
   #: (**untyped) -> void
   def initialize(**options)

data/lib/riffer/providers/base.rb

@@ -9,6 +9,7 @@ require "json"
 # class orchestrates them.
 class Riffer::Providers::Base
   # @rbs @current_tools: Array[singleton(Riffer::Tool)]
+  # @rbs @current_model: String?
 
   WIRE_SEPARATOR = "__" #: String
 
@@ -20,6 +21,19 @@ class Riffer::Providers::Base
     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
+    class_name = name
+    return "unknown" unless class_name
+
+    Riffer::Helpers::ClassNameConverter.convert(class_name.split("::").last.to_s)
+  end
+
   # Generates text using the provider.
   #
   #--
@@ -27,23 +41,35 @@ class Riffer::Providers::Base
   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)]
+    @current_model = model
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
     messages = merge_consecutive_messages(messages)
     params = build_request_params(messages, model, options)
-    response = execute_generate(params)
-
-    content = extract_content(response)
-    tool_calls = extract_tool_calls(response)
-    token_usage = extract_token_usage(response)
-    structured_output = parse_structured_output(content) if options[:structured_output] && tool_calls.empty?
-
-    Riffer::Messages::Assistant.new(
-      content,
-      tool_calls: tool_calls,
-      token_usage: token_usage,
-      structured_output: structured_output
-    )
+
+    in_chat_span(model, messages, options) do |span|
+      response = execute_generate(params)
+
+      content = extract_content(response)
+      tool_calls = extract_tool_calls(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?
+
+      Riffer::Tracing.record_usage(span, token_usage)
+      record_token_usage_metric(model, token_usage)
+      record_cost_metric(model, token_usage)
+      record_finish_reason(span, finish_reason&.reason, finish_reason&.raw)
+      capture_output(span, content: content, tool_calls: tool_calls, finish_reason: finish_reason&.reason)
+
+      Riffer::Messages::Assistant.new(
+        content,
+        tool_calls: tool_calls,
+        token_usage: token_usage,
+        structured_output: structured_output,
+        finish_reason: finish_reason&.reason
+      )
+    end
   end
 
   # Streams text from the provider.
@@ -53,12 +79,31 @@ class Riffer::Providers::Base
   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)]
+    @current_model = model
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
     messages = merge_consecutive_messages(messages)
     params = build_request_params(messages, model, options)
+
+    # The enumerator body runs in its own fiber, where the fiber-local OTEL
+    # context is empty — capture here so the chat span parents to the
+    # caller's trace.
+    trace_context = Riffer::Tracing.current_context
     Enumerator.new do |yielder|
-      execute_stream(params, yielder)
+      Riffer::Tracing.with_context(trace_context) do
+        in_chat_span(model, messages, options) do |span|
+          # The recorder feeds both the span and the token-usage metric, so build
+          # it whenever either is live — metrics fire even with tracing off.
+          observe = span.recording? || Riffer::Metrics.recording?
+          sink = observe ? Riffer::Tracing::StreamRecorder.new(yielder) : yielder
+          execute_stream(params, sink)
+          if sink.is_a?(Riffer::Tracing::StreamRecorder)
+            record_stream_outcome(span, sink)
+            record_token_usage_metric(model, sink.token_usage)
+            record_cost_metric(model, sink.token_usage)
+          end
+        end
+      end
     end
   end
 
@@ -95,7 +140,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     raise NotImplementedError, "Subclasses must implement #execute_stream"
   end
@@ -106,6 +151,49 @@ class Riffer::Providers::Base
     raise NotImplementedError, "Subclasses must implement #extract_token_usage"
   end
 
+  #: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
+  def apply_pricing(usage)
+    rates = pricing_rates
+    return usage unless rates
+
+    cost = rates.cost_for(
+      input_tokens: usage.input_tokens,
+      output_tokens: usage.output_tokens,
+      cache_read_tokens: usage.cache_read_tokens,
+      cache_write_tokens: usage.cache_write_tokens
+    )
+    Riffer::Providers::TokenUsage.new(
+      input_tokens: usage.input_tokens,
+      output_tokens: usage.output_tokens,
+      cache_write_tokens: usage.cache_write_tokens,
+      cache_read_tokens: usage.cache_read_tokens,
+      cost: cost
+    )
+  end
+
+  #--
+  #: () -> Riffer::Config::Pricing::Rates?
+  def pricing_rates
+    model = @current_model
+    return nil unless model
+
+    pricing = Riffer.config.pricing
+    return nil if pricing.empty?
+
+    key = Riffer::Providers::Repository.key_for(self.class)
+    return nil unless key
+
+    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)
+    nil
+  end
+
   #--
   #: (untyped) -> String
   def extract_content(response)
@@ -118,6 +206,150 @@ class Riffer::Providers::Base
     raise NotImplementedError, "Subclasses must implement #extract_tool_calls"
   end
 
+  # A deliberate whitelist — caller options outside it stay off spans.
+  REQUEST_PARAM_ATTRIBUTES = {
+    temperature: "gen_ai.request.temperature",
+    max_tokens: "gen_ai.request.max_tokens",
+    max_output_tokens: "gen_ai.request.max_tokens",
+    top_p: "gen_ai.request.top_p",
+    top_k: "gen_ai.request.top_k",
+    frequency_penalty: "gen_ai.request.frequency_penalty",
+    presence_penalty: "gen_ai.request.presence_penalty",
+    seed: "gen_ai.request.seed",
+    stop_sequences: "gen_ai.request.stop_sequences"
+  }.freeze #: Hash[Symbol, String]
+
+  #--
+  #: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
+  def in_chat_span(model, messages, options)
+    start = Riffer::Metrics.monotonic_now
+    error_type = nil #: String?
+    begin
+      Riffer::Tracing.in_span(model ? "chat #{model}" : "chat", attributes: chat_span_attributes(model, options), kind: :client) do |span|
+        capture_input(span, messages)
+        yield span
+      rescue => error
+        # The backend records the exception and error status on the re-raise;
+        # error.type is the one semconv attribute it doesn't set.
+        span.set_attribute("error.type", error.class.name)
+        raise
+      end
+    rescue => error
+      # The inner rescue tags the span; capture error.type here too, at method
+      # scope, where the ensure can read it onto the metric.
+      error_type = error.class.name #: String?
+      raise
+    ensure
+      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: chat_metric_attributes(model, error_type))
+    end
+  end
+
+  #--
+  #: (String?, Hash[Symbol, untyped]) -> Hash[String, untyped]
+  def chat_span_attributes(model, options)
+    attributes = {
+      "gen_ai.operation.name" => "chat",
+      "gen_ai.provider.name" => self.class.semconv_provider_name
+    } #: Hash[String, untyped]
+    attributes["gen_ai.request.model"] = model if model
+
+    REQUEST_PARAM_ATTRIBUTES.each do |key, attribute|
+      value = options[key]
+      attributes[attribute] = value unless value.nil?
+    end
+
+    attributes
+  end
+
+  #--
+  #: (String?) -> Hash[String, untyped]
+  def chat_metric_base_attributes(model)
+    attributes = {
+      "gen_ai.operation.name" => "chat",
+      "gen_ai.provider.name" => self.class.semconv_provider_name
+    } #: Hash[String, untyped]
+    attributes["gen_ai.request.model"] = model if model
+    attributes
+  end
+
+  #--
+  #: (String?, String?) -> Hash[String, untyped]
+  def chat_metric_attributes(model, error_type)
+    attributes = chat_metric_base_attributes(model)
+    attributes["error.type"] = error_type if error_type
+    attributes
+  end
+
+  # Per-call only — the run level would double-count an aggregate.
+  #--
+  #: (String?, Riffer::Providers::TokenUsage?) -> void
+  def record_token_usage_metric(model, usage)
+    return unless usage
+
+    base = chat_metric_base_attributes(model)
+    Riffer::Metrics::Instruments::TOKEN_USAGE.record(usage.input_tokens, attributes: base.merge("gen_ai.token.type" => "input"))
+    Riffer::Metrics::Instruments::TOKEN_USAGE.record(usage.output_tokens, attributes: base.merge("gen_ai.token.type" => "output"))
+  end
+
+  # Per-call only — the run level would double-count an aggregate.
+  #--
+  #: (String?, Riffer::Providers::TokenUsage?) -> void
+  def record_cost_metric(model, usage)
+    cost = usage&.cost
+    return unless cost
+
+    Riffer::Metrics::Instruments::COST.record(cost, attributes: chat_metric_base_attributes(model))
+  end
+
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Symbol?, String?) -> void
+  def record_finish_reason(span, reason, raw)
+    return unless reason
+
+    span.set_attribute("gen_ai.response.finish_reasons", [reason.to_s])
+    span.set_attribute("riffer.finish_reason.raw", raw) if raw && raw != reason.to_s
+  end
+
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tracing::StreamRecorder) -> void
+  def record_stream_outcome(span, recorder)
+    Riffer::Tracing.record_usage(span, recorder.token_usage)
+    record_finish_reason(span, recorder.finish_reason, recorder.raw_finish_reason)
+    capture_output(span, content: recorder.content, tool_calls: recorder.tool_calls, finish_reason: recorder.finish_reason)
+  end
+
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Array[Riffer::Messages::Base]) -> void
+  def capture_input(span, messages)
+    return unless capture_messages?(span)
+
+    span.set_attribute("gen_ai.input.messages", Riffer::Tracing::Capture.input_messages(messages))
+    system_instructions = Riffer::Tracing::Capture.system_instructions(messages)
+    span.set_attribute("gen_ai.system_instructions", system_instructions) if system_instructions
+  end
+
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
+  def capture_output(span, content:, tool_calls:, finish_reason:)
+    return unless capture_messages?(span)
+
+    span.set_attribute("gen_ai.output.messages", Riffer::Tracing::Capture.output_messages(content: content, tool_calls: tool_calls, finish_reason: finish_reason))
+  end
+
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> bool
+  def capture_messages?(span)
+    Riffer.config.tracing.capture_messages && span.recording?
+  end
+
+  #--
+  #: (Riffer::Providers::_EventSink, Riffer::Providers::FinishReason?) -> void
+  def yield_finish_reason(yielder, finish_reason)
+    return unless finish_reason
+
+    yielder << Riffer::StreamEvents::FinishReasonDone.new(finish_reason: finish_reason.reason, raw_finish_reason: finish_reason.raw)
+  end
+
   #--
   #: (String) -> Hash[Symbol, untyped]?
   def parse_structured_output(content)

data/lib/riffer/providers/finish_reason.rb

@@ -0,0 +1,27 @@
+# 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 error other].freeze #: Array[Symbol]
+
+  # The normalized reason.
+  attr_reader :reason #: Symbol
+
+  # The provider's raw finish-reason value, when one exists on the wire.
+  attr_reader :raw #: String?
+
+  # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
+  #--
+  #: (reason: Symbol, ?raw: String?) -> void
+  def initialize(reason:, raw: nil)
+    unless VALUES.include?(reason)
+      raise Riffer::ArgumentError, "reason must be one of #{VALUES.inspect}, got #{reason.inspect}"
+    end
+
+    @reason = reason
+    @raw = raw
+  end
+end

data/lib/riffer/providers/gemini.rb

@@ -17,6 +17,25 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   DEFAULT_OPEN_TIMEOUT = 10 #: Integer
   DEFAULT_READ_TIMEOUT = 60 #: Integer
 
+  FINISH_REASONS = {
+    "STOP" => :stop,
+    "MAX_TOKENS" => :length,
+    "SAFETY" => :content_filter,
+    "RECITATION" => :content_filter,
+    "BLOCKLIST" => :content_filter,
+    "PROHIBITED_CONTENT" => :content_filter,
+    "SPII" => :content_filter,
+    "IMAGE_SAFETY" => :content_filter,
+    "MALFORMED_FUNCTION_CALL" => :error
+  }.freeze #: Hash[String, Symbol]
+
+  # The GenAI semconv well-known provider name.
+  #--
+  #: () -> String
+  def self.semconv_provider_name
+    "gcp.gemini"
+  end
+
   #--
   #: (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
   def initialize(api_key: nil, open_timeout: nil, read_timeout: nil, **options)
@@ -103,15 +122,44 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     usage = response[:usageMetadata]
     return nil unless usage
 
-    Riffer::Providers::TokenUsage.new(
+    build_token_usage(usage)
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason(response)
+    parts = response.dig(:candidates, 0, :content, :parts)
+    has_function_call = !!parts&.any? { |part| part[:functionCall] }
+    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:)
+    return nil unless raw_reason
+
+    raw = raw_reason.to_s
+    reason = FINISH_REASONS.fetch(raw, :other)
+    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,
-      output_tokens: usage[:candidatesTokenCount] || 0,
+      output_tokens: (usage[:candidatesTokenCount] || 0) + (usage[:thoughtsTokenCount] || 0),
       cache_read_tokens: usage[:cachedContentTokenCount]
-    )
+    ))
   end
 
   #--
-  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     model = params[:model]
     body = params.except(:model)
@@ -125,6 +173,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
 
     full_text = +""
     buffer = +""
+    raw_finish_reason = nil #: String?
+    saw_function_call = false
 
     process_chunk = lambda do |chunk|
       buffer << chunk
@@ -146,6 +196,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
             yielder << Riffer::StreamEvents::TextDelta.new(part[:text])
           elsif part[:functionCall]
             fc = part[:functionCall]
+            saw_function_call = true
             call_id = "gemini_call_#{SecureRandom.hex(12)}"
             arguments = encode_tool_arguments(fc[:args])
             yielder << Riffer::StreamEvents::ToolCallDone.new(
@@ -157,15 +208,11 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
           end
         end
 
+        raw_finish_reason = parsed.dig(:candidates, 0, :finishReason) || raw_finish_reason
+
         usage = parsed[:usageMetadata]
         if usage && usage[:candidatesTokenCount]
-          yielder << Riffer::StreamEvents::TokenUsageDone.new(
-            token_usage: Riffer::Providers::TokenUsage.new(
-              input_tokens: usage[:promptTokenCount] || 0,
-              output_tokens: usage[:candidatesTokenCount] || 0,
-              cache_read_tokens: usage[:cachedContentTokenCount]
-            )
-          )
+          yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: build_token_usage(usage))
         end
       end
     end
@@ -183,6 +230,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     end
 
     yielder << Riffer::StreamEvents::TextDone.new(full_text) unless full_text.empty?
+    yield_finish_reason(yielder, build_finish_reason(raw_finish_reason, tool_calls: saw_function_call))
   end
 
   #--