llm.rb 12.5.1 → 13.0.0

data/resources/deepdive.md

@@ -43,6 +43,12 @@ features that didn't make it into the homepage documentation.
 
 - [LLM::Tool](#llmtool)
 - [Errors](#errors)
+- [Confirmation](#confirmation)
+- [Manual tool loop](#manual-tool-loop)
+  - [Executing](#executing)
+  - [Per-tool confirmation](#per-tool-confirmation)
+  - [Full loop](#full-loop)
+  - [Trade-offs](#trade-offs)
 </details>
 
 <details>
@@ -67,10 +73,34 @@ features that didn't make it into the homepage documentation.
 - [LLM::Stream](#llmstream)
 </details>
 
+<details>
+<summary>Concurrency</summary>
+
+- [Overview](#overview)
+- [sequential](#sequential)
+- [thread](#thread)
+- [fiber](#fiber)
+- [async](#async)
+- [fork](#fork)
+- [ractor](#ractor)
+- [Quick reference](#quick-reference)
+</details>
+
+<details>
+<summary>Context Compaction</summary>
+
+- [Configuration](#configuration)
+- [Standalone usage](#standalone-usage)
+- [Strategies](#strategies)
+- [Manual compaction](#manual-compaction)
+- [Lifecycle callbacks](#lifecycle-callbacks)
+</details>
+
 <details>
 <summary>Cancellation</summary>
 
 - [Cancel a request](#cancel-a-request)
+- [Tool interrupts](#tool-interrupts)
 </details>
 
 <details>
@@ -92,7 +122,7 @@ features that didn't make it into the homepage documentation.
 <summary>REPL</summary>
 
 - [LLM::Agent](#llmagent)
-- [State](#state)
+- [Persistence](#persistence)
 - [Tools](#tools)
 - [Skills](#skills-1)
 - [Tracer](#tracer-1)
@@ -133,6 +163,12 @@ features that didn't make it into the homepage documentation.
 - [translation](#translation)
 </details>
 
+<details>
+<summary>OCR</summary>
+
+- [Mistral](#mistral)
+</details>
+
 **Protocols**
 
 <details>
@@ -157,7 +193,7 @@ class, and it is built on top of
 [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) -
 the heart of the runtime. An agent manages the tool loop automatically,
 implements a tool loop guard for misbehaving models, and
-it can use five different concurrency strategies to execute
+it can use six different concurrency strategies to execute
 tools.
 
 An agent can be a subclass of
@@ -188,11 +224,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"
@@ -248,6 +284,14 @@ The model then proceeds to process the tool's response,
 and then might generate its own response, or perhaps call
 another tool.
 
+There is exactly one rule: a tool call must always produce
+a tool response. If a tool raises an exception, the runtime
+rescues it and returns a structured error to the model
+instead. The conversation never enters an invalid state
+because of a crashed tool &mdash; the model always has
+something to work with. This is by design. Keeping the
+tool loop alive is the highest priority.
+
 #### LLM::Tool
 
 A tool can be defined by subclassing
@@ -262,7 +306,7 @@ serve a user's query.
 require "llm"
 require "shellwords"
 
-class Shell < LLM::Shell
+class Shell < LLM::Tool
   name "shell"
   description "execute a shell command"
   parameter :name, String, "the command's name"
@@ -270,8 +314,8 @@ class Shell < LLM::Shell
   required %i[name]
   defaults arguments: []
 
-  def call(name:, arguments:)
-    out = `#{name.shellscape} #{arguments.map(&:shellescape).join(" ")}`
+  def call(name:, arguments: [])
+    out = `#{name.shellescape} #{arguments.map(&:shellescape).join(" ")}`
     {ok: $?.success?, out:}
   end
 end
@@ -283,15 +327,9 @@ agent.talk "What files are in the current working directory?"
 
 #### Errors
 
-Exceptions that might be raised by a tool are automatically
-rescued and returned to the model as a structured error.
-Otherwise &ndash; the conversation's history could be left
-in an invalid state.
-
-That's because a tool call must complete with a tool response,
-that's the only valid response a model expects, so even in the
-case of an error, something must be returned that communicates
-what happened.
+Exceptions raised by a tool are automatically rescued and
+returned to the model as a structured error. The model sees
+something like this:
 
 ```ruby
 class Error < LLM::Tool
@@ -307,6 +345,196 @@ class Error < LLM::Tool
 end
 ```
 
+The runtime wraps the exception into `{error: true, kind: "RuntimeError",
+message: "boom"}` and returns it to the model as the tool response. From
+the model's perspective the tool completed &mdash; it just completed with
+an error. The model can read the error, decide what went wrong, and try
+something else. The conversation stays valid.
+
+You can also handle errors yourself inside `call`. Rescue the exception
+and return whatever shape makes sense for your tool:
+
+```ruby
+class Shell < LLM::Tool
+  name "shell"
+  description "execute a shell command"
+
+  def call(name:, arguments: [])
+    out = `#{name} #{arguments.join(" ")}`
+    {ok: $?.success?, out:}
+  rescue Errno::ENOENT
+    {ok: false, error: "command not found: #{name}"}
+  end
+end
+```
+
+The model receives `{ok: false, error: "command not found: ls"}` and can
+react accordingly &mdash; maybe it corrects the command name and tries
+again. This is often better than letting the runtime's generic error
+wrapper speak for you, because you can provide domain-specific detail
+that helps the model recover.
+
+The principle is the same either way: **return something**. A tool call
+must complete with a tool response. If you don't return a value, and you
+don't raise, the runtime has nothing to send back and the conversation
+is stuck. As long as you return a Hash (or anything the model can
+interpret), the tool loop continues.
+
+#### Confirmation
+
+Tools that perform destructive actions can be gated behind
+explicit confirmation. List their names in
+[`LLM::Agent.confirm`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#confirm-class_method)
+to block execution until you override `on_tool_confirmation`.
+
+The default handler cancels the tool. Override it per-agent to
+prompt the user, log the decision, or auto-approve certain tools.
+
+```ruby
+class AdminAgent < LLM::Agent
+  set confirm: %w[delete destroy shutdown]
+
+  def on_tool_confirmation(fn, strategy)
+    print "Run #{fn.name} with #{fn.arguments}? [y/N] "
+    $stdin.gets&.match?(/\Ay\z/i) ? wait(strategy) : fn.cancel
+  end
+end
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = AdminAgent.new(llm)
+```
+
+Confirmation also accepts a Symbol for lazy resolution, which
+allows the list of confirmed tools to change per-instance:
+
+```ruby
+class AdaptiveAgent < LLM::Agent
+  set confirm: :tools_that_need_confirmation
+
+  def tools_that_need_confirmation
+    some_condition ? %w[delete destroy] : %w[delete]
+  end
+end
+```
+
+## Manual tool loop
+
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) manages
+the tool loop automatically — it calls the model, checks for tool calls,
+executes them, sends results back, and repeats until the model responds
+with text. You can bypass this and drive the loop yourself for finer
+control.
+
+Start with a bare [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+(no agent):
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+```
+
+Send a message and check whether the model wants to call tools:
+
+```ruby
+res = ctx.talk "What's the weather in Tokyo?"
+
+if ctx.pending_functions?
+  puts "Model requested #{ctx.pending_functions.size} tool(s)"
+else
+  puts res.text
+end
+```
+
+### Executing
+
+When the model asks to call tools, call `ctx.wait(:strategy)` to run
+them. `ctx.wait` picks up pending functions, spawns them, waits for
+results, and records them back in the context. Every strategy is
+supported: `:sequential`, `:thread`, `:fiber`, `:async`, `:fork`,
+and `:ractor`.
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+
+ctx.talk("What's the weather in Tokyo?")
+ctx.talk ctx.wait(:thread)
+```
+
+### Per-tool confirmation
+
+Because `pending_functions` returns a regular array, you can inspect
+each function before execution. Call `ctx.wait(:thread)` to execute
+all pending tools — but you can also selectively exclude functions or
+run individual ones through `fn.task(:thread).wait` for ad-hoc execution
+that bypasses guards and streaming hooks:
+
+```ruby
+results = ctx.pending_functions.map do |fn|
+  print "Run #{fn.name} with #{fn.arguments}? [y/N] "
+  if $stdin.gets&.match?(/\Ay\z/i)
+    fn.task(:thread).wait
+  else
+    fn.cancel(reason: "user declined")
+  end
+end
+ctx.talk(results)
+```
+
+This pattern is what
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)'s
+built-in confirmation feature uses internally, but doing it manually
+gives you full control — route the decision through a web socket, a
+background job, or a multi-user approval flow.
+
+### Full loop
+
+A complete manual tool loop looks like this:
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+res = nil
+
+loop do
+  res = ctx.talk("What's the weather in Tokyo?")
+  break unless ctx.pending_functions?
+
+  results = ctx.wait(:thread)
+  ctx.talk(results)
+end
+
+puts res.content
+```
+
+The loop exits when the model responds with text rather than tool
+calls. You can extend it with timeouts, user confirmation gates, or
+custom error handling for each tool.
+
+### Trade-offs
+
+Manual control is more code but gives you:
+
+- **Arbitrary pre-execution checks** — inspect, rewrite, or skip tool
+  calls before they run.
+- **Custom confirmation flows** — async approval over HTTP, Slack,
+  or email instead of the built-in terminal prompt.
+- **Different strategies per tool** — run one tool on a thread and
+  another in a forked process within the same turn.
+- **Fine-grained error recovery** — rescue per-tool failures and
+  decide which results to feed back.
+
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) handles
+all of this automatically and is the right choice for most applications.
+Drop down to the manual loop when you need control that the agent
+abstraction doesn't expose.
+
 ## Skills
 
 The skill concept is borrowed from tools like Claude and
@@ -571,11 +799,11 @@ class Stream < LLM::Stream
   def on_tool_return(tool, result)
   end
 
-  def on_compaction(ctx, compactor)
+  def on_compaction(compactor)
     # this callback is called *before* a compact happens
   end
 
-  def on_compaction_finish(ctx, compactor)
+  def on_compaction_finish(compactor)
     # this callback is called *after* a compact happens
   end
 end
@@ -583,6 +811,244 @@ end
 
 [Back to top](#table-of-contents)
 
+## Concurrency
+
+llm.rb supports six concurrency strategies for tool execution &ndash;
+`:sequential`, `:thread`, `:fiber`, `:async`, `:fork`, and `:ractor`.
+Each one implements the same interface &mdash; `spawn`, `wait`, `alive?`,
+`interrupt!` &mdash; so the caller never has to care which strategy is
+behind a given task.
+
+Choose a strategy per-agent or per-call:
+
+```ruby
+## Per-agent — every tool loop uses :fork
+agent = LLM::Agent.new(llm, concurrency: :fork, tools: [...])
+
+## Per-call — run a single tool on a thread
+fn = FetchStocks.function
+fn.task(:thread).wait
+```
+
+Interruption is reliable across all six. No matter the backing &mdash;
+thread, fiber, process, ractor &mdash; `LLM::Interrupt` reaches the
+tool and it can rescue, clean up, and either re-raise to cancel the
+turn or return a value to continue.
+
+#### sequential
+
+The default. Tools run one at a time on the calling thread. No
+concurrency, no overhead. `spawn` is a no-op &mdash; execution happens
+in `wait`. `alive?` always returns `false`.
+
+Best for simple agents with a tool or two, debugging, or when tool
+order matters.
+
+#### thread
+
+Each tool runs in its own `Thread`. The thread is created lazily &mdash;
+you can build a task, pass it around, and decide when to run it.
+Threads have `report_on_exception` disabled so errors surface through
+`wait` rather than stderr.
+
+Interruption raises `LLM::Interrupt` directly on the tool's thread,
+which stops it mid-flight.
+
+Best for IO-bound tools &mdash; HTTP calls, database queries. CRuby
+releases the GVL during blocking IO, so you get real concurrency.
+
+#### fiber
+
+Each tool runs in a scheduler-backed `Fiber` via `Fiber.schedule`.
+Requires `Fiber.scheduler` &mdash; raises `ArgumentError` without one.
+Fibers yield cooperatively at IO boundaries, so this pairs well with
+async libraries that set a scheduler.
+
+Interruption raises `LLM::Interrupt` on the fiber, which stops at
+the next yield point.
+
+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. A dedicated thread runs an `Async::Reactor` event loop.
+Work is submitted through a thread-safe `Queue` inbox and consumed
+by the reactor. All fibers stay on one thread &mdash; no shared-memory
+contention between them.
+
+The reactor is created on demand and shared across all tasks in a
+group. When `Group#wait` is called, tasks are submitted, the reactor
+runs them concurrently, and results are bridged back to the caller
+through per-task queues. The reactor is torn down after `wait`
+completes.
+
+Interruption pushes an `LLM::Interrupt` sentinel into the task's
+result queue instead of using `Fiber#raise` &mdash; cleaner, and it
+avoids surprising the reactor's internal fibers.
+
+Best for IO-bound tools when you want Async's structured concurrency
+model without running your whole application inside a reactor. The
+reactor is self-contained &mdash; your main thread stays synchronous.
+Requires the `async` gem.
+
+#### fork
+
+Each tool runs in a forked child process. Communication uses
+[`xchan`](https://github.com/1robertrb/xchan.rb) (marshal-based
+channels): the parent sends control messages, the child sends
+results back. Each child is a separate OS process with its own
+memory space &mdash; a crash in the tool cannot touch the parent.
+
+`Fork::Task` checks liveness with `Process.waitpid(WNOHANG)` and
+delivers interrupts as messages over the control channel. The child
+raises `LLM::Interrupt` on `Thread.main` when it receives the
+interrupt message. Tracer callbacks fire in both parent and child.
+
+Best for process isolation &mdash; shell commands, native extensions,
+anything you don't want touching the parent's memory. True parallelism
+too, since there's no GVL in separate processes. Requires the
+`xchan` gem.
+
+#### ractor
+
+Each class-based tool runs in a Ruby `Ractor`. `Ractor::Task`
+coordinates through `Ractor::Mailbox`. Interruption sends a message
+through the mailbox; a listener thread inside the ractor raises
+`LLM::Interrupt` on `Thread.main`.
+
+Ractors have restrictions: only class-based tools are supported (no
+blocks, skills, or MCP tools), and arguments must be
+ractor-shareable. The runtime raises `LLM::RactorError` early if
+you try to run an unsupported tool type.
+
+Best for CPU-bound tools, true parallelism without the overhead of
+forking full processes. More restrictive than `:fork` but lighter.
+
+#### Quick reference
+
+| Strategy | Backing | Parallel? | Isolation? | Requires |
+|---|---|---|---|---|
+| `:sequential` | direct call | No | No | &mdash; |
+| `:thread` | `Thread` | IO only (GVL) | No | &mdash; |
+| `:fiber` | `Fiber.schedule` | Cooperative | No | `Fiber.scheduler` |
+| `:async` | `Async::Reactor` on bg thread | Cooperative | No | `async` gem |
+| `:fork` | `Kernel.fork` | Yes (process) | Yes (memory) | `xchan` gem |
+| `:ractor` | `Ractor` | Yes (CPU) | Limited | &mdash; |
+
+[Back to top](#table-of-contents)
+
+## Context Compaction
+
+Long-running conversations consume tokens. Without intervention, every turn
+pushes toward the model's context window limit, at which point the provider
+rejects the request.
+
+llm.rb provides compaction through pluggable strategies. All strategies
+inherit from [`LLM::Compactor`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor.html)
+and are invoked automatically before each `ctx.talk(...)` call.
+
+### Configuration
+
+Pass a compactor class and options when creating a context or agent:
+
+```ruby
+ctx = LLM::Context.new(
+  llm,
+  compactor: LLM::Compactor::Truncate,
+  compactor_options: {keep: 64}
+)
+
+# LLM::Agent accepts the same options
+agent = LLM::Agent.new(
+  llm,
+  compactor: LLM::Compactor::Truncate,
+  compactor_options: {keep: 128}
+)
+```
+
+The compactor runs automatically before every `talk` call. This keeps the
+conversation constantly alive — there is no chance of exhausting the context
+window because old messages are dropped before they accumulate. The trade-off
+is that dropped messages are gone, so information may be lost. Set `keep` to
+a higher number to retain more context at the cost of slower accumulation.
+
+The default is [`LLM::Compactor::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Null.html)
+— compaction is disabled unless you opt in.
+
+### Standalone usage
+
+A compactor can be used independently of a context or agent:
+
+```ruby
+compactor = LLM::Compactor::Truncate.new(agent)
+compactor.call(keep: 200)   # or ctx, agent, etc.
+```
+
+This is useful for one-off compaction outside the automatic per-turn cycle,
+or when you want to compact on a different schedule.
+
+### Strategies
+
+**[`LLM::Compactor::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Null.html)**
+— the default. Does nothing.
+
+**[`LLM::Compactor::Truncate`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Truncate.html)**
+— drops the oldest messages, keeping only the N most recent.
+
+- **Fast** — no network call, no LLM overhead. Operates entirely in memory
+  with a single pass over the message list.
+- **No dependencies** — works offline, has no model or API requirements, and
+  introduces no additional cost.
+- **Tool-loop safe** — when a tool result (return) falls at the truncation
+  boundary, the corresponding tool call is kept. Without this, the
+  conversation would contain an orphaned result with no matching call,
+  causing API-level errors on the next turn.
+
+The `keep:` parameter accepts either an integer count or a percentage
+string like `"80%"`, which keeps approximately 80% of the most recent
+messages. This is useful when you want to trim proportionally rather
+than to an absolute number.
+
+```ruby
+ctx = LLM::Context.new(
+  llm,
+  compactor: LLM::Compactor::Truncate,
+  compactor_options: {keep: 128}
+)
+```
+
+### Manual compaction
+
+The REPL provides a `/compact` command that invokes Truncate on the current
+agent's context:
+
+```
+/compact        # keep last 128 messages
+/compact 50     # keep last 50 messages
+/compact 75%    # keep approximately 75% of messages
+```
+
+### Lifecycle callbacks
+
+Both strategies call stream hooks so the UI can show progress:
+
+```ruby
+def on_compaction(compactor)
+  # called before compaction begins
+end
+
+def on_compaction_finish(compactor)
+  # called after compaction completes
+end
+```
+
+The context's `compacted?` flag is `true` between compaction and the next
+model response.
+
+[Back to top](#table-of-contents)
+
 ## Serialization
 
 The [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
@@ -792,20 +1258,32 @@ for a number of different reasons, most often because the
 user made a mistake, or the model is making a mistake and
 the user wants to cancel the action.
 
-The runtime has built-in support for cancellation. So for
-example it is possible to cancel a request on the main
-thread from a secondary thread. A number of things happen
-when a request is cancelled. First the request is cancelled
-at the transport level, and each transport handles it a little
-differently. The net effect in every case is that the connection
-is closed.
-
-The runtime then notifies the rest of the system. so for example,
-if a tool was running, it will receive the `on_interrupt` / `on_cancel`
-callback that lets the tool do any necessary cleanup, or execute its own
-cancellation plan. Tools that were pending (not yet run but requetsed to
-run) are cancelled through
-[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method).
+The runtime has built-in support for cancellation. Call
+`agent.cancel!` or `ctx.cancel!` from any thread and two
+things happen at once:
+
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+is raised on the thread where `talk` is running, so the
+caller can rescue it and know the request was cancelled.
+
+At the same time, `LLM::Interrupt` is raised on every tool
+that is currently executing &mdash; regardless of which
+concurrency strategy it's using. A tool running in a thread
+gets it on that thread. A tool in a fiber gets it on that
+fiber. A tool in a forked process gets it via a message
+over the xchan control channel. The
+delivery mechanism depends on the strategy, but the effect is
+the same: the tool can rescue `LLM::Interrupt`, clean up
+resources, close connections, flush buffers, and either
+re-raise to abort or return a partial result.
+
+Pending tools &mdash; those the model requested but that haven't
+started running yet &mdash; are cancelled through
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method)
+without ever being executed.
+
+The transport layer also cancels the in-flight HTTP request,
+closing the connection to the provider.
 
 ```ruby
 require "llm"
@@ -828,6 +1306,58 @@ 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 (`:sequential`, `:thread`, `:fiber`,
+`:async`, `: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 delivers the interrupt through ractor
+message passing &mdash; a listener thread inside the tool ractor
+receives the interrupt message and raises `LLM::Interrupt` on the
+ractor's main thread. The end result is the same as every other
+strategy: the tool can rescue, clean up, and decide.
+The `:fork` strategy delivers the interrupt via a message
+over the xchan control channel, which a listener thread in the
+child process picks up and raises on `Thread.main`. All other strategies
+raise the exception directly on the executing thread or fiber.
+
 [Back to top](#table-of-contents)
 
 ## Tracer
@@ -916,15 +1446,20 @@ This feature requires that the [curses](https://github.com/ruby/curses)
 and [kramdown](https://github.com/gettalong/kramdown) libraries are
 installed and available to require.
 
+The `name:` option labels the agent throughout the TUI &mdash;
+useful when working with multiple agents. The `path:` option
+persists state across sessions. The `tools:` option attaches
+extra tools for the duration of the session.
+
 ```ruby
 require "llm"
 
 llm = LLM.deepseek(key: ENV["KEY"])
-agent = LLM::Agent.new(llm)
-agent.repl
+agent = LLM::Agent.new(llm, name: "my-agent")
+agent.repl(path: "session.json", tools: LLM::Tool.subclasses)
 ```
 
-#### State
+#### Persistence
 
 The `path:` option accepts a file path where runtime state
 is read from and written to. This lets you resume a
@@ -949,6 +1484,16 @@ agent = LLM::Agent.new(llm)
 agent.repl(tools: [Debugger])
 ```
 
+Load every built-in tool with `LLM::Tool.subclasses`:
+
+```ruby
+require "llm/tools"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl(tools: LLM::Tool.subclasses)
+```
+
 #### Skills
 
 The read-eval-print loop also accepts a `skills` option.
@@ -977,7 +1522,11 @@ agent.repl(tracer: true, tools: [Debugger])
 
 #### Input
 
-The input area supports several keyboard shortcuts:
+The input area supports several keyboard shortcuts.
+When characters arrive faster than a threshold the REPL
+detects that text is being pasted rather than typed. In
+paste mode pressing `Enter` inserts a newline instead of
+submitting, allowing multi-line prompts.
 
 | Key | Action |
 |---|---|
@@ -988,36 +1537,91 @@ The input area supports several keyboard shortcuts:
 | `Ctrl+K` | Erase from cursor to the end of the line |
 | `Ctrl+Y` | Paste previously killed text |
 | `Ctrl+D` | Delete the character at the cursor |
+| `Ctrl+P` | Recall the previous user message |
+| `Ctrl+N` | Recall the next user message |
 | `Left / Right` | Move the cursor |
-| `Up / Down` | Scroll the transcript |
-
-When characters arrive faster than a threshold the REPL
-detects that text is being pasted rather than typed. In
-paste mode pressing `Enter` inserts a newline instead of
-submitting, allowing multi-line prompts.
+| `Up / Down` | Scroll the transcript one line |
+| `PgUp` / `PgDn` | Scroll the transcript by one page |
+| `Tab` | Complete `/command` names |
+| `Esc` | Cancel the current request |
 
 #### Commands
 
 Commands are recognized by a `/` prefix on the input line.
-The built-in command is `/exit`, which leaves the REPL.
+Type `/compact` to free context window space by dropping the
+oldest messages. Type `/exit` to leave the REPL.
+
 The [`LLM::Repl::Command`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html)
-class can be subclassed to add custom commands &ndash;
-any subclass that defines a `name`, `description`, and
-`call` method is automatically registered and available.
+class is intentionally similar to [`LLM::Tool`](#llmtool) and
+[`LLM::Schema`](#schema) in its interface &ndash; you declare a
+name, description, and parameters with the same vocabulary.
+A subclass is automatically registered and available as `/name`.
+
+##### Parameters
+
+Parameters are declared with `parameter :name, Type, "description"`
+and marked required with `required %i[name]`. The `call` method
+receives them as keyword arguments matching the parameter names.
+Parameters without a user-supplied value fall back to the
+method signature's default.
 
 ```ruby
-class LLM::Repl::Command
-  class Clear < self
-    name "clear"
-    description "clears the transcript"
-
-    def call
-      system("clear") || system("cls")
-    end
+class Greeter < LLM::Command
+  name "greet"
+  description "Greets the given name"
+  parameter :name, String, "The person's name"
+  required %i[name]
+
+  def call(name:)
+    write "Welcome #{name}!\n"
   end
 end
 ```
 
+##### Output
+
+A command writes to the transcript with `write(str, who:)`.
+The `who:` label is rendered in bold. It defaults to
+`command(name): ` where `name` is the command's registered
+name.
+
+```ruby
+def call(name:)
+  write("Greetings #{name}!\n")
+end
+```
+
+##### Help
+
+The built-in [`help`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html#help-class_method)
+class method formats the name, description, and parameter list
+automatically. Use it from inside a command or via `/help`.
+
+```ruby
+class Greeter < LLM::Command
+  name "greet"
+  # ...
+end
+
+# /help greet displays:
+#   Command: greet
+#   Description: Greets the given name
+#
+#   Parameters:
+#     name [String] - The person's name (required)
+```
+
+##### Aliases
+
+Subclassing an existing command inherits its name, description,
+and parameters. This is how `/quit` is an alias of `/exit`:
+
+```ruby
+class Quit < LLM::Repl::Command::Exit
+  name "quit"
+end
+```
+
 [Back to top](#table-of-contents)
 
 ## Images
@@ -1182,3 +1786,35 @@ res.text # => "Good day"
 ```
 
 [Back to top](#table-of-contents)
+
+## OCR
+
+Optical Character Recognition extracts text from images and
+documents.
+
+#### Mistral
+
+Mistral is the only provider that currently supports OCR
+through its dedicated API endpoint. The `ocr` method accepts
+either an `image_url:` or a `document_url:` parameter.
+Document URLs can point to PDFs. The response exposes pages
+through `res.pages`, where each page has a `markdown` field
+containing the extracted text.
+
+```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 }
+```
+
+[Back to top](#table-of-contents)