llm.rb 16.0.0 → 17.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ffff6a5b0130efbb79ff9350c45c5119926a7a1a3a6082d37e6ad83bbe475a6
-  data.tar.gz: f833f7ae7a80028ed30afe176524dd91c339d98f7500cd007e8afa91162e0874
+  metadata.gz: 64500ab12462e962a82bb878d1216396f2cde76c07223dda496a1868de5f5520
+  data.tar.gz: e708caa24c81cc66585ae69fc95a5437a89b2b279b9eb4c5bc544457dc519bbf
 SHA512:
-  metadata.gz: 36950cc51888a2ecc7c62eeacb1bbbb6a2694af3b538ba830b304ca0ac79eea88067c093ba9fefffb5c57597026c697e1f513f0c75a2ff95af9ef68212054e8d
-  data.tar.gz: 0d2164fa4254a6cc062606b13257f902465fca99229e8aacb9c2d600f1e8eee87656a185b9de82f0846b5cc4ffd0275809c6a264f39c45876ede6b39f6814086
+  metadata.gz: 702022be0328b36155d9832a36241f5aaf79d7af6111024bd21ecbe3f75b7f0078995c3c6bceff8b134b03a8ee582815ef82ebe8320ddcfeb56a51d4ad70cc7c
+  data.tar.gz: 15092c8243ec262af8b77d98833a3c05a259a8e2413317f6002e5de9467ebd29eb0af7baaa4b08c22dabc9b943ad344cc938be1600e5382fb0b9f186e671bde6

data/CHANGELOG.md

@@ -1,13 +1,546 @@
 > Changelog <br>
 > [r.uby.dev](https://r.uby.dev) project
 
-This file covers the v16 series. Releases up to and including v15 are kept in
-[changelog/old.md](changelog/old.md).
+This file covers the v17 series and the previous
+v16 series. <br> Previous releases (v15 and
+before) can be seen in [changelog/old.md](changelog/old.md).
 
 ## What's next
 
 *No unreleased changes yet. Check back after the next release.*
 
+## v17.0.1
+
+Changes since `v17.0.0`.
+
+This is a small release with a single fix. An `intercept:`
+given to an agent is passed to the context now, so the
+intercept is called when a tool call is about to run.
+
+### Fix
+
+* **agent: forward `intercept:` to `LLM::Context`** <br>
+  An `intercept:` given to an agent was kept on the
+  agent as an instance variable and never read, so the
+  context a turn runs against fell back to
+  [`LLM::Intercept::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept/Null.html)
+  and no tool call was intercepted. The option is
+  passed to
+  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+  as a parameter now, the way `tools:` and `stream:`
+  are. Each way to set it works: `set intercept:`, a
+  block given to
+  [`LLM::Agent.intercept`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#intercept-class_method),
+  and an `intercept:` given to
+  [`LLM::Agent.new`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#initialize-instance_method).
+
+## v17.0.0
+
+Changes since `v16.0.0`.
+
+This release is large, and includes a number of breaking
+changes. It covers a lot of ground. I will try to cover the
+highlights but I won't be able to cover everything, and
+there won't be much depth. Check out the changelog entries
+to learn more.
+
+The Files API provided by deepseek is now supported
+(via [LLM::DeepSeek#files](https://r.uby.dev/api-docs/llm.rb/LLM/DeepSeek/Files.html)),
+and there was a large focus on the cancellation and
+interrupt story. [LLM::Tracer](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html)
+saw a lot of changes and it has the most changelog
+entries in this release.
+
+The `LLM::Guard` class was a focus as well, and it
+has been renamed to
+[LLM::Intercept](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html)
+. An intercept can block a tool call with a return
+of its own, it can mutate tool-call parameters in
+place, validate tool call parameters, and anything
+else a middleman that sits between the model and a
+tool could do.
+
+It is now possible to combine multiple tracers _or_
+intercepts into a single tracer, or intercept. The
+[LLM::Tracer.multi](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#multi-class_method)
+and
+[LLM::Intercept.multi](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html#multi-class_method)
+methods exist for this purpose.
+
+For everything else, keep reading.
+
+### Breaking
+
+#### Migration
+
+| Old | New |
+|-----|-----|
+| the default read timeout is 600 seconds | the default read timeout is 240 seconds |
+| `LLM::Tracer#on_interrupt` and `#on_exit` do nothing | both raise `NotImplementedError`, so a tracer answers for each |
+| `LLM::Tracer#on_tool_finish(result:, span:)` and `#on_tool_error(ex:, span:)` | both also take `started_at:` and `finished_at:` |
+| `LLM::Tracer#on_tool_error` is given the `Exception` a tool raised | it is given the `LLM::Function::Return` that holds the error |
+| a tracer's tool callbacks run on the thread or fiber that ran the tool | they run on the agent's thread, like the other callbacks |
+| a cancelled `:ractor` call answers in band with `cancelled: true` | it raises `LLM::Interrupt` in the caller's thread |
+| `LLM::Guard`, `LLM::Guard::Null` | `LLM::Intercept`, `LLM::Intercept::Null` |
+| `guard:` and `guard_options:` on a context or agent | `intercept:` and `intercept_options:` |
+| `LLM::Context#guard` | `LLM::Context#intercept` |
+| a guard that returned anything truthy stopped the tool call | only a `LLM::Function::Return` stops it, and any other value lets the call run |
+| `trace:` on `LLM::Agent#console`, a deprecated alias | it is removed, and `tracer:` is the keyword |
+
+### Intercept
+
+* **intercept: rename `LLM::Guard` to `LLM::Intercept`** <br>
+  The hook that sees a pending tool call before it
+  runs is an
+  [`LLM::Intercept`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html)
+  now, because it does more than guard a call:
+  `#call` receives the `LLM::Function`, so an
+  intercept can rewrite a call and let it run by
+  returning `nil`. A subclass of `LLM::Guard` is
+  renamed, the `guard:` and `guard_options:` a
+  context or agent takes are `intercept:` and
+  `intercept_options:`, and `LLM::Context#guard` is
+  `LLM::Context#intercept`. `LLM::Guard` is
+  removed, and no alias is left for it.
+
+* **intercept: add `LLM::Intercept.multi`** <br>
+  The
+  [`LLM::Intercept.multi`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html#multi-class_method)
+  factory combines one or more intercepts into a
+  single
+  [`LLM::Intercept::Multi`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept/Multi.html)
+  that a context or agent can be given as
+  `intercept:`. Each intercept is called in the
+  order it was given, and the first that returns an
+  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+  ends the call, so an intercept that returns `nil`
+  lets the next one decide. An `intercept:` is
+  taken as an instance now as well as a class,
+  which is what lets the factory's return value be
+  used as it is.
+
+* **intercept: give an intercept the options it was built with** <br>
+  The `intercept_options:` a context or agent is
+  built with now reach
+  [`LLM::Intercept#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html#call-instance_method)
+  as keywords, and an intercept can read them
+  through
+  [`LLM::Intercept#options`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html#options-instance_method).
+  Before, the options were held on the context and
+  never passed to the intercept, so a subclass that
+  wanted them had no way to read them.
+
+### Provider
+
+* **deepseek: upload a file once and refer to it by id** <br>
+  [`LLM::DeepSeek#files`](https://r.uby.dev/api-docs/llm.rb/LLM/DeepSeek.html#files-instance_method)
+  returns an
+  [`LLM::DeepSeek::Files`](https://r.uby.dev/api-docs/llm.rb/LLM/DeepSeek/Files.html)
+  object now, so a file can be uploaded once and a
+  later chat request can name it instead of
+  resending its bytes. Before, the call raised
+  `NotImplementedError`. Uploads default to
+  `purpose: "user_data"`, the only purpose
+  DeepSeek accepts, and requests go to the root of
+  the API host, where DeepSeek serves its Files
+  API.
+
+* **provider: add `LLM::Provider#retry_errors`** <br>
+  The
+  [`LLM::Provider#retry_errors`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#retry_errors-instance_method)
+  method returns the exceptions that a request can
+  raise and that are retried up to the provider's
+  retry budget. A provider extends the array it
+  inherits rather than replacing it, and
+  [`LLM::DeepSeek#retry_errors`](https://r.uby.dev/api-docs/llm.rb/LLM/DeepSeek.html#retry_errors-instance_method)
+  adds `LLM::ServerError`, the error DeepSeek
+  returns when its servers are overloaded, so a
+  request that finds an overloaded server is retried
+  with a growing delay like a rate limit instead of
+  failing on the first response.
+
+* **provider: drop the default read timeout to 240 seconds** <br>
+  The default read timeout is now 240 seconds (four
+  minutes), down from 600 seconds (ten minutes). A
+  timeout is retried, so the old default could be
+  spent on a response that never arrives, and the
+  new one fails sooner and opens a new session
+  instead. DeepSeek prompted the change: it can
+  stall past four minutes when it is under heavy
+  load. Pass `read_timeout:` or `timeout:` to a
+  provider to choose your own.
+
+### Agent
+
+* **agent: interrupt an agent via `LLM::Agent#id`** <br>
+  The
+  [`LLM.interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM.html#interrupt-class_method)
+  method can interrupt an agent with nothing more
+  than an ID that references it. A controller, a
+  background job, or a socket handler can use this
+  method to interrupt an agent that is running
+  in the same process but on a different thread
+  or fiber.
+
+* **agent: add `LLM::Agent.registry`** <br>
+  The
+  [`LLM::Agent.registry`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#registry-class_method)
+  method returns an object that holds every
+  active instance of
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
+  An agent enters the registry when it starts a turn,
+  and it exits the registry after that. The registry is
+  thread-safe, local to a single process
+  and
+  [`LLM.interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM.html#interrupt-class_method)
+  uses it under the hood to find an agent by ID.
+
+* **agent: `LLM.interrupt` can retry until it finds an agent** <br>
+  The method now takes `attempts:` and `interval:`, so
+  a caller that asks for an agent before its turn has
+  started can poll for it instead of giving up on the
+  first miss, which is the loop a caller used to write
+  by hand. `attempts` defaults to 1 and `interval` to
+  0.1 seconds, so the method is unchanged until a caller
+  asks it to wait. It returns `true` when an interrupt
+  took place, and `false` otherwise.
+
+* **agent: set an intercept at the class level** <br>
+  [`LLM::Agent.intercept`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#intercept-class_method)
+  is where an agent's intercept is declared, so it
+  can sit beside the agent's other defaults. It
+  takes an intercept, or a block that is resolved
+  when the agent is built, and `set intercept:`
+  takes a `Symbol` that names an instance method,
+  which is how
+  [`LLM::Intercept.multi`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html#multi-class_method)
+  is composed. An `intercept:` given to
+  [`LLM::Agent.new`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#initialize-instance_method)
+  is resolved the same way, and an ActiveRecord or
+  Sequel model that wraps an agent carries it into
+  the context it builds.
+
+* **agent: remove the deprecated `trace:` keyword from `LLM::Agent#console`** <br>
+  The `trace:` keyword is gone from
+  [`LLM::Agent#console`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#console-instance_method)
+  and from its `repl` alias. It was renamed to
+  `tracer:` in an earlier release, and it was kept
+  for a caller that still passed it, with a warning
+  each time. The keyword is `tracer:`, so
+  `trace: true` is `tracer: true`.
+
+### Function
+
+* **function: `:ractor` raises `LLM::Interrupt` (like everyone else)** <br>
+  An
+  [`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+  that is delivered to a tool running on a ractor
+  will travel back to the caller and raise itself
+  on the caller's thread, the same as all other
+  concurrency strategies. This only happens after
+  all tools have been interrupted themselves, and
+  it is the last step in an interrupt. The caller
+  is expected to rescue `LLM::Interrupt` and handle
+  the interrupt from there.
+
+* **function: add `LLM::Function::Task#intercepted?`** <br>
+  An intercept stops a tool call when it returns
+  an
+  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html),
+  because that Return is the answer the model is
+  given for the call. Any other value lets the call
+  through, where only `nil` did that before, so a
+  guard that returned anything else stopped a tool
+  call and answered the model with it.
+  [`LLM::Function::Task#intercepted?`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html#intercepted?-instance_method)
+  is the predicate a task asks, and it is true only
+  for a Return.
+
+### Tracer
+
+* **tracer: add `LLM::Tracer::Multi`** <br>
+  The
+  [`LLM::Tracer::Multi`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Multi.html)
+  tracer fans every tracing callback out to a set of
+  tracers, so a request can be logged to a file and
+  exported to OpenTelemetry at the same time instead
+  of choosing between them. Its `on_request_start`
+  and `on_tool_start` return an array with one span
+  per tracer, and that array is passed back as
+  `span:` to the matching finish, error, or interrupt
+  callback, so each tracer is handed the span it
+  returned. A tracer that raises is reported rather
+  than taking the request down with it, and
+  `LLM::Interrupt` still travels up the stack.
+
+* **tracer: add `LLM::Tracer.multi`** <br>
+  Add
+  [`LLM::Tracer.multi`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#multi-class_method)
+  as a factory for `LLM::Tracer::Multi`. The
+  provider comes first and is required, so a
+  tracer given as a class is built with it,
+  while a tracer given as an instance is used
+  as it is. Builtin tracers and a custom one
+  can be mixed in a single call.
+
+* **tracer: build every tracer given to `LLM::Tracer.multi`** <br>
+  Fix a bug where
+  [`LLM::Tracer.multi`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#multi-class_method)
+  passed its tracers to `LLM::Tracer::Multi.new` as
+  a single array rather than one argument each,
+  so a `Multi` held that array as its only
+  tracer and every callback raised `NoMethodError`
+  on it.
+  [`LLM::Tracer::Rescue`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Rescue.html)
+  reported the crash to standard error and
+  swallowed it, so the request was not traced.
+
+* **tracer: alias `LLM::Tracer.pretty_logger` as `LLM::Tracer.pretty`** <br>
+  Add
+  [`LLM::Tracer.pretty`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#pretty_logger-class_method)
+  as an alias for `LLM::Tracer.pretty_logger`,
+  so the shorter name builds the same tracer
+  with the same options. The README uses
+  `pretty` throughout.
+
+* **tracer: protect an agent from a tracer crash** <br>
+  The
+  [`LLM::Tracer::Rescue`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Rescue.html)
+  module prepends itself on every subclass of
+  [`LLM::Tracer`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html)
+  and rescues uncaught exceptions that occur
+  in tracer callback. Any callback that lets
+  an exception exit its method will be rescued
+  and the exception dumped onto standard error.
+
+* **tracer: run every `on_tool_*` callback on the agent's thread** <br>
+  The
+  [`LLM::Tracer#on_tool_start`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_tool_start-instance_method),
+  `#on_tool_finish`, `#on_tool_error`, and
+  `#on_tool_interrupt` callbacks are now
+  called on the same thread as the agent
+  they belong to - and this is true
+  across all strategies. The previous
+  implementation could call the tracer
+  across threads and fibers when given
+  the `thread`, `async`, and `fiber`
+  strategies.
+
+  Both `ractor`, and `fork` already kept the
+  tracer on one thread, and now all strategies
+  do. The last exception to the rule was
+  `LLM::Tracer#on_interrupt`, which could be
+  called on the thread that asked for the
+  interrupt rather than the thread that
+  received the interrupt.
+
+* **tracer: run `LLM::Tracer#on_interrupt` on the agent's thread** <br>
+  The
+  [`LLM::Tracer#on_interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_interrupt-instance_method)
+  callback is now called on the agent's thread,
+  or fiber, the same as every other callback.
+  Before, it was called by whoever asked for the
+  interrupt, so a tracer could be called across
+  threads for an interrupt alone. The raise now
+  unwinds to the turn it stopped, the tracer is
+  told `scope: :agent` there, and the interrupt
+  is re-raised for the caller.
+
+* **tracer: `on_interrupt` and `on_exit` raise `NotImplementedError`** <br>
+  The
+  [`LLM::Tracer#on_interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_interrupt-instance_method)
+  and
+  [`LLM::Tracer#on_exit`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_exit-instance_method)
+  methods now raise `NotImplementedError`
+  by default and subclasses of
+  [`LLM::Tracer`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html)
+  must implement them, otherwise
+  the tracer will crash and the crash
+  will be logged to standard error
+  (`$stderr`). A tracer crash does
+  not crash an agent, and both of
+  these methods can be implemented
+  as noops that return `nil`.
+
+* **tracer: `on_tool_{finish,interrupt,error}` receive `started_at` / `finished_at`** <br>
+  The
+  [`LLM::Tracer#on_tool_finish`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_tool_finish-instance_method),
+  [`LLM::Tracer#on_tool_interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_tool_interrupt-instance_method)
+  and
+  [`LLM::Tracer#on_tool_error`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_tool_error-instance_method)
+  methods now receive `started_at`
+  and `finished_at` attributes that can
+  determine how long a tool took to run.
+  Both are based on a monotonic clock
+  (`Process::CLOCK_MONOTONIC`) and
+  neither are `Time` objects.
+
+* **tracer: add `LLM::Tracer#on_tool_interrupt`** <br>
+  The [`LLM::Tracer#on_tool_interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_tool_interrupt-instance_method)
+  method allows a tracer to close a span that
+  was opened by
+  [`LLM::Tracer#on_tool_start`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_tool_start-instance_method)
+  and it is called for every tool that
+  was interrupted. The callback receives
+  the tool name and its tool call ID plus
+  the span that was opened by `on_tool_start`.
+
+* **tracer: return a span from `LLM::Tracer::Logger#on_tool_start`** <br>
+  The
+  [`LLM::Tracer::Logger#on_tool_start`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html#on_tool_start-instance_method)
+  method now returns a span that can be
+  matched by another callback method that
+  will close the span (eg `on_tool_start -> on_tool_finish`).
+
+* **tracer: return a span from `LLM::Tracer::PrettyLogger#on_tool_start`** <br>
+  The
+  [`LLM::Tracer::PrettyLogger#on_tool_start`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html#on_tool_start-instance_method)
+  method now returns a span that can be
+  matched by another callback method that
+  will close the span (eg `on_tool_start -> on_tool_finish`).
+
+* **tracer: add `LLM::Tracer::Logger#on_tool_interrupt`** <br>
+  This method implements the new callback available on the
+  superclass of Logger. The callback emits an `tool.interrupt`
+  event and carries other metadata with it.
+
+* **tracer: add `LLM::Tracer::PrettyLogger#on_tool_interrupt`** <br>
+  This method implements the new callback available on the
+  superclass of PrettyLogger. The callback emits a log entry
+  that captures the tool interrupt via an IO object.
+
+* **tracer: add `LLM::Tracer::Telemetry#on_tool_interrupt`** <br>
+  This method implements the new callback available on
+  the superclass of Telemetry. The callback records
+  `error.type` as `LLM::Interrupt`, marks the span as
+  an error, adds the standard `gen_ai.tool.finish`
+  event and closes the span that was opened by
+  `on_tool_start`. It follows the shape of
+  `on_tool_error` and `on_interrupt` instead of
+  emitting a `gen_ai.tool.interrupt` event, which is
+  not part of the OpenTelemetry standard.
+
+* **tracer: `LLM::Tracer#on_interrupt` raises `NotImplementedError` by default** <br>
+  The
+  [`LLM::Tracer#on_interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_interrupt-instance_method)
+  method is no longer a noop that returns nil. All tracers
+  that subclass `LLM::Tracer` must implement this method. The
+  change makes `on_interrupt` consistent with all other
+  callback methods that are available on [LLM::Tracer](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html).
+
+* **tracer: add `LLM::Tracer::Logger#on_interrupt`** <br>
+  This method implements the callback available on the
+  superclass of Logger. The callback emits an `info` event
+  that is named from the scope (eg `request.interrupt`)
+  and carries the scope and the request ID with it.
+
+* **tracer: add `LLM::Tracer::PrettyLogger#on_interrupt`** <br>
+  This method implements the callback available on the
+  superclass of PrettyLogger. The callback writes a line
+  to its IO object that names the provider and the scope
+  the interrupt was received in.
+
+* **tracer: add `LLM::Tracer::Telemetry#on_interrupt`** <br>
+  This method implements the callback available on the
+  superclass of Telemetry. A `:request` interrupt closes
+  the span that `on_request_start` opened and marks it
+  with an error and a `gen_ai.request.finish` event, since
+  a request is the only interrupted scope with a span left
+  open. The `:tool` and `:agent` scopes do nothing, because
+  tools are closed by `on_tool_interrupt`, and any other
+  scope raises `LLM::Error`.
+
+* **tracer: `LLM::Tracer#on_exit` raises `NotImplementedError` by default** <br>
+  The
+  [`LLM::Tracer#on_exit`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_exit-instance_method)
+  method is no longer a noop that returns nil. All tracers
+  that subclass `LLM::Tracer` must implement this method. The
+  change makes `on_exit` consistent with all other
+  callback methods that are available on [LLM::Tracer](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html).
+
+### LLM::Context
+
+* **context: inherit database ID** <br>
+  The
+  [`LLM::Context#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#id-instance_method)
+  and
+  [`LLM::Agent#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#id-instance_method)
+  methods will inherit the database ID
+  of the record that is associated with
+  them __if__ a record is in scope and
+  __if__ the database ID is in the UUIDv7
+  format. Otherwise a random UUIDv7 is
+  generated as the ID. A record is normally
+  in scope when given an ActiveRecord or
+  Sequel model has wrapped an instance
+  of
+  [LLM::Context](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+   /
+  [LLM::Agent](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
+
+* **context: an ID must be in the UUIDv7 format** <br>
+  An agent and context ID must __always__ carry a
+  UUIDv7 format, even when given an explicit `id`
+  as a parameter, and anything else raises
+  `LLM::Error`. This is because the ID is used
+  internally to compute other attributes
+  (such as `LLM::Agent#created_at`). The runtime
+  checks it with
+  [`LLM::Utils.uuidv7?`](https://r.uby.dev/api-docs/llm.rb/LLM/Utils.html#uuidv7?-instance_method),
+  the same predicate `LLM::Utils.timestamp` reads
+  a time through, so an id this predicate accepts
+  is an id `created_at` can answer for.
+
+### Registry
+
+* **refresh model metadata** <br>
+  Update `data/` with current listings, limits,
+  and pricing. Anthropic adds Claude Haiku 5.5,
+  Bedrock adds Claude Haiku 5.5, Claude Sonnet
+  5.5 in the US and EU, Claude Sonnet 5 and
+  Claude Opus 5 in India, and GLM-5.3 in the US
+  and global regions, Mistral adds the Ministral
+  3 3B, 8B, and 14B models, Mistral Large 4,
+  Codestral 25.08, Voxtral Small, GLM-5.2, and
+  Leanstral 1.5, DeepInfra adds
+  `Qwen/Qwen3-VL-30B-A3B-Instruct`, and
+  OpenRouter adds six models. OpenRouter drops
+  sixteen entries, twelve of them Qwen, and
+  Alibaba, Mistral, Moonshot, OpenAI, and xAI
+  correct limits and prices. Google adds Gemini 4
+  Argon, a reasoning model with a 1M-token context,
+  DeepInfra adds Claude Fable 5 and Mistral Small 3
+  and deprecates `Qwen/Qwen3.8-2.4T-A95B`, and
+  OpenRouter adds `liquid/lfm-2.5-24b-a2b`,
+  `google/gemini-4-argon`, the Scaledown extract
+  and summarize models, and the Pareto models,
+  drops `unbiased/pareto` and three Ling 3.0 Flash
+  and Apodex entries, and reprices several DeepSeek,
+  Z.ai, Tencent, Moonshot, Meta, and Gemma models.
+
+### Fix
+
+* **tools: require `test-cmd.rb` `~> 2.7.3`** <br>
+  The exec-backed tools now need `test-cmd.rb`
+  2.7.3 or later, up from 2.7.1. Version 2.7.2
+  fixes a race where `Process.wait` could claim a
+  process another thread had spawned, so a tool
+  could answer with a status and a pid that
+  belonged to another command, and 2.7.3 stops
+  looking for `/bin/false` when a command is not
+  found, which Windows does not have.
+
+* **tools: name the tool that was not found** <br>
+  The in-band error returned when a model asks for
+  a tool that does not exist names it now, as
+  `tool 'exec' not found`, where it said only
+  `tool not found`. That is the same message
+  [`LLM::Tool.find_by_name!`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#find_by_name!-class_method)
+  raises when it cannot resolve a name, so the two
+  paths read alike: the class raises
+  [`LLM::NoSuchToolError`](https://r.uby.dev/api-docs/llm.rb/LLM/NoSuchToolError.html)
+  rather than the `no such tool "exec"` it used to.
+
 ## v16.0.0
 
 Changes since `v15.5.0`.