llm.rb 12.4.0 → 12.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd29af290d188d501b82ef31aae35258d7b6987b14f51bdce68dfbcc3bdca671
-  data.tar.gz: 4def59348a5f33bd66248e654f75de05adc7bd8d188686c9464bcfca12a61dcb
+  metadata.gz: 665281b1c81541ff2f9621138cee510e473dfbda2c7dcff7d1a324e5fe558c89
+  data.tar.gz: c3ee596e41885038dc831ef6459da330d1984fea0125a9dbc5aa7d0ff8e21061
 SHA512:
-  metadata.gz: da29e5f492f1130249d5db09ce098aff34d6805d16ed1d8e6df120a3038c4e013dc4dc95a16fcf39dd68f5eacc813715a41c1de7b61befa28206914a26c1aa32
-  data.tar.gz: 310c5dab18e187fd8aabd66c363e192a0b556b7f26efd2d7c553416b60782921da94feec04b834549b023ac5f3064c74e411aa32e5981782b237aabe9938d1fb
+  metadata.gz: cecf7fa0a2b1c6aff010c537b6741c74e537104eb9a67e3c2cd2840d06963040834c87263f71f6a1f815a4be831efa7740b2c03eb3f5fde9bbb274be4ee69c5c
+  data.tar.gz: 8b695e7c1656bf427bb095a257e954437b5b2dfc46e4d22349eb91dab9981eac1c5fc6b46bca89ecfec14986d386a0fba6303ef4dcf39a82345d3a136e944092

data/CHANGELOG.md

@@ -15,8 +15,248 @@
 
 ## What's next
 
+Changes since `v12.5.0`.
+
+## v12.5.0
+
 Changes since `v12.4.0`.
 
+This release extends the REPL command system with typed parameters, a
+built-in `/help` command, command aliases (`/quit`), and cancellation
+via the 'Esc' key.
+
+The default HTTP timeout is increased to 15 minutes (900s) to better
+accommodate reasoning models and large structured outputs.
+`LLM::Agent#deserialize` and `LLM::Agent#restore` now return `self` for
+method chaining, and `LLM::Buffer#pop` is added for tail-end message
+removal.
+
+Tool resolution gains a fallback to the global `LLM::Function` registry
+before raising `LLM::NoSuchToolError`, and `pending_functions` aliases
+are added on both contexts and agents for a consistent interface.
+
+Several REPL bugs are fixed including parameter state leakage across
+turns and invalid tool-call error routing.
+
+Model metadata is refreshed across all providers with new Anthropic,
+OpenAI, Google, DeepInfra, DeepSeek, and xAI model entries.
+
+### Add
+
+#### Buffer & function internals
+
+* **buffer: add `LLM::Buffer#pop`** <br>
+  Add `LLM::Buffer#pop` for removing the last message from the tail
+  of the buffer, complementing the existing `#<<` and array-style
+  message management.
+
+* **function: add registry fallback for tool resolution** <br>
+  When resolving tool calls from a message, if the tool is not found
+  in the available tools list, it now also looks up the global
+  `LLM::Function` registry via `LLM::Function.find_by_name` before
+  creating a placeholder function. This improves tool resolution for
+  tools that are registered globally but not passed directly through
+  the request tool set.
+
+#### Consistent `pending_functions` aliases
+
+* **context: alias `LLM::Context#functions` as `LLM::Context#pending_functions`** <br>
+  Add `LLM::Context#pending_functions` as an alias for `LLM::Context#functions`,
+  so callers that prefer the more descriptive `pending_functions` name can use
+  it instead of `functions` when checking for unresolved tool work.
+
+* **agent: alias `LLM::Agent#functions` as `LLM::Agent#pending_functions`** <br>
+  Add `LLM::Agent#pending_functions` as an alias for `LLM::Agent#functions`,
+  matching the same alias on `LLM::Context`, so callers have a consistent
+  `pending_functions` interface across both contexts and agents.
+
+#### REPL command system
+
+* **repl: extend command system with parameter support** <br>
+  Commands can now declare typed parameters using the `parameter`
+  DSL, modelled after `LLM::Tool` and `LLM::Schema` conventions.
+  Parameters can be marked as required with `required %i[...]`,
+  and values are type-checked before being passed to `call`.
+  Argument parsing is handled by the repl: arguments are split
+  from the input string and assigned to parameters by position.
+
+  ```ruby
+  class Greeter < LLM::Command
+    name "greet"
+    description "Greets the given name"
+    parameter :name, String, "The person's name"
+    required %i[name]
+
+    def call(name:)
+      write("Welcome #{name}!\n")
+    end
+  end
+  ```
+
+* **repl: add `help` command** <br>
+  Add `LLM::Repl::Help` as a new built-in command, registered
+  automatically via the command registry. Typing `/help` shows
+  the `help` command's own name, description, and parameters,
+  while `/help <name>` shows details for a specific command,
+  including its parameters and whether each is required or
+  optional. Unknown command names produce an error message.
+
+  ```ruby
+  class Help < Command
+    name "help"
+    description "show help for a given command"
+    parameter :name, String, "The name of a command"
+
+    def call(name: nil)
+      if name.nil?
+        write("\n#{self.class.help}\n\n")
+      elsif command = LLM::Command.find_by(name:)
+        write("\n#{command.help}\n\n")
+      else
+        write "\nNo help for #{name} was found" \
+              "\nThat command doesn't exist.\n\n"
+      end
+    end
+  end
+  ```
+
+* **repl: add support for command aliases** <br>
+  Commands can now be aliased by creating a subclass of another
+  command (with `LLM::Command` as an indirect ancestor). The
+  first alias introduced is `/quit` as an alias of `/exit`.
+
+  ```ruby
+  class Quit < Command::Exit
+    name "quit"
+  end
+  ```
+
+* **repl: add `Command::Parameter#optional?`** <br>
+  Parameters now expose an `#optional?` method that returns `true`
+  when a parameter has not been marked as required, making it
+  possible to query parameter optionality programmatically.
+
+* **repl: add `LLM::Repl::Command#write`** <br>
+  Commands can now write output to the transcript via the `write`
+  method. Commands also receive a reference to the active repl
+  through their `#initialize` method, making it possible to
+  interact with the repl window from within a command.
+
+* **repl: display command errors in the curses UI** <br>
+  Commands invoked with too few arguments now display an error
+  message — `command(<name>): too few arguments` — directly in
+  the curses transcript area, giving immediate feedback instead
+  of silently failing.
+
+* **repl: add `LLM::Command` convenience constant** <br>
+  Add `LLM::Command = LLM::Repl::Command` as a shorter alias,
+  available once `"llm/repl"` is required.
+
+#### Misc
+
+* **repl: implement cancellation with the 'Esc' key** <br>
+  The curses-based REPL now supports cancelling an active model
+  request by pressing the 'Esc' key. When a request is in progress,
+  the status line shows `thinking • Esc to cancel`, and pressing
+  Esc calls `LLM::Agent#cancel!` to interrupt the request. The
+  transcript displays `request cancelled!` to confirm the
+  cancellation.
+
+### Change
+
+#### Misc
+
+* **provider: increase default timeout to 900s** <br>
+  The default HTTP timeout for all providers has been increased from
+  180 to 900 seconds (15 minutes) to better accommodate long-running
+  requests such as reasoning models and large structured outputs.
+
+* **agent: `deserialize` and `restore` return `self`** <br>
+  `LLM::Agent#deserialize` and `LLM::Agent#restore` now return `self`
+  (the agent instance) instead of forwarding the context's return
+  value, enabling method chaining after restoring agent state.
+
+* **context: discard all messages from a cancelled turn** <br>
+  When `LLM::Context#cancel!` is called, all messages added during
+  that turn are now discarded via `Buffer#slice!`, preventing edge
+  cases where dangling tool calls between turns caused repeated
+  cancellation loops. The `#repair!` method now handles tool call
+  cancellations on the next turn instead of mutating the conversation
+  buffer directly at cancellation time.
+
+* **stream: drop the `error` argument from `on_tool_call`** <br>
+  The `on_tool_call` callback no longer accepts an `error` argument.
+  Previously, stream parsers passed both a tool and an optional error,
+  requiring boilerplate like `if error; queue << error; end` in every
+  callback. Error handling is now pushed directly onto the stream queue
+  inside each provider's stream parser, so `on_tool_call(tool)` is the
+  only signature. The REPL stream and base `LLM::Stream` class have
+  been updated accordingly.
+
+#### REPL internals
+
+* **repl: pass the repl instance to command constructors** <br>
+  `LLM::Repl::Command` subclasses now receive the active repl
+  instance via `initialize(repl)`, enabling commands to write
+  to the transcript and interact with the repl window.
+
+* **repl: `Command#write` prefixes messages with the command name** <br>
+  The `#write` method now prefixes output with `command(<name>): `
+  so command messages are consistent with the `user:` and `agent:`
+  labels in the transcript. The prefix can be customised with the
+  `who:` keyword argument, or set to `who: nil` to disable it
+  entirely.
+
+### Fix
+
+#### Misc
+
+* **function: avoid silent skip of tools not found in available tools** <br>
+  When a model calls a tool that is not present in the available tools
+  list, instead of silently skipping the tool call (via `next`), a
+  `LLM::NoSuchToolError` is now raised so the model receives feedback
+  about the invalid tool call and can correct course.
+  <br><br>
+  An additional fallback to the global `LLM::Function` registry is
+  tried before raising, so globally registered tools are still
+  resolved even when not in the per-request tool set.
+
+#### REPL bugs
+
+* **repl: don't persist parameter state between turns** <br>
+  Parameter state (such as `Parameter#value`) was leaking across
+  turns because the same parameter objects were being mutated
+  in place. A duplicate set of parameters is now created for each
+  turn, keeping the original parameter definitions intact and
+  preventing stale state from carrying over.
+
+* **repl: reply with error when given an invalid tool** <br>
+  When the model tries to call a tool that does not exist, the
+  error is now pushed onto the stream queue so the model can
+  see the error and correct course, instead of silently dropping
+  the invalid tool call and leaving it to `Context#repair` to
+  remove it from history.
+
+* **repl: fix save of initial runtime state** <br>
+  Fix a bug in `LLM::Repl#configure` where a non-existent path
+  argument was treated as no path at all, preventing the initial
+  runtime state from being saved after the first turn. The correct
+  behavior is to create the file so it can be written to after
+  the first turn completes.
+
+### Refresh
+
+* **Refresh model metadata across all providers** <br>
+  Update model listings, pricing, capabilities, reasoning options,
+  modality support, context limits, and release dates across all
+  provider registries (Anthropic, AWS Bedrock, DeepInfra, DeepSeek,
+  Google, Mistral, OpenAI, xAI, and ZAI). Notable changes include
+  Anthropic claude-opus-4-8 and claude-sonnet-4-6 additions with
+  effort-based reasoning, OpenAI gpt-5.6-sol/terra/luna and
+  gpt-5-codex additions, Google gemini-3-pro-preview and
+  gemini-3-flash-preview additions, DeepInfra Qwen3.5 and DeepSeek
+  V4 model additions, and updated xAI Grok model entries.
+
 ## v12.4.0
 
 Changes since `v12.3.1`.

data/README.md

@@ -141,6 +141,8 @@ instance. The session inherits the agent's model, tools,
 skills, and instructions.
 
 ```ruby
+require "llm"
+
 llm = LLM.deepseek(key: ENV["KEY"])
 agent = LLM::Agent.new(llm)
 agent.repl
@@ -153,6 +155,8 @@ is read from and written to. This lets you resume a
 conversation across REPL sessions.
 
 ```ruby
+require "llm"
+
 llm = LLM.deepseek(key: ENV["KEY"])
 agent = LLM::Agent.new(llm)
 agent.repl(path: "session.json")
@@ -169,6 +173,8 @@ llm.rb. They power the agents that can be found in the
 [agents/](agents/) directory.
 
 ```ruby
+require "llm"
+
 llm = LLM.deepseek(key: ENV["KEY"])
 agent = LLM::Agent.new(llm)
 agent.repl(tools: [Debugger])
@@ -192,6 +198,8 @@ The `skills` option lets you load extra skill directories
 without attaching them to an agent permanently.
 
 ```ruby
+require "llm"
+
 llm = LLM.deepseek(key: ENV["KEY"])
 agent = LLM::Agent.new(llm)
 agent.repl(skills: [__dir__])
@@ -205,11 +213,39 @@ the tracer associated with an instance of
 [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
 
 ```ruby
-llm = LLM.deepseek(key: ENV["KEY"])
-agent = LLM::Agent.new(llm, tracer: LLM.logger(llm, path: "agent.log"))
+require "llm"
+
+llm    = LLM.deepseek(key: ENV["KEY"])
+tracer = LLM.logger(llm, path: "agent.log")
+agent  = LLM::Agent.new(llm, tracer:)
 agent.repl(tracer: true, tools: [Debugger])
 ```
 
+##### REPL: Commands
+
+Commands are recognized by a `/` prefix and are backed by the
+[`LLM::Repl::Command`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html)
+class, which can be subclassed to add custom commands. Once you
+create a subclass, it is automatically added to the repl. A command
+can have zero or more parameters, and all parameters are presumed
+to be a String (at least for now).
+
+```ruby
+require "llm"
+require "llm/repl"
+
+class Greeter < LLM::Command
+  name "greet"
+  description "Greets the given name"
+  parameter :name, String, "The person's name"
+  required %i[name]
+
+  def call(name:)
+    write("Welcome #{name}!\n")
+  end
+end
+```
+
 ##### REPL: Input
 
 The input area supports several keyboard shortcuts:
@@ -227,12 +263,6 @@ The input area supports several keyboard shortcuts:
 | `Up / Down` | Scroll the transcript |
 | `/exit` | Leave the REPL |
 
-##### REPL: Commands
-
-Commands are recognized by a `/` prefix and are backed by the
-[`LLM::Repl::Command`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html)
-class, which can be subclassed to add custom commands.
-
 #### LLM::MCP
 
 The Model Context Protocol (MCP) has first-class support