llm.rb 13.1.0 → 14.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb5c6136080e0136309987a4e042e6f646c26de39e38d6422bb3904fc665bf5f
-  data.tar.gz: d832b9c19f4173ba6e5631ffdc57f495eb4a9a8fb0b657801de185707bc4085e
+  metadata.gz: 80d9ecf944df7561e9a0ac70bb37225dac11f18b13fba94d689b672da3b27e6f
+  data.tar.gz: d3986e29989bcd415c40cd26fd4361ac8b3f92461cf81f2f5abf5a9d291cd068
 SHA512:
-  metadata.gz: 7ba4417a8c5b48a28b2baf04a2960374eae28c44dc2ec19e8f79da9a95f75fdf8cb5f1c749e6bfa1b1f6d1c790723e2005cb576f94f118997bb5e8b0f5d53a63
-  data.tar.gz: 0105af6bcaaec50930546e3a5a7207b8cf65e30bbea33359784061159748a3e2f3afb6e2b599eaad904e0c477d9827bb444c698315e56d43572be6ba86fe98b8
+  metadata.gz: 702cd38c23fa817b068dd9b7c8942f3641915c874e1ed9bef6526127767092f138fd09c320cd54fafc265e2b33131d0cca8b7376f2c7b5e9e3203e66b1f4a513
+  data.tar.gz: f5eebb31abe9349e451bb1410b01a35353dd466fc66b6df230c5cb6be469856be234dea3351f885eb9c616375c0b84bf18e72dc268b88454997919f475a89774

data/CHANGELOG.md

@@ -17,6 +17,326 @@
 
 *No unreleased changes yet. Check back after the next release.*
 
+## v14.0.0
+
+Changes since `v13.1.0`.
+
+This release replaces the `transformer=` setter with the new
+`LLM::Transformer` class hierarchy, refactors guards into the
+`LLM::Guard` superclass with per-tool-call interception, and replaces
+the agent `tool_attempts` parameter with the `tool_budget` class DSL.
+It also adds the Moonshot (Kimi) provider, the `LLM::Tool.set`
+bulk-assignment DSL, a `LLM::Function#return` shorthand, and a wide
+range of REPL improvements.
+
+### Breaking
+
+#### Migration
+
+| Old | New |
+|-----|-----|
+| `ctx.transformer = MyTransformer` | `LLM::Context.new(transformer: MyTransformer)` |
+| `transformer.call(ctx, prompt, params)` | `transformer.call(message:, **opts)` |
+| `~/.llm.rb/session.json` (shared across providers) | `~/.llm.rb/<provider>/<uuid>.json` (scoped per provider and directory) |
+| `agent.talk(tool_attempts: 25)` | `set :tool_budget => 50` (disabled by default) |
+| `LLM::LoopGuard` | `LLM::Guard::Loop` |
+| `guard: true` / `ctx.guard = MyGuard` | `guard: MyGuard, guard_options: {}` |
+| `guard.call(ctx)` (warning string) | `guard.call(function:)` (`LLM::Function::Return` or nil) |
+| `LLM::GuardError` | `"guard_error"` |
+
+* **replace the transformer setter with `LLM::Transformer`** <br>
+  The previous `transformer=` setter and 3-argument
+  `call(ctx, prompt, params)` interface on `LLM::Context` have been
+  replaced by the new
+  [`LLM::Transformer`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer.html)
+  class interface. Configure a transformer class through `transformer:`
+  and options through `transformer_options:` instead.
+
+* **cli: scope session persistence per provider and directory** <br>
+  `bin/llm.rb` no longer shares a single session file between providers.
+  Each provider now has a `~/.llm.rb/<provider>.json` file that maps the
+  current working directory to a UUID-scoped session file under
+  `~/.llm.rb/<provider>/<uuid>.json`, so sessions are scoped to both the
+  provider and the directory they were started in.
+
+* **cli: harden the executable against bad inputs** <br>
+  `bin/llm.rb` now prints an error message followed by the help menu and
+  exits with status 1 when the `-p` switch is given without an argument or
+  when an unknown option is passed. Previously unknown options produced a
+  warning but the run continued. The session-file lookup also no longer
+  rewrites `~/.llm.rb/<provider>.json` when it already exists.
+
+* **agent: replace `tool_attempts` with the `tool_budget` class DSL** <br>
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
+  replaces the `tool_attempts` parameter with a `tool_budget` class DSL
+  (`tool_budget { 50 }`) that caps the number of tool calls allowed in a
+  single turn. Once the budget is spent, the agent sends an in-band
+  advisory message back through the model telling it to solve the problem
+  with fewer tool calls.
+  <br><br>
+  The feature is now disabled by default; the old `tool_attempts`
+  parameter defaulted to 25, which long-horizon agents could easily
+  exhaust in a single turn.
+
+* **guard: replace `LLM::LoopGuard` with the `LLM::Guard` class hierarchy** <br>
+  [`LLM::Guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html)
+  is a new superclass for context-level supervisors, with
+  [`LLM::Guard::Loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Loop.html)
+  (replacing `LLM::LoopGuard`) and
+  [`LLM::Guard::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Null.html)
+  as the built-in implementations.
+  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+  now accepts `guard:` (a guard class defaulting to `LLM::Guard::Null`)
+  and `guard_options:` (a hash forwarded to the guard's `call` method),
+  matching the transformer and compactor interfaces. The old boolean and
+  hash forms of `guard` and the `guard=` setter are removed. `LLM::Agent`
+  enables `LLM::Guard::Loop` by default.
+
+* **guard: block individual tool calls instead of the whole batch** <br>
+  [`LLM::Guard#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html#call-instance_method)
+  now receives the pending `function:` and returns an
+  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+  (or nil) instead of a warning string for the entire batch, so a guard
+  can block a single tool call while the rest of the batch still
+  executes. Custom guards that implemented the old `call(ctx)`
+  warning-string interface must be updated to return a
+  `LLM::Function::Return` instead.
+
+* **errors: drop `LLM::GuardError`** <br>
+  Remove `LLM::GuardError`. The constant was never raised as an
+  exception; it only named the in-band error type for guarded tool
+  returns. Guarded tool returns now use the string `"guard_error"` as
+  their error type.
+
+### Core
+
+* **add `LLM::Provider#build_messages` for assembling outgoing messages** <br>
+  [`LLM::Provider#build_messages`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#build_messages-instance_method)
+  normalizes a prompt into `LLM::Message` objects and prepends the existing
+  history, replacing the per-provider `build_complete_messages`
+  implementation. The method is idempotent: prompts that are already
+  [`LLM::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html)
+  instances or arrays of messages are returned as-is.
+
+* **copy the `params` hash in `LLM::Context` and `LLM::Agent`** <br>
+  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) and
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now copy
+  the `params` hash in their constructors before mutating it, leaving the
+  caller's hash untouched. Previously the constructors deleted keys from
+  the caller's hash in place.
+
+* **gemspec: ship the deepdive sub-files in the gem** <br>
+  The gemspec now includes `resources/deepdive/*/*.md` in the gem
+  package, so the full deepdive guide (fundamentals, advanced,
+  protocols, and everything-else chapters) is available after
+  installation.
+
+* **add short aliases to `LLM::Cost`** <br>
+  [`LLM::Cost`](https://r.uby.dev/api-docs/llm.rb/LLM/Cost.html) now
+  offers short aliases for its cost accessors: `input`, `output`,
+  `input_audio`, `output_audio`, `input_image`, `cache_read`,
+  `cache_write`, and `reasoning`. Each alias matches the key used by
+  `#to_h`, so `cost.input` reads the same value as `cost.input_costs`.
+
+### Provider
+
+* **add `LLM::Moonshot` for the Moonshot AI provider** <br>
+  [`LLM::Moonshot`](https://r.uby.dev/api-docs/llm.rb/LLM/Moonshot.html)
+  is a new provider that talks to
+  [Moonshot AI](https://platform.moonshot.ai) through its
+  OpenAI-compatible Kimi API. Create an instance with
+  [`LLM.moonshot`](https://r.uby.dev/api-docs/llm.rb/LLM.html#moonshot-class_method),
+  which accepts the same `key:`, `host:`, and `base_path:` options as the
+  OpenAI provider. The provider defaults to the `kimi-k3` model and
+  supports chat completions, streaming, tool calls, and structured output
+  through the shared OpenAI-compatible path; image, audio, moderation,
+  responses, and vector store endpoints raise `NotImplementedError`.
+  Model metadata ships in `data/moonshot.json` for the registry.
+
+### Transformer
+
+* **add `LLM::Transformer` for rewriting messages before they reach the provider** <br>
+  [`LLM::Transformer`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer.html)
+  is a new superclass for message transformers. A transformer is bound to a
+  context and rewrites a single message before it is sent to the provider,
+  which makes it possible to redact personal information or rewrite any
+  message before it goes out over the wire. Each subclass implements
+  `call(message:, **opts)` and returns the message to send, either by
+  mutating it in place or returning a new one.
+  [`LLM::Transformer::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer/Null.html)
+  is a no-op transformer used as the default.
+
+* **hook the transformer API into `LLM::Context`** <br>
+  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) now
+  accepts `transformer:` (a transformer class defaulting to
+  `LLM::Transformer::Null`) and `transformer_options:` (a hash forwarded to
+  the transformer's `call` method). The transformer runs on the most recent
+  message in both chat and responses turns.
+  [`LLM::Stream#on_transform`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_transform-instance_method)
+  and
+  [`LLM::Stream#on_transform_finish`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_transform_finish-instance_method)
+  now receive the transformer instance as their single argument.
+
+### Tool
+
+* **add `LLM::Tool.set` for bulk-assigning tool properties** <br>
+  [`LLM::Tool.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#set-class_method)
+  accepts a hash of `name`, `description`, `parameters`, `required`, and
+  `defaults` to configure a tool subclass in a single call. Parameters are
+  defined as tuples of `[name, type, description, options]`, matching the
+  same interface as the existing `parameter` DSL. Unknown keys raise
+  `KeyError`.
+
+### Function
+
+* **add `LLM::Function#return` for building tool returns** <br>
+  [`LLM::Function#return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#return-instance_method)
+  returns an
+  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+  built from the function's own id and name, using the given hash as its
+  value. It is a shorthand mainly useful inside a
+  [`LLM::Guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html)
+  subclass and is defined via `define_method` because `return` is a Ruby
+  keyword.
+
+### Guard
+
+* **run the guard for streamed tool calls** <br>
+  Fix a gap where the guard was not consulted when a tool call was queued
+  while a response was still streaming. The guard is now stamped onto the
+  functions a context binds, so it runs wherever a task is spawned,
+  including tool calls queued from a stream. A blocked call yields its
+  `guard_error` return without executing.
+
+### Agent
+
+* **add `LLM::Agent#compacted?`** <br>
+  [`LLM::Agent#compacted?`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#compacted%3F-instance_method)
+  delegates to the wrapped
+  [`LLM::Context#compacted?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#compacted%3F-instance_method)
+  and reports whether the conversation has been compacted, so callers
+  can detect when history was trimmed.
+
+### Change
+
+* **openai: default to `gpt-5.6-luna`** <br>
+  The default OpenAI chat model has changed from `gpt-5.4-mini` to
+  `gpt-5.6-luna`. The new model is OpenAI's fastest and most affordable
+  option, matching the kind of default llm.rb aims for.
+
+### Repl
+
+* **show an unknown context state after `/compact`** <br>
+  After running `/compact`, the REPL status line now renders `Context
+  compacted` and the context-usage bar shows `???` instead of a percentage,
+  because the used context is unknown until the next response.
+
+* **land on a blank line after Ctrl+N at the end of history** <br>
+  When recalling history with Ctrl+P and Ctrl+N, Ctrl+N at the last item
+  now advances to a blank line so you can start typing new input, instead
+  of staying stuck on the last item in history (the previous behavior).
+  Recalling with Ctrl+P or Ctrl+N also no longer overwrites the input when
+  there is no history to show.
+
+* **restore history wrap for Ctrl+P and Ctrl+N** <br>
+  Fix a regression where Ctrl+P and Ctrl+N recalled history text without
+  reflowing it into rows, so recalled lines wider than the terminal were
+  clipped. Recalled text now flows through the same word-wrap path as
+  typed input and wraps at the terminal width.
+
+* **restore Ctrl+D deletion across rows** <br>
+  Fix a bug where Ctrl+D at the end of an input row was a no-op, so
+  multiline input could not be joined by deleting a row break. Deleting
+  at the end of a row now consumes the break and pulls the next row up,
+  restoring the split space so merged words do not run together.
+
+* **center the buffer with 20% gutters** <br>
+  The curses-based REPL now centers
+  [`LLM::Repl::Buffer`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Buffer.html)
+  in a content area that is 60% of the terminal width, with an unused 20%
+  gutter on each side. The drawing area is based on the available rows and
+  columns instead of a fixed 80-column width, and `Buffer#wrap` now
+  hard-breaks words that overflow the width onto the next row, fixing a
+  bug where a word could be cut off between rows.
+
+* **apply markdown to previous messages** <br>
+  The curses-based REPL now renders every message in the buffer with
+  markdown styling, including messages that were already present when
+  the session started or restored from disk. Previously only newly
+  streamed responses were styled; older messages fell back to plain
+  text.
+
+* **add `LLM::Repl#sender` for the user label** <br>
+  [`LLM::Repl#sender`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl.html#sender-instance_method)
+  returns the label used for user messages in the curses-based REPL. It
+  defaults to `"You"` (previously `"user"`), and the buffer layout now
+  places each label on its own line followed by the message content and a
+  blank line.
+
+* **add `LLM::Repl::Color` for coloring the curses UI** <br>
+  Add
+  [`LLM::Repl::Color`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Color.html)
+  as a new module that returns Curses color bitmasks. `Color.enable`
+  initializes 8 color pairs, and methods like `Color.blue` return the
+  corresponding `Curses.color_pair(X)` bitmask, which can be bitwise
+  OR'ed with other attributes such as `Curses::A_BOLD`. User labels in
+  the REPL are now rendered in blue instead of plain bold text.
+
+* **split on words rather than characters** <br>
+  `LLM::Repl::Buffer#wrap` now breaks text on word boundaries instead of
+  wrapping one character at a time. A word that does not fit on the
+  current row moves to the next, and only a single word longer than the
+  whole width is hard-broken, so text is never clipped by the window.
+
+* **render kramdown typographic symbols and smart quotes** <br>
+  Fix a bug where certain character sequences such as `...` were not
+  rendered at all in the curses-based REPL. Kramdown parses them into
+  `:typographic_sym` and `:smart_quote` nodes, which previously fell
+  through to the children clause and were dropped. The markdown renderer
+  now maps them to their unicode equivalents: ellipsis, en and em
+  dashes, guillemets, and single and double quotation marks.
+
+* **apply colors to the markdown renderer** <br>
+  The curses-based REPL now renders markdown with the `LLM::Repl::Color`
+  palette: headers and strong text in white, code spans and code blocks
+  in green, and links in underlined green, on the black background.
+  Previously markdown styling used bold, underline, and reverse video
+  attributes only.
+
+* **wrap the input line at word boundaries** <br>
+  The curses-based REPL input line now wraps words whole onto the next
+  row at the terminal width instead of cutting them in half. A word that
+  does not fit on the current row moves to the next row, and only a
+  single word longer than the whole width is hard-broken, so typed text
+  is never clipped by the window.
+
+* **distinguish the connecting and thinking status bar phases** <br>
+  The curses-based REPL status bar now shows `Connecting • Esc to
+  cancel` while the model is establishing a connection, then switches
+  to `Thinking • Esc to cancel` once a tool call or text fragment
+  arrives on the stream. Active tool calls appear in the status bar
+  with a lambda indicator.
+
+* **add emoji to the status bar phases** <br>
+  The curses-based REPL status bar now uses emoji to identify each
+  phase at a glance: a globe (`🌐`) while the model is connecting, and
+  a brain (`🧠`) while it is thinking. The text after the emoji still
+  reads `Connecting • Esc to cancel` and `Thinking • Esc to cancel`
+  respectively.
+
+* **render the status bar with color and attributes** <br>
+  The curses-based REPL status bar now supports colored and attributed
+  status text, so the lambda indicator for active tool calls is drawn
+  in bold red.
+
+### Registry
+
+* **refresh model metadata across providers** <br>
+  Update `data/*.json` files with current provider model listings and
+  pricing. Remove the deprecated Claude Opus 4.1 entries from the
+  Anthropic registry, add `Qwen/Qwen3.8-Max` to DeepInfra, and add a
+  `low` reasoning-effort option to DeepSeek.
+
 ## v13.1.0
 
 Changes since `v13.0.0`.