llm.rb 15.2.2 → 15.4.0

data/data/xai.json

@@ -370,17 +370,30 @@
         "output": 0
       }
     },
-    "grok-imagine-image-2.0": {
-      "id": "grok-imagine-image-2.0",
-      "name": "Grok Imagine Image 2.0",
-      "description": "Image model for prompt-driven generation, editing, and visual design workflows",
+    "grok-4.6": {
+      "id": "grok-4.6",
+      "name": "Grok 4.6",
+      "description": "xAI's frontier model for long-running agents, coding, knowledge work, and visual projects",
       "family": "grok",
       "attachment": true,
-      "reasoning": false,
-      "tool_call": false,
-      "temperature": false,
-      "release_date": "2026-08-07",
-      "last_updated": "2026-08-07",
+      "reasoning": true,
+      "reasoning_options": [
+        {
+          "type": "effort",
+          "values": [
+            "low",
+            "medium",
+            "high",
+            "xhigh"
+          ]
+        }
+      ],
+      "tool_call": true,
+      "structured_output": true,
+      "temperature": true,
+      "knowledge": "2026-02-01",
+      "release_date": "2026-08-12",
+      "last_updated": "2026-08-12",
       "modalities": {
         "input": [
           "text",
@@ -388,19 +401,39 @@
           "pdf"
         ],
         "output": [
-          "image",
-          "pdf"
+          "text"
         ]
       },
       "open_weights": false,
       "limit": {
-        "context": 64000,
-        "output": 0
+        "context": 500000,
+        "output": 500000
+      },
+      "cost": {
+        "input": 2,
+        "output": 6,
+        "cache_read": 0.5,
+        "tiers": [
+          {
+            "input": 4,
+            "output": 12,
+            "cache_read": 1,
+            "tier": {
+              "type": "context",
+              "size": 200000
+            }
+          }
+        ],
+        "context_over_200k": {
+          "input": 4,
+          "output": 12,
+          "cache_read": 1
+        }
       }
     },
-    "grok-4.6": {
-      "id": "grok-4.6",
-      "name": "Grok 4.6",
+    "grok-4.7": {
+      "id": "grok-4.7",
+      "name": "Grok 4.7",
       "description": "xAI's frontier model for long-running agents, coding, knowledge work, and visual projects",
       "family": "grok",
       "attachment": true,
@@ -419,9 +452,9 @@
       "tool_call": true,
       "structured_output": true,
       "temperature": true,
-      "knowledge": "2026-02-01",
-      "release_date": "2026-08-12",
-      "last_updated": "2026-08-12",
+      "knowledge": "2026-05",
+      "release_date": "2026-09-21",
+      "last_updated": "2026-09-21",
       "modalities": {
         "input": [
           "text",
@@ -462,7 +495,7 @@
     "grok-imagine-image-quality": {
       "id": "grok-imagine-image-quality",
       "name": "Grok Imagine Image Quality",
-      "description": "Image model for prompt-driven generation, editing, and visual design workflows",
+      "description": "Higher-fidelity Grok Imagine image model for prompt-driven generation, editing, and visual design workflows",
       "family": "grok",
       "attachment": true,
       "reasoning": false,

data/data/zai.json

@@ -240,11 +240,59 @@
         "cache_write": 0
       }
     },
+    "glm-5.3-flashx": {
+      "id": "glm-5.3-flashx",
+      "name": "GLM-5.3-FlashX",
+      "description": "High-speed GLM-5.3-Flash serving option for coding and agent workflows",
+      "family": "glm-flash",
+      "attachment": true,
+      "reasoning": true,
+      "reasoning_options": [
+        {
+          "type": "effort",
+          "values": [
+            "low",
+            "high",
+            "max"
+          ]
+        }
+      ],
+      "tool_call": true,
+      "interleaved": {
+        "field": "reasoning_content"
+      },
+      "structured_output": true,
+      "temperature": true,
+      "release_date": "2026-09-18",
+      "last_updated": "2026-09-18",
+      "modalities": {
+        "input": [
+          "text",
+          "image",
+          "video",
+          "pdf"
+        ],
+        "output": [
+          "text"
+        ]
+      },
+      "open_weights": true,
+      "limit": {
+        "context": 1000000,
+        "output": 131072
+      },
+      "cost": {
+        "input": 0.37,
+        "output": 1.25,
+        "cache_read": 0.075,
+        "cache_write": 0
+      }
+    },
     "glm-5.3-flash": {
       "id": "glm-5.3-flash",
       "name": "GLM-5.3-Flash",
       "description": "Native multimodal GLM model for efficient coding and long-horizon agent tasks",
-      "family": "glm",
+      "family": "glm-flash",
       "attachment": true,
       "reasoning": true,
       "reasoning_options": [
@@ -282,9 +330,9 @@
         "output": 131072
       },
       "cost": {
-        "input": 0.075,
-        "output": 0.25,
-        "cache_read": 0.015,
+        "input": 0.15,
+        "output": 0.5,
+        "cache_read": 0.03,
         "cache_write": 0
       }
     },
@@ -605,6 +653,44 @@
         "cache_write": 0
       }
     },
+    "glm-4.6v-flash": {
+      "id": "glm-4.6v-flash",
+      "name": "GLM-4.6V-Flash",
+      "description": "Lightweight GLM vision model for visual reasoning, documents, and multimodal agents",
+      "family": "glm-flash",
+      "attachment": true,
+      "reasoning": true,
+      "reasoning_options": [
+        {
+          "type": "toggle"
+        }
+      ],
+      "tool_call": true,
+      "temperature": true,
+      "release_date": "2025-12-08",
+      "last_updated": "2025-12-08",
+      "modalities": {
+        "input": [
+          "text",
+          "image",
+          "video"
+        ],
+        "output": [
+          "text"
+        ]
+      },
+      "open_weights": true,
+      "limit": {
+        "context": 128000,
+        "output": 32768
+      },
+      "cost": {
+        "input": 0,
+        "output": 0,
+        "cache_read": 0,
+        "cache_write": 0
+      }
+    },
     "glm-4.7-flash": {
       "id": "glm-4.7-flash",
       "name": "GLM-4.7-Flash",

data/docs/deepdive/advanced/compaction.md

@@ -47,11 +47,10 @@ compactor.call(keep: 200)
 
 ##### The `/keep` command
 
-The console provides a `/keep` command that accepts a count or
+The console provides a `/keep` command that requires a count or
 percentage:
 
 ```ruby
-# /keep        # keep last 128 messages
 # /keep 50     # keep last 50 messages
 # /keep 75%    # keep approximately 75% of messages
 ```

data/docs/deepdive/advanced/context.md

@@ -82,7 +82,60 @@ 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, so most users never touch this directly.
+default (or 8 on the Alibaba provider, which rate limits more
+often), so most users never touch this directly.
+
+### Identity
+
+#### Overview
+
+A context has an id and a creation time, and so does each message it
+holds. The id is a UUIDv7 string, a UUID version that encodes its own
+creation timestamp, so an id sorts by the order it was created and
+carries the time it was made.
+
+#### How it works
+
+Read the id and creation time from a context, an agent, or a message:
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+ctx.talk "Hello"
+ctx.id          # => "01932f5a-..." (UUIDv7)
+ctx.created_at  # => 2026-09-11 04:21:07 UTC
+ctx.messages.first.id
+```
+
+[`LLM::Agent#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#id-instance_method)
+and
+[`LLM::Agent#created_at`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#created_at-instance_method)
+delegate to the context the agent wraps.
+[`LLM::Context#created_at`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#created_at-instance_method)
+and
+[`LLM::Message#created_at`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#created_at-instance_method)
+are read from the id rather than stored, so they return `nil` when
+the id is not a UUIDv7 string.
+
+#### Why would I use it?
+
+An id gives a conversation or a message a stable name you can log,
+correlate, or look up. Because the id is a UUIDv7, the same value
+also answers when the object was created, so sorting ids sorts by
+creation order and no separate timestamp column is needed.
+
+#### Notes
+
+The id is generated once and saved with the runtime state, so it
+survives a save and a restore. A payload written before ids existed
+has none, so its object is restored with a fresh id.
+[`LLM::Message#==`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#==-instance_method)
+ignores the id, so a difference in creation time alone does not make
+two messages unequal.
+[`LLM::Utils.timestamp`](https://r.uby.dev/api-docs/llm.rb/LLM/Utils.html#timestamp-instance_method)
+is the shared method that decodes a UUIDv7 timestamp.
 
 ### Manual loop
 
@@ -280,3 +333,163 @@ The mechanism is the same across all six concurrency strategies.
 The `:ractor` strategy delivers the interrupt through ractor
 message passing. The `:fork` strategy delivers it via xchan.
 
+### Messages
+
+#### Overview
+
+[`LLM::Context#messages`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#messages-instance_method)
+returns an
+[`LLM::Buffer`](https://r.uby.dev/api-docs/llm.rb/LLM/Buffer.html),
+an ordered, array-like collection of the conversation's
+[`LLM::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html)
+objects. Read it to inspect or filter a conversation, and edit it to
+shape what the model sees next.
+
+#### How it works
+
+A buffer is `Enumerable`, so it supports `each`, `find`, `map`,
+`select`, and the rest. It also offers the array methods a long
+conversation needs, including `first`, `last`, `take`, `drop`,
+`shift`, `pop`, `slice!`, `select!`, `reject!`, and `clear`:
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+ctx.talk "Hello"
+
+ctx.messages.size       # => 2
+ctx.messages.first      # => the user message
+ctx.messages.last       # => the assistant message
+ctx.messages.each { |m| puts "#{m.role}: #{m.content}" }
+```
+
+Because a message carries its own role, filtering by role is a normal
+`select`:
+
+```ruby
+ctx.messages.select(&:assistant?)
+```
+
+#### Why would I use it?
+
+Reading the buffer gives you the conversation as data, so you can log
+it, count tokens against it, or render it in your own UI. Editing the
+buffer lets you drop or keep specific messages without rebuilding the
+conversation.
+
+#### Notes
+
+Changing the buffer changes the next request, so edits are best made
+between turns. The compaction topic covers the built-in, bounded way
+to trim a long conversation.
+
+### Prompt
+
+#### Overview
+
+[`LLM::Prompt`](https://r.uby.dev/api-docs/llm.rb/LLM/Prompt.html)
+composes a single request from several role-aware messages. A prompt
+is not just a string: it is an ordered list of messages with explicit
+roles, so one turn can carry a system message, a user message, and
+anything else the model supports.
+
+#### How it works
+
+Call
+[`LLM::Context#prompt`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#prompt-instance_method)
+with a block, then pass the result to
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk).
+Inside the block, `system`, `user`, and `developer` append a message
+with the matching role, and `talk` appends one with an explicit
+role. The provider resolves each role to its provider-specific name:
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+
+prompt = ctx.prompt do
+  system "Your task is to assist the user"
+  user "Hello. Can you assist me?"
+end
+
+res = ctx.talk(prompt)
+```
+
+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.
+
+#### Why would I use it?
+
+A prompt keeps the roles of a multi-part request explicit, and it is
+an object you can build, pass around, and compare before it is sent.
+Use it when a turn needs more than one role, or when the same prompt
+is composed in more than one place.
+
+#### Notes
+
+[`LLM::Agent#prompt`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#prompt-instance_method)
+delegates to the context it wraps, so an agent accepts a prompt
+wherever it accepts a string. `LLM::Context#build_prompt` is an alias
+kept for compatibility.
+
+### Attachments
+
+#### Overview
+
+A message can carry files alongside its text. Pass file paths with the
+`with:` option of
+[`LLM::Context#ask`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#ask-instance_method),
+or tag a value explicitly with
+[`LLM::Context#local_file`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#local_file-instance_method),
+[`LLM::Context#image_url`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#image_url-instance_method),
+or
+[`LLM::Context#remote_file`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#remote_file-instance_method).
+
+#### How it works
+
+`ask` is a shorthand for a turn that returns a response. Pass the
+prompt and, optionally, files to attach with `with:`. It also accepts
+a `stream:` target or a block for streaming:
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+
+res = ctx.ask "What is in this photo?", with: "photo.jpg"
+res = ctx.ask "Summarize these", with: ["one.pdf", "two.pdf"]
+```
+
+The three helpers tag a value so the runtime knows how to send it, for
+turns built with `talk`:
+
+```ruby
+ctx.talk ["Describe this", ctx.local_file("/images/photo.png")]
+ctx.talk ["Describe this", ctx.image_url("https://example.com/photo.png")]
+ctx.talk ["Describe this", ctx.remote_file(res)]
+```
+
+`local_file` reads a path from disk, `image_url` passes a URL the
+provider fetches, and `remote_file` reuses a file a previous response
+produced.
+
+#### Why would I use it?
+
+Attachments let one turn carry an image, a PDF, or another file for the
+model to read, instead of pasting its contents into the prompt.
+
+#### Notes
+
+Which files a model accepts depends on the provider and the model.
+`ask` is a shorthand over `talk`: it builds the same prompt and returns
+the same `LLM::Response`, so anything that works with `talk` works with
+`ask`. An agent delegates all four methods to the context it wraps.
+

data/docs/deepdive/advanced/guard.md

@@ -9,9 +9,8 @@
 is the superclass for context-level supervisors. A guard is bound
 to a context and inspects each pending tool call before it runs.
 It can let the call through, cancel it, block it with an error, or
-answer for it with a synthesized result. Beyond loop detection,
-guards handle policy, validation, quotas, cost control, caching,
-and approval workflows.
+answer for it with a synthesized result. Guards handle policy,
+validation, quotas, cost control, caching, and approval workflows.
 
 #### How it works
 
@@ -74,11 +73,13 @@ onto every function the context binds, so it runs whenever a task is
 spawned, including tool calls a stream queues itself during a
 streaming turn. A blocked call yields its return without executing.
 
-The runtime binds a guard instance to the context and stamps it onto
-the functions it resolves, so a guard cannot carry state in instance
-variables between calls. Anything a guard needs to remember, like
-how many calls already ran, must come from the conversation
-(`messages`) or from class-level state.
+The runtime creates a guard instance for each batch of tool calls and
+stamps it onto the functions in that batch, so the same instance sees
+every call in a batch. State in an instance variable therefore lasts
+for the batch, but not from one batch to the next. Anything a guard
+needs to remember across batches, like how many calls already ran,
+must come from the conversation (`messages`) or from class-level
+state.
 
 ### Inspect
 
@@ -320,52 +321,3 @@ guard is not a replacement for
 [`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method),
 which caps the number of tool calls in a single turn. The two
 compose: the budget caps call count, and a guard enforces cost.
-
-### Loop
-
-#### Overview
-
-[`LLM::Guard::Loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Loop.html)
-is the built-in loop-detection guard. It reduces each assistant
-tool call to a `[tool name, arguments]` signature and checks whether
-the tail of the sequence is repeating.
-
-#### How it works
-
-When you want to detect repeated tool-call patterns, enable
-[`LLM::Guard::Loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Loop.html)
-and tune the `threshold:` option, which is the number of repeated
-patterns required before the guard intervenes (default `3`). When
-the guard detects a repeat, it returns an in-band
-[`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
-with type `"guard_error"` and a message that tells the model it is
-stuck and should change approach:
-
-```ruby
-ctx = LLM::Context.new(
-  llm,
-  guard: LLM::Guard::Loop,
-  guard_options: {threshold: 2}
-)
-ctx.talk "Research the market", tools: [FetchNews, FetchStocks]
-```
-
-#### Why would I use it?
-
-Loop detection matters for long, autonomous agent runs. Without it,
-a model that repeats a tool call with the same arguments can
-bounce between calls forever. The guard turns that into a bounded
-conversation: after the threshold, the model receives a message
-telling it to stop and try a different strategy.
-
-#### Notes
-
-[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
-enables
-[`LLM::Guard::Loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Loop.html)
-by default, so agents get loop protection without configuration.
-A custom guard can be passed through the `guard:` option to replace
-the loop guard entirely. Guards and the agent's tool budget
-complement each other: a guard blocks work that looks stuck, while
-[`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
-caps the total number of tool calls in a single turn.

data/docs/deepdive/features/builtin_tools.md

@@ -126,7 +126,7 @@ method with a `name:`.
 
 | Tool | Name | Parameters | Purpose |
 |---|---|---|---|
-| [`LLM::Tool::Rg`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html) | `rg` | `patterns`, `path`, `timeout` | Recursively search for lines matching patterns |
+| [`LLM::Tool::Rg`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html) | `rg` | `patterns`, `path`, `timeout`, `max_count`, `max_bytes` | Recursively search for lines matching patterns |
 | [`LLM::Tool::Which`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Which.html) | `which` | `name` | Locate an executable on the system PATH |
 
 #### Why would I use it?
@@ -152,14 +152,13 @@ executable with the given name. When no match is found it returns
 
 The command tools run real subprocesses: arbitrary commands through
 `exec`, Ruby code through `ruby`, commands inside a Bundler context
-through `bundle-exec`, and a fixed set of git subcommands through
+through `bundle`, and a fixed set of git subcommands through
 `git`. All of them accept a `timeout:` and kill the child process
 when the model interrupts the turn.
 
 ```ruby
 LLM::Tool::Exec.new.call(
-  name: "bundle",
-  arguments: ["exec", "rspec", "spec/llm"],
+  arguments: ["bundle", "exec", "rspec", "spec/llm"],
   timeout: 30
 )
 ```
@@ -168,14 +167,14 @@ LLM::Tool::Exec.new.call(
 
 When you want to run a command and capture its output, call the
 [`LLM::Tool::Exec#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Exec.html#call-instance_method)
-method with a `name:` and optional `arguments:`. The `git` tool
-takes a single `arguments:` array whose first element is a
-subcommand from a fixed set, the `ruby` tool runs
-its code in a fresh process, and the `bundle-exec` tool runs a
-command under the project's Bundler context. `bundle-exec` inherits
-the `BUNDLE_GEMFILE` environment variable when set, or defaults to a
-`Gemfile` in the current working directory, so the model can run
-project tools like `rspec` or `rake` with the right gems loaded:
+method with an `arguments:` array whose first element is the command
+name. The `git` tool takes the same array, with a subcommand from a
+fixed set as its first element, the `ruby` tool runs its code in a
+fresh process, and the `bundle` tool runs a command under the
+project's Bundler context. `bundle` uses the `BUNDLE_GEMFILE`
+environment variable when set, or a `Gemfile` in the current working
+directory otherwise, so the model can run project tools like `rspec`
+or `rake` with the right gems loaded:
 
 ```ruby
 LLM::Tool::Bundle.new.call(
@@ -186,10 +185,10 @@ LLM::Tool::Bundle.new.call(
 
 | Tool | Name | Parameters | Purpose |
 |---|---|---|---|
-| [`LLM::Tool::Exec`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Exec.html) | `exec` | `name`, `arguments`, `timeout` | Run a command without a shell |
+| [`LLM::Tool::Exec`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Exec.html) | `exec` | `arguments`, `timeout` | Run a command without a shell |
 | [`LLM::Tool::Git`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html) | `git` | `arguments`, `timeout` | Run a fixed set of git subcommands |
 | [`LLM::Tool::Ruby`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Ruby.html) | `ruby` | `code`, `timeout` | Run a string of Ruby code |
-| [`LLM::Tool::BundleExec`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/BundleExec.html) | `bundle-exec` | `name`, `arguments`, `timeout` | Run a command through `bundle exec` |
+| [`LLM::Tool::Bundle`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Bundle.html) | `bundle` | `arguments`, `timeout` | Run a command through `bundle` |
 
 #### Why would I use it?
 
@@ -241,8 +240,7 @@ format the result itself:
 
 ```ruby
 LLM::Tool::Exec.new.call(
-  name: "bundle",
-  arguments: ["exec", "rspec"],
+  arguments: ["bundle", "exec", "rspec"],
   max_bytes: 20_000
 )
 ```

data/docs/deepdive/features/console.md

@@ -58,6 +58,11 @@ The console requires the `curses` and `kramdown` gems. By default the
 tracer is disabled during the session. Set `tracer: true` to keep
 it active.
 
+The loop was previously named the REPL. `LLM::Repl` and
+`LLM::Agent#repl` still resolve to `LLM::Console` and
+`LLM::Agent#console`, so existing code keeps working, but new code
+should use the `console` names.
+
 The user-message label is exposed through
 [`LLM::Console#sender`](https://r.uby.dev/api-docs/llm.rb/LLM/Console.html#sender-instance_method),
 which defaults to `"You"`. The