llm.rb 9.0.0 → 10.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 197ff330dc5e414f4f9291835fbcdeece4450ee3a8d3748e4f9cf28a46db07b1
-  data.tar.gz: 3020a4511134f292ed38c6fc826b157f05cc31c722e9fe52692b8b2f705551c7
+  metadata.gz: 6ba756238fa72e58ba774567a0c8e2a6d7351cb6313f9c8c08cbdeec8ec9cfa4
+  data.tar.gz: cba8295670dab2843cec902ae97b7ae14e775359380ba401ca5a0066eb60ad0e
 SHA512:
-  metadata.gz: 41f733d7d5b8a329420497f85c289f070f9016cf4d1bfdf5c5e49e274714310f5285e5598d4d27f5daa84cf26e837f311541ac8526bd987d7c7d917eb60eca21
-  data.tar.gz: f751b3887bd380e8f911106bedf6a0c606bcdc813ea4d7b01f2f332311ddd974c6dcfe838c7db5446d1683844ffbf379b2f5c8ef4b94459bedefaafc70be2098
+  metadata.gz: b8347b2adfe05a4700ec42e0ed5992a1332355bd20330590d8b3de214d980476a490855ff7e69b5b36c75f3684304c4ee61bdff9ecbcf8001f0b477b8010d064
+  data.tar.gz: a41512ffbc52b3665118161251441152389ca9daba1a6f4e010303490938dc33393da62f5e821521b2a9f4b45d85fd219b558fa7d2e185c24f43777d26e36a14

data/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 ## Unreleased
 
+## v10.0.0
+
+Changes since `v9.0.0`.
+
+This release unifies context turns under `#talk`, removes the
+deprecated `LLM::Bot` alias, and adds shared option resolution
+through `LLM::Utils`.
+
+Class-level agent tunables can now be resolved lazily via Proc,
+`Array[...]` schema/tool param types are supported, and a `key?`
+method has been added on providers.
+
+Agent tool confirmation hooks let selected tools be approved or
+cancelled before execution. Keep reading to learn more.
+
+### Breaking
+
+* **Unify context turns under `#talk`** <br>
+  Remove `LLM::Context#respond` and route responses-mode turns through
+  `LLM::Context#talk` with `mode: :responses` instead.
+
+* **Remove the `LLM::Bot` alias** <br>
+  Remove the backward-compatible `LLM::Bot` alias for `LLM::Context`.
+  Use `LLM::Context` directly instead.
+
+### Add
+
+* **Add shared option resolution through `LLM::Utils`** <br>
+  Add `LLM::Utils.resolve_option` for resolving configured values as
+  literals, procs, symbol-named methods, or duplicated hashes, and use
+  it in agent and ORM option resolution paths.
+
+* **Resolve all class-level agent tunables via Proc** <br>
+  Let `model`, `tools`, `skills`, `schema`, `stream`, and `tracer`
+  declared with a block be lazily evaluated against the agent instance
+  at initialization time, matching how `stream` and `tracer` already
+  worked.
+
+  Add `LLM::Agent#params` for direct access to the underlying context
+  parameters.
+
+  Ported from mruby-llm.
+
+* **Support `Array[...]` schema and tool param types** <br>
+  Let `LLM::Schema` properties and `LLM::Tool` params accept
+  `Array[...]` type declarations, including mixed item unions that are
+  serialized as `anyOf` array items.
+
+* **Add `LLM::Provider#key?`** <br>
+  Add `key?` to providers so callers can check whether a non-blank API
+  key has been configured.
+
+* **Add agent tool confirmation hooks** <br>
+  Add `LLM::Agent.confirm` and `LLM::Agent#on_tool_confirmation` so
+  selected tools can be approved or cancelled before execution. Pending
+  tool resolution now relies on `LLM::Context#functions` so confirmed
+  tools are not executed twice when mixed with unconfirmed tool calls.
+
+* **Add `LLM::Function#spawn(:call).wait`** <br>
+  Add task-shaped sequential execution support for direct
+  `LLM::Function#spawn(:call).wait`.
+
+### Fix
+
+* **Reduce private internal methods on `LLM::Stream`** <br>
+  Remove `tool_not_found` and `__tools__` from `LLM::Stream`. The
+  `__tools__` logic is inlined directly into `__find__` since that
+  was its only caller. The `tool_not_found` utility method was unused
+  externally and added unnecessary surface to LLM::Stream.
+
+  Ported from mruby-llm.
+
 ## v9.0.0
 
 Changes since `v8.1.0`.
@@ -162,7 +234,7 @@ DSML tool-marker filtering in streamed text.
   blocks that Bedrock rejects.
 
 * **Suppress Bedrock DSML tool markers in streamed text** <br>
-  Filter `"<｜DSML｜function_calls"` markers out of streamed Bedrock
+  Filter `\"<｜DSML｜function_calls\"` markers out of streamed Bedrock
   assistant text so tool-call sentinels do not leak into user-visible
   output.
 
@@ -313,7 +385,7 @@ provider usage has been recorded yet.
   buffer API.
 
 * **Support percentage compaction token thresholds** <br>
-  Let `LLM::Compactor` accept `token_threshold:` values like `"90%"` so
+  Let `LLM::Compactor` accept `token_threshold:` values like `\"90%\"` so
   compaction can trigger at a percentage of the active model context
   window.
 
@@ -1096,7 +1168,7 @@ Changes since `v4.9.0`.
 
 - Add HTTP transport for MCP with `LLM::MCP::Transport::HTTP` for remote servers
 - Add JSON Schema union types (`any_of`, `all_of`, `one_of`) with parser integration
-- Add JSON Schema type array union support (e.g., `"type\": [\"object\", \"null\"]`)
+- Add JSON Schema type array union support (e.g., `\"type\": [\"object\", \"null\"]`)
 - Add JSON Schema type inference from `const`, `enum`, or `default` fields
 
 ### Change
@@ -1197,7 +1269,7 @@ Notable merged work in this range includes:
 - `Add rack + websocket example (#130)`
 - `feat(gemspec): add changelog URI (#136)`
 - `feat(function): alias ThreadGroup#wait as ThreadGroup#value (#62)`
-- README and screencast refresh across `#66`, `#67`, `#68`, `#71`, and
+- README and screencast refresh across `#66`, `#68`, `#71`, and
   `#72`
 - `chore(bot): update deprecation warning from v5.0 to v6.0`
 - `fix(deepseek): tolerate malformed tool arguments`

data/README.md

@@ -1,10 +1,18 @@
 <p align="center">
-  <a href="llm.rb"><img src="https://github.com/llmrb/llm.rb/raw/main/llm.png" width="200" height="200" border="0" alt="llm.rb"></a>
+  <a href="llm.rb">
+    <img src="https://github.com/llmrb/llm.rb/raw/main/llm.png" width="200" height="200" border="0" alt="llm.rb">
+  </a>
 </p>
 <p align="center">
-  <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1"><img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc"></a>
-  <a href="https://opensource.org/license/0bsd"><img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License"></a>
-  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-9.0.0-green.svg?" alt="Version"></a>
+  <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1">
+    <img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc">
+  </a>
+  <a href="https://opensource.org/license/0bsd">
+    <img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License">
+  </a>
+  <a href="https://github.com/llmrb/llm.rb/tags">
+    <img src="https://img.shields.io/badge/version-10.0.0-green.svg?" alt="Version">
+  </a>
 </p>
 
 ## About
@@ -64,6 +72,36 @@ agent = LLM::Agent.new(llm, stream: $stdout)
 agent.talk "Hello world"
 ```
 
+#### Agents (Advanced)
+
+An agent can be configured to require confirmation before a tool is
+executed. When a matching tool is called, llm.rb runs
+`on_tool_confirmation`. That callback must decide whether to cancel the
+tool call or approve it and execute it by calling
+`fn.spawn(strategy).wait`, and it must always return an instance of
+[`LLM::Function::Return`](https://0x1eef.github.io/x/llm.rb/LLM/Function/Return.html):
+
+```ruby
+require "llm"
+
+class Agent < LLM::Agent
+  tools DeleteFile
+  confirm "delete-file"
+
+  def on_tool_confirmation(fn, strategy)
+    path = fn.arguments["path"] || fn.arguments[:path]
+    if path.start_with?("/tmp/")
+      fn.spawn(strategy).wait
+    else
+      fn.cancel(reason: "Deletion requires approval")
+    end
+  end
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+Agent.new(llm, stream: $stdout).talk("Delete /tmp/example.txt.")
+```
+
 #### Tools
 
 The
@@ -249,7 +287,10 @@ gem install llm.rb
 
 #### REPL
 
-This example uses [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) directly for an interactive REPL. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+This example uses [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html)
+directly for an interactive REPL. <br> See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -299,7 +340,9 @@ compactor can also use its own `model:` if you want summarization to run on a
 different model from the main context. `token_threshold:` accepts either a
 fixed token count or a percentage string like `"90%"`, which resolves
 against the active model context window and triggers compaction once total
-token usage goes over that percentage. See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+token usage goes over that percentage. See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -328,7 +371,15 @@ ctx = LLM::Context.new(
 
 #### Reasoning
 
-This example uses [`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html) with the OpenAI Responses API so reasoning output is streamed separately from visible assistant output. See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+This example uses [`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html)
+with the OpenAI Responses API so reasoning output is streamed separately from
+visible assistant output. See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
+
+To use the Responses API (OpenAI-specific), initialize a
+context or agent with `mode: :responses` and keep using
+`talk` for turns.
 
 ```ruby
 require "llm"
@@ -356,7 +407,10 @@ ctx.talk("Solve 17 * 19 and show your work.")
 
 #### Request Cancellation
 
-Need to cancel a stream? llm.rb has you covered through [`LLM::Context#interrupt!`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#interrupt-21-instance_method). <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+Need to cancel a stream? llm.rb has you covered through
+[`LLM::Context#interrupt!`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#interrupt-21-instance_method).
+<br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html)
+or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -377,7 +431,14 @@ worker.join
 
 #### Sequel (ORM)
 
-The `plugin :llm` integration wraps [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) on a `Sequel::Model` and keeps tool execution explicit. Like the ActiveRecord wrappers, its built-in persistence contract is the serialized `data` column, while `provider:` resolves a real `LLM::Provider` instance and `context:` injects defaults such as `model:`. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+The `plugin :llm` integration wraps
+[`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) on a
+`Sequel::Model` and keeps tool execution explicit. Like the ActiveRecord
+wrappers, its built-in persistence contract is the serialized `data` column,
+while `provider:` resolves a real `LLM::Provider` instance and `context:`
+injects defaults such as `model:`. <br> See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -412,7 +473,8 @@ one serialized `data` column. If your app has provider, model, or usage
 columns, provide them to llm.rb through `provider:` and `context:` instead of
 relying on reserved wrapper columns.
 
-See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html)
+or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -468,7 +530,8 @@ manages tool execution for you. Like `acts_as_llm`, its built-in persistence
 contract is one serialized `data` column. If your app has provider or model
 columns, provide them to llm.rb through your hooks and agent DSL.
 
-See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html)
+or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -521,7 +584,12 @@ end
 
 #### MCP
 
-This example uses [`LLM::MCP`](https://0x1eef.github.io/x/llm.rb/LLM/MCP.html) over HTTP so remote GitHub MCP tools run through the same `LLM::Context` tool path as local tools. It expects a GitHub token in `ENV["GITHUB_PAT"]`. See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+This example uses [`LLM::MCP`](https://0x1eef.github.io/x/llm.rb/LLM/MCP.html)
+over HTTP so remote GitHub MCP tools run through the same
+`LLM::Context` tool path as local tools. It expects a GitHub token in
+`ENV["GITHUB_PAT"]`. See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"