riffer 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc442fb9eb0296a5a9c6f289c1c9e63e7cdb732ef52b013e1556d1765a874f2d
-  data.tar.gz: aa7512f0b3ac38e4f0c7be500095c73fca0ae1740c37370ceb2aeaf57349dac8
+  metadata.gz: acfc9a0c002c97b79d515172d71aa419359e27fac0a3809934c30057931e66ef
+  data.tar.gz: 322aaebffb66c41824fdd3a3c43d08ae6bb806f8e2e06ca5ee1834648704e1d5
 SHA512:
-  metadata.gz: d9ace157326fa9ebfb356705f14cd4a8bac4af86e3ede2eb142adb4be36870399c81ee122fa02973135c9176b521bdee980745e3cc3f14422e12fbf1392fb009
-  data.tar.gz: cdc2e19b1aab77a93fb6ad7c4a800c5002a5efb63667366113fc04104a05c342863a1fa74219ed2569759f5f7be08dc534ac7c79b10c6d9ab61d6430db805113
+  metadata.gz: ba3554a4a135ae43f5d5a2d65928275e4acfcc27c03609f2578d5304e8825c3f42f05b7229fe5881fdc7c663372ef6ca3591af02b2719167bc7711fc7754e7e6
+  data.tar.gz: 49c2b41f0cb606ec9e86b72777d55b3b3222220d879b5e05ed211a07094d9561c7e1c054ce2689d3b81b6ff872d981f6e1f24306b916cf12a697f7df23f91a69

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.34.0"
+  ".": "0.35.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.35.0](https://github.com/janeapp/riffer/compare/riffer/v0.34.0...riffer/v0.35.0) (2026-06-25)
+
+
+### Features
+
+* per-call tags: for Agent#generate and #stream ([#339](https://github.com/janeapp/riffer/issues/339)) ([ddfda89](https://github.com/janeapp/riffer/commit/ddfda8929ca3b594415f827957d8c91104387317))
+
 ## [0.34.0](https://github.com/janeapp/riffer/compare/riffer/v0.33.0...riffer/v0.34.0) (2026-06-22)
 
 

data/docs/03_AGENTS.md

@@ -317,6 +317,50 @@ agent.generate('Hello')
 
 When `config:` is supplied, the class-level configuration is ignored for that instance.
 
+## Per-Call Tags
+
+`#generate` and `#stream` accept an optional `tags:` hash — a flat map of attribution labels scoped to that single call (for cost/usage attribution, filtering audit logs, slicing telemetry). It is **per-call only**.
+
+```ruby
+agent.generate("Summarize this ticket.",
+  tags: {team: "growth", feature: "summarizer", user_id: "u_abc123"})
+
+agent.stream("...", tags: {team: "growth", environment: "production"})
+```
+
+Keys and values may be `String` or `Symbol`; both are stringified, and entries with a `nil` value are dropped. Passing a non-`Hash` raises `Riffer::ArgumentError`. An omitted or empty `tags:` is a complete no-op.
+
+Tags propagate to **two** places:
+
+1. The provider's native per-request metadata field (see the mapping below).
+2. Observability — stamped as `riffer.tag.<key>` on **every** span and metric the call emits (`invoke_agent`, `chat`, `execute_tool`, `execute_guardrail` spans, and the duration/token-usage/cost metrics). See [Tracing](16_TRACING.md) and [Metrics](17_METRICS.md).
+
+### Reserved key: `user_id`
+
+`user_id` is a reserved tag. Beyond appearing like any other tag, it maps to the provider's native end-user identifier where one exists (see the table).
+
+### Provider mapping
+
+| Provider              | Native request field          | `user_id` handling                      |
+| --------------------- | ----------------------------- | --------------------------------------- |
+| Amazon Bedrock        | `request_metadata` (all tags) | Ordinary entry; no dedicated user field |
+| OpenAI / Azure OpenAI | `metadata` (all tags)         | Also mapped to `safety_identifier`      |
+| OpenRouter            | `metadata` (all tags)         | Also mapped to `user`                   |
+| Anthropic             | `metadata.user_id` **only**   | The only tag forwarded                  |
+| Gemini                | _(none — observability only)_ | Tag only; no request field              |
+
+**Anthropic silently drops non-`user_id` tags.** The Messages API has no free-form request-metadata field — only `metadata.user_id`. So for Anthropic, `user_id` is forwarded as `metadata: {user_id: …}` and **every other tag is dropped from the request** (it still appears on spans and metrics). This is intentional.
+
+**Gemini is observability-only.** Riffer's Gemini adapter targets the Gemini Developer API (`generativelanguage.googleapis.com`), whose `generateContent` request has **no** `labels` field — sending unknown fields is rejected. So tags are **not** added to the Gemini request; they propagate to spans and metrics only. Native request labels (`labels`, lowercase `[a-z0-9_-]`, ≤63 chars each) are a Vertex AI feature and would arrive with a future Vertex adapter.
+
+### Provider limits (not enforced)
+
+Riffer does not validate tag count, key/value length, or charset — it forwards what you give it and lets the provider reject anything out of bounds. Known limits: Bedrock `requestMetadata` ≤16 entries, key/value ≤256 chars; OpenAI / OpenRouter `metadata` ≤16 pairs (OpenRouter: 64-char keys, 512-char values).
+
+### Metric cardinality
+
+Tags are promoted onto metric dimensions verbatim — there is no allow-list. High-cardinality values (e.g. a unique `user_id` per request) will create a correspondingly large number of metric series in your backend. Keep metric-bound tags low-cardinality.
+
 ## Expand Your Agent
 
 | Goal                          | Feature           | Guide                                                                |

data/docs/16_TRACING.md

@@ -93,6 +93,10 @@ Every attribute a span can carry is listed below, including the conditional ones
 
 The contract promise is: **when present**, a key carries the documented meaning and type. It is _not_ a promise that every key appears on every span.
 
+### Per-call tags (`riffer.tag.*`)
+
+Any tags passed to `#generate` / `#stream` via `tags:` are stamped on **all four** span types as `riffer.tag.<key>` (string), so the per-span tables below omit them. They appear on every span the tagged call emits and are absent otherwise. Example: `tags: {team: "growth"}` adds `riffer.tag.team` → `"growth"` to the `invoke_agent`, `chat`, `execute_tool`, and `execute_guardrail` spans. See [Per-Call Tags](03_AGENTS.md#per-call-tags) for the full surface and the per-provider request-metadata mapping.
+
 ## `invoke_agent {agent}` — the run span
 
 `INTERNAL`. One per call to `Agent#generate` or `Agent#stream`. The span name suffix is the agent's identifier (e.g. `invoke_agent weather-agent`).

data/docs/17_METRICS.md

@@ -74,6 +74,8 @@ OpenTelemetry.meter_provider.add_view(
 
 Each instrument is documented here as a row carrying its name, instrument type, unit, and attribute set.
 
+> **Per-call tags become dimensions.** Any tags passed to `#generate` / `#stream` via `tags:` are added as `riffer.tag.<key>` attributes to **every** instrument below — `operation.duration` (each operation), `token.usage` (each point), `cost`, and `guardrail.duration` — so the attribute lists omit them. Tags are promoted verbatim with no allow-list — a high-cardinality value like a unique `user_id` per request multiplies time series accordingly; drop it with a [View](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#view) or keep metric-bound tags low-cardinality. See [Per-Call Tags](03_AGENTS.md#per-call-tags).
+
 ### `gen_ai.client.operation.duration`
 
 Histogram, unit `s`. The latency of a single GenAI operation, recorded around the same wrap as the matching [span](16_TRACING.md) on both the success and error paths and timed with a monotonic clock. Recording is independent of tracing — the metric fires even with `config.tracing.enabled = false`. Tell the three operations apart by `gen_ai.operation.name`.
@@ -123,9 +125,9 @@ Histogram, unit `s`. The latency of a single guardrail execution, recorded aroun
 
 This instrument is Riffer-owned (`riffer.*`, not `gen_ai.*`) by the same reasoning as its span: a guardrail is not a GenAI semantic-convention operation, so the `execute_guardrail` span deliberately carries no `gen_ai.operation.name` and lives in riffer's own `riffer.guardrail.*` namespace (see [Tracing](16_TRACING.md)). Folding the metric into `gen_ai.client.operation.duration` would contradict that, so the duration is its own riffer-owned histogram instead; see [Stability](#stability).
 
-| Value                                | Attributes                                                            |
-| ------------------------------------ | --------------------------------------------------------------------- |
-| duration of the guardrail execution  | `riffer.guardrail.name`, `riffer.guardrail.phase`, `error.type` (on raise) |
+| Value                               | Attributes                                                                 |
+| ----------------------------------- | -------------------------------------------------------------------------- |
+| duration of the guardrail execution | `riffer.guardrail.name`, `riffer.guardrail.phase`, `error.type` (on raise) |
 
 `riffer.guardrail.phase` is `before` or `after`. A pass, transform, or block is a **handled** outcome and records no `error.type` — that attribute carries the exception class only when a guardrail raises, mirroring the span. One time series exists per `riffer.guardrail.name` × `riffer.guardrail.phase`; guardrail names are bounded by the guardrails you configure, so cardinality is safe — unlike the dynamic tool names on `gen_ai.client.operation.duration`.
 

data/lib/riffer/agent/run.rb

@@ -10,37 +10,45 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
-  def generate(agent:, prompt: nil, files: nil)
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
-    run_loop(agent)
+    run_loop(agent, tags: tags)
   end
 
   # Runs the streaming loop for the given agent. See Riffer::Agent#stream
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream(agent:, prompt: nil, files: nil)
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     # The enumerator body runs in its own fiber, where the fiber-local OTEL
-    # context is empty — capture here so the run span parents to the caller's trace.
+    # context is empty — capture here so the run span parents to the caller's
+    # trace. tags ride as an ordinary argument captured in the closure, so they
+    # cross the fiber boundary without any re-propagation.
     trace_context = Riffer::Tracing.current_context
     Enumerator.new do |stream_yielder|
-      Riffer::Tracing.with_context(trace_context) { run_loop(agent, stream_yielder: stream_yielder) }
+      Riffer::Tracing.with_context(trace_context) { run_loop(agent, tags: tags, stream_yielder: stream_yielder) }
     end
   end
 
   private
 
+  # Both +generate+ and +stream+ funnel here, so this is the single place raw
+  # +tags+ are normalized. The clean <tt>String => String</tt> map is then
+  # threaded to every span/metric builder in the run as +riffer.tag.*+ and to
+  # each provider call (via +merged_model_options+) for native request-metadata
+  # mapping.
   #--
-  #: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
-  def run_loop(agent, stream_yielder: nil)
+  #: (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+  def run_loop(agent, tags: {}, stream_yielder: nil)
+    tags = normalize_tags(tags)
     start = Riffer::Metrics.monotonic_now
     error_type = nil #: String?
     begin
-      Riffer::Tracing.in_span("invoke_agent #{agent.class.identifier}", attributes: run_span_attributes(agent), kind: :internal) do |span|
-        response = execute_run(agent, stream_yielder)
+      Riffer::Tracing.in_span("invoke_agent #{agent.class.identifier}", attributes: run_span_attributes(agent, tags), kind: :internal) do |span|
+        response = execute_run(agent, stream_yielder, tags)
         record_run_outcome(span, response)
         response
       rescue => error
@@ -55,18 +63,18 @@ module Riffer::Agent::Run
       error_type = error.class.name #: String?
       raise
     ensure
-      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: run_metric_attributes(agent, error_type))
+      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: run_metric_attributes(agent, error_type, tags))
     end
   end
 
   #--
-  #: (Riffer::Agent, Enumerator::Yielder?) -> Riffer::Agent::Response
-  def execute_run(agent, stream_yielder)
+  #: (Riffer::Agent, Enumerator::Yielder?, ?Hash[String, String]) -> Riffer::Agent::Response
+  def execute_run(agent, stream_yielder, tags = {})
     all_modifications = [] #: Array[Riffer::Guardrails::Modification]
     run_usage = nil #: Riffer::Providers::TokenUsage?
     run_steps = 0
 
-    run_before_guardrails(agent, stream_yielder, all_modifications) do |tripwire|
+    run_before_guardrails(agent, stream_yielder, all_modifications, tags) do |tripwire|
       return tripwire_response(agent, stream_yielder, tripwire, all_modifications, steps: run_steps)
     end
 
@@ -84,16 +92,16 @@ module Riffer::Agent::Run
       step = agent.session.steps
 
       reason = catch(:riffer_interrupt) do
-        execute_pending_tool_calls(agent)
+        execute_pending_tool_calls(agent, tags)
 
         loop do
-          response = stream_yielder ? accumulate_streamed_response(agent, stream_yielder) : call_llm(agent)
+          response = stream_yielder ? accumulate_streamed_response(agent, stream_yielder, tags) : call_llm(agent, tags)
           step += 1
           run_steps += 1
           track_token_usage(agent, response.token_usage)
           run_usage = sum_usage(run_usage, response.token_usage)
 
-          processed_response = run_after_guardrails(agent, response, stream_yielder, all_modifications) do |tripwire|
+          processed_response = run_after_guardrails(agent, response, stream_yielder, all_modifications, tags) do |tripwire|
             return tripwire_response(agent, stream_yielder, tripwire, all_modifications, token_usage: run_usage, steps: run_steps)
           end
 
@@ -104,7 +112,7 @@ module Riffer::Agent::Run
           max_steps = agent.config.max_steps
           throw :riffer_interrupt, Riffer::Agent::INTERRUPT_MAX_STEPS if max_steps && step >= max_steps
 
-          execute_tool_calls(agent, processed_response)
+          execute_tool_calls(agent, processed_response, tags: tags)
         end
 
         return final_response(agent, all_modifications, token_usage: run_usage, steps: run_steps)
@@ -122,14 +130,14 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
-  def accumulate_streamed_response(agent, stream_yielder)
+  #: (Riffer::Agent, Enumerator::Yielder, ?Hash[String, String]) -> Riffer::Messages::Assistant
+  def accumulate_streamed_response(agent, stream_yielder, tags = {})
     accumulated_content = ""
     accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
     accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
     accumulated_finish_reason = nil #: Symbol?
 
-    call_llm_stream(agent).each do |event|
+    call_llm_stream(agent, tags).each do |event|
       stream_yielder << event
 
       case event
@@ -180,33 +188,33 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent) -> Riffer::Messages::Assistant
-  def call_llm(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
+  def call_llm(agent, tags = {})
     agent.provider.generate_text(
       messages: agent.session.messages,
       model: agent.model_name,
       tools: effective_tools(agent),
-      **merged_model_options(agent)
+      **merged_model_options(agent, tags)
     )
   end
 
   #--
-  #: (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def call_llm_stream(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def call_llm_stream(agent, tags = {})
     agent.provider.stream_text(
       messages: agent.session.messages,
       model: agent.model_name,
       tools: effective_tools(agent),
-      **merged_model_options(agent)
+      **merged_model_options(agent, tags)
     )
   end
 
   #--
-  #: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
-  def execute_tool_calls(agent, assistant_message, tool_calls: assistant_message.tool_calls)
+  #: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?tags: Hash[String, String]) -> void
+  def execute_tool_calls(agent, assistant_message, tool_calls: assistant_message.tool_calls, tags: {})
     return if tool_calls.empty?
 
-    results = agent.tool_runtime.execute(tool_calls, tools: effective_tools(agent), context: agent.context, assistant_message: assistant_message)
+    results = agent.tool_runtime.execute(tool_calls, tools: effective_tools(agent), context: agent.context, assistant_message: assistant_message, tags: tags)
 
     inject_discovered_tools(agent, results)
 
@@ -233,19 +241,19 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent) -> void
-  def execute_pending_tool_calls(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> void
+  def execute_pending_tool_calls(agent, tags = {})
     assistant_message, pending = agent.session.pending_tool_calls
-    execute_tool_calls(agent, assistant_message, tool_calls: pending) if assistant_message
+    execute_tool_calls(agent, assistant_message, tool_calls: pending, tags: tags) if assistant_message
   end
 
   #--
-  #: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> void
-  def run_before_guardrails(agent, stream_yielder, all_modifications)
+  #: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> void
+  def run_before_guardrails(agent, stream_yielder, all_modifications, tags = {})
     guardrails = agent.config.guardrails_for(:before)
     return if guardrails.empty?
 
-    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :before, context: agent.context)
+    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :before, context: agent.context, tags: tags)
     processed_messages, tripwire, modifications = runner.run(agent.session.messages)
     agent.session.set(processed_messages) unless tripwire
     record_modifications!(stream_yielder, all_modifications, modifications)
@@ -253,12 +261,12 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
-  def run_after_guardrails(agent, response, stream_yielder, all_modifications)
+  #: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
+  def run_after_guardrails(agent, response, stream_yielder, all_modifications, tags = {})
     guardrails = agent.config.guardrails_for(:after)
     return response if guardrails.empty?
 
-    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :after, context: agent.context)
+    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :after, context: agent.context, tags: tags)
     processed_response, tripwire, modifications = runner.run(response, messages: agent.session.messages)
 
     response_index = agent.session.messages.length
@@ -285,11 +293,16 @@ module Riffer::Agent::Run
     discovered.empty? ? agent.tools : agent.tools + discovered
   end
 
+  # +tags+ rides in the options hash as a curated key the providers extract for
+  # native request-metadata mapping (alongside +:structured_output+); it never
+  # reaches an SDK call verbatim. Span/metric tagging is threaded separately to
+  # each builder.
   #--
-  #: (Riffer::Agent) -> Hash[Symbol, untyped]
-  def merged_model_options(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
+  def merged_model_options(agent, tags = {})
     opts = agent.config.model_options.dup
     opts[:structured_output] = agent.structured_output if agent.structured_output
+    opts[:tags] = tags unless tags.empty?
     opts
   end
 
@@ -329,19 +342,19 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent) -> Hash[String, untyped]
-  def run_span_attributes(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> Hash[String, untyped]
+  def run_span_attributes(agent, tags = {})
     {
       "gen_ai.operation.name" => "invoke_agent",
       "gen_ai.agent.name" => agent.class.identifier,
       "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
       "gen_ai.request.model" => agent.model_name
-    }
+    }.merge(tag_attributes(tags))
   end
 
   #--
-  #: (Riffer::Agent, String?) -> Hash[String, untyped]
-  def run_metric_attributes(agent, error_type)
+  #: (Riffer::Agent, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def run_metric_attributes(agent, error_type, tags = {})
     attributes = {
       "gen_ai.operation.name" => "invoke_agent",
       "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
@@ -349,7 +362,27 @@ module Riffer::Agent::Run
       "gen_ai.agent.name" => agent.class.identifier
     } #: Hash[String, untyped]
     attributes["error.type"] = error_type if error_type
-    attributes
+    attributes.merge(tag_attributes(tags))
+  end
+
+  #--
+  #: (Hash[(String | Symbol), untyped]?) -> Hash[String, String]
+  def normalize_tags(tags)
+    return {} if tags.nil?
+    raise Riffer::ArgumentError, "tags: must be a Hash, got #{tags.class}" unless tags.is_a?(Hash)
+
+    result = {} #: Hash[String, String]
+    tags.each do |key, value|
+      next if value.nil?
+      result[key.to_s] = value.to_s
+    end
+    result
+  end
+
+  #--
+  #: (Hash[String, String]) -> Hash[String, String]
+  def tag_attributes(tags)
+    tags.transform_keys { |key| "riffer.tag.#{key}" }
   end
 
   #--

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/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
@@ -129,7 +133,7 @@ class Riffer::Guardrails::Runner
     {
       "riffer.guardrail.name" => guardrail.name,
       "riffer.guardrail.phase" => phase.to_s
-    }
+    }.merge(tags.transform_keys { |key| "riffer.tag.#{key}" })
   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
@@ -224,6 +227,7 @@ class Riffer::Providers::Base
   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,47 +262,55 @@ 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
 
   #--

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

data/lib/riffer/tools/runtime.rb

@@ -18,14 +18,16 @@ class Riffer::Tools::Runtime
 
   # Executes a batch of tool calls, returning <tt>[tool_call, response]</tt> pairs.
   #--
-  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
-  def execute(tool_calls, tools:, context:, assistant_message: nil)
+  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?, ?tags: Hash[String, String]) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
+  def execute(tool_calls, tools:, context:, assistant_message: nil, tags: {})
     # Each Runner worker runs in its own thread/fiber, where the OTEL context
     # starts empty — capture here so the execute_tool span parents correctly.
+    # tags are an ordinary local captured in the block, so they reach the
+    # worker's span/metric without re-propagation.
     trace_context = Riffer::Tracing.current_context
     @runner.map(tool_calls, context: context) do |tool_call|
       Riffer::Tracing.with_context(trace_context) do
-        instrument_tool_call(tool_call) do
+        instrument_tool_call(tool_call, tags) do
           around_tool_call(tool_call, context: context, assistant_message: assistant_message) do
             dispatch_tool_call(tool_call, tools: tools, context: context, assistant_message: assistant_message)
           end
@@ -57,12 +59,12 @@ class Riffer::Tools::Runtime
   private
 
   #--
-  #: (Riffer::Messages::Assistant::ToolCall) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
-  def instrument_tool_call(tool_call)
+  #: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
+  def instrument_tool_call(tool_call, tags = {})
     start = Riffer::Metrics.monotonic_now
     error_type = nil #: String?
     begin
-      result = in_tool_span(tool_call) do |span|
+      result = in_tool_span(tool_call, tags) do |span|
         response = yield
         record_tool_outcome(span, response)
         response
@@ -73,7 +75,7 @@ class Riffer::Tools::Runtime
       error_type = error.class.name #: String?
       raise
     ensure
-      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: tool_metric_attributes(tool_call, error_type))
+      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: tool_metric_attributes(tool_call, error_type, tags))
     end
   end
 
@@ -113,9 +115,9 @@ class Riffer::Tools::Runtime
 
   # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   #--
-  #: [R] (Riffer::Messages::Assistant::ToolCall) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
-  def in_tool_span(tool_call)
-    Riffer::Tracing.in_span("execute_tool #{tool_call.name}", attributes: tool_span_attributes(tool_call), kind: :internal) do |span|
+  #: [R] (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
+  def in_tool_span(tool_call, tags = {})
+    Riffer::Tracing.in_span("execute_tool #{tool_call.name}", attributes: tool_span_attributes(tool_call, tags), kind: :internal) do |span|
       capture_tool_arguments(span, tool_call)
       yield span
     rescue => error
@@ -127,24 +129,32 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: (Riffer::Messages::Assistant::ToolCall) -> Hash[String, untyped]
-  def tool_span_attributes(tool_call)
+  #: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) -> Hash[String, untyped]
+  def tool_span_attributes(tool_call, tags = {})
     {
       "gen_ai.operation.name" => "execute_tool",
       "gen_ai.tool.name" => tool_call.name,
       "gen_ai.tool.call.id" => tool_call.call_id
-    }
+    }.merge(tag_attributes(tags))
   end
 
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, String?) -> Hash[String, untyped]
-  def tool_metric_attributes(tool_call, error_type)
+  #: (Riffer::Messages::Assistant::ToolCall, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def tool_metric_attributes(tool_call, error_type, tags = {})
     attributes = {
       "gen_ai.operation.name" => "execute_tool",
       "gen_ai.tool.name" => tool_call.name
     } #: Hash[String, untyped]
     attributes["error.type"] = error_type if error_type
-    attributes
+    attributes.merge(tag_attributes(tags))
+  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
 
   # A returned error Response is a handled outcome, so its status stays unset —

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.34.0" #: String
+  VERSION = "0.35.0" #: String
 end

data/sig/generated/riffer/agent/run.rbs

@@ -7,29 +7,34 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   # --
-  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
-  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # Runs the streaming loop for the given agent. See Riffer::Agent#stream
   # for prompt/files semantics.
   #
   # --
-  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   private
 
+  # Both +generate+ and +stream+ funnel here, so this is the single place raw
+  # +tags+ are normalized. The clean <tt>String => String</tt> map is then
+  # threaded to every span/metric builder in the run as +riffer.tag.*+ and to
+  # each provider call (via +merged_model_options+) for native request-metadata
+  # mapping.
   # --
-  # : (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
-  def run_loop: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+  # : (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+  def run_loop: (Riffer::Agent, ?tags: Hash[String | Symbol, untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
 
   # --
-  # : (Riffer::Agent, Enumerator::Yielder?) -> Riffer::Agent::Response
-  def execute_run: (Riffer::Agent, Enumerator::Yielder?) -> Riffer::Agent::Response
+  # : (Riffer::Agent, Enumerator::Yielder?, ?Hash[String, String]) -> Riffer::Agent::Response
+  def execute_run: (Riffer::Agent, Enumerator::Yielder?, ?Hash[String, String]) -> Riffer::Agent::Response
 
   # --
-  # : (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
-  def accumulate_streamed_response: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
+  # : (Riffer::Agent, Enumerator::Yielder, ?Hash[String, String]) -> Riffer::Messages::Assistant
+  def accumulate_streamed_response: (Riffer::Agent, Enumerator::Yielder, ?Hash[String, String]) -> Riffer::Messages::Assistant
 
   # --
   # : (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
@@ -44,32 +49,32 @@ module Riffer::Agent::Run
   def final_response: (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
 
   # --
-  # : (Riffer::Agent) -> Riffer::Messages::Assistant
-  def call_llm: (Riffer::Agent) -> Riffer::Messages::Assistant
+  # : (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
+  def call_llm: (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
 
   # --
-  # : (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def call_llm_stream: (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (Riffer::Agent, ?Hash[String, String]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def call_llm_stream: (Riffer::Agent, ?Hash[String, String]) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   # --
-  # : (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
-  def execute_tool_calls: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
+  # : (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?tags: Hash[String, String]) -> void
+  def execute_tool_calls: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?tags: Hash[String, String]) -> void
 
   # --
   # : (Riffer::Agent, Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]) -> void
   def inject_discovered_tools: (Riffer::Agent, Array[[ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]]) -> void
 
   # --
-  # : (Riffer::Agent) -> void
-  def execute_pending_tool_calls: (Riffer::Agent) -> void
+  # : (Riffer::Agent, ?Hash[String, String]) -> void
+  def execute_pending_tool_calls: (Riffer::Agent, ?Hash[String, String]) -> void
 
   # --
-  # : (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> void
-  def run_before_guardrails: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> void
+  # : (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> void
+  def run_before_guardrails: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> void
 
   # --
-  # : (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
-  def run_after_guardrails: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
+  # : (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
+  def run_after_guardrails: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
 
   # --
   # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
@@ -79,9 +84,13 @@ module Riffer::Agent::Run
   # : (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
   def effective_tools: (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
 
+  # +tags+ rides in the options hash as a curated key the providers extract for
+  # native request-metadata mapping (alongside +:structured_output+); it never
+  # reaches an SDK call verbatim. Span/metric tagging is threaded separately to
+  # each builder.
   # --
-  # : (Riffer::Agent) -> Hash[Symbol, untyped]
-  def merged_model_options: (Riffer::Agent) -> Hash[Symbol, untyped]
+  # : (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
+  def merged_model_options: (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
 
   # --
   # : (Riffer::Agent, String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
@@ -102,12 +111,20 @@ module Riffer::Agent::Run
   def sum_usage: (Riffer::Providers::TokenUsage?, Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
 
   # --
-  # : (Riffer::Agent) -> Hash[String, untyped]
-  def run_span_attributes: (Riffer::Agent) -> Hash[String, untyped]
+  # : (Riffer::Agent, ?Hash[String, String]) -> Hash[String, untyped]
+  def run_span_attributes: (Riffer::Agent, ?Hash[String, String]) -> Hash[String, untyped]
 
   # --
-  # : (Riffer::Agent, String?) -> Hash[String, untyped]
-  def run_metric_attributes: (Riffer::Agent, String?) -> Hash[String, untyped]
+  # : (Riffer::Agent, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def run_metric_attributes: (Riffer::Agent, String?, ?Hash[String, String]) -> Hash[String, untyped]
+
+  # --
+  # : (Hash[(String | Symbol), untyped]?) -> Hash[String, String]
+  def normalize_tags: (Hash[String | Symbol, untyped]?) -> Hash[String, String]
+
+  # --
+  # : (Hash[String, String]) -> Hash[String, String]
+  def tag_attributes: (Hash[String, String]) -> Hash[String, String]
 
   # --
   # : (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void

data/sig/generated/riffer/agent.rbs

@@ -124,13 +124,13 @@ 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: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def self.generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # 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: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?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: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   # Reconstructs a runnable agent from a wire hash produced by +#to_h+.
   # --
@@ -213,18 +213,25 @@ 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: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # 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: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   # Interrupts the agent loop from an +on_message+ callback. Equivalent to
   # <tt>throw :riffer_interrupt, reason</tt>.

data/sig/generated/riffer/guardrails/runner.rbs

@@ -12,9 +12,12 @@ 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: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped) -> void
+  # : (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void
+  def initialize: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void
 
   # Runs the guardrails sequentially. For the +:before+ phase +data+ is the
   # messages array; for +:after+ it's the response (and +messages+ must be

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

@@ -99,22 +99,28 @@ class Riffer::Providers::Base
   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?, ?Hash[String, String]) -> Hash[String, untyped]
+  def chat_metric_base_attributes: (String?, ?Hash[String, String]) -> Hash[String, untyped]
 
   # --
-  # : (String?, String?) -> Hash[String, untyped]
-  def chat_metric_attributes: (String?, String?) -> Hash[String, untyped]
+  # : (String?, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def chat_metric_attributes: (String?, String?, ?Hash[String, String]) -> Hash[String, untyped]
+
+  # 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: (Hash[String, String]) -> Hash[String, String]
 
   # 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
+  # : (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
+  def record_token_usage_metric: (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> 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
+  # : (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
+  def record_cost_metric: (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
 
   # --
   # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Symbol?, String?) -> void

data/sig/generated/riffer/tools/runtime.rbs

@@ -12,8 +12,8 @@ class Riffer::Tools::Runtime
 
   # Executes a batch of tool calls, returning <tt>[tool_call, response]</tt> pairs.
   # --
-  # : (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
-  def execute: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]]
+  # : (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?, ?tags: Hash[String, String]) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
+  def execute: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?, ?tags: Hash[String, String]) -> Array[[ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]]
 
   # Hook wrapping each tool call; override in subclasses to instrument or
   # customize. Must +yield+ to continue.
@@ -36,8 +36,8 @@ class Riffer::Tools::Runtime
   private
 
   # --
-  # : (Riffer::Messages::Assistant::ToolCall) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
-  def instrument_tool_call: (Riffer::Messages::Assistant::ToolCall) { () -> Riffer::Tools::Response } -> [ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]
+  # : (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
+  def instrument_tool_call: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { () -> Riffer::Tools::Response } -> [ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]
 
   # --
   # : (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
@@ -49,16 +49,22 @@ class Riffer::Tools::Runtime
 
   # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   # --
-  # : [R] (Riffer::Messages::Assistant::ToolCall) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
-  def in_tool_span: [R] (Riffer::Messages::Assistant::ToolCall) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
+  # : [R] (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
+  def in_tool_span: [R] (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
 
   # --
-  # : (Riffer::Messages::Assistant::ToolCall) -> Hash[String, untyped]
-  def tool_span_attributes: (Riffer::Messages::Assistant::ToolCall) -> Hash[String, untyped]
+  # : (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) -> Hash[String, untyped]
+  def tool_span_attributes: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) -> Hash[String, untyped]
 
   # --
-  # : (Riffer::Messages::Assistant::ToolCall, String?) -> Hash[String, untyped]
-  def tool_metric_attributes: (Riffer::Messages::Assistant::ToolCall, String?) -> Hash[String, untyped]
+  # : (Riffer::Messages::Assistant::ToolCall, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def tool_metric_attributes: (Riffer::Messages::Assistant::ToolCall, String?, ?Hash[String, String]) -> Hash[String, untyped]
+
+  # 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: (Hash[String, String]) -> Hash[String, String]
 
   # A returned error Response is a handled outcome, so its status stays unset —
   # an error span status is reserved for a raised exception.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.35.0
 platform: ruby
 authors:
 - Jake Bottrall