llm.rb 4.16.1 → 4.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6119e0673d055f50139fd33a4523bd99ffabb0fc2688a361f23297ef9ac428fd
-  data.tar.gz: bfa5943241a2e9944245f0976458cfdd4895e7b72dbb83fd186f9d7ad2b987ee
+  metadata.gz: d834b30dd18d6bf83ccd2334bbedba0ee5a9f75d0d6d0616aefb7baa6be68ad0
+  data.tar.gz: d8c8a1e43cc89d888ab1ea008baddce7e1427fc3598daf68ca04fd0eff1351b0
 SHA512:
-  metadata.gz: e139622d5cbaa8f42a1a6739b9792119f9086ae0b11ae896794953d9bb0fa9ed46159da7f10f7a8b619ef468404ae425b2158b359c940a11220dd48b0b230e2e
-  data.tar.gz: 563f48928b6836d2bbcbc8d72bd594aa265fa285ad99cb8ff0c9574f9e67b7da60f9d42c2eeb1bddce0ba72e1425dab260bc65670fa7d812f7a77dc8016262d7
+  metadata.gz: f9fbe6f7080294c0500153dbfeb3c721407553289a2f34cd37e63552a84171bdc1bc130fb325aaf164f099c5fd6bfb417f550eea60dc126c20f940a7737e393a
+  data.tar.gz: 67cef120d84c98ea695caab059d2bb008ca1cbdeb15a1b2f13c819166b1edd7a523c7213acabed5b35c44e7123ae85481c0eaff815d6254088c858e5a0516ae3

data/CHANGELOG.md

@@ -2,8 +2,53 @@
 
 ## Unreleased
 
+Changes since `v4.17.0`.
+
+## 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,
+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`.
+
+### 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.
+
+* **Bring `LLM::Agent` closer to `LLM::Context`** <br>
+  Expand `LLM::Agent` so it exposes more of the same runtime surface as
+  `LLM::Context`, including returns, interruption, mode, cost, context
+  window, structured serialization, and other context-backed helpers,
+  while still auto-managing tool loops.
+
+* **Refresh agent docs and coverage** <br>
+  Update the README and deep dive to explain the current role of
+  `LLM::Agent`, add examples that show automatic tool execution and
+  concurrency, and add focused specs for the expanded agent surface and
+  tool-loop behavior.
+
+* **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`.
+
+* **Bring persisted ORM wrappers closer to `LLM::Context`** <br>
+  Expand both the Sequel plugin and `acts_as_llm` so record-backed
+  contexts expose more of the same runtime surface as `LLM::Context`,
+  including mode, returns, interruption, prompt helpers, file helpers,
+  and tracer access.
+
+* **Add ActiveRecord agent persistence with `acts_as_agent`** <br>
+  Add `acts_as_agent` for ActiveRecord models that should wrap
+  `LLM::Agent`, reusing the same record-backed runtime shape as
+  `acts_as_llm` while letting tool execution be managed by the agent.
+
 ## v4.16.1
 
 Changes since `v4.16.0`.

data/README.md

@@ -4,27 +4,24 @@
 <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.16.1-green.svg?" alt="Version"></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>
 </p>
 
 ## About
 
-llm.rb is a runtime for building AI systems that integrate directly with your
-application. It is not just an API wrapper. It provides a unified execution
-model for providers, tools, MCP servers, streaming, schemas, files, and
-state.
+llm.rb is a lightweight runtime for building capable AI systems in Ruby.
 
-It is built for engineers who want control over how these systems run. llm.rb
-stays close to Ruby, runs on the standard library by default, loads optional
-pieces only when needed, and remains easy to extend. It also works well in
-Rails or ActiveRecord applications, with built-in `acts_as_llm`, and includes
-built-in Sequel support through `plugin :llm`, so long-lived context state can
-be saved and restored across requests, jobs, or retries.
+It is not just an API wrapper. llm.rb gives you one runtime for providers,
+contexts, agents, tools, MCP servers, streaming, schemas, files, and persisted
+state, so real systems can be built out of one coherent execution model instead
+of a pile of adapters.
 
-Most LLM libraries stop at request/response APIs. Building real systems means
-stitching together streaming, tools, state, persistence, and external
-services by hand. llm.rb provides a single execution model for all of these,
-so they compose naturally instead of becoming separate subsystems.
+It stays close to Ruby, runs on the standard library by default, loads optional
+pieces only when needed, 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.
 
 ## Architecture
 
@@ -66,6 +63,10 @@ same context object.
 - **Streaming and tool execution work together** <br>
   Start tool work while output is still streaming so you can hide latency
   instead of waiting for turns to finish.
+- **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`.
 - **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),
@@ -88,11 +89,14 @@ same context object.
   Connect to MCP servers over stdio or HTTP without bolting on a separate
   integration stack.
 - **ActiveRecord and Sequel persistence are built in** <br>
-  Use `acts_as_llm` on ActiveRecord models or `plugin :llm` on Sequel models
-  to persist `LLM::Context` state with sensible default columns. Both support
-  `provider:` and `context:` hooks, plus `format: :string` for text columns
-  or `format: :jsonb` for native PostgreSQL JSON storage when ORM JSON
-  typecasting support is enabled.
+  llm.rb includes built-in ActiveRecord support through `acts_as_llm` and
+  `acts_as_agent`, plus built-in Sequel support through `plugin :llm`.
+  Use `acts_as_llm` when you want to wrap `LLM::Context`, `acts_as_agent`
+  when you want to wrap `LLM::Agent`, or `plugin :llm` on Sequel models to
+  persist `LLM::Context` state with sensible default columns. These
+  integrations support `provider:` and `context:` hooks, plus `format:
+  :string` for text columns or `format: :jsonb` for native PostgreSQL JSON
+  storage when ORM JSON typecasting support is enabled.
 - **Persistent HTTP pooling is shared process-wide** <br>
   When enabled, separate
   [`LLM::Provider`](https://0x1eef.github.io/x/llm.rb/LLM/Provider.html)
@@ -174,7 +178,7 @@ gem install llm.rb
 
 **REPL**
 
-See the [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) for more examples.
+This example uses [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) directly for an interactive REPL. <br> See the [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) for more examples.
 
 ```ruby
 require "llm"
@@ -191,7 +195,7 @@ end
 
 **Sequel (ORM)**
 
-See the [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) for more examples.
+The `plugin :llm` integration wraps [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) on a `Sequel::Model` and keeps tool execution explicit. <br> See the [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) for more examples.
 
 ```ruby
 require "llm"
@@ -207,9 +211,10 @@ ctx.talk("Remember that my favorite language is Ruby")
 puts ctx.talk("What is my favorite language?").content
 ```
 
-**ActiveRecord (ORM)**
+**ActiveRecord (ORM): acts_as_llm**
 
-See the [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) for more examples.
+The `acts_as_llm` method wraps [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) and
+provides full control over tool execution. <br> See the [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) for more examples.
 
 ```ruby
 require "llm"
@@ -225,6 +230,47 @@ ctx.talk("Remember that my favorite language is Ruby")
 puts ctx.talk("What is my favorite language?").content
 ```
 
+**ActiveRecord (ORM): acts_as_agent**
+
+The `acts_as_agent` method wraps [`LLM::Agent`](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html) and
+manages tool execution for you. <br> See the [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) for more examples.
+
+```ruby
+require "llm"
+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
+end
+
+ticket = Ticket.create!(provider: "openai", model: "gpt-5.4-mini")
+puts ticket.talk("How do I rotate my API key?").content
+```
+
+**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](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) for more examples.
+
+```ruby
+require "llm"
+
+class ShellAgent < LLM::Agent
+  model "gpt-5.4-mini"
+  instructions "You are a Linux system assistant."
+  tools Shell
+  concurrency :thread
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+agent = ShellAgent.new(llm)
+puts agent.talk("What time is it on this system?").content
+```
+
 ## Resources
 
 - [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) is the

data/lib/llm/active_record/acts_as_agent.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module LLM::ActiveRecord
+  ##
+  # ActiveRecord integration for persisting {LLM::Agent LLM::Agent} state.
+  #
+  # This wrapper reuses the same record-backed runtime surface as
+  # {LLM::ActiveRecord::ActsAsLLM}, but builds an {LLM::Agent LLM::Agent}
+  # instead of an {LLM::Context LLM::Context}. Agent defaults such as model,
+  # tools, schema, instructions, and concurrency are configured on the model
+  # class and forwarded to an internal agent subclass.
+  module ActsAsAgent
+    EMPTY_HASH = LLM::ActiveRecord::ActsAsLLM::EMPTY_HASH
+    DEFAULT_USAGE_COLUMNS = LLM::ActiveRecord::ActsAsLLM::DEFAULT_USAGE_COLUMNS
+    DEFAULTS = LLM::ActiveRecord::ActsAsLLM::DEFAULTS
+
+    module ClassMethods
+      def model(model = nil)
+        return agent.model if model.nil?
+        agent.model(model)
+      end
+
+      def tools(*tools)
+        return agent.tools if tools.empty?
+        agent.tools(*tools)
+      end
+
+      def schema(schema = nil)
+        return agent.schema if schema.nil?
+        agent.schema(schema)
+      end
+
+      def instructions(instructions = nil)
+        return agent.instructions if instructions.nil?
+        agent.instructions(instructions)
+      end
+
+      def concurrency(concurrency = nil)
+        return agent.concurrency if concurrency.nil?
+        agent.concurrency(concurrency)
+      end
+
+      def agent
+        @agent ||= Class.new(LLM::Agent)
+      end
+    end
+
+    module Hooks
+      ##
+      # Called when hooks are extended onto an ActiveRecord model.
+      #
+      # @param [Class] model
+      # @return [void]
+      def self.extended(model)
+        options = model.llm_agent_options
+        model.validates options[:provider_column], options[:model_column], presence: true
+        model.include LLM::ActiveRecord::ActsAsLLM::InstanceMethods unless model.ancestors.include?(LLM::ActiveRecord::ActsAsLLM::InstanceMethods)
+        model.include InstanceMethods unless model.ancestors.include?(InstanceMethods)
+        model.extend ClassMethods unless model.singleton_class.ancestors.include?(ClassMethods)
+      end
+    end
+
+    ##
+    # Installs the `acts_as_agent` wrapper on an ActiveRecord model.
+    #
+    # @param [Hash] options
+    # @option options [Symbol] :format
+    #   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.
+    # @return [void]
+    def acts_as_agent(options = EMPTY_HASH)
+      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
+    end
+
+    module InstanceMethods
+      private
+
+      ##
+      # Returns the resolved provider instance for this record.
+      # @return [LLM::Provider]
+      def llm
+        options = self.class.llm_agent_options
+        provider = self[columns[:provider_column]]
+        kwargs = resolve_options(options[:provider])
+        @llm ||= LLM.method(provider).call(**kwargs)
+        @llm.tracer = resolve_option(options[:tracer]) if options[:tracer]
+        @llm
+      end
+
+      ##
+      # @return [LLM::Agent]
+      def ctx
+        @ctx ||= begin
+          options = self.class.llm_agent_options
+          params = resolve_options(options[:context]).dup
+          params[:model] ||= self[columns[:model_column]]
+          ctx = self.class.agent.new(llm, params.compact)
+          data = self[columns[:data_column]]
+          if data.nil? || data == ""
+            ctx
+          else
+            case options[:format]
+            when :string then ctx.restore(string: data)
+            when :json, :jsonb then ctx.restore(data:)
+            else raise ArgumentError, "Unknown format: #{options[:format].inspect}"
+            end
+          end
+        end
+      end
+
+      ##
+      # @return [void]
+      def flush
+        attrs = {
+          columns[:data_column] => serialize_context(self.class.llm_agent_options[:format]),
+          columns[:input_tokens] => ctx.usage.input_tokens,
+          columns[:output_tokens] => ctx.usage.output_tokens,
+          columns[:total_tokens] => ctx.usage.total_tokens
+        }
+        assign_attributes(attrs)
+        save!
+      end
+
+      ##
+      # @return [Hash]
+      def resolve_option(option)
+        case option
+        when Proc then instance_exec(&option)
+        when Hash then option.dup
+        else option
+        end
+      end
+
+      ##
+      # @return [Hash]
+      def resolve_options(option)
+        case option
+        when Proc, Hash then resolve_option(option)
+        else EMPTY_HASH.dup
+        end
+      end
+
+      def serialize_context(format)
+        case format
+        when :string then ctx.to_json
+        when :json, :jsonb then ctx.to_h
+        else raise ArgumentError, "Unknown format: #{format.inspect}"
+        end
+      end
+
+      def columns
+        @columns ||= begin
+          options = self.class.llm_agent_options
+          usage_columns = options[:usage_columns]
+          {
+            provider_column: options[:provider_column],
+            model_column: options[:model_column],
+            data_column: options[:data_column],
+            input_tokens: usage_columns[:input_tokens],
+            output_tokens: usage_columns[:output_tokens],
+            total_tokens: usage_columns[:total_tokens]
+          }.freeze
+        end
+      end
+    end
+  end
+end
+
+::ActiveRecord::Base.extend(LLM::ActiveRecord::ActsAsAgent)

data/lib/llm/active_record/acts_as_llm.rb

@@ -13,7 +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.
+  # handling JSON typecasting for the model. A `tracer:` proc can also be
+  # configured to assign a fiber-local tracer onto the resolved provider.
   module ActsAsLLM
     EMPTY_HASH = {}.freeze
     DEFAULT_USAGE_COLUMNS = {
@@ -27,6 +28,7 @@ module LLM::ActiveRecord
       data_column: :data,
       format: :string,
       usage_columns: DEFAULT_USAGE_COLUMNS,
+      tracer: nil,
       provider: EMPTY_HASH,
       context: EMPTY_HASH
     }.freeze
@@ -52,6 +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.
     # @return [void]
     def acts_as_llm(options = EMPTY_HASH)
       options = DEFAULTS.merge(options)
@@ -94,6 +99,13 @@ module LLM::ActiveRecord
         ctx.call(...)
       end
 
+      ##
+      # @see LLM::Context#mode
+      # @return [Symbol]
+      def mode
+        ctx.mode
+      end
+
       ##
       # @see LLM::Context#messages
       # @return [Array<LLM::Message>]
@@ -116,6 +128,13 @@ module LLM::ActiveRecord
         ctx.functions
       end
 
+      ##
+      # @see LLM::Context#returns
+      # @return [Array<LLM::Function::Return>]
+      def returns
+        ctx.returns
+      end
+
       ##
       # @see LLM::Context#cost
       # @return [LLM::Cost]
@@ -143,6 +162,50 @@ module LLM::ActiveRecord
         )
       end
 
+      ##
+      # @see LLM::Context#interrupt!
+      # @return [nil]
+      def interrupt!
+        ctx.interrupt!
+      end
+      alias_method :cancel!, :interrupt!
+
+      ##
+      # @see LLM::Context#prompt
+      # @return [LLM::Prompt]
+      def prompt(&)
+        ctx.prompt(&)
+      end
+      alias_method :build_prompt, :prompt
+
+      ##
+      # @see LLM::Context#image_url
+      # @return [LLM::Object]
+      def image_url(...)
+        ctx.image_url(...)
+      end
+
+      ##
+      # @see LLM::Context#local_file
+      # @return [LLM::Object]
+      def local_file(...)
+        ctx.local_file(...)
+      end
+
+      ##
+      # @see LLM::Context#remote_file
+      # @return [LLM::Object]
+      def remote_file(...)
+        ctx.remote_file(...)
+      end
+
+      ##
+      # @see LLM::Context#tracer
+      # @return [LLM::Tracer]
+      def tracer
+        ctx.tracer
+      end
+
       private
 
       ##
@@ -153,6 +216,8 @@ module LLM::ActiveRecord
         provider = self[columns[:provider_column]]
         kwargs = resolve_options(options[:provider])
         @llm ||= LLM.method(provider).call(**kwargs)
+        @llm.tracer = resolve_option(options[:tracer]) if options[:tracer]
+        @llm
       end
 
       ##

data/lib/llm/active_record.rb

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
 require "llm/active_record/acts_as_llm"
+require "llm/active_record/acts_as_agent"

data/lib/llm/agent.rb

@@ -6,10 +6,18 @@ module LLM
   # reusable, preconfigured assistants with defaults for model,
   # tools, schema, and instructions.
   #
+  # It wraps the same stateful runtime surface as
+  # {LLM::Context LLM::Context}: message history, usage, persistence,
+  # streaming parameters, and provider-backed requests still flow through
+  # an underlying context. The defining behavior of an agent is that it
+  # automatically resolves pending tool calls for you during `talk` and
+  # `respond`, instead of leaving tool loops to the caller.
+  #
   # **Notes:**
   # * Instructions are injected only on the first request.
-  # * An agent will automatically execute tool calls (unlike {LLM::Context LLM::Context}).
-  # * The idea originally came from RubyLLM and was adapted to llm.rb.
+  # * An agent automatically executes tool loops (unlike {LLM::Context LLM::Context}).
+  # * Tool loop execution can be configured with `concurrency :call`,
+  #   `:thread`, `:task`, or `:fiber`.
   #
   # @example
   #   class SystemAdmin < LLM::Agent
@@ -72,6 +80,21 @@ module LLM
       @instructions = instructions
     end
 
+    ##
+    # Set or get the tool execution concurrency.
+    #
+    # @param [Symbol, nil] concurrency
+    #  Controls how pending tool loops are executed:
+    #  - `:call`: sequential calls
+    #  - `:thread`: concurrent threads
+    #  - `:task`: concurrent async tasks
+    #  - `:fiber`: concurrent raw fibers
+    # @return [Symbol, nil]
+    def self.concurrency(concurrency = nil)
+      return @concurrency if concurrency.nil?
+      @concurrency = concurrency
+    end
+
     ##
     # @param [LLM::Provider] provider
     #  A provider
@@ -82,8 +105,10 @@ module LLM
     # @option params [String] :model Defaults to the provider's default model
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
     # @option params [#to_json, nil] :schema Defaults to nil
+    # @option params [Symbol, nil] :concurrency Defaults to the agent class concurrency
     def initialize(llm, params = {})
       defaults = {model: self.class.model, tools: self.class.tools, schema: self.class.schema}.compact
+      @concurrency = params.delete(:concurrency) || self.class.concurrency
       @llm = llm
       @ctx = LLM::Context.new(llm, defaults.merge(params))
     end
@@ -94,7 +119,7 @@ module LLM
     #
     # @param prompt (see LLM::Provider#complete)
     # @param [Hash] params The params passed to the provider, including optional :stream, :tools, :schema etc.
-    # @option params [Integer] :max_tool_rounds The maxinum number of tool call iterations (default 10)
+    # @option params [Integer] :tool_attempts The maxinum number of tool call iterations (default 10)
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
@@ -102,13 +127,13 @@ module LLM
     #   response = agent.talk("Hello, what is your name?")
     #   puts response.choices[0].content
     def talk(prompt, params = {})
-      i, max = 0, Integer(params.delete(:max_tool_rounds) || 10)
+      max = Integer(params.delete(:tool_attempts) || 10)
       res = @ctx.talk(apply_instructions(prompt), params)
-      until @ctx.functions.empty?
-        raise LLM::ToolLoopError, "pending tool calls remain" if i >= max
-        res = @ctx.talk @ctx.functions.map(&:call), params
-        i += 1
+      max.times do
+        break if @ctx.functions.empty?
+        res = @ctx.talk(call_functions, params)
       end
+      raise LLM::ToolLoopError, "pending tool calls remain" unless @ctx.functions.empty?
       res
     end
     alias_method :chat, :talk
@@ -120,7 +145,7 @@ module LLM
     # @note Not all LLM providers support this API
     # @param prompt (see LLM::Provider#complete)
     # @param [Hash] params The params passed to the provider, including optional :stream, :tools, :schema etc.
-    # @option params [Integer] :max_tool_rounds The maxinum number of tool call iterations (default 10)
+    # @option params [Integer] :tool_attempts The maxinum number of tool call iterations (default 10)
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
@@ -128,13 +153,13 @@ module LLM
     #   res = agent.respond("What is the capital of France?")
     #   puts res.output_text
     def respond(prompt, params = {})
-      i, max = 0, Integer(params.delete(:max_tool_rounds) || 10)
+      max = Integer(params.delete(:tool_attempts) || 10)
       res = @ctx.respond(apply_instructions(prompt), params)
-      until @ctx.functions.empty?
-        raise LLM::ToolLoopError, "pending tool calls remain" if i >= max
-        res = @ctx.respond @ctx.functions.map(&:call), params
-        i += 1
+      max.times do
+        break if @ctx.functions.empty?
+        res = @ctx.respond(call_functions, params)
       end
+      raise LLM::ToolLoopError, "pending tool calls remain" unless @ctx.functions.empty?
       res
     end
 
@@ -150,12 +175,41 @@ module LLM
       @ctx.functions
     end
 
+    ##
+    # @see LLM::Context#returns
+    # @return [Array<LLM::Function::Return>]
+    def returns
+      @ctx.returns
+    end
+
+    ##
+    # @see LLM::Context#call
+    # @return [Object]
+    def call(...)
+      @ctx.call(...)
+    end
+
+    ##
+    # @see LLM::Context#wait
+    # @return [Array<LLM::Function::Return>]
+    def wait(...)
+      @ctx.wait(...)
+    end
+
     ##
     # @return [LLM::Object]
     def usage
       @ctx.usage
     end
 
+    ##
+    # Interrupt the active request, if any.
+    # @return [nil]
+    def interrupt!
+      @ctx.interrupt!
+    end
+    alias_method :cancel!, :interrupt!
+
     ##
     # @param (see LLM::Context#prompt)
     # @return (see LLM::Context#prompt)
@@ -206,6 +260,53 @@ module LLM
       @ctx.model
     end
 
+    ##
+    # @return [Symbol]
+    def mode
+      @ctx.mode
+    end
+
+    ##
+    # Returns the configured tool execution concurrency.
+    # @return [Symbol, nil]
+    def concurrency
+      @concurrency
+    end
+
+    ##
+    # @see LLM::Context#cost
+    # @return [LLM::Cost]
+    def cost
+      @ctx.cost
+    end
+
+    ##
+    # @see LLM::Context#context_window
+    # @return [Integer]
+    def context_window
+      @ctx.context_window
+    end
+
+    ##
+    # @see LLM::Context#to_h
+    # @return [Hash]
+    def to_h
+      @ctx.to_h
+    end
+
+    ##
+    # @return [String]
+    def to_json(...)
+      to_h.to_json(...)
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "@llm=#{@llm.class}, @mode=#{mode.inspect}, @messages=#{messages.inspect}>"
+    end
+
     ##
     # @param (see LLM::Context#serialize)
     # @return (see LLM::Context#serialize)
@@ -230,14 +331,24 @@ module LLM
       instr = self.class.instructions
       return new_prompt unless instr
       if LLM::Prompt === new_prompt
-        @ctx.messages.empty? ? new_prompt.system(instr) : nil
+        new_prompt.system(instr) if @ctx.messages.empty?
         new_prompt
       else
         prompt do
-          @ctx.messages.empty? ? _1.system(instr) : nil
+          _1.system(instr) if @ctx.messages.empty?
           _1.user(new_prompt)
         end
       end
     end
+
+    ##
+    # @return [Array<LLM::Function::Return>]
+    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"
+      end
+    end
   end
 end

data/lib/llm/sequel/plugin.rb

@@ -13,7 +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.
+  # JSON typecasting for the model. A `tracer:` proc can also be configured
+  # to assign a fiber-local tracer onto the resolved provider.
   module Plugin
     EMPTY_HASH = {}.freeze
     DEFAULT_USAGE_COLUMNS = {
@@ -27,6 +28,7 @@ module LLM::Sequel
       data_column: :data,
       format: :string,
       usage_columns: DEFAULT_USAGE_COLUMNS,
+      tracer: nil,
       provider: EMPTY_HASH,
       context: EMPTY_HASH
     }.freeze
@@ -59,6 +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.
     # @return [void]
     def self.configure(model, options = EMPTY_HASH)
       options = DEFAULTS.merge(options)
@@ -111,6 +116,13 @@ module LLM::Sequel
       ctx.call(...)
     end
 
+    ##
+    # @see LLM::Context#mode
+    # @return [Symbol]
+    def mode
+      ctx.mode
+    end
+
     ##
     # @see LLM::Context#messages
     # @return [Array<LLM::Message>]
@@ -134,6 +146,13 @@ module LLM::Sequel
       ctx.functions
     end
 
+    ##
+    # @see LLM::Context#returns
+    # @return [Array<LLM::Function::Return>]
+    def returns
+      ctx.returns
+    end
+
     ##
     # @see LLM::Context#cost
     # @return [LLM::Cost]
@@ -161,6 +180,50 @@ module LLM::Sequel
       )
     end
 
+    ##
+    # @see LLM::Context#interrupt!
+    # @return [nil]
+    def interrupt!
+      ctx.interrupt!
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @see LLM::Context#prompt
+    # @return [LLM::Prompt]
+    def prompt(&)
+      ctx.prompt(&)
+    end
+    alias_method :build_prompt, :prompt
+
+    ##
+    # @see LLM::Context#image_url
+    # @return [LLM::Object]
+    def image_url(...)
+      ctx.image_url(...)
+    end
+
+    ##
+    # @see LLM::Context#local_file
+    # @return [LLM::Object]
+    def local_file(...)
+      ctx.local_file(...)
+    end
+
+    ##
+    # @see LLM::Context#remote_file
+    # @return [LLM::Object]
+    def remote_file(...)
+      ctx.remote_file(...)
+    end
+
+    ##
+    # @see LLM::Context#tracer
+    # @return [LLM::Tracer]
+    def tracer
+      ctx.tracer
+    end
+
     private
 
     ##
@@ -171,6 +234,8 @@ module LLM::Sequel
       provider = self[columns[:provider_column]]
       kwargs = resolve_options(options[:provider])
       @llm ||= LLM.method(provider).call(**kwargs)
+      @llm.tracer = resolve_option(options[:tracer]) if options[:tracer]
+      @llm
     end
 
     ##

data/lib/llm/version.rb

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

data/llm.gemspec

@@ -8,25 +8,19 @@ Gem::Specification.new do |spec|
   spec.authors = ["Antar Azri", "0x1eef", "Christos Maris", "Rodrigo Serrano"]
   spec.email = ["azantar@proton.me", "0x1eef@hardenedbsd.org"]
 
-  spec.summary = "System integration layer for LLMs, tools, MCP, and APIs in Ruby."
+  spec.summary = "Lightweight runtime for building capable AI systems in Ruby."
 
   spec.description = <<~DESCRIPTION
-  llm.rb is a runtime for building AI systems that integrate directly with your
-  application. It is not just an API wrapper. It provides a unified execution
-  model for providers, tools, MCP servers, streaming, schemas, files, and
-  state.
-
-  It is built for engineers who want control over how these systems run.
-  llm.rb stays close to Ruby, runs on the standard library by default, loads
-  optional pieces only when needed, and remains easy to extend. It also works
-  well in Rails or ActiveRecord applications, where a small wrapper around
-  context persistence is enough to save and restore long-lived conversation
-  state across requests, jobs, or retries.
-
-  Most LLM libraries stop at request/response APIs. Building real systems
-  means stitching together streaming, tools, state, persistence, and external
-  services by hand. llm.rb provides a single execution model for all of these,
-  so they compose naturally instead of becoming separate subsystems.
+  llm.rb is a lightweight runtime for building capable AI systems in Ruby.
+  It is not just an API wrapper. llm.rb gives you one runtime for providers,
+  contexts, agents, tools, MCP servers, streaming, schemas, files, and
+  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.
   DESCRIPTION
 
   spec.license = "0BSD"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.16.1
+  version: 4.17.0
 platform: ruby
 authors:
 - Antar Azri
@@ -195,22 +195,16 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.7'
 description: |
-  llm.rb is a runtime for building AI systems that integrate directly with your
-  application. It is not just an API wrapper. It provides a unified execution
-  model for providers, tools, MCP servers, streaming, schemas, files, and
-  state.
-
-  It is built for engineers who want control over how these systems run.
-  llm.rb stays close to Ruby, runs on the standard library by default, loads
-  optional pieces only when needed, and remains easy to extend. It also works
-  well in Rails or ActiveRecord applications, where a small wrapper around
-  context persistence is enough to save and restore long-lived conversation
-  state across requests, jobs, or retries.
-
-  Most LLM libraries stop at request/response APIs. Building real systems
-  means stitching together streaming, tools, state, persistence, and external
-  services by hand. llm.rb provides a single execution model for all of these,
-  so they compose naturally instead of becoming separate subsystems.
+  llm.rb is a lightweight runtime for building capable AI systems in Ruby.
+  It is not just an API wrapper. llm.rb gives you one runtime for providers,
+  contexts, agents, tools, MCP servers, streaming, schemas, files, and
+  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.
 email:
 - azantar@proton.me
 - 0x1eef@hardenedbsd.org
@@ -229,6 +223,7 @@ files:
 - data/zai.json
 - lib/llm.rb
 - lib/llm/active_record.rb
+- lib/llm/active_record/acts_as_agent.rb
 - lib/llm/active_record/acts_as_llm.rb
 - lib/llm/agent.rb
 - lib/llm/bot.rb
@@ -410,5 +405,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: System integration layer for LLMs, tools, MCP, and APIs in Ruby.
+summary: Lightweight runtime for building capable AI systems in Ruby.
 test_files: []