llm.rb 5.2.1 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f9bdef0c733225e44dcf39d75e3397974122bfeb5e705a0797067242fd5c966
-  data.tar.gz: 567cc793e1e095e481abf5ef797a6fcb26a04faeed91855c234e531b78e3544a
+  metadata.gz: 0bd3ea0956fe1a9fa53bec3211dc4afe6f03c15fa67304ce5ba2c922d20abff1
+  data.tar.gz: 1aa03e4fc3eafbbbf9367deb8714f844ccd41299c666595d1d081a2db4d9d42e
 SHA512:
-  metadata.gz: 3d7e026b308228787d2f6ead8de197f847b644f7ba5bd0a1d679270a66e5c0e48c74a7d9494a86613bd061a42c2fd56ff270f73f8f3a627bc213dd7d57de788d
-  data.tar.gz: 8586a02d0345e7259f80b32e688a0ad531e28e3d15c8519781647ee1f77f23b6ecdaa9b28ed40efdea138c138511c7c4f88986ed7d646fb562e9faf7e2db687f
+  metadata.gz: 0e14b7cb29b5130b703c26369b6ecec106117e6a045bbcbeb79019c96814d9969e387c25992d2f3c96fd2ea43143ca4c48f00e91a00cc6cb3e20556145254d80
+  data.tar.gz: 3d34913dba2eab22f6f794196d59791cbadfeb71b9b4aaf588d46607112c4a0a0f741a9e8c9d308afb86d5d678a753b8a551ca66b08351581677845012c8e583

data/CHANGELOG.md

@@ -2,8 +2,56 @@
 
 ## 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`.
 
+This release deepens llm.rb's request-rewriting and tool-definition surface.
+It adds transformer lifecycle hooks to `LLM::Stream` so UIs can surface work
+like PII scrubbing before a request is sent, and it adds a more explicit
+OmniAI-style tool DSL form with `parameter` plus separate `required`
+declarations while keeping the older `param ... required: true` style working.
+
+### Change
+
+* **Add transformer stream lifecycle hooks** <br>
+  Add `on_transform` and `on_transform_finish` to
+  `LLM::Stream` so UIs can surface request rewriting work such as PII
+  scrubbing before a request is sent to the model.
+
+* **Add a separate `required` tool DSL form** <br>
+  Add `parameter` as an alias of `param` and support `required %i[...]`
+  as a separate declaration, inspired by OmniAI-style tools, while keeping
+  the existing `param ... required: true` form working too.
+
 ## v5.2.1
 
 Changes since `v5.2.0`.

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.2.1-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
@@ -26,7 +26,7 @@ execution model instead of a pile of adapters.
 
 Want to see some code? Jump to [the examples](#examples) section. <br>
 Want to see an agentic framework built on top of llm.rb? Check out [general-intelligence-systems/brute](https://github.com/general-intelligence-systems/brute). <br>
-Want a taste of what llm.rb can build? See [the screencast](#screencast).
+Want to see a self-hosted LLM environment built on llm.rb? Check out [Relay](https://github.com/llmrb/relay).
 
 ## Architecture
 
@@ -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"])
@@ -193,11 +194,22 @@ Transformers let llm.rb rewrite outgoing prompts and params before a request
 is sent to the provider. They also live on
 [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html), but
 they solve a different problem from guards: instead of blocking execution,
-they can normalize or scrub what gets sent.
+they can normalize or scrub what gets sent. When a stream is present, that
+lifecycle is also exposed through
+[`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html) with
+`on_transform` and `on_transform_finish`.
 
 That makes them a good fit for things like PII scrubbing, prompt
 normalization, or request-level param injection. A transformer just needs to
-implement `call(ctx, prompt, params)` and return `[prompt, params]`.
+implement `call(ctx, prompt, params)` and return `[prompt, params]`. That
+means a transformer can scrub plain text prompts, but it can also scrub
+[`LLM::Function::Return`](https://0x1eef.github.io/x/llm.rb/LLM/Function/Return.html)
+values. In other words, you can intercept a tool call's return value and
+modify it before sending it back to the LLM.
+
+That is also a useful UI hook. A stream can surface messages like
+`Anonymizing your data...` before a scrubber runs and `Data anonymized.`
+after it finishes.
 
 ```ruby
 class ScrubPII
@@ -212,22 +224,45 @@ class ScrubPII
   def scrub(prompt)
     case prompt
     when String then prompt.gsub(EMAIL, "[REDACTED_EMAIL]")
+    when Array then prompt.map { scrub(_1) }
+    when LLM::Function::Return then on_tool_return(prompt)
     else prompt
     end
   end
+
+  def on_tool_return(result)
+    value = case result.name
+    when "lookup-customer" then scrub_value(result.value)
+    else result.value
+    end
+    LLM::Function::Return.new(result.id, result.name, value)
+  end
+
+  def scrub_value(value)
+    case value
+    when String then value.gsub(EMAIL, "[REDACTED_EMAIL]")
+    when Array then value.map { scrub_value(_1) }
+    when Hash then value.transform_values { scrub_value(_1) }
+    else value
+    end
+  end
 end
 
 ctx = LLM::Context.new(llm)
 ctx.transformer = ScrubPII.new
 ```
 
+When a stream is present, that transformer lifecycle is also exposed through
+`on_transform` and `on_transform_finish` on
+[`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html).
+
 #### LLM::Stream
 
 `LLM::Stream` is not just for printing tokens. It supports `on_content`,
-`on_reasoning_content`, `on_tool_call`, `on_tool_return`, `on_compaction`,
-and `on_compaction_finish`, which means visible output, reasoning output, tool
-execution, and context compaction can all be driven through the same
-execution path.
+`on_reasoning_content`, `on_tool_call`, `on_tool_return`, `on_transform`,
+`on_transform_finish`, `on_compaction`, and `on_compaction_finish`, which
+means visible output, reasoning output, request rewriting, tool execution,
+and context compaction can all be driven through the same execution path.
 
 ```ruby
 class Stream < LLM::Stream
@@ -477,6 +512,29 @@ loop do
 end
 ```
 
+#### Multimodal: Local Files
+
+In llm.rb, a prompt can be a string, an [`LLM::Prompt`](https://0x1eef.github.io/x/llm.rb/LLM/Prompt.html), or an array.
+When you use an array, each element can be plain text or a tagged object such as
+[`ctx.image_url(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#image_url-instance_method),
+[`ctx.local_file(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#local_file-instance_method),
+or [`ctx.remote_file(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#remote_file-instance_method).
+Those tagged objects carry the metadata the provider adapter needs to turn one
+Ruby prompt into the provider-specific multimodal request schema.
+
+`ctx.local_file(path)` tags a local path as a `:local_file` object around
+`LLM.File(path)`. If the model understands that file type, you can include it
+directly in the prompt array instead of uploading it first through a provider
+Files API:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+ctx.talk ["Summarize this document.", ctx.local_file("README.md")]
+```
+
 #### Agent
 
 This example uses [`LLM::Agent`](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html) directly and lets the agent manage tool execution. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
@@ -509,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"])
@@ -738,13 +797,6 @@ mcp.run do
 end
 ```
 
-## Screencast
-
-This screencast was built on an older version of llm.rb, but it still shows
-how capable the runtime can be in a real application:
-
-[![Watch the llm.rb screencast](https://img.youtube.com/vi/Jb7LNUYlCf4/maxresdefault.jpg)](https://www.youtube.com/watch?v=x1K4wMeO_QA)
-
 ## Resources
 
 - [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) and

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/context.rb

@@ -489,7 +489,11 @@ module LLM
 
     def transform(prompt, params)
       return [prompt, params] unless transformer
+      stream = params[:stream]
+      stream.on_transform(self, transformer) if LLM::Stream === stream
       transformer.call(self, prompt, params)
+    ensure
+      stream.on_transform_finish(self, transformer) if LLM::Stream === stream
     end
 
     def guarded_return_for(function, warning)

data/lib/llm/function.rb

@@ -42,6 +42,33 @@ class LLM::Function
   extend LLM::Function::Registry
   prepend LLM::Function::Tracing
 
+  ##
+  # {LLM::Function::Return LLM::Function::Return} represents the result of a
+  # tool call.
+  #
+  # In llm.rb, tool execution is not complete until the requested function is
+  # answered with a return object and that return is sent back through the
+  # context. This is the object that closes that loop.
+  #
+  # The return carries:
+  # - the tool call ID
+  # - the tool name
+  # - the tool's return value
+  #
+  # That value is usually a `Hash`, but it can be any JSON-like structure your
+  # tool returns. `LLM::Function#call` produces one automatically, and
+  # `LLM::Function#cancel` produces one that represents a cancelled tool call.
+  #
+  # You can also construct one directly when you need to intercept, scrub, or
+  # synthesize a tool return before sending it back to the model.
+  #
+  # @example Returning a normal tool result
+  #   ret = LLM::Function::Return.new("call_1", "weather", {forecast: "sunny"})
+  #   ctx.talk(ret)
+  #
+  # @example Returning a tool result after rewriting its payload
+  #   value = ret.value.merge(email: "[REDACTED_EMAIL]")
+  #   ctx.talk(LLM::Function::Return.new(ret.id, ret.name, value))
   Return = Struct.new(:id, :name, :value) do
     ##
     # Returns true when the return value represents an error.
@@ -191,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)
@@ -301,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/stream.rb

@@ -19,7 +19,7 @@ module LLM
   # The most common callback is {#on_content}, which also maps to {#<<}.
   # Providers may also call {#on_reasoning_content} and {#on_tool_call} when
   # that data is available. Runtime features such as context compaction may
-  # also emit lifecycle callbacks like {#on_compaction}.
+  # also emit lifecycle callbacks like {#on_transform} or {#on_compaction}.
   class Stream
     require_relative "stream/queue"
 
@@ -112,6 +112,24 @@ module LLM
       nil
     end
 
+    ##
+    # Called before a context transformer rewrites a prompt.
+    # @param [LLM::Context] ctx
+    # @param [#call] transformer
+    # @return [nil]
+    def on_transform(ctx, transformer)
+      nil
+    end
+
+    ##
+    # Called after a context transformer finishes rewriting a prompt.
+    # @param [LLM::Context] ctx
+    # @param [#call] transformer
+    # @return [nil]
+    def on_transform_finish(ctx, transformer)
+      nil
+    end
+
     ##
     # Called before a context compaction starts.
     # @param [LLM::Context] ctx

data/lib/llm/tool/param.rb

@@ -11,7 +11,8 @@ class LLM::Tool
   #   class Greeter < LLM::Tool
   #     name "greeter"
   #     description "Greets the user"
-  #     param :name, String, "The user's name", required: true
+  #     parameter :name, String, "The user's name"
+  #     required %i[name]
   #
   #     def call(name:)
   #       puts "Hello, #{name}!"
@@ -41,6 +42,19 @@ class LLM::Tool
         end
       end
     end
+    alias_method :parameter, :param
+
+    ##
+    # Mark existing parameters as required.
+    # @param names [Array<Symbol,String>]
+    # @return [LLM::Schema::Object]
+    def required(names)
+      lock do
+        function.params.tap do |schema|
+          [*names].each { Utils.fetch(schema.properties, _1).required }
+        end
+      end
+    end
 
     ##
     # @api private
@@ -68,6 +82,10 @@ class LLM::Tool
         leaf.enum(*enum) if enum
         leaf
       end
+
+      def fetch(properties, name)
+        properties[name] || properties.fetch(name.to_s)
+      end
     end
   end
 end

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.2.1"
+  VERSION = "5.4.0"
 end

metadata

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