llm.rb 4.4.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 357446a155ea5c66f1f1de5e2172f021bfa339c1006bae3f35a18b1c1ad173a7
-  data.tar.gz: 4726be4c9133aa0da37771c6a16ba1eab27771acee6826a259f624a199cf8088
+  metadata.gz: c8252114d7ab58f00fd2d14389e932cfa9b2f0a71d96d9ea2c261f1f8b67d721
+  data.tar.gz: 8c00745ba750d0e271d8a4e5d5d9418a13556847c181e912aa8a8a1e7a9344b5
 SHA512:
-  metadata.gz: b97ee9fc6594633d4176d21651a9625e8cd7c55d7d66d9e3a8a0bf5314df957447e7b4af431f57cd5e9c47408ceefc08babbb868af05d9ef7b887e543c6914a8
-  data.tar.gz: 5881e618855cf3c9830fcc5edad571b2cb015a514ab99fcd4134e09402fda6ff51e7d034d50e96988739747a0dc5520b40c4938b9f1a0ed9af328dde22a48c99
+  metadata.gz: 9b45173644a3803db844c1cad679a14ec647e058bd4517ce0160b7f2f352480877375748a4abb727007d3c76e7b977a6c106a5bfa438575f69ef8cd60a5612d2
+  data.tar.gz: bebdb107819b1410bc6644529ad0f56544deadbae9661ab8ed2c84a420c74097b357113650de7ed7da1d0b388c601a9b7e60e30d887b62d72e7cfb84f3f0dd1a

data/README.md

@@ -4,7 +4,7 @@
 <p align="center">
   <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1"><img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc"></a>
   <a href="https://opensource.org/license/0bsd"><img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License"></a>
-  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.4.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.5.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -177,11 +177,47 @@ end
 ses.talk(prompt)
 ```
 
+#### Threads
+
+llm.rb is designed for threaded environments with throughput in mind.
+Locks are used selectively, and localized state is preferred wherever
+possible. Blanket locking across every class would help guarantee
+correctness but it would also add contention, reduce throughput,
+and increase complexity.
+
+That's why we decided to optimize for both correctness and throughput
+instead. An important part of that design is guaranteeing that
+[LLM::Provider](https://0x1eef.github.io/x/llm.rb/LLM/Provider.html)
+is safe to share across threads. [LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html) and
+[LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html) are
+stateful objects that should be kept local to a single thread. So the
+recommended pattern is to keep one session or agent per thread,
+and share a provider across multiple threads:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"], persistent: true)
+schema = llm.schema.object(answer: llm.schema.integer.required)
+
+vals = 10.times.map do |x|
+  Thread.new do
+    ses = LLM::Session.new(llm, schema:)
+    res = ses.talk "#{x} + 5 = ?"
+    res.messages.find(&:assistant?).content!
+  end
+end.map(&:value)
+
+vals.each { |val| puts val }
+```
+
 ## Features
 
 #### General
 - ✅  Unified API across providers
 - 📦  Zero runtime deps (stdlib-only)
+- 🧵  Thread-safe providers for multi-threaded workloads
 - 🧩  Pluggable JSON adapters (JSON, Oj, Yajl, etc)
 - 🧱  Builtin tracer API ([LLM::Tracer](https://0x1eef.github.io/x/llm.rb/LLM/Tracer.html))
 
@@ -438,18 +474,6 @@ ses2.restore(string: json)
 ses2.talk "Howdy partner. I'm back"
 ```
 
-#### Thread Safety
-
-The llm.rb library is thread-safe and can be used in a multi-threaded
-environments but it is important to keep in mind that the
-[LLM::Provider](https://0x1eef.github.io/x/llm.rb/LLM/Provider.html)
-and
-[LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html)
-classes should be instantiated once per thread, and not shared
-between threads. Generally the library tries to avoid global or
-shared state but where it exists reentrant locks are used to
-ensure thread-safety.
-
 ### Tools
 
 #### LLM::Function

data/lib/llm/provider.rb

@@ -36,10 +36,11 @@ class LLM::Provider
     @port = port
     @timeout = timeout
     @ssl = ssl
-    @client = persistent ? persistent_client : transient_client
+    @client = persistent ? persistent_client : nil
     @tracer = LLM::Tracer::Null.new(self)
     @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
     @headers = {"User-Agent" => "llm.rb v#{LLM::VERSION}"}
+    @monitor = Monitor.new
   end
 
   ##
@@ -182,7 +183,7 @@ class LLM::Provider
   # Returns an object that can generate a JSON schema
   # @return [LLM::Schema]
   def schema
-    @schema ||= LLM::Schema.new
+    LLM::Schema.new
   end
 
   ##
@@ -196,7 +197,9 @@ class LLM::Provider
   # @return [LLM::Provider]
   #  Returns self
   def with(headers:)
-    tap { @headers.merge!(headers) }
+    lock do
+      tap { @headers.merge!(headers) }
+    end
   end
 
   ##
@@ -277,10 +280,12 @@ class LLM::Provider
   #  A tracer
   # @return [void]
   def tracer=(tracer)
-    @tracer = if tracer.nil?
-      LLM::Tracer::Null.new(self)
-    else
-      tracer
+    lock do
+      @tracer = if tracer.nil?
+        LLM::Tracer::Null.new(self)
+      else
+        tracer
+      end
     end
   end
 
@@ -336,10 +341,12 @@ class LLM::Provider
   #  When there is a network error at the operating system level
   # @return [Net::HTTPResponse]
   def execute(request:, operation:, stream: nil, stream_parser: self.stream_parser, model: nil, &b)
-    span = @tracer.on_request_start(operation:, model:)
-    args = (Net::HTTP === client) ? [request] : [URI.join(base_uri, request.path), request]
+    tracer = @tracer
+    span = tracer.on_request_start(operation:, model:)
+    http = client || transient_client
+    args = (Net::HTTP === http) ? [request] : [URI.join(base_uri, request.path), request]
     res = if stream
-      client.request(*args) do |res|
+      http.request(*args) do |res|
         handler = event_handler.new stream_parser.new(stream)
         parser = LLM::EventStream::Parser.new
         parser.register(handler)
@@ -353,10 +360,10 @@ class LLM::Provider
         parser&.free
       end
     else
-      b ? client.request(*args) { (Net::HTTPSuccess === _1) ? b.call(_1) : _1 } :
-          client.request(*args)
+      b ? http.request(*args) { (Net::HTTPSuccess === _1) ? b.call(_1) : _1 } :
+          http.request(*args)
     end
-    [handle_response(res, span), span]
+    [handle_response(res, tracer, span), span, tracer]
   end
 
   ##
@@ -366,14 +373,18 @@ class LLM::Provider
   # @param [Object, nil] span
   #  The span
   # @return [Net::HTTPResponse]
-  def handle_response(res, span)
+  def handle_response(res, tracer, span)
     case res
     when Net::HTTPOK then res.body = parse_response(res)
-    else error_handler.new(@tracer, span, res).raise_error!
+    else error_handler.new(tracer, span, res).raise_error!
     end
     res
   end
 
+  ##
+  # Parse a HTTP response
+  # @param [Net::HTTPResponse] res
+  # @return [LLM::Object, String]
   def parse_response(res)
     case res["content-type"]
     when %r|\Aapplication/json\s*| then LLM::Object.from(LLM.json.load(res.body))
@@ -418,14 +429,8 @@ class LLM::Provider
   end
 
   ##
-  # Finalizes tracing after a response has been adapted/wrapped.
-  # @param [String] operation
-  # @param [String, nil] model
-  # @param [LLM::Response] res
-  # @param [Object, nil] span
-  # @return [LLM::Response]
-  def finish_trace(operation:, res:, model: nil, span: nil)
-    @tracer.on_request_finish(operation:, model:, res:, span:)
-    res
+  # @api private
+  def lock(&)
+    @monitor.synchronize(&)
   end
 end

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

@@ -38,9 +38,10 @@ class LLM::Anthropic
     def all(**params)
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/files?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -58,9 +59,10 @@ class LLM::Anthropic
       req = Net::HTTP::Post.new("/v1/files", headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -78,9 +80,10 @@ class LLM::Anthropic
       file_id = file.respond_to?(:id) ? file.id : file
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/files/#{file_id}?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -98,9 +101,10 @@ class LLM::Anthropic
       query = URI.encode_www_form(params)
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Get.new("/v1/files/#{file_id}?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
     alias_method :retrieve_metadata, :get_metadata
 
@@ -117,9 +121,10 @@ class LLM::Anthropic
     def delete(file:)
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Delete.new("/v1/files/#{file_id}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -142,9 +147,10 @@ class LLM::Anthropic
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Get.new("/v1/files/#{file_id}/content?#{query}", headers)
       io = StringIO.new("".b)
-      res, span = execute(request: req, operation: "request") { |res| res.read_body { |chunk| io << chunk } }
+      res, span, tracer = execute(request: req, operation: "request") { |res| res.read_body { |chunk| io << chunk } }
       res = LLM::Response.new(res).tap { _1.define_singleton_method(:file) { io } }
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     private
@@ -153,7 +159,7 @@ class LLM::Anthropic
       @provider.instance_variable_get(:@key)
     end
 
-    [:headers, :execute, :set_body_stream, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -40,14 +40,15 @@ class LLM::Anthropic
     def all(**params)
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/models?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     private
 
-    [:headers, :execute, :finish_trace].each do |m|
+    [:headers, :execute].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/anthropic.rb

@@ -43,10 +43,11 @@ module LLM
     def complete(prompt, params = {})
       params, stream, tools, role = normalize_complete_params(params)
       req = build_complete_request(prompt, params, role)
-      res, span = execute(request: req, stream: stream, operation: "chat", model: params[:model])
+      res, span, tracer = execute(request: req, stream: stream, operation: "chat", model: params[:model])
       res = ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
-      finish_trace(operation: "chat", model: params[:model], res:, span:)
+      tracer.on_request_finish(operation: "chat", model: params[:model], res:, span:)
+      res
     end
 
     ##
@@ -110,12 +111,14 @@ module LLM
     private
 
     def headers
-      (@headers || {}).merge(
-        "Content-Type" => "application/json",
-        "x-api-key" => @key,
-        "anthropic-version" => "2023-06-01",
-        "anthropic-beta" => "files-api-2025-04-14"
-      )
+      lock do
+        (@headers || {}).merge(
+          "Content-Type" => "application/json",
+          "x-api-key" => @key,
+          "anthropic-version" => "2023-06-01",
+          "anthropic-beta" => "files-api-2025-04-14"
+        )
+      end
     end
 
     def stream_parser

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

@@ -46,9 +46,10 @@ class LLM::Gemini
     def all(**params)
       query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/files?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :files)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -69,9 +70,10 @@ class LLM::Gemini
       req["X-Goog-Upload-Command"] = "upload, finalize"
       file.with_io do |io|
         set_body_stream(req, io)
-        res, span = execute(request: req, operation: "request")
+        res, span, tracer = execute(request: req, operation: "request")
         res = ResponseAdapter.adapt(res, type: :file)
-        finish_trace(operation: "request", res:, span:)
+        tracer.on_request_finish(operation: "request", res:, span:)
+        res
       end
     end
 
@@ -90,9 +92,10 @@ class LLM::Gemini
       file_id = file.respond_to?(:name) ? file.name : file.to_s
       query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/#{file_id}?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -109,9 +112,10 @@ class LLM::Gemini
       file_id = file.respond_to?(:name) ? file.name : file.to_s
       query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Delete.new("/v1beta/#{file_id}?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -132,8 +136,9 @@ class LLM::Gemini
       req["X-Goog-Upload-Header-Content-Length"] = file.bytesize
       req["X-Goog-Upload-Header-Content-Type"] = file.mime_type
       req.body = LLM.json.dump({file: {display_name: File.basename(file.path)}})
-      res, span = execute(request: req, operation: "request")
-      finish_trace(operation: "request", res: LLM::Response.new(res), span:)
+      res, span, tracer = execute(request: req, operation: "request")
+      trace_res = LLM::Response.new(res)
+      tracer.on_request_finish(operation: "request", res: trace_res, span:)
       res["x-goog-upload-url"]
     end
 
@@ -141,7 +146,7 @@ class LLM::Gemini
       @provider.instance_variable_get(:@key)
     end
 
-    [:headers, :execute, :set_body_stream, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -51,9 +51,10 @@ class LLM::Gemini
         instances: [{prompt:}]
       })
       req.body = body
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :image)
-      finish_trace(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     ##
@@ -90,7 +91,7 @@ class LLM::Gemini
       @provider.instance_variable_get(:@key)
     end
 
-    [:headers, :execute, :set_body_stream, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -42,9 +42,10 @@ class LLM::Gemini
     def all(**params)
       query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/models?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :models)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     private
@@ -53,7 +54,7 @@ class LLM::Gemini
       @provider.instance_variable_get(:@key)
     end
 
-    [:headers, :execute, :finish_trace].each do |m|
+    [:headers, :execute].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/gemini/request_adapter/completion.rb

@@ -48,7 +48,7 @@ module LLM::Gemini::RequestAdapter
     def adapt_object(object)
       case object.kind
       when :image_url
-        [{file_data: {mime_type: "image/*", file_uri: object.value.to_s}}]
+        [{file_data: {file_uri: object.value.to_s}}]
       when :local_file
         file = object.value
         [{inline_data: {mime_type: file.mime_type, data: file.to_b64}}]

data/lib/llm/providers/gemini.rb

@@ -49,9 +49,10 @@ module LLM
       path = ["/v1beta/models/#{model}", "embedContent?key=#{@key}"].join(":")
       req = Net::HTTP::Post.new(path, headers)
       req.body = LLM.json.dump({content: {parts: [{text: input}]}})
-      res, span = execute(request: req, operation: "embeddings", model:)
+      res, span, tracer = execute(request: req, operation: "embeddings", model:)
       res = ResponseAdapter.adapt(res, type: :embedding)
-      finish_trace(operation: "embeddings", model:, res:, span:)
+      tracer.on_request_finish(operation: "embeddings", model:, res:, span:)
+      res
     end
 
     ##
@@ -67,10 +68,11 @@ module LLM
     def complete(prompt, params = {})
       params, stream, tools, role, model = normalize_complete_params(params)
       req = build_complete_request(prompt, params, role, model, stream)
-      res, span = execute(request: req, stream: stream, operation: "chat", model:)
+      res, span, tracer = execute(request: req, stream: stream, operation: "chat", model:)
       res = ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
-      finish_trace(operation: "chat", model:, res:, span:)
+      tracer.on_request_finish(operation: "chat", model:, res:, span:)
+      res
     end
 
     ##
@@ -167,9 +169,11 @@ module LLM
     private
 
     def headers
-      (@headers || {}).merge(
-        "Content-Type" => "application/json"
-      )
+      lock do
+        (@headers || {}).merge(
+          "Content-Type" => "application/json"
+        )
+      end
     end
 
     def stream_parser

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

@@ -43,14 +43,15 @@ class LLM::Ollama
     def all(**params)
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/api/tags?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     private
 
-    [:headers, :execute, :finish_trace].each do |m|
+    [:headers, :execute].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/ollama.rb

@@ -43,9 +43,10 @@ module LLM
       params   = {model:}.merge!(params)
       req      = Net::HTTP::Post.new("/v1/embeddings", headers)
       req.body = LLM.json.dump({input:}.merge!(params))
-      res, span = execute(request: req, operation: "embeddings", model:)
+      res, span, tracer = execute(request: req, operation: "embeddings", model:)
       res = ResponseAdapter.adapt(res, type: :embedding)
-      finish_trace(operation: "embeddings", model:, res:, span:)
+      tracer.on_request_finish(operation: "embeddings", model:, res:, span:)
+      res
     end
 
     ##
@@ -61,10 +62,11 @@ module LLM
     def complete(prompt, params = {})
       params, stream, tools, role = normalize_complete_params(params)
       req = build_complete_request(prompt, params, role)
-      res, span = execute(request: req, stream: stream, operation: "chat", model: params[:model])
+      res, span, tracer = execute(request: req, stream: stream, operation: "chat", model: params[:model])
       res = ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
-      finish_trace(operation: "chat", model: params[:model], res:, span:)
+      tracer.on_request_finish(operation: "chat", model: params[:model], res:, span:)
+      res
     end
 
     ##
@@ -92,10 +94,12 @@ module LLM
     private
 
     def headers
-      (@headers || {}).merge(
-        "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{@key}"
-      )
+      lock do
+        (@headers || {}).merge(
+          "Content-Type" => "application/json",
+          "Authorization" => "Bearer #{@key}"
+        )
+      end
     end
 
     def stream_parser

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

@@ -35,9 +35,10 @@ class LLM::OpenAI
       req = Net::HTTP::Post.new("/v1/audio/speech", headers)
       req.body = LLM.json.dump({input:, voice:, model:, response_format:}.merge!(params))
       io = StringIO.new("".b)
-      res, span = execute(request: req, operation: "request") { _1.read_body { |chunk| io << chunk } }
+      res, span, tracer = execute(request: req, operation: "request") { _1.read_body { |chunk| io << chunk } }
       res = LLM::Response.new(res).tap { _1.define_singleton_method(:audio) { io } }
-      finish_trace(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     ##
@@ -57,9 +58,10 @@ class LLM::OpenAI
       req = Net::HTTP::Post.new("/v1/audio/transcriptions", headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     ##
@@ -80,14 +82,15 @@ class LLM::OpenAI
       req = Net::HTTP::Post.new("/v1/audio/translations", headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     private
 
-    [:headers, :execute, :set_body_stream, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -41,9 +41,10 @@ class LLM::OpenAI
     def all(**params)
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/files?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -62,9 +63,10 @@ class LLM::OpenAI
       req = Net::HTTP::Post.new("/v1/files", headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -82,9 +84,10 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/files/#{file_id}?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -104,9 +107,10 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Get.new("/v1/files/#{file_id}/content?#{query}", headers)
       io = StringIO.new("".b)
-      res, span = execute(request: req, operation: "request") { |res| res.read_body { |chunk| io << chunk } }
+      res, span, tracer = execute(request: req, operation: "request") { |res| res.read_body { |chunk| io << chunk } }
       res = LLM::Response.new(res).tap { _1.define_singleton_method(:file) { io } }
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -122,14 +126,15 @@ class LLM::OpenAI
     def delete(file:)
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Delete.new("/v1/files/#{file_id}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     private
 
-    [:headers, :execute, :set_body_stream, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -50,9 +50,10 @@ class LLM::OpenAI
     def create(prompt:, model: "dall-e-3", **params)
       req = Net::HTTP::Post.new("/v1/images/generations", headers)
       req.body = LLM.json.dump({prompt:, n: 1, model:}.merge!(params))
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :image)
-      finish_trace(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     ##
@@ -73,9 +74,10 @@ class LLM::OpenAI
       req = Net::HTTP::Post.new("/v1/images/variations", headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :image)
-      finish_trace(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     ##
@@ -97,14 +99,15 @@ class LLM::OpenAI
       req = Net::HTTP::Post.new("/v1/images/edits", headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :image)
-      finish_trace(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     private
 
-    [:headers, :execute, :set_body_stream, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -40,14 +40,15 @@ class LLM::OpenAI
     def all(**params)
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/models?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     private
 
-    [:headers, :execute, :set_body_stream, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -50,14 +50,15 @@ class LLM::OpenAI
       req = Net::HTTP::Post.new("/v1/moderations", headers)
       input = RequestAdapter::Moderation.new(input).adapt
       req.body = LLM.json.dump({input:, model:}.merge!(params))
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :moderations)
-      finish_trace(operation: "request", model:, res:, span:)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     private
 
-    [:headers, :execute, :finish_trace].each do |m|
+    [:headers, :execute].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -44,10 +44,11 @@ class LLM::OpenAI
       messages = [*(params.delete(:input) || []), LLM::Message.new(role, prompt)]
       body = LLM.json.dump({input: [adapt(messages, mode: :response)].flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
-      res, span = execute(request: req, stream:, stream_parser:, operation: "chat", model: params[:model])
+      res, span, tracer = execute(request: req, stream:, stream_parser:, operation: "chat", model: params[:model])
       res = ResponseAdapter.adapt(res, type: :responds)
         .extend(Module.new { define_method(:__tools__) { tools } })
-      finish_trace(operation: "chat", model: params[:model], res:, span:)
+      tracer.on_request_finish(operation: "chat", model: params[:model], res:, span:)
+      res
     end
 
     ##
@@ -60,9 +61,10 @@ class LLM::OpenAI
       response_id = response.respond_to?(:id) ? response.id : response
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/responses/#{response_id}?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :responds)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -74,14 +76,15 @@ class LLM::OpenAI
     def delete(response)
       response_id = response.respond_to?(:id) ? response.id : response
       req = Net::HTTP::Delete.new("/v1/responses/#{response_id}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     private
 
-    [:headers, :execute, :set_body_stream, :resolve_tools, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream, :resolve_tools].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
 

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

@@ -32,9 +32,10 @@ class LLM::OpenAI
     def all(**params)
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/vector_stores?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -48,9 +49,10 @@ class LLM::OpenAI
     def create(name:, file_ids: nil, **params)
       req = Net::HTTP::Post.new("/v1/vector_stores", headers)
       req.body = LLM.json.dump(params.merge({name:, file_ids:}).compact)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -71,9 +73,10 @@ class LLM::OpenAI
     def get(vector:)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -88,9 +91,10 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}", headers)
       req.body = LLM.json.dump(params.merge({name:}).compact)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -102,9 +106,10 @@ class LLM::OpenAI
     def delete(vector:)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       req = Net::HTTP::Delete.new("/v1/vector_stores/#{vector_id}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -119,9 +124,10 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/search", headers)
       req.body = LLM.json.dump(params.merge({query:}).compact)
-      res, span = execute(request: req, operation: "retrieval")
+      res, span, tracer = execute(request: req, operation: "retrieval")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      finish_trace(operation: "retrieval", res:, span:)
+      tracer.on_request_finish(operation: "retrieval", res:, span:)
+      res
     end
 
     ##
@@ -135,9 +141,10 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}/files?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -154,9 +161,10 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/files", headers)
       req.body = LLM.json.dump(params.merge({file_id:, attributes:}).compact)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
     alias_method :create_file, :add_file
 
@@ -184,9 +192,10 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/files/#{file_id}", headers)
       req.body = LLM.json.dump(params.merge({attributes:}).compact)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -201,9 +210,10 @@ class LLM::OpenAI
       file_id = file.respond_to?(:id) ? file.id : file
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}/files/#{file_id}?#{query}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -217,9 +227,10 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Delete.new("/v1/vector_stores/#{vector_id}/files/#{file_id}", headers)
-      res, span = execute(request: req, operation: "request")
+      res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
-      finish_trace(operation: "request", res:, span:)
+      tracer.on_request_finish(operation: "request", res:, span:)
+      res
     end
 
     ##
@@ -248,7 +259,7 @@ class LLM::OpenAI
 
     private
 
-    [:headers, :execute, :set_body_stream, :finish_trace].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/openai.rb

@@ -47,9 +47,10 @@ module LLM
     def embed(input, model: "text-embedding-3-small", **params)
       req = Net::HTTP::Post.new("/v1/embeddings", headers)
       req.body = LLM.json.dump({input:, model:}.merge!(params))
-      res, span = execute(request: req, operation: "embeddings", model:)
+      res, span, tracer = execute(request: req, operation: "embeddings", model:)
       res = ResponseAdapter.adapt(res, type: :embedding)
-      finish_trace(operation: "embeddings", model:, res:, span:)
+      tracer.on_request_finish(operation: "embeddings", model:, res:, span:)
+      res
     end
 
     ##
@@ -65,10 +66,11 @@ module LLM
     def complete(prompt, params = {})
       params, stream, tools, role = normalize_complete_params(params)
       req = build_complete_request(prompt, params, role)
-      res, span = execute(request: req, stream: stream, operation: "chat", model: params[:model])
+      res, span, tracer = execute(request: req, stream: stream, operation: "chat", model: params[:model])
       res = ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
-      finish_trace(operation: "chat", model: params[:model], res:, span:)
+      tracer.on_request_finish(operation: "chat", model: params[:model], res:, span:)
+      res
     end
 
     ##
@@ -181,10 +183,12 @@ module LLM
     end
 
     def headers
-      (@headers || {}).merge(
-        "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{@key}"
-      )
+      lock do
+        (@headers || {}).merge(
+          "Content-Type" => "application/json",
+          "Authorization" => "Bearer #{@key}"
+        )
+      end
     end
 
     def stream_parser

data/lib/llm/tracer/telemetry.rb

@@ -48,8 +48,6 @@ module LLM
     def initialize(provider, options = {})
       super
       @exporter = options.delete(:exporter)
-      @root_span = nil
-      @root_context = nil
       setup!
     end
 
@@ -69,22 +67,23 @@ module LLM
       )
       attrs = attributes.compact
       attrs["llm.trace_group_id"] = trace_group_id.to_s
-      @root_span = @tracer.start_span(
+      root_span = @tracer.start_span(
         name,
         kind: :server,
         attributes: attrs,
         with_parent: parent_ctx
       )
-      @root_context = ::OpenTelemetry::Trace.context_with_span(@root_span)
+      thread[thread_root_span_key] = root_span
+      thread[thread_root_context_key] = ::OpenTelemetry::Trace.context_with_span(root_span)
       self
     end
 
     ##
     # @return [self]
     def stop_trace
-      @root_span&.finish
-      @root_span = nil
-      @root_context = nil
+      thread[thread_root_span_key]&.finish
+      thread[thread_root_span_key] = nil
+      thread[thread_root_context_key] = nil
       self
     end
 
@@ -197,11 +196,30 @@ module LLM
     ##
     # @api private
     def create_span(name, kind: :client, attributes: {})
+      root_context = thread[thread_root_context_key]
       opts = {kind:, attributes:}
-      opts[:with_parent] = @root_context if @root_context
+      opts[:with_parent] = root_context if root_context
       @tracer.start_span(name, **opts)
     end
 
+    ##
+    # @api private
+    def thread_root_span_key
+      @thread_root_span_key ||= :"llm.telemetry.root_span.#{object_id}"
+    end
+
+    ##
+    # @api private
+    def thread_root_context_key
+      @thread_root_context_key ||= :"llm.telemetry.root_context.#{object_id}"
+    end
+
+    ##
+    # @api private
+    def thread
+      Thread.current
+    end
+
     ##
     # Converts a string trace_group_id to an OpenTelemetry SpanContext so all
     # spans created with this context share the same trace_id.

data/lib/llm/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.4.0
+  version: 4.5.0
 platform: ruby
 authors:
 - Antar Azri