llm.rb 4.19.0 → 4.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18c28f7b5ec05ad6f9629a6a328be4dd377a6efb43a13c2ac99dd0abf015b1f8
-  data.tar.gz: a0c03de362af927d090a6bc09b2170ddb7eb5766f26b1f8f657a37bd10d0162e
+  metadata.gz: d57e4d2af8568cdd6328c0a956fddb40aecbd2943a268b595dbd87ee811553a4
+  data.tar.gz: 8cf576171c3bfd7328b8316d42aecbb364a7e4d0a6bbff707cdc65cc9ddfbd01
 SHA512:
-  metadata.gz: c8255c9435bec0a7a06fb427f3a1ade4e0b5ce47f111d33f4cbf1218fce1f89f1438c71980b52c3de7542563690f08bcf54417cb7d427720248a22f8b30a12fb
-  data.tar.gz: 54aebea9a5f8ac687163d3df3c2c3d31091f8f8d6d96b5ad242199daa8fdfb8e5e17e2b626f7a682158ba9251202362fc9fddaed6c08e6eb8399c8b0509659d8
+  metadata.gz: 4d9087909b30c47e5ddb9c9407b53efdbbd2a3732629579dfd53415d60e1457a56b738b9942b578434888b97ee597d78955f21a1af5235847e6daa944810e8d7
+  data.tar.gz: a890e08d0129ccfa18188efb503e8ac32e4d5424a79851bf2bfa15424b713cae4431afeb78fe7645437d8b3d0c11cc2d975d7415279a2880ca5cd557de57cf5f

data/CHANGELOG.md

@@ -2,8 +2,28 @@
 
 ## 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`.

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.19.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

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "4.19.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.19.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