llm.rb 16.0.0.pre.2 → 16.0.0.pre.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61578ce1082ecd25f86574ef19e1ffd4cc2b68c6689b705f0544f4aa3e391ede
-  data.tar.gz: 742b8d66f49113389c5ff08772e79498334eb6d5afe9821f05c2b8d1851cf4e8
+  metadata.gz: a83847d3c33a48980bd9740d7aff397db757ec91224440a97c10240c0ae3a290
+  data.tar.gz: 402d6ea4a68fc987e3597d1b6dd84089f2804c7774ef35e38fb8fc424b0e62b0
 SHA512:
-  metadata.gz: d0024edabc9ac7360a71a485362aed854644187c116777623b340e5fbd391ae257139aefe07ba29ce7fe9bf04573e66ff09c0f48024153833cbb28b385e13280
-  data.tar.gz: ec0b4f0b2ba6a66b38cd324c5c3ea6daccd4ff76cde43a1fa8c272c20da89bec735ff7b7bae3afb516d4b5a3131b4e383abe70f48365d6ba9c8a61028e233c48
+  metadata.gz: f75dda6e725c6aa48748a407e744c94c006d3db4973cf45064f7f0252fc2bc818ee7a99b564e66c4bad6ad4066bf5214b912a637b3b25b8b9f335d45d226c7e2
+  data.tar.gz: ea3e7fe4a32687c7a34f4b85a0bd4aeee5b7b68387452dd1ac98a3572f1b1f74b4f19ac3ee32b10cf6f53563b9eceb5a8e9292e6001b90728e4997c7b9a301a2

data/CHANGELOG.md

@@ -22,6 +22,7 @@
 | Old | New |
 |-----|-----|
 | Ruby 3.3 or later | Ruby 3.4 or later |
+| `record.messages` returns the messages the runtime holds | a `:jsonb` record returns a relation of `LLM::ActiveRecord::Message` rows |
 
 * **drop Ruby 3.3 support** <br>
   The gem now requires Ruby 3.4 or later: `required_ruby_version` is
@@ -30,6 +31,31 @@
   cancel that arrives before the tool starts is not delivered there, while
   Ruby 3.4 and 4.0 both deliver it.
 
+* **activerecord: read a `:jsonb` record's messages from the column** <br>
+  [`LLM::ActiveRecord`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord.html)
+  now answers `#messages` for a record whose `format` is `:jsonb` with an
+  [`ActiveRecord::Relation`](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html)
+  over the column, through
+  [`LLM::ActiveRecord::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html),
+  so a conversation can be filtered, counted, and ordered in SQL, and reading it
+  needs no provider and no credentials. Before this, every record loaded the
+  runtime and returned the messages it held, whatever the format. The relation
+  is not a drop-in replacement for that buffer: it reads what is persisted
+  rather than what a runtime holds in memory, it is unordered, so order by
+  `position`, and its rows answer `unwrap!` rather than being
+  [`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`.
+
 ### Console
 
 * **console: erase with the backspace key on OpenBSD** <br>
@@ -39,6 +65,13 @@
   terminal's terminfo describes the key. All three erase. Before this only 127
   did, so the backspace key did nothing on the OpenBSD console.
 
+### Fix
+
+* **fork: require xchan.rb `~> 0.24`** <br>
+  The `:fork` concurrency strategy now requires the `xchan.rb` gem at `~> 0.24`
+  instead of `~> 0.23`, and the gemspec's development dependency follows. An
+  application that uses `:fork` needs `xchan.rb` 0.24 or later.
+
 ### Function
 
 * **function: deliver an interrupt to the tool, not to whatever is running** <br>
@@ -77,6 +110,38 @@
   side effects happening and its result written to a queue nobody read, and the
   reactor thread stayed alive until a group's `wait` stopped it.
 
+* **function: run the interrupt hook on every strategy** <br>
+  A tool that implements
+  [`LLM::Tool#on_interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#on_interrupt-instance_method)
+  or
+  [`LLM::Tool#on_cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#on_cancel-instance_method)
+  is now told on every concurrency strategy. `:thread`, `:fiber`, and `:async`
+  run the hook on the thread or fiber that ran the call, `:fork` and `:ractor`
+  run it inside the child or the ractor before the interrupt is delivered, and
+  a sequential group's cancel tells every task it holds. Before this, `:async`,
+  `:fork`, and `:ractor` never ran the hook, the others ran it on the thread
+  that cancelled, and a class-backed tool ran it on no strategy at all, because
+  `interrupt!` read the hook off the tool's definition and a class answers
+  `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.
+
 ### Provider
 
 * **deepseek: support image attachments in chat completions** <br>
@@ -97,13 +162,39 @@
   `qwen3.5-flash`, `qwen3.7-flash`, and `qwen3.8-omni-flash`, and gives
   `qwen3.7-plus` attachments, structured output, and a lower price; OpenAI adds
   `gpt-daybreak-blue-latest` and `gpt-daybreak-red-latest`; Bedrock adds
-  `openai.gpt-6-sol` and `openai.gpt-6-luna`; and DeepInfra adds
-  `tencent/Hy4-preview` and the Xiaomi MiMo V2.6 Pro and V2.6 Flash models.
+  `openai.gpt-6-sol`, `openai.gpt-6-luna`, and
+  `global.anthropic.claude-sonnet-5-5`; and DeepInfra adds `tencent/Hy4-preview`
+  and the Xiaomi MiMo V2.6 Pro and V2.6 Flash models.
   Bedrock also corrects the context and output limits of fifteen models, Google
   lowers the limits of `gemini-2.5-computer-use-preview-10-2025` and
-  `gemini-3-pro-image`, and OpenRouter adds four models, drops six, and reprices
+  `gemini-3-pro-image`, and OpenRouter adds five models, drops six, and reprices
   many of the DeepSeek, Z.ai, and Qwen entries.
 
+### Schema
+
+* **schema: apply every `parameter` option to the leaf** <br>
+  [`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) now applies each
+  option given to `parameter` to the leaf its type resolves to, so settings such
+  as `min:`, `max:`, `multiple_of:`, and `const:` reach the schema instead of
+  being dropped. Before this only `required`, `default`, and `enum` were read, so
+  `parameter :age, Integer, "Age", min: 1, max: 9` sent a plain integer and lost
+  the range. A `default:` of `false` survives now as well, where the old code
+  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/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
 

data/docs/deepdive/features/database.md

@@ -407,6 +407,26 @@ you write across every agent is not covered by default; index the state
 column for those, for example with a GIN index on
 `data jsonb_path_ops`.
 
+A record whose `format` is `:jsonb` also returns this view from
+`#messages`, so a conversation can be read without building a runtime:
+no provider, and no credentials. What it returns differs from the
+runtime's own `#messages` in three ways. It reads what is persisted
+rather than the state a context holds in memory and has not saved. It
+is unordered, and conversation order is `position` rather than `id`, so
+order it explicitly. And its rows are
+[`LLM::ActiveRecord::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html)
+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. `#messages!` is the runtime's own list, whatever the
+format is, so a jsonb record reaches it in one call.
+
+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
 
 #### Overview

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

@@ -245,9 +245,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/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
 
       ##
@@ -89,9 +91,42 @@ module LLM::ActiveRecord
       end
 
       ##
+      # Returns the messages this record holds.
+      #
+      # A record that stores its state as jsonb reads them from the column,
+      # as a relation: the conversation can be filtered, counted and ordered
+      # in the database, and nothing here needs a provider to be built. Every
+      # other format loads the runtime and hands back the messages it holds.
+      #
+      # The two do not agree about what is visible. The relation reads what is
+      # persisted rather than what the runtime holds in memory, it is
+      # 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. {#messages!} is the runtime's own collection,
+      # for a caller who wants that instead.
       # @see LLM::Context#messages
-      # @return [Array<LLM::Message>]
+      # @return [ActiveRecord::Relation, LLM::Buffer]
       def messages
+        options = self.class.llm_plugin_options
+        if options[:format] == :jsonb
+          LLM::ActiveRecord::Message.for(agent: self)
+        else
+          ctx.messages
+        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
 

data/lib/llm/agent.rb

@@ -441,7 +441,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