llm.rb 4.18.0 → 4.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42357f605b8995c24722c0a2d285d98de0e99fe6f9687e2f4451339dcfbc2e87
-  data.tar.gz: 2953c742deeec6dc7c7acc9ed77f4520846a92299a4df94e415416d5c623033c
+  metadata.gz: d57e4d2af8568cdd6328c0a956fddb40aecbd2943a268b595dbd87ee811553a4
+  data.tar.gz: 8cf576171c3bfd7328b8316d42aecbb364a7e4d0a6bbff707cdc65cc9ddfbd01
 SHA512:
-  metadata.gz: 534fad616562768b0a851142f411117634d824a92187577d6baad4427c1e0eddf7a765dbfe3b662f76ba52011d760803793473a1881b4f69b8f4c7f9fc16bdc3
-  data.tar.gz: f1d90ad7f7b71f4817fcfa494f48a4e7f189560674d7b86d618f1f4e217e2a34189e15156e71ecdcfffe81e9588315f4759a82f4ec3eaed3846a29c77a906a66
+  metadata.gz: 4d9087909b30c47e5ddb9c9407b53efdbbd2a3732629579dfd53415d60e1457a56b738b9942b578434888b97ee597d78955f21a1af5235847e6daa944810e8d7
+  data.tar.gz: a890e08d0129ccfa18188efb503e8ac32e4d5424a79851bf2bfa15424b713cae4431afeb78fe7645437d8b3d0c11cc2d975d7415279a2880ca5cd557de57cf5f

data/CHANGELOG.md

@@ -2,8 +2,59 @@
 
 ## Unreleased
 
+Changes since `v4.20.0`.
+
+## v4.20.0
+
+Changes since `v4.19.0`.
+
+This release adds better support for tagged prompt content. `LLM::Context`
+can now serialize and restore `image_url`, `local_file`, and `remote_file`
+content cleanly, and `LLM::Message` now exposes helpers for inspecting
+tagged image and file attachments.
+
+### Change
+
+* **Round-trip tagged prompt objects through `LLM::Context`** <br>
+  Teach `LLM::Context` serialization and restore to preserve
+  `image_url`, `local_file`, and `remote_file` content across
+  `to_json` / `restore`.
+
+* **Add attachment helpers to `LLM::Message`** <br>
+  Add `image_url?`, `image_urls`, `file?`, and `files` so callers can
+  inspect messages for tagged image and file content more directly.
+
+## v4.19.0
+
 Changes since `v4.18.0`.
 
+This release tightens the ActiveRecord and ORM integration layer. It adds
+inline agent DSL blocks to `acts_as_agent` so agent defaults can be defined
+where the wrapper is declared, and it exposes the resolved provider through
+public `llm` methods on the ActiveRecord and Sequel wrappers.
+
+### Change
+
+* **Make ORM provider access public through `llm`** <br>
+  Expose the resolved provider on the Sequel plugin and the ActiveRecord
+  `acts_as_llm` / `acts_as_agent` wrappers through a public `llm` method.
+
+* **Allow inline agent DSL blocks in `acts_as_agent`** <br>
+  Let ActiveRecord models configure `model`, `tools`, `schema`,
+  `instructions`, and `concurrency` directly inside the `acts_as_agent`
+  declaration block.
+
+## v4.18.0
+
+Changes since `v4.17.0`.
+
+This release improves tracing and tool execution behavior across llm.rb.
+It makes provider tracers default to the provider instance, adds
+`LLM::Provider#with_tracer` for scoped overrides, restores tool tracing for
+concurrent and streamed tool execution, extends streamed tracing to MCP tools,
+and adds symbol-based ORM option hooks alongside experimental ractor tool
+concurrency.
+
 ### Change
 
 * **Make provider tracers default to the provider instance** <br>
@@ -42,17 +93,6 @@ Changes since `v4.18.0`.
   is especially useful for CPU-bound tools, while `:task`, `:fiber`, or
   `:thread` may be a better fit for I/O-bound work.
 
-## v4.18.0
-
-Changes since `v4.17.0`.
-
-This release improves tracing and tool execution behavior across llm.rb.
-It makes provider tracers default to the provider instance, adds
-`LLM::Provider#with_tracer` for scoped overrides, restores tool tracing for
-concurrent and streamed tool execution, extends streamed tracing to MCP tools,
-and adds symbol-based ORM option hooks alongside experimental ractor tool
-concurrency.
-
 ## v4.17.0
 
 Changes since `v4.16.1`.

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-4.18.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.20.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -254,11 +254,18 @@ require "active_record"
 require "llm/active_record"
 
 class Ticket < ApplicationRecord
-  acts_as_agent provider: -> { { key: ENV["#{provider.upcase}_SECRET"], persistent: true } }
-  model "gpt-5.4-mini"
-  instructions "You are a concise support assistant."
-  tools SearchDocs, Escalate
-  concurrency :thread
+  acts_as_agent provider: :set_provider do
+    model "gpt-5.4-mini"
+    instructions "You are a concise support assistant."
+    tools SearchDocs, Escalate
+    concurrency :thread
+  end
+
+  private
+
+  def set_provider
+    { key: ENV["#{provider.upcase}_SECRET"], persistent: true }
+  end
 end
 
 ticket = Ticket.create!(provider: "openai", model: "gpt-5.4-mini")

data/lib/llm/active_record/acts_as_agent.rb

@@ -71,18 +71,21 @@ module LLM::ActiveRecord
     # @option options [Proc, Symbol, LLM::Tracer, nil] :tracer
     #   Optional tracer, method name, or proc that resolves to one and is
     #   assigned through `llm.tracer = ...` on the resolved provider.
+    # @yield
+    #   Evaluated in the model class after the wrapper is installed, so agent
+    #   DSL methods such as `model`, `tools`, `schema`, `instructions`, and
+    #   `concurrency` can be configured inline.
     # @return [void]
-    def acts_as_agent(options = EMPTY_HASH)
+    def acts_as_agent(options = EMPTY_HASH, &block)
       options = DEFAULTS.merge(options)
       usage_columns = DEFAULT_USAGE_COLUMNS.merge(options[:usage_columns] || EMPTY_HASH)
       class_attribute :llm_agent_options, instance_accessor: false, default: DEFAULTS unless respond_to?(:llm_agent_options)
       self.llm_agent_options = options.merge(usage_columns: usage_columns.freeze).freeze
       extend Hooks
+      class_exec(&block) if block
     end
 
     module InstanceMethods
-      private
-
       ##
       # Returns the resolved provider instance for this record.
       # @return [LLM::Provider]
@@ -96,6 +99,8 @@ module LLM::ActiveRecord
         @llm
       end
 
+      private
+
       ##
       # @return [LLM::Agent]
       def ctx

data/lib/llm/active_record/acts_as_llm.rb

@@ -206,8 +206,6 @@ module LLM::ActiveRecord
         ctx.tracer
       end
 
-      private
-
       ##
       # Returns the resolved provider instance for this record.
       # @return [LLM::Provider]
@@ -221,6 +219,8 @@ module LLM::ActiveRecord
         @llm
       end
 
+      private
+
       ##
       # @return [LLM::Context]
       def ctx

data/lib/llm/context/deserializer.rb

@@ -4,6 +4,32 @@ class LLM::Context
   ##
   # @api private
   module Deserializer
+    ##
+    # Restore a saved context state
+    # @param [String, nil] path
+    #  The path to a JSON file
+    # @param [String, nil] string
+    #  A raw JSON string
+    # @param [Hash, nil] data
+    #  A parsed context payload
+    # @raise [SystemCallError]
+    #  Might raise a number of SystemCallError subclasses
+    # @return [LLM::Context]
+    def deserialize(path: nil, string: nil, data: nil)
+      ctx = if data
+        data
+      elsif path.nil? and string.nil?
+        raise ArgumentError, "a path, string, or data payload is required"
+      elsif path
+        LLM.json.load(::File.binread(path))
+      else
+        LLM.json.load(string)
+      end
+      @messages.concat [*ctx["messages"]].map { deserialize_message(_1) }
+      self
+    end
+    alias_method :restore, :deserialize
+
     ##
     # @param [Hash] payload
     # @return [LLM::Message]
@@ -14,12 +40,36 @@ class LLM::Context
       usage = payload["usage"]
       reasoning_content = payload["reasoning_content"]
       extra = {tool_calls:, original_tool_calls:, tools: @params[:tools], usage:, reasoning_content:}.compact
-      content = returns.nil? ? payload["content"] : returns
+      content = returns.nil? ? deserialize_content(payload["content"]) : returns
       LLM::Message.new(payload["role"], content, extra)
     end
 
     private
 
+    def deserialize_content(content)
+      case content
+      when Array
+        content.map { deserialize_content(_1) }
+      when Hash
+        deserialize_object(content)
+      else
+        content
+      end
+    end
+
+    def deserialize_object(object)
+      case object["__llm_kind__"]
+      when "image_url"
+        LLM::Object.from(value: object["value"], kind: :image_url)
+      when "local_file"
+        LLM::Object.from(value: LLM.File(object["path"]), kind: :local_file)
+      when "remote_file"
+        LLM::Object.from(value: LLM::Object.from(object["value"] || {}), kind: :remote_file)
+      else
+        object
+      end
+    end
+
     def deserialize_tool_calls(items)
       items ||= []
       items.empty? ? nil : items

data/lib/llm/context/serializer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class LLM::Context
+  ##
+  # @api private
+  module Serializer
+    private
+
+    def serialize_message(message)
+      h = message.to_h
+      h[:content] = serialize_content(h[:content])
+      h
+    end
+
+    def serialize_content(content)
+      case content
+      when Array
+        content.map { serialize_content(_1) }
+      when LLM::Object
+        serialize_object(content)
+      else
+        content
+      end
+    end
+
+    def serialize_object(object)
+      case object.kind
+      when :image_url
+        {__llm_kind__: "image_url", value: object.value}
+      when :local_file
+        {__llm_kind__: "local_file", path: object.value.path}
+      when :remote_file
+        {__llm_kind__: "remote_file", value: serialize_remote_file(object.value)}
+      else
+        object.to_h
+      end
+    end
+
+    def serialize_remote_file(file)
+      {
+        "file?" => file.respond_to?(:file?) ? file.file? : true,
+        "id" => (file.id if file.respond_to?(:id)),
+        "filename" => (file.filename if file.respond_to?(:filename)),
+        "mime_type" => (file.mime_type if file.respond_to?(:mime_type)),
+        "uri" => (file.uri if file.respond_to?(:uri)),
+        "file_type" => (file.file_type if file.respond_to?(:file_type)),
+        "name" => (file.name if file.respond_to?(:name)),
+        "display_name" => (file.display_name if file.respond_to?(:display_name))
+      }.compact
+    end
+  end
+end

data/lib/llm/context.rb

@@ -34,7 +34,9 @@ module LLM
   #   ctx.talk(prompt)
   #   ctx.messages.each { |m| puts "[#{m.role}] #{m.content}" }
   class Context
+    require_relative "context/serializer"
     require_relative "context/deserializer"
+    include Serializer
     include Deserializer
 
     ##
@@ -279,7 +281,7 @@ module LLM
     ##
     # @return [Hash]
     def to_h
-      {schema_version: 1, model:, messages:}
+      {schema_version: 1, model:, messages: @messages.map { serialize_message(_1) }}
     end
 
     ##
@@ -299,36 +301,10 @@ module LLM
     #  Might raise a number of SystemCallError subclasses
     # @return [void]
     def serialize(path:)
-      ::File.binwrite path, LLM.json.dump(self)
+      ::File.binwrite path, LLM.json.dump(to_h)
     end
     alias_method :save, :serialize
 
-    ##
-    # Restore a saved context state
-    # @param [String, nil] path
-    #  The path to a JSON file
-    # @param [String, nil] string
-    #  A raw JSON string
-    # @param [Hash, nil] data
-    #  A parsed context payload
-    # @raise [SystemCallError]
-    #  Might raise a number of SystemCallError subclasses
-    # @return [LLM::Context]
-    def deserialize(path: nil, string: nil, data: nil)
-      ctx = if data
-        data
-      elsif path.nil? and string.nil?
-        raise ArgumentError, "a path, string, or data payload is required"
-      elsif path
-        LLM.json.load(::File.binread(path))
-      else
-        LLM.json.load(string)
-      end
-      @messages.concat [*ctx["messages"]].map { deserialize_message(_1) }
-      self
-    end
-    alias_method :restore, :deserialize
-
     ##
     # @return [LLM::Cost]
     #  Returns an _approximate_ cost for a given context

data/lib/llm/message.rb

@@ -74,6 +74,36 @@ module LLM
       extra.reasoning_content
     end
 
+    ##
+    # Returns true when a message contains an image URL
+    # @return [Boolean]
+    def image_url?
+      image_urls.any?
+    end
+
+    ##
+    # Returns image URL content items from the message
+    # @return [Array<LLM::Object>]
+    def image_urls
+      content_items.select { LLM::Object === _1 && _1.kind == :image_url }
+    end
+
+    ##
+    # Returns true when a message contains a local or remote file
+    # @return [Boolean]
+    def file?
+      files.any?
+    end
+
+    ##
+    # Returns local and remote file content items from the message
+    # @return [Array<LLM::Object>]
+    def files
+      content_items.select do
+        LLM::Object === _1 && [:local_file, :remote_file].include?(_1.kind)
+      end
+    end
+
     ##
     # @return [Array<LLM::Function>]
     def functions
@@ -178,5 +208,9 @@ module LLM
       tools = extra.tools || response&.__tools__ || []
       tools.map { _1.respond_to?(:function) ? _1.function : _1 }
     end
+
+    def content_items
+      Array(content)
+    end
   end
 end

data/lib/llm/sequel/plugin.rb

@@ -224,8 +224,6 @@ module LLM::Sequel
       ctx.tracer
     end
 
-    private
-
     ##
     # Returns the resolved provider instance for this record.
     # @return [LLM::Provider]
@@ -239,6 +237,8 @@ module LLM::Sequel
       @llm
     end
 
+    private
+
     ##
     # @return [LLM::Context]
     def ctx

data/lib/llm/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.18.0
+  version: 4.20.0
 platform: ruby
 authors:
 - Antar Azri
@@ -231,6 +231,7 @@ files:
 - lib/llm/buffer.rb
 - lib/llm/context.rb
 - lib/llm/context/deserializer.rb
+- lib/llm/context/serializer.rb
 - lib/llm/contract.rb
 - lib/llm/contract/completion.rb
 - lib/llm/cost.rb