llm.rb 16.0.0.pre.3 → 16.0.0.pre.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8bd3b4f303036ba390981de3ec63ea0bb523cc653c4b77b221e4591e9b9a446
-  data.tar.gz: 3036ce3c4248e3ddad524657f31ea2c300f98282ad0aa68791848f56cd1b91f5
+  metadata.gz: f5558a0514d6bd6b9648f743a308ce8e6dbb3802b8709edc6caf45d7c1ab3de8
+  data.tar.gz: a5d3178f0c79e152b8032cce974be69edd1e52cc629658034a750183ccb41ea8
 SHA512:
-  metadata.gz: 604bafd36e8a55405e3fc487957ae97b9e4ffd67777711c071f7bfb9cfe005e0400294c089e72fbec3019538f4706c92cfe5bb15f3d0c2f994a324b9ba1a3322
-  data.tar.gz: d3bf4d7e1f9337cd7bdedb40ac4cfb4f95b6195e6df3360d428bfa6c220994edfaf8c5f053256e968c1feb9ae025b29854586dd9834dc84948729644f7a7b8ff
+  metadata.gz: 3a0288112d140d3e0a3e34dc35e570ceb25ad62fd7f3c33a2942cb111432992b7194e18fb406bf55a25a945aff0e89ce055c292a1de50c00b66c801027b95c52
+  data.tar.gz: 454a1c74a59401689c88947714f741ada1d39f6ce95013bf8bdd6fab76690adafd3a4be8af02e9eace2a71ae26c3f4daf3a1751fdf326549f722da888cbcb309

data/CHANGELOG.md

@@ -46,6 +46,39 @@
   [`LLM::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html) objects.
   Every other format, and Sequel, still loads the runtime.
 
+### ActiveRecord
+
+* **activerecord: add `messages!` for the runtime's own messages** <br>
+  [`LLM::ActiveRecord#messages!`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord.html#messages!-instance_method)
+  returns the messages the runtime holds whatever the storage format is, so a
+  jsonb record can still reach them now that its `#messages` answers with the
+  view over the column. It reads what the context holds, including state that
+  has not been saved, where `#messages` reads the column. The Sequel plugin
+  answers to `#messages!` too, where it is the same call as `#messages`.
+
+### Agent
+
+* **agent: keep the instructions it injected in step** <br>
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now brings
+  the instructions it injected up to date before a request goes out, so a
+  conversation restored from saved state runs on the agent's current
+  instructions rather than on the ones it was saved with. The message is
+  found by a mark the agent puts on it, so a message the caller composed is
+  never replaced, and the mark is written by
+  [`LLM::Message#to_h`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#to_h-instance_method)
+  and read back on a restore, which is the conversation the refresh exists
+  for. Before this, the instructions were injected once and the message
+  stayed as it was for the life of the conversation.
+
+* **agent: identify its own instructions by the mark, not by the role** <br>
+  Fix a bug where the agent decided whether it had already injected its
+  instructions by looking for a message with the `system` role. Google gives
+  instructions the `user` role, so the agent did not recognise the message it
+  had already injected and added another copy of the instructions on every
+  turn. It now asks the provider which role instructions are given, and
+  identifies the message it wrote by its mark, because on Google the message
+  a caller seeds a conversation with is a user message too.
+
 ### Console
 
 * **console: erase with the backspace key on OpenBSD** <br>
@@ -115,6 +148,35 @@
   `respond_to?` with false for an instance method. A hook that raises becomes
   what the caller sees in place of the call's result.
 
+### ORM
+
+* **orm: save a conversation after each request, not once per turn** <br>
+  [`LLM::Step`](https://r.uby.dev/api-docs/llm.rb/LLM/Step.html) is prepended
+  onto every stream by
+  [`LLM::Stream.try`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#try-class_method),
+  so a conversation bound to a record is written down as it goes and a turn
+  that is interrupted can be continued rather than started over. It saves
+  through
+  [`LLM::Context#record`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#record-instance_method),
+  an ActiveRecord model through `LLM::ActiveRecord::Utils.save!` and a Sequel
+  model through `LLM::Sequel::Plugin::Utils.save!`, and the write is best
+  effort, so a failure is swallowed rather than raised inside the request that
+  has just completed. Before this, `talk` and `ask` on both wrappers saved
+  once, when the whole turn had finished, so an interrupted turn persisted
+  nothing.
+
+### Prompt
+
+* **prompt: let a message carry fields a caller attaches to it** <br>
+  [`LLM::Prompt#system`](https://r.uby.dev/api-docs/llm.rb/LLM/Prompt.html#system-instance_method),
+  [`#user`](https://r.uby.dev/api-docs/llm.rb/LLM/Prompt.html#user-instance_method),
+  [`#developer`](https://r.uby.dev/api-docs/llm.rb/LLM/Prompt.html#developer-instance_method),
+  and [`#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Prompt.html#talk-instance_method),
+  along with its `#chat` alias, now take an `extra:` keyword, so a message a
+  caller composes can carry fields of its own. The runtime reads those fields
+  back rather than inferring provenance from a role, which is how an agent
+  tells the instructions it injected from a message the caller wrote.
+
 ### Provider
 
 * **deepseek: support image attachments in chat completions** <br>
@@ -155,6 +217,19 @@
   discarded a false default, and `required: false` marks the parameter optional
   rather than being ignored.
 
+### Stream
+
+* **stream: add `on_step`, called when a request completes** <br>
+  [`LLM::Stream#on_step`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_step-instance_method)
+  is a new callback, emitted from
+  [`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
+  once the prompt and the response are in the conversation. It marks the
+  boundary between one request and the next, which is the point a stream can
+  checkpoint the conversation at, because a provider will accept it again
+  there. It fires once per successful request, so a request retried after a
+  rate limit or a timeout calls it when it lands and not once per attempt, and
+  it fires even when the stream is disabled.
+
 ## v15.5.0
 
 Changes since `v15.4.1`.

data/README.md

@@ -78,7 +78,8 @@ agent.talk "hello world"
 Streams can be simple IO objects or subclasses of
 [`LLM::Stream`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html)
 with structured callbacks for content,
-reasoning, tool calls, tool returns, and compaction.
+reasoning, tool calls, tool returns, the boundary a completed
+request marks, and compaction.
 Streams can also observe message transformers, which rewrite
 outgoing messages before they reach the provider.
 
@@ -102,6 +103,11 @@ class MyStream < LLM::Stream
   def on_tool_return(tool, result)
   end
 
+  # A request has completed: the response is in the conversation, and
+  # any tools it asked for run after this.
+  def on_step(ctx, res)
+  end
+
   # Before a transformer rewrites an outgoing message.
   def on_transform(transformer)
   end

data/docs/deepdive/advanced/context.md

@@ -81,9 +81,10 @@ Pass `retry_budget:` to retry a request that was rate limited
 Each retry sleeps a growing interval (2s, 4s, 6s, ...) and notifies
 the stream through
 [`LLM::Stream#on_retry`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_retry-instance_method)
-before trying again. An `LLM::Agent` enables a budget of 5 by
-default (or 8 on the Alibaba provider, which rate limits more
-often), so most users never touch this directly.
+before trying again. The budget lives on the provider, where it
+defaults to 5 (8 on Alibaba, which rate limits more often), and an
+agent that sets none of its own takes the provider's, so most users
+never touch this directly.
 
 ### Identity
 
@@ -423,7 +424,9 @@ The block receives the prompt object when it takes an argument, and
 otherwise runs in the prompt's context:
 [`LLM::Prompt#to_a`](https://r.uby.dev/api-docs/llm.rb/LLM/Prompt.html#to_a)
 returns the messages in order, and two prompts are equal when their
-messages match.
+messages match. Each of `system`, `user`, `developer`, and `talk`
+accepts an `extra:` hash, which is attached to the message it builds,
+so a caller can carry a field of its own alongside the content.
 
 #### Why would I use it?
 

data/docs/deepdive/features/console.md

@@ -66,9 +66,9 @@ should use the `console` names.
 When `bin/llm.rb` starts, it looks for an `AGENTS.md` file in the
 current working directory. If one exists, its contents become the
 agent's instructions for the session, so a project can describe how it
-wants the agent to work without passing flags. The instructions are
-injected once, so a resumed session that already has a system message
-keeps the one it has.
+wants the agent to work without passing flags. The agent brings its
+instructions up to date before each request, so a resumed session runs
+on the current file rather than the one it was saved with.
 
 The user-message label is exposed through
 [`LLM::Console#sender`](https://r.uby.dev/api-docs/llm.rb/LLM/Console.html#sender-instance_method),

data/docs/deepdive/features/database.md

@@ -34,13 +34,23 @@ and
 for serialization and
 [`LLM::Context#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#restore)
 for deserialization. Save writes the current state, restore loads
-it back and picks up where the conversation left off. The ORM
-wrappers automate this; each
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
-or
-[`LLM::Agent#ask`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#ask)
-call persists the
-updated state back to the column automatically.
+it back and picks up where the conversation left off.
+
+The ORM wrappers write on a different boundary than the file does, and
+the two are worth telling apart.
+[`LLM::Step`](https://r.uby.dev/api-docs/llm.rb/LLM/Step.html) is
+prepended onto the stream, and it saves the conversation through the
+record the context is bound to each time
+[`LLM::Stream#on_step`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_step-instance_method)
+fires - after a response is in the conversation and before the tools it
+asked for run. A turn that runs tools before it answers is therefore
+saved more than once, and an application that writes it down can
+continue an interrupted turn instead of redoing it.
+
+A `path:` has no record behind it to write to, so that one saves once
+per turn. The difference is what each is for: the column is a
+checkpoint after every completed request, and the file is a session at
+the end of one.
 
 #### Why would I use it?
 
@@ -242,12 +252,10 @@ first call, a fresh agent is created and the conversation starts
 from scratch.
 
 On subsequent calls, the stored state is restored and the
-conversation continues. Every
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
-or
-[`LLM::Agent#ask`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#ask)
-call persists the
-updated state back to the column automatically.
+conversation continues. The column is written after each completed
+request rather than at the end of a turn, so a turn that runs tools
+before it answers is saved more than once - and a turn that is
+interrupted can be resumed from its last completed request.
 
 The `data_column:` option lets you use a different column name.
 The `format:` option controls the storage type. Use `:string` for
@@ -327,7 +335,7 @@ agent.talk "perform research"
 #### Why would I use it?
 
 The ActiveRecord wrapper integrates with your existing models.
-Agent state is automatically persisted after each conversation turn
+Agent state is automatically persisted after each completed request,
 using the same `create!`, `save!`, and query methods you already
 use.
 
@@ -419,11 +427,12 @@ records rather than
 [`LLM::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html)
 objects, until
 [`#unwrap!`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html#unwrap!-instance_method)
-turns them back.
+turns them back. `#messages!` is the runtime's own list, whatever the
+format is, so a jsonb record reaches it in one call.
 
-Every other format loads the runtime and returns the messages it
-holds, as it always did, and that is the default. Sequel has no
-equivalent: its plugin persists the same state, and there is no view to
+Every other format answers `#messages` with the runtime's messages, as
+it always did, and that is the default. Sequel has no equivalent to any
+of this: its plugin persists the same state, and there is no view to
 read it back in the database.
 
 ### Sequel
@@ -446,11 +455,8 @@ the plugin in the model class. The `data` column stores
 the full agent state as JSON, same structure as ActiveRecord.
 On first call, a fresh agent is created. On subsequent calls,
 the stored state is restored and the conversation continues.
-Every
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
-or
-[`LLM::Agent#ask`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#ask)
-call persists the updated state.
+The state is written after each completed request, as it is under
+ActiveRecord.
 
 The `data_column:` and `format:` options work identically to
 ActiveRecord. For `:jsonb`, Sequel loads the `pg_json` extension

data/docs/deepdive/features/embeddings.md

@@ -50,6 +50,8 @@ an `embed` method:
 - Ollama (`qwen3:latest`)
 - Google (`gemini-embedding-2`)
 - Mistral (`mistral-embed`)
+- OpenRouter (`openai/text-embedding-3-small`)
+- Bedrock (the model is given per call)
 
 ### Vector stores (OpenAI)
 

data/docs/deepdive/features/files.md

@@ -0,0 +1,52 @@
+
+## Files
+
+### Introduction
+
+#### Overview
+
+Some providers keep files you upload, and let a later request refer to
+one by id instead of resending its bytes. The Files API is how a file
+is uploaded, listed, fetched, downloaded, and deleted, and a file id is
+then passed to an endpoint that reads it.
+
+#### How it works
+
+Call the file methods on a provider that implements them. `create`
+uploads a file and returns its record, `get` reads a record, `download`
+returns the bytes, `all` lists the files, and `delete` removes one:
+
+```ruby
+require "llm"
+
+llm  = LLM.openai(key: ENV["KEY"])
+ctx  = LLM::Context.new(llm)
+
+file = llm.files.create(file: "/books/goodread.pdf")
+ctx.talk ["Tell me about this PDF", file]
+
+llm.files.all                         # every uploaded file
+llm.files.get(file: file.id)          # one file's record
+llm.files.download(file: file.id)     # its bytes, under #file
+llm.files.delete(file: file.id)
+```
+
+`create` takes a path, an `LLM::File`, or a `File` object, and a
+`purpose:` that tells the provider what the file is for. An uploaded
+file carries its id, so it can be passed to a turn directly, as above,
+and a response from `download` exposes the bytes through `#file`.
+
+#### Why would I use it?
+
+A file that a provider stores can be reused across requests without
+being uploaded each time. That keeps a large document or an image out
+of the request body, and it is how OpenAI's vector stores, and the
+assistants that read them, get their content.
+
+#### Notes
+
+OpenAI, Anthropic, and Google implement the Files API; a provider that
+does not raises `NotImplementedError`. `download` is OpenAI-only. A
+file id belongs to the provider that minted it: DeepSeek, for example,
+has no Files API and raises `LLM::PromptError` when it is handed a file
+id from another provider.

data/docs/deepdive/features/moderations.md

@@ -0,0 +1,48 @@
+
+## Moderations
+
+### Introduction
+
+#### Overview
+
+A moderation classifies text or an image against a set of harm
+categories, so an application can decide what to do with it before
+showing it, storing it, or sending it to a model. OpenAI hosts the
+moderation endpoint.
+
+#### How it works
+
+Call `llm.moderations` with the content to check. The response lists a
+moderation per input, and each one reports whether it was flagged, the
+categories it matched, and their scores:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+
+res = llm.moderations.create(input: "I hate you")
+mod = res.moderations[0]
+
+mod.flagged?     # => true
+mod.categories   # the categories that matched
+mod.scores       # a score per category
+```
+
+`input` accepts a string or a URL, so an image URL is classified the
+same way text is.
+
+#### Why would I use it?
+
+A moderation is a cheap check that runs before an expensive or public
+step. Screen user-generated content before publishing it, gate a
+request before it reaches a model, or keep a record of what was
+filtered and why.
+
+#### Notes
+
+Only OpenAI implements moderations; another provider raises
+`NotImplementedError`. The default model is `omni-moderation-latest`,
+and it classifies both text and images. The scores are model
+estimates, so a threshold is a product decision rather than a fixed
+value.

data/docs/deepdive/features/responses.md

@@ -0,0 +1,54 @@
+
+## Responses
+
+### Introduction
+
+#### Overview
+
+OpenAI's Responses API gives every reply an id, and a later call can
+continue from one by passing `previous_response_id:`. When the provider
+is asked to store the reply, it keeps the history, so a client can hand
+the thread back instead of resending it.
+
+#### How it works
+
+Create a response with `llm.responses.create`, then continue it by
+passing `previous_response_id:` the id of the last one. A response can
+be read back with `get` and removed with `delete`:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+
+first  = llm.responses.create "Your task is to answer the user's questions",
+                              role: :developer
+second = llm.responses.create "5 + 5 = X ?",
+                              role: :user,
+                              previous_response_id: first.id
+
+puts second.content
+
+llm.responses.get(second)     # read it back
+llm.responses.delete(second)  # remove it
+```
+
+`create` accepts the same prompt shapes as a completion (a string or a
+list), plus `role:`, `model:`, `tools:`, and a `stream:` target. It
+returns an `LLM::Response` like any other call.
+
+#### Why would I use it?
+
+Server-side state means the conversation lives with the provider
+instead of in the request. Passing one id continues a thread without
+rebuilding and resending the messages, which keeps requests small and
+lets a client that lost its local history pick the thread back up.
+
+#### Notes
+
+Only OpenAI implements the Responses API. A context in `mode:
+:responses` uses this endpoint and defaults to `store: false`, so the
+conversation is not kept on the provider and the context rebuilds the
+input itself; set `store: true` to keep it there and have the next turn
+continue with `previous_response_id`. A plain `llm.responses.create`
+call continues only when `previous_response_id:` is given.

data/docs/deepdive/fundamentals/agents.md

@@ -21,8 +21,9 @@ 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
 [`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.
+(see the Tool budget section). Instructions are injected once and
+brought up to date from the agent before each request, unless the
+prompt already carries a system message of the caller's own.
 
 #### Why would I use it?
 
@@ -245,9 +246,12 @@ of hanging.
 
 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 defaults to five for agents, while a raw
+`Net::OpenTimeout` and `Net::ReadTimeout`); other errors are 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)
-defaults to zero (`retry_budget: 0`). A 429 is refused before any
-content streams, so retrying the same request loses nothing. Pass
-`retry_budget: 0` to disable retries on an agent.
+defaults to zero (`retry_budget: 0`), so retries are opt-in there. A
+429 is refused before any content streams, so retrying the same
+request loses nothing. Pass `retry_budget: 0` to disable retries on
+an agent.

data/docs/deepdive/fundamentals/providers.md

@@ -92,6 +92,43 @@ missing model or registry raises `LLM::NoSuchModelError` or
 `LLM::NoSuchRegistryError`, which the runtime rescues to default
 gracefully (for example, an unknown context window reads as `nil`).
 
+### Model listings
+
+#### Overview
+
+The registry is the catalog llm.rb ships. A provider can also list the
+models it serves right now, which shows a model added since your copy
+of `data/` was written, or one available to your account alone.
+
+#### How it works
+
+A provider with a models endpoint exposes it through `llm.models`, and
+`all` returns the list:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+llm.models.all.each { puts _1.id }
+```
+
+OpenAI, Anthropic, Google, Bedrock, and Ollama implement it. Bedrock
+lists the foundation models in the configured region and accepts
+`byProvider:` to narrow the list; Ollama lists the models pulled into
+the local daemon.
+
+#### Why would I use it?
+
+A shipped catalog goes stale between releases. Asking the provider
+keeps a model picker current and reveals models the catalog does not
+know about.
+
+#### Notes
+
+Not every provider implements a models endpoint; calling `models` on
+one that does not raises `NotImplementedError`. Unlike the registry,
+the call needs credentials.
+
 ### Request headers
 
 #### Overview

data/docs/deepdive/fundamentals/schema.md

@@ -178,3 +178,53 @@ DSL builds, so the result is used the same way.
 An unsupported `type`, an unresolvable `$ref`, or a `$ref` that does
 not start with `#/` raises `TypeError`. When a schema omits `type`,
 the parser infers it from `const`, `enum`, or `default`.
+
+### Deferred types
+
+#### Overview
+
+A property or parameter type can be given as a block, in which case the
+type is worked out when the schema is serialized rather than when the
+class that declares it is defined. That is how a type that only exists
+at runtime, such as the values a store holds right now, is described.
+
+#### How it works
+
+Pass a block in place of the type. It is called each time the schema is
+serialized, and whatever it returns is resolved in turn, so it can
+return a leaf, a class, or an array of either:
+
+```ruby
+class Article < LLM::Schema
+  property :kind, proc { LLM::Schema::Enum[*Article.kinds] }, "The article kind"
+  required %i[kind]
+end
+```
+
+The same works for a tool parameter:
+
+```ruby
+class Publish < LLM::Tool
+  name "publish"
+  parameter :kind, proc { LLM::Schema::Enum[*Article.kinds] }, "The article kind"
+  required %i[kind]
+
+  def call(kind:)
+    Article.publish(kind:)
+  end
+end
+```
+
+#### Why would I use it?
+
+A schema is a class-level definition, but the choices it offers are
+sometimes only known when a request is made. A deferred type lets the
+schema be declared once and still send the values that are current at
+the time of the request.
+
+#### Notes
+
+The block is called on every serialization, so it runs once per
+request and sees the latest values. Everything a leaf accepts, such as
+`required`, `default`, and `enum`, is applied to the resolved leaf
+after the block returns.

data/docs/deepdive/fundamentals/stream.md

@@ -67,6 +67,17 @@ receives tokens as they arrive.
 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.
+[`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
+request and the next: the response is in the conversation, and a
+turn that asked for tools runs them after this while a turn that is
+finished ends here. That boundary is where a conversation is whole,
+and the runtime's
+[`LLM::Step`](https://r.uby.dev/api-docs/llm.rb/LLM/Step.html) is
+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)
 fires each time a failed request is retried. Compaction hooks
 let you show progress or log what was trimmed. Skill hooks bracket a
@@ -96,6 +107,11 @@ class MyStream < LLM::Stream
   def on_tool_return(tool, result)
   end
 
+  # A request has completed: the response is in the conversation, and
+  # any tools it asked for run after this.
+  def on_step(ctx, res)
+  end
+
   # Before a transformer rewrites an outgoing message.
   def on_transform(transformer)
   end
@@ -135,9 +151,3 @@ agent.talk "Explain Ruby fibers."
 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/docs/deepdive/fundamentals/tools.md

@@ -435,6 +435,12 @@ needs most. See the
 The tools that spawn subprocesses use the optional `test-cmd.rb`
 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.
+[`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.
+
 ### Interrupts
 
 #### Overview

data/docs/deepdive/reference/object.md

@@ -61,6 +61,12 @@ 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).
 
+The adapter is `LLM::JSONAdapter::JSON`, the standard library, by
+default. Set `LLM.json = :oj` or `LLM.json = :yajl` to use a faster
+backend when the matching gem is present; every adapter normalizes
+strings to valid UTF-8 before it serializes, so the choice affects
+speed rather than behavior.
+
 ### Reading and writing
 
 #### Overview

data/docs/deepdive/reference/response.md

@@ -0,0 +1,55 @@
+
+## LLM::Response
+
+### Introduction
+
+#### Overview
+
+Every call returns an
+[`LLM::Response`](https://r.uby.dev/api-docs/llm.rb/LLM/Response.html).
+It is one normalized shape that a provider, an endpoint, or a context
+extends with the accessors that response needs, so chat completions,
+embeddings, images, and OCR all share a common surface without losing
+their own.
+
+#### How it works
+
+`LLM::Response` carries the transport response and a little common
+state: `#res` (the underlying HTTP response), `#body` (the parsed body,
+or a raw string), `#ok?`, `#id`, and `#file?`. A name the base class
+does not define falls through to the body, so a provider field such as
+`content` is reachable directly.
+
+A completion response also includes
+[`LLM::Contract::Completion`](https://r.uby.dev/api-docs/llm.rb/LLM/Contract/Completion.html),
+which adds the pieces a chat reply needs:
+
+```ruby
+res = agent.talk "Weather in Paris?", schema: Weather
+
+res.content            # the raw text, or the structured reply
+res.content!           # the reply parsed as an LLM::Object
+res.messages           # the messages this turn produced
+res.usage              # an LLM::Usage (input, output, reasoning, cache, ...)
+res.reasoning_content  # the model's reasoning, when the provider exposes it
+res.model              # the model that answered
+```
+
+#### Why would I use it?
+
+One shape means one set of methods to learn: the same `content!`,
+`usage`, and `messages` work whatever the provider. When an endpoint
+returns something shaped differently, it adds an accessor rather than
+changing the contract.
+
+#### Notes
+
+`#usage` returns an
+[`LLM::Usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Usage.html), so
+token counts are read the same way everywhere; the individual token
+readers (`input_tokens`, `output_tokens`, `cache_read_tokens`, and so
+on) live on the completion contract. Endpoint-specific accessors such
+as `images`, `pages`, `audio`, or `embeddings` come from the adapter
+that extends the response, so they are present only on responses that
+carry that data. `#content!` parses the content as JSON, which is the
+read to use with a schema.

data/docs/deepdive.md

@@ -68,6 +68,9 @@ is the best place to start if you are new to llm.rb.
 - [Built-in tools](deepdive/features/builtin_tools.md)
 - [Concurrency](deepdive/features/concurrency.md)
 - [Embeddings](deepdive/features/embeddings.md)
+- [Files](deepdive/features/files.md)
+- [Moderations](deepdive/features/moderations.md)
+- [Responses](deepdive/features/responses.md)
 - [Database](deepdive/features/database.md)
 - [Console](deepdive/features/console.md)
 
@@ -88,6 +91,7 @@ is the best place to start if you are new to llm.rb.
 
 ## Reference
 
+- [LLM::Response](deepdive/reference/response.md)
 - [LLM::Object](deepdive/reference/object.md)
 - [LLM::Cost](deepdive/reference/cost.md)
 - [Tracer](deepdive/reference/tracer.md)

data/lib/llm/active_record/acts_as_llm.rb

@@ -56,21 +56,23 @@ module LLM::ActiveRecord
 
     module InstanceMethods
       ##
-      # Continues the stored context with new input and flushes it.
+      # Continues the stored context with new input.
+      #
+      # The conversation is saved by {LLM::Step LLM::Step} at each request.
       # @see LLM::Context#talk
       # @return [LLM::Response]
       def talk(...)
-        options = self.class.llm_plugin_options
-        ctx.talk(...).tap { Utils.save!(self, ctx, options) }
+        ctx.talk(...)
       end
 
       ##
-      # Continues the stored context with new input and flushes it.
+      # Continues the stored context with new input.
+      #
+      # The conversation is saved by {LLM::Step LLM::Step} at each request.
       # @see LLM::Context#ask
       # @return [LLM::Response]
       def ask(...)
-        options = self.class.llm_plugin_options
-        ctx.ask(...).tap { Utils.save!(self, ctx, options) }
+        ctx.ask(...)
       end
 
       ##
@@ -101,7 +103,8 @@ module LLM::ActiveRecord
       # unordered - conversation order is `position`, not `id` - and its rows
       # are {LLM::ActiveRecord::Message} records until
       # {LLM::ActiveRecord::Message#unwrap!} turns them back into
-      # {LLM::Message} objects.
+      # {LLM::Message} objects. {#messages!} is the runtime's own collection,
+      # for a caller who wants that instead.
       # @see LLM::Context#messages
       # @return [ActiveRecord::Relation, LLM::Buffer]
       def messages
@@ -113,6 +116,20 @@ module LLM::ActiveRecord
         end
       end
 
+      ##
+      # Returns the messages the runtime holds, whatever the storage format is.
+      #
+      # This is what {#messages} answers with for every format but jsonb, and
+      # it is the way back to it for a jsonb record. The difference between
+      # the two is what each reads: this reads what the context holds,
+      # including state that has not been saved, where {#messages} reads the
+      # column.
+      # @see LLM::Context#messages
+      # @return [LLM::Buffer]
+      def messages!
+        ctx.messages
+      end
+
       ##
       # @note The bang keeps the ActiveRecord and Sequel wrappers aligned.
       # @see LLM::Context#model

data/lib/llm/agent.rb

@@ -15,7 +15,10 @@ module LLM
   # instead of leaving tool loops to the caller.
   #
   # **Notes:**
-  # * Instructions are injected once unless a system message is already present.
+  # * Instructions are injected once, and kept in step after that. A
+  #   restored conversation carries the instructions that were current
+  #   when it started, and the message is brought up to date before the
+  #   next request goes out.
   # * An agent automatically executes tool loops (unlike {LLM::Context LLM::Context}).
   # * The tool loop can be bounded with `tool_budget`. Once the budget is
   #   spent, no further tool calls are run for that turn: the agent sends an
@@ -53,6 +56,14 @@ module LLM
     UNDEFINED = Object.new
     private_constant :UNDEFINED
 
+    ##
+    # Marks the message an agent injects as its own, so that a later
+    # turn can tell it from a message the caller composed. The role
+    # cannot do that: it is true of whatever the caller put there.
+    # @api private
+    INSTRUCTIONS = {instructions: true}.freeze
+    private_constant :INSTRUCTIONS
+
     ##
     # Ugh :)
     # @api private
@@ -441,7 +452,10 @@ module LLM
       # knows its own API, and how often it recovers from a
       # rate limit rather than failing outright.
       params[:retry_budget] = llm.retry_budget if params[:retry_budget].equal?(UNDEFINED)
-      @ctx = LLM::Context.new(llm, params)
+      ##
+      # The context is bound to the same record the agent holds, so code
+      # written against a context alone can find it through `ctx.record`.
+      @ctx = LLM::Context.new(llm, params.merge(record: @record).compact)
       @path and File.readable?(@path) ? @ctx.restore(path:) : nil
     end
 
@@ -799,27 +813,92 @@ module LLM
     # @return [LLM::Prompt]
     def apply_instructions(new_prompt)
       return new_prompt unless @instructions
+      ##
+      # A prompt that carries a system message of its own is the
+      # caller's, and the instructions already in the conversation are
+      # left as they are. The context is deliberately not consulted: a
+      # restored context always holds the message this exists to bring
+      # up to date, which is what `inject_instructions?` tests for.
+      refresh_instructions! unless carries_system_message?(new_prompt)
       if LLM::Prompt === new_prompt
-        new_prompt.system(@instructions) if inject_instructions?(new_prompt)
+        new_prompt.system(@instructions, extra: INSTRUCTIONS) if inject_instructions?(new_prompt)
         new_prompt
       else
         prompt do
-          _1.system(@instructions) if inject_instructions?
+          _1.system(@instructions, extra: INSTRUCTIONS) if inject_instructions?
           _1.user(new_prompt)
         end
       end
     end
 
+    ##
+    # Brings the instructions stored in the conversation up to date.
+    #
+    # The message is identified by the mark the agent put on it when it
+    # injected it, and not by its role or its position. A role is true
+    # of whatever the caller put there - on a provider whose system role
+    # is `:user`, the first message of a conversation the caller seeded
+    # is a user message too - so a rule written on either of those
+    # replaces a message that was never the agent's to replace.
+    #
+    # A message with no mark is left alone, which is the safe direction:
+    # a conversation written before the mark existed keeps its stale
+    # instructions rather than losing a message. Stale is recoverable.
+    #
+    # An agent with no instructions returns first. The caller reaches
+    # this through `apply_instructions`, which already returns early for
+    # the same reason, and the guard is repeated here so that the method
+    # cannot replace a message with nil however it is reached.
+    #
+    # Comparing content rather than the message is deliberate.
+    # {LLM::Message#==} compares everything a message carries apart from
+    # its id, which drags fields that have nothing to do with
+    # instructions into the comparison. The mark is carried onto the
+    # replacement so that the turn after this one can still find it, and
+    # so is the role the message already had: it is the provider's, and
+    # rebuilding it here would undo the reason the replacement is safe.
+    # @api private
+    # @return [void]
+    def refresh_instructions!
+      return unless @instructions
+      message = @ctx.messages.first
+      return unless message&.extra&.key?(:instructions)
+      return if message.content == @instructions
+      @ctx.messages.replace(
+        [LLM::Message.new(message.role, @instructions, message.extra), *@ctx.messages.drop(1)]
+      )
+    end
+
+    ##
+    # Returns true when a prompt carries a system message of its own.
+    #
+    # This is the half of `inject_instructions?` that asks about the
+    # prompt rather than about the context, and it is the one a refresh
+    # needs. The context half says "do not inject again", which is not
+    # the same question as "whose instructions are these".
+    #
+    # The role asked about is the provider's: a prompt's `system` is
+    # built with the role the provider gives instructions, which is not
+    # the string "system" everywhere.
+    # @param [LLM::Prompt, Object] prompt
+    # @return [Boolean]
+    def carries_system_message?(prompt)
+      role = @llm.system_role.to_s
+      LLM::Prompt === prompt && prompt.to_a.any? { _1.role.to_s == role }
+    end
+
     ##
     # Returns true when agent instructions should be injected for the turn.
-    # Instructions are injected once unless a system message is already
-    # present in the existing context or the prompt being sent.
+    # Instructions are injected once unless a message with the provider's
+    # system role is already present in the existing context or the prompt
+    # being sent.
     # @param [LLM::Prompt, nil] prompt
     # @return [Boolean]
     def inject_instructions?(prompt = nil)
-      return false if @ctx.messages.any?(&:system?)
+      role = @llm.system_role.to_s
+      return false if @ctx.messages.any? { _1.role.to_s == role }
       return true if prompt.nil?
-      !prompt.to_a.any?(&:system?)
+      !prompt.to_a.any? { _1.role.to_s == role }
     end
 
     ##

data/lib/llm/context/deserializer.rb

@@ -40,6 +40,19 @@ class LLM::Context
 
     private
 
+    ##
+    # Rebuilds one message from a payload.
+    #
+    # The fields that describe a message are named here rather than
+    # taken from everything the payload holds, so a field that
+    # {LLM::Message#to_h} writes has to be read here as well - and one
+    # that is not named is dropped on the way in, whatever the payload
+    # carries. `instructions` marks the message an agent injected as its
+    # own, and the agent looks for that mark rather than for a role or a
+    # position when it refreshes the instructions in a restored
+    # conversation.
+    # @param [Hash] payload
+    # @return [LLM::Message]
     def deserialize_message(payload)
       tool_calls = deserialize_tool_calls(payload["tools"])
       returns = deserialize_returns(payload["content"]) if returns.nil?
@@ -47,8 +60,18 @@ class LLM::Context
       usage = payload["usage"]
       reasoning_content = payload["reasoning_content"]
       compaction = payload["compaction"]
+      instructions = payload["instructions"]
       id = payload["id"]
-      extra = {tool_calls:, original_tool_calls:, tools: @params[:tools], usage:, reasoning_content:, compaction:, id:}.compact
+      extra = {
+        tool_calls:,
+        original_tool_calls:,
+        tools: @params[:tools],
+        usage:,
+        reasoning_content:,
+        compaction:,
+        instructions:,
+        id:
+      }.compact
       content = returns.nil? ? deserialize_content(payload["content"]) : returns
       LLM::Message.new(payload["role"], content, extra)
     end

data/lib/llm/context.rb

@@ -222,6 +222,7 @@ module LLM
         @messages.concat(prompt)
       end
       @messages.concat([res.choices[-1]].compact)
+      stream.on_step(self, res)
       res
     ensure
       @owner = nil

data/lib/llm/message.rb

@@ -46,6 +46,12 @@ module LLM
 
     ##
     # Returns a Hash representation of the message.
+    #
+    # This is the whole of a message as far as storage is concerned:
+    # {LLM::Context#to_h} maps its messages through here, and restore
+    # reads them back from the same list. A field that is not named
+    # here does not survive a save, so a field the runtime relies on
+    # after a restore has to be named.
     # @return [Hash]
     def to_h
       {
@@ -54,6 +60,7 @@ module LLM
         content:,
         reasoning_content:,
         compaction: extra.compaction,
+        instructions: extra.instructions,
         tools: extra.tool_calls&.map { LLM::Object === _1 ? _1.to_h : _1 },
         usage:,
         original_tool_calls: extra.original_tool_calls

data/lib/llm/prompt.rb

@@ -40,40 +40,51 @@ class LLM::Prompt
   #  The message
   # @param [Symbol] role
   #  The role (eg user, system)
+  # @param [Hash, nil] extra
+  #  Fields carried alongside the message. A caller that composes a
+  #  message of its own can mark it here, and the runtime reads the
+  #  mark back rather than inferring it from the role.
   # @return [void]
-  def talk(content, role: @provider.user_role)
+  def talk(content, role: @provider.user_role, extra: nil)
     role = case role.to_sym
     when :system then @provider.system_role
     when :user then @provider.user_role
     when :developer then @provider.developer_role
     else role
     end
-    @buffer << LLM::Message.new(role, content)
+    message = extra ? LLM::Message.new(role, content, extra) : LLM::Message.new(role, content)
+    @buffer << message
   end
   alias_method :chat, :talk
 
   ##
   # @param [String] content
   #  The message content
+  # @param [Hash, nil] extra
+  #  Fields carried alongside the message
   # @return [void]
-  def user(content)
-    talk(content, role: @provider.user_role)
+  def user(content, extra: nil)
+    talk(content, role: @provider.user_role, extra:)
   end
 
   ##
   # @param [String] content
   #  The message content
+  # @param [Hash, nil] extra
+  #  Fields carried alongside the message
   # @return [void]
-  def system(content)
-    talk(content, role: @provider.system_role)
+  def system(content, extra: nil)
+    talk(content, role: @provider.system_role, extra:)
   end
 
   ##
   # @param [String] content
   #  The message content
+  # @param [Hash, nil] extra
+  #  Fields carried alongside the message
   # @return [void]
-  def developer(content)
-    talk(content, role: @provider.developer_role)
+  def developer(content, extra: nil)
+    talk(content, role: @provider.developer_role, extra:)
   end
 
   ##

data/lib/llm/sequel/plugin.rb

@@ -155,21 +155,23 @@ module LLM::Sequel
     Utils = Plugin::Utils
 
     ##
-    # Continues the stored context with new input and flushes it.
+    # Continues the stored context with new input.
+    #
+    # The conversation is saved by {LLM::Step LLM::Step} at each request.
     # @see LLM::Context#talk
     # @return [LLM::Response]
     def talk(...)
-      options = self.class.llm_plugin_options
-      ctx.talk(...).tap { Utils.save!(self, ctx, options) }
+      ctx.talk(...)
     end
 
     ##
-    # Continues the stored context with new input and flushes it.
+    # Continues the stored context with new input.
+    #
+    # The conversation is saved by {LLM::Step LLM::Step} at each request.
     # @see LLM::Context#ask
     # @return [LLM::Response]
     def ask(...)
-      options = self.class.llm_plugin_options
-      ctx.ask(...).tap { Utils.save!(self, ctx, options) }
+      ctx.ask(...)
     end
 
     ##
@@ -199,6 +201,17 @@ module LLM::Sequel
       ctx.messages
     end
 
+    ##
+    # @note The same call {#messages} makes here, and here for the sake of the
+    #   name: on {LLM::ActiveRecord} the two differ for a jsonb record, and a
+    #   wrapper that answered to a name the other one does not is the next
+    #   reader's surprise.
+    # @see LLM::Context#messages
+    # @return [LLM::Buffer]
+    def messages!
+      ctx.messages
+    end
+
     ##
     # @note The bang is used because Sequel reserves `model` for the
     #   underlying model class on instances.

data/lib/llm/step.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # Writes the conversation down when a request completes.
+  #
+  # {LLM::Step LLM::Step} is prepended onto a stream's singleton class by
+  # {LLM::Stream.try}, so a conversation bound to a record is saved as it goes:
+  # a turn that is interrupted - by a crash, by a deploy, or by a provider that
+  # refuses - can be continued rather than started over.
+  #
+  # It saves through the record the context is bound to ({LLM::Context#record}),
+  # and it knows both the ORMs llm.rb speaks: an ActiveRecord model is saved
+  # with {LLM::ActiveRecord::Utils.save!} and a Sequel model with
+  # {LLM::Sequel::Plugin::Utils.save!}. A context with no record - which is
+  # every context that is not backed by a model - has nothing to save, and
+  # neither has a record that carries neither plugin, so the step is passed
+  # along untouched.
+  #
+  # All of this is one method on purpose. The module is put onto an object the
+  # caller owns, and a helper would be one more name on that object for as long
+  # as it lives.
+  #
+  # The write is best effort: a failure is swallowed rather than raised, because
+  # this runs inside the request that has just completed, and a stale checkpoint
+  # is a smaller failure than a turn that ends because the database was busy.
+  # Only the write is covered, so a stream's own `on_step` is reached whether or
+  # not the write lands - a step that a tracer hears about does not depend on a
+  # database having been free.
+  #
+  # @see LLM::Stream#on_step
+  # @see LLM::ActiveRecord::Utils.save!
+  module Step
+    ##
+    # Saves the conversation the context holds, then passes the step along.
+    #
+    # @param [LLM::Context] ctx
+    #  The context the request belongs to
+    # @param [LLM::Response] res
+    #  The response for the request that completed
+    # @return [nil]
+    def on_step(ctx, res)
+      record = ctx.record
+      if record and record.class.respond_to?(:llm_plugin_options)
+        options = record.class.llm_plugin_options
+        begin
+          if defined?(::ActiveRecord::Base) and ::ActiveRecord::Base === record
+            LLM::ActiveRecord::Utils.save!(record, ctx, options)
+          elsif defined?(::Sequel::Model) and ::Sequel::Model === record
+            LLM::Sequel::Plugin::Utils.save!(record, ctx, options)
+          end
+        rescue
+          nil
+        end
+      end
+      super
+    end
+  end
+end

data/lib/llm/stream.rb

@@ -37,10 +37,12 @@ module LLM
   #
   # @see LLM::Agent Where streams are typically attached
   # @see LLM::Context Where streams are bound per-turn
+  # @see LLM::Step An extension that saves the conversation at each step
   class Stream
     require_relative "stream/queue"
     require_relative "stream/io"
     require_relative "stream/disabled"
+    require_relative "step"
 
     ##
     # This method will try to convert its argument into
@@ -51,18 +53,22 @@ module LLM
     # objects, IO objects who implement `#<<`, true, false,
     # and nil. Anything else raises a TypeError.
     #
+    # The stream it answers with is ready to be told about a step:
+    # {LLM::Step LLM::Step} is prepended onto it here, once, rather than by
+    # every caller that means to save a conversation.
+    #
     # @raise [TypeError]
     # @param [LLM::Stream, #<<, Boolean, NilClass] obj
     # @return [LLM::Stream]
     def self.try(obj, extra: {})
       if LLM::Stream === obj
-        obj.tap { _1.extra.merge!(extra) }
+        obj.tap { _1.extra.merge!(extra) }.tap { _1.singleton_class.prepend(LLM::Step) }
       elsif obj.respond_to?(:<<)
-        LLM::Stream::IO.new(obj).tap { _1.extra.merge!(extra) }
+        LLM::Stream::IO.new(obj).tap { _1.extra.merge!(extra) }.tap { _1.singleton_class.prepend(LLM::Step) }
       elsif obj == true
-        LLM::Stream.new.tap { _1.extra.merge!(extra) }
+        LLM::Stream.new.tap { _1.extra.merge!(extra) }.tap { _1.singleton_class.prepend(LLM::Step) }
       elsif obj.nil? || obj == false
-        LLM::Stream::Disabled.new.tap { _1.extra.merge!(extra) }
+        LLM::Stream::Disabled.new.tap { _1.extra.merge!(extra) }.tap { _1.singleton_class.prepend(LLM::Step) }
       else
         raise TypeError, "invalid stream object"
       end
@@ -152,6 +158,32 @@ module LLM
       nil
     end
 
+    ##
+    # Called when a request in a turn has completed.
+    #
+    # This is the boundary between one request and the next: the response
+    # is in the context's message history, and a turn that asked for tools
+    # runs them after this while a turn that is finished ends here.
+    #
+    # It is emitted once per successful request, so a request that is
+    # retried after a rate limit or a timeout calls this when it lands and
+    # not once per attempt. It is also emitted when the stream is disabled:
+    # a disabled stream has no output to report, but it is still told that
+    # a step ended.
+    #
+    # The context is passed with the response so that a stream does not have
+    # to reach for it: {LLM::Step LLM::Step}, which saves the conversation the
+    # context holds, is written against this callback alone.
+    #
+    # @param [LLM::Context] ctx
+    #  The context the request belongs to
+    # @param [LLM::Response] res
+    #  The response for the request that completed
+    # @return [nil]
+    def on_step(ctx, res)
+      nil
+    end
+
     ##
     # Called before a context transformer rewrites a prompt.
     # @param [LLM::Transformer] transformer

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "16.0.0.pre.3"
+  VERSION = "16.0.0.pre.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 16.0.0.pre.3
+  version: 16.0.0.pre.5
 platform: ruby
 authors:
 - Robert Gleeson
@@ -400,6 +400,9 @@ files:
 - docs/deepdive/features/console.md
 - docs/deepdive/features/database.md
 - docs/deepdive/features/embeddings.md
+- docs/deepdive/features/files.md
+- docs/deepdive/features/moderations.md
+- docs/deepdive/features/responses.md
 - docs/deepdive/fundamentals/agents.md
 - docs/deepdive/fundamentals/providers.md
 - docs/deepdive/fundamentals/schema.md
@@ -414,6 +417,7 @@ files:
 - docs/deepdive/reference/cost.md
 - docs/deepdive/reference/model_registry.md
 - docs/deepdive/reference/object.md
+- docs/deepdive/reference/response.md
 - docs/deepdive/reference/tracer.md
 - lib/llm.rb
 - lib/llm/a2a.rb
@@ -642,6 +646,7 @@ files:
 - lib/llm/server_tool.rb
 - lib/llm/session.rb
 - lib/llm/skill.rb
+- lib/llm/step.rb
 - lib/llm/stream.rb
 - lib/llm/stream/disabled.rb
 - lib/llm/stream/io.rb