llm.rb 13.0.0 → 14.0.0

data/resources/deepdive/everything_else/object.md

@@ -0,0 +1,108 @@
+
+## LLM::Object
+
+### Introduction
+
+#### Overview
+
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
+is the hash-like object that llm.rb uses everywhere structured data
+flows through the runtime. Response bodies, tool arguments, schema
+results, usage and cost data, and function parameters all come back
+as [`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
+instances. It is similar in spirit to OpenStruct,
+and it was introduced after OpenStruct became a bundled gem rather
+than a default gem in Ruby 3.5.
+
+#### How it works
+
+When you want to read a value from an
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html),
+use either method-style or bracket access. Keys are indifferent, so
+strings and symbols work interchangeably:
+
+```ruby
+obj = LLM::Object.from(city: "Paris", temperature: 15.0)
+
+obj.city          # => "Paris"
+obj["city"]       # => "Paris"
+obj[:city]        # => "Paris"
+obj[:temperature] # => 15.0
+```
+
+Nested hashes and arrays are converted recursively, so deep chains
+read naturally:
+
+```ruby
+obj = LLM::Object.from(person: {name: "John"})
+obj.person.name   # => "John"
+obj.person.class  # => LLM::Object
+```
+
+#### Why would I use it?
+
+Most of the time you do not construct
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
+instances yourself. They come back from `talk`, `ask`, `embed`, and
+every other call that returns structured data. Knowing how they
+behave lets you read response fields, pass tool arguments, and
+inspect usage without reaching for `to_h` on every line.
+
+#### Notes
+
+An
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
+is enumerable and supports the usual Hash operations: `keys`,
+`values`, `key?`, `fetch`, `dig`, `slice`, `merge`, `merge!`,
+`delete`, `size`, and `empty?`. Use `to_h` for a plain Hash and
+`to_hash` for one with symbol keys. A missing key returns `nil`
+rather than raising. Because it subclasses `BasicObject`, `to_json`
+is defined explicitly and serializes through the configured JSON
+adapter via
+[`LLM.json.dump`](https://r.uby.dev/api-docs/llm.rb/LLM.html#json-class_method).
+
+### Reading and writing
+
+#### Overview
+
+Beyond simple reads,
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
+supports assignment, mutation, and iteration, so you can treat it
+like a Hash in place.
+
+#### How it works
+
+Assign values with method or bracket syntax, mutate in place, and
+iterate like a Hash:
+
+```ruby
+obj = LLM::Object.from({})
+
+obj.city = "Paris"       # method-style write
+obj["country"] = "France"
+
+obj.key?(:city)          # => true
+obj.keys                 # => ["city", "country"]
+obj.merge!(population: 2_100_000)
+
+obj.each { |key, value| puts "#{key}: #{value}" }
+obj.transform_values!(&:upcase) if obj.any?
+```
+
+#### Why would I use it?
+
+Tool implementations receive their arguments as an
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
+and often build a result Hash from them. Merging defaults, deleting
+optional keys, and transforming values in place keeps that code
+concise without converting back and forth between Hash and
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html).
+
+#### Notes
+
+`merge` returns a new
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html);
+`merge!` mutates in place.
+Assignment always stores the key as a string internally, which is
+why string and symbol lookups both work. Equality compares against
+anything that responds to `to_h`.

data/resources/deepdive/everything_else/ocr.md

@@ -0,0 +1,48 @@
+
+## OCR
+
+### Introduction
+
+#### Overview
+
+OCR pulls text out of images and PDFs so you can search, index,
+or process scanned content. Mistral is the only provider with a
+dedicated OCR endpoint, and it accepts both image URLs and
+document URLs.
+
+#### How it works
+
+Mistral is the only provider with a dedicated OCR endpoint. The
+[`LLM::Provider#ocr`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#ocr)
+method accepts an `image_url:` or `document_url:` parameter.
+Document URLs can point to PDFs.
+
+```ruby
+require "llm"
+
+llm = LLM.mistral(key: ENV["KEY"])
+
+# Extract text from an image
+res = llm.ocr(image_url: "https://example.com/photo.png")
+res.pages.each { |page| puts page.markdown }
+
+# Extract text from a PDF
+res = llm.ocr(document_url: "https://example.com/report.pdf")
+res.pages.each { |page| puts page.markdown }
+```
+
+#### Why would I use it?
+
+OCR extracts text from scanned documents and images. The result
+feeds into search indexes, extraction pipelines that pull out dates
+and amounts, or archives so scanned contracts become searchable
+records. PDFs and images both work, and the response is structured
+per page with markdown.
+
+#### Notes
+
+Only Mistral currently supports OCR through the llm.rb runtime.
+The response exposes pages through
+[`LLM::OCR::Response#pages`](https://r.uby.dev/api-docs/llm.rb/LLM/OCR/Response.html#pages),
+where each page
+has a `markdown` field containing the extracted text.

data/resources/deepdive/fundamentals/agents.md

@@ -0,0 +1,202 @@
+
+## Agents
+### Introduction
+
+#### Overview
+
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+is the recommended entry point for most use-cases. It provides a
+class-level DSL for defining reusable, preconfigured assistants
+with defaults for model, tools, schema, and instructions. Under
+the hood it delegates to
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html),
+so it has the same runtime surface: message history, streaming,
+serialization, compaction, and concurrency.
+
+#### How it works
+
+An agent holds a conversation with a model. You send input with
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk),
+the model responds, and if it requests tools the agent
+executes them automatically and feeds the results back. It enables
+[a loop guard by default](https://r.uby.dev/llm/deepdive/advanced/guard)
+that detects repeated tool-call patterns
+and blocks stuck execution. The tool loop can also be bounded with
+[`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
+(see the Tool budget section). Instructions are injected once
+unless a system message is already present.
+
+#### Why would I use it?
+
+Agents manage the tool loop for you. They guard against infinite
+loops, keep conversation state across turns, and let you define
+reusable configurations at the class level. If you need manual
+control over the tool loop, use
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+directly instead.
+
+#### Notes
+
+Agents support the same concurrency strategies, compaction,
+cancellation, and serialization as contexts. The trade-off between
+a subclass and a direct instance is only in how the agent is
+organized, not in what it can do. Tool loop execution can be
+configured with `concurrency: :sequential`, `:thread`, `:async`,
+`:fiber`, `:fork`, or `:ractor`.
+
+### Class-based
+
+#### Overview
+
+A subclass of
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+gives you a reusable agent with its own behavior. You define the model, tools, and other
+attributes at the class level, and each instance picks them up
+as defaults. Attributes can be overridden per-instance, and they
+can be plain values, blocks, or Symbols that resolve to methods.
+The class becomes a self-contained worker that you can instantiate
+and talk to from anywhere.
+
+#### How it works
+
+A subclass declares its defaults with
+[`LLM::Agent.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#set-class_method).
+Each key is a
+class-level accessor: `name`, `description`, `model`, `tools`,
+`skills`, `instructions`, `stream`, `tracer`, `concurrency`,
+`schema`, `confirm`, `path`, `tool_budget`.
+Keyword arguments in the constructor override these defaults.
+
+```ruby
+class Agent < LLM::Agent
+  set model: "deepseek-v4-pro",
+      description: "system administration agent",
+      tools: [Shell]
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+agent = Agent.new(llm)
+agent.talk "Run 'date'"
+```
+
+#### Why would I use it?
+
+A subclass is useful when multiple parts of an application need to
+call the same agent. The configuration and any helper methods live in one place. Define a
+`research!` method that kicks off the agent's work. The subclass
+becomes a self-contained worker.
+
+#### Notes
+
+Attributes passed to
+[`LLM::Agent.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#set-class_method)
+can be plain values, blocks, or
+Symbols. A Symbol is evaluated as an instance method on the
+subclass, so `tracer: :set_tracer` calls `set_tracer` on the
+instance. A block like `stream: -> { $stdout }` is evaluated
+when the attribute is first accessed.
+
+Set `path:` on a subclass or instance for automatic filesystem
+persistence; the agent restores conversation history from the
+file on startup and saves it back after every turn with no
+manual
+[`LLM::Agent#save`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#save)/
+[`LLM::Agent#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#restore)
+calls. See the
+[database deepdive](../fundamentals/database.md) for details.
+
+### Object-based
+
+#### Overview
+
+An
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+instance is the simplest way to get started. You pass a provider and any configuration as keyword
+arguments, and the agent runs the tool loop and manages state
+just like a subclass would. This is the right choice when you
+are prototyping, running a one-off task, or when the agent's
+configuration is determined at runtime.
+
+#### How it works
+
+A direct instance takes the same attributes as keyword arguments
+to
+[`LLM::Agent.new`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#initialize-instance_method).
+The first argument is always the provider.
+Everything else is optional. The agent runs the tool loop
+and manages state under the hood through a
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html).
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, stream: $stdout)
+agent.talk "Hello world"
+```
+
+#### Why would I use it?
+
+A direct instance is the right choice for quick experiments, one-shot
+tasks, or when defining a class would be overkill. It is also
+the right choice when the agent's configuration is determined at
+runtime and a class hierarchy adds unnecessary complexity.
+
+#### Notes
+
+Direct instances accept all the same options as subclasses. The
+difference is only in how the agent is organized, not in what it
+can do. Under the hood,
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+creates a
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+that manages the message history.
+
+### Tool budget
+
+#### Overview
+
+[`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
+caps the number of tool calls allowed in a single turn. Once the
+budget is spent, the agent sends an in-band advisory message back
+through the model instead of running more tools. By default no
+budget is set, so the feature is disabled.
+
+#### How it works
+
+When you want to bound how many tools an agent can call in one
+turn, set the budget with
+[`LLM::Agent.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#set-class_method).
+The budget can be a plain number or a block evaluated against the
+agent instance. Once the agent has made the budgeted number of tool
+calls, it stops and returns an in-band advisory message describing
+the spent budget. A model will usually change course afterwards:
+
+```ruby
+class Researcher < LLM::Agent
+  set model: "deepseek-v4-pro",
+      tools: [FetchNews, FetchStocks],
+      tool_budget: 5
+end
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = Researcher.new(llm)
+agent.talk "Research the market"
+```
+
+#### Why would I use it?
+
+A tool budget prevents runaway tool loops. A misbehaving model can
+otherwise keep calling tools, spending tokens on every round trip.
+Capping the budget turns that into a bounded conversation: after
+the cap, the model is told it has run out of tool calls and must
+respond from what it has.
+
+#### Notes
+
+The budget is disabled by default (`nil`). Set it on a subclass
+with the `tool_budget` DSL, through
+[`LLM::Agent.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#set-class_method)
+with `tool_budget:`, or per-instance with the `tool_budget:` keyword
+argument to
+[`LLM::Agent.new`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#initialize-instance_method).
+This replaces the previous `tool_attempts` parameter, which is no
+longer used.

data/resources/deepdive/fundamentals/builtin_tools.md

@@ -0,0 +1,191 @@
+
+## Built-in tools
+
+### Introduction
+
+#### Overview
+
+llm.rb ships with twelve ready-made tools that cover the operations
+a coding or system agent needs most: filesystem work, search, and
+shell commands. Each tool is a subclass of
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+with a name, description, and typed parameters, exactly like a tool
+you would write yourself. Load the whole catalog with
+`require "llm/tools"`.
+
+#### How it works
+
+When you want to attach every built-in tool to an agent, require
+the catalog and pass the full set of subclasses as the `tools:`
+option. The runtime registers each tool's schema and lets the model
+decide when to call it.
+
+```ruby
+require "llm"
+require "llm/tools"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, tools: LLM::Tool.subclasses)
+agent.talk "List the files in this repository"
+```
+
+#### Why would I use it?
+
+The built-in tools cover the operations a coding or system agent
+needs most, so you rarely need to write your own. They also handle
+edge cases correctly: subprocesses get timeouts, interrupts kill
+the child process, and failed calls return structured errors
+instead of crashing the conversation.
+
+#### Notes
+
+The tools that spawn subprocesses use the optional `test-cmd.rb`
+gem for process management and interrupt handling. The gem is
+required only when those tools load. Every tool returns a Hash with
+an `ok:` key that tells the model whether the call succeeded.
+
+### Filesystem
+
+#### Overview
+
+The filesystem tools let the model read, write, and edit files,
+list and create directories, and move around the working tree.
+The most distinctive is
+[`LLM::Tool::EditFile`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/EditFile.html),
+which replaces an exact snippet and verifies the match count:
+
+```ruby
+LLM::Tool::EditFile.new.call(
+  path: "config.yml",
+  before: "port: 3000",
+  after:  "port: 4000"
+)
+# => {ok: true, replaced: 1}
+```
+
+#### How it works
+
+Each filesystem tool takes a path and returns a result Hash. The
+`read-file` tool reads a whole file by default and accepts `start:`
+and `stop:` to read a range of lines instead. The `edit-file` tool
+counts occurrences of `before` and raises unless the count matches
+`expected_count`, which defaults to 1.
+
+| Tool | Name | Parameters | Purpose |
+|---|---|---|---|
+| [`LLM::Tool::Pwd`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Pwd.html) | `pwd` | none | Report the current working directory |
+| [`LLM::Tool::Ls`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Ls.html) | `ls` | `path`, `glob` | List files and directories, optionally matching a glob |
+| [`LLM::Tool::Chdir`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Chdir.html) | `chdir` | `path` | Change the current working directory |
+| [`LLM::Tool::Mkdir`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Mkdir.html) | `mkdir` | `path` | Create a tree of directories |
+| [`LLM::Tool::ReadFile`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/ReadFile.html) | `read-file` | `path`, `start`, `stop` | Read a file, optionally a range of lines |
+| [`LLM::Tool::WriteFile`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/WriteFile.html) | `write-file` | `path`, `content` | Write a string to a file |
+| [`LLM::Tool::EditFile`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/EditFile.html) | `edit-file` | `path`, `before`, `after`, `expected_count` | Replace an exact snippet in a file |
+
+#### Why would I use it?
+
+Reading source files to answer questions, writing new files, and
+editing a snippet in place are the bread and butter of a coding
+agent. The filesystem tools give the model all of it without you
+writing a single tool.
+
+#### Notes
+
+The `chdir` tool changes the working directory for the whole
+process, so subsequent file operations see the new directory. The
+`mkdir` tool creates parent directories, like `mkdir -p`. The `ls`
+tool raises when the path does not exist.
+
+### Search
+
+#### Overview
+
+The search tools find things without reading the whole tree: `rg`
+searches file contents, and `which` locates an executable on the
+PATH. When a method name or a term is needed, the model searches
+for it instead of guessing.
+
+```ruby
+LLM::Tool::Rg.new.call(patterns: ["def talk"], path: "lib")
+# => {ok: true, stdout: "lib/llm/context.rb:42:def talk", stderr: ""}
+```
+
+#### How it works
+
+When you want to search for one or more patterns, call the
+[`LLM::Tool::Rg#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html#call-instance_method)
+method with an Array of patterns, an optional `path:`, and a
+`timeout:` in seconds. When you want to check whether a command is
+installed, call the
+[`LLM::Tool::Which#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Which.html#call-instance_method)
+method with a `name:`.
+
+| Tool | Name | Parameters | Purpose |
+|---|---|---|---|
+| [`LLM::Tool::Rg`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html) | `rg` | `patterns`, `path`, `timeout` | Recursively search for lines matching patterns |
+| [`LLM::Tool::Which`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Which.html) | `which` | `name` | Locate an executable on the system PATH |
+
+#### Why would I use it?
+
+Search is how the model finds something without scanning files one
+by one. Asked where a method is defined, the agent searches for it.
+Before running a command, it checks with `which` that the binary
+exists, and falls back to another approach when it does not.
+
+#### Notes
+
+The `rg` tool runs the ripgrep binary, so `rg` must be installed
+and on the PATH. It refuses to search from the filesystem root and
+rejects the pattern `.` to keep the model from dumping the entire
+tree in one call. The `which` tool is pure Ruby: it scans the PATH
+in order and returns the first directory that contains an
+executable with the given name. When no match is found it returns
+`{ok: false, path: nil}`.
+
+### Shell
+
+#### Overview
+
+The shell tools run real subprocesses: arbitrary commands through
+`shell`, Ruby code through `ruby`, and a fixed set of git actions
+through `git`. All three accept a `timeout:` and kill the child
+process when the model interrupts the turn.
+
+```ruby
+LLM::Tool::Shell.new.call(
+  name: "bundle",
+  arguments: ["exec", "rspec", "spec/llm"],
+  timeout: 30
+)
+```
+
+#### How it works
+
+When you want to run a command and capture its output, call the
+[`LLM::Tool::Shell#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Shell.html#call-instance_method)
+method with a `name:` and optional `arguments:`. The `git` tool
+accepts an `action:` from a fixed set, and the `ruby` tool runs its
+code in a fresh process.
+
+| Tool | Name | Parameters | Purpose |
+|---|---|---|---|
+| [`LLM::Tool::Shell`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Shell.html) | `shell` | `name`, `arguments`, `timeout` | Run a shell command |
+| [`LLM::Tool::Git`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html) | `git` | `action`, `arguments`, `timeout` | Run a fixed set of git actions |
+| [`LLM::Tool::Ruby`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Ruby.html) | `ruby` | `code`, `timeout` | Run a string of Ruby code |
+
+#### Why would I use it?
+
+Running tests, inspecting git history, and executing a snippet of
+Ruby are things a coding agent needs to do. The shell tools make
+those actions first-class, and the timeout keeps a hanging command
+from stalling the conversation.
+
+#### Notes
+
+[`LLM::Tool::Shell`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Shell.html)
+can be dangerous given a low-quality model. Gate it behind
+[`LLM::Agent#confirm`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#confirm)
+or manage the tool loop manually through
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html).
+On interrupt, the running child process is killed. The `ruby` tool
+uses the same Ruby that launched llm.rb. The `git` tool wraps the
+actions `log`, `diff`, `commit`, `checkout`, `branch`, and `show`.

data/resources/deepdive/fundamentals/concurrency.md

@@ -0,0 +1,104 @@
+
+## Concurrency
+
+### Introduction
+
+#### Overview
+
+llm.rb supports six concurrency strategies for tool execution:
+`:sequential`, `:thread`, `:fiber`, `:async`, `:fork`, and
+`:ractor`. Each implements the same interface
+([`LLM::Function::Task#spawn`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#spawn),
+[`LLM::Function::Task#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#wait),
+[`LLM::Function::Task#alive?`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#alive?),
+[`LLM::Function::Task#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#interrupt!)),
+so the caller never has to care which
+strategy is behind a given task.
+
+#### How it works
+
+Each strategy creates a task object that wraps a function call.
+[`LLM::Function::Task#spawn`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#spawn)
+starts execution,
+[`LLM::Function::Task#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#wait)
+collects the result,
+[`LLM::Function::Task#alive?`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#alive?)
+checks whether the task is still running, and
+[`LLM::Function::Task#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#interrupt!)
+signals the task to stop.
+
+Interruption is reliable across all six.
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+reaches the tool regardless of whether it runs on a thread, fiber, process,
+or ractor.
+
+A tool can rescue
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+and return a structured error to cancel the tool call, or it can
+re-raise to cancel the turn entirely. When you re-raise
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+or leave it unrescued the exception is raised on the caller's thread
+and that effectively terminates the turn.
+
+The main benefit of rescuing yourself is to let the tool clean up
+and free lingering resources, but you usually want to re-raise so
+the cancel request ends the turn. Otherwise the tool call is
+intercepted but the turn continues.
+
+```ruby
+##
+# At a high-level
+agent = LLM::Agent.new(llm, concurrency: :fork, tools: [...])
+agent.talk "Run the tools"
+
+##
+# At a low-level
+fn = FetchStocks.function
+fn.task(:thread).wait
+```
+
+#### Why would I use it?
+
+Different tools have different execution requirements. IO-bound
+tools benefit from thread or async concurrency. CPU-bound tools
+benefit from ractors or forks. Tools that might crash the process
+should run in a fork for isolation.
+
+The common interface means you can change strategies without
+changing your tool code.
+
+#### Notes
+
+**sequential**: Tools run one at a time on the calling thread. No
+overhead. Best for simple agents or when tool order matters.
+
+**thread**: Each tool runs in its own Thread. Releases the GVL
+during blocking IO. Best for IO-bound tools like HTTP calls and
+database queries.
+
+**fiber**: Each tool runs in a scheduler-backed Fiber. Requires
+`Fiber.scheduler`. Best for IO-bound tools inside an async
+framework. Much lighter than threads.
+
+**async**: Each tool runs as an `Async::Task` inside a managed
+background reactor. Best for IO-bound tools when you want Async's
+structured concurrency model without running your whole application
+inside a reactor. Requires the `async` gem.
+
+**fork**: Each tool runs in a forked child process. True parallelism
+and process isolation. Best for shell commands, native extensions,
+or anything you do not want touching the parent's memory. Requires
+the `xchan` gem.
+
+**ractor**: Each class-based tool runs in a Ruby Ractor. True
+parallelism without the overhead of forking full processes. Only
+class-based tools are supported. Arguments must be ractor-shareable.
+
+| Strategy | Backing | Parallel? | Isolation? | Requires |
+|---|---|---|---|---|
+| `:sequential` | direct call | No | No | None |
+| `:thread` | `Thread` | IO only (GVL) | No | None |
+| `:fiber` | `Fiber.schedule` | Cooperative | No | `Fiber.scheduler` |
+| `:async` | `Async::Reactor` | Cooperative | No | `async` gem |
+| `:fork` | `Kernel.fork` | Yes (process) | Yes (memory) | `xchan` gem |
+| `:ractor` | `Ractor` | Yes (CPU) | Limited | None |