llm.rb 0.2.1 → 0.3.1

data/lib/llm/chat.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Chat LLM::Chat} provides a chat object that maintains a
+  # thread of messages that acts as context throughout a conversation.
+  # A conversation can use the chat completions API that most LLM providers
+  # support or the responses API that a select few LLM providers support.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(ENV["KEY"])
+  #   bot = LLM::Chat.new(llm).lazy
+  #   bot.chat("Your task is to answer all of my questions", :system)
+  #   bot.chat("Your answers should be short and concise", :system)
+  #   bot.chat("What is 5 + 7 ?", :user)
+  #   bot.chat("Why is the sky blue ?", :user)
+  #   bot.chat("Why did the chicken cross the road ?", :user)
+  #   bot.messages.map { print "[#{_1.role}]", _1.content, "\n" }
+  class Chat
+    ##
+    # @return [Array<LLM::Message>]
+    attr_reader :messages
+
+    ##
+    # @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
+
+    ##
+    # Maintain a conversation via the chat completions API
+    # @param prompt (see LLM::Provider#prompt)
+    # @param role (see LLM::Provider#prompt)
+    # @param params (see LLM::Provider#prompt)
+    # @return [LLM::Chat]
+    def chat(prompt, role = :user, **params)
+      if lazy?
+        @messages << [LLM::Message.new(role, prompt), @params.merge(params), :complete]
+        self
+      else
+        completion = complete!(prompt, role, params)
+        @messages.concat [Message.new(role, prompt), completion.choices[0]]
+        self
+      end
+    end
+
+    ##
+    # Maintain a conversation via the responses API
+    # @note Not all LLM providers support this API
+    # @param prompt (see LLM::Provider#prompt)
+    # @param role (see LLM::Provider#prompt)
+    # @param params (see LLM::Provider#prompt)
+    # @return [LLM::Chat]
+    def respond(prompt, role = :user, **params)
+      if lazy?
+        @messages << [LLM::Message.new(role, prompt), @params.merge(params), :respond]
+        self
+      else
+        @response = respond!(prompt, role, params)
+        @messages.concat [Message.new(role, prompt), @response.outputs[0]]
+        self
+      end
+    end
+
+    ##
+    # The last message in the conversation.
+    # @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.
+    # @return [LLM::Message]
+    def last_message(role: @provider.assistant_role)
+      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::Chat]
+    def lazy
+      tap do
+        next if lazy?
+        @lazy = true
+        @messages = LLM::Buffer.new(@provider)
+      end
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true if the conversation is lazy
+    def lazy?
+      @lazy
+    end
+
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "@provider=#{@provider.class}, @params=#{@params.inspect}, " \
+      "@messages=#{@messages.inspect}, @lazy=#{@lazy.inspect}>"
+    end
+
+    private
+
+    def respond!(prompt, role, params)
+      @provider.responses.create(
+        prompt,
+        role,
+        **@params.merge(params.merge(@response ? {previous_response_id: @response.id} : {}))
+      )
+    end
+
+    def complete!(prompt, role, params)
+      @provider.complete(
+        prompt,
+        role,
+        **@params.merge(params.merge(messages:))
+      )
+    end
+  end
+end

data/lib/llm/error.rb

@@ -10,7 +10,7 @@ module LLM
 
     ##
     # The superclass of all HTTP protocol errors
-    class BadResponse < Error
+    class ResponseError < Error
       ##
       # @return [Net::HTTPResponse]
       #  Returns the response associated with an error
@@ -19,10 +19,10 @@ module LLM
 
     ##
     # HTTPUnauthorized
-    Unauthorized = Class.new(BadResponse)
+    Unauthorized = Class.new(ResponseError)
 
     ##
     # HTTPTooManyRequests
-    RateLimit = Class.new(BadResponse)
+    RateLimit = Class.new(ResponseError)
   end
 end

data/lib/llm/file.rb

@@ -1,45 +1,10 @@
 # frozen_string_literal: true
 
+##
+# The {LLM::File LLM::File} class represents a local file. It can
+# be used as a prompt with certain providers (eg: Ollama, Gemini),
+# and as an input with certain methods
 class LLM::File
-  ##
-  # @return [Hash]
-  #  Returns a hash of common file extensions and their
-  #  corresponding MIME types
-  def self.mime_types
-    @mime_types ||= {
-      # Images
-      ".png" => "image/png",
-      ".jpg" => "image/jpeg",
-      ".jpeg" => "image/jpeg",
-      ".webp" => "image/webp",
-
-      # Videos
-      ".flv" => "video/x-flv",
-      ".mov" => "video/quicktime",
-      ".mpeg" => "video/mpeg",
-      ".mpg" => "video/mpeg",
-      ".mp4" => "video/mp4",
-      ".webm" => "video/webm",
-      ".wmv" => "video/x-ms-wmv",
-      ".3gp" => "video/3gpp",
-
-      # Audio
-      ".aac" => "audio/aac",
-      ".flac" => "audio/flac",
-      ".mp3" => "audio/mpeg",
-      ".m4a" => "audio/mp4",
-      ".mpga" => "audio/mpeg",
-      ".opus" => "audio/opus",
-      ".pcm" => "audio/L16",
-      ".wav" => "audio/wav",
-      ".weba" => "audio/webm",
-
-      # Documents
-      ".pdf" => "application/pdf",
-      ".txt" => "text/plain"
-    }.freeze
-  end
-
   ##
   # @return [String]
   #  Returns the path to a file
@@ -53,7 +18,38 @@ class LLM::File
   # @return [String]
   #  Returns the MIME type of the file
   def mime_type
-    self.class.mime_types[File.extname(path)]
+    LLM::Mime[File.extname(path)]
+  end
+
+  ##
+  # @return [String]
+  #  Returns true if the file is an image
+  def image?
+    mime_type.start_with?("image/")
+  end
+
+  ##
+  # @return [Integer]
+  #  Returns the size of the file in bytes
+  def bytesize
+    File.size(path)
+  end
+
+  ##
+  # @return [String]
+  #  Returns the file contents in base64
+  def to_b64
+    [File.binread(path)].pack("m0")
+  end
+
+  ##
+  # @return [File]
+  #  Yields an IO object suitable to be streamed
+  def with_io
+    io = File.open(path, "rb")
+    yield(io)
+  ensure
+    io.close
   end
 end
 

data/lib/llm/message.rb

@@ -3,18 +3,22 @@
 module LLM
   class Message
     ##
+    # Returns the role of the message
     # @return [Symbol]
     attr_reader :role
 
     ##
+    # Returns the content of the message
     # @return [String]
     attr_reader :content
 
     ##
+    # Returns extra context associated with the message
     # @return [Hash]
     attr_reader :extra
 
     ##
+    # Returns a new message
     # @param [Symbol] role
     # @param [String] content
     # @param [Hash] extra
@@ -26,23 +30,17 @@ module LLM
     end
 
     ##
-    # @return [OpenStruct]
-    def logprobs
-      return nil unless extra.key?(:logprobs)
-      OpenStruct.from_hash(extra[:logprobs])
-    end
-
-    ##
+    # Returns a hash representation of the message
     # @return [Hash]
     def to_h
       {role:, content:}
     end
 
     ##
+    # Returns true when two objects have the same role and content
     # @param [Object] other
     #  The other object to compare
     # @return [Boolean]
-    #  Returns true when the "other" object has the same role and content
     def ==(other)
       if other.respond_to?(:to_h)
         to_h == other.to_h
@@ -51,5 +49,20 @@ module LLM
       end
     end
     alias_method :eql?, :==
+
+    ##
+    # Returns true when the message is from the LLM
+    # @return [Boolean]
+    def assistant?
+      role == "assistant" || role == "model"
+    end
+
+    ##
+    # Returns a string representation of the message
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "role=#{role.inspect} content=#{content.inspect}>"
+    end
   end
 end

data/lib/llm/mime.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+##
+# @private
+class LLM::Mime
+  ##
+  # Lookup a mime type
+  # @return [String, nil]
+  def self.[](key)
+    if key.respond_to?(:path)
+      types[File.extname(key.path)]
+    else
+      types[key]
+    end
+  end
+
+  ##
+  # Returns a Hash of mime types
+  # @return [Hash]
+  def self.types
+    @types ||= {
+      # Images
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".webp" => "image/webp",
+
+      # Videos
+      ".flv" => "video/x-flv",
+      ".mov" => "video/quicktime",
+      ".mpeg" => "video/mpeg",
+      ".mpg" => "video/mpeg",
+      ".mp4" => "video/mp4",
+      ".webm" => "video/webm",
+      ".wmv" => "video/x-ms-wmv",
+      ".3gp" => "video/3gpp",
+
+      # Audio
+      ".aac" => "audio/aac",
+      ".flac" => "audio/flac",
+      ".mp3" => "audio/mpeg",
+      ".m4a" => "audio/mp4",
+      ".mpga" => "audio/mpeg",
+      ".opus" => "audio/opus",
+      ".pcm" => "audio/L16",
+      ".wav" => "audio/wav",
+      ".weba" => "audio/webm",
+
+      # Documents
+      ".pdf" => "application/pdf",
+      ".txt" => "text/plain"
+    }
+  end
+end

data/lib/llm/multipart.rb

@@ -0,0 +1,100 @@
+# encoding: ascii-8bit
+# frozen_string_literal: true
+
+##
+# @private
+class LLM::Multipart
+  require "llm"
+  require "securerandom"
+
+  ##
+  # @return [String]
+  attr_reader :boundary
+
+  ##
+  # @param [Hash] params
+  #  Request parameters
+  # @return [LLM::Multipart]
+  def initialize(params)
+    @boundary = "BOUNDARY__#{SecureRandom.hex(16)}"
+    @params = params
+  end
+
+  ##
+  # Returns the multipart content type
+  # @return [String]
+  def content_type
+    "multipart/form-data; boundary=#{@boundary}"
+  end
+
+  ##
+  # Returns the multipart request body parts
+  # @return [Array<String>]
+  def parts
+    params.map do |key, value|
+      locals = {key: key.to_s.b, boundary: boundary.to_s.b}
+      if value.respond_to?(:path)
+        file_part(key, value, locals)
+      else
+        data_part(key, value, locals)
+      end
+    end
+  end
+
+  ##
+  # Returns the multipart request body
+  # @return [String]
+  def body
+    io = StringIO.new("".b)
+    [*parts, StringIO.new("--#{@boundary}--\r\n".b)].each { IO.copy_stream(_1.tap(&:rewind), io) }
+    io.tap(&:rewind)
+  end
+
+  private
+
+  attr_reader :params
+
+  def attributes(file)
+    {
+      filename: File.basename(file.path).b,
+      content_type: LLM::Mime[file].b
+    }
+  end
+
+  def multipart_header(type:, locals:)
+    if type == :file
+      str = StringIO.new("".b)
+      str << "--#{locals[:boundary]}" \
+             "\r\n" \
+             "Content-Disposition: form-data; name=\"#{locals[:key]}\";" \
+             "filename=\"#{locals[:filename]}\"" \
+             "\r\n" \
+             "Content-Type: #{locals[:content_type]}" \
+             "\r\n\r\n"
+    elsif type == :data
+      str = StringIO.new("".b)
+      str << "--#{locals[:boundary]}" \
+             "\r\n" \
+             "Content-Disposition: form-data; name=\"#{locals[:key]}\"" \
+             "\r\n\r\n"
+    else
+      raise "unknown type: #{type}"
+    end
+  end
+
+  def file_part(key, file, locals)
+    locals = locals.merge(attributes(file))
+    multipart_header(type: :file, locals:).tap do |io|
+      IO.copy_stream(file.path, io)
+      io << "\r\n"
+    end
+  end
+
+  def data_part(key, value, locals)
+    locals = locals.merge(value:)
+    multipart_header(type: :data, locals:).tap do |io|
+      io << value.to_s
+      io << "\r\n"
+    end
+  end
+end

data/lib/llm/provider.rb

@@ -15,8 +15,7 @@
 # @see LLM::Provider::Gemini
 # @see LLM::Provider::Ollama
 class LLM::Provider
-  require_relative "http_client"
-  include LLM::HTTPClient
+  require "net/http"
 
   ##
   # @param [String] secret
@@ -44,62 +43,139 @@ class LLM::Provider
   end
 
   ##
+  # Provides an embedding
   # @param [String, Array<String>] input
   #  The input to embed
+  # @param [String] model
+  #  The embedding model to use
+  # @param [Hash] params
+  #  Other embedding parameters
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Embedding]
-  def embed(input, **params)
+  def embed(input, model:, **params)
     raise NotImplementedError
   end
 
   ##
-  # Completes a given prompt using the LLM
+  # Provides an interface to the chat completions API
   # @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"},
+  #   messages = [
+  #     {role: "system", content: "Your task is to answer all of my questions"},
+  #     {role: "system", content: "Your answers should be short and concise"},
   #   ]
-  #   res = llm.complete "What is your name and what age are you?", :user, messages: context
+  #   res = llm.complete("Hello. What is the answer to 5 + 2 ?", :user, messages:)
   #   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
+  # @param [String] model
+  #  The model to use for the completion
+  # @param [Hash] params
+  #  Other completion parameters
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Completion]
-  def complete(prompt, role = :user, **params)
+  def complete(prompt, role = :user, model:, **params)
     raise NotImplementedError
   end
 
   ##
-  # Starts a new lazy conversation
+  # Starts a new lazy chat powered by the chat completions API
+  # @note
+  #  This method creates a lazy version of a
+  #  {LLM::Chat LLM::Chat} object.
+  # @param prompt (see LLM::Provider#complete)
+  # @param role (see LLM::Provider#complete)
+  # @param model (see LLM::Provider#complete)
+  # @param [Hash] params
+  #  Other completion parameters to maintain throughout a chat
+  # @raise (see LLM::Provider#complete)
+  # @return [LLM::Chat]
+  def chat(prompt, role = :user, model: nil, **params)
+    LLM::Chat.new(self, params).lazy.chat(prompt, role)
+  end
+
+  ##
+  # Starts a new chat powered by the chat completions API
+  # @note
+  #  This method creates a non-lazy version of a
+  #  {LLM::Chat LLM::Chat} object.
+  # @param prompt (see LLM::Provider#complete)
+  # @param role (see LLM::Provider#complete)
+  # @param model (see LLM::Provider#complete)
+  # @param [Hash] params
+  #  Other completion parameters to maintain throughout a chat
+  # @raise (see LLM::Provider#complete)
+  # @return [LLM::Chat]
+  def chat!(prompt, role = :user, model: nil, **params)
+    LLM::Chat.new(self, params).chat(prompt, role)
+  end
+
+  ##
+  # Starts a new lazy chat powered by the responses API
   # @note
   #  This method creates a lazy variant of a
-  #  {LLM::Conversation LLM::Conversation} object.
+  #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
   # @param role (see LLM::Provider#complete)
+  # @param model (see LLM::Provider#complete)
+  # @param [Hash] params
+  #  Other completion parameters to maintain throughout a chat
   # @raise (see LLM::Provider#complete)
-  # @return [LLM::LazyConversation]
-  def chat(prompt, role = :user, **params)
-    LLM::Conversation.new(self, params).lazy.chat(prompt, role)
+  # @return [LLM::Chat]
+  def respond(prompt, role = :user, model: nil, **params)
+    LLM::Chat.new(self, params).lazy.respond(prompt, role)
   end
 
   ##
-  # Starts a new conversation
+  # Starts a new chat powered by the responses API
   # @note
   #  This method creates a non-lazy variant of a
-  #  {LLM::Conversation LLM::Conversation} object.
+  #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
   # @param role (see LLM::Provider#complete)
+  # @param model (see LLM::Provider#complete)
+  # @param [Hash] params
+  #  Other completion parameters to maintain throughout a chat
   # @raise (see LLM::Provider#complete)
-  # @return [LLM::Conversation]
-  def chat!(prompt, role = :user, **params)
-    LLM::Conversation.new(self, params).chat(prompt, role)
+  # @return [LLM::Chat]
+  def respond!(prompt, role = :user, model: nil, **params)
+    LLM::Chat.new(self, params).respond(prompt, role)
+  end
+
+  ##
+  # @note
+  # Compared to the chat completions API, the responses API
+  # can require less bandwidth on each turn, maintain state
+  # server-side, and produce faster responses.
+  # @return [LLM::OpenAI::Responses]
+  #  Returns an interface to the responses API
+  def responses
+    raise NotImplementedError
+  end
+
+  ##
+  # @return [LLM::OpenAI::Images, LLM::Gemini::Images]
+  #  Returns an interface to the images API
+  def images
+    raise NotImplementedError
+  end
+
+  ##
+  # @return [LLM::OpenAI::Audio]
+  #  Returns an interface to the audio API
+  def audio
+    raise NotImplementedError
+  end
+
+  ##
+  # @return [LLM::OpenAI::Files]
+  #  Returns an interface to the files API
+  def files
+    raise NotImplementedError
   end
 
   ##
@@ -145,6 +221,32 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # Initiates a HTTP request
+  # @param [Net::HTTP] http
+  #  The HTTP object to use for the request
+  # @param [Net::HTTPRequest] req
+  #  The request to send
+  # @param [Proc] b
+  #  A block to yield the response to (optional)
+  # @return [Net::HTTPResponse]
+  #  The response from the server
+  # @raise [LLM::Error::Unauthorized]
+  #  When authentication fails
+  # @raise [LLM::Error::RateLimit]
+  #  When the rate limit is exceeded
+  # @raise [LLM::Error::ResponseError]
+  #  When any other unsuccessful status code is returned
+  # @raise [SystemCallError]
+  #  When there is a network error at the operating system level
+  def request(http, req, &b)
+    res = http.request(req, &b)
+    case res
+    when Net::HTTPOK then res
+    else error_handler.new(res).raise_error!
+    end
+  end
+
   ##
   # @param [String] provider
   #  The name of the provider

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 class LLM::Anthropic
+  ##
+  # @private
   class ErrorHandler
     ##
     # @return [Net::HTTPResponse]
@@ -25,7 +27,7 @@ class LLM::Anthropic
       when Net::HTTPTooManyRequests
         raise LLM::Error::RateLimit.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::Error::BadResponse.new { _1.response = res }, "Unexpected response"
+        raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
       end
     end
   end

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 class LLM::Anthropic
+  ##
+  # @private
   module Format
     ##
     # @param [Array<LLM::Message>] messages