llm.rb 15.2.2 → 15.4.0

data/lib/llm/providers/openai/audio.rb

@@ -35,13 +35,13 @@ class LLM::OpenAI
       req = LLM::Transport::Request.post(path("/audio/speech"), headers)
       req.body = LLM.json.dump({input:, voice:, model:, response_format:}.merge!(params))
       io = StringIO.new("".b)
-      res, span, tracer = execute(request: req, operation: "request") { _1.read_body { |chunk| io << chunk } }
+      res, span, tracer, request_id = execute(request: req, operation: "request") { _1.read_body { |chunk| io << chunk } }
       content_type = res["content-type"].to_s.split(";").first
       content_type = content_type.empty? ? LLM::Mime[".#{response_format}"] : content_type
       data = "data:#{content_type};base64,#{[io.string].pack("m0")}"
       res.body = LLM::Object.from(audio: data)
       res = ResponseAdapter.adapt(LLM::Response.new(res), type: :audio)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:, request_id:)
       res
     end
 
@@ -62,9 +62,9 @@ class LLM::OpenAI
       req = LLM::Transport::Request.post(path("/audio/transcriptions"), headers)
       req["content-type"] = multi.content_type
       transport.set_body_stream(req, multi.body)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:, request_id:)
       res
     end
 
@@ -86,9 +86,9 @@ class LLM::OpenAI
       req = LLM::Transport::Request.post(path("/audio/translations"), headers)
       req["content-type"] = multi.content_type
       transport.set_body_stream(req, multi.body)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:, request_id:)
       res
     end
 

data/lib/llm/providers/openai/error_handler.rb

@@ -21,10 +21,13 @@ class LLM::OpenAI
     #  The span
     # @param [LLM::Transport::Response, Net::HTTPResponse] res
     #  The response from the server
+    # @param [String] request_id
+    #  The id of the request that failed
     # @return [LLM::OpenAI::ErrorHandler]
-    def initialize(tracer, span, res)
+    def initialize(tracer, span, res, request_id)
       @tracer = tracer
       @span = span
+      @request_id = request_id
       @res = LLM::Transport::Response.from(res)
     end
 
@@ -33,7 +36,7 @@ class LLM::OpenAI
     #  Raises a subclass of {LLM::Error LLM::Error}
     def raise_error!
       ex = error
-      @tracer.on_request_error(ex:, span:)
+      @tracer.on_request_error(ex:, span:, request_id: @request_id)
     ensure
       raise(ex) if ex
     end

data/lib/llm/providers/openai/files.rb

@@ -41,9 +41,9 @@ class LLM::OpenAI
     def all(**params)
       query = URI.encode_www_form(params)
       req = LLM::Transport::Request.get(path("/files?#{query}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -63,9 +63,9 @@ class LLM::OpenAI
       req = LLM::Transport::Request.post(path("/files"), headers)
       req["content-type"] = multi.content_type
       transport.set_body_stream(req, multi.body)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -84,9 +84,9 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       query = URI.encode_www_form(params)
       req = LLM::Transport::Request.get(path("/files/#{file_id}?#{query}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -107,9 +107,9 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       req = LLM::Transport::Request.get(path("/files/#{file_id}/content?#{query}"), headers)
       io = StringIO.new("".b)
-      res, span, tracer = execute(request: req, operation: "request") { |res| res.read_body { |chunk| io << chunk } }
+      res, span, tracer, request_id = execute(request: req, operation: "request") { |res| res.read_body { |chunk| io << chunk } }
       res = LLM::Response.new(res).tap { _1.define_singleton_method(:file) { io } }
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -126,9 +126,9 @@ class LLM::OpenAI
     def delete(file:)
       file_id = file.respond_to?(:id) ? file.id : file
       req = LLM::Transport::Request.delete(path("/files/#{file_id}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 

data/lib/llm/providers/openai/images.rb

@@ -38,9 +38,9 @@ class LLM::OpenAI
     def create(prompt:, model: "gpt-image-1-mini", output_format: "png", **params)
       req = LLM::Transport::Request.post(path("/images/generations"), headers)
       req.body = LLM.json.dump({prompt:, n: 1, model:, output_format:}.merge!(params))
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :image)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:, request_id:)
       res
     end
 
@@ -64,9 +64,9 @@ class LLM::OpenAI
       req = LLM::Transport::Request.post(path("/images/edits"), headers)
       req["content-type"] = multi.content_type
       transport.set_body_stream(req, multi.body)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :image)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:, request_id:)
       res
     end
 

data/lib/llm/providers/openai/models.rb

@@ -40,9 +40,9 @@ class LLM::OpenAI
     def all(**params)
       query = URI.encode_www_form(params)
       req = LLM::Transport::Request.get(path("/models?#{query}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :models)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 

data/lib/llm/providers/openai/moderations.rb

@@ -50,9 +50,9 @@ class LLM::OpenAI
       req = LLM::Transport::Request.post(path("/moderations"), headers)
       input = RequestAdapter::Moderation.new(input).adapt
       req.body = LLM.json.dump({input:, model:}.merge!(params))
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :moderations)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:, request_id:)
       res
     end
 

data/lib/llm/providers/openai/request_adapter.rb

@@ -36,7 +36,7 @@ class LLM::OpenAI
       {
         response_format: {
           type: "json_schema",
-          json_schema: {name: "JSONSchema", schema:}
+          json_schema: {name: "JSONSchema", schema: LLM::Schema::Utils.close(schema)}
         }
       }
     end

data/lib/llm/providers/openai/responses.rb

@@ -54,10 +54,10 @@ class LLM::OpenAI
       params.delete(:input)
       body = LLM.json.dump({input: [adapt(messages, mode: :response)].flatten}.merge!(params))
       transport.set_body_stream(req, StringIO.new(body))
-      res, span, tracer = execute(request: req, stream:, stream_parser:, operation: "chat", model: params[:model])
+      res, span, tracer, request_id = execute(request: req, stream:, stream_parser:, operation: "chat", model: params[:model])
       res = ResponseAdapter.adapt(res, type: :responds)
         .extend(Module.new { define_method(:__tools__) { tools } })
-      tracer.on_request_finish(operation: "chat", model: params[:model], res:, span:)
+      tracer.on_request_finish(operation: "chat", model: params[:model], res:, span:, request_id:)
       res
     end
 
@@ -71,9 +71,9 @@ class LLM::OpenAI
       response_id = response.respond_to?(:id) ? response.id : response
       query = URI.encode_www_form(params)
       req = LLM::Transport::Request.get(path("/responses/#{response_id}?#{query}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :responds)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -86,9 +86,9 @@ class LLM::OpenAI
     def delete(response)
       response_id = response.respond_to?(:id) ? response.id : response
       req = LLM::Transport::Request.delete(path("/responses/#{response_id}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -98,7 +98,7 @@ class LLM::OpenAI
     def adapt_function(fn)
       {
         type: "function", name: fn.name, description: fn.description,
-        parameters: fn.params.to_h.merge(additionalProperties: false), strict: false
+        parameters: LLM::Schema::Utils.close(fn.params), strict: false
       }.compact
     end
 
@@ -112,7 +112,7 @@ class LLM::OpenAI
       return {} unless params && params[:schema]
       schema = params.delete(:schema)
       schema = schema.respond_to?(:object) ? schema.object : schema
-      schema = schema.to_h.merge(additionalProperties: false)
+      schema = LLM::Schema::Utils.close(schema)
       name = "JSONSchema"
       {text: {format: {type: "json_schema", name:, schema:}}}
     end

data/lib/llm/providers/openai/vector_stores.rb

@@ -32,9 +32,9 @@ class LLM::OpenAI
     def all(**params)
       query = URI.encode_www_form(params)
       req = LLM::Transport::Request.get(path("/vector_stores?#{query}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -49,9 +49,9 @@ class LLM::OpenAI
     def create(name:, file_ids: nil, **params)
       req = LLM::Transport::Request.post(path("/vector_stores"), headers)
       req.body = LLM.json.dump(params.merge({name:, file_ids:}).compact)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -73,9 +73,9 @@ class LLM::OpenAI
     def get(vector:)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       req = LLM::Transport::Request.get(path("/vector_stores/#{vector_id}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -91,9 +91,9 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       req = LLM::Transport::Request.post(path("/vector_stores/#{vector_id}"), headers)
       req.body = LLM.json.dump(params.merge({name:}).compact)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -106,9 +106,9 @@ class LLM::OpenAI
     def delete(vector:)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       req = LLM::Transport::Request.delete(path("/vector_stores/#{vector_id}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -124,9 +124,9 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       req = LLM::Transport::Request.post(path("/vector_stores/#{vector_id}/search"), headers)
       req.body = LLM.json.dump(params.merge({query:}).compact)
-      res, span, tracer = execute(request: req, operation: "retrieval")
+      res, span, tracer, request_id = execute(request: req, operation: "retrieval")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      tracer.on_request_finish(operation: "retrieval", res:, span:)
+      tracer.on_request_finish(operation: "retrieval", res:, span:, request_id:)
       res
     end
 
@@ -141,9 +141,9 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       query = URI.encode_www_form(params)
       req = LLM::Transport::Request.get(path("/vector_stores/#{vector_id}/files?#{query}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -161,9 +161,9 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       req = LLM::Transport::Request.post(path("/vector_stores/#{vector_id}/files"), headers)
       req.body = LLM.json.dump(params.merge({file_id:, attributes:}).compact)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
     alias_method :create_file, :add_file
@@ -192,9 +192,9 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       req = LLM::Transport::Request.post(path("/vector_stores/#{vector_id}/files/#{file_id}"), headers)
       req.body = LLM.json.dump(params.merge({attributes:}).compact)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -210,9 +210,9 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       query = URI.encode_www_form(params)
       req = LLM::Transport::Request.get(path("/vector_stores/#{vector_id}/files/#{file_id}?#{query}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 
@@ -227,9 +227,9 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       file_id = file.respond_to?(:id) ? file.id : file
       req = LLM::Transport::Request.delete(path("/vector_stores/#{vector_id}/files/#{file_id}"), headers)
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      tracer.on_request_finish(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:, request_id:)
       res
     end
 

data/lib/llm/providers/openai.rb

@@ -54,9 +54,9 @@ module LLM
     def embed(input, model: "text-embedding-3-small", **params)
       req = LLM::Transport::Request.post(path("/embeddings"), headers)
       req.body = LLM.json.dump({input:, model:}.merge!(params))
-      res, span, tracer = execute(request: req, operation: "embeddings", model:)
+      res, span, tracer, request_id = execute(request: req, operation: "embeddings", model:)
       res = ResponseAdapter.adapt(res, type: :embedding)
-      tracer.on_request_finish(operation: "embeddings", model:, res:, span:)
+      tracer.on_request_finish(operation: "embeddings", model:, res:, span:, request_id:)
       res
     end
 
@@ -74,10 +74,10 @@ module LLM
       params, stream, tools, role = normalize_complete_params(params)
       req, messages = build_complete_request(prompt, params, role)
       tracer.set_request_metadata(user_input: extract_user_input(messages, fallback: prompt))
-      res, span, tracer = execute(request: req, stream: stream, operation: "chat", model: params[:model])
+      res, span, tracer, request_id = execute(request: req, stream: stream, operation: "chat", model: params[:model])
       res = ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
-      tracer.on_request_finish(operation: "chat", model: params[:model], res:, span:)
+      tracer.on_request_finish(operation: "chat", model: params[:model], res:, span:, request_id:)
       res
     end
 
@@ -156,10 +156,10 @@ module LLM
     # @param [LLM::Function] fn
     # @return [Hash]
     def adapt_function(fn)
-      params = fn.params.to_h
+      params = LLM::Schema::Utils.close(fn.params)
       {
-        type: "function", name: fn.name,
-        function: {name: fn.name, description: fn.description, parameters: params}
+        type: "function",
+        function: {name: fn.name, description: fn.description, parameters: params, strict: false}
       }.compact
     end
 
@@ -203,7 +203,9 @@ module LLM
 
     def headers
       lock do
-        (@headers || {}).merge(
+        (@headers || {})
+        .merge(temporary_headers)
+        .merge(
           "Content-Type" => "application/json",
           "Authorization" => "Bearer #{@key}"
         )

data/lib/llm/providers/xai/images.rb

@@ -34,9 +34,9 @@ class LLM::XAI
     def create(prompt:, model: "grok-imagine-image-quality", **params)
       req = LLM::Transport::Request.post(path("/images/generations"), headers)
       req.body = LLM.json.dump({prompt:, n: 1, model:, response_format: "b64_json"}.merge!(params))
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::OpenAI::ResponseAdapter.adapt(res, type: :image)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:, request_id:)
       res
     end
 
@@ -61,9 +61,9 @@ class LLM::XAI
         image: image_url(image),
         response_format: "b64_json"
       }.merge!(params))
-      res, span, tracer = execute(request: req, operation: "request")
+      res, span, tracer, request_id = execute(request: req, operation: "request")
       res = LLM::OpenAI::ResponseAdapter.adapt(res, type: :image)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:, request_id:)
       res
     end
 

data/lib/llm/schema.rb

@@ -81,6 +81,30 @@ class LLM::Schema
     def fetch(properties, name)
       properties[name] || properties.fetch(name.to_s)
     end
+
+    ##
+    # Returns a copy of a JSON schema where every object is
+    # closed with "additionalProperties": false. OpenAI and
+    # Azure reject tool parameters that leave an object open,
+    # and they validate nested objects as well as the root.
+    # @param [Object] node
+    #  A schema, a Hash of properties, or an Array of either
+    # @return [Object]
+    def close(node)
+      case node
+      when LLM::Schema::Leaf
+        close(node.to_h)
+      when LLM::Object
+        close(node.to_h)
+      when Hash
+        node.to_h { |key, value| [key, close(value)] }
+            .then { _1[:type] == "object" ? _1.merge(additionalProperties: false) : _1 }
+      when Array
+        node.map { close(_1) }
+      else
+        node
+      end
+    end
   end
 
   ##

data/lib/llm/tracer/telemetry.rb

@@ -86,7 +86,7 @@ module LLM
 
     ##
     # @param (see LLM::Tracer#on_request_start)
-    def on_request_start(operation:, model: nil, inputs: nil)
+    def on_request_start(operation:, model: nil, inputs: nil, request_id:)
       case operation
       when "chat" then start_chat(operation:, model:, inputs:)
       when "retrieval" then start_retrieval(operation:)
@@ -96,7 +96,7 @@ module LLM
 
     ##
     # @param (see LLM::Tracer#on_request_finish)
-    def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil)
+    def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil, request_id:)
       return nil unless span
       case operation
       when "chat" then finish_chat(operation:, model:, res:, span:, outputs:, metadata:)
@@ -107,7 +107,7 @@ module LLM
 
     ##
     # @param (see LLM::Tracer#on_request_error)
-    def on_request_error(ex:, span:)
+    def on_request_error(ex:, span:, request_id:)
       return nil unless span
       attributes = {"error.type" => ex.class.to_s}.compact
       attributes.each { span.set_attribute(_1, _2) }
@@ -305,7 +305,7 @@ module LLM
         "gen_ai.operation.name" => operation,
         "gen_ai.request.model" => model,
         "gen_ai.response.id" => res.id,
-        "gen_ai.response.model" => model,
+        "gen_ai.response.model" => res.model,
         "gen_ai.usage.input_tokens" => res.usage.input_tokens,
         "gen_ai.usage.output_tokens" => res.usage.output_tokens,
         "output.value" => serialize_request_value(output_value)

data/lib/llm/tracer.rb

@@ -66,8 +66,12 @@ module LLM
     # @param [String] operation
     # @param [String] model
     # @param [Hash, nil] inputs Optional span attributes (e.g. gen_ai.input.messages) from llm.rb or caller.
+    # @param [String] request_id
+    #  The id of the request. It is a UUIDv7, and it is shared by
+    #  {#on_request_start}, {#on_request_finish}, and {#on_request_error}
+    #  for the same request.
     # @return [void]
-    def on_request_start(operation:, model: nil, inputs: nil)
+    def on_request_start(operation:, model: nil, inputs: nil, request_id:)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
@@ -79,8 +83,10 @@ module LLM
     # @param [String] model
     # @param [Hash, nil] outputs Optional span attributes (e.g. gen_ai.output.messages) from llm.rb or caller.
     # @param [Hash, nil] metadata Optional metadata from llm.rb or caller.
+    # @param [String] request_id
+    #  The id of the request, as passed to {#on_request_start}
     # @return [void]
-    def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil)
+    def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil, request_id:)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
@@ -88,8 +94,10 @@ module LLM
     # Called when an LLM provider request fails.
     # @param [LLM::Error] ex
     # @param [Object, nil] span
+    # @param [String] request_id
+    #  The id of the request, as passed to {#on_request_start}
     # @return [void]
-    def on_request_error(ex:, span:)
+    def on_request_error(ex:, span:, request_id:)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 

data/lib/llm/transport/execution.rb

@@ -33,10 +33,11 @@ class LLM::Transport
       stream &&= LLM::Object.from(streamer: stream, parser: stream_parser, decoder: stream_decoder)
       owner = transport.request_owner
       tracer = self.tracer
-      span = tracer.on_request_start(operation:, model:, inputs:)
+      request_id = SecureRandom.uuid_v7
+      span = tracer.on_request_start(operation:, model:, inputs:, request_id:)
       res = transport.request(request, owner:, stream:, &b)
       res = LLM::Transport::Response.from(res)
-      [handle_response(res, tracer, span), span, tracer]
+      [handle_response(res, tracer, span, request_id), span, tracer, request_id]
     rescue *transport.interrupt_errors
       raise LLM::Interrupt, "request interrupted" if transport.interrupted?(owner)
       raise
@@ -48,9 +49,12 @@ class LLM::Transport
     #  The response to handle
     # @param [Object, nil] span
     #  The span
+    # @param [String] request_id
+    #  The id of the request being handled
     # @return [LLM::Transport::Response]
-    def handle_response(res, tracer, span)
-      res.ok? ? res.body = parse_response(res) : error_handler.new(tracer, span, res).raise_error!
+    def handle_response(res, tracer, span, request_id)
+      res.ok? ? res.body = parse_response(res) :
+                           error_handler.new(tracer, span, res, request_id).raise_error!
       res
     end
 

data/lib/llm/utils.rb

@@ -48,6 +48,19 @@ module LLM
       (defined?(::Sequel::Model) and ::Sequel::Model === obj)
     end
 
+    ##
+    # Returns the UTC time encoded in a UUIDv7, or nil when the
+    # given value is not a UUIDv7. The first 48 bits of a UUIDv7
+    # are a Unix millisecond timestamp.
+    # @param [Object] id
+    # @return [Time, nil]
+    def timestamp(id)
+      hex = id.to_s.delete("-")
+      return nil unless hex.match?(/\A\h{32}\z/)
+      return nil unless hex[12] == "7"
+      Time.at(hex[0, 12].to_i(16) / 1000.0).utc
+    end
+
     ##
     # Normalizes an HTTP API base path.
     #

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "15.2.2"
+  VERSION = "15.4.0"
 end

data/llm.gemspec

@@ -35,9 +35,9 @@ DESCRIPTION
   spec.executables = ["llm.rb"]
   spec.require_paths = ["lib"]
   spec.post_install_message = "\n" \
-                              "Got a question about llm.rb? " \
+                              "Want to see what I'm building with llm.rb? " \
                               "\n" \
-                              "The https://r.uby.dev website can help." \
+                              "Checkout the https://r.uby.dev website." \
                               "\n\n"
 
   spec.add_development_dependency "webmock", "~> 3.24.0"