llm.rb 4.2.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 567ae33357581ae1602a337ee53dbc86328b4b6c3ee5af5f0b86cf810c039e64
-  data.tar.gz: 4a3d332aad0a2f824966a850c6be36e48894a871d1831f70527e46df5614b207
+  metadata.gz: f35a8e2b21d2bf7914c9b261897eaa6d9c6d0ff03dc51c0e751f86d22e08f093
+  data.tar.gz: 92ffab3eab12fd6393ef8e324360d13e9725403a9571cf6c28427be090021965
 SHA512:
-  metadata.gz: 6c04ea5dcf20e9757b0bac1d0eb4cc27176fe966f4ad6fd0f5f06b708d8653522be25b454c9e831f2a5d30fa7676f04d289692fb94ae3bd06f98ab0576ccf7f3
-  data.tar.gz: 2f0d46d75e75382a601863fc0c10e4218efb3029c0650d021586007895d6647fd006eeffd7c6e7027204fcb75168be0e4f51b974d08df95397f1a233baa4239b
+  metadata.gz: 02cdeb6b969b4ec2d76ffce29236fb8c189cdf3a71ea121e2b218ffb8fdadff0005cfd4211bcdac6e17b9814f9533949f0bdec19efdd8fb2262096d5bd440dde
+  data.tar.gz: 3cf0abeefd9927df9e600a694387e0f7d334f9c614b6e64cd54cf3e5f82b6a73895d74c392a5a6f68a92c529155cfb3db067bf8b2ef85e0df4505105c759870c

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.2.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.3.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -39,7 +39,7 @@ llm = LLM.openai(key: ENV["KEY"])
 ses = LLM::Session.new(llm, stream: $stdout)
 loop do
   print "> "
-  ses.talk(STDIN.gets)
+  ses.talk(STDIN.gets || break)
   puts
 end
 ```
@@ -193,6 +193,7 @@ ses.talk(prompt)
 
 #### Chat, Agents
 - 🧠  Stateless + stateful chat (completions + responses)
+- 💾  Save and restore sessions across processes
 - 🤖  Tool calling / function execution
 - 🔁  Agent tool-call auto-execution (bounded)
 - 🗂️  JSON Schema structured output
@@ -383,6 +384,60 @@ ses.talk "Hello world!"
 ses.talk "Adios."
 ```
 
+#### Serialization
+
+[LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html) can be
+serialized and deserialized across process boundaries and persisted to
+storage such as files, a `jsonb` column (PostgreSQL), or other backends
+through a JSON representation of the history encapsulated by
+[LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html)
+&ndash; inclusive of tool metadata as well:
+
+* Process 1
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+ses = LLM::Session.new(llm)
+ses.talk "Howdy partner"
+ses.talk "I'll see you later"
+ses.save(path: "session.json")
+```
+* Process 2
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+require "pp"
+
+llm = LLM.openai(key: ENV["KEY"])
+ses = LLM::Session.new(llm)
+ses.restore(path: "session.json")
+ses.talk "Howdy partner. I'm back"
+pp ses.messages
+```
+
+But how does it work without a file ? The [LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html)
+class implements `#to_json` and it can be used to obtain a JSON representation
+of a session that can be stored in a `jsonb` column in PostgreSQL, or any
+other storage backend. The session can then be restored from the JSON
+representation via the restore method and its `string` argument:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+ses1 = LLM::Session.new(llm)
+ses1.talk "Howdy partner"
+ses1.talk "I'll see you later"
+
+json = ses1.to_json
+ses2 = LLM::Session.new(llm)
+ses2.restore(string: json)
+ses2.talk "Howdy partner. I'm back"
+```
+
 #### Thread Safety
 
 The llm.rb library is thread-safe and can be used in a multi-threaded
@@ -719,6 +774,12 @@ llm.rb can be installed via rubygems.org:
 
 	gem install llm.rb
 
+## Sources
+
+* [GitHub.com](https://github.com/llmrb/llm.rb)
+* [GitLab.com](https://gitlab.com/llmrb/llm.rb)
+* [Codeberg.org](https://codeberg.org/llmrb/llm.rb)
+
 ## License
 
 [BSD Zero Clause](https://choosealicense.com/licenses/0bsd/)

data/lib/llm/agent.rb

@@ -204,6 +204,22 @@ module LLM
       @ses.model
     end
 
+    ##
+    # @param (see LLM::Session#serialize)
+    # @return (see LLM::Session#serialize)
+    def serialize(**kw)
+      @ses.serialize(**kw)
+    end
+    alias_method :save, :serialize
+
+    ##
+    # @param (see LLM::Session#deserialize)
+    # @return (see LLM::Session#deserialize)
+    def deserialize(**kw)
+      @ses.deserialize(**kw)
+    end
+    alias_method :restore, :deserialize
+
     private
 
     def apply_instructions(prompt)

data/lib/llm/bot.rb

@@ -23,6 +23,9 @@ module LLM
   #   ses.talk(prompt)
   #   ses.messages.each { |m| puts "[#{m.role}] #{m.content}" }
   class Session
+    require_relative "session/deserializer"
+    include Deserializer
+
     ##
     # Returns an Enumerable for the messages in a conversation
     # @return [LLM::Buffer<LLM::Message>]
@@ -60,7 +63,9 @@ module LLM
       params = params.merge(messages: [*@messages.to_a, *messages])
       params = @params.merge(params)
       res = @provider.complete(prompt, params)
-      @messages.concat [LLM::Message.new(params[:role] || :user, prompt)]
+      role = params[:role] || @provider.user_role
+      role = @provider.tool_role if params[:role].nil? && [*prompt].grep(LLM::Function::Return).any?
+      @messages.concat [LLM::Message.new(role, prompt)]
       @messages.concat messages
       @messages.concat [res.choices[-1]]
       res
@@ -86,7 +91,8 @@ module LLM
       params = params.merge(previous_response_id: res_id, input: messages).compact
       params = @params.merge(params)
       res = @provider.responses.create(prompt, params)
-      @messages.concat [LLM::Message.new(params[:role] || :user, prompt)]
+      role = params[:role] || @provider.user_role
+      @messages.concat [LLM::Message.new(role, prompt)]
       @messages.concat messages
       @messages.concat [res.choices[-1]]
       res
@@ -190,6 +196,56 @@ module LLM
       messages.find(&:assistant?)&.model || @params[:model]
     end
 
+    ##
+    # @return [Hash]
+    def to_h
+      {model:, messages:}
+    end
+
+    ##
+    # @return [String]
+    def to_json(...)
+      {schema_version: 1}.merge!(to_h).to_json(...)
+    end
+
+    ##
+    # Save a session
+    # @example
+    #  llm = LLM.openai(key: ENV["KEY"])
+    #  ses = LLM::Session.new(llm)
+    #  ses.talk "Hello"
+    #  ses.save(path: "session.json")
+    # @raise [SystemCallError]
+    #  Might raise a number of SystemCallError subclasses
+    # @return [void]
+    def serialize(path:)
+      ::File.binwrite path, LLM.json.dump(self)
+    end
+    alias_method :save, :serialize
+
+    ##
+    # Restore a session
+    # @param [String, nil] path
+    #  The path to a JSON file
+    # @param [String, nil] string
+    #  A raw JSON string
+    # @raise [SystemCallError]
+    #  Might raise a number of SystemCallError subclasses
+    # @return [LLM::Session]
+    def deserialize(path: nil, string: nil)
+      payload = if path.nil? and string.nil?
+        raise ArgumentError, "a path or string is required"
+      elsif path
+        ::File.binread(path)
+      else
+        string
+      end
+      ses = LLM.json.load(payload)
+      @messages.concat [*ses["messages"]].map { deserialize_message(_1) }
+      self
+    end
+    alias_method :restore, :deserialize
+
     private
 
     def fetch(prompt, params)
@@ -203,4 +259,7 @@ module LLM
 
   # Backward-compatible alias
   Bot = Session
+
+  # Scheduled for removal in v5.0
+  deprecate_constant :Bot
 end

data/lib/llm/buffer.rb

@@ -70,6 +70,12 @@ module LLM
       @messages[index]
     end
 
+    ##
+    # @return [String]
+    def to_json(...)
+      LLM.json.dump(@messages, ...)
+    end
+
     ##
     # @return [String]
     def inspect

data/lib/llm/function.rb

@@ -33,6 +33,18 @@ class LLM::Function
   prepend LLM::Function::Tracing
 
   class Return < Struct.new(:id, :name, :value)
+    ##
+    # Returns a Hash representation of {LLM::Function::Return}
+    # @return [Hash]
+    def to_h
+      {id:, name:, value:}
+    end
+
+    ##
+    # @return [String]
+    def to_json(...)
+      LLM.json.dump(to_h, ...)
+    end
   end
 
   ##

data/lib/llm/json_adapter.rb

@@ -35,16 +35,16 @@ module LLM
   class JSONAdapter::JSON < JSONAdapter
     ##
     # @return (see JSONAdapter#dump)
-    def self.dump(obj)
+    def self.dump(obj, ...)
       require "json" unless defined?(::JSON)
-      ::JSON.dump(obj)
+      ::JSON.dump(obj, ...)
     end
 
     ##
     # @return (see JSONAdapter#load)
-    def self.load(string)
+    def self.load(string, ...)
       require "json" unless defined?(::JSON)
-      ::JSON.parse(string)
+      ::JSON.parse(string, ...)
     end
 
     ##
@@ -61,16 +61,16 @@ module LLM
   class JSONAdapter::Oj < JSONAdapter
     ##
     # @return (see JSONAdapter#dump)
-    def self.dump(obj)
+    def self.dump(obj, options = {})
       require "oj" unless defined?(::Oj)
-      ::Oj.dump(obj, mode: :compat)
+      ::Oj.dump(obj, options.merge(mode: :compat))
     end
 
     ##
     # @return (see JSONAdapter#load)
-    def self.load(string)
+    def self.load(string, options = {})
       require "oj" unless defined?(::Oj)
-      ::Oj.load(string, mode: :compat, symbol_keys: false, symbolize_names: false)
+      ::Oj.load(string, options.merge(mode: :compat, symbol_keys: false, symbolize_names: false))
     end
 
     ##
@@ -87,16 +87,16 @@ module LLM
   class JSONAdapter::Yajl < JSONAdapter
     ##
     # @return (see JSONAdapter#dump)
-    def self.dump(obj)
+    def self.dump(obj, ...)
       require "yajl" unless defined?(::Yajl)
-      ::Yajl::Encoder.encode(obj)
+      ::Yajl::Encoder.encode(obj, ...)
     end
 
     ##
     # @return (see JSONAdapter#load)
-    def self.load(string)
+    def self.load(string, ...)
       require "yajl" unless defined?(::Yajl)
-      ::Yajl::Parser.parse(string)
+      ::Yajl::Parser.parse(string, ...)
     end
 
     ##

data/lib/llm/message.rb

@@ -30,10 +30,18 @@ module LLM
     end
 
     ##
-    # Returns a hash representation of the message
+    # Returns a Hash representation of the message.
     # @return [Hash]
     def to_h
-      {role:, content:}
+      {role:, content:,
+       tools: @extra[:tool_calls],
+       original_tool_calls: extra[:original_tool_calls]}.compact
+    end
+
+    ##
+    # @return [String]
+    def to_json(...)
+      LLM.json.dump(to_h, ...)
     end
 
     ##
@@ -62,7 +70,7 @@ module LLM
     # @return [Array<LLM::Function>]
     def functions
       @functions ||= tool_calls.map do |fn|
-        function = tools.find { _1.name.to_s == fn["name"] }.dup
+        function = available_tools.find { _1.name.to_s == fn["name"] }.dup
         function.tap { _1.id = fn.id }
         function.tap { _1.arguments = fn.arguments }
       end
@@ -158,7 +166,7 @@ module LLM
       @tool_calls ||= LLM::Object.from(@extra[:tool_calls] || [])
     end
 
-    def tools
+    def available_tools
       response&.__tools__ || []
     end
   end

data/lib/llm/provider.rb

@@ -253,6 +253,12 @@ class LLM::Provider
     :developer
   end
 
+  ##
+  # @return [Symbol]
+  def tool_role
+    :tool
+  end
+
   ##
   # @return [LLM::Tracer]
   #  Returns an LLM tracer

data/lib/llm/providers/gemini/files.rb

@@ -131,7 +131,7 @@ class LLM::Gemini
       req["X-Goog-Upload-Command"] = "start"
       req["X-Goog-Upload-Header-Content-Length"] = file.bytesize
       req["X-Goog-Upload-Header-Content-Type"] = file.mime_type
-      req.body = LLM.json.dump(file: {display_name: File.basename(file.path)})
+      req.body = LLM.json.dump({file: {display_name: File.basename(file.path)}})
       res, span = execute(request: req, operation: "request")
       finish_trace(operation: "request", res: LLM::Response.new(res), span:)
       res["x-goog-upload-url"]

data/lib/llm/schema/object.rb

@@ -52,8 +52,8 @@ class LLM::Schema
 
     ##
     # @return [String]
-    def to_json(options = {})
-      to_h.to_json(options)
+    def to_json(...)
+      LLM.json.dump(to_h, ...)
     end
 
     ##

data/lib/llm/session/deserializer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class LLM::Session
+  ##
+  # @api private
+  module Deserializer
+    ##
+    # @param [Hash] payload
+    # @return [LLM::Message]
+    def deserialize_message(payload)
+      tool_calls = deserialize_tool_calls(payload["tools"])
+      returns = deserialize_returns(payload["content"]) if returns.nil?
+      original_tool_calls = payload["original_tool_calls"]
+      extra = {tool_calls:, original_tool_calls:}.compact
+      content = returns.nil? ? payload["content"] : returns
+      LLM::Message.new(payload["role"], content, extra)
+    end
+
+    private
+
+    def deserialize_tool_calls(items)
+      items ||= []
+      items.empty? ? nil : items
+    end
+
+    def deserialize_returns(items)
+      returns = [*items].filter_map do |item|
+        next unless Hash === item
+        id, name, value = item.values_at("id", "name", "value")
+        next if id.nil? || name.nil? || value.nil?
+        LLM::Function::Return.new(id, name, value)
+      end
+      returns.empty? ? nil : returns
+    end
+  end
+end

data/lib/llm/version.rb

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

data/llm.gemspec

@@ -16,11 +16,11 @@ Gem::Specification.new do |spec|
   SUMMARY
 
   spec.description = spec.summary
-  spec.homepage = "https://github.com/llmrb/llm"
   spec.license = "0BSD"
   spec.required_ruby_version = ">= 3.2.0"
 
-  spec.metadata["homepage_uri"] = spec.homepage
+  spec.homepage = "https://github.com/llmrb/llm.rb"
+  spec.metadata["homepage_uri"] = "https://github.com/llmrb/llm.rb"
   spec.metadata["source_code_uri"] = "https://github.com/llmrb/llm.rb"
   spec.metadata["documentation_uri"] = "https://0x1eef.github.io/x/llm.rb"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 4.3.0
 platform: ruby
 authors:
 - Antar Azri
@@ -313,6 +313,7 @@ files:
 - lib/llm/schema/version.rb
 - lib/llm/server_tool.rb
 - lib/llm/session.rb
+- lib/llm/session/deserializer.rb
 - lib/llm/tool.rb
 - lib/llm/tool/param.rb
 - lib/llm/tracer.rb
@@ -323,11 +324,11 @@ files:
 - lib/llm/utils.rb
 - lib/llm/version.rb
 - llm.gemspec
-homepage: https://github.com/llmrb/llm
+homepage: https://github.com/llmrb/llm.rb
 licenses:
 - 0BSD
 metadata:
-  homepage_uri: https://github.com/llmrb/llm
+  homepage_uri: https://github.com/llmrb/llm.rb
   source_code_uri: https://github.com/llmrb/llm.rb
   documentation_uri: https://0x1eef.github.io/x/llm.rb
 rdoc_options: []