riffer 0.32.1 → 0.34.0

data/sig/generated/riffer/metrics/otel.rbs

@@ -0,0 +1,48 @@
+# Generated from lib/riffer/metrics/otel.rb with RBS::Inline
+
+# OTEL-backed metrics backend. <tt>::OpenTelemetry</tt> constants appear only
+# inside method bodies here, so the gem loads and eager-loads cleanly when the
+# OpenTelemetry metrics API is absent.
+class Riffer::Metrics::Otel
+  # :nodoc: all
+  SUPPORTED_API_VERSIONS: Gem::Requirement
+
+  # Builds a backend when the OpenTelemetry metrics API is loadable at a
+  # supported version; returns +nil+ so resolution falls back to NoOp.
+  # +provider+ defaults to the global <tt>OpenTelemetry.meter_provider</tt>.
+  # --
+  # : (?provider: untyped) -> Riffer::Metrics::Otel?
+  def self.build: (?provider: untyped) -> Riffer::Metrics::Otel?
+
+  # Whether the OpenTelemetry metrics API gem is loadable at a supported
+  # version.
+  # --
+  # : () -> bool
+  def self.available?: () -> bool
+
+  # Whether the given opentelemetry-metrics-api version is one riffer codes
+  # against. The gem is undeclared, so this guard is the only protection
+  # against an incompatible, still-pre-1.0 API.
+  # --
+  # : (Gem::Version) -> bool
+  def self.supported?: (Gem::Version) -> bool
+
+  # --
+  # : () -> Gem::Version?
+  private def self.api_version: () -> Gem::Version?
+
+  @meter: untyped
+
+  @instruments: Hash[String, untyped]
+
+  @mutex: Mutex
+
+  # --
+  # : (provider: untyped) -> void
+  def initialize: (provider: untyped) -> void
+
+  # Records a value onto the named histogram.
+  # --
+  # : (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
+  def record_histogram: (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
+end

data/sig/generated/riffer/metrics.rbs

@@ -0,0 +1,72 @@
+# Generated from lib/riffer/metrics.rb with RBS::Inline
+
+# Internal metrics port — records OTEL metric instruments when the host bundles
+# the OpenTelemetry metrics API and no-ops otherwise, so riffer never declares
+# an OTEL dependency.
+module Riffer::Metrics
+  @backend: untyped
+
+  MUTEX: Mutex
+
+  # The Ruby API cannot attach a schema URL to a meter, so the semconv pin
+  # lives here as the documented contract version.
+  SCHEMA_URL: String
+
+  # A handle to a named histogram, safe to hold as a constant: it defers backend
+  # resolution to record time, so it survives a meter-provider swap or a runtime
+  # +enabled+ flip.
+  class Histogram
+    @name: String
+
+    @unit: String?
+
+    @description: String?
+
+    # --
+    # : (String, ?unit: String?, ?description: String?) -> void
+    def initialize: (String, ?unit: String?, ?description: String?) -> void
+
+    # --
+    # : (Numeric, ?attributes: Hash[String, untyped]?) -> void
+    def record: (Numeric, ?attributes: Hash[String, untyped]?) -> void
+  end
+
+  # Returns a handle to the named histogram.
+  # --
+  # : (String, ?unit: String?, ?description: String?) -> Riffer::Metrics::Histogram
+  def create_histogram: (String, ?unit: String?, ?description: String?) -> Riffer::Metrics::Histogram
+
+  # Records a value onto the named histogram.
+  # --
+  # : (String, Numeric, ?unit: String?, ?description: String?, ?attributes: Hash[String, untyped]?) -> void
+  def record_histogram: (String, Numeric, ?unit: String?, ?description: String?, ?attributes: Hash[String, untyped]?) -> void
+
+  # Mirrors a span's +recording?+ so a caller can skip work that exists only to
+  # feed a metric. True for any live backend — the OTEL backend or a
+  # consumer-supplied one — so a custom metrics sink still gets fed.
+  # --
+  # : () -> bool
+  def recording?: () -> bool
+
+  # Reads the monotonic clock in seconds — the time source for duration metrics,
+  # immune to wall-clock adjustments.
+  # --
+  # : () -> Float
+  def monotonic_now: () -> Float
+
+  # Discards the resolved backend so the next record re-resolves it; cached
+  # instruments live on that backend, so this clears them too.
+  # --
+  # : () -> void
+  def reset!: () -> void
+
+  private
+
+  # --
+  # : () -> untyped
+  def backend: () -> untyped
+
+  # --
+  # : () -> untyped
+  def resolve_backend: () -> untyped
+end

data/sig/generated/riffer/providers/amazon_bedrock.rbs

@@ -7,12 +7,19 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # cross-region (+us.anthropic.claude-...+) ids.
   ANTHROPIC_MODEL_PATTERN: Regexp
 
+  FINISH_REASONS: Hash[String, Symbol]
+
   # Returns the skill adapter for the Bedrock model — XML for Anthropic models
   # (which Bedrock hosts alongside other vendors'), else Markdown.
   # --
   # : (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
+  # The GenAI semconv well-known provider name.
+  # --
+  # : () -> String
+  def self.semconv_provider_name: () -> String
+
   # --
   # : (?api_token: String?, ?region: String?, **untyped) -> void
   def initialize: (?api_token: String?, ?region: String?, **untyped) -> void
@@ -42,6 +49,20 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage: (untyped) -> Riffer::Providers::TokenUsage?
 
+  # Converse's +input_tokens+ excludes the cache buckets; TokenUsage's
+  # input includes them.
+  # --
+  # : (untyped) -> Riffer::Providers::TokenUsage
+  def build_token_usage: (untyped) -> Riffer::Providers::TokenUsage
+
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String
@@ -51,8 +72,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def extract_tool_calls: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
 
   # --
-  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
-  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
+  def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
 
   # Re-raises a Bedrock stream-exception event as the matching
   # +Aws::BedrockRuntime::Errors+ class. ConverseStream delivers API errors on
@@ -63,28 +84,28 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def raise_if_stream_exception!: (untyped) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_start_tool_use: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_content_block_start_tool_use: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_delta_text_delta: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_content_block_delta_text_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_delta_tool_use: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_content_block_delta_tool_use: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_stop_text_delta: (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_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_stop_tool_use: (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: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_metadata_usage: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_metadata_usage: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
   # : (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/anthropic.rbs

@@ -5,12 +5,19 @@
 class Riffer::Providers::Anthropic < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE: String
 
+  FINISH_REASONS: Hash[String, Symbol]
+
   # Returns the XML skill adapter for Anthropic/Claude.
   #
   # --
   # : (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
+  # The GenAI semconv well-known provider name.
+  # --
+  # : () -> String
+  def self.semconv_provider_name: () -> String
+
   # --
   # : (?api_key: String?, **untyped) -> void
   def initialize: (?api_key: String?, **untyped) -> void
@@ -29,6 +36,20 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage: (untyped) -> Riffer::Providers::TokenUsage?
 
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
+  # Anthropic's +input_tokens+ excludes the cache buckets; TokenUsage's
+  # input includes them.
+  # --
+  # : (untyped) -> Riffer::Providers::TokenUsage
+  def build_token_usage: (untyped) -> Riffer::Providers::TokenUsage
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String
@@ -38,8 +59,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   def extract_tool_calls: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
 
   # --
-  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
-  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
+  def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
 
   # --
   # : (untyped, state: Hash[Symbol, untyped]) -> void
@@ -50,40 +71,40 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   def handle_raw_content_block_delta: (untyped, state: Hash[Symbol, untyped]) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_text_event: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_text_event: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_thinking_event: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_thinking_event: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_input_json_event: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_input_json_event: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_stop_tool_use: (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: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_stop_thinking: (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: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_stop_text: (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: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_stop_server_tool_use: (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: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_content_block_stop_web_search_result: (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: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, accumulated_message: untyped, yielder: Enumerator::Yielder) -> void
-  def handle_message_stop: (untyped, accumulated_message: untyped, yielder: Enumerator::Yielder) -> void
+  # : (untyped, accumulated_message: untyped, yielder: Riffer::Providers::_EventSink) -> void
+  def handle_message_stop: (untyped, accumulated_message: untyped, yielder: Riffer::Providers::_EventSink) -> void
 
   # --
   # : (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/azure_open_ai.rbs

@@ -4,6 +4,11 @@
 # 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: () -> String
+
   # --
   # : (**untyped) -> void
   def initialize: (**untyped) -> void

data/sig/generated/riffer/providers/base.rbs

@@ -5,6 +5,8 @@
 # +extract_token_usage+, +extract_content+, +extract_tool_calls+) and the base
 # class orchestrates them.
 class Riffer::Providers::Base
+  @current_model: String?
+
   @current_tools: Array[singleton(Riffer::Tool)]
 
   WIRE_SEPARATOR: String
@@ -15,6 +17,14 @@ class Riffer::Providers::Base
   # : (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
+  # 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: () -> String
+
   # Generates text using the provider.
   #
   # --
@@ -49,13 +59,26 @@ class Riffer::Providers::Base
   def execute_generate: (Hash[Symbol, untyped]) -> untyped
 
   # --
-  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
-  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
+  def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
 
   # --
   # : (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage: (untyped) -> Riffer::Providers::TokenUsage?
 
+  # : (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
+  def apply_pricing: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
+
+  # --
+  # : () -> Riffer::Config::Pricing::Rates?
+  def pricing_rates: () -> Riffer::Config::Pricing::Rates?
+
+  # 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: (untyped) -> Riffer::Providers::FinishReason?
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String
@@ -64,6 +87,59 @@ class Riffer::Providers::Base
   # : (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
 
+  # A deliberate whitelist — caller options outside it stay off spans.
+  REQUEST_PARAM_ATTRIBUTES: Hash[Symbol, String]
+
+  # --
+  # : [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
+  def in_chat_span: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
+
+  # --
+  # : (String?, Hash[Symbol, untyped]) -> Hash[String, untyped]
+  def chat_span_attributes: (String?, Hash[Symbol, untyped]) -> Hash[String, untyped]
+
+  # --
+  # : (String?) -> Hash[String, untyped]
+  def chat_metric_base_attributes: (String?) -> Hash[String, untyped]
+
+  # --
+  # : (String?, String?) -> Hash[String, untyped]
+  def chat_metric_attributes: (String?, String?) -> Hash[String, untyped]
+
+  # Per-call only — the run level would double-count an aggregate.
+  # --
+  # : (String?, Riffer::Providers::TokenUsage?) -> void
+  def record_token_usage_metric: (String?, Riffer::Providers::TokenUsage?) -> void
+
+  # Per-call only — the run level would double-count an aggregate.
+  # --
+  # : (String?, Riffer::Providers::TokenUsage?) -> void
+  def record_cost_metric: (String?, Riffer::Providers::TokenUsage?) -> void
+
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Symbol?, String?) -> void
+  def record_finish_reason: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Symbol?, String?) -> void
+
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tracing::StreamRecorder) -> void
+  def record_stream_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Tracing::StreamRecorder) -> void
+
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Array[Riffer::Messages::Base]) -> void
+  def capture_input: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Array[Riffer::Messages::Base]) -> void
+
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
+  def capture_output: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
+
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
+  def capture_messages?: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> bool
+
+  # --
+  # : (Riffer::Providers::_EventSink, Riffer::Providers::FinishReason?) -> void
+  def yield_finish_reason: (Riffer::Providers::_EventSink, Riffer::Providers::FinishReason?) -> void
+
   # --
   # : (String) -> Hash[Symbol, untyped]?
   def parse_structured_output: (String) -> Hash[Symbol, untyped]?

data/sig/generated/riffer/providers/finish_reason.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/riffer/providers/finish_reason.rb with RBS::Inline
+
+# 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: 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: Symbol, ?raw: String?) -> void
+end

data/sig/generated/riffer/providers/gemini.rbs

@@ -16,6 +16,13 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
 
   DEFAULT_READ_TIMEOUT: Integer
 
+  FINISH_REASONS: Hash[String, Symbol]
+
+  # The GenAI semconv well-known provider name.
+  # --
+  # : () -> String
+  def self.semconv_provider_name: () -> String
+
   # --
   # : (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
   def initialize: (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
@@ -43,8 +50,24 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   def extract_token_usage: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage?
 
   # --
-  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
-  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  # : (Hash[Symbol, untyped]) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason: (Hash[Symbol, untyped]) -> Riffer::Providers::FinishReason?
+
+  # 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: (String?, tool_calls: bool) -> Riffer::Providers::FinishReason?
+
+  # Gemini reports thinking tokens outside +candidatesTokenCount+;
+  # TokenUsage's output includes them.
+  # --
+  # : (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage
+  def build_token_usage: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage
+
+  # --
+  # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
+  def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
 
   # --
   # : (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/mock.rbs

@@ -14,6 +14,11 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   # : (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
+  # The GenAI semconv well-known provider name.
+  # --
+  # : () -> String
+  def self.semconv_provider_name: () -> String
+
   # Array of recorded method calls for assertions.
   attr_reader calls: Array[Hash[Symbol, untyped]]
 
@@ -29,15 +34,17 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   # : (**untyped) -> void
   def initialize: (**untyped) -> void
 
-  # Stubs the next response; call repeatedly to queue several.
+  # 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)
   #
   # --
-  # : (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?) -> void
-  def stub_response: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?) -> void
+  # : (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?) -> void
+  def stub_response: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?) -> void
 
   # Clears all stubbed responses.
   #
@@ -63,6 +70,10 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage: (untyped) -> Riffer::Providers::TokenUsage?
 
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String
@@ -72,8 +83,8 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   def extract_tool_calls: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
 
   # --
-  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
-  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
+  def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
 
   # --
   # : () -> Hash[Symbol, untyped]