llm.rb 4.17.0 → 4.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d834b30dd18d6bf83ccd2334bbedba0ee5a9f75d0d6d0616aefb7baa6be68ad0
-  data.tar.gz: d8c8a1e43cc89d888ab1ea008baddce7e1427fc3598daf68ca04fd0eff1351b0
+  metadata.gz: 18c28f7b5ec05ad6f9629a6a328be4dd377a6efb43a13c2ac99dd0abf015b1f8
+  data.tar.gz: a0c03de362af927d090a6bc09b2170ddb7eb5766f26b1f8f657a37bd10d0162e
 SHA512:
-  metadata.gz: f9fbe6f7080294c0500153dbfeb3c721407553289a2f34cd37e63552a84171bdc1bc130fb325aaf164f099c5fd6bfb417f550eea60dc126c20f940a7737e393a
-  data.tar.gz: 67cef120d84c98ea695caab059d2bb008ca1cbdeb15a1b2f13c819166b1edd7a523c7213acabed5b35c44e7123ae85481c0eaff815d6254088c858e5a0516ae3
+  metadata.gz: c8255c9435bec0a7a06fb427f3a1ade4e0b5ce47f111d33f4cbf1218fce1f89f1438c71980b52c3de7542563690f08bcf54417cb7d427720248a22f8b30a12fb
+  data.tar.gz: 54aebea9a5f8ac687163d3df3c2c3d31091f8f8d6d96b5ad242199daa8fdfb8e5e17e2b626f7a682158ba9251202362fc9fddaed6c08e6eb8399c8b0509659d8

data/CHANGELOG.md

@@ -2,24 +2,95 @@
 
 ## Unreleased
 
+Changes since `v4.19.0`.
+
+## v4.19.0
+
+Changes since `v4.18.0`.
+
+This release tightens the ActiveRecord and ORM integration layer. It adds
+inline agent DSL blocks to `acts_as_agent` so agent defaults can be defined
+where the wrapper is declared, and it exposes the resolved provider through
+public `llm` methods on the ActiveRecord and Sequel wrappers.
+
+### Change
+
+* **Make ORM provider access public through `llm`** <br>
+  Expose the resolved provider on the Sequel plugin and the ActiveRecord
+  `acts_as_llm` / `acts_as_agent` wrappers through a public `llm` method.
+
+* **Allow inline agent DSL blocks in `acts_as_agent`** <br>
+  Let ActiveRecord models configure `model`, `tools`, `schema`,
+  `instructions`, and `concurrency` directly inside the `acts_as_agent`
+  declaration block.
+
+## v4.18.0
+
 Changes since `v4.17.0`.
 
+This release improves tracing and tool execution behavior across llm.rb.
+It makes provider tracers default to the provider instance, adds
+`LLM::Provider#with_tracer` for scoped overrides, restores tool tracing for
+concurrent and streamed tool execution, extends streamed tracing to MCP tools,
+and adds symbol-based ORM option hooks alongside experimental ractor tool
+concurrency.
+
+### Change
+
+* **Make provider tracers default to the provider instance** <br>
+  Change `llm.tracer = ...` so it sets a provider default tracer instead of
+  relying on scoped fiber-local state alone. This makes tracer configuration
+  behave more predictably across normal tasks, threads, and fibers that share
+  the same provider instance.
+
+* **Add `LLM::Provider#with_tracer` for scoped overrides** <br>
+  Add `with_tracer` as the opt-in escape hatch for request- or turn-scoped
+  tracer overrides. Use it when you want temporary tracing on the current
+  fiber without replacing the provider's default tracer.
+
+* **Trace concurrent tool calls outside ractors** <br>
+  Make tool tracing fire correctly when functions run through `:thread`,
+  `:task`, or `:fiber` concurrency. Experimental `:ractor` execution still
+  does not emit tool tracer events.
+
+* **Trace streamed tool calls, including MCP tools** <br>
+  Bind stream metadata through `LLM::Stream#extra` so streamed tool calls
+  inherit tracer and model context before they are handed to `on_tool_call`.
+  This restores tool tracing for streamed MCP and local tool execution.
+
+* **Support symbol-based ORM option hooks** <br>
+  Let `provider:`, `context:`, and `tracer:` on the Sequel plugin and
+  the ActiveRecord `acts_as_llm` / `acts_as_agent` wrappers resolve through
+  model method names as well as procs.
+
+* **Add experimental ractor tool concurrency** <br>
+  Add `:ractor` support to `LLM::Function#spawn`, `LLM::Function::Array#wait`,
+  `LLM::Stream#wait`, and `LLM::Agent.concurrency` so class-based tools with
+  ractor-safe arguments and return values can run in Ruby ractors and report
+  their results back into the normal LLM tool-return path. MCP tools are not
+  supported by the current `:ractor` mode, but mixed workloads can still
+  branch on `tool.mcp?` and choose a supported strategy per tool. `:ractor`
+  is especially useful for CPU-bound tools, while `:task`, `:fiber`, or
+  `:thread` may be a better fit for I/O-bound work.
+
 ## v4.17.0
 
 Changes since `v4.16.1`.
 
 This release expands agent support across llm.rb. It brings `LLM::Agent`
-closer to `LLM::Context`, adds configurable automatic tool concurrency,
+closer to `LLM::Context`, adds configurable automatic tool concurrency
+including experimental ractor support for class-based tools,
 extends persisted ORM wrappers with more of the context runtime surface and
-fiber-local tracer hooks, and introduces built-in ActiveRecord agent
-persistence through `acts_as_agent`.
+tracer hooks, and introduces built-in ActiveRecord agent persistence through
+`acts_as_agent`.
 
 ### Change
 
 * **Add configurable tool concurrency to `LLM::Agent`** <br>
   Add the class-level `concurrency` DSL to `LLM::Agent` so automatic
-  tool loops can run with `:call`, `:thread`, `:task`, or `:fiber`
-  instead of always executing sequentially.
+  tool loops can run with `:call`, `:thread`, `:task`, `:fiber`, or
+  experimental `:ractor` support for class-based tools instead of
+  always executing sequentially.
 
 * **Bring `LLM::Agent` closer to `LLM::Context`** <br>
   Expand `LLM::Agent` so it exposes more of the same runtime surface as
@@ -35,8 +106,8 @@ persistence through `acts_as_agent`.
 
 * **Add ORM tracer hooks for persisted contexts** <br>
   Add `tracer:` to both the Sequel plugin and `acts_as_llm` so models
-  can resolve and assign fiber-local tracers onto the provider used by
-  their persisted `LLM::Context`.
+  can resolve and assign tracers onto the provider used by their persisted
+  `LLM::Context`.
 
 * **Bring persisted ORM wrappers closer to `LLM::Context`** <br>
   Expand both the Sequel plugin and `acts_as_llm` so record-backed

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.17.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.19.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -23,6 +23,8 @@ pieces only when needed, includes built-in ActiveRecord support through
 long-lived, tool-capable, stateful AI workflows instead of just
 request/response helpers.
 
+Want to see some code? Jump to [the examples](#examples) section.
+
 ## Architecture
 
 <p align="center">
@@ -66,7 +68,10 @@ same context object.
 - **Agents auto-manage tool execution** <br>
   Use `LLM::Agent` when you want the same stateful runtime surface as
   `LLM::Context`, but with tool loops executed automatically according to a
-  configured concurrency mode such as `:call`, `:thread`, `:task`, or `:fiber`.
+  configured concurrency mode such as `:call`, `:thread`, `:task`, `:fiber`,
+  or experimental `:ractor` support for class-based tools. MCP tools are not
+  supported by the current `:ractor` mode, but mixed tool sets can still
+  route MCP tools and local tools through different strategies at runtime.
 - **Tool calls have an explicit lifecycle** <br>
   A tool call can be executed, cancelled through
   [`LLM::Function#cancel`](https://0x1eef.github.io/x/llm.rb/LLM/Function.html#cancel-instance_method),
@@ -78,7 +83,12 @@ same context object.
   [`LLM::Context#cancel!`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#cancel-21-instance_method)
   is inspired by Go's context cancellation model.
 - **Concurrency is a first-class feature** <br>
-  Use threads, fibers, or async tasks without rewriting your tool layer.
+  Use threads, fibers, async tasks, or experimental ractors without
+  rewriting your tool layer. The current `:ractor` mode is for class-based
+  tools and does not support MCP tools, but mixed workloads can branch on
+  `tool.mcp?` and choose a supported strategy per tool. `:ractor` is
+  especially useful for CPU-bound tools, while `:task`, `:fiber`, or
+  `:thread` may be a better fit for I/O-bound work.
 - **Advanced workloads are built in, not bolted on** <br>
   Streaming, concurrent tool execution, persistence, tracing, and MCP support
   all fit the same runtime model.
@@ -199,6 +209,7 @@ The `plugin :llm` integration wraps [`LLM::Context`](https://0x1eef.github.io/x/
 
 ```ruby
 require "llm"
+require "net/http/persistent"
 require "sequel"
 require "sequel/plugins/llm"
 
@@ -218,6 +229,7 @@ provides full control over tool execution. <br> See the [deepdive](https://0x1ee
 
 ```ruby
 require "llm"
+require "net/http/persistent"
 require "active_record"
 require "llm/active_record"
 
@@ -237,15 +249,23 @@ manages tool execution for you. <br> See the [deepdive](https://0x1eef.github.io
 
 ```ruby
 require "llm"
+require "net/http/persistent"
 require "active_record"
 require "llm/active_record"
 
 class Ticket < ApplicationRecord
-  acts_as_agent provider: -> { { key: ENV["#{provider.upcase}_SECRET"], persistent: true } }
-  model "gpt-5.4-mini"
-  instructions "You are a concise support assistant."
-  tools SearchDocs, Escalate
-  concurrency :thread
+  acts_as_agent provider: :set_provider do
+    model "gpt-5.4-mini"
+    instructions "You are a concise support assistant."
+    tools SearchDocs, Escalate
+    concurrency :thread
+  end
+
+  private
+
+  def set_provider
+    { key: ENV["#{provider.upcase}_SECRET"], persistent: true }
+  end
 end
 
 ticket = Ticket.create!(provider: "openai", model: "gpt-5.4-mini")

data/lib/llm/active_record/acts_as_agent.rb

@@ -68,21 +68,24 @@ module LLM::ActiveRecord
     #   Storage format for the serialized agent state. Use `:string` for text
     #   columns, or `:json` / `:jsonb` for structured JSON columns with
     #   ActiveRecord JSON typecasting enabled.
-    # @option options [Proc, LLM::Tracer, nil] :tracer
-    #   Optional tracer or proc that resolves to one and is assigned through
-    #   `llm.tracer = ...` on the resolved provider.
+    # @option options [Proc, Symbol, LLM::Tracer, nil] :tracer
+    #   Optional tracer, method name, or proc that resolves to one and is
+    #   assigned through `llm.tracer = ...` on the resolved provider.
+    # @yield
+    #   Evaluated in the model class after the wrapper is installed, so agent
+    #   DSL methods such as `model`, `tools`, `schema`, `instructions`, and
+    #   `concurrency` can be configured inline.
     # @return [void]
-    def acts_as_agent(options = EMPTY_HASH)
+    def acts_as_agent(options = EMPTY_HASH, &block)
       options = DEFAULTS.merge(options)
       usage_columns = DEFAULT_USAGE_COLUMNS.merge(options[:usage_columns] || EMPTY_HASH)
       class_attribute :llm_agent_options, instance_accessor: false, default: DEFAULTS unless respond_to?(:llm_agent_options)
       self.llm_agent_options = options.merge(usage_columns: usage_columns.freeze).freeze
       extend Hooks
+      class_exec(&block) if block
     end
 
     module InstanceMethods
-      private
-
       ##
       # Returns the resolved provider instance for this record.
       # @return [LLM::Provider]
@@ -90,11 +93,14 @@ module LLM::ActiveRecord
         options = self.class.llm_agent_options
         provider = self[columns[:provider_column]]
         kwargs = resolve_options(options[:provider])
-        @llm ||= LLM.method(provider).call(**kwargs)
+        return @llm if @llm
+        @llm = LLM.method(provider).call(**kwargs)
         @llm.tracer = resolve_option(options[:tracer]) if options[:tracer]
         @llm
       end
 
+      private
+
       ##
       # @return [LLM::Agent]
       def ctx
@@ -134,6 +140,7 @@ module LLM::ActiveRecord
       def resolve_option(option)
         case option
         when Proc then instance_exec(&option)
+        when Symbol then send(option)
         when Hash then option.dup
         else option
         end

data/lib/llm/active_record/acts_as_llm.rb

@@ -13,8 +13,8 @@ module LLM::ActiveRecord
   # default) or as a structured object (`format: :json` / `:jsonb`) for
   # databases such as PostgreSQL that can persist JSON natively.
   # `:json` and `:jsonb` expect a real JSON column type with ActiveRecord
-  # handling JSON typecasting for the model. A `tracer:` proc can also be
-  # configured to assign a fiber-local tracer onto the resolved provider.
+  # handling JSON typecasting for the model. `provider:`, `context:`, and
+  # `tracer:` can also be configured as symbols that are called on the model.
   module ActsAsLLM
     EMPTY_HASH = {}.freeze
     DEFAULT_USAGE_COLUMNS = {
@@ -54,9 +54,9 @@ module LLM::ActiveRecord
     #   Storage format for the serialized context. Use `:string` for text
     #   columns, or `:json` / `:jsonb` for structured JSON columns with
     #   ActiveRecord JSON typecasting enabled.
-    # @option options [Proc, LLM::Tracer, nil] :tracer
-    #   Optional tracer or proc that resolves to one and is assigned through
-    #   `llm.tracer = ...` on the resolved provider.
+    # @option options [Proc, Symbol, LLM::Tracer, nil] :tracer
+    #   Optional tracer, method name, or proc that resolves to one and is
+    #   assigned through `llm.tracer = ...` on the resolved provider.
     # @return [void]
     def acts_as_llm(options = EMPTY_HASH)
       options = DEFAULTS.merge(options)
@@ -206,8 +206,6 @@ module LLM::ActiveRecord
         ctx.tracer
       end
 
-      private
-
       ##
       # Returns the resolved provider instance for this record.
       # @return [LLM::Provider]
@@ -215,11 +213,14 @@ module LLM::ActiveRecord
         options = self.class.llm_plugin_options
         provider = self[columns[:provider_column]]
         kwargs = resolve_options(options[:provider])
-        @llm ||= LLM.method(provider).call(**kwargs)
+        return @llm if @llm
+        @llm = LLM.method(provider).call(**kwargs)
         @llm.tracer = resolve_option(options[:tracer]) if options[:tracer]
         @llm
       end
 
+      private
+
       ##
       # @return [LLM::Context]
       def ctx
@@ -259,6 +260,7 @@ module LLM::ActiveRecord
       def resolve_option(option)
         case option
         when Proc then instance_exec(&option)
+        when Symbol then send(option)
         when Hash then option.dup
         else option
         end

data/lib/llm/agent.rb

@@ -17,7 +17,7 @@ module LLM
   # * Instructions are injected only on the first request.
   # * An agent automatically executes tool loops (unlike {LLM::Context LLM::Context}).
   # * Tool loop execution can be configured with `concurrency :call`,
-  #   `:thread`, `:task`, or `:fiber`.
+  #   `:thread`, `:task`, `:fiber`, or `:ractor`.
   #
   # @example
   #   class SystemAdmin < LLM::Agent
@@ -89,6 +89,8 @@ module LLM
     #  - `:thread`: concurrent threads
     #  - `:task`: concurrent async tasks
     #  - `:fiber`: concurrent raw fibers
+    #  - `:ractor`: concurrent Ruby ractors for class-based tools; MCP tools are not supported,
+    #    and this mode is especially useful for CPU-bound tool work
     # @return [Symbol, nil]
     def self.concurrency(concurrency = nil)
       return @concurrency if concurrency.nil?
@@ -346,8 +348,8 @@ module LLM
     def call_functions
       case concurrency || :call
       when :call then call(:functions)
-      when :thread, :task, :fiber then wait(concurrency)
-      else raise ArgumentError, "Unknown concurrency: #{concurrency.inspect}. Expected :call, :thread, :task, or :fiber"
+      when :thread, :task, :fiber, :ractor then wait(concurrency)
+      else raise ArgumentError, "Unknown concurrency: #{concurrency.inspect}. Expected :call, :thread, :task, :fiber, or :ractor"
       end
     end
   end

data/lib/llm/context.rb

@@ -86,6 +86,7 @@ module LLM
       return respond(prompt, params) if mode == :responses
       params = params.merge(messages: @messages.to_a)
       params = @params.merge(params)
+      bind!(params[:stream], params[:model])
       res = @llm.complete(prompt, params)
       role = params[:role] || @llm.user_role
       role = @llm.tool_role if params[:role].nil? && [*prompt].grep(LLM::Function::Return).any?
@@ -110,6 +111,7 @@ module LLM
     #   puts res.output_text
     def respond(prompt, params = {})
       params = @params.merge(params)
+      bind!(params[:stream], params[:model])
       res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
       params = params.merge(previous_response_id: res_id, input: @messages.to_a).compact
       res = @llm.responses.create(prompt, params)
@@ -356,6 +358,14 @@ module LLM
     rescue LLM::NoSuchModelError, LLM::NoSuchRegistryError
       0
     end
+
+    private
+
+    def bind!(stream, model)
+      return unless LLM::Stream === stream
+      stream.extra[:tracer] = tracer
+      stream.extra[:model] = model
+    end
   end
 
   # Backward-compatible alias

data/lib/llm/function/array.rb

@@ -27,8 +27,9 @@ class LLM::Function
     #   - `:thread`: Use threads
     #   - `:task`: Use async tasks (requires async gem)
     #   - `:fiber`: Use raw fibers
+    #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
     #
-    # @return [LLM::Function::ThreadGroup, LLM::Function::TaskGroup, LLM::Function::FiberGroup]
+    # @return [LLM::Function::ThreadGroup, LLM::Function::TaskGroup, LLM::Function::FiberGroup, LLM::Function::Ractor::Group]
     def spawn(strategy)
       case strategy
       when :task
@@ -37,8 +38,10 @@ class LLM::Function
         ThreadGroup.new(map { |fn| fn.spawn(:thread) })
       when :fiber
         FiberGroup.new(map { |fn| fn.spawn(:fiber) })
+      when :ractor
+        Ractor::Group.new(map { |fn| fn.spawn(:ractor) })
       else
-        raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
+        raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, or :ractor"
       end
     end
 
@@ -51,6 +54,7 @@ class LLM::Function
     #   - `:thread`: Use threads
     #   - `:task`: Use async tasks (requires async gem)
     #   - `:fiber`: Use raw fibers
+    #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
     #
     # @return [Array<LLM::Function::Return>]
     #  Returns values to be reported back to the LLM.

data/lib/llm/function/ractor/job.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Ractor::Job} class manages execution and mailbox
+  # coordination for a single ractor-backed function call.
+  class Ractor::Job
+    ##
+    # @param [::Ractor] mailbox
+    # @param [Class] runner_class
+    # @param [String, nil] id
+    # @param [String] name
+    # @param [Hash, Array, nil] arguments
+    # @return [LLM::Function::Ractor::Job]
+    def initialize(mailbox, runner_class, id, name, arguments)
+      @mailbox = mailbox
+      @runner_class = runner_class
+      @id = id
+      @name = name
+      @arguments = arguments
+    end
+
+    ##
+    # @return [void]
+    def call
+      spawn
+      wait
+    end
+
+    private
+
+    def wait
+      done = false
+      result = nil
+      waiters = []
+      loop do
+        case ::Ractor.receive
+        in [:done, *result]
+          done = true
+          waiters.each { _1.send(result) }
+          waiters.clear
+        in [:alive?, reply]
+          reply.send(!done)
+        in [:wait, reply]
+          done ? reply.send(result) : waiters << reply
+        end
+      end
+    end
+
+    def spawn
+      ::Ractor.new(@mailbox, @runner_class, @id, @name, @arguments) do |mailbox, runner_class, id, name, arguments|
+        kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments
+        mailbox.send([:done, id, name, runner_class.new.call(**kwargs)])
+      rescue => ex
+        mailbox.send([:done, id, name, {error: true, type: ex.class.name, message: ex.message}])
+      end
+    end
+  end
+end

data/lib/llm/function/ractor/mailbox.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Ractor::Mailbox} class manages the mailbox protocol
+  # for a single ractor-backed function call.
+  class Ractor::Mailbox
+    ##
+    # @return [::Ractor]
+    attr_reader :task
+
+    ##
+    # @param [::Ractor] task
+    # @return [LLM::Function::Ractor::Mailbox]
+    def initialize(task)
+      @task = task
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      request(:alive?)
+    end
+
+    ##
+    # @return [Array]
+    def wait
+      request(:wait)
+    end
+
+    private
+
+    def request(type)
+      reply = ::Ractor.new { ::Ractor.receive }
+      task.send([type, reply])
+      reply.respond_to?(:take) ? reply.take : ::Ractor.select(reply).last
+    end
+  end
+end

data/lib/llm/function/ractor/task.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Ractor::Task} class wraps a ractor-backed function
+  # call and delegates mailbox coordination to
+  # {LLM::Function::Ractor::Mailbox}.
+  class Ractor::Task
+    ##
+    # @return [LLM::Function::Ractor::Mailbox]
+    attr_reader :mailbox
+
+    ##
+    # @param [Class] runner_class
+    # @param [String, nil] id
+    # @param [String] name
+    # @param [Hash, Array, nil] arguments
+    # @return [LLM::Function::Ractor::Task]
+    def initialize(runner_class, id, name, arguments)
+      @mailbox = Ractor::Mailbox.new(build_task(runner_class, id, name, arguments))
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      mailbox.alive?
+    end
+
+    ##
+    # @return [LLM::Function::Return]
+    def wait
+      id, name, value = mailbox.wait
+      Return.new(id, name, value)
+    end
+    alias_method :value, :wait
+
+    private
+
+    def build_task(runner_class, id, name, arguments)
+      ::Ractor.new(runner_class, id, name, arguments) do |runner_class, id, name, arguments|
+        LLM::Function::Ractor::Job.new(::Ractor.current, runner_class, id, name, arguments).call
+      end
+    end
+  end
+end

data/lib/llm/function/ractor.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  module Ractor
+    require_relative "ractor/mailbox"
+    require_relative "ractor/job"
+    require_relative "ractor/task"
+  end
+end

data/lib/llm/function/ractor_group.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Ractor::Group} class wraps an array of
+  # {LLM::Function::Ractor::Task} objects that are running
+  # {LLM::Function} calls concurrently.
+  class Ractor::Group
+    ##
+    # @param [Array<LLM::Function::Task>] tasks
+    # @return [LLM::Function::Ractor::Group]
+    def initialize(tasks)
+      @tasks = tasks
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      @tasks.any?(&:alive?)
+    end
+
+    ##
+    # @return [Array<LLM::Function::Return>]
+    def wait
+      @tasks.map(&:wait)
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function/task.rb

@@ -14,7 +14,7 @@ class LLM::Function
     attr_reader :function
 
     ##
-    # @param [Thread, Fiber, Async::Task] task
+    # @param [Thread, Fiber, Async::Task, Ractor, LLM::Function::Ractor::Task] task
     # @param [LLM::Function, nil] function
     # @return [LLM::Function::Task]
     def initialize(task, function = nil)
@@ -25,7 +25,8 @@ class LLM::Function
     ##
     # @return [Boolean]
     def alive?
-      task.alive?
+      return task.alive? if task.respond_to?(:alive?)
+      false
     end
 
     ##

data/lib/llm/function.rb

@@ -36,6 +36,8 @@ class LLM::Function
   require_relative "function/thread_group"
   require_relative "function/fiber_group"
   require_relative "function/task_group"
+  require_relative "function/ractor"
+  require_relative "function/ractor_group"
 
   extend LLM::Function::Registry
   prepend LLM::Function::Tracing
@@ -174,6 +176,7 @@ class LLM::Function
   #   - `:thread`: Use threads
   #   - `:task`: Use async tasks (requires async gem)
   #   - `:fiber`: Use raw fibers
+  #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
   #
   # @return [LLM::Function::Task]
   #   Returns a task whose `#value` is an {LLM::Function::Return}.
@@ -181,17 +184,20 @@ class LLM::Function
     task = case strategy
     when :task
       require "async" unless defined?(::Async)
-      Async { call_function }
+      Async { call }
     when :thread
-      Thread.new { call_function }
+      Thread.new { call }
     when :fiber
       Fiber.new do
-        call_function
+        call
       ensure
         Fiber.yield
       end.tap(&:resume)
+    when :ractor
+      raise ArgumentError, "Ractor concurrency only supports class-based tools" unless Class === @runner
+      Ractor::Task.new(@runner, id, name, arguments)
     else
-      raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
+      raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, or :ractor"
     end
     Task.new(task, self)
   ensure

data/lib/llm/provider.rb

@@ -271,34 +271,48 @@ class LLM::Provider
 
   ##
   # @return [LLM::Tracer]
-  #  Returns a fiber-local tracer
+  #  Returns the current scoped tracer override or provider default tracer
   def tracer
-    weakmap[self] || LLM::Tracer::Null.new(self)
+    weakmap[self] || @tracer || LLM::Tracer::Null.new(self)
   end
 
   ##
-  # Set a fiber-local tracer
+  # Set the provider's default tracer
+  # This tracer is shared by the provider instance and becomes the fallback
+  # whenever no scoped override is active.
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   Thread.new do
-  #     llm.tracer = LLM::Tracer::Logger.new(llm, path: "/path/to/log/1.txt")
-  #   end
-  #   Thread.new do
-  #     llm.tracer = LLM::Tracer::Logger.new(llm, path: "/path/to/log/2.txt")
-  #   end
-  #   # ...
+  #   llm.tracer = LLM::Tracer::Logger.new(llm, path: "/path/to/log.txt")
   # @param [LLM::Tracer] tracer
   #  A tracer
   # @return [void]
   def tracer=(tracer)
-    if tracer.nil?
-      if weakmap.respond_to?(:delete)
-        weakmap.delete(self)
-      else
-        weakmap[self] = nil
-      end
+    @tracer = tracer
+  end
+
+  ##
+  # Override the tracer for the current fiber while the block runs.
+  # This is useful when you want per-request or per-turn tracing without
+  # replacing the provider's default tracer.
+  # @example
+  #   llm.with_tracer(LLM::Tracer::Logger.new(llm, io: $stdout)) do
+  #     llm.complete("hello", model: "gpt-5.4-mini")
+  #   end
+  # @param [LLM::Tracer] tracer
+  # @yield
+  # @return [Object]
+  def with_tracer(tracer)
+    had_override = weakmap.key?(self)
+    previous = weakmap[self]
+    weakmap[self] = tracer
+    yield
+  ensure
+    if had_override
+      weakmap[self] = previous
+    elsif weakmap.respond_to?(:delete)
+      weakmap.delete(self)
     else
-      weakmap[self] = tracer
+      weakmap[self] = nil
     end
   end
 

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

@@ -109,6 +109,8 @@ class LLM::Anthropic
       fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
         fn.id = tool["id"]
         fn.arguments = LLM::Anthropic.parse_tool_input(tool["input"])
+        fn.tracer = @stream.extra[:tracer]
+        fn.model = @stream.extra[:model]
       end
       [fn, (registered ? nil : @stream.tool_not_found(fn))]
     end

data/lib/llm/providers/google/stream_parser.rb

@@ -157,6 +157,8 @@ class LLM::Google
       fn = (registered || LLM::Function.new(call["name"])).dup.tap do |fn|
         fn.id = LLM::Google.tool_id(part:, cindex:, pindex:)
         fn.arguments = call["args"]
+        fn.tracer = @stream.extra[:tracer]
+        fn.model = @stream.extra[:model]
       end
       [fn, (registered ? nil : @stream.tool_not_found(fn))]
     end

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

@@ -273,6 +273,8 @@ class LLM::OpenAI
       fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
         fn.id = tool["call_id"]
         fn.arguments = arguments
+        fn.tracer = @stream.extra[:tracer]
+        fn.model = @stream.extra[:model]
       end
       [fn, (registered ? nil : @stream.tool_not_found(fn))]
     end

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

@@ -189,6 +189,8 @@ class LLM::OpenAI
       fn = (registered || LLM::Function.new(function["name"])).dup.tap do |fn|
         fn.id = tool["id"]
         fn.arguments = arguments
+        fn.tracer = @stream.extra[:tracer]
+        fn.model = @stream.extra[:model]
       end
       [fn, (registered ? nil : @stream.tool_not_found(fn))]
     end

data/lib/llm/sequel/plugin.rb

@@ -13,8 +13,8 @@ module LLM::Sequel
   # default) or as a structured object (`format: :json` / `:jsonb`) for
   # databases such as PostgreSQL that can persist JSON natively.
   # `:json` and `:jsonb` expect a real JSON column type with Sequel handling
-  # JSON typecasting for the model. A `tracer:` proc can also be configured
-  # to assign a fiber-local tracer onto the resolved provider.
+  # JSON typecasting for the model. `provider:`, `context:`, and `tracer:`
+  # can also be configured as symbols that are called on the model.
   module Plugin
     EMPTY_HASH = {}.freeze
     DEFAULT_USAGE_COLUMNS = {
@@ -61,9 +61,9 @@ module LLM::Sequel
     #   Storage format for the serialized context. Use `:string` for text
     #   columns, or `:json` / `:jsonb` for structured JSON columns with Sequel
     #   JSON typecasting enabled.
-    # @option options [Proc, LLM::Tracer, nil] :tracer
-    #   Optional tracer or proc that resolves to one and is assigned through
-    #   `llm.tracer = ...` on the resolved provider.
+    # @option options [Proc, Symbol, LLM::Tracer, nil] :tracer
+    #   Optional tracer, method name, or proc that resolves to one and is
+    #   assigned through `llm.tracer = ...` on the resolved provider.
     # @return [void]
     def self.configure(model, options = EMPTY_HASH)
       options = DEFAULTS.merge(options)
@@ -224,8 +224,6 @@ module LLM::Sequel
       ctx.tracer
     end
 
-    private
-
     ##
     # Returns the resolved provider instance for this record.
     # @return [LLM::Provider]
@@ -233,11 +231,14 @@ module LLM::Sequel
       options = self.class.llm_plugin_options
       provider = self[columns[:provider_column]]
       kwargs = resolve_options(options[:provider])
-      @llm ||= LLM.method(provider).call(**kwargs)
+      return @llm if @llm
+      @llm = LLM.method(provider).call(**kwargs)
       @llm.tracer = resolve_option(options[:tracer]) if options[:tracer]
       @llm
     end
 
+    private
+
     ##
     # @return [LLM::Context]
     def ctx
@@ -276,6 +277,7 @@ module LLM::Sequel
     def resolve_option(option)
       case option
       when Proc then instance_exec(&option)
+      when Symbol then send(option)
       when Hash then option.dup
       else option
       end

data/lib/llm/stream/queue.rb

@@ -38,6 +38,7 @@ class LLM::Stream
     #   - `:thread`: Use threads
     #   - `:task`: Use async tasks (requires async gem)
     #   - `:fiber`: Use raw fibers
+    #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
     # @return [Array<LLM::Function::Return>]
     def wait(strategy)
       returns, tasks = @items.shift(@items.length).partition { LLM::Function::Return === _1 }
@@ -45,7 +46,8 @@ class LLM::Stream
       when :thread then LLM::Function::ThreadGroup.new(tasks).wait
       when :task then LLM::Function::TaskGroup.new(tasks).wait
       when :fiber then LLM::Function::FiberGroup.new(tasks).wait
-      else raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
+      when :ractor then LLM::Function::Ractor::Group.new(tasks).wait
+      else raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, or :ractor"
       end
       returns.concat fire_hooks(tasks, results)
     end

data/lib/llm/stream.rb

@@ -22,6 +22,13 @@ module LLM
   class Stream
     require_relative "stream/queue"
 
+    ##
+    # Returns extra context associated with the current streamed request.
+    # @return [Hash]
+    def extra
+      @extra ||= LLM::Object.from({})
+    end
+
     ##
     # Returns a lazily-initialized queue for tool results or spawned work.
     # @return [LLM::Stream::Queue]
@@ -63,13 +70,16 @@ module LLM
     # Called when a streamed tool call has been fully constructed.
     # @note A stream implementation may start tool execution here, for
     #   example by pushing `tool.spawn(:thread)`, `tool.spawn(:fiber)`, or
-    #   `tool.spawn(:task)` onto {#queue}. When a streamed tool cannot be
-    #   resolved, `error` is passed as an {LLM::Function::Return}. It can be
-    #   sent back to the model, allowing the tool-call path to recover and the
-    #   session to continue. Tool resolution depends on
+    #   `tool.spawn(:task)` onto {#queue}. Mixed strategies can also be
+    #   selected per tool, such as `tool.mcp? ? tool.spawn(:task) :
+    #   tool.spawn(:ractor)`. When a streamed tool cannot be resolved, `error`
+    #   is passed as an {LLM::Function::Return}. It can be sent back to the
+    #   model, allowing the tool-call path to recover and the session to
+    #   continue. Tool resolution depends on
     #   {LLM::Function.registry}, which includes {LLM::Tool LLM::Tool}
     #   subclasses, including MCP tools, but not functions defined with
-    #   {LLM.function}.
+    #   {LLM.function}. The current `:ractor` mode is for class-based tools
+    #   and does not support MCP tools.
     # @param [LLM::Function] tool
     #  The parsed tool call.
     # @param [LLM::Function::Return, nil] error

data/lib/llm/version.rb

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

data/llm.gemspec

@@ -17,10 +17,11 @@ Gem::Specification.new do |spec|
   persisted state, so real systems can be built out of one coherent
   execution model instead of a pile of adapters. It stays close to Ruby, runs
   on the standard library by default, loads optional pieces only when needed,
-  works naturally in Rails or ActiveRecord through acts_as_llm, includes
-  built-in Sequel support through plugin :llm, and is designed for
-  engineers who want control over long-lived, tool-capable, stateful AI
-  workflows instead of just request/response helpers.
+  includes built-in ActiveRecord support through acts_as_llm and
+  acts_as_agent, includes built-in Sequel support through plugin :llm,
+  and is designed for engineers who want control over long-lived,
+  tool-capable, stateful AI workflows instead of just request/response
+  helpers.
   DESCRIPTION
 
   spec.license = "0BSD"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.17.0
+  version: 4.19.0
 platform: ruby
 authors:
 - Antar Azri
@@ -201,10 +201,11 @@ description: |
   persisted state, so real systems can be built out of one coherent
   execution model instead of a pile of adapters. It stays close to Ruby, runs
   on the standard library by default, loads optional pieces only when needed,
-  works naturally in Rails or ActiveRecord through acts_as_llm, includes
-  built-in Sequel support through plugin :llm, and is designed for
-  engineers who want control over long-lived, tool-capable, stateful AI
-  workflows instead of just request/response helpers.
+  includes built-in ActiveRecord support through acts_as_llm and
+  acts_as_agent, includes built-in Sequel support through plugin :llm,
+  and is designed for engineers who want control over long-lived,
+  tool-capable, stateful AI workflows instead of just request/response
+  helpers.
 email:
 - azantar@proton.me
 - 0x1eef@hardenedbsd.org
@@ -242,6 +243,11 @@ files:
 - lib/llm/function.rb
 - lib/llm/function/array.rb
 - lib/llm/function/fiber_group.rb
+- lib/llm/function/ractor.rb
+- lib/llm/function/ractor/job.rb
+- lib/llm/function/ractor/mailbox.rb
+- lib/llm/function/ractor/task.rb
+- lib/llm/function/ractor_group.rb
 - lib/llm/function/registry.rb
 - lib/llm/function/task.rb
 - lib/llm/function/task_group.rb
@@ -403,7 +409,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Lightweight runtime for building capable AI systems in Ruby.
 test_files: []