llm.rb 12.1.0 → 12.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4c7d2a7e0fd6a5b05cfdaaf2702f94f9a15d3e277739559f5cb676768fe6a9c
-  data.tar.gz: ad3081a38e1096459791ec6cffd1ae0a8550f5d4df2c6c95fd8842b78a0024f4
+  metadata.gz: ae69643ba5cddb3b39899ca27deabd69071c23fb30d787b99630d97b64ef0dcc
+  data.tar.gz: cdcb6eee3f60742d2cf37f22518e10eab3b4fe3eabd5d0e0958d5d4116cd63d4
 SHA512:
-  metadata.gz: 0e5a58f5b22d07b05d981423414de270b1ae760c7920452e736a55709c6c1eeee941407de8a8667365ee83943deeb0554d05bec5425b7132fe907dc62f349ffa
-  data.tar.gz: fabedc3aad36ba5cbaf7b126c55ddc3cbb428aadb3b2887a40e429daf35c65ff81a4d8c903583dea27c051d89f076d9d3446736e948954a6cef26065aebfa624
+  metadata.gz: 8817934bdc50e10ab8387df49d77811a397ef1f4c0a78f3ae7475b26fd2494e4404bc365d746fdba22cb3102f4fb3238b51a8253f9abd7b7882066b098dbe748
+  data.tar.gz: 68315c12c2f73c4314e1baf972498bd041952ec8591ebe8b51c6084e70cbf183427314cf04c4025d94dedd85c985c0db1ae5d7ef3473618484a679c11daa68c6

data/CHANGELOG.md

@@ -15,8 +15,256 @@
 
 ## What's next
 
+Changes since `v12.3.0`.
+
+## 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`.
 
+This release adds Mistral as a new provider with chat completions, streaming, tool calls,
+structured outputs, file/image attachments, and embeddings support. It introduces
+the `trace:` option to `LLM::Agent#repl` for keeping the tracer active during
+interactive sessions.
+
+Several fixes land for the Google provider (generationConfig parameter leakage),
+`LLM::Context#tracer=` (always assigning nil), `LLM::Provider#with_tracer(nil)`
+(nil fallback), and `LLM::Context#repair!` (dropping Struct returns).
+
+The default HTTP timeout has been increased from 60s to 180s to better accommodate
+reasoning models and large structured outputs, and the Anthropic default model has
+been updated to `claude-opus-4-8`. Model metadata has been refreshed across
+Anthropic, AWS Bedrock, DeepInfra, Google, and xAI, with Mistral model data added
+to the registry.
+
+### Add
+
+* **Add `trace:` option to `LLM::Agent#repl`** <br>
+  `LLM::Agent#repl` now accepts a `trace:` keyword argument. By default
+  the tracer is disabled for the duration of the repl session to prevent
+  curses UI interference from output written to `$stdout` or `$stderr`.
+  Set `trace: true` to keep the tracer active during the session, which
+  is useful when the tracer writes to a file rather than the terminal.
+
+* **Add a new provider: LLM::Mistral** <br>
+  [Mistral](https://mistral.ai) is now supported through its
+  OpenAI-compatible API. The provider supports chat completions,
+  streaming, tool calls, structured output (schema), file/image
+  attachments, and embeddings. Use `LLM.mistral(...)` to create a
+  provider instance.
+
+* **Add `LLM.mistral(...)` convenience method** <br>
+  A new top-level accessor (`LLM.mistral`) returns an `LLM::Mistral`
+  provider instance, matching the pattern used by other providers.
+
+### Fix
+
+* **Fix Google `generationConfig` parameter leakage** <br>
+  Fix a bug in the Google provider where non-generation parameters
+  (`role`, `model`, `messages`, `stream`) were leaking into the
+  `generationConfig` object alongside legitimate generation config
+  parameters such as `temperature`. Non-config parameters are now
+  filtered out before constructing `generationConfig`.
+
+* **Fix `LLM::Context#tracer=` always assigning `nil`** <br>
+  The `LLM::Context#tracer=` setter had a bug where it always assigned
+  `nil` regardless of the tracer value passed. It now correctly assigns
+  the given tracer or falls back to `LLM::Tracer::Null`.
+
+* **Fix `LLM::Provider#with_tracer(nil)` fallback** <br>
+  `LLM::Provider#with_tracer(nil)` now falls back to
+  `LLM::Tracer::Null` instead of setting a `nil` tracer directly.
+
+* **Fix `LLM::Context#repair!` dropping `Struct` returns** <br>
+  `LLM::Context#repair!` used `[*prompt]` to wrap the prompt before
+  grepping for return objects. Since `LLM::Function::Return` is a
+  `Struct`, the splat operator expanded it into its member values
+  instead of wrapping it, causing the grep to silently drop returns.
+  The fix wraps both sources in an array before flattening.
+
+### Change
+
+* **Increase default provider timeout from 60s to 180s** <br>
+  The default HTTP timeout for all providers has been increased from
+  60 to 180 seconds to better accommodate long-running requests such
+  as reasoning models and large structured outputs.
+
+* **Change Anthropic default model to `claude-opus-4-8`** <br>
+  The default Anthropic chat model has been updated from
+  `claude-sonnet-4-20250514` to `claude-opus-4-8`, reflecting the
+  latest model release from Anthropic.
+
+* **Refresh model metadata** <br>
+  Update model listings, pricing, and capabilities for Anthropic,
+  AWS Bedrock, DeepInfra, Google, and xAI. Add Mistral model data
+  to the registry.
+
 ## v12.1.0
 
 Changes since `v12.0.0`.

data/README.md

@@ -14,16 +14,15 @@
 
 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
 
 The runtime supports OpenAI, OpenAI-compatible endpoints, Anthropic, Google
-Gemini, DeepSeek, DeepInfra, xAI, Z.ai, AWS Bedrock, Ollama, and llama.cpp.
+Gemini, Mistral, DeepSeek, DeepInfra, xAI, Z.ai, AWS Bedrock, Ollama, and llama.cpp.
 It has first-class support for streaming, tool calls,  MCP
 and A2A, embeddings, vector stores and the RAG pattern.
 
@@ -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
@@ -265,28 +306,37 @@ agent.talk "perform research"
 <summary>What providers does llm.rb support?</summary>
 <br>
 <p>
-China-based
 
-* DeepSeek
-* zAI
+**Cloud**
+
+The following cloud-based providers are available to choose from. <br>
+In no particular order:
+
+🇺🇸 OpenAI <br>
+🇺🇸 DeepInfra <br>
+🇺🇸 xAI <br>
+🇺🇸 Google (Gemini) <br>
+🇺🇸 AWS bedrock <br>
+🇺🇸 Anthropic <br>
+🇨🇳 DeepSeek <br>
+🇨🇳 zAI <br>
+🇪🇺 Mistral <br>
 
-US-based
+**Weights**
 
-* OpenAI
-* Google (Gemini)
-* xAI
-* AWS bedrock
-* DeepInfra
-* Anthropic
+The following providers provide access to open-weight models. <br>
+In no particular order:
 
-Openweights
+🇺🇸 DeepInfra <br>
+🇺🇸 AWS bedrock <br>
+🇨🇳 DeepSeek <br>
+🇨🇳 zAI <br>
+🇪🇺 Mistral <br>
 
-* DeepSeek
-* zAI
-* DeepInfra
-* AWS bedrock
+**Local**
 
-Host your own
+The following providers can be run locally on your own hardware. <br>
+In no particular order:
 
 * Ollama
 * Llamacpp

data/data/anthropic.json

@@ -31,7 +31,7 @@
       "tool_call": true,
       "structured_output": true,
       "temperature": true,
-      "knowledge": "2025-03-31",
+      "knowledge": "2025-05",
       "release_date": "2025-11-24",
       "last_updated": "2025-11-24",
       "modalities": {
@@ -321,7 +321,7 @@
       "tool_call": true,
       "structured_output": true,
       "temperature": true,
-      "knowledge": "2025-03-31",
+      "knowledge": "2025-05",
       "release_date": "2025-11-24",
       "last_updated": "2025-11-01",
       "modalities": {
@@ -368,6 +368,7 @@
       "tool_call": true,
       "structured_output": true,
       "temperature": false,
+      "knowledge": "2026-01",
       "release_date": "2026-05-28",
       "last_updated": "2026-05-28",
       "modalities": {

data/data/bedrock.json

@@ -92,6 +92,47 @@
         "cache_write": 3.75
       }
     },
+    "jp.anthropic.claude-haiku-4-5-20251001-v1:0": {
+      "id": "jp.anthropic.claude-haiku-4-5-20251001-v1:0",
+      "name": "Claude Haiku 4.5 (JP)",
+      "description": "Fast Claude model for responsive assistance, classification, and lightweight agents",
+      "family": "claude-haiku",
+      "attachment": true,
+      "reasoning": true,
+      "reasoning_options": [
+        {
+          "type": "budget_tokens",
+          "min": 1024
+        }
+      ],
+      "tool_call": true,
+      "structured_output": true,
+      "temperature": true,
+      "knowledge": "2025-02-28",
+      "release_date": "2025-10-15",
+      "last_updated": "2025-10-15",
+      "modalities": {
+        "input": [
+          "text",
+          "image",
+          "pdf"
+        ],
+        "output": [
+          "text"
+        ]
+      },
+      "open_weights": false,
+      "limit": {
+        "context": 200000,
+        "output": 64000
+      },
+      "cost": {
+        "input": 1,
+        "output": 5,
+        "cache_read": 0.1,
+        "cache_write": 1.25
+      }
+    },
     "us.meta.llama4-scout-17b-instruct-v1:0": {
       "id": "us.meta.llama4-scout-17b-instruct-v1:0",
       "name": "Llama 4 Scout 17B Instruct (US)",
@@ -1349,6 +1390,7 @@
       ],
       "tool_call": true,
       "temperature": false,
+      "knowledge": "2026-01",
       "release_date": "2026-05-28",
       "last_updated": "2026-05-28",
       "modalities": {
@@ -2328,6 +2370,7 @@
       ],
       "tool_call": true,
       "temperature": false,
+      "knowledge": "2026-01",
       "release_date": "2026-05-28",
       "last_updated": "2026-05-28",
       "modalities": {
@@ -2835,6 +2878,7 @@
       ],
       "tool_call": true,
       "temperature": false,
+      "knowledge": "2026-01",
       "release_date": "2026-05-28",
       "last_updated": "2026-05-28",
       "modalities": {
@@ -3136,6 +3180,7 @@
       ],
       "tool_call": true,
       "temperature": false,
+      "knowledge": "2026-01",
       "release_date": "2026-05-28",
       "last_updated": "2026-05-28",
       "modalities": {
@@ -3181,6 +3226,7 @@
       ],
       "tool_call": true,
       "temperature": false,
+      "knowledge": "2026-01",
       "release_date": "2026-05-28",
       "last_updated": "2026-05-28",
       "modalities": {
@@ -3518,6 +3564,7 @@
       ],
       "tool_call": true,
       "temperature": false,
+      "knowledge": "2026-01",
       "release_date": "2026-05-28",
       "last_updated": "2026-05-28",
       "modalities": {

data/data/deepinfra.json

@@ -557,7 +557,7 @@
       },
       "open_weights": true,
       "limit": {
-        "context": 16384,
+        "context": 262144,
         "output": 65536
       },
       "cost": {
@@ -767,7 +767,7 @@
         "output": 16384
       },
       "cost": {
-        "input": 0.039,
+        "input": 0.037,
         "output": 0.17
       }
     },

data/data/google.json

@@ -562,6 +562,38 @@
         "input_audio": 0.3
       }
     },
+    "gemini-omni-flash-preview": {
+      "id": "gemini-omni-flash-preview",
+      "name": "Gemini Omni Flash Preview",
+      "description": "Video generation and editing model for fast, conversational text- and image-to-video workflows",
+      "family": "gemini",
+      "attachment": true,
+      "reasoning": true,
+      "reasoning_options": [],
+      "tool_call": false,
+      "temperature": true,
+      "release_date": "2026-06-30",
+      "last_updated": "2026-06-30",
+      "modalities": {
+        "input": [
+          "text",
+          "image",
+          "video"
+        ],
+        "output": [
+          "video"
+        ]
+      },
+      "open_weights": false,
+      "limit": {
+        "context": 131072,
+        "output": 65536
+      },
+      "cost": {
+        "input": 1.5,
+        "output": 17.5
+      }
+    },
     "gemini-3.1-flash-image-preview": {
       "id": "gemini-3.1-flash-image-preview",
       "name": "Nano Banana 2",