llm.rb 13.0.0 → 14.0.0

data/resources/deepdive/fundamentals/schema.md

@@ -0,0 +1,61 @@
+
+## Schema
+
+### Introduction
+
+#### Overview
+
+A schema describes the shape of a structured response you expect
+from the model. Instead of parsing free-form text, you declare
+the expected structure and the runtime coerces the response into
+an object with typed accessors.
+
+#### How it works
+
+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)
+or
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk),
+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.
+
+```ruby
+class Estimation < LLM::Schema
+  property :age, Integer, "The estimated age of the person"
+  property :confidence, Number, "Your confidence in the estimate"
+  property :applicable, Boolean, "True when the photo contains a person"
+  property :comments, String, "Any additional comments"
+  required %i[age confidence applicable comments]
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, schema: Estimation)
+res = agent.ask "Given this photo, provide an age estimate", with: "photo.jpg"
+
+estimate = res.content!
+
+if estimate.applicable
+  print "The person is approx ", estimate.age.to_s, " years old"
+else
+  print "This photo is not applicable: ", estimate.comments
+end
+```
+
+#### Why would I use it?
+
+Schemas give you structured data instead of free text. Pass the
+result to other code without parsing. Use them for classification,
+extraction, or any workflow where the output needs to feed into
+another system.
+
+#### Notes
+
+Schemas can define objects, arrays, enums, and nested schemas.
+They are also used internally by
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+for parameter definitions, so you already benefit from them
+when you declare tool parameters.

data/resources/deepdive/fundamentals/skills.md

@@ -0,0 +1,106 @@
+
+## Skills
+
+### Introduction
+
+#### Overview
+
+A skill turns a markdown file into a callable tool. Write the
+instructions in markdown, declare what tools the subagent needs
+in the frontmatter, and register the file with the parent agent.
+When the model calls the skill, the runtime spawns a fresh subagent
+with those instructions as its system prompt and only the tools
+you gave it. The subagent runs one turn and returns. Then it is
+discarded.
+
+#### How it works
+
+A parent agent works with zero or more skill files. Each skill
+is registered as a tool the model can call.
+
+When the model calls a skill, a subagent is created with:
+
+- Its own system prompt: the body of the SKILL.md file
+- Limited tools: only what you declare in the frontmatter
+- Context awareness: the last 8 user/assistant messages from the
+  parent (tool calls stripped)
+
+The subagent runs one turn and returns. The parent sees the result
+like any other tool return.
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, skills: ["./skills/git-log", "./skills/deploy"])
+agent.talk "Review the recent commits, then deploy if everything looks clean"
+```
+
+#### Why would I use it?
+
+Because each skill spawns a fresh subagent with constrained tools,
+you can build a clear hierarchy. The parent supervises, decides
+which skill to call, inspects the result, and can iterate or
+compose multiple skills.
+
+Each skill is focused. A changelog skill gets `git-log` and
+`write-file`, not the shell. A deploy skill gets deployment tools,
+not file readers.
+
+Skills are stateless. Every call is independent. No carryover, no
+cross-contamination.
+
+#### Notes
+
+Skills can also be attached to the REPL session without modifying
+the agent:
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl(skills: [__dir__])
+```
+
+### Frontmatter
+
+#### Overview
+
+The frontmatter at the top of a skill file controls how the
+subagent sees itself and what it can reach. It sets the skill's
+name (which becomes the tool name), a description (which the
+model reads to decide when to call it), and a tool list (which
+limits what the subagent can do). Leave the tools out and the
+subagent has none. Set them to `all` and it has everything.
+
+#### How it works
+
+The frontmatter is parsed from the YAML block at the top of the
+file. The markdown body that follows becomes the subagent's system
+prompt. The `tools` field resolves at load time: named tools are
+looked up in the registry, `inherit` copies from the parent context,
+and `all` grabs everything available. The `tools` field accepts four
+forms:
+
+| Field | Purpose |
+|---|---|
+| `name` | A short identifier for the skill. Used as the tool name. |
+| `description` | Explains to the model what the skill does. Used as the tool description. |
+| `tools` | Controls what the subagent can call. See below. |
+
+| Value | Behavior |
+|---|---|
+| `inherit` | Copies the parent agent's tools, excluding other skills. |
+| `all` or `*` | Every tool in the global registry. |
+| `['name1', 'name2']` | Only the named tools. Raises an error if not found. |
+| (omitted) | No tools at all. |
+
+#### Why would I use it?
+
+The frontmatter is how you configure what a skill can do and what
+tools it has access to. `inherit` copies the parent's capabilities
+into the skill. An explicit list restricts the subagent to only
+the tools it needs.
+
+#### Notes
+
+The fewer tools a subagent has, the less it can wander.

data/resources/deepdive/fundamentals/stream.md

@@ -0,0 +1,110 @@
+
+## Stream
+
+### Introduction
+
+#### Overview
+
+Streaming delivers model output as it is generated, token by
+token, instead of waiting for the full response. The user sees
+text appear in real time, and the application can act on partial
+results as they arrive.
+
+#### How it works
+
+The stream target can be any object that responds to `#<<`. Each
+time the provider emits a token, the runtime calls `target <<
+chunk` with the raw content. The tokens arrive in order as the
+model generates them, so the output appears character by character
+instead of all at once. When the response is complete, the stream
+closes and control returns to the caller.
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, stream: $stdout)
+agent.talk "hello world"
+```
+
+#### Why would I use it?
+
+Streaming lets users see output sooner and cancel mid-response if
+the model goes off course. It also enables progress indicators and
+partial result processing, things that are not possible with a
+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)
+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
+[`LLM::Stream`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html)
+subclass gives you visibility into tool calls, compaction events,
+and reasoning content.
+
+### Callbacks
+
+#### Overview
+
+A stream subclass provides structured hooks into content, tool
+calls, compaction, and other runtime events. Each hook fires at
+a specific point in the request lifecycle. This gives you
+fine-grained visibility into what the runtime is doing as it
+happens, from the first token to the final tool return.
+
+#### How it works
+
+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)
+receives tokens as they arrive.
+[`LLM::Stream#on_tool_call`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_call)
+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)
+fires when the tool completes. Compaction hooks
+let you show progress or log what was trimmed.
+
+```ruby
+class MyStream < LLM::Stream
+  def on_content(content)
+    print content
+  end
+
+  def on_reasoning_content(content)
+    warn content
+  end
+
+  def on_tool_call(tool)
+  end
+
+  def on_tool_return(tool, result)
+  end
+
+  def on_compaction(compactor)
+  end
+
+  def on_compaction_finish(compactor)
+  end
+end
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, stream: MyStream.new)
+agent.talk "Explain Ruby fibers."
+```
+
+#### Why would I use it?
+
+A stream subclass gives you visibility into more than just content chunks. React to tool
+calls as they happen, show compaction progress, or integrate with
+an existing observability stack.
+
+#### 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)
+and does not include the other hooks.

data/resources/deepdive/fundamentals/tools.md

@@ -0,0 +1,265 @@
+
+## Tools
+
+### Introduction
+
+#### Overview
+
+A tool is how a model reaches outside its own head. Without tools,
+the model can only produce text. With a tool, it can run a shell
+command, query a database, or fetch a web page. The model decides
+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)
+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)
+method receives the arguments and returns the result. That is the entire
+contract: name, description, parameters, and a method that runs.
+
+#### How it works
+
+A tool is a subclass of
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+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 serialises the arguments and passes them to
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call).
+
+If
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
+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)
+by rescuing and returning a domain-specific error hash.
+
+```ruby
+class Shell < LLM::Tool
+  name "shell"
+  description "execute a shell command"
+  parameter :name, String, "the command's name"
+  parameter :arguments, Array[String], "One or more arguments"
+  required %i[name]
+  defaults arguments: []
+
+  def call(name:, arguments: [])
+    out = `#{name.shellescape} #{arguments.map(&:shellescape).join(" ")}`
+    {ok: $?.success?, out:}
+  end
+end
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, tools: [Shell], stream: $stdout)
+agent.talk "What files are in the current working directory?"
+```
+
+#### Why would I use it?
+
+Tools are how the model interacts with the outside world. Without
+them, the model can only produce text. With tools, it can query
+databases, run shell commands, fetch web pages, or call APIs. The
+tool loop stays alive even when a tool fails. One broken tool does
+not derail the conversation.
+
+#### Notes
+
+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)
+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).
+Confirmation also accepts a Symbol that resolves to an instance
+method, letting the confirmed set change per-instance based on
+runtime conditions.
+
+Tool properties can be defined with individual method calls (as shown
+in the How it works section) or with
+[`LLM::Tool.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#set-class_method)
+(see the Set subsection). Both approaches work the same way.
+
+### Confirmation
+
+#### Overview
+
+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)
+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).
+The default handler cancels
+the tool. Override it per-agent to prompt the user, log the decision,
+or auto-approve certain tools.
+
+#### How it works
+
+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)
+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)
+to execute the tool or
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+to block it. The default handler cancels the call.
+
+```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) ? fn.task(strategy).wait : fn.cancel
+  end
+end
+```
+
+#### Why would I use it?
+
+Confirmation prevents the model from running dangerous tools
+without user oversight. You decide the approval flow: a terminal
+prompt, a web socket, a background job queue.
+
+#### Notes
+
+Confirmation names can be a static array of tool names or a Symbol
+that resolves to an instance method. The Symbol form lets the
+confirmed set change per-instance based on runtime conditions.
+
+### Errors
+
+#### Overview
+
+A tool that raises does not crash the conversation. The runtime
+catches the exception, wraps it into a structured error, and
+returns it to the model. The model can read the error, decide what
+went wrong, and try something else. The tool loop stays alive no
+matter what.
+
+#### How it works
+
+If
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
+raises, the runtime returns `{error: true, type: "RuntimeError",
+message: "boom"}` to the model. You can also rescue inside
+[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
+and return your own error shape that gives the model more context.
+
+```ruby
+class Shell < LLM::Tool
+  set name: "shell",
+      description: "run a shell command",
+      parameters: {
+        ["name", String, "the command name"],
+        ["arguments", Array[String], "one or more arguments"]
+      },
+      required: %i[name],
+      defaults: {arguments: []}
+
+  def call(name:, arguments: [])
+    out = `#{name} #{arguments.join(" ")}`
+    {ok: $?.success?, out:}
+  rescue Errno::ENOENT
+    {ok: false, error: "command not found: #{name}"}
+  end
+end
+```
+
+#### Why would I use it?
+
+Custom error handling gives the model domain-specific detail that
+helps it recover. Instead of a generic "RuntimeError: boom", the
+model sees `{ok: false, error: "command not found: ls"}` and knows
+to correct the command name and try again.
+
+#### Notes
+
+The principle is the same either way: return something. A tool call
+must complete with a tool response. If you do not return a value and
+you do not raise, the runtime has nothing to send back and the
+conversation is stuck.
+
+### Set
+
+#### Overview
+
+[`LLM::Tool.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#set-class_method)
+is an alternative way to define tool properties using a Hash. It
+works the same way as individual method calls and accepts the same
+keys: `name`, `description`, `parameters`, `required`, and
+`defaults`.
+
+#### How it works
+
+When you want to define tool properties at once, call
+[`LLM::Tool.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#set-class_method)
+with a Hash. The keys match the individual method names. The
+`parameters` key accepts the same Array of tuples that the
+individual `parameter` method does.
+
+```ruby
+class Shell < LLM::Tool
+  set name: "shell",
+      description: "execute a shell command",
+      parameters: [
+        [:name, String, "the command's name"],
+        [:arguments, Array[String], "One or more arguments"]
+      ],
+      required: %i[name],
+      defaults: {arguments: []}
+
+  def call(name:, arguments: [])
+    out = `#{name.shellescape} #{arguments.map(&:shellescape).join(" ")}`
+    {ok: $?.success?, out:}
+  end
+end
+```
+
+#### Why would I use it?
+
+`set` is useful when you want to keep related properties together.
+Instead of spreading `name`, `description`, `parameters`, and
+`required` across multiple lines, you can group them in a single
+Hash that reads like a configuration block.
+
+#### Notes
+
+Unknown keys raise `KeyError`, so typos are caught at class load
+time rather than at runtime.
+
+### Built-in tools
+
+#### Overview
+
+llm.rb ships with twelve ready-made tools that cover filesystem,
+search, and shell operations. Load them all with
+`require "llm/tools"`. Each tool is documented in the
+[built-in tools catalog](builtin_tools.md).
+
+#### How it works
+
+When you want to attach the built-in tools to an agent, require
+the catalog and pass the full set of subclasses as the `tools:`
+option.
+
+```ruby
+require "llm"
+require "llm/tools"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, tools: LLM::Tool.subclasses)
+```
+
+#### Why would I use it?
+
+The built-in tools cover the operations a coding or system agent
+needs most. See the
+[built-in tools catalog](builtin_tools.md) for the full reference.
+
+#### Notes
+
+The tools that spawn subprocesses use the optional `test-cmd.rb`
+gem for process management and interrupt handling.

data/resources/deepdive/protocols/a2a.md

@@ -0,0 +1,106 @@
+
+## A2A
+
+### Introduction
+
+#### Overview
+
+The Agent-to-Agent (A2A) protocol lets agents communicate directly
+over a network. Unlike MCP, which connects an agent to external
+tools, A2A connects agents to other agents. A remote agent advertises
+its skills through a card. The calling agent loads those skills as
+local tools and calls them the same way it calls any other tool.
+One agent can research, another can code, a third can review.
+
+#### How it works
+
+The REST transport communicates over standard HTTP and JSON. Both
+transports expose the remote agent's skills as local
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+subclasses.
+
+```ruby
+require "llm"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+a2a   = LLM::A2A.rest(url: "https://agent.example.com")
+agent = LLM::Agent.new(llm, tools: a2a.skills)
+agent.talk "What's happening, fellow agent?"
+```
+
+#### Why would I use it?
+
+A2A lets you compose autonomous agents that delegate and collaborate.
+One agent researches a topic. Another writes code. A third reviews
+the result. Each agent runs independently and communicates over
+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)
+method lists which transports a remote agent supports.
+
+##### Persistent connections
+
+A persistent connection reuses the same HTTP connection across
+requests to the same A2A agent. Both REST and JSON-RPC transports
+accept the `persistent: true` option. Persistent connections matter
+when an agent makes many requests to the same remote agent in a
+short window, since reusing the connection avoids the handshake and
+teardown overhead of a fresh TCP connection per request. The option
+defaults to `false`; for a single request or an infrequent pattern,
+the overhead is negligible. When you want to avoid reopening a TCP
+connection for every request, pass `persistent: true` to the
+transport constructor. This uses
+[`Net::HTTP::Persistent`](https://github.com/drbrain/net-http-persistent)
+under the hood:
+
+```ruby
+a2a = LLM::A2A.rest(url: "https://agent.example.com", persistent: true)
+a2a = LLM::A2A.jsonrpc(url: "https://agent.example.com", persistent: true)
+```
+
+### JSON-RPC
+
+#### Overview
+
+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)
+method lists which transports a remote agent supports.
+
+#### How it works
+
+When you want to connect to a remote A2A agent using JSON-RPC,
+provide a URL and optional headers. The agent's skill list is
+fetched and translated into
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) subclasses the model can call.
+
+```ruby
+require "llm"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+a2a   = LLM::A2A.jsonrpc(url: "https://agent.example.com")
+agent = LLM::Agent.new(llm, tools: a2a.skills)
+agent.talk "What's happening, fellow agent?"
+```
+
+#### Why would I use it?
+
+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)
+method lists which transports a remote agent supports.
+
+#### Notes
+
+JSON-RPC request and response objects are typed and follow the 2.0
+spec. The
+[`LLM::A2A.jsonrpc`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A.html#jsonrpc-class_method)
+transport provides structured message envelopes rather than plain
+HTTP.
+