llm.rb 5.3.0 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39e1632fb63f83a65c5a146ea2a2f4178d0d99d26d2a347f36d360c09ea9845d
-  data.tar.gz: 04b2236d5cac243cc496b686d8d8a5097676e7bcd6973bacfa8d1f7e8d48e270
+  metadata.gz: 0bd3ea0956fe1a9fa53bec3211dc4afe6f03c15fa67304ce5ba2c922d20abff1
+  data.tar.gz: 1aa03e4fc3eafbbbf9367deb8714f844ccd41299c666595d1d081a2db4d9d42e
 SHA512:
-  metadata.gz: 1b4a68bd3b3e109a00f996f520296405ad6066b4f17c1e59da4077c2023c5fe0c95e770b9bd563a531748a16d79355f8db5fb2dcd66ac42673698ddcbea07704
-  data.tar.gz: 12713c07834164f3d13d01613126488cc19e937b8f127fcdbf839d8c75f2f6b77c6207e7e3e6f515d996e35aedb6d6e7333ba563a3f4578f4c33f454d41c6088
+  metadata.gz: 0e14b7cb29b5130b703c26369b6ecec106117e6a045bbcbeb79019c96814d9969e387c25992d2f3c96fd2ea43143ca4c48f00e91a00cc6cb3e20556145254d80
+  data.tar.gz: 3d34913dba2eab22f6f794196d59791cbadfeb71b9b4aaf588d46607112c4a0a0f741a9e8c9d308afb86d5d678a753b8a551ca66b08351581677845012c8e583

data/CHANGELOG.md

@@ -2,8 +2,34 @@
 
 ## Unreleased
 
+Changes since `v5.4.0`.
+
+## v5.4.0
+
 Changes since `v5.3.0`.
 
+This release expands tracer support around agentic execution. It lets
+`LLM::Agent` define scoped tracers through the agent DSL and fixes concurrent
+tool execution so those scoped tracers stay attached when work crosses
+thread, task, fiber, and skill boundaries.
+
+### Change
+
+* **Add agent-scoped tracers** <br>
+  Let `LLM::Agent` classes define `tracer ...` or `tracer { ... }` so an
+  agent can carry its own tracer without replacing the provider's default
+  tracer. The resolved tracer is scoped to that agent's turns, tool loops,
+  and pending tool access. Available through the `acts_as_agent` and Sequel
+  agent plugin `tracer` DSL too.
+
+### Fix
+
+* **Preserve scoped tracers across concurrent tool work** <br>
+  Keep agent- and request-scoped tracers attached when tool execution
+  crosses `:thread`, `:task`, or `:fiber` boundaries, including skill
+  execution, so spawned work does not fall back to the provider default
+  tracer.
+
 ## v5.3.0
 
 Changes since `v5.2.1`.

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-5.3.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-5.4.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -87,6 +87,7 @@ Review the release state, summarize what changed, and prepare the release.
 class Agent < LLM::Agent
   model "gpt-5.4-mini"
   skills "./skills/release"
+  tracer { LLM::Tracer::Logger.new(llm, path: "logs/release-agent.log") }
 end
 
 llm = LLM.openai(key: ENV["KEY"])
@@ -566,6 +567,7 @@ class Agent < LLM::Agent
   model "gpt-5.4-mini"
   instructions "You are a concise release assistant."
   skills "./skills/release", "./skills/review"
+  tracer { LLM::Tracer::Logger.new(llm, path: "logs/release-agent.log") }
 end
 
 llm = LLM.openai(key: ENV["KEY"])

data/lib/llm/active_record/acts_as_agent.rb

@@ -41,6 +41,11 @@ module LLM::ActiveRecord
         agent.concurrency(concurrency)
       end
 
+      def tracer(tracer = nil, &block)
+        return agent.tracer if tracer.nil? && !block
+        agent.tracer(tracer, &block)
+      end
+
       def agent
         @agent ||= Class.new(LLM::Agent)
       end

data/lib/llm/agent.rb

@@ -115,6 +115,26 @@ module LLM
       @concurrency = concurrency
     end
 
+    ##
+    # Set or get the default tracer.
+    #
+    # When a block is provided, it is stored and evaluated lazily against the
+    # agent instance during initialization so it can build a tracer from the
+    # resolved provider.
+    #
+    # @example
+    #   class Agent < LLM::Agent
+    #     tracer { LLM::Tracer::Logger.new(llm, io: $stdout) }
+    #   end
+    #
+    # @param [LLM::Tracer, Proc, nil] tracer
+    # @yieldreturn [LLM::Tracer, nil]
+    # @return [LLM::Tracer, Proc, nil]
+    def self.tracer(tracer = nil, &block)
+      return @tracer if tracer.nil? && !block
+      @tracer = block || tracer
+    end
+
     ##
     # @param [LLM::Provider] provider
     #  A provider
@@ -131,6 +151,7 @@ module LLM
       defaults = {model: self.class.model, tools: self.class.tools, skills: self.class.skills, schema: self.class.schema}.compact
       @concurrency = params.delete(:concurrency) || self.class.concurrency
       @llm = llm
+      @tracer = resolve_option(self.class.tracer) unless self.class.tracer.nil?
       @ctx = LLM::Context.new(llm, defaults.merge({guard: true}).merge(params))
     end
 
@@ -179,7 +200,7 @@ module LLM
     ##
     # @return [Array<LLM::Function>]
     def functions
-      @ctx.functions
+      @tracer ? @llm.with_tracer(@tracer) { @ctx.functions } : @ctx.functions
     end
 
     ##
@@ -193,14 +214,14 @@ module LLM
     # @see LLM::Context#call
     # @return [Object]
     def call(...)
-      @ctx.call(...)
+      @tracer ? @llm.with_tracer(@tracer) { @ctx.call(...) } : @ctx.call(...)
     end
 
     ##
     # @see LLM::Context#wait
     # @return [Array<LLM::Function::Return>]
     def wait(...)
-      @ctx.wait(...)
+      @tracer ? @llm.with_tracer(@tracer) { @ctx.wait(...) } : @ctx.wait(...)
     end
 
     ##
@@ -257,7 +278,7 @@ module LLM
     # @return [LLM::Tracer]
     #  Returns an LLM tracer
     def tracer
-      @ctx.tracer
+      @tracer || @ctx.tracer
     end
 
     ##
@@ -371,14 +392,21 @@ module LLM
     end
 
     def run_loop(method, prompt, params)
-      max = Integer(params.delete(:tool_attempts) || 25)
-      res = @ctx.public_send(method, apply_instructions(prompt), params)
-      max.times do
-        break if @ctx.functions.empty?
-        res = @ctx.public_send(method, call_functions, params)
+      loop = proc do
+        max = Integer(params.delete(:tool_attempts) || 25)
+        res = @ctx.public_send(method, apply_instructions(prompt), params)
+        max.times do
+          break if @ctx.functions.empty?
+          res = @ctx.public_send(method, call_functions, params)
+        end
+        raise LLM::ToolLoopError, "pending tool calls remain" unless @ctx.functions.empty?
+        res
       end
-      raise LLM::ToolLoopError, "pending tool calls remain" unless @ctx.functions.empty?
-      res
+      @tracer ? @llm.with_tracer(@tracer, &loop) : loop.call
+    end
+
+    def resolve_option(option)
+      Proc === option ? instance_exec(&option) : option
     end
   end
 end

data/lib/llm/function.rb

@@ -218,12 +218,12 @@ class LLM::Function
     task = case strategy
     when :task
       require "async" unless defined?(::Async)
-      Async { call }
+      Async { call! }
     when :thread
-      Thread.new { call }
+      Thread.new { call! }
     when :fiber
       Fiber.new do
-        call
+        call!
       ensure
         Fiber.yield
       end.tap(&:resume)
@@ -328,9 +328,16 @@ class LLM::Function
   #   Returns a Return object with either the function result or error information.
   def call_function
     runner = ((Class === @runner) ? @runner.new : @runner)
+    runner.tracer = @tracer if runner.respond_to?(:tracer=)
     kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments
     Return.new(id, name, runner.call(**kwargs))
   rescue => ex
     Return.new(id, name,  {error: true, type: ex.class.name, message: ex.message})
   end
+
+  def call!
+    llm = @tracer&.llm
+    return call unless llm.respond_to?(:with_tracer)
+    llm.with_tracer(@tracer) { call }
+  end
 end

data/lib/llm/sequel/agent.rb

@@ -62,6 +62,11 @@ module LLM::Sequel
         agent.concurrency(concurrency)
       end
 
+      def tracer(tracer = nil, &block)
+        return agent.tracer if tracer.nil? && !block
+        agent.tracer(tracer, &block)
+      end
+
       def agent
         @agent ||= Class.new(LLM::Agent)
       end

data/lib/llm/skill.rb

@@ -74,11 +74,12 @@ module LLM
     # @param [LLM::Context] ctx
     # @return [Hash]
     def call(ctx)
-      instructions, tools = self.instructions, self.tools
+      instructions, tools, tracer = self.instructions, self.tools, ctx.llm.tracer
       params = ctx.params.merge(mode: ctx.mode).reject { [:tools, :schema].include?(_1) }
       agent = Class.new(LLM::Agent) do
         instructions(instructions)
         tools(*tools)
+        tracer(tracer)
       end.new(ctx.llm, params)
       agent.messages.concat(messages_for(ctx))
       res = agent.talk("Solve the user's query.")
@@ -95,6 +96,7 @@ module LLM
       Class.new(LLM::Tool) do
         name skill.name
         description skill.description
+        attr_accessor :tracer
 
         define_method(:call) do
           skill.call(ctx)

data/lib/llm/tracer/logger.rb

@@ -114,7 +114,7 @@ module LLM
     # @param [LLM::Response] res
     # @api private
     def finish_attributes(operation, res)
-      case @provider.class.to_s
+      case @llm.class.to_s
       when "LLM::OpenAI" then openai_attributes(operation, res)
       else {}
       end

data/lib/llm/tracer/telemetry.rb

@@ -233,7 +233,7 @@ module LLM
     # @param [LLM::Response] res
     # @api private
     def finish_attributes(operation, res)
-      case @provider.class.to_s
+      case @llm.class.to_s
       when "LLM::OpenAI" then openai_attributes(operation, res)
       else {}
       end

data/lib/llm/tracer.rb

@@ -14,13 +14,17 @@ module LLM
     require_relative "tracer/langsmith"
     require_relative "tracer/null"
 
+    ##
+    # @return [LLM::Provider]
+    attr_reader :llm
+
     ##
     # @param [LLM::Provider] provider
     #  A provider
     # @param [Hash] options
     #  A hash of options
     def initialize(provider, options = {})
-      @provider = provider
+      @llm = provider
       @options = {}
     end
 
@@ -124,7 +128,7 @@ module LLM
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} @provider=#{@provider.class} @tracer=#{@tracer.inspect}>"
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} @provider=#{@llm.class} @tracer=#{@tracer.inspect}>"
     end
 
     ##
@@ -245,19 +249,19 @@ module LLM
     ##
     # @return [String]
     def provider_name
-      @provider.class.name.split("::").last.downcase
+      @llm.class.name.split("::").last.downcase
     end
 
     ##
     # @return [String]
     def provider_host
-      @provider.instance_variable_get(:@host)
+      @llm.instance_variable_get(:@host)
     end
 
     ##
     # @return [String]
     def provider_port
-      @provider.instance_variable_get(:@port)
+      @llm.instance_variable_get(:@port)
     end
   end
 end

data/lib/llm/version.rb

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

metadata

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