llm.rb 1.0.1 → 2.0.0

data/lib/llm/bot.rb

@@ -13,25 +13,18 @@ module LLM
   #
   #   llm  = LLM.openai(key: ENV["KEY"])
   #   bot  = LLM::Bot.new(llm)
-  #   url  = "https://en.wikipedia.org/wiki/Special:FilePath/Cognac_glass.jpg"
-  #   msgs = bot.chat do |prompt|
-  #     prompt.system "Your task is to answer all user queries"
-  #     prompt.user ["Tell me about this URL", URI(url)]
-  #     prompt.user ["Tell me about this PDF", File.open("handbook.pdf", "rb")]
-  #     prompt.user "Are the URL and PDF similar to each other?"
+  #   url  = "https://upload.wikimedia.org/wikipedia/commons/c/c7/Lisc_lipy.jpg"
+  #
+  #   prompt = bot.build_prompt do
+  #     it.system "Your task is to answer all user queries"
+  #     it.user ["Tell me about this URL", bot.image_url(url)]
+  #     it.user ["Tell me about this PDF", bot.local_file("handbook.pdf")]
   #   end
+  #   bot.chat(prompt)
   #
-  #   # At this point, we execute a single request
-  #   msgs.each { print "[#{_1.role}] ", _1.content, "\n" }
+  #   # The full conversation history is in bot.messages
+  #   bot.messages.each { print "[#{_1.role}] ", _1.content, "\n" }
   class Bot
-    require_relative "bot/prompt/completion"
-    require_relative "bot/prompt/respond"
-    require_relative "bot/conversable"
-    require_relative "bot/builder"
-
-    include Conversable
-    include Builder
-
     ##
     # Returns an Enumerable for the messages in a conversation
     # @return [LLM::Buffer<LLM::Message>]
@@ -45,7 +38,6 @@ module LLM
     #  Any parameter the provider supports can be included and
     #  not only those listed here.
     # @option params [String] :model Defaults to the provider's default model
-    # @option params [#to_json, nil] :schema Defaults to nil
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
     def initialize(provider, params = {})
       @provider = provider
@@ -54,56 +46,51 @@ module LLM
     end
 
     ##
-    # Maintain a conversation via the chat completions API
-    # @overload def chat(prompt, params = {})
-    #   @param prompt (see LLM::Provider#complete)
-    #   @param params The params
-    #   @return [LLM::Bot]
-    #     Returns self
-    # @overload def chat(prompt, params, &block)
-    #   @param prompt (see LLM::Provider#complete)
-    #   @param params The params
-    #   @yield prompt Yields a prompt
-    #   @return [LLM::Buffer]
-    #     Returns messages
-    def chat(prompt = nil, params = {})
-      if block_given?
-        params = prompt
-        yield Prompt::Completion.new(self, params)
-        messages
-      elsif prompt.nil?
-        raise ArgumentError, "wrong number of arguments (given 0, expected 1)"
-      else
-        params = {role: :user}.merge!(params)
-        tap { async_completion(prompt, params) }
-      end
+    # Maintain a conversation via the chat completions API.
+    # This method immediately sends a request to the LLM and returns the response.
+    #
+    # @param prompt (see LLM::Provider#complete)
+    # @param params The params, including optional :role (defaults to :user), :stream, :tools, :schema etc.
+    # @return [LLM::Response] Returns the LLM's response for this turn.
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   bot = LLM::Bot.new(llm)
+    #   response = bot.chat("Hello, what is your name?")
+    #   puts response.choices[0].content
+    def chat(prompt, params = {})
+      prompt, params, messages = fetch(prompt, params)
+      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)]
+      @messages.concat messages
+      @messages.concat [res.choices[-1]]
+      res
     end
 
     ##
-    # Maintain a conversation via the responses API
-    # @overload def respond(prompt, params = {})
-    #   @param prompt (see LLM::Provider#complete)
-    #   @param params The params
-    #   @return [LLM::Bot]
-    #     Returns self
-    # @overload def respond(prompt, params, &block)
-    #   @note Not all LLM providers support this API
-    #   @param prompt (see LLM::Provider#complete)
-    #   @param params The params
-    #   @yield prompt Yields a prompt
-    #   @return [LLM::Buffer]
-    #     Returns messages
-    def respond(prompt = nil, params = {})
-      if block_given?
-        params = prompt
-        yield Prompt::Respond.new(self, params)
-        messages
-      elsif prompt.nil?
-        raise ArgumentError, "wrong number of arguments (given 0, expected 1)"
-      else
-        params = {role: :user}.merge!(params)
-        tap { async_response(prompt, params) }
-      end
+    # Maintain a conversation via the responses API.
+    # This method immediately sends a request to the LLM and returns the response.
+    #
+    # @note Not all LLM providers support this API
+    # @param prompt (see LLM::Provider#complete)
+    # @param params The params, including optional :role (defaults to :user), :stream, :tools, :schema etc.
+    # @return [LLM::Response] Returns the LLM's response for this turn.
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   bot = LLM::Bot.new(llm)
+    #   res = bot.respond("What is the capital of France?")
+    #   puts res.output_text
+    def respond(prompt, params = {})
+      prompt, params, messages = fetch(prompt, params)
+      res_id = @messages.find(&:assistant?)&.response&.response_id
+      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)]
+      @messages.concat messages
+      @messages.concat [res.choices[-1]]
+      res
     end
 
     ##
@@ -118,24 +105,12 @@ module LLM
     # Returns an array of functions that can be called
     # @return [Array<LLM::Function>]
     def functions
-      messages
+      @messages
         .select(&:assistant?)
         .flat_map(&:functions)
         .select(&:pending?)
     end
 
-    ##
-    # @example
-    #   llm = LLM.openai(key: ENV["KEY"])
-    #   bot = LLM::Bot.new(llm, stream: $stdout)
-    #   bot.chat("Hello", role: :user).flush
-    # Drains the buffer and returns all messages as an array
-    # @return [Array<LLM::Message>]
-    def drain
-      messages.drain
-    end
-    alias_method :flush, :drain
-
     ##
     # Returns token usage for the conversation
     # @note
@@ -144,7 +119,59 @@ module LLM
     # if there are no assistant messages
     # @return [LLM::Object]
     def usage
-      messages.find(&:assistant?)&.usage || LLM::Object.from_hash({})
+      @messages.find(&:assistant?)&.usage || LLM::Object.from_hash({})
+    end
+
+    ##
+    # Build a prompt
+    # @example
+    #   prompt = bot.build_prompt do
+    #     it.system "Your task is to assist the user"
+    #     it.user "Hello, can you assist me?"
+    #   end
+    #   bot.chat(prompt)
+    def build_prompt(&)
+      LLM::Builder.new(&).tap(&:call)
+    end
+
+    ##
+    # Recongize an object as a URL to an image
+    # @param [String] url
+    #  The URL
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def image_url(url)
+      LLM::Object.from_hash(value: url, kind: :image_url)
+    end
+
+    ##
+    # Recongize an object as a local file
+    # @param [String] path
+    #  The path
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def local_file(path)
+      LLM::Object.from_hash(value: LLM.File(path), kind: :local_file)
+    end
+
+    ##
+    # Reconginize an object as a remote file
+    # @param [LLM::Response] res
+    #  The response
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def remote_file(res)
+      LLM::Object.from_hash(value: res, kind: :remote_file)
+    end
+
+    private
+
+    def fetch(prompt, params)
+      return [prompt, params, []] unless LLM::Builder === prompt
+      messages = prompt.to_a
+      prompt = messages.shift
+      params.merge!(role: prompt.role)
+      [prompt.content, params, messages]
     end
   end
 end

data/lib/llm/buffer.rb

@@ -3,8 +3,7 @@
 module LLM
   ##
   # {LLM::Buffer LLM::Buffer} provides an Enumerable object that
-  # yields each message in a conversation on-demand, and only sends
-  # a request to the LLM when a response is needed.
+  # tracks messages in a conversation thread.
   class Buffer
     include Enumerable
 
@@ -13,19 +12,24 @@ module LLM
     # @return [LLM::Buffer]
     def initialize(provider)
       @provider = provider
-      @pending = []
-      @completed = []
+      @messages = []
+    end
+
+    ##
+    # Append an array
+    # @param [Array<LLM::Message>] ary
+    #  The array to append
+    def concat(ary)
+      @messages.concat(ary)
     end
 
     ##
     # @yield [LLM::Message]
     #  Yields each message in the conversation thread
-    # @raise (see LLM::Provider#complete)
     # @return [void]
     def each(...)
       if block_given?
-        empty! unless @pending.empty?
-        @completed.each { yield(_1) }
+        @messages.each { yield(_1) }
       else
         enum_for(:each, ...)
       end
@@ -53,19 +57,15 @@ module LLM
     #  The number of messages to return
     # @return [LLM::Message, Array<LLM::Message>, nil]
     def last(n = nil)
-      if @pending.empty?
-        n.nil? ? @completed.last : @completed.last(n)
-      else
-        n.nil? ? to_a.last : to_a.last(n)
-      end
+      n.nil? ? @messages.last : @messages.last(n)
     end
 
     ##
-    # @param [[LLM::Message, Hash, Symbol]] item
-    #  A message and its parameters
+    # @param [[LLM::Message]] item
+    #  A message to add to the buffer
     # @return [void]
     def <<(item)
-      @pending << item
+      @messages << item
       self
     end
     alias_method :push, :<<
@@ -76,87 +76,21 @@ module LLM
     # @return [LLM::Message, nil]
     #  Returns a message, or nil
     def [](index)
-      if @pending.empty?
-        if Range === index
-          slice = @completed[index]
-          (slice.nil? || slice.size < index.size) ? to_a[index] : slice
-        else
-          @completed[index]
-        end
-      else
-        to_a[index]
-      end
+      @messages[index]
     end
 
     ##
     # @return [String]
     def inspect
       "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
-      "completed_count=#{@completed.size} pending_count=#{@pending.size}>"
+      "message_count=#{@messages.size}>"
     end
 
     ##
     # Returns true when the buffer is empty
     # @return [Boolean]
     def empty?
-      @pending.empty? and @completed.empty?
-    end
-
-    ##
-    # @example
-    #   llm = LLM.openai(key: ENV["KEY"])
-    #   bot = LLM::Bot.new(llm, stream: $stdout)
-    #   bot.chat "Hello", role: :user
-    #   bot.messages.flush
-    # @see LLM::Bot#drain
-    # @note
-    #   This method is especially useful when using the streaming API.
-    # Drains the buffer and returns all messages as an array
-    # @return [Array<LLM::Message>]
-    def drain
-      to_a
-    end
-    alias_method :flush, :drain
-
-    private
-
-    def empty!
-      message, params, method = @pending.pop
-      if method == :complete
-        complete!(message, params)
-      elsif method == :respond
-        respond!(message, params)
-      else
-        raise LLM::Error, "Unknown method: #{method}"
-      end
-    end
-
-    def complete!(message, params)
-      oldparams = @pending.map { _1[1] }
-      pendings  = @pending.map { _1[0] }
-      messages  = [*@completed, *pendings]
-      role = message.role
-      completion = @provider.complete(
-        message.content,
-        [*oldparams, params.merge(role:, messages:)].inject({}, &:merge!)
-      )
-      @completed.concat([*pendings, message, *completion.choices[0]])
-      @pending.clear
-    end
-
-    def respond!(message, params)
-      oldparams = @pending.map { _1[1] }
-      pendings  = @pending.map { _1[0] }
-      messages  = [*pendings]
-      role = message.role
-      params = [
-        *oldparams,
-        params.merge(input: messages),
-        @response ? {previous_response_id: @response.response_id} : {}
-      ].inject({}, &:merge!)
-      @response = @provider.responses.create(message.content, params.merge(role:))
-      @completed.concat([*pendings, message, *@response.choices[0]])
-      @pending.clear
+      @messages.empty?
     end
   end
 end

data/lib/llm/builder.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::Builder LLM::Builder} class can build a collection
+# of messages that can be sent in a single request.
+#
+# @example
+#   llm = LLM.openai(key: ENV["KEY"])
+#   bot = LLM::Bot.new(llm)
+#   prompt = bot.build_prompt do
+#     it.system "Your task is to assist the user"
+#     it.user "Hello. Can you assist me?"
+#   end
+#   res = bot.chat(prompt)
+class LLM::Builder
+  ##
+  # @param [Proc] evaluator
+  #  The evaluator
+  def initialize(&evaluator)
+    @buffer = []
+    @evaluator = evaluator
+  end
+
+  ##
+  # @return [void]
+  def call
+    @evaluator.call(self)
+  end
+
+  ##
+  # @param [String] content
+  #  The message
+  # @param [Symbol] role
+  #  The role (eg user, system)
+  # @return [void]
+  def chat(content, role: :user)
+    @buffer << LLM::Message.new(role, content)
+  end
+
+  ##
+  # @param [String] content
+  #  The message content
+  # @return [void]
+  def user(content)
+    chat(content, role: :user)
+  end
+
+  ##
+  # @param [String] content
+  #  The message content
+  # @return [void]
+  def system(content)
+    chat(content, role: :system)
+  end
+
+  ##
+  # @return [Array]
+  def to_a
+    @buffer.dup
+  end
+end

data/lib/llm/function.rb

@@ -83,7 +83,11 @@ class LLM::Function
   # @return [void]
   def params
     if block_given?
-      @params = yield(@schema)
+      if @params
+        @params.merge!(yield(@schema))
+      else
+        @params = yield(@schema)
+      end
     else
       @params
     end

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

@@ -45,29 +45,12 @@ module LLM::Anthropic::Format
         content.empty? ? throw(:abort, nil) : [content]
       when Array
         content.empty? ? throw(:abort, nil) : content.flat_map { format_content(_1) }
-      when URI
-        [{type: :image, source: {type: "url", url: content.to_s}}]
-      when File
-        content.close unless content.closed?
-        format_content(LLM.File(content.path))
-      when LLM::File
-        if content.image?
-          [{type: :image, source: {type: "base64", media_type: content.mime_type, data: content.to_b64}}]
-        elsif content.pdf?
-          [{type: :document, source: {type: "base64", media_type: content.mime_type, data: content.to_b64}}]
-        else
-          raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
-                                  "is not an image or PDF, and therefore not supported by the " \
-                                  "Anthropic API"
-        end
-      when LLM::Response
-        if content.file?
-          [{type: content.file_type, source: {type: :file, file_id: content.id}}]
-        else
-          prompt_error!(content)
-        end
+      when LLM::Object
+        format_object(content)
       when String
         [{type: :text, text: content}]
+      when LLM::Response
+        format_remote_file(content)
       when LLM::Message
         format_content(content.content)
       when LLM::Function::Return
@@ -77,9 +60,42 @@ module LLM::Anthropic::Format
       end
     end
 
+    def format_object(object)
+      case object.kind
+      when :image_url
+        [{type: :image, source: {type: "url", url: object.value.to_s}}]
+      when :local_file
+        format_local_file(object.value)
+      when :remote_file
+        format_remote_file(object.value)
+      else
+        prompt_error!(content)
+      end
+    end
+
+    def format_local_file(file)
+      if file.image?
+        [{type: :image, source: {type: "base64", media_type: file.mime_type, data: file.to_b64}}]
+      elsif file.pdf?
+        [{type: :document, source: {type: "base64", media_type: file.mime_type, data: file.to_b64}}]
+      else
+        raise LLM::PromptError, "The given object (an instance of #{file.class}) " \
+                                "is not an image or PDF, and therefore not supported by the " \
+                                "Anthropic API"
+      end
+    end
+
+    def format_remote_file(file)
+      prompt_error!(file) unless file.file?
+      [{type: file.file_type, source: {type: :file, file_id: file.id}}]
+    end
+
     def prompt_error!(content)
-      raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
-                              "is not supported by the Anthropic API"
+      if LLM::Object === content
+      else
+        raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                                "is not supported by the Anthropic API."
+      end
     end
 
     def message = @message

data/lib/llm/providers/deepseek/format/completion_format.rb

@@ -36,9 +36,10 @@ module LLM::DeepSeek::Format
         format_content(content.content)
       when LLM::Function::Return
         throw(:abort, {role: "tool", tool_call_id: content.id, content: JSON.dump(content.value)})
+      when LLM::Object
+        prompt_error!(content)
       else
-        raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
-                                "is not supported by the DeepSeek chat completions API"
+        prompt_error!(content)
       end
     end
 
@@ -61,6 +62,16 @@ module LLM::DeepSeek::Format
       end
     end
 
+    def prompt_error!(object)
+      if LLM::Object === object
+        raise LLM::PromptError, "The given LLM::Object with kind '#{content.kind}' is not " \
+                                "supported by the DeepSeek API"
+      else
+        raise LLM::PromptError, "The given object (an instance of #{object.class}) " \
+                                "is not supported by the DeepSeek API"
+      end
+    end
+
     def message = @message
     def content = message.content
     def returns = content.grep(LLM::Function::Return)

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

@@ -43,7 +43,7 @@ class LLM::Gemini
       res = @provider.complete [
         "Your task is to transcribe the contents of an audio file",
         "Your response should include the transcription, and nothing else",
-        LLM.File(file)
+        LLM::Object.from_hash(value: LLM.File(file), kind: :local_file)
       ], params.merge(role: :user, model:)
       res.tap { _1.define_singleton_method(:text) { choices[0].content } }
     end
@@ -65,7 +65,7 @@ class LLM::Gemini
       res = @provider.complete [
         "Your task is to translate the contents of an audio file into English",
         "Your response should include the translation, and nothing else",
-        LLM.File(file)
+        LLM::Object.from_hash(value: LLM.File(file), kind: :local_file)
       ], params.merge(role: :user, model:)
       res.tap { _1.define_singleton_method(:text) { choices[0].content } }
     end

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

@@ -30,37 +30,48 @@ module LLM::Gemini::Format
       case content
       when Array
         content.empty? ? throw(:abort, nil) : content.flat_map { format_content(_1) }
-      when LLM::Response
-        format_response(content)
-      when File
-        content.close unless content.closed?
-        format_content(LLM.File(content.path))
-      when LLM::File
-        file = content
-        [{inline_data: {mime_type: file.mime_type, data: file.to_b64}}]
       when String
         [{text: content}]
+      when LLM::Response
+        format_remote_file(content)
       when LLM::Message
         format_content(content.content)
       when LLM::Function::Return
         [{functionResponse: {name: content.name, response: content.value}}]
+      when LLM::Object
+        format_object(content)
       else
         prompt_error!(content)
       end
     end
 
-    def format_response(response)
-      if response.file?
-        file = response
-        [{file_data: {mime_type: file.mime_type, file_uri: file.uri}}]
+    def format_object(object)
+      case object.kind
+      when :image_url
+        [{file_data: {mime_type: "image/*", file_uri: object.value.to_s}}]
+      when :local_file
+        file = object.value
+        [{inline_data: {mime_type: file.mime_type, data: file.to_b64}}]
+      when :remote_file
+        format_remote_file(object.value)
       else
-        prompt_error!(content)
+        prompt_error!(object)
       end
     end
 
+    def format_remote_file(file)
+      return prompt_error!(file) unless file.file?
+      [{file_data: {mime_type: file.mime_type, file_uri: file.uri}}]
+    end
+
     def prompt_error!(object)
-      raise LLM::PromptError, "The given object (an instance of #{object.class}) " \
-                              "is not supported by the Gemini API"
+      if LLM::Object === object
+        raise LLM::PromptError, "The given LLM::Object with kind '#{content.kind}' is not " \
+                                "supported by the Gemini API"
+      else
+        raise LLM::PromptError, "The given object (an instance of #{object.class}) " \
+                                "is not supported by the Gemini API"
+      end
     end
 
     def message = @message

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

@@ -69,7 +69,7 @@ class LLM::Gemini
     # @return [LLM::Response]
     def edit(image:, prompt:, model: "gemini-2.5-flash-image-preview", **params)
       req   = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
-      image = LLM.File(image)
+      image = LLM::Object.from_hash(value: LLM.File(image), kind: :local_file)
       body  = JSON.dump({
         contents: [{parts: [{text: edit_prompt}, {text: prompt}, format.format_content(image)]}],
         generationConfig: {responseModalities: ["TEXT", "IMAGE"]}