llm.rb 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7f9330df025e16999629b094202d78b504de9bedeafc45ec8d75bf729024567
-  data.tar.gz: e3a22daa5ac7add9b815346fe810ed368b9f3e3a3bb135cb4e5bbbb3875eacae
+  metadata.gz: 732a483717a5ec8e443077fb71294b1e301c3a8867b225c1fc2a58bd02fe3130
+  data.tar.gz: a1c2591a07c413cebfdffa99d133855bb177cc4a6607860333dbc9991da8d33e
 SHA512:
-  metadata.gz: b985c6f0b967354f3d1e5941ebeb2e5d6623b9d0abc33fd238f3764e72a6a6e10c293e7e61221d1be8ad89e631ecc7236bca597e809f1598ad54f0b305bb1103
-  data.tar.gz: 721f373b9eada6417b864e723504e5168df8f4362bef9edb4026aad2b39a3f99de5c72081f40ab80828d2f53d24c62c55e035ccd4964e3dadca2a27f3784e6e6
+  metadata.gz: 4f5983f97b3c1e25f4147ec81f6d91df5073ea03dc4031690979f68b2053bf73bae07f7c57c3f7c9813dfd5b43eb1bd7364d5f5929234013d6b19bb49f9271ec
+  data.tar.gz: 286f560ce2d9e048e481796d27fd6c9a658b92cec0267f9527fad49bf5349ece0d05b943c086cce3c12bbd82f53dbf086ed91c516d39b815bd6106edca21914a

data/README.md

@@ -31,8 +31,8 @@ llm = LLM.ollama(nil)
 
 The
 [LLM::Provider#chat](https://0x1eef.github.io/x/llm/LLM/Provider.html#chat-instance_method)
-method returns a
-[LLM::LazyConversation](https://0x1eef.github.io/x/llm/LLM/LazyConversation.html)
+method returns a lazy-variant of a
+[LLM::Conversation](https://0x1eef.github.io/x/llm/LLM/Conversation.html)
 object, and it allows for a "lazy" conversation where messages are batched and
 sent to the provider only when necessary. The non-lazy counterpart is available via the
 [LLM::Provider#chat!](https://0x1eef.github.io/x/llm/LLM/Provider.html#chat!-instance_method)

data/lib/llm/conversation.rb

@@ -3,14 +3,14 @@
 module LLM
   ##
   # {LLM::Conversation LLM::Conversation} provides a conversation
-  # object that maintains a thread of messages that act as the
-  # context of the conversation.
-  #
+  # object that maintains a thread of messages that acts as context
+  # throughout the conversation.
   # @example
-  #   llm = LLM.openai(key)
-  #   bot = llm.chat("What is the capital of France?")
-  #   bot.chat("What should we eat in Paris?")
-  #   bot.chat("What is the weather like in Paris?")
+  #   llm = LLM.openai(ENV["KEY"])
+  #   convo = llm.chat("You are my climate expert", :system)
+  #   convo.chat("What's the climate like in Rio de Janerio?", :user)
+  #   convo.chat("What's the climate like in Algiers?", :user)
+  #   convo.chat("What's the climate like in Tokyo?", :user)
   #   p bot.messages.map { [_1.role, _1.content] }
   class Conversation
     ##
@@ -20,9 +20,12 @@ module LLM
     ##
     # @param [LLM::Provider] provider
     #  A provider
+    # @param [Hash] params
+    #  The parameters to maintain throughout the conversation
     def initialize(provider, params = {})
       @provider = provider
       @params = params
+      @lazy = false
       @messages = []
     end
 
@@ -31,12 +34,20 @@ module LLM
     # @return [LLM::Conversation]
     def chat(prompt, role = :user, **params)
       tap do
-        completion = @provider.complete(prompt, role, **@params.merge(params.merge(messages:)))
-        @messages.concat [Message.new(role, prompt), completion.choices[0]]
+        if lazy?
+          @messages << [LLM::Message.new(role, prompt), @params.merge(params)]
+        else
+          completion = complete(prompt, role, params)
+          @messages.concat [Message.new(role, prompt), completion.choices[0]]
+        end
       end
     end
 
     ##
+    # @note
+    #  The `read_response` and `recent_message` methods are aliases of
+    #  the `last_message` method, and you can choose the name that best
+    #  fits your context or code style.
     # @param [#to_s] role
     #  The role of the last message.
     #  Defaults to the LLM's assistant role (eg "assistant" or "model")
@@ -46,5 +57,34 @@ module LLM
       messages.reverse_each.find { _1.role == role.to_s }
     end
     alias_method :recent_message, :last_message
+    alias_method :read_response, :last_message
+
+    ##
+    # Enables lazy mode for the conversation.
+    # @return [LLM::Conversation]
+    def lazy
+      tap do
+        next if lazy?
+        @lazy = true
+        @messages = LLM::MessageQueue.new(@provider)
+      end
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true if the conversation is lazy
+    def lazy?
+      @lazy
+    end
+
+    private
+
+    def complete(prompt, role, params)
+      @provider.complete(
+        prompt,
+          role,
+          **@params.merge(params.merge(messages:))
+      )
+    end
   end
 end

data/lib/llm/message_queue.rb

@@ -13,7 +13,8 @@ module LLM
     # @return [LLM::MessageQueue]
     def initialize(provider)
       @provider = provider
-      @messages = []
+      @pending = []
+      @completed = []
     end
 
     ##
@@ -22,26 +23,32 @@ module LLM
     # @raise (see LLM::Provider#complete)
     # @return [void]
     def each
-      @messages = complete! unless @messages.grep(LLM::Message).size == @messages.size
-      @messages.each { yield(_1) }
+      complete! unless @pending.empty?
+      @completed.each { yield(_1) }
     end
 
     ##
-    # @param message [Object]
-    #  A message to add to the conversation thread
+    # @param [[LLM::Message, Hash]] item
+    #  A message and its parameters
     # @return [void]
-    def <<(message)
-      @messages << message
+    def <<(item)
+      @pending << item
+      self
     end
     alias_method :push, :<<
 
     private
 
     def complete!
-      prompt, role, params = @messages[-1]
-      rest = @messages[0..-2].map { (Array === _1) ? LLM::Message.new(_1[1], _1[0]) : _1 }
-      comp = @provider.complete(prompt, role, **params.merge(messages: rest)).choices.last
-      [*rest, LLM::Message.new(role, prompt), comp]
+      message, params = @pending[-1]
+      messages = @pending[0..-2].map { _1[0] }
+      completion = @provider.complete(
+        message.content,
+        message.role,
+        **params.merge(messages:)
+      )
+      @completed.concat([*messages, message, completion.choices[0]])
+      @pending.clear
     end
   end
 end

data/lib/llm/provider.rb

@@ -2,7 +2,18 @@
 
 ##
 # The Provider class represents an abstract class for
-# LLM (Language Model) providers
+# LLM (Language Model) providers.
+#
+# @note
+#  This class is not meant to be instantiated directly.
+#  Instead, use one of the subclasses that implement
+#  the methods defined here.
+#
+# @abstract
+# @see LLM::Provider::OpenAI
+# @see LLM::Provider::Anthropic
+# @see LLM::Provider::Gemini
+# @see LLM::Provider::Ollama
 class LLM::Provider
   require_relative "http_client"
   include LLM::HTTPClient
@@ -44,10 +55,20 @@ class LLM::Provider
 
   ##
   # Completes a given prompt using the LLM
+  # @example
+  #   llm = LLM.openai(ENV["KEY"])
+  #   context = [
+  #     {role: "system", content: "Answer all of my questions"},
+  #     {role: "system", content: "Your name is Pablo, you are 25 years old and you are my amigo"},
+  #   ]
+  #   res = llm.complete "What is your name and what age are you?", :user, messages: context
+  #   print "[#{res.choices[0].role}]", res.choices[0].content, "\n"
   # @param [String] prompt
   #  The input prompt to be completed
   # @param [Symbol] role
   #  The role of the prompt (e.g. :user, :system)
+  # @param [Array<Hash, LLM::Message>] messages
+  #  The messages to include in the completion
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Completion]
@@ -57,16 +78,22 @@ class LLM::Provider
 
   ##
   # Starts a new lazy conversation
+  # @note
+  #  This method creates a lazy variant of a
+  #  {LLM::Conversation LLM::Conversation} object.
   # @param prompt (see LLM::Provider#complete)
   # @param role (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
   # @return [LLM::LazyConversation]
   def chat(prompt, role = :user, **params)
-    LLM::LazyConversation.new(self, params).chat(prompt, role)
+    LLM::Conversation.new(self, params).lazy.chat(prompt, role)
   end
 
   ##
   # Starts a new conversation
+  # @note
+  #  This method creates a non-lazy variant of a
+  #  {LLM::Conversation LLM::Conversation} object.
   # @param prompt (see LLM::Provider#complete)
   # @param role (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)

data/lib/llm/providers/anthropic/format.rb

@@ -7,7 +7,13 @@ class LLM::Anthropic
     #  The messages to format
     # @return [Array<Hash>]
     def format(messages)
-      messages.map { {role: _1.role, content: format_content(_1.content)} }
+      messages.map do
+        if Hash === _1
+          {role: _1[:role], content: format_content(_1[:content])}
+        else
+          {role: _1.role, content: format_content(_1.content)}
+        end
+      end
     end
 
     private

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

@@ -7,7 +7,13 @@ class LLM::Gemini
     #  The messages to format
     # @return [Array<Hash>]
     def format(messages)
-      messages.map { {role: _1.role, parts: [format_content(_1.content)]} }
+      messages.map do
+        if Hash === _1
+          {role: _1[:role], parts: [format_content(_1[:content])]}
+        else
+          {role: _1.role, parts: [format_content(_1.content)]}
+        end
+      end
     end
 
     private

data/lib/llm/providers/ollama/format.rb

@@ -7,7 +7,13 @@ class LLM::Ollama
     #  The messages to format
     # @return [Array<Hash>]
     def format(messages)
-      messages.map { {role: _1.role, content: format_content(_1.content)} }
+      messages.map do
+        if Hash === _1
+          {role: _1[:role], content: format_content(_1[:content])}
+        else
+          {role: _1.role, content: format_content(_1.content)}
+        end
+      end
     end
 
     private

data/lib/llm/providers/openai/format.rb

@@ -7,7 +7,13 @@ class LLM::OpenAI
     #  The messages to format
     # @return [Array<Hash>]
     def format(messages)
-      messages.map { {role: _1.role, content: format_content(_1.content)} }
+      messages.map do
+        if Hash === _1
+          {role: _1[:role], content: format_content(_1[:content])}
+        else
+          {role: _1.role, content: format_content(_1.content)}
+        end
+      end
     end
 
     private

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -9,7 +9,7 @@ module LLM
   require_relative "llm/model"
   require_relative "llm/provider"
   require_relative "llm/conversation"
-  require_relative "llm/lazy_conversation"
+  require_relative "llm/message_queue"
   require_relative "llm/core_ext/ostruct"
 
   module_function

data/spec/gemini/completion_spec.rb

@@ -46,6 +46,27 @@ RSpec.describe "LLM::Gemini: completions" do
     end
   end
 
+  context "when given a thread of messages",
+          vcr: {cassette_name: "gemini/completions/successful_response_thread"} do
+    subject(:response) do
+      gemini.complete "What is your name? What age are you?", :user, messages: [
+        {role: "user", content: "Answer all of my questions"},
+        {role: "user", content: "Your name is Pablo, you are 25 years old and you are my amigo"}
+      ]
+    end
+
+    it "has choices" do
+      expect(response).to have_attributes(
+        choices: [
+          have_attributes(
+            role: "model",
+            content: "My name is Pablo, and I am 25 years old.  ¡Amigo!\n"
+          )
+        ]
+      )
+    end
+  end
+
   context "when given an unauthorized response",
           vcr: {cassette_name: "gemini/completions/unauthorized_response"} do
     subject(:response) { gemini.complete("Hello!", :user) }

data/spec/llm/conversation_spec.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-RSpec.describe LLM::Conversation do
+require "setup"
+
+RSpec.describe "LLM::Conversation: non-lazy" do
   shared_examples "a multi-turn conversation" do
     context "when given a thread of messages" do
       let(:inputs) do
@@ -54,3 +56,93 @@ RSpec.describe LLM::Conversation do
     include_examples "a multi-turn conversation"
   end
 end
+
+RSpec.describe "LLM::Conversation: lazy" do
+  let(:described_class) { LLM::Conversation }
+  let(:token) { ENV["LLM_SECRET"] || "TOKEN" }
+  let(:prompt) { "Keep your answers short and concise, and provide three answers to the three questions" }
+
+  context "with gemini",
+          vcr: {cassette_name: "gemini/lazy_conversation/successful_response"} do
+    let(:provider) { LLM.gemini(token) }
+    let(:conversation) { described_class.new(provider).lazy }
+
+    context "when given a thread of messages" do
+      subject(:message) { conversation.messages.to_a[-1] }
+
+      before do
+        conversation.chat prompt
+        conversation.chat "What is 3+2 ?"
+        conversation.chat "What is 5+5 ?"
+        conversation.chat "What is 5+7 ?"
+      end
+
+      it "maintains a conversation" do
+        is_expected.to have_attributes(
+          role: "model",
+          content: "5\n10\n12\n"
+        )
+      end
+    end
+  end
+
+  context "with openai"  do
+    let(:provider) { LLM.openai(token) }
+    let(:conversation) { described_class.new(provider).lazy }
+
+    context "when given a thread of messages",
+            vcr: {cassette_name: "openai/lazy_conversation/successful_response"} do
+      subject(:message) { conversation.recent_message }
+
+      before do
+        conversation.chat prompt, :system
+        conversation.chat "What is 3+2 ?"
+        conversation.chat "What is 5+5 ?"
+        conversation.chat "What is 5+7 ?"
+      end
+
+      it "maintains a conversation" do
+        is_expected.to have_attributes(
+          role: "assistant",
+          content: "1. 5  \n2. 10  \n3. 12  "
+        )
+      end
+    end
+
+    context "when given a specific model",
+            vcr: {cassette_name: "openai/lazy_conversation/successful_response_o3_mini"} do
+      let(:conversation) { described_class.new(provider, model: provider.models["o3-mini"]).lazy }
+
+      it "maintains the model throughout a conversation" do
+        conversation.chat(prompt, :system)
+        expect(conversation.recent_message.extra[:completion].model).to eq("o3-mini-2025-01-31")
+        conversation.chat("What is 5+5?")
+        expect(conversation.recent_message.extra[:completion].model).to eq("o3-mini-2025-01-31")
+      end
+    end
+  end
+
+  context "with ollama",
+          vcr: {cassette_name: "ollama/lazy_conversation/successful_response"} do
+    let(:provider) { LLM.ollama(nil, host: "eel.home.network") }
+    let(:conversation) { described_class.new(provider).lazy }
+
+    context "when given a thread of messages" do
+      subject(:message) { conversation.recent_message }
+
+      before do
+        conversation.chat prompt, :system
+        conversation.chat "What is 3+2 ?"
+        conversation.chat "What is 5+5 ?"
+        conversation.chat "What is 5+7 ?"
+      end
+
+      it "maintains a conversation" do
+        is_expected.to have_attributes(
+          role: "assistant",
+          content: "Here are the calculations:\n\n1. 3 + 2 = 5\n2. 5 + 5 = 10\n3. 5 + 7 = 12"
+        )
+      end
+    end
+  end
+end

data/spec/openai/completion_spec.rb

@@ -42,6 +42,27 @@ RSpec.describe "LLM::OpenAI: completions" do
     end
   end
 
+  context "when given a thread of messages",
+          vcr: {cassette_name: "openai/completions/successful_response_thread"} do
+    subject(:response) do
+      openai.complete "What is your name? What age are you?", :user, messages: [
+        {role: "system", content: "Answer all of my questions"},
+        {role: "system", content: "Your name is Pablo, you are 25 years old and you are my amigo"}
+      ]
+    end
+
+    it "has choices" do
+      expect(response).to have_attributes(
+        choices: [
+          have_attributes(
+            role: "assistant",
+            content: "My name is Pablo, and I'm 25 years old! How can I help you today, amigo?"
+          )
+        ]
+      )
+    end
+  end
+
   context "when given a 'bad request' response",
           vcr: {cassette_name: "openai/completions/bad_request"} do
     subject(:response) { openai.complete(URI("/foobar.exe"), :user) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Antar Azri
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-01 00:00:00.000000000 Z
+date: 2025-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -197,7 +197,6 @@ files:
 - lib/llm/error.rb
 - lib/llm/file.rb
 - lib/llm/http_client.rb
-- lib/llm/lazy_conversation.rb
 - lib/llm/message.rb
 - lib/llm/message_queue.rb
 - lib/llm/model.rb
@@ -235,7 +234,6 @@ files:
 - spec/gemini/completion_spec.rb
 - spec/gemini/embedding_spec.rb
 - spec/llm/conversation_spec.rb
-- spec/llm/lazy_conversation_spec.rb
 - spec/ollama/completion_spec.rb
 - spec/ollama/embedding_spec.rb
 - spec/openai/completion_spec.rb

data/lib/llm/lazy_conversation.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module LLM
-  require_relative "message_queue"
-
-  ##
-  # {LLM::LazyConversation LLM::LazyConversation} provides a
-  # conversation object that allows input prompts to be queued
-  # and only sent to the LLM when a response is needed.
-  #
-  # @example
-  #   llm = LLM.openai(key)
-  #   bot = llm.chat("Be a helpful weather assistant", :system)
-  #   bot.chat("What's the weather like in Rio?")
-  #   bot.chat("What's the weather like in Algiers?")
-  #   bot.messages.each do |message|
-  #     # A single request is made at this point
-  #   end
-  class LazyConversation
-    ##
-    # @return [LLM::MessageQueue]
-    attr_reader :messages
-
-    ##
-    # @param [LLM::Provider] provider
-    #  A provider
-    def initialize(provider, params = {})
-      @provider = provider
-      @params = params
-      @messages = LLM::MessageQueue.new(provider)
-    end
-
-    ##
-    # @param prompt (see LLM::Provider#prompt)
-    # @return [LLM::Conversation]
-    def chat(prompt, role = :user, **params)
-      tap { @messages << [prompt, role, @params.merge(params)] }
-    end
-
-    ##
-    # @param [#to_s] role
-    #  The role of the last message.
-    #  Defaults to the LLM's assistant role (eg "assistant" or "model")
-    # @return [LLM::Message]
-    #  The last message for the given role
-    def last_message(role: @provider.assistant_role)
-      messages.reverse_each.find { _1.role == role.to_s }
-    end
-    alias_method :recent_message, :last_message
-  end
-end

data/spec/llm/lazy_conversation_spec.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-require "setup"
-
-RSpec.describe LLM::LazyConversation do
-  let(:token) { ENV["LLM_SECRET"] || "TOKEN" }
-  let(:prompt) { "Keep your answers short and concise, and provide three answers to the three questions" }
-
-  context "with gemini",
-          vcr: {cassette_name: "gemini/lazy_conversation/successful_response"} do
-    let(:provider) { LLM.gemini(token) }
-    let(:conversation) { described_class.new(provider) }
-
-    context "when given a thread of messages" do
-      subject(:message) { conversation.messages.to_a[-1] }
-
-      before do
-        conversation.chat prompt
-        conversation.chat "What is 3+2 ?"
-        conversation.chat "What is 5+5 ?"
-        conversation.chat "What is 5+7 ?"
-      end
-
-      it "maintains a conversation" do
-        is_expected.to have_attributes(
-          role: "model",
-          content: "5\n10\n12\n"
-        )
-      end
-    end
-  end
-
-  context "with openai"  do
-    let(:provider) { LLM.openai(token) }
-    let(:conversation) { described_class.new(provider) }
-
-    context "when given a thread of messages",
-            vcr: {cassette_name: "openai/lazy_conversation/successful_response"} do
-      subject(:message) { conversation.recent_message }
-
-      before do
-        conversation.chat prompt, :system
-        conversation.chat "What is 3+2 ?"
-        conversation.chat "What is 5+5 ?"
-        conversation.chat "What is 5+7 ?"
-      end
-
-      it "maintains a conversation" do
-        is_expected.to have_attributes(
-          role: "assistant",
-          content: "1. 5  \n2. 10  \n3. 12  "
-        )
-      end
-    end
-
-    context "when given a specific model",
-            vcr: {cassette_name: "openai/lazy_conversation/successful_response_o3_mini"} do
-      let(:conversation) { described_class.new(provider, model: provider.models["o3-mini"]) }
-
-      it "maintains the model throughout a conversation" do
-        conversation.chat(prompt, :system)
-        expect(conversation.recent_message.extra[:completion].model).to eq("o3-mini-2025-01-31")
-        conversation.chat("What is 5+5?")
-        expect(conversation.recent_message.extra[:completion].model).to eq("o3-mini-2025-01-31")
-      end
-    end
-  end
-
-  context "with ollama",
-          vcr: {cassette_name: "ollama/lazy_conversation/successful_response"} do
-    let(:provider) { LLM.ollama(nil, host: "eel.home.network") }
-    let(:conversation) { described_class.new(provider) }
-
-    context "when given a thread of messages" do
-      subject(:message) { conversation.recent_message }
-
-      before do
-        conversation.chat prompt, :system
-        conversation.chat "What is 3+2 ?"
-        conversation.chat "What is 5+5 ?"
-        conversation.chat "What is 5+7 ?"
-      end
-
-      it "maintains a conversation" do
-        is_expected.to have_attributes(
-          role: "assistant",
-          content: "Here are the calculations:\n\n1. 3 + 2 = 5\n2. 5 + 5 = 10\n3. 5 + 7 = 12"
-        )
-      end
-    end
-  end
-end