llm.rb 12.5.1 → 12.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eec18b65456b95a668fd5552fbd1c73464e26c55d07cc980efe5973e82fd548
-  data.tar.gz: 4ab12f000f12f64e65afbca3ac4b08d79751f6d860c7cc9cab685c0e688d20c7
+  metadata.gz: 1660ea34a112d4c31eb8c9a51000ecd244b0f5629a4f763eceecd734d96f765b
+  data.tar.gz: 8040eefe13ffc48a40181642dad749d6abd7d16950f5d9e379ef006a0bb5af0c
 SHA512:
-  metadata.gz: 86a7207e852129c3e22a747e74c8f5bcf12666886786104a38b01d2d80cc8cf82a008678fc7c5817203e138b6929aeeaba090af87f95fbea4185e7b733bbc8ff
-  data.tar.gz: 40c2df5d31af69ff01c666259c2f39c54f545a9bb1115e4419266c2ce3a467467236ac3f2c9d39154d3242ebf9d12cb1541dad3c21f1b60290c1a816ac09003e
+  metadata.gz: cc1821c04eb0f996ca3e5d86d1722565e1fe2bc13351f3771c57de556d7ee9e97d930b3516ec70dea9686fad6443498c40d50584c6065a95242318f054a98d83
+  data.tar.gz: 3cc468ef1332c6f39d6b34a6a11fafe91eaf459ed80d5e79709f8106278fcb6fa1ba4f67b701a38539c3cba4d6967ad88858cccb4bb6b5b12690290036ad2afb

data/CHANGELOG.md

@@ -15,6 +15,101 @@
 
 ## What's next
 
+## v12.6.0
+
+Changes since `v12.5.1`.
+
+This release adds bulk defaults for tools and agents — `LLM::Tool.defaults`
+for setting parameter defaults and `LLM::Agent.set` for mass-assigning
+class-level defaults, both mirrored on ActiveRecord and Sequel agent models.
+
+It also makes `LLM::Interrupt` reliable across every concurrency strategy
+(:thread, :call, :fiber, :task, :fork, and :ractor) so tool cancellation
+works consistently regardless of execution backend, and fixes a stale fiber
+reference in `LLM::Context#talk` that could prevent interruption after a
+prior call.
+
+### Add
+
+* **tool: add `defaults` method for setting parameter defaults** <br>
+  Add `LLM::Tool.defaults(properties)` for bulk-setting default values
+  on tool parameters, matching the same interface as `LLM::Schema.defaults`.
+  Each key maps to a parameter name; unknown keys raise `KeyError`.
+
+* **agent: add `set` method for bulk-assigning class-level defaults** <br>
+  Add `LLM::Agent.set(properties)` for mass-assigning agent defaults
+  from a Hash. Each key maps to a class-level accessor; unknown keys
+  raise `KeyError`.
+
+* **active_record: expose `set` on `acts_as_agent` models** <br>
+  ActiveRecord models using `acts_as_agent` can call `set` to
+  bulk-assign agent class-level defaults.
+
+* **sequel: expose `set` on `plugin :agent` models** <br>
+  Sequel models using `plugin :agent` can call `set` to bulk-assign
+  agent class-level defaults.
+
+### Fix
+
+* **function: raise `LLM::Interrupt` on thread where tool is running** <br>
+  On cancel, `LLM::Interrupt` is now raised on the thread that is
+  running a tool. The tool can rescue `LLM::Interrupt` and gracefully
+  terminate (e.g., clean up resources). The previous approach used
+  `Thread#interrupt` which was less reliable — it did not interrupt a
+  sleeping thread.
+
+* **function: suppress thread exception reporting in `:thread` concurrency** <br>
+  Threads spawned by the `:thread` concurrency strategy now have
+  `report_on_exception` set to `false`, preventing noisy exception
+  messages from appearing on stderr when a thread is interrupted
+  during tool execution.
+
+* **context: clear `@owner` after `talk` completes** <br>
+  `LLM::Context#talk` now clears the `@owner` reference in an
+  `ensure` block after the method completes, so `interrupt!` does
+  not attempt to interrupt a stale fiber reference from a prior
+  call.
+
+* **function: raise `LLM::Interrupt` on thread waiting in `CallGroup#wait`** <br>
+  When using `ctx.wait(:call)`, `LLM::Interrupt` is now raised on the
+  thread executing the sequential tool wait. `CallGroup#wait` tracks the
+  active thread and `interrupt!` raises `LLM::Interrupt` on it, enabling
+  interruption of the `:call` concurrency strategy just like the existing
+  `:thread` strategy.
+
+* **function: raise `LLM::Interrupt` on fiber-backed tool tasks** <br>
+  `LLM::Interrupt` is now raised on the active fiber via `Fiber#raise`
+  when interrupting `:fiber`-concurrency tools.
+  <br><br>
+  `Task#interrupt!` now dispatches by task type — `Thread#raise` for
+  threads, `Fiber#raise` for fibers — making interruption reliable
+  across all concurrency strategies.
+
+* **function: raise `LLM::Interrupt` on fork-backed tool tasks** <br>
+  `LLM::Interrupt` is now raised on the main thread of a fork child
+  process via `Thread.main.raise(LLM::Interrupt)` when interrupting
+  `:fork`-concurrency tools, and the fork `Task#wait` re-raises the
+  interrupt on the parent side — making interruption reliable across
+  all concurrency strategies including `:fork`.
+
+* **function: raise `LLM::Interrupt` on `Async::Task`-backed tool tasks** <br>
+  `LLM::Interrupt` is now raised on the underlying fiber of an
+  `Async::Task` via `Fiber#raise` when interrupting `:task`-concurrency
+  tools. `Task#interrupt!` now detects `Async::Task` instances and
+  dispatches to `Fiber#raise`, extending reliable interruption to the
+  `:task` concurrency strategy under the Async runtime.
+
+* **function: raise `LLM::Interrupt` on ractor-backed tool tasks** <br>
+  `LLM::Interrupt` is now raised on the main thread inside a ractor
+  via `Thread.main.raise(LLM::Interrupt)` when interrupting
+  `:ractor`-concurrency tools. A listener thread inside the tool
+  ractor waits for an interrupt message via `Ractor.receive` and
+  raises `LLM::Interrupt` on the ractor's main thread.
+  <br><br>
+  `Task#interrupt!` delegates to the mailbox to send the interrupt
+  message — extending reliable interruption to the `:ractor`
+  concurrency strategy.
+
 ## v12.5.1
 
 Changes since `v12.5.0`.

data/README.md

@@ -362,11 +362,10 @@ require "llm"
 require "llm/active_record"
 
 class Agent < ApplicationRecord
-  acts_as_agent do |agent|
-    agent.model "deepseek-v4-pro"
-    agent.instructions "solve the user's query"
-    agent.tools [Research, FinalizeResearch, ActOnResearch]
-  end
+  acts_as_agent
+  set instructions: "solve the user's query",
+      model: "deepseek-v4-pro",
+      tools: [Research, FinalizeResearch, ActOnResearch]
 
   private
 

data/lib/llm/active_record/acts_as_agent.rb

@@ -17,9 +17,41 @@ module LLM::ActiveRecord
   # class and forwarded to an internal agent subclass.
   module ActsAsAgent
     module ClassMethods
+      ##
+      # @return [Class<LLM::Agent>]
       def agent
         @agent ||= Class.new(LLM::Agent)
       end
+
+      ##
+      # Bulk-assign class-level agent defaults.
+      #
+      # Each key is resolved by calling the corresponding class method on the
+      # internal agent subclass.
+      #
+      # @example
+      #   class Agent < ApplicationRecord
+      #     acts_as_agent
+      #     set instructions: "You are a system administrator",
+      #         model: "gpt-4.1-nano",
+      #         tools: [Shell]
+      #   end
+      #
+      # @param [Hash] properties
+      # @option properties [String] :instructions
+      # @option properties [String] :model
+      # @option properties [Array<LLM::Function>] :tools
+      # @option properties [Array<String>] :skills
+      # @option properties [#to_json] :schema
+      # @option properties [Symbol, Array<Symbol>] :concurrency
+      # @option properties [LLM::Tracer, Proc] :tracer
+      # @option properties [Object, Proc] :stream
+      # @option properties [String, Symbol, Array<String, Symbol>, Proc] :confirm
+      # @raise [KeyError] when a property key does not match a class-level accessor
+      # @return [void]
+      def set(properties)
+        agent.set(properties)
+      end
     end
 
     module Hooks

data/lib/llm/agent.rb

@@ -27,10 +27,10 @@ module LLM
   #
   # @example
   #   class SystemAdmin < LLM::Agent
-  #     model "gpt-4.1-nano"
-  #     instructions "You are a Linux system admin"
-  #     tools Shell
-  #     schema Result
+  #     set model: "gpt-4.1-nano",
+  #         instructions: "You are a Linux system admin",
+  #         tools: [Shell],
+  #         schema: Result
   #   end
   #
   #   llm = LLM.openai(key: ENV["KEY"])
@@ -42,6 +42,42 @@ module LLM
     # @return [LLM::Provider]
     attr_reader :llm
 
+    ##
+    # Bulk-assign class-level agent defaults from a Hash.
+    #
+    # Each key is resolved by calling the corresponding class method on the
+    # agent subclass. An error is raised for unknown keys so that typos are
+    # caught early.
+    #
+    # @example
+    #   class AdminAgent < LLM::Agent
+    #     set instructions: "You are a system administrator",
+    #         model: "gpt-4.1-nano",
+    #         tools: [Shell, ReadFile]
+    #   end
+    #
+    # @param [Hash] properties
+    # @option properties [String] :instructions
+    # @option properties [String] :model
+    # @option properties [Array<LLM::Function>] :tools
+    # @option properties [Array<String>] :skills
+    # @option properties [#to_json] :schema
+    # @option properties [Symbol, Array<Symbol>] :concurrency
+    # @option properties [LLM::Tracer, Proc] :tracer
+    # @option properties [Object, Proc] :stream
+    # @option properties [String, Symbol, Array<String, Symbol>, Proc] :confirm
+    # @raise [KeyError] when a property key does not match a class-level accessor
+    # @return [void]
+    def self.set(properties)
+      properties.each do
+        if respond_to?(_1)
+          public_send(_1, _2)
+        else
+          raise KeyError, "key not found: #{_1}"
+        end
+      end
+    end
+
     ##
     # Set or get the default model
     # @param [String, nil] model

data/lib/llm/context.rb

@@ -206,6 +206,8 @@ module LLM
       @messages.concat LLM::Prompt === prompt ? prompt.to_a : [LLM::Message.new(role, prompt)]
       @messages.concat [res.choices[-1]].compact
       res
+    ensure
+      @owner = nil
     end
 
     ##

data/lib/llm/function/call_group.rb

@@ -14,6 +14,7 @@ class LLM::Function
     # @return [LLM::Function::CallGroup]
     def initialize(functions)
       @functions = functions
+      @owner = nil
     end
 
     ##
@@ -25,6 +26,7 @@ class LLM::Function
     ##
     # @return [nil]
     def interrupt!
+      @owner&.raise(LLM::Interrupt)
       nil
     end
     alias_method :cancel!, :interrupt!
@@ -32,7 +34,10 @@ class LLM::Function
     ##
     # @return [Array<LLM::Function::Return>]
     def wait
+      @owner = Thread.current
       @functions.map(&:call)
+    ensure
+      @owner = nil
     end
     alias_method :value, :wait
   end

data/lib/llm/function/fiber_group.rb

@@ -62,7 +62,7 @@ class LLM::Function
     ##
     # @return [nil]
     def interrupt!
-      @fibers.each(&:interrupt!)
+      @fibers.each { _1.task.raise(LLM::Interrupt) if _1.task.alive? }
       nil
     end
     alias_method :cancel!, :interrupt!

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

@@ -24,6 +24,8 @@ class LLM::Function
       runner = @function.runner
       controller = setup(runner)
       @ch.result.write([:result, call!(runner)])
+    rescue LLM::Interrupt
+      @ch.result.write([:interrupt])
     rescue => ex
       @ch.result.write([:result, error(ex)])
     ensure
@@ -56,8 +58,7 @@ class LLM::Function
         ready << true
         kind = @ch.control.recv
         next unless kind == :interrupt
-        hook = %i[on_cancel on_interrupt].find { runner.respond_to?(_1) }
-        runner.public_send(hook) if hook
+        Thread.main.raise(LLM::Interrupt)
       rescue IOError, ArgumentError
       end
       ready.pop

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

@@ -52,6 +52,7 @@ class LLM::Function
     # @return [LLM::Function::Return]
     def wait
       kind, data = @ch.result.recv
+      raise LLM::Interrupt if kind == :interrupt
       raise ArgumentError, "Unknown fork message: #{kind.inspect}" unless kind == :result
       result = Return.new(data[:id], data[:name], data[:value])
       reap

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

@@ -35,22 +35,32 @@ class LLM::Function
       waiters = []
       loop do
         case ::Ractor.receive
-        in [:done, *result]
+        in [:done, *data]
+          result ||= data
           done = true
           waiters.each { _1.send(result) }
           waiters.clear
         in [:alive?, reply]
           reply.send(!done)
         in [:wait, reply]
-          done ? reply.send(result) : waiters << reply
+          done ? reply.send(result) : (waiters << reply)
+        in [:interrupt]
+          @tool&.send(:interrupt)
         end
       end
     end
 
     def spawn
-      ::Ractor.new(@mailbox, @runner_class, @id, @name, @arguments) do |mailbox, runner_class, id, name, arguments|
+      @tool = ::Ractor.new(@mailbox, @runner_class, @id, @name, @arguments) do |mailbox, runner_class, id, name, arguments|
+        Thread.new do
+          ::Ractor.receive == :interrupt or next
+          Thread.main.raise(LLM::Interrupt)
+        rescue ::Ractor::Error
+        end
         kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments
         mailbox.send([:done, id, name, runner_class.new.call(**kwargs)])
+      rescue LLM::Interrupt
+        mailbox.send([:done, id, name, {cancelled: true, reason: "interrupted"}])
       rescue => ex
         mailbox.send([:done, id, name, {error: true, type: ex.class.name, message: ex.message}])
       end

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

@@ -28,6 +28,13 @@ class LLM::Function
       request(:wait)
     end
 
+    ##
+    # @return [nil]
+    def interrupt!
+      task.send([:interrupt])
+      nil
+    end
+
     private
 
     def request(type)

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

@@ -43,6 +43,7 @@ class LLM::Function
     ##
     # @return [nil]
     def interrupt!
+      mailbox&.interrupt!
       nil
     end
     alias_method :cancel!, :interrupt!

data/lib/llm/function/task.rb

@@ -33,7 +33,18 @@ class LLM::Function
     ##
     # @return [nil]
     def interrupt!
-      task.interrupt! if task.respond_to?(:interrupt!)
+      case task
+      when Thread
+        task.raise(LLM::Interrupt)
+      when Fiber
+        task.raise(LLM::Interrupt) if task.alive?
+      else
+        if defined?(::Async::Task) and ::Async::Task === task
+          task.fiber&.raise(LLM::Interrupt) if task.alive?
+        elsif task.respond_to?(:interrupt!)
+          task.interrupt!
+        end
+      end
       function&.interrupt!
       nil
     end

data/lib/llm/function/thread_group.rb

@@ -68,7 +68,7 @@ class LLM::Function
     ##
     # @return [nil]
     def interrupt!
-      @threads.each(&:interrupt!)
+      @threads.each { _1.task.raise LLM::Interrupt }
       nil
     end
     alias_method :cancel!, :interrupt!

data/lib/llm/function/tracing.rb

@@ -11,6 +11,8 @@ class LLM::Function
       result = super
       @tracer.on_tool_finish(result:, span:)
       result
+    rescue LLM::Interrupt
+      raise
     rescue => ex
       @tracer.on_tool_error(ex:, span:)
       raise(ex)

data/lib/llm/function.rb

@@ -256,7 +256,7 @@ class LLM::Function
       LLM.require "async" unless defined?(::Async)
       Async { call! }
     when :thread
-      Thread.new { call! }
+      Thread.new { call! }.tap { _1.report_on_exception = false }
     when :fiber
       raise ArgumentError, "Fiber concurrency requires Fiber.scheduler" unless Fiber.scheduler
       Fiber.schedule { call! }
@@ -382,6 +382,8 @@ class LLM::Function
     runner = self.runner
     kwargs = arguments.respond_to?(:to_h) ? arguments.to_h.transform_keys(&:to_sym) : arguments
     Return.new(id, name, runner.call(**kwargs))
+  rescue LLM::Interrupt
+    raise
   rescue => ex
     Return.new(id, name, {error: true, type: ex.class.name, message: ex.message})
   end

data/lib/llm/sequel/agent.rb

@@ -32,9 +32,41 @@ module LLM::Sequel
         @llm_agent_options || Agent::DEFAULTS
       end
 
+      ##
+      # @return [Class<LLM::Agent>]
       def agent
         @agent ||= Class.new(LLM::Agent)
       end
+
+      ##
+      # Bulk-assign class-level agent defaults.
+      #
+      # Each key is resolved by calling the corresponding class method on the
+      # internal agent subclass.
+      #
+      # @example
+      #   class Agent < Sequel::Model
+      #     plugin :llm_agent
+      #     set instructions: "You are a system administrator",
+      #         model: "gpt-4.1-nano",
+      #         tools: [Shell]
+      #   end
+      #
+      # @param [Hash] properties
+      # @option properties [String] :instructions
+      # @option properties [String] :model
+      # @option properties [Array<LLM::Function>] :tools
+      # @option properties [Array<String>] :skills
+      # @option properties [#to_json] :schema
+      # @option properties [Symbol, Array<Symbol>] :concurrency
+      # @option properties [LLM::Tracer, Proc] :tracer
+      # @option properties [Object, Proc] :stream
+      # @option properties [String, Symbol, Array<String, Symbol>, Proc] :confirm
+      # @raise [KeyError] when a property key does not match a class-level accessor
+      # @return [void]
+      def set(properties)
+        agent.set(properties)
+      end
     end
 
     module InstanceMethods

data/lib/llm/tool/param.rb

@@ -56,6 +56,18 @@ class LLM::Tool
       end
     end
 
+    ##
+    # Set default values for parameters.
+    # @param [Hash] defaults
+    # @return [LLM::Schema::Object]
+    def defaults(defaults)
+      lock do
+        function.params.tap do |schema|
+          defaults.each { Utils.fetch(schema.properties, _1).default(_2) }
+        end
+      end
+    end
+
     ##
     # @api private
     module Utils

data/lib/llm/version.rb

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

data/resources/deepdive.md

@@ -71,6 +71,7 @@ features that didn't make it into the homepage documentation.
 <summary>Cancellation</summary>
 
 - [Cancel a request](#cancel-a-request)
+- [Tool interrupts](#tool-interrupts)
 </details>
 
 <details>
@@ -188,11 +189,11 @@ be simpler without it.
 
 ```ruby
 class Agent < LLM::Agent
-  model "deepseek-v4-pro"
-  tools { [DoResearch, FinalizeResearch, ActOnResearch] }
-  stream { $stdout }
-  tracer :set_tracer
-  concurrency :fork
+  set model: "deepseek-v4-pro",
+      tools: [DoResearch, FinalizeResearch, ActOnResearch],
+      stream: -> { $stdout },
+      tracer: :set_tracer,
+      concurrency: :fork
 
   def research!
     talk "start the research"
@@ -828,6 +829,54 @@ rescue LLM::Interrupt
 end
 ```
 
+#### Tool interrupts
+
+When a running tool is interrupted &ndash; for example the user presses
+ESC in the [REPL](#repl) &ndash; the runtime raises
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+on the tool's execution context. This behavior is uniform across
+all six concurrency strategies (`:call`, `:thread`, `:fiber`,
+`:task`, `:fork`, and `:ractor`).
+
+A tool has two choices:
+
+**Re-raise** `LLM::Interrupt` to cancel the entire turn. The
+exception propagates out of the tool loop and the request is
+aborted. This is the default when you don't rescue the exception.
+
+```ruby
+def call
+  # ... do work ...
+rescue LLM::Interrupt
+  cleanup
+  raise   # cancel the turn
+end
+```
+
+**Return a value** to continue the tool loop. The model receives
+the result and decides what to do next, aware that the tool was
+interrupted.
+
+```ruby
+def call
+  # ... do work ...
+rescue LLM::Interrupt
+  cleanup
+  {ok: false, reason: "interrupted"}  # continue the loop
+end
+```
+
+The right choice depends on the situation. A hard cancel aborts
+the request outright &ndash; useful when continuing would produce
+garbage. Returning a value lets the model adapt, which can be
+helpful when the interrupt is temporary (e.g. a timeout).
+
+The `:ractor` strategy is cooperative by nature &ndash; the ractor
+must check for a cancel message at safe points in its execution.
+The `:fork` strategy delivers the interrupt via a signal, which
+interrupts blocking syscalls immediately. All other strategies
+raise the exception directly on the executing thread or fiber.
+
 [Back to top](#table-of-contents)
 
 ## Tracer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 12.5.1
+  version: 12.6.0
 platform: ruby
 authors:
 - robert