llm.rb 16.0.0 → 17.0.1

data/docs/deepdive/features/builtin_tools.md

@@ -201,7 +201,7 @@ from stalling the conversation.
 
 [`LLM::Tool::Exec`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Exec.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)
+[`LLM::Agent#confirm`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#confirm-instance_method)
 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

data/docs/deepdive/features/concurrency.md

@@ -8,23 +8,23 @@
 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!)),
+([`LLM::Function::Task#spawn`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#spawn-instance_method),
+[`LLM::Function::Task#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#wait-instance_method),
+[`LLM::Function::Task#alive?`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#alive?-instance_method),
+[`LLM::Function::Task#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#interrupt!-instance_method)),
 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)
+[`LLM::Function::Task#spawn`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#spawn-instance_method)
 starts execution,
-[`LLM::Function::Task#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#wait)
+[`LLM::Function::Task#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#wait-instance_method)
 collects the result,
-[`LLM::Function::Task#alive?`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#alive?)
+[`LLM::Function::Task#alive?`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#alive?-instance_method)
 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!)
+[`LLM::Function::Task#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#interrupt!-instance_method)
 signals the task to stop.
 
 Interruption is reliable across all six.
@@ -83,8 +83,13 @@ 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.
+`Fiber.scheduler`, and that scheduler has to implement
+`fiber_interrupt`, which is how a cancel is asked of a fiber rather than
+raised into it. A scheduler without it is refused with
+[`LLM::FiberError`](https://r.uby.dev/api-docs/llm.rb/LLM/FiberError.html)
+before anything is scheduled, since a cancel that cannot be asked for is
+a cancel that cannot be delivered. 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

data/docs/deepdive/features/database.md

@@ -28,11 +28,11 @@ All four use the same serialization mechanism under the hood.
 
 [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
 implements
-[`LLM::Context#to_h`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_h)
+[`LLM::Context#to_h`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_h-instance_method)
 and
-[`LLM::Context#to_json`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_json)
+[`LLM::Context#to_json`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_json-instance_method)
 for serialization and
-[`LLM::Context#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#restore)
+[`LLM::Context#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#restore-instance_method)
 for deserialization. Save writes the current state, restore loads
 it back and picks up where the conversation left off.
 
@@ -70,16 +70,16 @@ underlying serialization as filesystem persistence.
 
 #### Overview
 
-The [`LLM::Agent#path`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#path)
+The [`LLM::Agent#path`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#path-instance_method)
 attribute provides transparent auto-persistence. Set a file path once
 and the agent restores conversation history from that file on startup
 and saves it back after every
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk-instance_method)
 or
-[`LLM::Agent#ask`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#ask)
+[`LLM::Agent#ask`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#ask-instance_method)
 turn. 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)
+[`LLM::Agent#save`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#save-instance_method)/
+[`LLM::Agent#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#restore-instance_method)
 calls needed.
 
 The feature is available on subclasses via the class DSL and on
@@ -89,9 +89,9 @@ direct instances via the `path:` keyword argument.
 
 When a `path` is set, the agent loads existing state from the file
 during initialization. After each turn
-([`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+([`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk-instance_method)
 or
-[`LLM::Agent#ask`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#ask)),
+[`LLM::Agent#ask`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#ask-instance_method)),
 the updated
 state is written back automatically. If the file does not exist yet,
 the agent starts with a blank conversation and creates the file on
@@ -140,9 +140,9 @@ Auto-persistence eliminates boilerplate. You set the path once and
 forget about serialization entirely. The agent picks up where it
 left off across process restarts, console sessions, or debugging runs
 without a single
-[`LLM::Agent#save`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#save)
+[`LLM::Agent#save`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#save-instance_method)
 or
-[`LLM::Agent#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#restore)
+[`LLM::Agent#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#restore-instance_method)
 call in your code.
 
 #### Notes
@@ -150,9 +150,9 @@ call in your code.
 The auto-path feature is a strict superset of manual filesystem
 persistence. If you need fine-grained control over when state is
 saved (e.g. batch several turns before persisting), use the manual
-[`LLM::Agent#save`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#save)
+[`LLM::Agent#save`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#save-instance_method)
 and
-[`LLM::Agent#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#restore)
+[`LLM::Agent#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#restore-instance_method)
 methods described in the Filesystem section below. The `path`
 attribute delegates to the same underlying serialization.
 
@@ -170,12 +170,12 @@ process or on a different machine, and pick up where you left off.
 
 [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
 implements
-[`LLM::Context#to_h`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_h)
+[`LLM::Context#to_h`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_h-instance_method)
 and
-[`LLM::Context#to_json`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_json)
+[`LLM::Context#to_json`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_json-instance_method)
 for serialization
 and
-[`LLM::Context#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#restore)
+[`LLM::Context#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#restore-instance_method)
 for deserialization. The serialized state includes the context id,
 the message history, the model name, the compaction status, and a
 snapshot of token usage. Save and
@@ -358,7 +358,7 @@ parameters. Those two are the only callbacks `acts_as_llm` and
 
 An agent built by `acts_as_agent` is bound to the record it was
 loaded from, and
-[`LLM::Agent#record`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#record)
+[`LLM::Agent#record`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#record-instance_method)
 returns it. To persist a context instead of an agent, use
 `acts_as_llm`: the model gains `#llm` (the provider) and `#ctx` (the
 context), and persists the same state without the automatic tool
@@ -547,6 +547,6 @@ To persist a context instead of an agent, use `plugin :llm`. The
 model gains `#llm` (the provider) and `#ctx` (the context), and
 persists the same state without the automatic tool loop. An agent
 built by `plugin :agent` is bound to its record, which
-[`LLM::Agent#record`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#record)
+[`LLM::Agent#record`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#record-instance_method)
 returns.
 

data/docs/deepdive/features/embeddings.md

@@ -9,7 +9,7 @@ Embeddings convert text into numerical vectors that capture semantic
 meaning. Similar texts produce vectors that are close together in the
 vector space, enabling semantic search, clustering, and classification.
 Most providers offer embedding models through an
-[`LLM::Provider#embed`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#embed)
+[`LLM::Provider#embed`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#embed-instance_method)
 method.
 
 llm.rb also includes support for OpenAI's vector store API, which
@@ -19,7 +19,7 @@ provides a managed vector database as an HTTP service.
 
 When you want to generate an embedding vector for a piece of text,
 call
-[`LLM::Provider#embed`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#embed)
+[`LLM::Provider#embed`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#embed-instance_method)
 on any provider that supports it. The method accepts an input string
 or array of strings and returns a response with the resulting
 embeddings, which can be stored in a vector database and used for
@@ -113,7 +113,7 @@ The trade-off is vendor lock-in and per-request pricing.
 Vector stores require the `openai` provider. Other providers such as
 DeepInfra, Google, and Mistral expose an embedding method but no
 vector store API. For a self-hosted vector database, pair
-[`LLM::Provider#embed`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#embed)
+[`LLM::Provider#embed`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#embed-instance_method)
 with sqlite-vec or pgvector.
 
 ### Local vector search
@@ -121,7 +121,7 @@ with sqlite-vec or pgvector.
 #### Overview
 
 Local vector search combines
-[`LLM::Provider#embed`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#embed)
+[`LLM::Provider#embed`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#embed-instance_method)
 with a local vector database such as
 [sqlite-vec](https://github.com/asg017/sqlite-vec) or
 [pgvector](https://github.com/pgvector/pgvector). This approach keeps

data/docs/deepdive/features/files.md

@@ -47,8 +47,10 @@ assistants that read them, get their content.
 
 Anthropic, Google, and OpenAI implement the Files API, and so do the
 providers built on OpenAI's - Moonshot and Alibaba among them, which
-inherit it. A provider that has no Files API of its own, such as
-DeepSeek, Mistral, or xAI, raises `NotImplementedError`. `download` is
-OpenAI-only, so the OpenAI-compatible providers inherit that too. A file
-id belongs to the provider that minted it: DeepSeek, for example, raises
-`LLM::PromptError` when it is handed a file id from another provider.
+inherit it. DeepSeek implements the Files API too, scoped to images that
+a chat request references by `file_id`. A provider that has no Files API
+of its own, such as Mistral or xAI, raises `NotImplementedError`.
+`download` is OpenAI-only, so the OpenAI-compatible providers inherit
+that too. A file id belongs to the provider that minted it: a file id minted by
+another provider is passed through as-is, and fails when DeepSeek's API
+tries to resolve it.

data/docs/deepdive/fundamentals/agents.md

@@ -16,7 +16,7 @@ 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),
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk-instance_method),
 the model responds, and if it requests tools the agent
 executes them automatically and feeds the results back. The tool
 loop can be bounded with
@@ -30,7 +30,7 @@ prompt already carries a system message of the caller's own.
 Agents manage the tool loop for you. They keep conversation state
 across turns and let you define reusable configurations at the
 class level. The loop runs until the model stops requesting tools
-unless you bound it with `tool_budget` or a guard. If you need
+unless you bound it with `tool_budget` or an intercept. 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.
@@ -100,8 +100,8 @@ 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)
+[`LLM::Agent#save`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#save-instance_method)/
+[`LLM::Agent#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#restore-instance_method)
 calls. See the
 [database deepdive](../features/database.md) for details.
 
@@ -244,10 +244,15 @@ of hanging.
 
 #### Notes
 
-The retry budget applies to rate-limited requests
-(`LLM::RateLimitError`) and timeouts (`Timeout::Error`, covering
-`Net::OpenTimeout` and `Net::ReadTimeout`); other errors are never
-retried. The budget lives on the provider, where it defaults to five
+The retry budget applies to the errors the provider lists in
+[`LLM::Provider#retry_errors`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#retry_errors-instance_method):
+rate limits (`LLM::RateLimitError`), an exhausted quota, and timeouts
+(`Net::OpenTimeout`, `Net::ReadTimeout`, `Net::WriteTimeout`). A
+provider extends that list rather than replacing it, so
+[`LLM::DeepSeek`](https://r.uby.dev/api-docs/llm.rb/LLM/DeepSeek.html)
+also retries `LLM::ServerError`, the error it returns when its servers
+are overloaded; anything not on the list is never retried. The budget
+lives on the provider, where it defaults to five
 (eight on Alibaba, which rate limits more often), and an agent that
 sets none of its own takes the provider's. A raw
 [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)

data/docs/deepdive/fundamentals/providers.md

@@ -37,7 +37,7 @@ as `LLM.aliyun`.
 Providers are the first building block of every llm.rb program.
 Because the whole runtime shares one provider interface, you can
 swap one provider for another with a single line change, and the
-same tools, schemas, streaming, and guards work unchanged.
+same tools, schemas, streaming, and intercepts work unchanged.
 
 #### Notes
 

data/docs/deepdive/fundamentals/schema.md

@@ -16,9 +16,9 @@ When you want a structured response from the model, subclass
 [`LLM::Schema`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html)
 and declare properties with types and constraints. When you pass
 the schema to
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk-instance_method)
 or
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk),
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method),
 the runtime includes it in the request parameters. The provider returns a
 JSON object matching the schema, which is coerced into an
 [`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html) with typed accessors.

data/docs/deepdive/fundamentals/stream.md

@@ -37,7 +37,7 @@ single blocking response.
 #### Notes
 
 The IO-like form is equivalent to
-[`LLM::Stream#on_content`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_content)
+[`LLM::Stream#on_content`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_content-instance_method)
 and does not include the other hooks. It covers content output
 (piping to stdout or a log file) without the overhead of a full
 subclass. A
@@ -61,11 +61,11 @@ When you want to react to specific runtime events, override the
 hooks on a
 [`LLM::Stream`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html)
 subclass.
-[`LLM::Stream#on_content`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_content)
+[`LLM::Stream#on_content`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_content-instance_method)
 receives tokens as they arrive.
-[`LLM::Stream#on_tool_call`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_call)
+[`LLM::Stream#on_tool_call`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_call-instance_method)
 fires when the model requests a tool.
-[`LLM::Stream#on_tool_return`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_return)
+[`LLM::Stream#on_tool_return`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_return-instance_method)
 fires when the tool completes.
 [`LLM::Stream#on_step`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_step-instance_method)
 fires when a request completes, which is the boundary between one
@@ -78,13 +78,13 @@ written against it - it is prepended onto a stream, and saves the
 conversation through the record the context is bound to, so a turn
 that is interrupted can be continued from its last completed request
 rather than started over.
-[`LLM::Stream#on_retry`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_retry)
+[`LLM::Stream#on_retry`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_retry-instance_method)
 fires each time a failed request is retried. Compaction hooks
 let you show progress or log what was trimmed. Skill hooks bracket a
 skill's subagent execution:
-[`LLM::Stream#on_skill_call`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_skill_call)
+[`LLM::Stream#on_skill_call`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_skill_call-instance_method)
 fires before a skill's subagent runs, and
-[`LLM::Stream#on_skill_return`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_skill_return)
+[`LLM::Stream#on_skill_return`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_skill_return-instance_method)
 fires after it finishes.
 
 ```ruby
@@ -164,7 +164,7 @@ instead, and hand the result to the turn when it is asked for.
 #### How it works
 
 Start the tool from
-[`LLM::Stream#on_tool_call`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_call)
+[`LLM::Stream#on_tool_call`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_call-instance_method)
 and enqueue its task on
 [`LLM::Stream#queue`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#queue-instance_method).
 [`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait-instance_method)

data/docs/deepdive/fundamentals/tools.md

@@ -12,10 +12,10 @@ when a tool fits the request; the runtime calls it and sends the
 result back.
 
 A tool is a Ruby class with a name, a description, and a
-[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call-instance_method)
 method. The name tells the model what the tool is called. The
 description tells the model when to use it. The
-[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call-instance_method)
 method receives the arguments and returns the result. That is the entire
 contract: name, description, parameters, and a method that runs.
 
@@ -26,7 +26,7 @@ A tool is a subclass of
 with a name, description, and optional typed parameters. The model sees the name and
 description and decides whether to call it. When it does, the
 runtime serializes the arguments and passes them to
-[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call).
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call-instance_method).
 
 Tools that spawn subprocesses can include
 [`LLM::Tool::Utils`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Utils.html)
@@ -36,11 +36,11 @@ and `now` help. The built-in `Exec`, `Git`, `Rg`, `Mkdir`, and `Ruby`
 tools use it to kill a command that exceeds its `timeout`.
 
 If
-[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call-instance_method)
 raises, the runtime rescues it and returns a structured
 error to the model instead. The conversation stays valid. You can
 also handle errors yourself inside
-[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call-instance_method)
 by rescuing and returning a domain-specific error hash.
 
 ```ruby
@@ -96,9 +96,9 @@ API call at once, then return a synthesized answer. See
 
 Confirmation gates tools behind explicit approval. List tool names
 in
-[`LLM::Agent#confirm`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#confirm)
+[`LLM::Agent#confirm`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#confirm-instance_method)
 to block execution until you override
-[`LLM::Agent#on_tool_confirmation`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#on_tool_confirmation).
+[`LLM::Agent#on_tool_confirmation`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#on_tool_confirmation-instance_method).
 Confirmation also accepts a Symbol that resolves to an instance
 method, letting the confirmed set change per-instance based on
 runtime conditions.
@@ -122,10 +122,10 @@ keywords in full.
 
 Tools that perform destructive actions can be gated behind explicit
 approval. List their names in
-[`LLM::Agent#confirm`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#confirm)
+[`LLM::Agent#confirm`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#confirm-instance_method)
 to block execution
 until you override
-[`LLM::Agent#on_tool_confirmation`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#on_tool_confirmation).
+[`LLM::Agent#on_tool_confirmation`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#on_tool_confirmation-instance_method).
 The default handler cancels
 the tool. Override it per-agent to prompt the user, log the decision,
 or auto-approve certain tools.
@@ -134,12 +134,12 @@ or auto-approve certain tools.
 
 When you want to override the default approval flow for a gated
 tool, override
-[`LLM::Agent#on_tool_confirmation`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#on_tool_confirmation)
+[`LLM::Agent#on_tool_confirmation`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#on_tool_confirmation-instance_method)
 on the subclass. The method receives the pending function and the
 execution strategy. Call
-[`LLM::Function#task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#task)
+[`LLM::Function#task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#task-instance_method)
 to execute the tool or
-[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method)
 to block it. The default handler cancels the call.
 
 ```ruby
@@ -178,7 +178,7 @@ matter what.
 #### How it works
 
 If
-[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call-instance_method)
 raises, the runtime returns `{error: true, type: "RuntimeError",
 message: "boom"}` to the model. A tool can also check for a known
 failure and return its own error shape, which gives the model
@@ -445,7 +445,7 @@ gem for process management and interrupt handling.
 
 `LLM::Tool.subclasses` lists the direct subclasses of
 [`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html), so a
-tool defined under an intermediate base class is not in the list.
+tool defined under an intermediate superclass is not in the list.
 [`LLM::Tool.registry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#registry-class_method)
 lists every tool that has a name, wherever it sits in the hierarchy.
 

data/docs/deepdive/media/ocr.md

@@ -13,7 +13,7 @@ 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)
+[`LLM::Provider#ocr`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#ocr-instance_method)
 method accepts an `image_url:` or `document_url:` parameter.
 Document URLs can point to PDFs.
 

data/docs/deepdive/protocols/a2a.md

@@ -38,7 +38,7 @@ the network.
 #### Notes
 
 An agent's capabilities are advertised through a card. The
-[`LLM::A2A::Card#interfaces`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A/Card.html#interfaces)
+[`LLM::A2A::Card#interfaces`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A/Card.html#interfaces-instance_method)
 method lists which transports a remote agent supports.
 
 ##### Persistent connections
@@ -69,7 +69,7 @@ JSON-RPC is an alternative transport for A2A agents. It uses a
 more structured protocol than REST, with request and response
 objects that follow the JSON-RPC 2.0 spec. Some agents advertise
 only JSON-RPC, others advertise both. The
-[`LLM::A2A::Card#interfaces`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A/Card.html#interfaces)
+[`LLM::A2A::Card#interfaces`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A/Card.html#interfaces-instance_method)
 method lists which transports a remote agent supports.
 
 #### How it works
@@ -93,7 +93,7 @@ agent.talk "What's happening, fellow agent?"
 JSON-RPC provides typed request and response objects that follow
 the 2.0 spec, offering a more structured protocol than REST. Some
 agents advertise only JSON-RPC, while others advertise both. The
-[`LLM::A2A::Card#interfaces`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A/Card.html#interfaces)
+[`LLM::A2A::Card#interfaces`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A/Card.html#interfaces-instance_method)
 method lists which transports a remote agent supports.
 
 #### Notes

data/docs/deepdive/protocols/mcp.md

@@ -17,7 +17,7 @@ subclasses the model can call.
 
 The stdio transport runs the server as a child process and
 communicates over stdin/stdout. Use
-[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session-instance_method)
 to avoid launching the same process multiple times.
 
 ```ruby
@@ -41,11 +41,62 @@ one. Remove them without touching the agent's code.
 #### Notes
 
 For stdio, use
-[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session-instance_method)
 to avoid launching the same process multiple times. For HTTP,
-[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session-instance_method)
 carries little benefit.
 
+### Local repository lookup with Sem
+
+[Sem](https://github.com/Ataraxy-Labs/sem) provides symbol lookup and
+source search through a local stdio MCP server. Install Sem following
+its upstream instructions and verify `sem --version`. This example
+uses the existing stdio client; no model credentials are needed.
+
+Save the following as `sem_code.rb`, then run it with an existing
+Git checkout and a symbol in that checkout:
+
+```bash
+SEM_REPO=/absolute/path/to/repo ruby sem_code.rb parse_config
+```
+
+```ruby
+require "llm"
+
+repo = File.realpath(ENV.fetch("SEM_REPO"))
+query = ARGV.fetch(0)
+mcp = LLM::MCP.stdio(
+  argv: [ENV.fetch("SEM_BIN", "sem"), "mcp"],
+  env: {"SEM_REPO" => repo},
+  cwd: repo
+)
+
+mcp.session do
+  lookup = mcp.tools.find { |tool| tool.name == "sem_find" }
+  raise "Server did not expose sem_find" unless lookup
+
+  puts LLM.json.dump(lookup.new.call(
+    query: query,
+    mode: "context",
+    token_budget: 1200
+  ))
+end
+```
+
+Use `SEM_BIN=/absolute/path/to/sem` if Sem is not on PATH. Keeping
+discovery and lookup inside `session` reuses the child process. The
+first query may build a repository index; an empty result can mean
+the symbol was not found. Consult the discovered tool schema for
+the installed Sem version.
+
+For an agent conversation, pass only the tool classes you intend
+to expose, for example `mcp.tools.select { |t| t.name == "sem_find" }`,
+inside the same session. This filters the model's available tools,
+not the server's permissions. The full Sem server also exposes
+validation tools that can execute commands: use trusted checkouts
+and host permissions. `SEM_REPO` is not a sandbox. The lookup does
+not edit source files, but Sem may write its local index.
+
 ### HTTP
 
 #### Overview
@@ -90,7 +141,7 @@ by a different team and exposed as a service.
 #### Notes
 
 For HTTP,
-[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session-instance_method)
 carries little benefit.
 
 ##### Persistent connections
@@ -109,15 +160,73 @@ mcp = LLM::MCP.http(
 )
 ```
 
+### Parallel web search and fetch
+
+[Parallel Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp)
+provides `web_search` and `web_fetch` over HTTP without a Parallel
+API key. The anonymous tier is free for exploration and light use,
+with rate limits and server-managed search settings.
+
+This example discovers the tools through the HTTP client, searches
+for Ruby documentation, then extracts excerpts from a specific page.
+It uses the default `net/http` transport and needs no model or provider
+credentials. Save it as `parallel_search.rb` and run
+`ruby parallel_search.rb` after installing `llm.rb`.
+
+```ruby
+require "llm"
+
+mcp = LLM::MCP.http(
+  url: "https://search.parallel.ai/mcp",
+  headers: {
+    "User-Agent" => "llm.rb/#{LLM::VERSION}",
+    "Accept" => "application/json, text/event-stream"
+  }
+)
+
+mcp.session do
+  tools = mcp.tools
+  search = tools.find { _1.name == "web_search" }.new
+  fetch = tools.find { _1.name == "web_fetch" }.new
+  session_id = SecureRandom.uuid
+  queries = ["Ruby Fiber scheduler documentation"]
+
+  puts LLM.json.dump(search.call(
+    objective: "Find the official Ruby Fiber scheduler documentation.",
+    search_queries: queries,
+    session_id:
+  ))
+
+  puts LLM.json.dump(fetch.call(
+    urls: ["https://docs.ruby-lang.org/en/master/Fiber.html"],
+    objective: "Explain how Ruby uses a Fiber scheduler.",
+    search_queries: queries,
+    session_id:
+  ))
+end
+```
+
+To let an agent choose when to search or fetch, pass the discovered
+tools to `talk` instead. Model inference is separate from the free
+MCP service and uses your chosen provider's credentials and pricing.
+Using the same `mcp` configuration above:
+
+```ruby
+llm = LLM.deepseek(key: ENV.fetch("DEEPSEEK_API_KEY"))
+agent = LLM::Agent.new(llm)
+agent.talk "Find the official Ruby Fiber scheduler docs and explain them.",
+           tools: mcp.tools
+```
+
 ### Prompts
 
 #### Overview
 
 An MCP server can offer prompts as well as tools: reusable,
 parameterized message templates a client fetches and sends to a model.
-[`LLM::MCP#prompts`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#prompts)
+[`LLM::MCP#prompts`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#prompts-instance_method)
 lists them, and
-[`LLM::MCP#find_prompt`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#find_prompt)
+[`LLM::MCP#find_prompt`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#find_prompt-instance_method)
 fetches one and returns its messages.
 
 #### How it works
@@ -155,7 +264,7 @@ it, so it can change without a client release.
 `find_prompt` adapts each message's content to the runtime's shape: a
 text item becomes a string, and anything else stays an `LLM::Object`
 under `original_content`.
-[`LLM::MCP#get_prompt`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#get_prompt)
+[`LLM::MCP#get_prompt`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#get_prompt-instance_method)
 is an alias. Like `tools`, both methods borrow a session when one is
 not already running.