llm.rb 12.2.0 → 12.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20d8c7c9c3d9d270f371781b28e7537a5c6921cff138cfc895bdbf0042003d07
-  data.tar.gz: 11b1abd397f1b13afadf4fe56e9670037a7c6ee586e945fd6a909505a4114122
+  metadata.gz: a1be1cd2af0cc8a817e510b04d1d74efd08cedf714b3faff4bdb7a58345fe14f
+  data.tar.gz: 3768fdf7f131d30c04d0ba83514bec31eb8d64de661980aa811a4e804a4df1e5
 SHA512:
-  metadata.gz: d99ad697a3b3d5d13a0804ab3cea569ffbf5dc88d853aabe7461c4ae59020519e140aa0de1c2b26336b03998212410449da238ea8df5f6a190012f026093464c
-  data.tar.gz: dd6314a5e1e7ba3899d1ab13ba4f076508481bc2e24d3502bfa5cc4ebfb66a2203772ffc9acb4987b741eea413997493b8f85a2a7a841cf768e80d9b412886a8
+  metadata.gz: 667c546559bb199c7381fbea97171b5e82e874098c40a763004db85667038aa430fa98592c4d42b1426e4536e288e70c018278b9e7af9fcf9b6d972eabd65cbe
+  data.tar.gz: 0163f85848ce7292905396458755d9ccb23298c6f7c6f06cf0532fb3bdb3517e1b188a022937eb540b823d82d7bc8d869549bc17c8d79767c5efe027bf5ae9be

data/CHANGELOG.md

@@ -15,8 +15,195 @@
 
 ## What's next
 
+Changes since `v12.3.1`.
+
+## v12.3.1
+
+Changes since `v12.3.0`.
+
+This release fixes a flickering issue in the curses-based REPL redraw.
+The full-screen clear that caused visible flickering has been replaced
+with a targeted cursor-hide approach, and stale rows from a larger
+transcript are now explicitly cleared to prevent ghost text from
+lingering when the transcript shrinks.
+
+### Fix
+
+* **repl: fix redraw flicker** <br>
+  Replace `Curses.clear` with `Curses.curs_set(0)` in the REPL redraw
+  method to avoid a full screen clear that caused visible flickering
+  during redraws. The drawing order is also adjusted so the status line
+  is drawn before the divider, and stale rows left over from a larger
+  transcript are now explicitly cleared to prevent ghost text from
+  lingering when the transcript shrinks.
+
+## v12.3.0
+
 Changes since `v12.2.0`.
 
+This release brings major improvements to the curses-based REPL
+(`LLM::Agent#repl`). The status line now shows a context-usage bar and
+running cost counter, the input field expands to three rows with
+full cursor navigation, model responses are rendered as styled markdown,
+and the UI stays responsive while the agent is working by running
+requests in a separate thread. A new `LLM::Stream::IO` and
+`LLM::Stream::Disabled` provide a uniform stream representation across
+all stream types.
+
+Mistral OCR support is added for extracting text from images and
+documents via the `/v1/ocr` endpoint. The `skills:` and `tools:` options
+on `LLM::Agent#repl` let you attach additional tools or skill directories
+for the duration of a session. `LLM::Object#merge!` rounds out the
+in-place merge API, and a new `LLM.logger` convenience method creates
+tracer logger instances with less verbosity.
+
+### Add
+
+* **Add `LLM.logger` convenience method** <br>
+  Add `LLM.logger(llm, ...)` as a shorter, less verbose way to create an
+  `LLM::Tracer::Logger` instance. Takes a provider and optional keyword
+  arguments forwarded to the logger constructor.
+
+* **Add `skills:` option to `LLM::Agent#repl`** <br>
+  `LLM::Agent#repl` now accepts a `skills:` keyword argument that attaches
+  one or more skill directories (containing `SKILL.md`) for the duration of
+  the repl session. Skills are loaded and converted to tools, combining with
+  any tools already configured on the agent, and are discarded when the
+  session ends.
+
+* **Add `LLM::Provider#ocr` base method** <br>
+  Add a base `ocr(...)` method to `LLM::Provider` that raises `NotImplementedError`
+  by default, establishing a common interface for providers that support OCR
+  (Optical Character Recognition) on images and documents.
+
+* **Add Mistral OCR endpoint support** <br>
+  The Mistral provider now supports OCR via its `/v1/ocr` endpoint. Call
+  `mistral.ocr(image_url: ...)` for images or `mistral.ocr(document_url: ...)`
+  for documents (e.g., PDFs). Returns an `LLM::Response` with extracted pages,
+  markdown content, and structured block data.
+
+* **Add `LLM::Object#merge!`** <br>
+  Add `LLM::Object#merge!` for in-place merging of hash data into an
+  `LLM::Object` instance, complementing the existing `#merge` method.
+
+* **Add `LLM::Stream::IO` and `LLM::Stream::Disabled`** <br>
+  `LLM::Stream::IO` wraps IO-like objects as stream targets, forwarding
+  streamed content via `#<<`. `LLM::Stream::Disabled` represents an explicitly
+  disabled stream with no-op callbacks.
+
+  This is part of an internal refactoring that lets all stream values — IO
+  objects, `true`, `false`, `nil`, and `LLM::Stream` instances themselves —
+  be represented by the same `LLM::Stream` interface via the new
+  `LLM::Stream.try` factory method.
+
+  Before this change the codebase had to perform ad-hoc type checks
+  (e.g. `if LLM::Stream === stream`) scattered throughout. After this
+  change all stream handling goes through a single uniform path, and
+  providers check `#enabled?` to decide whether to request streaming
+  from the API.
+
+### Change
+
+* **repl: rename `trace:` to `tracer:`** <br>
+  The `trace:` keyword argument in `LLM::Agent#repl` has been renamed to
+  `tracer:` for consistency with the rest of the codebase. The old `trace:`
+  name still works with a deprecation warning.
+
+* **repl: add context-usage bar and cost counter to the status line** <br>
+  The curses-based REPL status line now shows a small progress bar that
+  indicates how much of the model's context window remains as a percentage,
+  alongside a running cost estimate rendered on the right side of the status
+  line. The input line has been updated to show the provider name as a prefix.
+  Estimates are best-effort and depend on registry pricing data (see `data/`).
+
+* **repl: keep the UI responsive while a request is in progress** <br>
+  The curses-based REPL now spawns the agent request in a separate thread
+  and communicates streamed output through a queue, so the curses UI stays
+  responsive during model processing. Users can continue to scroll through
+  the transcript while the agent is working.
+
+* **repl: style transcript rows as structured data with bold labels** <br>
+  The curses-based REPL transcript now stores rows as structured data with
+  style metadata instead of plain strings, enabling bold rendering of the
+  `user:` and `agent:` labels for improved readability during interactive
+  sessions.
+
+* **repl: render a small subset of markdown** <br>
+  The curses-based REPL now renders model responses as styled markdown.
+  Headers and strong text render in bold, emphasis renders in underline,
+  and code spans and blocks are highlighted with inverted colors. Streaming
+  content is buffered and re-rendered on each tick so the transcript reads
+  cleanly as the agent responds. Requires the optional `kramdown` gem.
+
+* **repl: add cursor LEFT/RIGHT movement to the input line** <br>
+  The curses-based REPL input now supports cursor movement with the left
+  and right arrow keys, enabling in-place text editing before submitting
+  a prompt. The cursor position is tracked visually and moves backwards
+  on left-arrow and forwards on right-arrow.
+
+* **repl: add Ctrl+A and Ctrl+E keybindings to the input line** <br>
+  The curses-based REPL input now supports Ctrl+A to jump the cursor to
+  the start of the input line and Ctrl+E to jump it to the end, matching
+  common terminal editing conventions.
+
+* **repl: add `tools:` option to `LLM::Agent#repl`** <br>
+  `LLM::Agent#repl` now accepts a `tools:` keyword argument that attaches
+  additional tool classes or instances for the duration of the repl session.
+  These tools are combined with any tools already configured on the agent,
+  and are discarded when the session ends.
+
+* **repl: add repl support to ActiveRecord and Sequel agent models** <br>
+  `acts_as_agent` (ActiveRecord) and `plugin :agent` (Sequel) models now
+  expose a `repl` method that delegates to the underlying agent's
+  read-eval-print loop. This allows interactive debugging and inspection
+  of persisted agent state at runtime. Note that changes made during a
+  repl session do not persist back to the database.
+
+* **repl: add extra padding between markdown nodes** <br>
+  The curses-based REPL markdown renderer now adds extra vertical spacing
+  between certain markdown elements — paragraphs, headers, and codeblocks —
+  for improved readability of model responses.
+
+* **repl: add a visual divider between transcript and the rows below it** <br>
+  The curses-based REPL now draws a horizontal divider line (using a unicode
+  `─` character) to separate the transcript area from the status and input
+  rows below it. A single empty buffer row is also added between the
+  transcript and the divider, preventing transcript text from running too
+  close to the status and input rows.
+
+* **repl: expand input field to 3 rows** <br>
+  The curses-based REPL input field now spans three rows instead of one,
+  wrapping text that exceeds the terminal width onto subsequent lines. A
+  scrollable viewport follows the cursor so the active line stays visible,
+  and common navigation commands (Ctrl+A, Ctrl+E, cursor keys) work across
+  all three rows of the expanded input area.
+
+* **Refresh OpenAI model metadata** <br>
+  Add new OpenAI models to the registry, including `gpt-5.6`,
+  `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`, and
+  `gpt-realtime-2.1`, with associated pricing, capabilities, and
+  limits.
+
+### Fix
+
+* **Fix Ollama non-streaming response handling** <br>
+  Fix the Ollama provider to properly handle the non-streaming path. When
+  the provider returns a raw NDJSON response body (instead of streaming),
+  the response is now parsed and merged into a single `LLM::Object` before
+  being returned to the caller. Previously the non-streaming path was
+  effectively broken and would fail to produce a valid completion response.
+
+* **repl: handle a negative context window allowance in the usage bar** <br>
+  Fix a crash in the curses-based REPL context-usage bar when the context
+  window allowance is exceeded (used > total). The negative width value that
+  resulted from this edge case could cause curses errors; it now gracefully
+  defaults to `0%` and zero bar width.
+
+* **Fix YARD documentation across provider and tool files** <br>
+  Fix unnamed, misnamed, and missing `@param` tags in `LLM::Repl::Status`,
+  `LLM::Tool::Git`, `LLM::Tool::Pwd`, `LLM::Tool::Rg`, and
+  `LLM::Tool::SwapText`.
+
 ## v12.2.0
 
 Changes since `v12.1.0`.

data/README.md

@@ -14,11 +14,10 @@
 
 Welcome to the canonical llm.rb repository.
 
-llm.rb is not a library, framework or toolkit but an advanced runtime
-for building highly capable AI applications on CRuby. By default
-it has zero runtime dependencies although certain functionality –
-such as ActiveRecord support – require optional dependencies
-that are opt-in.
+llm.rb is an advanced runtime for building capable AI applications
+on CRuby. By default it has zero runtime dependencies although certain
+functionality – such as ActiveRecord support – require
+optional dependencies that are opt-in.
 
 ## Features
 
@@ -121,13 +120,14 @@ agent.talk "Explain Ruby fibers."
 
 The [LLM::Agent#repl](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
 method allows an agent to spawn a read-eval-print loop
-that can be useful during the development and operation
-of agents. It can be used to debug tool calls, confirm an
-agent has done what was expected, or improve the agent
-by asking questions about what it has done up to that point.
+that can be useful while developing or operating agents.
+It can be used to debug tool calls, confirm an
+agent has done what was expected, or improve an agent by
+asking questions about what it has done up to that point.
 
 This feature requires that the [curses](https://github.com/ruby/curses)
-library is installed and available to require.
+and [kramdown](https://github.com/gettalong/kramdown) libraries are
+installed and available to require.
 
 ```ruby
 llm = LLM.deepseek(key: ENV["KEY"])
@@ -135,6 +135,47 @@ agent = LLM::Agent.new(llm)
 agent.repl
 ```
 
+The read-eval-print loop accepts both `tools` and `skills`
+options that lets you attach additional tools or skills
+for the duration of the session. This is in addition to
+any tools or skills that might already be associated with
+an agent.
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl(tools: [Debugger], skills: [__dir__])
+```
+
+A number of optional tools are distributed as part
+of llm.rb. They power the agents that can be found in
+the [agents/](agents/) directory, so they're optimized
+for developer tasks.
+
+The following example starts a read-eval-print loop
+with all of the builtin tools available.
+
+```ruby
+require "llm"
+require "lll/tools"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl(tools: LLM::Tool.subclasses)
+```
+
+By default the tracer is disabled for the duration of
+the session. This can be configured through the
+`tracer` option. Setting it to `true` will configure
+the REPL to use 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"))
+agent.repl(tracer: true, tools: [Debugger])
+```
+
 #### LLM::MCP
 
 The Model Context Protocol (MCP) has first-class support