llm.rb 5.2.1 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f9bdef0c733225e44dcf39d75e3397974122bfeb5e705a0797067242fd5c966
-  data.tar.gz: 567cc793e1e095e481abf5ef797a6fcb26a04faeed91855c234e531b78e3544a
+  metadata.gz: 39e1632fb63f83a65c5a146ea2a2f4178d0d99d26d2a347f36d360c09ea9845d
+  data.tar.gz: 04b2236d5cac243cc496b686d8d8a5097676e7bcd6973bacfa8d1f7e8d48e270
 SHA512:
-  metadata.gz: 3d7e026b308228787d2f6ead8de197f847b644f7ba5bd0a1d679270a66e5c0e48c74a7d9494a86613bd061a42c2fd56ff270f73f8f3a627bc213dd7d57de788d
-  data.tar.gz: 8586a02d0345e7259f80b32e688a0ad531e28e3d15c8519781647ee1f77f23b6ecdaa9b28ed40efdea138c138511c7c4f88986ed7d646fb562e9faf7e2db687f
+  metadata.gz: 1b4a68bd3b3e109a00f996f520296405ad6066b4f17c1e59da4077c2023c5fe0c95e770b9bd563a531748a16d79355f8db5fb2dcd66ac42673698ddcbea07704
+  data.tar.gz: 12713c07834164f3d13d01613126488cc19e937b8f127fcdbf839d8c75f2f6b77c6207e7e3e6f515d996e35aedb6d6e7333ba563a3f4578f4c33f454d41c6088

data/CHANGELOG.md

@@ -2,8 +2,30 @@
 
 ## Unreleased
 
+Changes since `v5.3.0`.
+
+## v5.3.0
+
 Changes since `v5.2.1`.
 
+This release deepens llm.rb's request-rewriting and tool-definition surface.
+It adds transformer lifecycle hooks to `LLM::Stream` so UIs can surface work
+like PII scrubbing before a request is sent, and it adds a more explicit
+OmniAI-style tool DSL form with `parameter` plus separate `required`
+declarations while keeping the older `param ... required: true` style working.
+
+### Change
+
+* **Add transformer stream lifecycle hooks** <br>
+  Add `on_transform` and `on_transform_finish` to
+  `LLM::Stream` so UIs can surface request rewriting work such as PII
+  scrubbing before a request is sent to the model.
+
+* **Add a separate `required` tool DSL form** <br>
+  Add `parameter` as an alias of `param` and support `required %i[...]`
+  as a separate declaration, inspired by OmniAI-style tools, while keeping
+  the existing `param ... required: true` form working too.
+
 ## v5.2.1
 
 Changes since `v5.2.0`.

data/README.md

@@ -4,7 +4,7 @@
 <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-5.2.1-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-5.3.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -26,7 +26,7 @@ execution model instead of a pile of adapters.
 
 Want to see some code? Jump to [the examples](#examples) section. <br>
 Want to see an agentic framework built on top of llm.rb? Check out [general-intelligence-systems/brute](https://github.com/general-intelligence-systems/brute). <br>
-Want a taste of what llm.rb can build? See [the screencast](#screencast).
+Want to see a self-hosted LLM environment built on llm.rb? Check out [Relay](https://github.com/llmrb/relay).
 
 ## Architecture
 
@@ -193,11 +193,22 @@ Transformers let llm.rb rewrite outgoing prompts and params before a request
 is sent to the provider. They also live on
 [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html), but
 they solve a different problem from guards: instead of blocking execution,
-they can normalize or scrub what gets sent.
+they can normalize or scrub what gets sent. When a stream is present, that
+lifecycle is also exposed through
+[`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html) with
+`on_transform` and `on_transform_finish`.
 
 That makes them a good fit for things like PII scrubbing, prompt
 normalization, or request-level param injection. A transformer just needs to
-implement `call(ctx, prompt, params)` and return `[prompt, params]`.
+implement `call(ctx, prompt, params)` and return `[prompt, params]`. That
+means a transformer can scrub plain text prompts, but it can also scrub
+[`LLM::Function::Return`](https://0x1eef.github.io/x/llm.rb/LLM/Function/Return.html)
+values. In other words, you can intercept a tool call's return value and
+modify it before sending it back to the LLM.
+
+That is also a useful UI hook. A stream can surface messages like
+`Anonymizing your data...` before a scrubber runs and `Data anonymized.`
+after it finishes.
 
 ```ruby
 class ScrubPII
@@ -212,22 +223,45 @@ class ScrubPII
   def scrub(prompt)
     case prompt
     when String then prompt.gsub(EMAIL, "[REDACTED_EMAIL]")
+    when Array then prompt.map { scrub(_1) }
+    when LLM::Function::Return then on_tool_return(prompt)
     else prompt
     end
   end
+
+  def on_tool_return(result)
+    value = case result.name
+    when "lookup-customer" then scrub_value(result.value)
+    else result.value
+    end
+    LLM::Function::Return.new(result.id, result.name, value)
+  end
+
+  def scrub_value(value)
+    case value
+    when String then value.gsub(EMAIL, "[REDACTED_EMAIL]")
+    when Array then value.map { scrub_value(_1) }
+    when Hash then value.transform_values { scrub_value(_1) }
+    else value
+    end
+  end
 end
 
 ctx = LLM::Context.new(llm)
 ctx.transformer = ScrubPII.new
 ```
 
+When a stream is present, that transformer lifecycle is also exposed through
+`on_transform` and `on_transform_finish` on
+[`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html).
+
 #### LLM::Stream
 
 `LLM::Stream` is not just for printing tokens. It supports `on_content`,
-`on_reasoning_content`, `on_tool_call`, `on_tool_return`, `on_compaction`,
-and `on_compaction_finish`, which means visible output, reasoning output, tool
-execution, and context compaction can all be driven through the same
-execution path.
+`on_reasoning_content`, `on_tool_call`, `on_tool_return`, `on_transform`,
+`on_transform_finish`, `on_compaction`, and `on_compaction_finish`, which
+means visible output, reasoning output, request rewriting, tool execution,
+and context compaction can all be driven through the same execution path.
 
 ```ruby
 class Stream < LLM::Stream
@@ -477,6 +511,29 @@ loop do
 end
 ```
 
+#### Multimodal: Local Files
+
+In llm.rb, a prompt can be a string, an [`LLM::Prompt`](https://0x1eef.github.io/x/llm.rb/LLM/Prompt.html), or an array.
+When you use an array, each element can be plain text or a tagged object such as
+[`ctx.image_url(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#image_url-instance_method),
+[`ctx.local_file(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#local_file-instance_method),
+or [`ctx.remote_file(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#remote_file-instance_method).
+Those tagged objects carry the metadata the provider adapter needs to turn one
+Ruby prompt into the provider-specific multimodal request schema.
+
+`ctx.local_file(path)` tags a local path as a `:local_file` object around
+`LLM.File(path)`. If the model understands that file type, you can include it
+directly in the prompt array instead of uploading it first through a provider
+Files API:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+ctx.talk ["Summarize this document.", ctx.local_file("README.md")]
+```
+
 #### Agent
 
 This example uses [`LLM::Agent`](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html) directly and lets the agent manage tool execution. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
@@ -738,13 +795,6 @@ mcp.run do
 end
 ```
 
-## Screencast
-
-This screencast was built on an older version of llm.rb, but it still shows
-how capable the runtime can be in a real application:
-
-[![Watch the llm.rb screencast](https://img.youtube.com/vi/Jb7LNUYlCf4/maxresdefault.jpg)](https://www.youtube.com/watch?v=x1K4wMeO_QA)
-
 ## Resources
 
 - [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) and

data/lib/llm/context.rb

@@ -489,7 +489,11 @@ module LLM
 
     def transform(prompt, params)
       return [prompt, params] unless transformer
+      stream = params[:stream]
+      stream.on_transform(self, transformer) if LLM::Stream === stream
       transformer.call(self, prompt, params)
+    ensure
+      stream.on_transform_finish(self, transformer) if LLM::Stream === stream
     end
 
     def guarded_return_for(function, warning)

data/lib/llm/function.rb

@@ -42,6 +42,33 @@ class LLM::Function
   extend LLM::Function::Registry
   prepend LLM::Function::Tracing
 
+  ##
+  # {LLM::Function::Return LLM::Function::Return} represents the result of a
+  # tool call.
+  #
+  # In llm.rb, tool execution is not complete until the requested function is
+  # answered with a return object and that return is sent back through the
+  # context. This is the object that closes that loop.
+  #
+  # The return carries:
+  # - the tool call ID
+  # - the tool name
+  # - the tool's return value
+  #
+  # That value is usually a `Hash`, but it can be any JSON-like structure your
+  # tool returns. `LLM::Function#call` produces one automatically, and
+  # `LLM::Function#cancel` produces one that represents a cancelled tool call.
+  #
+  # You can also construct one directly when you need to intercept, scrub, or
+  # synthesize a tool return before sending it back to the model.
+  #
+  # @example Returning a normal tool result
+  #   ret = LLM::Function::Return.new("call_1", "weather", {forecast: "sunny"})
+  #   ctx.talk(ret)
+  #
+  # @example Returning a tool result after rewriting its payload
+  #   value = ret.value.merge(email: "[REDACTED_EMAIL]")
+  #   ctx.talk(LLM::Function::Return.new(ret.id, ret.name, value))
   Return = Struct.new(:id, :name, :value) do
     ##
     # Returns true when the return value represents an error.

data/lib/llm/stream.rb

@@ -19,7 +19,7 @@ module LLM
   # The most common callback is {#on_content}, which also maps to {#<<}.
   # Providers may also call {#on_reasoning_content} and {#on_tool_call} when
   # that data is available. Runtime features such as context compaction may
-  # also emit lifecycle callbacks like {#on_compaction}.
+  # also emit lifecycle callbacks like {#on_transform} or {#on_compaction}.
   class Stream
     require_relative "stream/queue"
 
@@ -112,6 +112,24 @@ module LLM
       nil
     end
 
+    ##
+    # Called before a context transformer rewrites a prompt.
+    # @param [LLM::Context] ctx
+    # @param [#call] transformer
+    # @return [nil]
+    def on_transform(ctx, transformer)
+      nil
+    end
+
+    ##
+    # Called after a context transformer finishes rewriting a prompt.
+    # @param [LLM::Context] ctx
+    # @param [#call] transformer
+    # @return [nil]
+    def on_transform_finish(ctx, transformer)
+      nil
+    end
+
     ##
     # Called before a context compaction starts.
     # @param [LLM::Context] ctx

data/lib/llm/tool/param.rb

@@ -11,7 +11,8 @@ class LLM::Tool
   #   class Greeter < LLM::Tool
   #     name "greeter"
   #     description "Greets the user"
-  #     param :name, String, "The user's name", required: true
+  #     parameter :name, String, "The user's name"
+  #     required %i[name]
   #
   #     def call(name:)
   #       puts "Hello, #{name}!"
@@ -41,6 +42,19 @@ class LLM::Tool
         end
       end
     end
+    alias_method :parameter, :param
+
+    ##
+    # Mark existing parameters as required.
+    # @param names [Array<Symbol,String>]
+    # @return [LLM::Schema::Object]
+    def required(names)
+      lock do
+        function.params.tap do |schema|
+          [*names].each { Utils.fetch(schema.properties, _1).required }
+        end
+      end
+    end
 
     ##
     # @api private
@@ -68,6 +82,10 @@ class LLM::Tool
         leaf.enum(*enum) if enum
         leaf
       end
+
+      def fetch(properties, name)
+        properties[name] || properties.fetch(name.to_s)
+      end
     end
   end
 end

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "5.2.1"
+  VERSION = "5.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 5.2.1
+  version: 5.3.0
 platform: ruby
 authors:
 - Antar Azri