llm.rb 4.20.1 → 4.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58f2ff0f8147443face2f3d7c48b249b8aec30de4345fa286f87c622853cb516
-  data.tar.gz: 9dba9a0609fff95e141ee5a819ff454a9dbd5ecb9c987a1a3e3b73822431d6d2
+  metadata.gz: f0bca66b2bd8873cf39abb3be19dc99ca20d558e40ef3e9f475bf1f33faef6b6
+  data.tar.gz: c73a2c5093e7e09557242919feb5a377f25b0fa8a11249a9f346673ad7d3a921
 SHA512:
-  metadata.gz: 172de04003136f5b599f5b2c274d9354ca576512bc35e9af85c5672f32bd3ad5f85a8a0b7e60e29c60b8fa7e6bd8d39ed5d23692c60a4b6de0f2c941d542fd41
-  data.tar.gz: 9a3ef1da238e38ab51af3a20f235201bca736a41753c9848a589467676a979829dca6c7e5708ee12be344e9e0686ba4652504514b72769ff5d511c5d752dd9f2
+  metadata.gz: 2a00191aaab47702a794f9fa86d782f21832be2a7ef309bd558aa482100d7c66ddbdf3320e89c80af2942c6e33295f10d387702130162fbac7cc98fd9b24c9a8
+  data.tar.gz: a6709f6fd265af673da771f635f34c68e28e490405700c1a59b18253391dbbcae09ce677a4251994d898a851ec08dc598c5ff858e516e25b1206948f509abf67

data/CHANGELOG.md

@@ -2,8 +2,55 @@
 
 ## Unreleased
 
+Changes since `v4.21.0`.
+
+## v4.21.0
+
+Changes since `v4.20.2`.
+
+This release expands higher-level composition in llm.rb. It adds Sequel agent
+persistence through `plugin :agent` and introduces directory-backed skills
+that load from `SKILL.md`, resolve named tools, and plug directly into
+`LLM::Context` and `LLM::Agent`.
+
+### Change
+
+* **Add `plugin :agent` for Sequel models** <br>
+  Add Sequel support for `plugin :agent`, similar to ActiveRecord's
+  `acts_as_agent`, so models can wrap `LLM::Agent` with built-in
+  persistence.
+
+* **Load directory-backed skills through `LLM::Context` and `LLM::Agent`** <br>
+  Add `skills:` to `LLM::Context` and `skills ...` to `LLM::Agent` so
+  directories with `SKILL.md` can be loaded, resolved into tools, and run
+  through the normal llm.rb tool path.
+
+## v4.20.2
+
 Changes since `v4.20.1`.
 
+This patch release improves runtime behavior around interruption and mixed
+concurrency waits. It also rounds out response API uniformity for Google
+completion responses.
+
+### Fix
+
+* **Expose Google completion response IDs through `.id`** <br>
+  Add `LLM::Response#id` support to Google completion responses so tracer
+  and caller code can rely on the same API used by other providers.
+
+* **Track interrupt ownership on the active request** <br>
+  Bind `LLM::Context` interruption to the fiber running `talk` or `respond`
+  so `interrupt!` works correctly when requests are started outside the
+  context's initialization fiber.
+
+### Change
+
+* **Allow mixed concurrency strategies in `wait(...)`** <br>
+  Let `LLM::Context#wait`, `LLM::Stream#wait`, and `LLM::Agent.concurrency`
+  accept arrays such as `[:thread, :ractor]` so mixed tool sets can wait on
+  more than one concurrency strategy.
+
 ## v4.20.1
 
 Changes since `v4.20.0`.

data/README.md

@@ -4,26 +4,33 @@
 <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.20.1-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.21.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
 
 llm.rb is a lightweight runtime for building capable AI systems in Ruby.
+<br>
+
+It is also the most capable AI Ruby runtime that exists _today_, and that claim is
+backed up by research. Maybe it won't always be true, and that would be good news too -
+because it would mean the Ruby ecosystem is getting stronger.
 
-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.
+llm.rb is not just an API wrapper: it gives you one runtime for providers,
+contexts, agents, tools, skills, 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, includes built-in ActiveRecord support through
+llm.rb is designed for Ruby, and although it works great in Rails, it is not tightly
+coupled to it. It runs on the standard library by default (zero dependencies),
+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
+`plugin :llm` and `plugin :agent`, and is designed for engineers who want control over
 long-lived, tool-capable, stateful AI workflows instead of just
 request/response helpers.
 
-Want to see some code? Jump to [the examples](#examples) section.
+Want to see some code? Jump to [the examples](#examples) section. <br>
+Want a taste of what llm.rb can build? See [the screencast](#screencast).
 
 ## Architecture
 
@@ -100,13 +107,18 @@ same context object.
   integration stack.
 - **ActiveRecord and Sequel persistence are built in** <br>
   llm.rb includes built-in ActiveRecord support through `acts_as_llm` and
-  `acts_as_agent`, plus built-in Sequel support through `plugin :llm`.
+  `acts_as_agent`, plus built-in Sequel support through `plugin :llm` and
+  `plugin :agent`.
   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.
+  when you want to wrap `LLM::Agent`, `plugin :llm` when you want a
+  `LLM::Context` on a Sequel model, or `plugin :agent` when you want an
+  `LLM::Agent`. 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.
+- **ORM models can become persistent agents** <br>
+  Turn an ActiveRecord or Sequel model into an agent-capable model with
+  built-in persistence, stored on the same table, with `jsonb` support when
+  your ORM and database support native JSON columns.
 - **Persistent HTTP pooling is shared process-wide** <br>
   When enabled, separate
   [`LLM::Provider`](https://0x1eef.github.io/x/llm.rb/LLM/Provider.html)
@@ -125,6 +137,11 @@ same context object.
 - **Tools are explicit** <br>
   Run local tools, provider-native tools, and MCP tools through the same path
   with fewer special cases.
+- **Skills are just tools loaded from directories** <br>
+  Point llm.rb at directories with a `SKILL.md`, resolve named tools through
+  the registry, and run those skills through `LLM::Context` or `LLM::Agent`
+  without creating a second execution model. If you are familiar with skills
+  in Claude or Codex, llm.rb supports the same general idea.
 - **Providers are normalized, not flattened** <br>
   Share one API surface across providers without losing access to provider-
   specific capabilities where they matter.
@@ -164,6 +181,7 @@ same context object.
 - **Run Tools While Streaming** — overlap model output with tool latency
 - **Concurrent Execution** — threads, async tasks, and fibers
 - **Agents** — reusable assistants with tool auto-execution
+- **Skills** — directory-backed capabilities loaded from `SKILL.md`
 - **Structured Outputs** — JSON Schema-based responses
 - **Responses API** — stateful response workflows where providers support them
 - **MCP Support** — stdio and HTTP MCP clients with prompt and tool support
@@ -186,9 +204,9 @@ gem install llm.rb
 
 ## Examples
 
-**REPL**
+#### REPL
 
-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.
+This example uses [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) directly for an interactive REPL. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -203,9 +221,91 @@ loop do
 end
 ```
 
-**Sequel (ORM)**
+#### Streaming
+
+This example uses [`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html) directly so visible output and tool execution can happen together. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+
+```ruby
+require "llm"
+
+class Stream < LLM::Stream
+  def on_content(content)
+    $stdout << content
+  end
+
+  def on_tool_call(tool, error)
+    return queue << error if error
+    $stdout << "\nRunning tool #{tool.name}...\n"
+    queue << tool.spawn(:thread)
+  end
+
+  def on_tool_return(tool, result)
+    if result.error?
+      $stdout << "Tool #{tool.name} failed\n"
+    else
+      $stdout << "Finished tool #{tool.name}\n"
+    end
+  end
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm, stream: Stream.new, tools: [System])
+
+ctx.talk("Run `date` and `uname -a`.")
+ctx.talk(ctx.wait(:thread)) while ctx.functions.any?
+```
+
+#### Reasoning
+
+This example uses [`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html) with the OpenAI Responses API so reasoning output is streamed separately from visible assistant output. See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+
+```ruby
+require "llm"
+
+class Stream < LLM::Stream
+  def on_content(content)
+    $stdout << content
+  end
+
+  def on_reasoning_content(content)
+    $stderr << content
+  end
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(
+  llm,
+  model: "gpt-5.4-mini",
+  mode: :responses,
+  reasoning: {effort: "medium"},
+  stream: Stream.new
+)
+ctx.talk("Solve 17 * 19 and show your work.")
+```
+
+#### Request Cancellation
 
-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.
+Need to cancel a stream? llm.rb has you covered through [`LLM::Context#interrupt!`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#interrupt-21-instance_method). <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+
+```ruby
+require "llm"
+require "io/console"
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm, stream: $stdout)
+
+worker = Thread.new do
+  ctx.talk("Write a very long essay about network protocols.")
+end
+
+STDIN.getch
+ctx.interrupt!
+worker.join
+```
+
+#### Sequel (ORM)
+
+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 (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -222,10 +322,10 @@ ctx.talk("Remember that my favorite language is Ruby")
 puts ctx.talk("What is my favorite language?").content
 ```
 
-**ActiveRecord (ORM): acts_as_llm**
+#### ActiveRecord (ORM): acts_as_llm
 
 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.
+provides full control over tool execution. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -242,10 +342,10 @@ ctx.talk("Remember that my favorite language is Ruby")
 puts ctx.talk("What is my favorite language?").content
 ```
 
-**ActiveRecord (ORM): acts_as_agent**
+#### 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.
+manages tool execution for you. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -272,9 +372,9 @@ ticket = Ticket.create!(provider: "openai", model: "gpt-5.4-mini")
 puts ticket.talk("How do I rotate my API key?").content
 ```
 
-**Agent**
+#### 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.
+This example uses [`LLM::Agent`](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html) directly and lets the agent manage tool execution. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -291,10 +391,58 @@ agent = ShellAgent.new(llm)
 puts agent.talk("What time is it on this system?").content
 ```
 
+#### Skills
+
+This example uses [`LLM::Agent`](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html) with directory-backed skills so `SKILL.md` capabilities run through the normal tool path. If you have used skills in Claude or Codex, this is the same kind of building block. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+
+```ruby
+require "llm"
+
+class Agent < LLM::Agent
+  model "gpt-5.4-mini"
+  instructions "You are a concise release assistant."
+  skills "./skills/release", "./skills/review"
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+puts Agent.new(llm).talk("Use the review skill.").content
+```
+
+#### MCP
+
+This example uses [`LLM::MCP`](https://0x1eef.github.io/x/llm.rb/LLM/MCP.html) over HTTP so remote GitHub MCP tools run through the same `LLM::Context` tool path as local tools. See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+
+```ruby
+require "llm"
+require "net/http/persistent"
+
+llm = LLM.openai(key: ENV["KEY"])
+mcp = LLM::MCP.http(
+  url: "https://api.githubcopilot.com/mcp/",
+  headers: {"Authorization" => "Bearer #{ENV.fetch("GITHUB_PAT")}"}
+).persistent
+
+begin
+  mcp.start
+  ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
+  ctx.talk("Pull information about my GitHub account.")
+  ctx.talk(ctx.call(:functions)) while ctx.functions.any?
+ensure
+  mcp.stop
+end
+```
+
+## Screencast
+
+This screencast was built on an older version of llm.rb, but it still shows
+how capable the runtime can be in a real application:
+
+[![Watch the llm.rb screencast](https://img.youtube.com/vi/Jb7LNUYlCf4/maxresdefault.jpg)](https://www.youtube.com/watch?v=x1K4wMeO_QA)
+
 ## Resources
 
-- [deepdive](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) is the
-  examples guide.
+- [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) and
+  [deepdive (markdown)](resources/deepdive.md) are the examples guide.
 - [relay](https://github.com/llmrb/relay) shows a real application built on
   top of llm.rb.
 - [doc site](https://0x1eef.github.io/x/llm.rb?rebuild=1) has the API docs.

data/lib/llm/agent.rb

@@ -17,7 +17,8 @@ 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`, `:fiber`, or `:ractor`.
+  #   `:thread`, `:task`, `:fiber`, `:ractor`, or a list of queued task
+  #   types such as `[:thread, :ractor]`.
   #
   # @example
   #   class SystemAdmin < LLM::Agent
@@ -58,6 +59,17 @@ module LLM
       @tools = tools.flatten
     end
 
+    ##
+    # Set or get the default skills
+    # @param [Array<String>, nil] skills
+    #  One or more skill directories
+    # @return [Array<String>, nil]
+    #  Returns the current skills when no argument is provided
+    def self.skills(*skills)
+      return @skills if skills.empty?
+      @skills = skills.flatten
+    end
+
     ##
     # Set or get the default schema
     # @param [#to_json, nil] schema
@@ -83,7 +95,7 @@ module LLM
     ##
     # Set or get the tool execution concurrency.
     #
-    # @param [Symbol, nil] concurrency
+    # @param [Symbol, Array<Symbol>, nil] concurrency
     #  Controls how pending tool loops are executed:
     #  - `:call`: sequential calls
     #  - `:thread`: concurrent threads
@@ -91,7 +103,10 @@ module LLM
     #  - `: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]
+    #  - `[:thread, :ractor]`: the possible concurrency strategies to wait on, in the
+    #    given order. This is useful for mixed tool sets or when work may have been
+    #    spawned with more than one concurrency strategy.
+    # @return [Symbol, Array<Symbol>, nil]
     def self.concurrency(concurrency = nil)
       return @concurrency if concurrency.nil?
       @concurrency = concurrency
@@ -106,10 +121,11 @@ module LLM
     #  not only those listed here.
     # @option params [String] :model Defaults to the provider's default model
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    # @option params [Array<String>, nil] :skills Defaults to nil
     # @option params [#to_json, nil] :schema Defaults to nil
-    # @option params [Symbol, nil] :concurrency Defaults to the agent class concurrency
+    # @option params [Symbol, Array<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
+      defaults = {model: self.class.model, tools: self.class.tools, skills: self.class.skills, schema: self.class.schema}.compact
       @concurrency = params.delete(:concurrency) || self.class.concurrency
       @llm = llm
       @ctx = LLM::Context.new(llm, defaults.merge(params))
@@ -270,7 +286,7 @@ module LLM
 
     ##
     # Returns the configured tool execution concurrency.
-    # @return [Symbol, nil]
+    # @return [Symbol, Array<Symbol>, nil]
     def concurrency
       @concurrency
     end
@@ -348,8 +364,8 @@ module LLM
     def call_functions
       case concurrency || :call
       when :call then call(:functions)
-      when :thread, :task, :fiber, :ractor then wait(concurrency)
-      else raise ArgumentError, "Unknown concurrency: #{concurrency.inspect}. Expected :call, :thread, :task, :fiber, or :ractor"
+      when :thread, :task, :fiber, :ractor, Array then wait(concurrency)
+      else raise ArgumentError, "Unknown concurrency: #{concurrency.inspect}. Expected :call, :thread, :task, :fiber, :ractor, or an array of queued task types"
       end
     end
   end

data/lib/llm/context.rb

@@ -64,12 +64,14 @@ module LLM
     # @option params [Symbol] :mode Defaults to :completions
     # @option params [String] :model Defaults to the provider's default model
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    # @option params [Array<String>, nil] :skills Defaults to nil
     def initialize(llm, params = {})
       @llm = llm
       @mode = params.delete(:mode) || :completions
+      tools = [*params.delete(:tools), *load_skills(params.delete(:skills))]
       @params = {model: llm.default_model, schema: nil}.compact.merge!(params)
+      @params[:tools] = tools unless tools.empty?
       @messages = LLM::Buffer.new(llm)
-      @owner = Fiber.current
     end
 
     ##
@@ -86,6 +88,7 @@ module LLM
     #   puts res.messages[0].content
     def talk(prompt, params = {})
       return respond(prompt, params) if mode == :responses
+      @owner = Fiber.current
       params = params.merge(messages: @messages.to_a)
       params = @params.merge(params)
       bind!(params[:stream], params[:model])
@@ -112,6 +115,7 @@ module LLM
     #   res = ctx.respond("What is the capital of France?")
     #   puts res.output_text
     def respond(prompt, params = {})
+      @owner = Fiber.current
       params = @params.merge(params)
       bind!(params[:stream], params[:model])
       res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
@@ -182,8 +186,10 @@ module LLM
     # exposes a non-empty queue. Otherwise it falls back to waiting on
     # the context's pending functions directly.
     #
-    # @param [Symbol] strategy
-    #  The concurrency strategy to use
+    # @param [Symbol, Array<Symbol>] strategy
+    #  The concurrency strategy to use, or the possible concurrency strategies to
+    #  wait on. For example, `[:thread, :ractor]` waits for any queued thread or
+    #  ractor work, in that order.
     # @return [Array<LLM::Function::Return>]
     def wait(strategy)
       stream = @params[:stream]
@@ -342,6 +348,10 @@ module LLM
       stream.extra[:tracer] = tracer
       stream.extra[:model] = model
     end
+
+    def load_skills(skills)
+      [*skills].map { LLM::Skill.load(_1).to_tool(llm) }
+    end
   end
 
   # Backward-compatible alias

data/lib/llm/providers/google/response_adapter/completion.rb

@@ -9,6 +9,12 @@ module LLM::Google::ResponseAdapter
     end
     alias_method :choices, :messages
 
+    ##
+    # (see LLM::Contract::Completion#id)
+    def id
+      body["responseId"]
+    end
+
     ##
     # (see LLM::Contract::Completion#input_tokens)
     def input_tokens

data/lib/llm/sequel/agent.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module LLM::Sequel
+  ##
+  # Sequel plugin for persisting {LLM::Agent LLM::Agent} state.
+  #
+  # This wrapper reuses the same record-backed runtime surface as
+  # {LLM::Sequel::Plugin}, 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 Agent
+    EMPTY_HASH = LLM::Sequel::Plugin::EMPTY_HASH
+    DEFAULT_USAGE_COLUMNS = LLM::Sequel::Plugin::DEFAULT_USAGE_COLUMNS
+    DEFAULTS = LLM::Sequel::Plugin::DEFAULTS
+
+    def self.apply(model, **)
+      model.extend ClassMethods
+      model.include LLM::Sequel::Plugin::InstanceMethods
+      model.include InstanceMethods
+    end
+
+    def self.configure(model, options = EMPTY_HASH, &block)
+      options = DEFAULTS.merge(options)
+      usage_columns = DEFAULT_USAGE_COLUMNS.merge(options[:usage_columns] || EMPTY_HASH)
+      model.instance_variable_set(
+        :@llm_agent_options,
+        options.merge(usage_columns: usage_columns.freeze).freeze
+      )
+      model.instance_exec(&block) if block
+    end
+
+    module ClassMethods
+      def llm_plugin_options
+        @llm_agent_options || Agent::DEFAULTS
+      end
+
+      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 InstanceMethods
+      private
+
+      def ctx
+        @ctx ||= begin
+          options = self.class.llm_plugin_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
+
+      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
+      end
+
+      def resolve_options(option)
+        case option
+        when Proc, Symbol, Hash then resolve_option(option)
+        else Agent::EMPTY_HASH.dup
+        end
+      end
+    end
+  end
+end

data/lib/llm/skill.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Skill LLM::Skill} represents a directory-backed packaged capability.
+  # A skill directory must contain a `SKILL.md` file with YAML frontmatter.
+  # Skills can expose themselves as normal {LLM::Tool LLM::Tool} classes through
+  # {#to_tool}. This keeps skills on the same execution path as local tools.
+  class Skill
+    ##
+    # Load a skill from a directory.
+    # @param [String, Pathname] path
+    # @return [LLM::Skill]
+    def self.load(path)
+      new(path).tap(&:load!)
+    end
+
+    ##
+    # Returns the skill directory.
+    # @return [String]
+    attr_reader :path
+
+    ##
+    # Returns the skill name.
+    # @return [String]
+    attr_reader :name
+
+    ##
+    # Returns the skill description.
+    # @return [String]
+    attr_reader :description
+
+    ##
+    # Returns the skill instructions.
+    # @return [String]
+    attr_reader :instructions
+
+    ##
+    # Returns the skill frontmatter.
+    # @return [LLM::Object]
+    attr_reader :frontmatter
+
+    ##
+    # Returns the skill tools.
+    # @return [Array<Class<LLM::Tool>>]
+    attr_reader :tools
+
+    def initialize(path)
+      @path = path.to_s
+      @name = ::File.basename(@path)
+      @description = "Skill: #{@name}"
+      @instructions = ""
+      @frontmatter = LLM::Object.from({})
+      @tools = []
+    end
+
+    ##
+    # Load and parse the skill.
+    # @return [LLM::Skill]
+    def load!
+      path = ::File.join(@path, "SKILL.md")
+      parse(::File.read(path))
+      self
+    end
+
+    ##
+    # Execute the skill by wrapping it in a small agent with the skill
+    # instructions. The provider is bound explicitly by the caller.
+    # @param [LLM::Provider] llm
+    # @param [Hash] input
+    # @return [Hash]
+    def call(llm, **)
+      instructions = self.instructions
+      tools = self.tools
+      agent = Class.new(LLM::Agent) do
+        instructions instructions
+        tools(*tools)
+      end.new(llm)
+      res = agent.talk(instructions)
+      {content: res.content}
+    end
+
+    ##
+    # Expose the skill as a normal LLM::Tool. The provider is bound explicitly
+    # when the tool class is built.
+    # @param [LLM::Provider] llm
+    # @return [Class<LLM::Tool>]
+    def to_tool(llm)
+      skill = self
+      Class.new(LLM::Tool) do
+        name skill.name
+        description skill.description
+
+        define_method(:call) do |**input|
+          skill.call(llm, **input)
+        end
+      end
+    end
+
+    private
+
+    def parse(content)
+      match = content.match(/\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m)
+      unless match
+        @instructions = content
+        return
+      end
+      require "yaml" unless defined?(::YAML)
+      @frontmatter = LLM::Object.from(YAML.safe_load(match[1]) || {})
+      @name = @frontmatter.name || @name
+      @description = @frontmatter.description || @description
+      @tools = [*@frontmatter.tools].map { LLM::Tool.find_by_name!(_1) }
+      @instructions = match[2]
+    end
+  end
+end

data/lib/llm/stream/queue.rb

@@ -33,27 +33,57 @@ class LLM::Stream
 
     ##
     # Waits for queued work to finish and returns function results.
-    # @param [Symbol] strategy
-    #   Controls concurrency strategy:
+    # @param [Symbol, Array<Symbol>] strategy
+    #   Controls concurrency strategy, or lists the possible concurrency strategies
+    #   to wait on:
     #   - `: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)
+    #   - `[:thread, :ractor]`: Wait for any queued thread or ractor work, in the
+    #     given order. This is useful when different tools were spawned with
+    #     different concurrency strategies.
     # @return [Array<LLM::Function::Return>]
     def wait(strategy)
       returns, tasks = @items.shift(@items.length).partition { LLM::Function::Return === _1 }
-      results = case strategy
+      results = wait_tasks(tasks, strategy)
+      returns.concat fire_hooks(tasks, results)
+    end
+    alias_method :value, :wait
+
+    private
+
+    def wait_tasks(tasks, strategy)
+      strategies = Array(strategy)
+      return wait_group(tasks, strategies.first) unless strategies.length > 1
+      grouped = strategies.to_h { [_1, []] }
+      tasks.each do |task|
+        grouped[task_strategy(task)] << task
+      end
+      strategies.flat_map do |name|
+        selected = grouped.fetch(name)
+        selected.empty? ? [] : wait_group(selected, name)
+      end
+    end
+
+    def wait_group(tasks, strategy)
+      case strategy
       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
       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
-    alias_method :value, :wait
 
-    private
+    def task_strategy(task)
+      case task.task
+      when Thread then :thread
+      when Fiber then :fiber
+      when LLM::Function::Ractor::Task then :ractor
+      else :task
+      end
+    end
 
     def fire_hooks(tasks, results)
       results.each_with_index do |result, idx|

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -29,6 +29,7 @@ module LLM
   require_relative "llm/eventstream"
   require_relative "llm/eventhandler"
   require_relative "llm/tool"
+  require_relative "llm/skill"
   require_relative "llm/server_tool"
   require_relative "llm/mcp"
 

data/lib/sequel/plugins/agent.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Sequel
+  module Plugins
+    require "llm/sequel/agent"
+    Agent = LLM::Sequel::Agent
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.20.1
+  version: 4.21.0
 platform: ruby
 authors:
 - Antar Azri
@@ -371,9 +371,11 @@ files:
 - lib/llm/schema/parser.rb
 - lib/llm/schema/string.rb
 - lib/llm/schema/version.rb
+- lib/llm/sequel/agent.rb
 - lib/llm/sequel/plugin.rb
 - lib/llm/server_tool.rb
 - lib/llm/session.rb
+- lib/llm/skill.rb
 - lib/llm/stream.rb
 - lib/llm/stream/queue.rb
 - lib/llm/tool.rb
@@ -386,6 +388,7 @@ files:
 - lib/llm/usage.rb
 - lib/llm/utils.rb
 - lib/llm/version.rb
+- lib/sequel/plugins/agent.rb
 - lib/sequel/plugins/llm.rb
 - llm.gemspec
 homepage: https://github.com/llmrb/llm.rb