riffer 0.33.0 → 0.35.0

data/lib/riffer/agent.rb

@@ -169,16 +169,16 @@ class Riffer::Agent
 
   # Generates a response using a new agent instance.
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
-  def self.generate(prompt = nil, files: nil, context: nil)
-    new(context: context).generate(prompt, files: files)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def self.generate(prompt = nil, files: nil, context: nil, tags: {})
+    new(context: context).generate(prompt, files: files, tags: tags)
   end
 
   # Streams a response using a new agent instance.
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def self.stream(prompt = nil, files: nil, context: nil)
-    new(context: context).stream(prompt, files: files)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def self.stream(prompt = nil, files: nil, context: nil, tags: {})
+    new(context: context).stream(prompt, files: files, tags: tags)
   end
 
   # Reconstructs a runnable agent from a wire hash produced by +#to_h+.
@@ -288,22 +288,29 @@ class Riffer::Agent
   # against the current session, resuming a persisted conversation or pending
   # tool calls. +files:+ requires +prompt+.
   #
+  # +tags:+ is an optional flat hash of attribution tags applied to this single
+  # call: they propagate to the provider's native request-metadata field, and
+  # are stamped as +riffer.tag.*+ on every span and metric the call emits. See
+  # +docs/03_AGENTS.md+ for the per-provider mapping. The reserved key
+  # +user_id+ also maps to the provider's native user identifier where one
+  # exists.
+  #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
-  def generate(prompt = nil, files: nil)
-    Riffer::Agent::Run.generate(agent: self, prompt: prompt, files: files)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate(prompt = nil, files: nil, tags: {})
+    Riffer::Agent::Run.generate(agent: self, prompt: prompt, files: files, tags: tags)
   end
 
   # Streams a response from the agent, returning an +Enumerator+ of
-  # +Riffer::StreamEvents+. See +#generate+ for prompt/files semantics.
+  # +Riffer::StreamEvents+. See +#generate+ for prompt/files/tags semantics.
   #
   # Raises Riffer::ArgumentError if structured output is configured.
   #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream(prompt = nil, files: nil)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream(prompt = nil, files: nil, tags: {})
     raise Riffer::ArgumentError, "Structured output is not supported with streaming. Use #generate instead." if @structured_output
-    Riffer::Agent::Run.stream(agent: self, prompt: prompt, files: files)
+    Riffer::Agent::Run.stream(agent: self, prompt: prompt, files: files, tags: tags)
   end
 
   # Interrupts the agent loop from an +on_message+ callback. Equivalent to

data/lib/riffer/config.rb

@@ -61,16 +61,16 @@ class Riffer::Config
     # content routinely carries sensitive data.
     attr_reader :capture_messages #: bool
 
-    # Explicit OTEL tracer provider; defaults to +nil+, which resolves the
-    # global <tt>OpenTelemetry.tracer_provider</tt> at first span.
-    attr_reader :tracer_provider #: untyped
+    # The backend riffer routes spans through; defaults to +nil+, a no-op.
+    # Riffer auto-detects no backend; assigning one is opt-in.
+    attr_reader :backend #: untyped
 
     #--
     #: () -> void
     def initialize
       @enabled = true
       @capture_messages = false
-      @tracer_provider = nil
+      @backend = nil
     end
 
     # Sets the enabled flag, coercing boolean-ish values so an env-var
@@ -91,17 +91,17 @@ class Riffer::Config
       @capture_messages = Riffer::Helpers::Boolean.coerce(value, attribute: "capture_messages")
     end
 
-    # Sets an explicit tracer provider, forcing the OTEL backend. Raises
-    # Riffer::ArgumentError when the OpenTelemetry API gem isn't available
-    # at a supported version.
+    # Sets the tracing backend riffer routes spans through. Raises
+    # Riffer::ArgumentError unless the value is +nil+ or responds to the full
+    # delegated contract: +in_span+, +current_context+, and +with_context+.
     #--
     #: (untyped) -> void
-    def tracer_provider=(value)
-      if !value.nil? && !Riffer::Tracing::Otel.available?
-        raise Riffer::ArgumentError,
-          "tracer_provider requires the opentelemetry-api gem (#{Riffer::Tracing::Otel::SUPPORTED_API_VERSIONS})"
+    def backend=(value)
+      contract = %i[in_span current_context with_context]
+      unless value.nil? || contract.all? { |method| value.respond_to?(method) }
+        raise Riffer::ArgumentError, "tracing backend must respond to #in_span, #current_context, and #with_context"
       end
-      @tracer_provider = value
+      @backend = value
       Riffer::Tracing.reset!
     end
   end
@@ -113,15 +113,15 @@ class Riffer::Config
     # no-op until a host wires an OTEL metrics SDK.
     attr_reader :enabled #: bool
 
-    # Explicit OTEL meter provider; defaults to +nil+, which resolves the
-    # global <tt>OpenTelemetry.meter_provider</tt> at first record.
-    attr_reader :meter_provider #: untyped
+    # The backend riffer routes measurements through; defaults to +nil+, a no-op.
+    # Riffer auto-detects no backend; assigning one is opt-in.
+    attr_reader :backend #: untyped
 
     #--
     #: () -> void
     def initialize
       @enabled = true
-      @meter_provider = nil
+      @backend = nil
     end
 
     # Sets the enabled flag, coercing boolean-ish values so an env-var
@@ -133,17 +133,16 @@ class Riffer::Config
       @enabled = Riffer::Helpers::Boolean.coerce(value, attribute: "enabled")
     end
 
-    # Sets an explicit meter provider, forcing the OTEL backend. Raises
-    # Riffer::ArgumentError when the OpenTelemetry metrics API gem isn't
-    # available at a supported version.
+    # Sets the metrics backend riffer routes measurements through. Raises
+    # Riffer::ArgumentError unless the value is +nil+ or responds to
+    # +record_histogram+.
     #--
     #: (untyped) -> void
-    def meter_provider=(value)
-      if !value.nil? && !Riffer::Metrics::Otel.available?
-        raise Riffer::ArgumentError,
-          "meter_provider requires the opentelemetry-metrics-api gem (#{Riffer::Metrics::Otel::SUPPORTED_API_VERSIONS})"
+    def backend=(value)
+      unless value.nil? || value.respond_to?(:record_histogram)
+        raise Riffer::ArgumentError, "metrics backend must respond to #record_histogram"
       end
-      @meter_provider = value
+      @backend = value
       Riffer::Metrics.reset!
     end
   end

data/lib/riffer/guardrails/runner.rb

@@ -13,12 +13,16 @@ class Riffer::Guardrails::Runner
   # The context passed to guardrails.
   attr_reader :context #: untyped
 
+  # The normalized per-call tags, stamped as +riffer.tag.*+ on guardrail spans.
+  attr_reader :tags #: Hash[String, String]
+
   #--
-  #: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped) -> void
-  def initialize(guardrail_configs, phase:, context: nil)
+  #: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void
+  def initialize(guardrail_configs, phase:, context: nil, tags: {})
     @guardrail_configs = guardrail_configs
     @phase = phase
     @context = context
+    @tags = tags
   end
 
   # Runs the guardrails sequentially. For the +:before+ phase +data+ is the
@@ -81,15 +85,32 @@ class Riffer::Guardrails::Runner
   #--
   #: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
   def execute_guardrail(guardrail, data, messages:)
-    Riffer::Tracing.in_span("execute_guardrail #{guardrail.name}", attributes: guardrail_span_attributes(guardrail), kind: :internal) do |span|
-      result = run_guardrail_phase(guardrail, data, messages: messages)
-      record_guardrail_outcome(span, result)
-      result
+    instrument_guardrail(guardrail) do
+      Riffer::Tracing.in_span("execute_guardrail #{guardrail.name}", attributes: guardrail_span_attributes(guardrail), kind: :internal) do |span|
+        result = run_guardrail_phase(guardrail, data, messages: messages)
+        record_guardrail_outcome(span, result)
+        result
+      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
+    end
+  end
+
+  #--
+  #: (Riffer::Guardrail) { () -> Riffer::Guardrails::Result } -> Riffer::Guardrails::Result
+  def instrument_guardrail(guardrail)
+    start = Riffer::Metrics.monotonic_now
+    error_type = nil #: String?
+    begin
+      yield
     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)
+      error_type = error.class.name #: String?
       raise
+    ensure
+      Riffer::Metrics::Instruments::GUARDRAIL_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: guardrail_metric_attributes(guardrail, error_type))
     end
   end
 
@@ -112,13 +133,21 @@ class Riffer::Guardrails::Runner
     {
       "riffer.guardrail.name" => guardrail.name,
       "riffer.guardrail.phase" => phase.to_s
-    }
+    }.merge(tags.transform_keys { |key| "riffer.tag.#{key}" })
+  end
+
+  #--
+  #: (Riffer::Guardrail, String?) -> Hash[String, untyped]
+  def guardrail_metric_attributes(guardrail, error_type)
+    attributes = guardrail_span_attributes(guardrail)
+    attributes["error.type"] = error_type if error_type
+    attributes
   end
 
   # A block is a handled outcome, so its span status stays unset — an error
   # span status is reserved for a raised exception.
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Guardrails::Result) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Guardrails::Result) -> void
   def record_guardrail_outcome(span, result)
     span.set_attribute("riffer.guardrail.action", result.type.to_s)
     span.set_attribute("riffer.tripwire.reason", result.data) if result.block?

data/lib/riffer/metrics/instruments.rb

@@ -22,4 +22,10 @@ module Riffer::Metrics::Instruments # :nodoc: all
     unit: "USD",
     description: "Cost of GenAI client operations in USD"
   ) #: Riffer::Metrics::Histogram
+
+  GUARDRAIL_DURATION = Riffer::Metrics.create_histogram(
+    "riffer.guardrail.duration",
+    unit: "s",
+    description: "Duration of guardrail execution"
+  ) #: Riffer::Metrics::Histogram
 end

data/lib/riffer/metrics/{null.rb → no_op.rb}

@@ -3,7 +3,7 @@
 
 # No-op metrics backend, used when the OpenTelemetry metrics API is unavailable
 # or metrics are disabled.
-module Riffer::Metrics::Null # :nodoc: all
+module Riffer::Metrics::NoOp # :nodoc: all
   extend self
 
   # Ignores the measurement; there is no meter without the OTEL metrics API.

data/lib/riffer/metrics/otel.rb

@@ -9,10 +9,11 @@ class Riffer::Metrics::Otel # :nodoc: all
 
   class << self
     # Builds a backend when the OpenTelemetry metrics API is loadable at a
-    # supported version; returns +nil+ so resolution falls back to Null.
+    # 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 build(provider:)
+    #: (?provider: untyped) -> Riffer::Metrics::Otel?
+    def build(provider: nil)
       version = api_version
       return nil unless version
 

data/lib/riffer/metrics.rb

@@ -7,7 +7,7 @@
 module Riffer::Metrics # :nodoc: all
   extend self
 
-  # @rbs @backend: (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))?
+  # @rbs @backend: untyped
 
   MUTEX = Mutex.new #: Mutex
 
@@ -54,11 +54,12 @@ module Riffer::Metrics # :nodoc: all
   end
 
   # Mirrors a span's +recording?+ so a caller can skip work that exists only to
-  # feed a metric.
+  # 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?
-    Riffer.config.metrics.enabled && backend.is_a?(Otel)
+    Riffer.config.metrics.enabled && !backend.equal?(NoOp)
   end
 
   # Reads the monotonic clock in seconds — the time source for duration metrics,
@@ -80,14 +81,14 @@ module Riffer::Metrics # :nodoc: all
   private
 
   #--
-  #: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  #: () -> untyped
   def backend
     @backend || MUTEX.synchronize { @backend ||= resolve_backend }
   end
 
   #--
-  #: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  #: () -> untyped
   def resolve_backend
-    Otel.build(provider: Riffer.config.metrics.meter_provider) || Null
+    Riffer.config.metrics.backend || NoOp
   end
 end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -64,14 +64,20 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     tools = options[:tools]
     structured_output = options[:structured_output]
     cache_control = options[:cache_control]
+    tags = options[:tags] || {}
 
     params = {
       model_id: model,
       system: partitioned_messages[:system],
       messages: partitioned_messages[:conversation],
-      **options.except(:tools, :structured_output, :cache_control)
+      **options.except(:tools, :structured_output, :cache_control, :tags)
     } #: Hash[Symbol, untyped]
 
+    # requestMetadata is a flat String=>String map used to filter invocation
+    # logs; every tag (including the reserved user_id) rides along, since
+    # Converse has no dedicated end-user field.
+    params[:request_metadata] = tags unless tags.empty?
+
     if tools && !tools.empty?
       params[:tool_config] = {
         tools: tools.map { |t| convert_tool_to_bedrock_format(t) }

data/lib/riffer/providers/anthropic.rb

@@ -48,6 +48,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     tools = options[:tools]
     structured_output = options[:structured_output]
     web_search = options[:web_search]
+    tags = options[:tags] || {}
 
     max_tokens = options.fetch(:max_tokens, 4096)
 
@@ -55,11 +56,17 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       model: model,
       messages: partitioned_messages[:conversation],
       max_tokens: max_tokens,
-      **options.except(:tools, :max_tokens, :structured_output, :web_search)
+      **options.except(:tools, :max_tokens, :structured_output, :web_search, :tags)
     } #: Hash[Symbol, untyped]
 
     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/metrics.
+    user_id = tags["user_id"]
+    params[:metadata] = {user_id: user_id} if user_id
+
     anthropic_tools = [] #: Array[Hash[Symbol, untyped]]
     anthropic_tools.concat(tools.map { |t| convert_tool_to_anthropic_format(t) }) if tools && !tools.empty?
 

data/lib/riffer/providers/base.rb

@@ -46,6 +46,7 @@ class Riffer::Providers::Base
     validate_normalized_messages!(messages)
     messages = merge_consecutive_messages(messages)
     params = build_request_params(messages, model, options)
+    tags = options[:tags] || {}
 
     in_chat_span(model, messages, options) do |span|
       response = execute_generate(params)
@@ -57,8 +58,8 @@ class Riffer::Providers::Base
       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_token_usage_metric(model, token_usage, tags)
+      record_cost_metric(model, token_usage, tags)
       record_finish_reason(span, finish_reason&.reason, finish_reason&.raw)
       capture_output(span, content: content, tool_calls: tool_calls, finish_reason: finish_reason&.reason)
 
@@ -84,10 +85,12 @@ class Riffer::Providers::Base
     validate_normalized_messages!(messages)
     messages = merge_consecutive_messages(messages)
     params = build_request_params(messages, model, options)
+    tags = options[:tags] || {}
 
     # 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.
+    # context is empty — capture here so the chat span parents to the caller's
+    # trace. tags are an ordinary local captured in the closure, so they reach
+    # the span/metric builders without re-propagation.
     trace_context = Riffer::Tracing.current_context
     Enumerator.new do |yielder|
       Riffer::Tracing.with_context(trace_context) do
@@ -99,8 +102,8 @@ class Riffer::Providers::Base
           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)
+            record_token_usage_metric(model, sink.token_usage, tags)
+            record_cost_metric(model, sink.token_usage, tags)
           end
         end
       end
@@ -220,10 +223,11 @@ class Riffer::Providers::Base
   }.freeze #: Hash[Symbol, String]
 
   #--
-  #: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
+  #: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_chat_span(model, messages, options)
     start = Riffer::Metrics.monotonic_now
     error_type = nil #: String?
+    tags = options[:tags] || {} #: Hash[String, String]
     begin
       Riffer::Tracing.in_span(model ? "chat #{model}" : "chat", attributes: chat_span_attributes(model, options), kind: :client) do |span|
         capture_input(span, messages)
@@ -240,7 +244,7 @@ class Riffer::Providers::Base
       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))
+      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: chat_metric_attributes(model, error_type, tags))
     end
   end
 
@@ -258,51 +262,59 @@ class Riffer::Providers::Base
       attributes[attribute] = value unless value.nil?
     end
 
-    attributes
+    attributes.merge(tag_attributes(options[:tags] || {}))
   end
 
   #--
-  #: (String?) -> Hash[String, untyped]
-  def chat_metric_base_attributes(model)
+  #: (String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def chat_metric_base_attributes(model, tags = {})
     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
+    attributes.merge(tag_attributes(tags))
   end
 
   #--
-  #: (String?, String?) -> Hash[String, untyped]
-  def chat_metric_attributes(model, error_type)
-    attributes = chat_metric_base_attributes(model)
+  #: (String?, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def chat_metric_attributes(model, error_type, tags = {})
+    attributes = chat_metric_base_attributes(model, tags)
     attributes["error.type"] = error_type if error_type
     attributes
   end
 
+  # Maps normalized tags to their namespaced span/metric 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)
+    tags.transform_keys { |key| "riffer.tag.#{key}" }
+  end
+
   # Per-call only — the run level would double-count an aggregate.
   #--
-  #: (String?, Riffer::Providers::TokenUsage?) -> void
-  def record_token_usage_metric(model, usage)
+  #: (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
+  def record_token_usage_metric(model, usage, tags = {})
     return unless usage
 
-    base = chat_metric_base_attributes(model)
+    base = chat_metric_base_attributes(model, tags)
     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)
+  #: (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
+  def record_cost_metric(model, usage, tags = {})
     cost = usage&.cost
     return unless cost
 
-    Riffer::Metrics::Instruments::COST.record(cost, attributes: chat_metric_base_attributes(model))
+    Riffer::Metrics::Instruments::COST.record(cost, attributes: chat_metric_base_attributes(model, tags))
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Symbol?, String?) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Symbol?, String?) -> void
   def record_finish_reason(span, reason, raw)
     return unless reason
 
@@ -311,7 +323,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tracing::StreamRecorder) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::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)
@@ -319,7 +331,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Array[Riffer::Messages::Base]) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Array[Riffer::Messages::Base]) -> void
   def capture_input(span, messages)
     return unless capture_messages?(span)
 
@@ -329,7 +341,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> 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(span, content:, tool_calls:, finish_reason:)
     return unless capture_messages?(span)
 
@@ -337,7 +349,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> bool
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
   def capture_messages?(span)
     Riffer.config.tracing.capture_messages && span.recording?
   end

data/lib/riffer/providers/gemini.rb

@@ -67,7 +67,11 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       }]
     end
 
-    generation_config = options.except(:tools, :structured_output)
+    # 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/10_CONFIGURATION.md.
+    generation_config = options.except(:tools, :structured_output, :tags)
 
     if structured_output
       generation_config[:responseMimeType] = "application/json"

data/lib/riffer/providers/open_ai.rb

@@ -30,6 +30,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     tools = options[:tools]
     structured_output = options[:structured_output]
     web_search = options[:web_search]
+    tags = options[:tags] || {}
 
     params = {
       input: convert_messages_to_openai_format(messages),
@@ -38,9 +39,17 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         effort: reasoning,
         summary: "auto"
       },
-      **options.except(:reasoning, :tools, :structured_output, :web_search)
+      **options.except(:reasoning, :tools, :structured_output, :web_search, :tags)
     } #: Hash[Symbol, untyped]
 
+    unless tags.empty?
+      params[:metadata] = 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
+
     openai_tools = [] #: Array[Hash[Symbol, untyped]]
     openai_tools.concat(tools.map { |t| convert_tool_to_openai_format(t) }) if tools && !tools.empty?
 

data/lib/riffer/providers/open_router.rb

@@ -44,13 +44,22 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     reasoning = options[:reasoning]
     tools = options[:tools]
     structured_output = options[:structured_output]
+    tags = options[:tags] || {}
 
     params = {
       model: model,
       messages: convert_messages_to_chat_completions_format(messages),
-      **options.except(:reasoning, :tools, :structured_output)
+      **options.except(:reasoning, :tools, :structured_output, :tags)
     } #: Hash[Symbol, untyped]
 
+    unless tags.empty?
+      params[:metadata] = tags
+      # OpenRouter exposes the legacy Chat Completions user field rather than
+      # safety_identifier; the reserved user_id maps there and stays in metadata.
+      user = tags["user_id"]
+      params[:user] = user if user
+    end
+
     if reasoning
       params[:reasoning] = reasoning.is_a?(String) ? {effort: reasoning} : reasoning
     end